Volume 11 — Extension Points and the Widening Discipline

The Nest runtimeNest runtime / Nest virtual machine (Nest VM)The whole machine this set specifies: wave log + processors (topology and observers) + membrane + settle loop. In the reference project the bare word Nest historically named the workbench shell; this set reserves the machine sense and calls the workbench Nest Studio. (Vol. 00 §5)Volume 15 — Terminology grows by a fixed discipline: pluggable modules on existing rails, never narrowing the flat path. This volume catalogues every sanctioned extension point of the current machine, the constructs already declared in the formats but not yet enforced, the recorded future work, and the open decisions an extension must not pretend are settledSettledQuiescent with no discharge in flight. (Vol. 03 §7)Volume 15 — Terminology. It is the volume an extension author reads first; Volumes 12–13 are worked examples of its rules.

§1. The growth rule

1. New capability plugs in behind existing contracts (strategy registryStrategy registryThe named-factory table resolving knot strategies at registration; also the injection seam for the local integrator. (Vol. 05 §8)Volume 15 — Terminology, processor list, 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 list, emit-declaration union, protocol namespaces). It MUST NOT require the flat machine to change behaviour when the capability is absent.
2. Base functionality is never narrowed without explicit agreement and motivation; a degenerate configuration (a trivially 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 clewClewOne per-key executor instance of a registered knot definition; parallel keys wind independent clews. (Vol. 05 §2)Volume 15 — Terminology, a demands-only bind) is a configuration of the same unit, not a new kind.
3. Every extension names, at design time, how it preserves the three obligations — attributionAttribution, reachability, terminationThe three load-bearing obligations of the decoupled model. (Vol. 01 §7)Volume 15 — Terminology, reachability, termination — and which honest states it adds.

§2. Core widenings: the amendment procedure

The invariant core (envelope + three contracts + append semantics) changes only by deliberate, recorded widening: proposed explicitly, motivated, agreed, landed together with terminology, requirements, formats, and tests (the same-work-item rule). The precedent log:

Candidate widenings currently open (not agreed; extensions MUST NOT assume them): log restore/continuation into a live engine (§6.1); a processor settlement/quiescenceQuiescentThe engine cursor has consumed the whole log and produced nothing further. (Vol. 03 §7)Volume 15 — Terminology hook (§6.2); a new envelope kind of any sort.

§3. Extension points: behaviour

§3.1 Knot strategies (registry)

Add accumulator kinds by registering factories under new strategy names (Vol. 05 §8). Rules: honour the five-method lifecycle and station limits; validate configuration at construction (the registration probe surfaces defectsDefectA rejected discharge or invalid registration; the settle fails and the shell reports it. (Vol. 08 §7)Volume 15 — Terminology); extend the compiler to accept the name and validate its config — authoring visibility is never implicit.

§3.2 Local integrators

The injection seam for deterministic-class semantic 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 (Vol. 05 §5.1). Any pure (deltas) → {state, grade} function qualifies. Swapping it changes the machine classMachine classThe execution profile fixed at assembly: deterministic (pure functions everywhere; byte-reproducible re-execution), semantic (non-determinism enters at discharge), hybrid (both). (Vol. 01 §5, Vol. 08 §5)Volume 15 — Terminology, not the format.

§3.3 Wave processors (observers and routers)

The processor list is the machine's own extension point (Vol. 02 §1). Passive observersObserverA passive wave processor that mirrors tuples and emits nothing behavioural. (Vol. 02 §3.4)Volume 15 — Terminology (mirrors, metrics, digest feeders) MUST emit nothing behavioural. Active processors — routers that own local topologiesTopologyThe live set of registered activation knots and bind descriptors that the wave flows through. (Vol. 02 §5)Volume 15 — Terminology — are permitted and are the sanctioned path to compartmentalisation: the Cell extension replaces the top-level topology with CellSpace(root: TopologyGraph) while root-only behaviour stays byte-identical (Vol. 12 §4).

§3.4 Output controllers

New world capabilities are new 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 with configuration records (Vol. 07 §5): narrow claims, correlation field, answer types, budgets, secrets outside records. Installation is a deployment/control-plane operation — never a wave fact (the no-self-granted-power rule, Vol. 12 §9). Deterministic function hosts, artefact stores, chat egress, delivery receipts are all this shape.

§3.5 Emit declarations

The declaration union (writes | unfold) is designed for careful growth; the proposed third member is cell (Vol. 12 §3). Rules for any new member: fixed at projection, carried whole in the intention, mutually exclusive with the others, executable by 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 without consulting the bind, validated before publication, attributable (uid/stamp), and bounded (worst case statically computable).

§3.6 Protocol families

New asynchronous capability = new domain.fact namespace with closed shapes, correlation identityCorrelation identityThe uid joining an intention with its answers (<ownerId>#<n>), plus the emittedBy provenance stamp on sown emissions. (Vol. 03 §4)Volume 15 — Terminology, producer class, terminal-answer rule, and collision review (Vol. 04 §6.3). Never a new envelope kind.

§4. Extension points: formats (currently open rails)

• 4.1 Reducers — append | latest/overwrite today; a new reducer is a compiler + knotActivation 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 change behind one enum.
• 4.2 Where-clauses — equals/not_equals today; richer predicates extend one shared matcher (ruleMatches); extensions MUST reuse it rather than fork a second condition language (the rule the Cell 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 restates, Vol. 12 §6, check 9).
• 4.3 Branches and ledgers (DECLARED) — named lanes (planes of breadth) and isolated sub-scopes (levels of depth) with isolation marks; parsed, validated, rejected beyond main. Their enforcement is where the attributionAttribution, reachability, terminationThe three load-bearing obligations of the decoupled model. (Vol. 01 §7)Volume 15 — Terminology obligation gets its full home (Vol. 03 §5); until then, keys + lanes + stamps carry it.
• 4.4 Runtime declaration — mode: single-thread, isolation: declared-only: the reserved surface for concurrency and enforcement stages.
• 4.5 Condition and gateGateA predicate over the bound scope. Gates decide between emit and reject; the current form is min_grade over a named entry. (Vol. 06 §5)Volume 15 — Terminology languages — deterministic conditions are the null-guard subset; gates are min_grade. Richer expressions (the reference artefactsReference artefactA format document fixing target vocabulary that the current compiler deliberately rejects beyond its stage. (Vol. 09 §1)Volume 15 — Terminology sketch full boolean gates over scope fields) MUST arrive through the deliberate expression rail: one parser, closed grammar, explicit rejection of the rest.
• 4.6 Schema subset — grows keyword by keyword (Vol. 09 §7.3); admission validation stays the final authority.
• 4.7 Fact-shape conventions — data.grade (gate comparand), data.lane (canvasUnderstanding canvasSeveral clews winding in parallel and collecting one another's committed integrations through where clauses over lanes — cross-pollination under budgets. aka canvas. (Vol. 10 §4)Volume 15 — Terminology mark), data.uid/bindId/knotId (correlation), emittedBy (provenance): extensions SHOULD reuse these names rather than mint synonyms.

§5. Declared-future authoring constructs (reserved words)

The grammar reserves and rejects, with the distinct "declared but not yet supported" diagnostic, a family of full-shape constructs fixed by the reference project's target-shape pipeline artefact:

Illustration of the reserved shapes (target syntax; the current compiler rejects every construct below by name):

descriptors:
  - id: unfold.problem                # static fan-out over declared planes
    on: intake.ready
    action: unfold
    affinity:
      heads:                          # ray = branch + allowed writes + seeded op
        - { branch: truth, writes: [dimension.unfolded],
            op: { strategy: semantic_evaluator, dimension: truth } }
      knots:                          # tendrils hung on the declared branches
        - { id: collect.truth, listen_on: truth, match: dimension.unfolded }
    synthesize:                       # fan-in once the tendrils have gathered
      when: [collect.truth]
      strategy: semantic_evaluator
      writes: problem.described
      on_branch: main

  - id: unfold.questions              # generative fan-out with per-item ledgers
    on: problem.ready
    action: unfold
    fanout: generative
    affinity:
      generate: { from: problem.described, strategy: semantic_evaluator, as: questions }
      head_template:
        branch: "question/{index}"
        isolation: ledger             # declared isolation level
        writes: [question.answered]
        op: { strategy: semantic_evaluator, dimension: deep }
      knot_template:
        id: "collect.question/{index}"
        listen_on: "question/{index}"
        match: question.answered
    synthesize: { when: all-generated, strategy: semantic_evaluator,
                  writes: solution.raw, on_branch: main }

  - id: guard.out_of_bounds           # terminal guard diverting the wave
    on: guard.problem_class           # a knot whose condition declares
    action: emit                      #   evaluate: control_questions
    writes: pipeline.out_of_bounds    #   polarity: out_of_bounds
    terminal: true

Rules: implementations MUST keep rejecting these explicitly until implemented; implementing one moves it from this table into Volumes 05–09 in the same work item; the emit-template unfold (Vol. 06 §7) is the already-executable subset of this family and MUST remain compatible with the first-class form when it lands.

§6. Recorded future work and open decisions

Extensions MUST treat the following as open, not as silently assumable:

1. Restore/continuation (open core widening): processors keep materialised state in memory; the engine has no API to load 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 continue. Any proposal must choose rehydration vs snapshots vs an explicit core restore, and must not re-discharge old intentions (Vol. 08 §9).
2. QuiescenceQuiescentThe engine cursor has consumed the whole log and produced nothing further. (Vol. 03 §7)Volume 15 — Terminology/settlement hook: processors have no settlement callback; at_quiescence barriersBarrierThe join policy over demands (currently all): the rendezvous at which the bound demands become simultaneously available. The current barrier latches: a later readiness refreshes a demand's entry until projection. (Vol. 06 §4)Volume 15 — Terminology, stall facts, and Cell completion events wait on an additive runtime/session hook. Until then, unfinished status is a digest.
3. Wave maturity block (recorded): edge-triggered readinessReadinessThe state an activation knot reaches when its accumulated understanding satisfies its test; readiness is what activates bind descriptors. Readiness is reified: the topology commits it as a tuple carrying the understanding snapshot. (Vol. 02 §5, Vol. 04 §2.3)Volume 15 — Terminology and understanding-by-reference (log-growth control, Vol. 03 §8), canvasUnderstanding canvasSeveral clews winding in parallel and collecting one another's committed integrations through where clauses over lanes — cross-pollination under budgets. aka canvas. (Vol. 10 §4)Volume 15 — Terminology diversity/dedup guards, barrier failure guard, run cost metrics.
4. 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 claim exclusivity: behavioural claims() cannot prove exclusive serviceServiceThe function evaluated over the bound scope to produce the integration. Its kind (model instruction, deterministic function, other) is an assembly property. aka service function. (Vol. 06 §3, Vol. 08 §5)Volume 15 — Terminology 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; inspectable claim manifests with overlap validation 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 are the intended mechanism (Vol. 07 §3.3).
5. Operator rendezvousRendezvousOne key lane's gathering state of an operator bind: activation flag, scope, one-shot projection latch. (Vol. 02 §4.5, Vol. 06 §4)Volume 15 — Terminology reset: the one-shot latch never reopens; long-lived figures needing re-projection await an explicit rendezvous reset policyReset policyWhat readiness does to the clew: on_ready clears the wound state; never keeps it, allowing repeated readiness. (Vol. 05 §1)Volume 15 — Terminology — revision-style fresh binds are the sanctioned workaround (Vol. 06 §4.2).
6. Session layer (WaveSession): additive, specified with the Cell extension (Vol. 12 §8); multi-turn products depend on it.

§7. Extension definition checklist

A conforming extension specification states:

1. which rails of §3–4 it uses, and proof the flat machine is unchanged when the extension is absent (root-compatibility test);
2. its protocol family per Vol. 04 §6.3 (shapes, correlation, producers, terminal answers) and its reserved-namespace claims;
3. its authoring surface per Vol. 09 (closed keys, diagnostics, compiler reuse);
4. how attributionAttribution, reachability, terminationThe three load-bearing obligations of the decoupled model. (Vol. 01 §7)Volume 15 — Terminology, reachability, and termination hold, with budgets and their accounting semantics;
5. its honest states and their derivations (what "unfinished" and "failed" look like on the log);
6. its trust boundaries: what is untrusted data, what validates it, what is all-or-nothing, where secrets live, what only the control plane may do;
7. its verification matrix entries (Vol. 14 §4) and regression obligations (golden logs preserved; new fixtures).

Volumes 12 and 13 are written to this checklist and serve as its templates.