← back to Docs source: system/specs/CHANNELS.md

CHANNELS — The Four-Channel Commissioning Contract

Status: DRAFT v2.0 — command-center review pending What this is: the mechanical spec for worker wiring. Doctrine (SYSTEM.md §6): commissioning is integration, not instantiation; an unwired worker is not commissioned; undefined is where information leaks. This document turns that into a manifest schema, a verdict format, and a pre-flight checklist a script can verify. The v1 deployment found wiring defects by hand, in ad-hoc adversarial audits; v2 makes them a set-reconciliation query.

1. The four channels

Every worker has exactly four channel endpoints. Not three, not "whatever it needs" — four, each explicitly declared. A leaf worker does not omit its down-channels; it declares them CLOSED. Closed is a wired state; undefined is a defect.

Channel	Direction	Carries
`broadcast_up`	worker → its manager	Reports, findings, proposals, heartbeats, escalations. Captured — the manager (or a condenser) provably consumes it; broadcast into a void is uncommissioned.
`listen_up`	manager → worker	Directives, verdicts on the worker's proposals, bounced escalations, config.
`broadcast_down`	worker → its reports	Assignments, standards, delegated verdicts. `CLOSED` for leaves.
`listen_down`	reports → worker	Subordinate output the worker consumes. `CLOSED` for leaves.

Sideways is up-then-down. Peer-to-peer channels are forbidden — no worker declares an endpoint whose counterpart is not its direct manager or direct report. Coordination between cousins routes up to the lowest common ancestor and back down, keeping every hop on the auditable trail. A manifest declaring a peer endpoint fails pre-flight check C4 (§5); a peer channel observed in operation (a worker reading another worker's workspace, workers sharing a scratch file as a mailbox) is a highest-severity wiring alarm. Workers communicate by verdicts, never shared memory.

2. The manifest wiring block

Wiring declarations live in the worker's manifest — workers/<worker_id>/manifest.yaml — so declared-vs-observed drift is auditable by set reconciliation (§6). The wiring block:

worker_id: voice-scanner
class: operating/eliminator
skill_ref: seo/PIPELINE.md#voice-3d
job: "scan drafted pages for voice-pattern violations"
model_class: deepseek-tier          # per ops/MODELS.md; ramp may hold it higher
commissioned: 2026-07-20T15:00:00Z
death_conditions:                    # apoptosis, audited dumbly
  - "zero findings for 200 consecutive runs AND fixer pair retired"
channels:
  broadcast_up:
    kind: path                       # path | ledger | discord
    endpoint: data/channels/voice-scanner/up.jsonl
    captured_by: pipeline-condenser  # the consumer of record — MUST exist in census
  listen_up:
    kind: path
    endpoint: data/channels/pipeline-condenser/down/voice-scanner.jsonl
    written_by: pipeline-condenser
  broadcast_down: CLOSED             # leaf — closed, not undefined
  listen_down: CLOSED

Field contract:

Field	Type	Rule
`channels.<name>`	object or the literal string `CLOSED`	All four keys mandatory. Absent key, `null`, `~`, or empty object = undefined = uncommissioned (§5).
`kind`	enum `path \	ledger \	discord`	`path` = append-only JSONL file under `data/channels/`; `ledger` = the record itself is the message (verdicts); `discord` = a broadcast mirror. RESOLVED (ML, F8 — reversed from the draft lean): the broadcast surface into Discord is deliberately GIGANTIC. Every worker's broadcast-up is mirrored to a Discord channel so ML can watch the whole workforce work — it aids visualization and evaluation of the workforce. Discord mirrors are display, never transport: the captured `path`/`ledger` endpoint remains the endpoint of record that parents and the funnel read; a Discord outage loses nothing. Channel topology per `ops/DEPLOYMENT.md` §5; tuning what is surfaced where is expected, but the default is everything visible.
`endpoint`	string path/channel-id	Must be unique per (worker, channel); persistent, not a temp path.
`captured_by` / `written_by`	worker_id	The counterpart of record. Must exist in the census; must declare the mirror endpoint (§6). For `broadcast_up`, `captured_by` is what makes the channel captured rather than a void.

Channel files are append-only JSONL with the same discipline as the ledger (LEDGER.md §1): one message per line, UTC timestamps, no mutation. Channels carry work; the ledger carries record — every verdict-class message on a channel is mirrored to the ledger (§3), other traffic (drafts, working notes) is not.

3. Verdict format on channels

When a manager answers a subordinate's proposal — or any orienter renders judgment that travels a channel — the message is a typed verdict, provenance-carrying, ledger-mirrored:

{
  "msg": "verdict",
  "ledger_id": "01J3ZKAB2C…",
  "ts": "2026-07-20T15:12:04Z",
  "run_id": "2026-07-20T15-pipeline-condenser-r88",
  "from": "pipeline-condenser",
  "to": "voice-scanner",
  "re": "workers/voice-scanner/proposals/2026-07-20T1502.yaml#doc1",
  "verdict": "kill",
  "standard_version": "gate-ramp.yaml@sha256:9c1e…/voice-pattern/phase:build",
  "reason": "corroboration 1 < threshold 2",
  "provenance": [ { "kind": "artifact", "value": "…", "fingerprint": "sha256:…",
                    "attested_by": "pipeline-condenser", "tier": "internal" } ]
}

Rules:

ledger_id is mandatory and must reference an existing ledger verdict record with identical verdict, standard_version, and reason. **The ledger copy is authoritative**; the channel copy is delivery. Divergence between the two is a funnel-audit alarm.
Untyped prose verdicts ("looks good, proceed") are invalid on any channel — a consumer receiving one treats it as no verdict and the completeness invariant (LEDGER.md §4.4) eventually flags the unanswered candidate.
Verdicts carry provenance like every other judgment: what evidence the judge counted, attested, fingerprinted.
msg types on channels: verdict, assignment, report, heartbeat, escalation, config. Same envelope discipline (ts, run_id, from, to); only verdict and escalation require ledger mirroring.

4. Commissioning: the five-step checklist

Commissioning is integration, not instantiation. The steps, in order, each producing a machine-checkable artifact:

Step	Act	Artifact a script can verify
1. Reuse-check	Prove no commissioned worker already owns this job.	`commissioning/<worker_id>/reuse-check.json`: the census query run (`job_overlap: []`), its `run_id`, and the negative result. Non-empty overlap = block; never duplicate a job.
2. Fit diagnosis	Name the gap this worker closes and the layer/class it belongs to.	`fit.json`: `{gap, layer, class, blueprint_ref}` — class must exist in BLUEPRINT.md or carry a blueprint-defect filing.
3. Supporting-cast / pod plan	Every corner is a pod: name the worker's gate, meter, drift sentinel, diagnoser, improver. No orphan functions; no open loops.	`pod.json`: `{gate, meter, sentinel, diagnoser, improver}` — each entry a worker_id or metric-file that exists (or is co-commissioned in the same batch). Open entries = open loops = block.
4. Wire the four channels	Write the manifest wiring block; create the endpoints; counterparts declare their mirrors.	The manifest itself + endpoint existence + mirror declarations (§6 reconciliation passes on the proposed set).
5. Commission	The commissioning verdict passes its gate (worker-create, tier per CONSEQUENCE.md); the `commit` is ledgered.	Ledger `commit` record with `artifact_kind: worker`, referencing artifacts 1–4.

The pre-flight script (gates/commissioning-preflight.py, gatelib-based) runs checks C1–C7 and exits by the unified convention (GATES.md §3):

C1 — manifest parses; all four channel keys present; each is CLOSED or a complete {kind, endpoint, captured_by|written_by} object.
C2 — broadcast_up.captured_by exists in the census and declares the mirror listen_down endpoint (or is a condenser with this worker enrolled).
C3 — every endpoint path exists, is under data/channels/, and is writable by exactly the declared writer (permission check).
C4 — no peer wiring: every counterpart is the worker's direct manager or direct report in the org chart; graph distance 1 on the tree, no lateral edges.
C5 — values gate present in the worker's template (GATES.md §6) — unwired values gate fails commissioning outright.
C6 — reuse-check, fit, and pod artifacts exist and are internally complete (no open pod entries).
C7 — death conditions declared and dumb-auditable (counts/streaks/events, no prose). Silent-failure detectors additionally declare never_retire_on_silence: true.

Uncommissioned = any undefined endpoint. One missing, null, or unverifiable channel key and the worker does not run: schedulers refuse to schedule it, gates refuse its proposals (killed as malformed:uncommissioned-proposer), and its existence is a census finding. There is no partially-wired grace state.

5. Decommissioning

Retirement reverses commissioning through the worker-retire gate (decommit asymmetry, CONSEQUENCE.md §3): the decommit is ledgered, endpoints are closed with a terminal heartbeat (status: decommissioned) on broadcast_up, the manifest is marked retired: with the ledger reference — never deleted; retire-with-record. Its counterparts' mirror declarations are updated in the same batch, or reconciliation (§6) flags the dangling mirror within one sweep.

6. Drift audit: declared vs. observed

Because wiring lives in manifests, the self-knowledge layer audits it with its dumb primitives — set reconciliation and counting, no judgment:

Declared set: {(worker, channel, endpoint, counterpart)} parsed from all manifests.
Observed set: endpoints that actually exist on disk, their writers (from fs metadata and message from fields), their last-write timestamps.
Mirror closure: for every declared broadcast_up → captured_by: M, worker M declares a listen_down covering it; likewise broadcast_down ↔ listen_up. Asymmetric declarations = wiring defect.
Findings, never actions — each discrepancy is a ledgered alarm: orphan-endpoint (observed, not declared), phantom-endpoint (declared, absent), uncaptured-broadcast (declared up-channel whose consumer never reads: counterpart read timestamps stale beyond the worker's cadence × 3 [OPEN — flag for command center: the staleness multiplier for "captured" — 3× cadence is a placeholder]), peer-channel (lateral edge observed), stale-channel (no traffic beyond death-condition horizons).
The census cross-check: every commissioned worker has a manifest, every manifest's worker is scheduled, every scheduled worker heartbeats. Three sets, one reconciliation, run nightly.

Provenance: four-channel and up-then-down doctrine from SYSTEM.md §6 and corpus/COMMISSIONING.md scope; pod rule from SYSTEM.md §1 (ML, 2026-07-20); verdict mirroring from SYSTEM.md §5 substrate item 1; hand-found wiring defects motivating C1–C7 from the Sarge/FJF deployment record (flaws doc, Flaw 9).