Skip to content

fix(clock): read the Lamport floor past counterless __stamps rows; opt-in skipMalformed - #300

Merged
christian-byrne merged 9 commits into
mainfrom
cbyrne/lamport-floor-companion-rows
Nov 5, 2026
Merged

christian-byrne merged 9 commits into
mainfrom
cbyrne/lamport-floor-companion-rows

Conversation

@christian-byrne

@christian-byrne christian-byrne commented Nov 1, 2026 •

Copy link
Copy Markdown
Contributor

Carries Simon's #280 forward onto current main (his six commits, cherry-picked with authorship kept). #280 had gone stale and conflicting; this replaces it.

Problem

observedDocCounter is how a producer finds the Lamport floor to stamp above. It throws __stamps contains a malformed stamp tuple on ordinary documents, because the applier itself writes two counterless companion rows into __stamps:

  • ["grow_request", …] from an autogrow connect (growInputSlot);
  • ["interior_route", …] from deleting a subgraph instance (applyDeleteNode).

After one autogrow connect or one subgraph-instance delete, the floor is unreadable on that document from then on. Cloud's doc host catches the throw and skips the Lamport lift (services/agent/dochost/src/lamport.ts, documentCounter), so on those documents the agent's edits fall back to the old counter and can be LWW-dropped behind a person's earlier edit again, the case Comfy-Org/cloud#14881 fixed.

Fix

  • observedDocCounter passes over __stamps rows whose canonical key starts with grow_request or interior_route. The tags are shared with the applier's key builders (GROW_REQUEST_TAG, INTERIOR_ROUTE_TAG in doc.ts). Reservations are never skipped. The counters those ops carry are still counted through their own stamps.
  • Opt-in observedDocCounter(doc, { skipMalformed: true }) returns { counter, skipped } for producers that must keep minting. The default call still fails closed, and DocDerivedLamportClockStore keeps the strict read.
  • Schema doc: Amendment A27 (renumbered from fix(clock): read the Lamport floor past counterless __stamps rows; opt-in skipMalformed #280's A25, which main has since used).

Changes on top of #280 (from an adversarial review)

  • Lenient mode no longer drops a malformed row's readable counter. Before, a row like [900, 42, op] was skipped whole, so the floor could stay at a lower readable counter and the producer would mint under 900. Over-estimating the floor is safe; under-estimating it is the LWW loss this whole fix is about.
  • Companion rows are skipped by key AND value: interior_route only when the value is a string, grow_request only when its first element is not a number. A counter-shaped row under a companion-looking key is counted, not dropped.
  • Accepted Lamport decision D2: in lenient mode an unreadable __clock_reservations root counts as one skipped entry instead of throwing. An unreadable __stamps root still throws in both modes.
  • The applier stores a grow's widget as sent, so a grow with a non-string widget must still leave the floor readable; a test runs that real connect through applyOps.

Red / green

  • Red on main (src/clock.ts from main, tests from this branch): 3 failures, all TypeError: __stamps contains a malformed stamp tuple (autogrow floor, lenient mode, floor after subgraph delete).
  • Review fixes, each red first: lenient floor {counter: 50} instead of 900; companion-keyed counter row hidden (undefined instead of 60); real grow with widget: 5 threw malformed stamp tuple.
  • Green on this branch: npm test 1892 passed / 2 skipped (1894); check:purity, check:imports, check:pins, check:profile-claims, check:coderabbit, check:stateless, check:adrs, verify:corpus, lint, typecheck all pass.
  • The full op-pool permutation sweep now asserts every generated document's floor is readable, so a new counterless __stamps row fails a test instead of failing producers.

Invariants

  • KA-13 (no package-owned state): unchanged; the read is pure and check:stateless passes.
  • KA-2 / KA-4 (ordering identity in the op; deterministic apply): unaffected; only the floor read changes, not apply or compare.
  • Public exports: observedDocCounter gains an overload and LenientDocCounter is exported. The one-argument call keeps its signature and fail-closed behaviour.

After merge

Release a patch version, then bump the pin in cloud's services/agent/dochost so the agent's Lamport lift works on documents with autogrow connects or deleted subgraph instances.

synap5e and others added 8 commits November 1, 2026 08:38
observedDocCounter threw "malformed stamp tuple" on any document with an
autogrow connect, because the applier keeps each grow's requested slot shape
in __stamps under a ["grow_request", ...] key. Those rows carry no counter;
skip them so producers can take a Lamport floor from real documents.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
(cherry picked from commit 26b6aea)
…ves alone

A deleted subgraph instance leaves its definition id in __stamps under an
["interior_route", ...] key, which made the floor read throw the same way.
Skip both companion row kinds, and test that the grow's own stamp still
counts and fails closed and that reservations are never skipped.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
(cherry picked from commit 733fbe3)
… op-pool sweep

Every generated op-pool document now asserts its Lamport floor is readable,
so a new counterless __stamps row fails a test instead of producers.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
(cherry picked from commit e88fec4)
…keep minting

observedDocCounter(doc) still fails closed on a malformed row (ADR-021).
observedDocCounter(doc, { skipMalformed: true }) returns the maximum over the
readable rows of both ledgers plus the count it passed over, so a producer
can stamp above every valid counter instead of refusing or dropping to zero.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
(cherry picked from commit 14b33ac)
… schema doc

The floor read's companion prefixes are derived from GROW_REQUEST_TAG and
INTERIOR_ROUTE_TAG in doc.ts, which the applier's key builders also use.
Amendment A25 records the companion skip and the opt-in lenient read. The
lenient tests now cover null rows, non-JSON reservation keys and a
non-map ledger root, which still throws.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
(cherry picked from commit a226b3a)
… boundary

skipped counts malformed rows only; the docs now say companion rows are
not counted. Tests pin that a neighbouring or nested tag still fails closed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
(cherry picked from commit be9f782)
…oor; skip companion rows by value shape

Lenient mode dropped a malformed row entirely, so a row like [900, 42, op]
could leave the floor at a lower readable counter and the producer would mint
under it. Count a valid first element even when the row is skipped.

Companion rows are now skipped only when their value has the shape the
applier stores (string for interior_route, [string, string|null, boolean] for
grow_request), so a counter under a companion-looking key is still counted.
The applier stores a grow's widget field as sent, so a grow with a
non-string widget wrote a row the exact-shape check rejected, and the strict
floor became unreadable again after one such connect. Skip a grow_request row
whenever its first element is not a number; a counter-shaped row under that
key is still counted.
@github-actions github-actions Bot added the risk:R1 PR risk grade (advisory shadow check; grader-owned) label Nov 1, 2026
…s root

Applies the accepted Lamport decision D2: with skipMalformed, a
__clock_reservations root that is not a readable map counts as one skipped
entry instead of throwing. Winning counters live in __stamps, whose root
still has to be readable in either mode; the strict read and the clock store
refuse both.
@christian-byrne christian-byrne self-assigned this Nov 1, 2026
@coderabbitai

coderabbitai Bot commented Nov 1, 2026 •

Copy link
Copy Markdown

Review in Change Stack →

Warning

Review limit reached

  • Run on-demand review

This review includes 3 billable files and costs up to $0.75.

  • Ask an admin to make reviews automatic

Open in CodeRabbit

Reviews can continue after your included limit without a manual trigger. An admin must approve usage-based billing.

Or wait 48 minutes for your next included review.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available. Your 105 included PR review attempts over the past 7 days set your current allowance at 1 review per hour.

Learn how review limits work.

Review configuration:

Run configuration
Commits

Reviewing files that changed from the base of the PR and between 682977b and c7a92ab.

Files selected for processing: 3
  • docs/multiplayer-schema.md
  • src/clock.ts
  • test/clock.test.ts

No actionable comments were generated in the recent review.

Recent review info
Run configuration
Commits

Reviewing files that changed from the base of the PR and between 15324fd and 682977b.

Files selected for processing: 8
  • docs/multiplayer-schema.md
  • src/applier.ts
  • src/clock.ts
  • src/doc.ts
  • src/read.ts
  • test/clock.test.ts
  • test/define-subgraph.test.ts
  • test/permutation/full-op-pool.permutation.test.ts

Included review availability: This review used your included allowance. 0 included reviews remain after this review. Your included PR review attempts over the past 7 days set your current allowance at 1 review per hour.

Walkthrough

The change defines tags for counterless grow_request and interior_route rows in __stamps. observedDocCounter skips these rows and adds an opt-in mode that counts malformed rows while returning the maximum readable counter.

Changes: Stamp counter behavior

Layer / File(s) Summary
Companion stamp tags
src/doc.ts, src/applier.ts
The code defines exported tag constants for grow_request and interior_route. The serialized keys use these constants.
Counter read behavior
src/clock.ts, src/read.ts, docs/multiplayer-schema.md, test/clock.test.ts, test/define-subgraph.test.ts, test/permutation/full-op-pool.permutation.test.ts
observedDocCounter skips counterless companion rows. Strict mode remains the default; skipMalformed returns the maximum readable counter and the number of skipped rows. Tests cover malformed rows, retained interior-route stamps, replica counters, and operation groups.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Bug fix

Suggested reviewers: jaeone94

Merge Risk: Minimal · previous review 68297

Companion rows are excluded from counter reads. No merge-blocking issue was identified.

Pre-merge checks: Passed 4 · Failed 1

Failed Failed checks: 1 warning

Check name Status Explanation Resolution
Docstring Coverage Warning Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff with cyclomatic complexity of at least 2. Documentat… Write docstrings for the functions missing them to satisfy the coverage threshold.
Passed Passed checks: 4 passed
Check name Status Explanation
Description Check Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check Passed The title clearly identifies the main changes: reading the Lamport floor past counterless __stamps rows and adding opt-in skipMalformed handling.
Linked Issues check Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check Passed Check skipped because no linked issues were found for this pull request.
Full details: Docstring Coverage

Explanation

Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff with cyclomatic complexity of at least 2. Documentation-only edits and deletions within surviving functions are included; unchanged diff context and fully deleted functions are excluded. Analyzed 3 functions across 7 files. (1 skipped: 1 unsupported.)

Resolution

Write docstrings for the functions missing them to satisfy the coverage threshold.

Finishing Touches
Generate docstrings
  • Commit to this branch
  • Create a new PR
Generate unit tests (beta)
  • Commit to this branch
  • Create a new PR
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

@jaeone94 jaeone94 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM. I checked every __stamps write in the applier: grow_request and interior_route are the only rows that are not stamp tuples, and the permutation sweep now catches any new one. The strict path skips them too, so the doc host stops throwing without opting in. salvageCounter accepts the same range as validateLamportCounter(…, true), so lenient mode can only over-estimate the floor.

Two notes, neither blocking:

  1. Rollout. The patch release that carries this also crosses 0.3.13, which brings #276 (DynamicGroup rows). So the cloud dochost bump inherits the same gate as Comfy-Org/cloud#16862: it waits until Cloud serves the cloud/1.60 frontend line. The PM-2212 fix reaches Cloud then, not right after this merges. It may be simpler to move #16862 to the new version and do one bump.
  2. skipMalformed. Nothing in the package uses lenient mode yet. Is a dochost change planned to opt in and log skipped?

Nit: GROW_REQUEST_TAG and INTERIOR_ROUTE_TAG are appended after widgetStorageOf in the otherwise alphabetical ./doc.js import in applier.ts.

@jaeone94 jaeone94 assigned christian-byrne and unassigned jaeone94 Nov 2, 2026
@christian-byrne
christian-byrne merged commit c879261 into main Nov 5, 2026
8 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

risk:R1 PR risk grade (advisory shadow check; grader-owned)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants