Repository navigation
docs(adr): CRDT-RECOVERY-0029 — sequence-gap recovery replays against the existing follower doc - #16160
Conversation
DrJKL
left a comment
There was a problem hiding this comment.
I found one correctness issue in the proposed recovery invariant. Details inline.
DrJKL
left a comment
There was a problem hiding this comment.
Proposed committable language for the recovery invariant.
|
Note Agent-authored update.
Full context for agent readersCommit Validation: |
|
@coderabbitai review |
|
696abf2 to
30bd71a
Compare
|
@coderabbitai review |
|
# Conflicts: # docs/adr/README.md
Addresses review feedback:\nhttps://github.com//pull/16160#discussion_r3879129889
Addresses review feedback:\nhttps://github.com//pull/16160#discussion_r3883679146
DrJKL
left a comment
There was a problem hiding this comment.
Two issues remain before this ADR is internally consistent.
- ADR-0024 says an explicit
doc_resetis the sole replacement path. This ADR also replaces the document when the generation ID is missing or cannot be verified. Update ADR-0024 in this PR, or state exactly which clause this ADR supersedes. Otherwise both rules will remain live. - The ADR-019 and DQ-47 links return 404 for repository readers, so they cannot verify the decisions that govern this record. Move the governing material to an accessible source or make this ADR self-contained and treat those links as optional history.
The numeric prefix should be reassigned from the latest main immediately before merge. I recommend Lineage-Gated Replay (LGR) as the stable name across renumbering. The repository still requires the numeric ADR prefix, so the acronym complements the number rather than replacing it.
The inline suggestions tighten the prose, distinguish the proposed protocol from the current implementation, remove expired weekend process detail, and align the title and index.
- renumber 0027 -> 0028 to resolve the identifier collision with #16160 (0027-seq-gap-recovery-is-replay-never-wipe.md), which is also open - rewrite Current implementation to reflect #15381 (merged): both listing and deletion now branch on the assetsEnabled/assetDeletionEnabled flags, not just the legacy history path - fold the 2026-08-29 update into the numbered Decision list instead of keeping it as a separate dated section - rename Current Gaps -> Implementation gaps and correct it: decision 7 (history deletion gated on every record deletion succeeding) is verified unimplemented in useMediaAssetActions.deleteAssets on main; only the legacy (assetsEnabled=false) path deletes history today - replace 'unwind' in the meta-review reference bullet with the actual non-atomic/no-rollback semantics decision 7 states - fix three References links: the old asset-record-content-split paths in Comfy-Org/ideation-sharing 404; repoint to the real asset-deletion/intended/{index,logical,scenarios}.md paths pinned to ab6246440c3234fe315e4fc36145c818e5309868 All rewritten claims verified against origin/main source (useMediaAssetActions.ts, assetsStore.ts) and the referenced repo's current tree before applying. Addresses: #16102 (review)
DrJKL
left a comment
There was a problem hiding this comment.
Two consistency issues from my prior review remain.
ADR-0024 says an explicit doc_reset is the sole ordinary follower-document replacement path, while this ADR also requires replacement when generation validation is missing or fails. The records need one rule. The ADR-019 and DQ-47 references also still return 404, so the governing claims are inaccessible.
Maintainability-skill finding: no new finding beyond these duplicated architectural authorities. The renumbering to ADR-0029 is internally consistent. The branch conflicts with the current ADR index and must be updated from main.
Checks: frozen install, Oxfmt, and git diff --check passed; both external references returned 404. Documentation-only typecheck and tests were not run.
| state vector. | ||
| 2. The follower keeps its existing Y.Doc and applies the returned delta only after the | ||
| host confirms the same generation. | ||
| 3. A missing, unverifiable, or different generation is a lineage break. The follower |
There was a problem hiding this comment.
ADR-0024 still says an explicit doc_reset is the sole ordinary follower-document replacement path, while this rule also replaces the document when generation validation is missing or fails. Update ADR-0024 here or state exactly which clause this ADR supersedes so both accepted records define one replacement rule.
There was a problem hiding this comment.
You were right that the two records disagreed, and checking the code first turned up something worse: the ADR disagreed with the implementation, not just with ADR-0024.
What the follower actually does, on current main:
layoutFollowerBridge.ts:283-295— a seq gap withholds the uncertain frame, dispatchesdoc_gap, and callsresubscribe(). The doc is kept and the subscribe carries its existing state vector.layoutFollowerBridge.ts:342—dropDocForNewLineage()is reached from exactly two callers:onDocReset(:333) and asubscribe()naming a differentworkflow_id(:174-175).
So an explicit doc_reset (or a cross-workflow subscribe) is the only replacement path, and a gap never replaces the doc. That is ADR-GRAPH-DOCUMENT-0024, implemented as written.
The old decision 3 here said "a missing, unverifiable, or different generation is a lineage break". No frame carries a generation ID — grep -rn generation src/workbench/extensions/agent/crdt --include=*.ts returns nothing outside tests, and docFrameClient.ts:420-425 sends only workflow_id and state_vector_b64. Read literally, "missing generation" is always true, so that clause mandated replacing the doc on every gap: the opposite of decision 2, of the title, and of the code.
Rewritten in 73b5690 to split the two:
- Decision 1-3, "Current rule (implemented)", restates ADR-GRAPH-DOCUMENT-0024. This ADR now says explicitly that it supersedes no clause of it.
- Decision 4-6, "Required protocol change (not implemented)", is the generation ID as a proposed wire change. Decision 5 says ADR-GRAPH-DOCUMENT-0024 gets amended when it ships, not before, and there is an explicit line that decision 5 must not be read as "absent generation means lineage break".
ADR-GRAPH-DOCUMENT-0024 gained a matching paragraph in its reconnect section plus a Glossary qualifier, so both records now name the same single rule and the same open exposure.
One thing I did not paper over: status went from Accepted back to Proposed. You asked for Accepted earlier because the index said Accepted, but main no longer carries that row, and the substance of this ADR is a protocol change nothing implements. Marking that Accepted while the code does something else is the failure mode this thread caught. Happy to flip it back if you read it differently.
Also worth flagging, since it bears on decision 6 being an accepted risk rather than a theoretical one: #16372 shows a rejected Yjs update mutating the replica before throwing, with the state vector advancing past it, and #16353 shows a resubscribe carrying a vector that already covers a withheld update, so the host returns no delta. Neither is in scope here, but both are the same ambiguous-recovery surface.
| ## References | ||
|
|
||
| - [ADR-0003](0003-crdt-based-layout-system.md) — centralized layout management with CRDT. | ||
| - [ADR-019 — CRDT weekend final call](https://github.com/christian-byrne/in-app-agent-program/blob/main/decisions/ADR-019-crdt-weekend-final-call.md) |
There was a problem hiding this comment.
This reference and the DQ-47 reference below still return 404 for repository readers. Move the governing material to an accessible source, or make this ADR self-contained and identify these links as optional history.
There was a problem hiding this comment.
Confirmed, and the cause is worse than a bad path. Both targets exist but sit in private repos:
christian-byrne/in-app-agent-program—.privateistrue.decisions/ADR-019-crdt-weekend-final-call.mdis really there, but only I can see it.christian-byrne/blocked-on-christian— also.private: true. Issue 56 is "URGENT DQ-47: choose one CRDT sequence-gap ADR vehicle and owner".
So they 404 for every reader of this repo and govern nothing here. Same shape as #16191, where the cited ADR-017 turned out to live in that same private repo.
A third link was dead for an unrelated reason: [ADR-0003](0003-crdt-based-layout-system.md) pointed at a filename that no longer exists — main renamed it to CRDT-LAYOUT-0003-crdt-layout-intent-and-local-measurement.md. pnpm adr:check rejects the old form outright as a legacy numbered reference.
Fixed in 9c28f37:
- Both private links dropped as references. What they settled that still governs is now stated inline — the deferred-contracts section names the three open contracts itself instead of pointing at a tracker nobody can open.
- They survive only as a trailing "Non-public history (not governing)" note that says plainly the records are unreadable from this repo and confer no authority. I would rather name the provenance and mark it unreachable than quietly delete it, but tell me if you would rather it go entirely.
- The ADR-0003 reference now points at the renamed file.
The ADR is self-contained now: nothing in the decision depends on a link a reader cannot open.
Resolves the docs/adr/README.md index conflict in favor of main's TOPIC-NNNN identifier scheme. The new ADR's index row is re-added under its renamed identifier in the following commit.
The follower replaces its doc in exactly two places -- an explicit
doc_reset, and a subscribe naming a different workflow_id. A sequence
gap withholds the frame and resubscribes with the existing doc's state
vector; it never replaces the doc. That matches ADR-GRAPH-DOCUMENT-0024.
The previous decision 3 ("a missing, unverifiable, or different
generation is a lineage break") contradicted that code: no frame carries
a generation ID today, so read literally it mandated replacing the doc
on every gap. Split the decision into the implemented rule and the
proposed protocol change, state that this ADR supersedes no clause of
ADR-GRAPH-DOCUMENT-0024, and amend that ADR to name the same exposure so
both records define one replacement rule. Status drops to Proposed
because the generation ID is not implemented.
Also renames the file to the TOPIC-NNNN scheme now on main and restores
its index row.
Addresses review feedback:
#16160 (comment)
Both cited sources live in private repositories (christian-byrne/in-app-agent-program and christian-byrne/blocked-on-christian), so they 404 for every reader of this repository and govern nothing here. Everything they settled that still applies is stated inline, and they are kept only as a clearly labelled non-governing provenance note. The ADR-0003 reference was also dead: that file was renamed to CRDT-LAYOUT-0003-crdt-layout-intent-and-local-measurement.md on main. Addresses review feedback: #16160 (comment)
🧩 Custom Nodes Ecosystem Matrix: 🟡 Withheld — could not measureExecutes the frontend JS of every registry pack that ships any, against this change, in both renderers. The eight This candidate changes nothing the matrix measures, so every expensive stage was skipped. Reproduce locally# build one shard's fixture, then run it
python3 scripts/registry-census/build_matrix.py --shard 1/4
MATRIX_RENDERER=vue MATRIX_VUE=1 \
npx vitest run --config vitest.matrix.config.mts
Full docs: scripts/registry-census/README.md 🌾 Fallow: ✅ PassedFallow audits the diff for duplication, complexity and dead code. It gates on new findings only, so when the audit completes, a red is something this PR introduced or moved — never inherited backlog. A red can also mean the audit itself did not finish; the details below say which happened. No new findings in the changed files. Reproduce locally# the base the gate compared against
npx fallow audit --root . --quiet --format json \
--changed-since ae3afc4705a12efcaecde072e5299be0befc4767
Full docs: ADR-DEVEX-LINT-0015 |
DrJKL
left a comment
There was a problem hiding this comment.
Verdict: changes requested
The two prior consistency findings are addressed: the ADR now separates the shipped replacement rule from the unimplemented generation-ID proposal, and its governing rationale no longer depends on private references.
One integration blocker remains. This head still conflicts with current main in docs/adr/README.md (mergeable_state: dirty; merge-tree conflict reproduced against origin/main at 53d8eb9f). Please update the branch, retain both ADR index additions while resolving the table, and rerun the claimed merged-tree checks. The PR description currently says this conflict was already cleared, but the live head is still based on dd1867ba.
I also left one committable suggestion for the protocol wording: not every accepted frame carries a sequence number.
Checks: live head fetched and confirmed as 9c28f37a; current-main merge conflict reproduced; adr:check passed via the direct tsx entry point; Oxfmt passed on all three changed files; git diff --check passed; CI is green for the head. Documentation and maintainability lanes completed. Fallow, unit tests, and typecheck are not applicable to this Markdown-only diff.
| ## Context | ||
|
|
||
| The in-app agent's CRDT follower integrates Yjs updates from one authoritative doc | ||
| host. Every frame carries a sequence number, so transport loss can leave a gap. |
There was a problem hiding this comment.
doc_subscribed and doc_ops_result accept seq only optionally, while awareness has no sequence field, so “Every frame” overstates the protocol. Narrow this to the frame whose sequence actually drives gap detection:
| host. Every frame carries a sequence number, so transport loss can leave a gap. | |
| host. Every `doc_update` carries a sequence number, so transport loss can leave a | |
| gap. |
Dismissed at DrJKL's request during the Agent PR survey. This does not mark the findings as fixed or approve the PR.
DrJKL
left a comment
There was a problem hiding this comment.
Approved on 2483eb74148bab979eb98bb80254edaf7568d880.
I pushed two commits to unblock this ADR:
a4206bc5merges currentmainand keeps both new ADR index rows.2483eb74replaces the obsolete generation-ID proposal with the existinglineage_seqcontract and fixes the sequence-number wording.
Relevance check: #18700, #20172, and closed #16375 do not replace this decision. The host and generated contract already carry lineage_seq, but the frontend still uses it only on doc_reset. It does not read it from updates or subscribe acknowledgements and does not send known_lineage_seq. The ADR is still needed to record the missed-reset exposure and the follower change.
The earlier findings are resolved: the ADR and GRAPH-DOCUMENT-0024 state one current replacement rule, private records do not govern the decision, the ADR-index conflict is gone, and the protocol wording matches the code.
Checks: ADR validation, ADR links, Oxfmt, and git diff --check passed locally. Required CI passed on this head, including lint, typecheck, Fallow, unit, and E2E gates.
Resolved on 2483eb7: ADR-0024 and CRDT-RECOVERY-0029 now state one current replacement rule, and private records no longer govern the decision.
Summary
Adds ADR-CRDT-RECOVERY-0029 for in-app agent CRDT sequence-gap recovery and amends ADR-GRAPH-DOCUMENT-0024 so both records state the same current replacement rule.
Changes
doc_reset, a reset synthesized after a re-minting or conflictingdoc_reseed_result, or a subscribe to anotherworkflow_id.lineage_seq: store it with the Y.Doc, send it asknown_lineage_seq, and compare it on updates, resets, and subscribe acknowledgements. Until then, a lost reset during a gap remains an accepted exposure.lineage_seqon updates or acknowledgements.Review Focus
Whether decisions 1-3 match the current follower and whether decisions 4-6 match the generated and host doc-frame contracts.
Validation
tsx scripts/check-adrs.ts, ADR link validation, Oxfmt on the changed docs, andgit diff --checkpass after merging currentmain.