CoAgnes Labthe study spaceresearch preview · build 1ececa2

Orientation · Introduction and Reading Map

Nest Runtime Specification Set — Introduction and Reading Map

CURRENTsnapshot of 14 July 20266 min read

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

At a glance

  • What the Nest runtime is: a virtual machine whose one memory is an append-only wave log, whose units are activation knots, bind descriptors and output controllers, and whose execution model is the wave. §1
  • The three machine classes — deterministic, semantic, hybrid — and the three surfaces where two implementations must agree: the log, the algorithms, the YAML formats. §1
  • The sixteen volumes, the reference-implementation book, and the order in which to read them. §2.1§2.2§2.3
  • The four status labels — CURRENT, DECLARED, PROPOSED, SEED — and the set's conventions: the RFC 2119 key words, numbered rules over code, zero-based offsets. §3§4
  • Where each part of the machine is specified, and how the set governs its own changes. §6§7

Questions this volume answers

  1. What is the Nest runtime, in one sentence? §1
  2. Must a conforming machine use a language model? §1
  3. Where must two implementations agree to be compatible? §1
  4. In what order should the volumes be read? §2.3
  5. What do CURRENT, DECLARED, PROPOSED and SEED mean? §3
  6. Which words mark a requirement? §4
  7. Where is each part of the machine specified? §6
  8. How does the set itself change? §7

This directory is the complete developer specification of 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 — the wave-log virtual machine. It is written in the manner of a processor architecture manual and is deliberately self-contained: everything needed to understand the machine, to implement a conforming machine in any programming language, and to write systems that run on it is inside this directory. TypeScript is used for demonstration only; every normative rule is stated in language-neutral form.

The set was snapshotted from a working reference implementation (the Florispace Core project). That project's source is not required reading: the refimpl book inside this directory describes the reference implementation completely enough to build a fresh compatible one.

§1. What is specified

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 is a virtual machine whose single memory is an append-only wave logWave logThe ordered, append-only history of committed wave tuples. The single source of truth; entries are never rewritten, only appended. aka append-log. (Vol. 03)Volume 15 — Terminology of immutable tuplesWave tupleAn immutable record in the wave log: offset, kind, key, payload. The unit of fact. aka tuple. (Vol. 03 §1)Volume 15 — Terminology, whose execution units are activation 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 (accumulators), bind descriptorsBind descriptorA bind. Woken by an activation knot, it gathers named understandings from the space, judges them, runs a service, and publishes an integration. aka descriptor, bind. (Vol. 06)Volume 15 — Terminology (gather–judge–publish units), and 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 (the I/O boundary), and whose execution model is the wave: a committed tuple propagates through the registered topologyTopologyThe live set of registered activation knots and bind descriptors that the wave flows through. (Vol. 02 §5)Volume 15 — Terminology until the log stops growing and no external 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 is in flight.

A conforming machine may be:

  • deterministic — every 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 and 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 is computed by deterministic functions; the machine is fully replayable from its inputs;
  • semantic — integrations and services are discharged to a large language model (or another non-deterministic oracle) through the membraneMembraneThe boundary where the wave meets the world: output controllers face outward, ingress faces inward. (Vol. 07)Volume 15 — Terminology;
  • hybrid — both kinds coexist; the kind of each function is fixed by the bind and knot declarations and by the controllers installed 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.

The choice is an assembly property, not a core property: the log format, the propagation algorithms, and the authoring formats are identical across all three classes. Compatibility between differing implementations is defined at exactly three surfaces: the log, the algorithms, and the YAML core-structure formats (see 14-conformance-and-verification.md).

§2. Contents

§2.1 Volumes

Vol.FileContentsStatus
0000-introduction.mdThis map, conventions, namingCURRENT
0101-overview.mdThe machine at a glance: philosophy, figure, machine classesCURRENT
0202-machine-model.mdExecution environment, stations, the architectural register fileCURRENT
0303-wave-log.mdThe wave log: envelope, offsets, ordering, persistence (JSONL), quiescenceCURRENT
0404-tuple-reference.mdTuple catalogue: system tuples, protocol families, reserved namespacesCURRENT
0505-activation-knots.mdKnots: lifecycle, clews, deterministic and semantic winding, budgetsCURRENT
0606-bind-descriptors.mdBinds: emit descriptors, operator binds, rendezvous, gates, emit declarationsCURRENT
0707-membrane-and-controllers.mdThe membrane: claims, discharge, correlation, failure conversionCURRENT
0808-virtual-machine.mdThe Nest VM: assembly, settle algorithm, machine classes, terminal statesCURRENT
0909-authoring-formats.mdYAML formats: pipeline grammar, records, packages, schema subset, compilationCURRENT
1010-algorithmic-constructs.mdProgramming guide: gates, canvases, cascades, unfold, figuresCURRENT
1111-extension-points.mdExtension points: rails, declared-but-unenforced constructs, widening disciplineCURRENT / DECLARED
1212-ext-cells-and-charters.mdExtension: Semantic Charters, Cells, CellSpacePROPOSED
1313-ext-experience-protocols.mdExtension: CoAgnes experience protocols; Nest EducationSEED
1414-conformance-and-verification.mdConformance classes, the golden fixture, the seven verification matricesCURRENT
1515-terminology.mdThe canonical vocabulary of the whole setCURRENT

§2.2 The refimpl book

refimpl/ — eight chapters describing the reference implementation unit by unit (kernel, topologyTopologyThe live set of registered activation knots and bind descriptors that the wave flows through. (Vol. 02 §5)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, descriptors, membraneMembraneThe boundary where the wave meets the world: output controllers face outward, ingress faces inward. (Vol. 07)Volume 15 — Terminology 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, runtime and wiring, loaderLoaderThe component that splits an authoring pipeline into individual records and commits them as seeds. aka splitter. (Vol. 09 §6)Volume 15 — Terminology and schema, shells): its state, algorithms, edge cases, exact observable choices, and the liberty space a new implementation has. The volumes are the contract; the book is the worked existence proof and the source of every "reference field" name.

§2.3 Reading order

Volumes 01–03 for orientation; 04–07 are the reference an implementer keeps open; 08 defines what a machine must do; 09–10 are for authors of systems on the machine; 11–13 fix where and how the machine grows; 14 defines "conforming"; 15 is the vocabulary. An implementer then works through refimpl 01–07 beside the volumes; refimpl 08 sketches shells.

Lab fig. 00·1Eight stations along one line from left to right: the map (00), orientation 01 to 03, the reference 04 to 07, the machine 08, authoring 09 and 10, growth 11 to 13, conformance 14, vocabulary 15. Under growth: 11 current and declared, 12 proposed, 13 seed. Under the reference and the machine runs a dashed band: the refimpl book, chapters 01 to 07 beside the volumes, and 08 on shells.The map00Orientation01 02 03Reference04 05 06 07The machine08Authoring09 10Growth11 12 1311 current · declared12 proposed13 seedConformance14Vocabulary15the refimpl book: 01–07 beside the volumes · 08 sketches shells
Lab fig. 00·1Eight stations along one line from left to right: the map (00), orientation 01 to 03, the reference 04 to 07, the machine 08, authoring 09 and 10, growth 11 to 13, conformance 14, vocabulary 15. Under growth: 11 current and declared, 12 proposed, 13 seed. Under the reference and the machine runs a dashed band: the refimpl book, chapters 01 to 07 beside the volumes, and 08 on shells.The map00Orientation01 02 03Reference04 05 06 07The machine08Authoring09 10Growth11 12 1311 current · declared12 proposed13 seedConformance14Vocabulary15the refimpl book beside:01–07; 08 sketches shells
Lab fig. 00·1 The set in its reading order: the map, then orientation, the reference an implementer keeps open, what a machine must do, how to write for it, where it grows, what conforming means, and the vocabulary — with the reference-implementation book read beside the reference, and each volume's status where it is not CURRENT. A reading aid by CoAgnes Lab; §2.3 governs.

§3. Status labels

Every volume, and where necessary every section, carries one of four labels. The labels keep the snapshot honest: nothing declared is presented as enforced, and nothing proposed is presented as agreed.

  • CURRENT — implemented in the reference implementation and covered by its regression suite; the text is a snapshot of working behaviour.
  • DECLARED — present in the authoring formats and validated by the compiler, but not enforced by the runtime (for example branch isolation levels). A conforming implementation must parse and preserve these constructs and must not silently drop them.
  • PROPOSED — agreed design direction, specified normatively in Vol. 12; not implemented behaviour. Implementation must land together with tests and the promotion of the affected sections to CURRENT.
  • SEED — conceptual direction, specified in Vol. 13; to be checked against real product constraints before it hardens.

§4. Conventions

  • Prose is technical British English.
  • The key words MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY are to be interpreted as in RFC 2119. They mark conformance requirements; text without them is descriptive.
  • Normative algorithms are given as numbered rules or pseudocode, independent of any host language. TypeScript fragments are demonstrations aligned with the reference implementation; where a fragment and a numbered rule could be read differently, the numbered rule governs.
  • monospace names refer to tupleWave tupleAn immutable record in the wave log: offset, kind, key, payload. The unit of fact. aka tuple. (Vol. 03 §1)Volume 15 — Terminology kinds, fact types, payload fields, YAML keys, or reference-implementation identifiers.
  • Cross-references of the form "Vol. NN §M" target volumes in this directory; "refimpl NN §M" targets book chapters. References to numbered rule lists are written "§N, check M" or "§N.M" (rule M of section N). All file links stay inside this directory.
  • Mentions of the reference project's file layout (module names, artefact directories) are descriptive anchors, catalogued in refimpl 00 §3–4; a port chooses its own layout.
  • Offsets, indices of log positions, are zero-based. Template item indices ({index} in unfoldUnfoldThe constrained in-wave authoring form: a service result instantiates declared knot/close/head templates. (Vol. 06 §7)Volume 15 — Terminology templates) are one-based; this asymmetry is inherited and fixed (see Vol. 06 §7).

§5. Vocabulary and one naming note

The canonical vocabulary of the whole set is Volume 15: one term, one meaning, older synonyms noted as aka. The two central entities are the activation 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 (which accumulates understanding) and the bind descriptorBind descriptorA bind. Woken by an activation knot, it gathers named understandings from the space, judges them, runs a service, and publishes an integration. aka descriptor, bind. (Vol. 06)Volume 15 — Terminology (which binds, judges, and emits); within a bind descriptor, heads are part of the affinity structure.

Naming note. In the reference project the bare word Nest historically named the workbench shell. This specification set names the whole machine 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 (equivalently, the Nest virtual machine, Nest VM), because the runtime is the nest in which waves live and the workbench is one shell over it. Where the workbench is meant, this set writes Nest Studio. An overloaded word is resolved by explicit definition, not by silent reuse — the same discipline Vol. 15 §9 applies to cell.

§6. Specification map

Machine partNormative volumeReference description
Tuple envelope, emissionsVol. 03refimpl 01 §1
Processor and executor contractsVol. 02 §2refimpl 01 §2
Propagation engineVol. 02 §7, 08refimpl 01 §3
Topology (registration, dispatch, clews)Vol. 02 §5, 05 §2refimpl 02
Deterministic knotVol. 05 §4refimpl 03 §2–3
Semantic knotVol. 05 §5refimpl 03 §4
Emit descriptorVol. 06 §2refimpl 04 §1
Operator bindVol. 06 §3–5refimpl 04 §2
Membrane sweepVol. 07 §3refimpl 05 §1
Inference/service controllerVol. 07 §4refimpl 05 §2
Delegated emit templatesVol. 06 §7refimpl 05 §3
Settle loopVol. 08 §3refimpl 06 §1
AssemblyVol. 08 §1refimpl 06 §2
Pipeline compilerVol. 09refimpl 07 §2
JSON Schema subsetVol. 09 §7refimpl 07 §3
Shells, trace digestVol. 08 §8–10refimpl 08

§7. Governance of this set

The set carries its governance with it:

  1. Same work item. A change to machine behaviour and the matching change to these volumes land together — the set never trails the machine.
  2. Append-only history of agreements. Dated behaviour records are never rewritten, only clarified or superseded by later entries.
  3. Invariants apart from choices. Stable semantics, boundaries, and public contracts belong to the volumes; demo data and diagnostics only where they define required behaviour (the golden fixture does).
  4. Named enforcement. Every structural rule states its enforcement path — a type boundary, a narrow export, or a regression test.
  5. Deliberate widening. Core contracts change only by the recorded procedure of Vol. 11 §2.
  6. Verification. Before publication, and after any substantial revision, the set is re-verified through the seven matrices — truth, deep, connect, 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, knowledge, evolution, responsibility — defined in Vol. 14 §4.