Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
170 changes: 170 additions & 0 deletions docs/decisions/ADR-022-durable-link-intent.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,170 @@
# ADR-022: Preserve durable link intent across node-presence races

- **Status:** Proposed
- **Date:** 2026-09-03
- **Depends on:** [Amendment A7](../multiplayer-schema.md#amendment-a7--2026-08-21--stamp-gated-node-presence-canonical-autogrow-naming-scoped-clear-issue-11) (node presence), [Amendment A18](../multiplayer-schema.md#amendment-a18--2026-08-30--normalized-stamped-link-identity) (normalized link identity)

## Context

`delete_node` currently removes an incident live link only when the delete wins
the node-presence register. That is locally sensible but not convergent when a
link already exists in the common snapshot. Given an add at stamp 9 and a
delete at stamp 5, applying add then delete keeps the link because the delete
loses; applying delete then add removes the link before the later add arrives.
The node survives in both replicas, but the graph does not.

Always deleting every incident link is not correct. Amendment A7 says incident
links are severed only when the node is actually removed; a losing delete must
not permanently disconnect a node that survives. The reproducer in
`test/delete-node-lww-loser-removed-links.test.ts` also shows that explicitly
named `removed_links` have different semantics: those removals are ungated and
permanent even when node deletion loses.

The current `links` root cannot represent these distinctions. Once an
incident tuple is deleted, it contains no durable evidence that a winning
connect intent should be added to `links` again after a higher-stamped re-add.

## Decision

Introduce a schema-v3 `__link_state` root keyed by normalized link id. It is
the durable source of link intent; `links` remains the live set exposed to
projection and existing readers.

Each `__link_state` entry is one of:

1. **Connect intent:** the complete normalized link tuple, its A18
link-identity authority, and kind-specific eligibility metadata.
2. **Removal tombstone:** a terminal marker written for a link id explicitly
named in `delete_node.removed_links`.

Link-identity authority is either a modern A18 stamp or the reserved
`imported` baseline. `imported` is an out-of-band value in `__link_state`, not
a fabricated op stamp or an entry in `__stamps`; every valid op stamp sorts
above it. Eligibility is a discriminated union because the three connect kinds
do not share one destination register:

| Connect kind | Durable eligibility | When the intent is in `links` | Retirement and restoration |
|---|---|---|---|
| Concrete input | Destination target `("input", String(to_node), to_slot)` and the stamp that admitted the connect, or `imported` | Both endpoint nodes exist and that target still names the intent's authority | A winning `disconnect` or a later connect on the target retires the old intent. Endpoint deletion only removes it from `links`; a winning re-add restores it while the same authority still wins. |
| Promoted input | Destination target `("input", String(to_node), "grow", full_declared_name)`, its stamped or `imported` authority, and the declared slot descriptor | Both endpoints exist and the full-name register still names the intent's authority; the declared slot is reused or recreated by name | A later winner on the full-name register retires the old intent. A matching `disconnect` resolves through the stored full-name target rather than treating the current numeric index as a different register. Endpoint deletion and re-add have the same remove/restore behavior as concrete input. |
| Autogrow | The link's unique `grow_id` plus the complete grow request; an imported intent instead carries the exact persisted grown-slot descriptor because its original request is unavailable | Both endpoints exist and that grow identity has not been retired; no destination-input stamp participates | A matching `disconnect` records retirement against that grow identity. An unrelated input-register winner cannot retire it. Endpoint deletion removes the tuple; when destination re-add makes the slot absent, it is recreated from the durable request or imported descriptor before the tuple is restored. |

The inputcount widget write embedded in an autogrow remains its separate
stamped widget register. It does not turn the grown slot into a scalar
destination-input register.

The transition rules are:

- A winning `connect` stores or replaces connect intent after the existing A18
link-identity gate and its kind-specific eligibility checks pass. It adds the
tuple and coherent endpoint references to `links` only while the conditions
in the table hold.
- A winning node delete removes incident tuples and endpoint references from
the live graph but keeps their connect intent. A later winning re-add adds
each still-eligible intent back to `links`.
- A losing node delete changes neither incident intent nor `links`.
- Every id in `delete_node.removed_links` writes a removal tombstone even when
no live tuple has that id. This preserves A7's ungated, monotonic severance
and prevents an older or hidden connect intent from reappearing.
- `disconnect` retires the matching connect intent according to its stored
eligibility kind, including while the tuple is absent because an endpoint is
absent. The durable state, not the current `links` entry, supplies the kind
and target.
- A later A18 link-identity winner may replace older connect intent, but an
explicit-removal tombstone for that normalized id is terminal because the op
vocabulary does not permit link-id reuse.
- `clear` has only `removed_nodes`; it writes no link tombstones. It removes a
live incident tuple only when deletion wins for at least one endpoint named
in `removed_nodes`, and keeps that tuple's intent for a later winning re-add.
Permanent severance by `clear` would require an operation-vocabulary change
that supplies explicit link ids.

The live graph is derived only from durable registers. Arrival order never
decides whether intent exists, whether it is eligible, or whether its tuple and
endpoint references are installed.

## Schema and migration

This adds a root map, so `SCHEMA_VERSION` must move from 2 to 3
([KA-11](../INVARIANTS.md#ka-11--schema-version-discipline-is-enforced-on-read)).
The host-owned v2 → v3 migration validates every live v2 `links` tuple and
seeds one connect-intent entry for it. It classifies the destination in this
order:

1. **Promoted:** the destination node is an instance of a stored definition
and the destination slot name is one of that definition's declared inputs.
2. **Autogrow:** the destination slot's normalized `grow_id` equals the
normalized link id.
3. **Concrete:** every other coherent destination slot.

Migration preserves each complete, internally consistent modern record
independently: an A18 record remains the identity authority; a concrete or
promoted input record remains its eligibility authority; and autogrow's grow
and grow-request records remain its request. Where one of those records is
absent, the corresponding authority or descriptor is `imported`. This is the
expected path for ordinary links copied by `mint()`, which have no A18 or
destination-input stamps, and for imported autogrow slots whose original
request is unavailable; the latter preserves the exact slot descriptor already
in the workflow. A future stamped operation always supersedes an `imported`
authority without discarding any modern authority migration did find.

Migration refuses only a malformed or incoherent live tuple: for example, a
non-six-field tuple, a map key that disagrees with its normalized id, a missing
endpoint or indexed slot, or endpoint references that disagree with the tuple.
Missing A18, input, grow, or grow-request stamps are not a refusal and never
cause migration to invent ordering metadata.

`mint()` seeds the same `imported` state directly for coherent workflow links;
`initDoc()` creates the empty root. The wire-layout fixture, schema
documentation, root-name mutation guards, and read-surface accessors move in
the same change. Snapshot compaction must retain `__link_state` even for links
currently absent from `links`. Re-minting from `project(doc)` alone would
discard intent, so compaction must copy the durable root or use a schema-owned
compact representation rather than treating projected workflow JSON as
complete state.

## Required implementation gates

The implementation is not complete until permanent tests cover:

- the imported-baseline link delete/add race in both arrival orders, including
a winning delete followed by a higher re-add at either endpoint;
- named removal of a live link and of a nonexistent link;
- concrete, promoted, and autogrow eligibility, including a disconnect while
each kind's intent is absent from `links`;
- competing A18 link-identity and concrete/promoted input-register winners;
- duplicate delivery and both batch boundaries;
- `mint()` and v2 → v3 migration for unstamped concrete, promoted, and
autogrow links, plus malformed-tuple refusal, current-version no-op, and
unreadable-schema refusal;
- `clear`, snapshot encoding, and compaction retention.

The convergence tests must fork replicas from one snapshot
([KA-10](../INVARIANTS.md#ka-10--bootstrapreconnect-forks-from-one-seeded-snapshot)),
compare canonical projections after legal causal permutations
([KA-4](../INVARIANTS.md#ka-4--the-applier-is-deterministic-and-idempotent)),
and verify byte-identical retry behavior. The v3 wire-layout test must make
omission or renaming of `__link_state` fail.

## Rejected alternatives

- **Always remove incident links:** converges by permanently severing wiring
for a delete that loses node presence, contradicting A7.
- **Reconstruct from the deleted tuple:** the tuple no longer exists in one
arrival order, so reconstruction itself is arrival-dependent.
- **Keep hidden tuples in `links`:** makes projection and current callers see
links whose endpoints are absent, violating the existing live-link contract.
- **Encode intent only in `__stamps`:** a stamp cannot recover the complete
tuple or kind-specific eligibility needed to decide live membership.

## Consequences

- The graph converges without changing the product meaning of a losing node
delete or an explicit named severance.
- Link lifecycle becomes an explicit durable state machine rather than an
inference from the current live graph.
- The change is intentionally schema-wide: migration and compaction are part
of correctness, not follow-up cleanup.
- Hidden intent increases document size until an explicit removal retires it;
host compaction can discard only state proven unreachable under the no-id-
reuse rule.