wire: specify and verify Deixis composition and reconstruction laws.

[jm9e]

Deixis service coordination — 2026-09-25

The next API/service interpretation is tracked in #42 and https://github.com/Bitspark/deixis/issues/49, with the common service coordinator at https://github.com/Bitspark/deixis-svc/issues/1. Its target is addressless Wire A0 plus Deixis-derived addressed A1. The declared-composite laws and executed evidence below remain valuable; they do not freeze the current addressed Send(path, message) API or require every opaque Wire to expose a finite tree.

BitTree's snapshot conversion in https://github.com/Bitspark/bittree/issues/37 has since completed and is closed. Its new live TreeAccess/API transition is https://github.com/Bitspark/bittree/issues/53; snapshot structure and live Wire access are separate. Bitwire independence work is #39, superseding the older general assignment of reusable runtime/carrier ownership to Nightseam.

Keep codec, library, runtime and released consumer evidence separate. This issue's remaining release/adoption obligations are not closed by filing the generic service work.

---

Goal

Make Wire composition a concrete, independently tested realization of the selection, reconstruction and interpretation invariants being formalized in Bitspark/deixis#3.

A caller must observe the same supported behavior when a declared composite is accessed directly, selected through nested views, reconstructed from its retained own value and complete named children, or carried through a conforming relay. Existing Bitwire laws cover selection and selection after mounting; this issue adds the reconstruction direction and the evidence needed to claim it.

This is the Bitwire implementation workstream for deixis#3. Deixis owns the general laws and model decision; this repository owns their concrete Wire contract and independent acceptance. Completing one issue does not automatically complete the other.

Accepted design and current delivery

Current design: ADR 0006, delivered by PR #32 squash-merged at fdc2ae99bbd4dcf1f887c5e32bbda2e315c890a1. Declared composites are a precise behavioral realization of Deixis v0.2.0's Node[T] = T × FinMap[Bytes, Node[T]]. A node's value is its origin: the behavior for a message sent at [], conceptually a handler of a Message. Every named child keeps its complete Wire access. A refusing origin is a value, and a child-only mount is the specialization with the refusing origin.

ADR 0006 supersedes ADR0005's policy-bearing node value (from PR #30), before any release. With a policy in the node value, a selected child was a guarded view, so the Deixis selection law needed an inherited context. Interception remains available as an explicit guard composed around access; ADR0005's interpretation is recovered as guard(P, compose(o, …)). The ADR0005 record stays as history, marked superseded.

Evidence, kept separate:

• Reference, test-only. Go and TypeScript interpreters of compose(origin, children) meet all 39 independently authored cases, on local pairs and on WebSockets in both directions.

• Production, released Nightseam v0.6.0. Mount, At and ForwardWire realize the child-only specialization. The 20 child-only cases conform on every carrier in both languages. The other 19 reproduce the exact observations recorded in the gap ledger:

  • no public origin-bearing constructor (16 cases);
  • conflicting segments accepted, because Mount takes a pre-built map;
  • invalid segments accepted;
  • nil or undefined children accepted.

  A changed gap fails the gate, and so does a gap that starts conforming. Mount also requires Endpoint-typed children for send-only composition.

• Unreleased production API, no gaps. Nightseam PR #713 (nightseam#705) adopts ADR 0006. Its ComposeDeclared / Declared.compose take an origin and complete child Wire access, refuse invalid, duplicate and missing children, and bind a send-only view that passes every frame kind on. Bitwire PR #34, squash-merged at 7ad642eac01eed695c97fba10a0dfcc55cec2016, pins Nightseam main b6d52c426e1e53bcf017046b6650930a377f4b33. Its production gate runs all 39 cases through that API in Go and TypeScript, on local pairs and on WebSockets in both directions: 234 executions, no gaps accepted. The upstream construction tests pass under the race detector in CI. Bitwire PR #33, merged at ad23f5cbab763a234b2c27d8299e51706c8c1d14, also runs Nightseam's actual requester-cancellation witnesses through bound, selected and reconstructed access in both languages, including captured destinations after assembler replacement. These supplementary runtime-owned tests and all 234 independent case executions pass at the same pinned commit; Linux CI applies the Go race detector.

• Retired. The ADR0005 gate from PR conformance: verify production declared composition against independent cases. #31, against Nightseam PR #698, and its 27 preserved cases were retired by conformance: gate Nightseam's decision 0006 API with no gaps. #34. They remain in history at fdc2ae9.

What remains open:

• Nightseam release. Nothing released yet: the API is on Nightseam main and targets its 0.7.0 milestone, which is gated on the auth round. When a release ships it, the released baseline moves to that release and production-gaps.json empties. nightseam#703 tracks evidence tied to released revisions.
• Bitwire release. A tag carrying ADR 0006 and the 39 cases is the user's decision. Native declarations are unchanged, so RELEASING.md's policy implies a patch release, v0.2.1.
• Consumers. BitTree's conversion is bittree#37, still to be assessed against ADR 0006.
• Generated code, landed on Nightseam main, evidence owned upstream.
  • nightseam#711 (b3db460): every generated side emits Declared(access). It composes the refusing origin with At(access, [op]) for each operation it receives, plus identity.check. duplex.Through serves a side over declared send access.
  • nightseam#715 (3a9ff3c): generated models behind declared composition, with consumer guards composed around access. It covers local pairs, WebSockets and prepared tunnel channels; direct, selected, reconstructed and forwarded access; and calls, callbacks, events, a refusal, a reply delayed across rebuild and rebind, cancellation in both directions, metadata and teardown. Nightseam reports 180 CI runs (Go/Go, Go/TypeScript, TypeScript/Go) and 60 local TypeScript/TypeScript runs.
• Other languages. The six other runtime ports have no declared construction API: nightseam#702.

This issue stays open for the released runtime adoption and the consumer assessment.

Required laws and scope

Origin = Message → Admission            Parts = Origin × FinMap[Segment, Access]
send(compose(o, m), [],    x) = o(x)
send(compose(o, m), k : p, x) = send(m[k], p, x)   when k ∈ dom m, else refused

(S0) at(w, [])             ≈ w
(S1) at(at(w,p), q)         ≈ at(w, p ++ q)
(S2) at(c, [k])            ≈ m[k]       (S3) ≈ ⊥ when k ∉ dom m
(O)  origin(c)             ≈ o
(R0) compose(parts(c))     ≈ c
(R1) parts(compose(o, m))  ≅ (o, m)     capability identity, exact keys
(M)  mount(m)              ≈ compose(refuse, m)
(H)  I(Node(o, m))         = compose(o, {k ↦ I(m[k])})
(A)  at(I(n), p)           ≈ I(at(n, path(p)))   or ⊥ when undefined

• Key mapping. A segment maps to a Deixis key by exact UTF-8. Empty key and empty path are distinct, and there is no normalization. Keys outside the image are refused at construction, never repaired.
• Definedness. Undefined navigation corresponds to refusal. The converse fails for an existing childless node whose origin refuses; only the retained parts distinguish it.
• Admitted composites. Construction takes an origin and (segment, access) entries, refuses conflicting, invalid and missing children, copies its inputs and retains Parts for its owner. It is finite and acyclic by construction. Opaque children are holes of a declared skeleton, and decomposition stops there.
• Cuts and substitution. Complete cuts agree. Substitution holds only for children equivalent in context, including shared state.
• Authority. Decomposition belongs to the construction owner. A send-only Wire gains no enumeration, unwrapping or method, and an arbitrary Wire is not decomposable.
• Equivalence. ≈ covers admission and refusal, destination and relative path, unchanged messages, return identity and context, replies and invocation outcomes, order, shared state, authority and lifetime. Carrier properties are stated; faults are separate outcomes.

Deliverables

1. ADR: define Wire's Deixis realization, composite-origin rule, complete-decomposition requirement, observation relation and compatibility/version disposition. Use the mandatory-value model accepted in deixis#3, explicitly choose T_Q, and retain the own value alongside the complete child map. Optional parent information, if needed, is an explicit carrier choice. Delivered by ADR 0006 (T = origin).
2. Shared contract: update docs/wire/contract.md, docs/composition.md, relevant profile/ownership documentation and all eight delivered language presentations consistently. Record changes under Unreleased; do not retrofit an unproved guarantee onto an immutable release.
3. Independent cases and runner: extend conformance with input fixtures and separately authored expected observations. Exercise actual implementations through public facilities. Keep historical baselines distinct and tests free of private sibling-checkout or runtime-package dependencies.
4. Runtime evidence: exercise Go and TypeScript against the pinned released Nightseam implementation, locally and over its declared carriers. Record failing requirements as concrete upstream gaps. Keep the language/adoption matrix honest about implementations not exercised.

No new Wire primitive is justified yet. Selection and composition may remain operations around the existing send-only interface. A proposed native API addition must identify an observable requirement that existing composition cannot satisfy.

Required conformance cases

• Direct, nested-selected, mounted, reconstructed and forwarded access agree for complete declared composites.
• Different complete cuts preserve full paths, state and declared observations.
• Empty suffixes, empty child keys, opaque segments, empty declared branches and missing destinations are covered.
• Parent-origin refusal is preserved; independent parent behavior cannot disappear unnoticed.
• Omitted, renamed, extra or conflicting children are rejected or detected as nonequivalent, according to the declared domain.
• Stateful/shared children preserve their state and aliasing; equivalent substitution is checked in an assembly context.
• Return capability, established context, delayed replies and supported cancellation survive the relevant compositions and detach/rebind scenarios.
• Composition teardown preserves borrowed-child usability and the declared ownership rules.
• The runner fails on missing, extra, duplicate or mismatched observations.
• Current production runs, reference-only evidence and unimplemented requirements are reported separately.

Boundaries and related work

• Deixis #3: general formalization, interpretation invariance and structural reconstruction/round-trip laws. Operational undo belongs to consumers.
• Bitwire #20: existing capture-retirement/profile-integration work. Reuse its lifecycle obligations and evidence; this issue neither supersedes it nor closes it by implication.
• Current baseline: existing production composition and lifecycle coverage, with explicit remaining limits.
• Inverse operations and undo receipts belong to session/domain contracts. Bitwire preserves their messages and capabilities under the same composition laws; it defines no generic inverse, undo or witness API.
• Nightseam implements its runtime and carriers. Consumers such as BitTree own their domain/access mappings. Bitwire remains independent of those runtime implementations.

[jm9e]

Nightseam's adoption status for this issue, and one contract point for Bitwire to settle.

Production adoption: in flight

Bitspark/nightseam#698 (issue nightseam#696) adds a production declared-composition API in Go and TypeScript: construction, complete raw parts, immutable fresh-child attachment and guarded send-only binding. It runs all 27 cases of this repository's conformance/declared/cases.json, pinned by revision 671b61d and SHA-256 with expectations withheld from the drivers, through those production facilities: local pairs and both WebSocket directions, Go/Go and TypeScript/TypeScript, 162 executions. Its required full CI is still pending.

The follow-ups are filed under nightseam#697:

• nightseam#699: requester cancellation, below.
• nightseam#700: generated models describe their complete operation domain as a declared composition.
• nightseam#701: generated acceptance, Go and TypeScript in all four pairings over a local pair, a WebSocket and a tunnel channel, with callbacks, returned live references, delayed replies, cancellation, context and teardown.
• nightseam#703: evidence pinned to released revisions.
• nightseam#702: the six other ports, 0.8.0.

Contract point: a requester's cancellation at the bound entry

ADR0005 gives cancellation to "the admitted invocation's captured profile facilities". The only example is callee-side: pending-across-rebuild cancels through the receiving invocation's lifecycle. The requester side is unspecified.

In Nightseam's profile (nightseam.duplex/1) a caller cancels by presenting a cancel frame at the Wire and path its request went out on, carrying the request's return capability and identifier. A physical peer routes it by (return capability, identifier), not by path. Through declared bound access that cancel meets Q's entry, which refuses it, and the body is never cancelled. By the ADR's own sentence, that is a cancellation "already owed by the profile" being suppressed.

nightseam#699 realizes the ADR's clause "Implementations that expose a generic control entry must bind it to the captured invocation" as follows:

• On admission, bound access records the destination own origin, keyed by (Return identity, frame ID).
• A later cancel carrying that key goes once to that origin at [], with no policy and no tree lookup.
• A cancel naming nothing this access admitted, and every response, still refuse. So controls-are-not-new-admission keeps passing unchanged.
• The record is held weakly by the caller's return capability. Rebuild and rebind cannot retarget it, and bound access sends no lifecycle vocabulary to the caller's return capability.

Two questions for Bitwire:

1. Is this the intended reading, or does Bitwire want requester cancellation carried some other way, for example only through a lifecycle-speaking return capability?
2. If it is, can Bitwire add an independent case for it: admit a request, rebuild and rebind, then cancel at the original bound access? Nightseam would then run Bitwire's expectation rather than its own.

Evidence boundary

ADR0005 and conformance/declared/ exist only on main (671b61d); v0.2.0 predates them. Nightseam's evidence can therefore cite a commit but not a released contract. The current baseline here also still pins Nightseam v0.6.0, which has no production construction API. nightseam#703 moves Nightseam's pin once Bitwire tags a release carrying ADR0005 and Nightseam releases the API. The matching pin in conformance/current/nightseam.json stays with this repository.

---

Drafted by Claude (Opus 5.5) in Julian's Claude Code session and posted at Julian's request.

[jm9e]

Contract and independent acceptance for the Deixis v0.2.0 realization landed in #32, squash-merged at fdc2ae99bbd4dcf1f887c5e32bbda2e315c890a1.

• ADR 0006. A node's value is its origin, the behavior at []. Named children keep their complete Wire access, and a mount is the case with a refusing origin. The ADR fixes the exact UTF-8 segment-to-key mapping, both reconstruction directions, refusal as the counterpart of undefined navigation, complete-cut agreement and the observational equivalence. It supersedes ADR0005's policy-bearing node value before any release. Interception becomes a guard composed around access. No Wire method is added, and decomposition stays with the construction owner.
• Evidence.
  • 39 independent cases, run on local pairs and on WebSockets in both directions.
  • Reference interpreters (test-only): all cases pass in Go and TypeScript.
  • Released Nightseam v0.6.0 Mount: the 20 child-only cases conform. The other 19 must match the exact observations in conformance/declared/production-gaps.json: no origin-bearing constructor, and conflicting, invalid or missing children accepted.
  • ADR0005's 27 cases are preserved byte for byte and still gate Nightseam's unreleased #698 API. That gate is evidence about ADR0005, not ADR0006.
• Runtime adoption is handed to Nightseam in duplex: adopt Bitwire decision 0006 declared composites with origins and complete children. nightseam#705. This issue stays open for that adoption and for the consumer assessment (bittree#37).

[jm9e]

Nightseam's unreleased API now meets ADR 0006 with no gaps. nightseam#713 merged as b6d52c4, and Bitwire #34 (7ad642e) gates it on all 39 cases: Go and TypeScript, local pairs and both WebSocket directions, 234 executions. The ADR0005 gate is retired. Still open: a Nightseam release shipping the API (0.7.0, which also lets the released gap ledger empty), the Bitwire release decision (v0.2.1 per policy) and the BitTree assessment (bittree#37).