Volume 08 — The Nest Virtual Machine: Assembly, Settle, Classes, States

This volume assembles the parts of Vol. 02–07 into the machine as a whole: the 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 rule, the settleSettleThe runtime algorithm alternating propagation with membrane discharges until the machine settles. (Vol. 08 §3)Volume 15 — Terminology algorithm that drives a wave to rest, the determinism and replay guarantees per 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, the honest terminal states, and the derived-reading discipline for shells. A conforming Nest VMNest 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 in any host language is defined by this volume plus the formats it references.

§1. Assembly

One machine instance is assembled as:

NestVM = Runtime( Engine([ Topology(strategyRegistry), …observers ]),
                  Membrane([ …controllers ]) )

Rules:

1. One 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 per product. Every shell of one product (CLI, workbench, chat, tests) MUST drive the same assembly function, differing only in how seeds are fed and the log is read. Behaviour identical by construction.
2. ObserversObserverA passive wave processor that mirrors tuples and emits nothing behavioural. (Vol. 02 §3.4)Volume 15 — Terminology are plain processors registered beside the topologyTopologyThe live set of registered activation knots and bind descriptors that the wave flows through. (Vol. 02 §5)Volume 15 — Terminology; observation never touches the core (the reference LogMirror feeds both the persisted JSONL store and live feeds from one sink).
3. 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 installed statically at assembly (Vol. 07 §2.6).
4. The topology is one processor among processors — replaceable by a routing processor that owns local topologies, which is exactly the Cell extension's move (Vol. 12 §4): Engine([CellSpace(root: Topology), …observers]).

Reference demonstration:

export function assembleWave(observers: readonly WaveProcessor<AnyTuple>[] = []) {
  const controller = new TogetherInferenceController(loadTogetherInferenceConfig(), {
    apiKey: resolveTogetherApiKey()
  });
  return new WaveRuntime(
    new WaveEngine<AnyTuple>([new TopologyGraph(), ...observers]),
    new Membrane([controller])
  );
}

§2. Inputs: seeds

A run begins with seeds: the compiled pipeline's individual recordsIndividual recordA single activation-knot or bind-descriptor definition, split out of the authoring pipeline at load and committed to the wave log. (Vol. 04 §2)Volume 15 — Terminology followed by the declared input facts (buildInputFacts translates named input values to facts of the declared types on the chosen key). Seeds are ordinary 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; the engine assigns their offsets like any other.

§3. The settle algorithm

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

The runtime drives the wave across the membraneMembraneThe boundary where the wave meets the world: output controllers face outward, ingress faces inward. (Vol. 07)Volume 15 — Terminology until the machine settlesSettleThe runtime algorithm alternating propagation with membrane discharges until the machine settles. (Vol. 08 §3)Volume 15 — Terminology:

settle(seeds):
  assert ¬SETTLING; SETTLING ← true
  pending ← seeds
  loop:
      log ← engine.run(pending)                 // propagate to quiescence (Vol. 02 §7)
      for d in membrane.sweep(log):             // start new discharges (Vol. 07 §3)
          DISCHARGE.TABLE += d
      if DISCHARGE.TABLE = ∅:
          SETTLING ← false; return log          // settled
      pending ← await earliest completed discharge; remove it from DISCHARGE.TABLE

Normative points:

1. Alternation. Propagation and 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 alternate: the engine always runs to quiescenceQuiescentThe engine cursor has consumed the whole log and produced nothing further. (Vol. 03 §7)Volume 15 — Terminology before the membrane sweeps; discharge answers re-enter as the next run's seeds. 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 never observe a half-propagated log.
2. Earliest completion wins. The runtime awaits the earliest completed discharge (any fair completion order is conforming), commits its 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, and loops. Multiple discharges MAY be in flight simultaneously; their answers interleave in completion order — consumers rely on correlation, not adjacency (Vol. 03 §3).
3. One wave at a time. A machine instance handles one settling wave; a concurrent settle is a caller error. Repeated sequential settles on one instance are permitted and are the substrate of sessions (§9).
4. DefectDefectA rejected discharge or invalid registration; the settle fails and the shell reports it. (Vol. 08 §7)Volume 15 — Terminology path. A rejected discharge aborts the settle with the defect; the log up to that point remains valid history (persisted by observersObserverA passive wave processor that mirrors tuples and emits nothing behavioural. (Vol. 02 §3.4)Volume 15 — Terminology), and the shell reports the terminal state defect.
5. settle([]) on a machine with committed-but-unswept tuplesWave tupleAn immutable record in the wave log: offset, kind, key, payload. The unit of fact. aka tuple. (Vol. 03 §1)Volume 15 — Terminology is valid: the sweep picks up from MEMBRANE.CURSOR.

§4. The full tact, end to end

The complete causal chain of one semantic tact, as the log records it:

input fact ──► knot matches, winds        (queues delta)
           └─► knot projects  inference.request(uid₁)      [engine run n]
membrane sweeps, controller discharges uid₁                [between runs]
world answers ──► inference.response(uid₁) (+reasoning)     [seeds of run n+1]
knot winds integration ──► GRADE ≥ threshold
topology commits  sys.knot.ready {knotId, understanding}
bind rendezvous completes ──► gates pass
bind projects  service.request(uid₂: scope, schema, emit)
membrane sweeps, controller discharges uid₂
world answers ──► publication under emit declaration (+service.reasoning)
                    e.g. fact  frame.truth.ready {bindId, uid₂, result}
… downstream knots wind the publication …                  (the cascade continues)
quiescent ∧ no discharge in flight ──► settled

§5. Machine classes and determinism

The class taxonomy of Vol. 01 §5 has these normative consequences:

1. Deterministic class. With deterministic executors, integrators, and 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 (or none), re-execution from identical seeds MUST reproduce the log byte for byte (modulo host JSON number formatting, which SHOULD be normalised). This is the strongest conformance class and the required class for golden-log tests (Vol. 14 §2). Note the engine itself introduces no non-determinism: single-threaded propagation, ordered processors, ordered batches.
2. Semantic class. Non-determinism enters exactly 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. Re-execution MAY differ; therefore: the log is the record of what happened (replay is reading, Vol. 03 §6.4); tests substitute deterministic controller doubles; acceptance runs are recorded, not re-run. Interleaving of concurrent discharge answers is additionally scheduling-dependent — consumers MUST be correlation-driven.
3. Hybrid class. Deterministic sub-figures retain class-1 guarantees when their inputs are fixed; the machine as a whole carries class-2 guarantees.
4. In all classes, given one already-committed log, every derivation of §8 MUST be a pure function of it — identical across implementations.

The class is decided by the installed 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, local integratorLocal integratorThe pure function (deltas) → {state, grade} used by locally winding semantic knots. (Vol. 05 §5.1)Volume 15 — Terminology, and controllers — the types of functions bound in 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 and binds are an implementation liberty, bounded only by the protocol contracts (Vol. 04) and station rules (Vol. 02 §3).

§6. Conformance obligations of a machine

A conforming Nest VMNest 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 MUST provide, observably:

1. the envelope, ordering, and batch semantics of Vol. 02 §7 / Vol. 03;
2. the topologyTopologyThe live set of registered activation knots and bind descriptors that the wave flows through. (Vol. 02 §5)Volume 15 — Terminology dispatch and 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 reification of Vol. 02 §5;
3. the 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 lifecycle and two bundled strategies of Vol. 05 (further strategies optional);
4. the two descriptor forms and 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 algorithm of Vol. 06;
5. the sweep, 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, and failure discipline of Vol. 07;
6. the settleSettleThe runtime algorithm alternating propagation with membrane discharges until the machine settles. (Vol. 08 §3)Volume 15 — Terminology algorithm of §3 with its alternation and defectDefectA rejected discharge or invalid registration; the settle fails and the shell reports it. (Vol. 08 §7)Volume 15 — Terminology rules;
7. the honest terminal states of §7;
8. rejection-with-diagnostics for every unsupported authoring construct it loads (Vol. 09 §5) — silence is non-conforming;
9. the JSONL persistence format when it persists runs at all (Vol. 03 §6).

§7. Terminal states

Every run ends in exactly one of three honest states, and shells MUST present them without embellishment:

"Unfinished" is a derivation over the settledSettledQuiescent with no discharge in flight. (Vol. 03 §7)Volume 15 — Terminology log (unanswered-uid count, open lids), not a distinct runtime signal — deliberately, until a quiescenceQuiescentThe engine cursor has consumed the whole log and produced nothing further. (Vol. 03 §7)Volume 15 — Terminology hook is added (Vol. 11 §6). Runtime quiescence is never presented as epistemic success: settled means "the machine has nothing further to do", not "the answer is good" (assessment is a separate concern, Vol. 12 §7).

§8. Derived readings (shells)

Everything a shell shows MUST be derivable from 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, persisted logs, or immutable package artefacts — no shell-private truth about a run. The reference derivations, all pure functions of the log:

• the feed — tuples in offset order (live via a mirror processor; SSE replay of a finished run reconstructs the same surface);
• the trace digest (vault of lidsVault of lidsThe trace digest read backwards: binds as closing lids with their affinity hanging below; an unprojected bind is an open lid with empty demand sockets. (Vol. 08 §8)Volume 15 — Terminology) — the log read backwards as bind lids: each bind with its outcome (fact / unfoldUnfoldThe constrained in-wave authoring form: a service result instantiates declared knot/close/head templates. (Vol. 06 §7)Volume 15 — Terminology / rejected / failed / pending), its intention (scope keys, instruction), and its affinity hanging below — activation and demandDemandA named binding (as:) to an activation knot whose integrated understanding the bind descriptor gathers back. The gathering face of affinity, and the second method through which understanding enters the bind. aka tendril. (Vol. 06 §3–4)Volume 15 — Terminology 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 with their 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 tacts (request / response / reasoning / failure offsets, grades), repeated 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 folded to a count, provenance threads (emittedBy) shown; an operator bindOperator bindThe full bind form: activation + demands + gates + a service crossing the membrane. (Vol. 06 §3)Volume 15 — Terminology whose intention has not projected reads as an open lid with empty demand sockets — the barrierBarrierThe 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's wait is a picture, not a search;
• run metadata — the sidecar counters of Vol. 03 §6.3;
• (PROPOSED) Charter/Cell/decision/artefact digests of the extension (Vol. 12 §7).

Extensions and shells MUST follow the same rule: if the UI needs data not in the log or records, the protocol is widened first.

§9. Sessions and continuation

Current stage: one machine instance per run; settle called once (the workbench's run orchestration) — plus the standing capability of repeated, non-overlapping settlesSettleThe runtime algorithm alternating propagation with membrane discharges until the machine settles. (Vol. 08 §3)Volume 15 — Terminology on one instance in one process.

• WaveSession (PROPOSED). A session layer owns one runtime and key, serialises 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 (messages, review decisions), calls settle again only after the previous settle completes, mirrors every tupleWave tupleAn immutable record in the wave log: offset, kind, key, payload. The unit of fact. aka tuple. (Vol. 03 §1)Volume 15 — Terminology to one JSONL/SSE history, and exposes derived digests. It requires no core change (Vol. 12 §8; Vol. 13 §5 depends on it).
• Restart-safe continuation — rehydrating registers from a persisted log and continuing without re-discharging old intentions — is an explicitly open core-widening decision (Vol. 11 §6). A conforming machine MUST NOT silently re-discharge intentions from a reloaded log.

§10. Shells of the reference implementation

For orientation (not normative beyond the one-assembly rule):

• CLI — bare start runs the bundled demo; run | validate | nest over pipelines; the log tail printed as JSON lines (refimpl 08 §1);
• Nest Studio (the workbench) — localhost server over the same 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: pipeline catalogue with compiler verdicts, run creation with generated input forms, live SSE feed, persisted run history, the trace vault and feed, brick-based authoring writing ordinary pipeline packagesPipeline packageA directory of pipeline.yaml beside schemas/* — the portable programme unit; drafts and templates are ordinary packages. (Vol. 09 §8)Volume 15 — Terminology (drafts), and template promotion with provenance — every view a derivation per §8; full description with the API surface: refimpl 08 §2–3;
• planned surfaces (chat + Charter rail; Learn) are extension volumes' concern (Vol. 12 §8, Vol. 13 §5).