CoAgnes Labthe study spaceresearch preview · build 1ececa2

The machine in reference · Volume 07

Volume 07 — The Membrane and Output Controllers

CURRENTsnapshot of 14 July 20265 min read← Volume 06 — Bind DescriptorsVolume 08 — The Nest Virtual Machine →

Reading aids · CoAgnes LabNot part of the specification; where they differ, the volume governs.

At a glance

  • The controller contract: two methods — claims, a pure and fast predicate, and discharge, the only asynchronous point of the machine. §2
  • The sweep: the membrane's own cursor passes every committed tuple exactly once, between engine runs — so an intention is discharged at most once. §3
  • What a conforming controller does with each intention kind: a winding discharge (inference.request) and a service discharge (service.request) — publication by proxy, under the intention's own emit declaration. §4.1§4.2
  • The controller's configuration record: its claims, correlation field, answer types and budgets — and credentials that never live in a record or in the log. §5
  • Ingress, the inward half, and the failure discipline: what may enter from outside, and how every failure shows on the log. §6§7

Where it sits

Read after
Volume 03 — The Wave LogVolume 04 — Tuple ReferenceVolume 06 — Bind Descriptors
Read next
Volume 08 — The Nest Virtual Machine
Requirements
10 sentences with MUST, SHOULD or MAY — the list
At work
4 of its sections seen in a real run of the machine, each linked under its heading
Across the set
every volume's questionsthe machine in figures

Questions this volume answers

  1. What is the membrane, and what crosses it? §1
  2. What must an output controller implement? §2
  3. What is the difference between an expected failure and a defect? §2
  4. Can an intention be discharged twice, or retried? §3
  5. When does the membrane sweep — during propagation, or after it? §3
  6. What does a controller publish when a service request is answered? §4.2
  7. Where do a controller's credentials live? §5
  8. What may a shell commit from outside, and what may it not? §6

The membraneMembraneThe boundary where the wave meets the world: output controllers face outward, ingress faces inward. (Vol. 07)Volume 15 — Terminology is the boundary where the wave meets the world: output controllersOutput controllerA receiver of committed tuples facing outward: it claims tuples by kind/fact type and discharges them to the external world exactly once per runtime. It neither judges nor integrates — a third station beside the activation knot and the bind descriptor, standing outside the propagation cycle on its own cursor. aka effector, egress handler. (Vol. 07 §2–3)Volume 15 — Terminology face outward, claiming committed tuplesWave tupleAn immutable record in the wave log: offset, kind, key, payload. The unit of fact. aka tuple. (Vol. 03 §1)Volume 15 — Terminology and discharging them to external systems; ingressIngressThe inward half of the membrane: the edge through which external events — the world's answers among them — are committed to the wave log as fact tuples. (Vol. 07 §6)Volume 15 — Terminology faces inward, committing external events as fact tuples. Nothing reaches the world that was not first a committed fact, and nothing external enters except as a committed fact. This volume specifies the sweep algorithm, the controller contract, the reference inference controller's protocol behaviour, controller configuration records, and the failure discipline.

§1. One publication, two receptions

A committed tupleWave tupleAn immutable record in the wave log: offset, kind, key, payload. The unit of fact. aka tuple. (Vol. 03 §1)Volume 15 — Terminology is received twice over: inward by knotsActivation knotAn accumulating unit that matches wave tuples, winds them, and tests readiness; it accumulates understanding. When ready, it activates bind descriptors. Its minimal form is a single condition matcher — a degenerate configuration of the same accumulator, not a different kind. aka knot, clew (for the per-key instance see clew). (Vol. 05)Volume 15 — Terminology that windWindThe act of integrating a matched tuple into the knot's wound state. Deterministic winding completes locally; semantic winding unfolds through the world — the knot projects a winding intention and later winds the returned integration. (Vol. 05 §1, §5)Volume 15 — Terminology it, outward by controllersOutput controllerA receiver of committed tuples facing outward: it claims tuples by kind/fact type and discharges them to the external world exactly once per runtime. It neither judges nor integrates — a third station beside the activation knot and the bind descriptor, standing outside the propagation cycle on its own cursor. aka effector, egress handler. (Vol. 07 §2–3)Volume 15 — Terminology that claim it. The two receptions are not exclusive — one tuple may both wind a knot and leave through a controller. Which kinds flow where is declared by the topologyTopologyThe live set of registered activation knots and bind descriptors that the wave flows through. (Vol. 02 §5)Volume 15 — Terminology and the installed claims, like every other binding. The membraneMembraneThe boundary where the wave meets the world: output controllers face outward, ingress faces inward. (Vol. 07)Volume 15 — Terminology is therefore a second reading of the one truth, never a second truth.

Lab fig. 07·1A strip of numbered records. One record sends one arrow up to a knot, which winds it, and one arrow down across a dashed line — the membrane — to a controller that discharges it to the world. From the world an arrow returns across the membrane to the end of the strip, where the answer is appended as a new record.The log — committed tuples#0#1#2#3#4#5#6appendedknotinward — a knot winds itThe machineThe worldThe membranecontrolleroutward — a controller claims itdischargean external systemthe answer enters again only as a committed fact
Lab fig. 07·1A strip of numbered records. One record sends one arrow up to a knot, which winds it, and one arrow down across a dashed line — the membrane — to a controller that discharges it to the world. From the world an arrow returns across the membrane to the end of the strip, where the answer is appended as a new record.The logknot#2#3#4#5#6inwardThe membraneThe worldoutwardcontrollerdischargean external systemthe answer: a new fact
Lab fig. 07·1 One committed tuple, two receptions: inward by the knots that wind it, outward by the controllers that claim it. The membrane is a second reading of the one truth — and what the world answers enters again only as committed facts. A reading aid by CoAgnes Lab; §1 governs.

§2. The controller contract

Seen at work Fragment 2 · The request is handed to the world

ts
interface IOutputController<T extends WaveTuple> {
  readonly id: string;
  claims(tuple: T): boolean;                                 // synchronous predicate
  discharge(tuple: T): Promise<readonly WaveEmission<T>[]>;  // the only async seam
}
  1. claims MUST be a pure, fast predicate (typically over kind and factType).
  2. discharge performs the external effect and resolves with the world's answers as emissionsEmissionA wave tuple without its offset — the form in which content is handed to the engine; the engine assigns the offset at append. (Vol. 03 §1)Volume 15 — Terminology. It is the only asynchronous point of the machine.
  3. A controllerOutput controllerA receiver of committed tuples facing outward: it claims tuples by kind/fact type and discharges them to the external world exactly once per runtime. It neither judges nor integrates — a third station beside the activation knot and the bind descriptor, standing outside the propagation cycle on its own cursor. aka effector, egress handler. (Vol. 07 §2–3)Volume 15 — Terminology MUST neither judge nor integrate: it converts an intention into an effect and the effect's answer into correlated facts. Semantic content originates in the world or in the intention, never in the controller.
  4. Expected external failures — transport errors, HTTP errors, timeouts, unparsable or schema-violating output — MUST resolve as failure facts (inference.failed / service.failed), so the wave settlesSettleThe runtime algorithm alternating propagation with membrane discharges until the machine settles. (Vol. 08 §3)Volume 15 — Terminology and the log records what the world answered.
  5. A rejected promise is a defectDefectA rejected discharge or invalid registration; the settle fails and the shell reports it. (Vol. 08 §7)Volume 15 — Terminology — reserved for configuration and programming errors (a missing API key is the canonical example). A defect fails the settle; it is not converted into a fact.
  6. Controllers are installed statically at assemblyAssemblyThe construction of one machine instance: engine with processors, membrane with controllers — one assembly shared by every shell of a product. (Vol. 08 §1)Volume 15 — Terminology. No committed fact may install, enable, disable, or re-credential a controller (the control-plane rule, restated in Vol. 12 §9–10).

§3. The sweep algorithm

Seen at work Fragment 1 · The membrane passes #0

The membraneMembraneThe boundary where the wave meets the world: output controllers face outward, ingress faces inward. (Vol. 07)Volume 15 — Terminology owns its own cursor over the same log (register MEMBRANE.CURSOR, Vol. 02 §4.6):

sweep(log):
  discharges ← []
  while MEMBRANE.CURSOR < |log|:
      t ← log[MEMBRANE.CURSOR++]
      for each controller c:
          if c.claims(t): discharges += c.discharge(t)   // started, not awaited
  return discharges
Lab fig. 07·2A strip of numbered records with two pointers above it: the engine's at the end, the membrane's at record 4, moving on by one. Below, two controllers are asked about record 4: one says no, the other claims it and starts a discharge, marked started, not awaited.The log#0#1#2#3#4#5#6ENGINE.CURSOR — at the endMEMBRANE.CURSOR+1claims(#4)?controller Anocontroller Byes — it claims itdischarge(#4)started, not awaitedonce per offset — no redelivery, no retry · between engine runs, never inside apply
Lab fig. 07·2A strip of numbered records with two pointers above it: the engine's at the end, the membrane's at record 4, moving on by one. Below, two controllers are asked about record 4: one says no, the other claims it and starts a discharge, marked started, not awaited.The log#0#1#2#3#4#5#6MEMBRANE.CURSOR+1ENGINE.CURSOR — at the endclaims(#4)?controller Anocontroller Byesdischarge(#4)not awaitedonce per offset — no redelivery, no retrybetween engine runs, never inside apply
Lab fig. 07·2 The sweep: the engine's cursor runs ahead; the membrane's own cursor follows, once per offset, between engine runs. For each tuple every controller is asked whether it claims it; a claimed tuple starts a discharge, which is not awaited — and is never repeated. A reading aid by CoAgnes Lab; §3 governs.
  1. The cursor advances exactly once per offset: a committed tupleWave tupleAn immutable record in the wave log: offset, kind, key, payload. The unit of fact. aka tuple. (Vol. 03 §1)Volume 15 — Terminology is swept once per runtime, so an intention is discharged at most once. There is no redelivery, no acknowledgement, no retry at this layer; retry, where wanted, is topologyTopologyThe live set of registered activation knots and bind descriptors that the wave flows through. (Vol. 02 §5)Volume 15 — Terminology (a new intention).
  2. ControllersOutput controllerA receiver of committed tuples facing outward: it claims tuples by kind/fact type and discharges them to the external world exactly once per runtime. It neither judges nor integrates — a third station beside the activation knot and the bind descriptor, standing outside the propagation cycle on its own cursor. aka effector, egress handler. (Vol. 07 §2–3)Volume 15 — Terminology receive tuples outside the propagation cycle: sweeping happens between engine runs (Vol. 08 §3), never inside apply.
  3. Several controllers MAY claim one tuple; each dischargesDischargeThe asynchronous execution of an external effect for one claimed tuple, resolving with the world's answers as emissions. (Vol. 07 §2)Volume 15 — Terminology independently. Implementations SHOULD keep service-protocol claims exclusive by configuration review — overlapping claims on service.request would double-publish under one declaration (recorded hold, Vol. 11 §6).

§4. The reference service/inference controller

The reference controllerOutput controllerA receiver of committed tuples facing outward: it claims tuples by kind/fact type and discharges them to the external world exactly once per runtime. It neither judges nor integrates — a third station beside the activation knot and the bind descriptor, standing outside the propagation cycle on its own cursor. aka effector, egress handler. (Vol. 07 §2–3)Volume 15 — Terminology claims both intention kinds of Vol. 04 and demonstrates the normative dischargeDischargeThe asynchronous execution of an external effect for one claimed tuple, resolving with the world's answers as emissions. (Vol. 07 §2)Volume 15 — Terminology behaviour for each. Any conforming controller for these protocols — LLM-backed, deterministic function host, rule engine, human-task queue — MUST honour the same observable contract.

§4.1 Winding discharge (inference.request)

  1. Compose the integrationIntegrationThe understanding a bind descriptor forms and publishes as a wave tuple; received by others through binding — as an activation or as a demand — so integrations compose into higher-order understanding. (Vol. 06 §1)Volume 15 — Terminology task from the intention: questions (the angle), state (possibly empty), deltasDeltaThe unit of new material a collection rule extracts from an accepted fact. On a canvas, deltas are labelled by their rule name. (Vol. 05 §3, §5.4)Volume 15 — Terminology.
  2. Obtain an integration {state, grade} from the world. Grade MUST be clamped to [0, 1]; an unparsable answer is an expected failureExpected failureAn external failure returned as a correlated fact (*.failed), letting the wave settle with the failure on record. Distinct from a defect — a configuration or programming error that rejects the discharge and fails the settle. (Vol. 07 §7)Volume 15 — Terminology.
  3. Resolve with inference.response {knotId, uid, state, grade, lane?} — lane echoed verbatim from the request — plus inference.reasoning {knotId, uid, reasoning} when the world supplied non-empty reasoning.
  4. On expected failure resolve with inference.failed {knotId, uid, reason}.

The reference implementation fixes the semantic task in a system prompt — "rewrite STATE into one updated, self-contained integrated understanding that absorbs the DELTAS and addresses the QUESTIONS; assess with a grade in [0,1]" — and requires a single JSON object {"state", "grade"} in reply. The prompt wording is implementation detail; the task semantics (absorb deltas, address questions, self-contained state, honest grade) are the portable contract of the windingWindThe act of integrating a matched tuple into the knot's wound state. Deterministic winding completes locally; semantic winding unfolds through the world — the knot projects a winding intention and later winds the returned integration. (Vol. 05 §1, §5)Volume 15 — Terminology protocol.

§4.2 Service discharge (service.request)

Seen at work Fragment 2 · #4 · the request crosses the membrane

  1. Compose the operator task: instruction + bound scopeBound scopeThe record of names — from the activation tuple and the demands — over which gates and the service are evaluated. (Vol. 06 §4)Volume 15 — Terminology (+ declared schema).
  2. Obtain a single JSON object as the result.
  3. If a schema is declared, validate the result against it (Vol. 09 §7); a violation is an expected failureExpected failureAn external failure returned as a correlated fact (*.failed), letting the wave settle with the failure on record. Distinct from a defect — a configuration or programming error that rejects the discharge and fails the settle. (Vol. 07 §7)Volume 15 — Terminology (service.failed), never a partial publication.
  4. Publish under the intention's emit declarationEmit declarationThe declared publication form carried in the intention: writes (one fact) or unfold (a sown-topology template); the proposed third member is cell. (Vol. 06 §6–8)Volume 15 — Terminology — publication by proxy:
    • writes: one fact {bindId, uid, result} of the declared type;
    • unfold: the instantiated batch of Vol. 06 §7 (knotsActivation knotAn accumulating unit that matches wave tuples, winds them, and tests readiness; it accumulates understanding. When ready, it activates bind descriptors. Its minimal form is a single condition matcher — a degenerate configuration of the same accumulator, not a different kind. aka knot, clew (for the per-key instance see clew). (Vol. 05)Volume 15 — Terminology, close, heads, each stamped emittedBy: uid). An instantiation error (missing placeholder, empty items) is an expected failure.
  5. Add service.reasoning when non-empty reasoning was supplied.
  6. On expected failure resolve with service.failed {bindId, uid, reason}.
Lab fig. 07·3On the left a service request with its fields — bindId, uid, instruction, scope, schema, emit. In the middle a controller with four numbered steps: compose, obtain, validate, publish. On the right the published answer with bindId, uid and result; the two stamps bindId and uid are marked on both. Below the validate step a branch leads to a service.failed fact.the same two stamps — bindId · uidservice.requestbindIduidinstructionscopeschemaemit.writes: Tcontroller1compose the task2obtain one result3validate: the schema4publish under emitT — the answerbindIduidresultservice.failedbindId · uid · reasonif 3 fails: a failure fact,never half an answer
Lab fig. 07·3On the left a service request with its fields — bindId, uid, instruction, scope, schema, emit. In the middle a controller with four numbered steps: compose, obtain, validate, publish. On the right the published answer with bindId, uid and result; the two stamps bindId and uid are marked on both. Below the validate step a branch leads to a service.failed fact.the same two stamps — bindId · uidservice.requestbindIduidinstructionscopeschemaemit.writes: Tcontroller1compose the task2obtain one result3validate: the schema4publish under emitT — the answerbindIduidresultservice.failedbindId · uidreasonif 3 fails: a failurefact, never half an answer
Lab fig. 07·3 A service discharge, publication by proxy: the request carries everything needed; the controller composes the task, obtains one result, checks it against the declared schema, and publishes it under the intention's own emit declaration — with the same two correlation stamps. A result of the wrong shape is a failure fact, never half an answer. A reading aid by CoAgnes Lab; §4.2 governs.

The controllerOutput controllerA receiver of committed tuples facing outward: it claims tuples by kind/fact type and discharges them to the external world exactly once per runtime. It neither judges nor integrates — a third station beside the activation knot and the bind descriptor, standing outside the propagation cycle on its own cursor. aka effector, egress handler. (Vol. 07 §2–3)Volume 15 — Terminology fills content and never alters form: the declaration fixed at projection is executed verbatim. Deterministic machines implement §4.2 by dispatching instruction to a registered function over scope — the declaration-level contract is identical.

§4.3 Budgets

The reference controllerOutput controllerA receiver of committed tuples facing outward: it claims tuples by kind/fact type and discharges them to the external world exactly once per runtime. It neither judges nor integrates — a third station beside the activation knot and the bind descriptor, standing outside the propagation cycle on its own cursor. aka effector, egress handler. (Vol. 07 §2–3)Volume 15 — Terminology enforces two budgets per completion from its configuration record: max_tokens and timeout_ms (abort → expected timeout failure). Declared-but-unenforced budget fields (max_in_flight, retries) remain configuration surface (DECLARED) — an implementation MAY enforce them, MUST NOT reinterpret them.

§5. Controller configuration records

ControllersOutput controllerA receiver of committed tuples facing outward: it claims tuples by kind/fact type and discharges them to the external world exactly once per runtime. It neither judges nor integrates — a third station beside the activation knot and the bind descriptor, standing outside the propagation cycle on its own cursor. aka effector, egress handler. (Vol. 07 §2–3)Volume 15 — Terminology are configured by YAML records — inspectable manifests kept beside the pipelines (reference layout: refimpl 00 §4); the live record is read at wiring time (refimpl 05 §4):

yaml
id: controller.inference.together
kind: output.controller
claims:
  - match_type: inference.request        # the claim predicate, declaratively
correlation:
  field: uid                             # payload field joining intention and answers
answers:
  - type: inference.response
  - type: inference.reasoning
  - type: inference.failed
model:                                   # controller-specific block
  provider: together
  name: zai-org/GLM-5.2
  base_url: https://api.together.ai/v1
  reasoning_effort: high
budget:
  max_tokens: 16384                      # enforced per completion
  timeout_ms: 180000                     # enforced
  max_in_flight: 4                       # declared; not yet enforced
  retries: 0                             # declared; not yet enforced
  1. The record declares claims, correlation field, answer types, and budgets — the inspectable manifest of the controller's protocol surface.
  2. Secrets never live in records or the log: credentials resolve from the environment (or an ignored local file) at assemblyAssemblyThe construction of one machine instance: engine with processors, membrane with controllers — one assembly shared by every shell of a product. (Vol. 08 §1)Volume 15 — Terminology. A missing credential is a configuration defectDefectA rejected discharge or invalid registration; the settle fails and the shell reports it. (Vol. 08 §7)Volume 15 — Terminology at dischargeDischargeThe asynchronous execution of an external effect for one claimed tuple, resolving with the world's answers as emissions. (Vol. 07 §2)Volume 15 — Terminology (§2.5), so a misconfigured machine fails the settleSettleThe runtime algorithm alternating propagation with membrane discharges until the machine settles. (Vol. 08 §3)Volume 15 — Terminology loudly instead of stalling silently.
  3. Extensions introducing new controllers MUST ship such a record; claim-overlap review over these manifests is the intended exclusivity mechanism (Vol. 11 §6).

§6. Ingress

Seen at work Fragment 1 · #2 · a note arrives

IngressIngressThe inward half of the membrane: the edge through which external events — the world's answers among them — are committed to the wave log as fact tuples. (Vol. 07 §6)Volume 15 — Terminology is the inward half of the membraneMembraneThe boundary where the wave meets the world: output controllers face outward, ingress faces inward. (Vol. 07)Volume 15 — Terminology: shells commit external events — user messages, declared inputs, review decisions, delivery receipts — as fact tuplesWave tupleAn immutable record in the wave log: offset, kind, key, payload. The unit of fact. aka tuple. (Vol. 03 §1)Volume 15 — Terminology through the runtime's seed path (Vol. 08 §3).

  1. Shells MUST commit only declared input fact forms and MUST NOT accept reserved-namespace fact types from external callers (Vol. 04 §6).
  2. Ingress assigns the attributionAttribution, reachability, terminationThe three load-bearing obligations of the decoupled model. (Vol. 01 §7)Volume 15 — Terminology key server-side/shell-side; external callers do not choose arbitrary lanes.
  3. The world's answers to intentions are not shell ingress: they re-enter through the dischargeDischargeThe asynchronous execution of an external effect for one claimed tuple, resolving with the world's answers as emissions. (Vol. 07 §2)Volume 15 — Terminology path with their correlation identitiesCorrelation identityThe uid joining an intention with its answers (<ownerId>#<n>), plus the emittedBy provenance stamp on sown emissions. (Vol. 03 §4)Volume 15 — Terminology.

§7. Failure discipline summary

ConditionManifestationEffect on the run
expected external failureinference.failed / service.failed factwave continues; may settle unfinished; visible on log
schema-violating world answerservice.failed factsame as above; nothing partial is published
unparsable world answerfailure fact with excerptsame
configuration/programming defectrejected discharge promisesettle fails; shell reports non-zero / defect status
budget stop (knot winding)no emission; queued deltas remainsettled unfinished; stall visible

Reading aids · CoAgnes LabNot part of the specification; where they differ, the volume governs.

Requirements in this volume

Every sentence of the volume with MUST, SHOULD or MAY, as it stands, with the section it stands in. These key words mark its conformance requirements; the rest of its text is descriptive (Vol. 00 §4).

  1. MUSTclaims MUST be a pure, fast predicate (typically over kind and factType).§2
  2. MUSTA controller MUST neither judge nor integrate: it converts an intention into an effect and the effect's answer into correlated facts.§2
  3. MUSTExpected external failures — transport errors, HTTP errors, timeouts, unparsable or schema-violating output — MUST resolve as failure facts (inference.failed / service.failed), so the wave settles and the log records what the world answered.§2
  4. MAYSeveral controllers MAY claim one tuple; each discharges independently.§3
  5. SHOULDImplementations SHOULD keep service-protocol claims exclusive by configuration review — overlapping claims on service.request would double-publish under one declaration (recorded hold, Vol. 11 §6).§3
  6. MUSTAny conforming controller for these protocols — LLM-backed, deterministic function host, rule engine, human-task queue — MUST honour the same observable contract.§4
  7. MUSTGrade MUST be clamped to [0, 1]; an unparsable answer is an expected failure.§4.1
  8. MAYMUST NOTDeclared-but-unenforced budget fields (max_in_flight, retries) remain configuration surface (DECLARED) — an implementation MAY enforce them, MUST NOT reinterpret them.§4.3
  9. MUSTExtensions introducing new controllers MUST ship such a record; claim-overlap review over these manifests is the intended exclusivity mechanism (Vol. 11 §6).§5
  10. MUSTMUST NOTShells MUST commit only declared input fact forms and MUST NOT accept reserved-namespace fact types from external callers (Vol. 04 §6).§6