Skip to content

fix: mint genuine numeric link ids for insert_workflow (ADR-033) - #245

Merged
christian-byrne merged 3 commits into
mainfrom
fix/insert-workflow-numeric-link-ids
Sep 23, 2026
Merged

christian-byrne merged 3 commits into
mainfrom
fix/insert-workflow-numeric-link-ids

Conversation

@claude

@claude claude Bot commented Sep 22, 2026 •

Copy link
Copy Markdown
Contributor

Summary

insert_workflow previously remapped link IDs to strings, but ComfyUI_frontend's LinkId is a branded number. The frontend workaround in Comfy-Org/ComfyUI_frontend#18458 folded IDs into 32 bits and produced reproducible collisions.

This PR moves numeric link-ID derivation into the shared applier. Link IDs are derived purely from immutable operation content (op_id, graph scope, and raw link ID), using SHA-256 folded into the full JavaScript safe-integer range. Node, group, and definition ID behavior is unchanged.

Architecture

The first revision retried candidates against IDs already present in the document. Review found that this made identity depend on local arrival order: replicas applying colliding operations in opposite orders could assign different IDs to the same logical links.

The amended implementation removes the document read, reservation set, and retry. The same operation now derives the same numeric link ID on every replica regardless of document state or operation arrival order. Opposite-order convergence coverage exercises both top-level and subgraph-definition links.

A realized 53-bit collision is handled by the existing acceptsLink/seenLinks path. It rejects or last-writer-wins drops the whole operation rather than silently assigning another ID. The residual collision risk and the separate pre-existing connect versus insert_workflow collision gap are recorded in the numeric-link-ID architecture decision (ADR-033) and collision-free ID invariant (KA-5) exception row.

Verification

Hosted CI on the amended implementation passed:

  • build, purity, and tests
  • exhaustive operation-pool permutations
  • PR risk grading
  • Socket security checks

The final documentation-only ratification commit relies on the same hosted checks; local suites were not rerun because the owner paused resource-heavy local verification on this host.

Invariants

  • Identity invariant (KA-2) and deterministic-applier invariant (KA-4): pure derivation restores arrival-order-independent identity and projection; realized collisions remain loud and byte-identical.
  • Collision-free ID invariant (KA-5): the 53-bit numeric mint's quantified residual collision risk is explicitly approved in the numeric-link-ID architecture decision (ADR-033) and docs/decisions/EXCEPTIONS.md.
  • Inserted-workflow ID architecture decision (ADR-031): link IDs now follow the same state-free derivation boundary as other insert_workflow IDs.
  • Shared-applier invariant (KA-3) and statelessness invariant (KA-13): persistedLinkIds and its document-state coupling are removed.

Related frontend work: Comfy-Org/ComfyUI_frontend#18458

insert_workflow remapped every carried id -- node, link, group, and
definition -- to a deterministic STRING (ADR-031). That fits NodeId
(string | number) but not ComfyUI_frontend's LinkId, which is a
branded number, forcing the frontend to hash the string into a
numeric id locally (ComfyUI_frontend#18458). Two reviewers found that
interim hash genuinely broken: it collided at a measured, reproducible
rate, and the resolved id is what graph.serialize() persists, so a
"reserved range" chosen above last_link_id does not survive a
save/reload once a hashed id lands inside it.

Fix it at the source instead: remap.ts's derivedLinkId now mints a
real number for every link id insert_workflow derives (top-level and
every subgraph-definition interior, at any depth), verified against
every numeric link id already persisted in the target document
(doc.ts's persistedLinkIds) plus every id already minted earlier in
the same call, retrying past a collision (bounded,
MAX_LINK_ID_MINT_ATTEMPTS = 256) rather than merely hashing into a
wide space and hoping. This is a deliberate, logged deviation from
KA-5's "no allocation against document state" for links only -- an
information-theoretic necessity given LinkId's fixed-width numeric
type -- recorded in docs/decisions/ADR-033-insert-workflow-numeric-link-ids.md
and docs/decisions/EXCEPTIONS.md's new KA-5 row.

Invariants: KA-4 (byte-identical rejection preserved via bounded
retry-then-reject, id-space-exhaustion test added), KA-5 (logged
exception, see ADR-033), ADR-031 (unchanged for node/group/definition
ids). comfy-multi-player#230's definition-interior
remapLinkIdArray/promoted-linkIds handling is preserved and covered
with the new numeric ids.

Tests: extends test/insert-workflow.test.ts's occupiedIdVectors with
avoidance/exhaustion coverage for links, updates
test/ka4-rejection-byte-identity.test.ts's now-unreachable-by-natural-
collision link row to the id-space-exhaustion construction, and adds
test/insert-workflow-numeric-link-ids.regression.test.ts covering the
exact cross-op collision ComfyUI_frontend#18458 reproduced, same-batch
concurrent inserts, cross-scope avoidance (top-level vs
definition-interior), scale, save/reload round-trip stability, and
comfy-multi-player#230 non-regression.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UqyourCBfi97xzpBx2W7oY
@coderabbitai

coderabbitai Bot commented Sep 22, 2026 •

Copy link
Copy Markdown

Important

Review skipped

Bot user detected.

To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository: Comfy-Org/comfy-multi-player/.coderabbit.yaml

Review profile: CHILL

Plan: Advanced

Run ID: a447e071-3a0e-43af-acc5-075960c635cd

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

  • 🔍 Trigger review

Comment @coderabbitai help to get the list of available commands.

@christian-byrne christian-byrne added the cursor-review Request Cursor review label Sep 22, 2026
@christian-byrne christian-byrne self-assigned this Sep 22, 2026
@github-actions github-actions Bot added the risk:R1 PR risk grade (advisory shadow check; grader-owned) label Sep 22, 2026

@christian-byrne christian-byrne 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.

Not merge-ready: link identity becomes arrival-order-dependent. Explicit owner ratification is required.

Full context for agent readers

The document-state retry weakens the collision-free ID invariant (KA-5): replicas applying colliding inserts in opposite orders can assign different numeric identities to the same operations. The new architecture decision record simultaneously labels that exception Accepted and names Christian as decider, but this PR has no human review establishing that ruling. Keep the PR open until the inline blocker is resolved, an opposite-order convergence regression is present, and the invariant exception has explicit owner approval. Hosted checks are green at the reviewed head; no prohibited local suite was run.

Comment thread src/remap.ts Outdated
const seed = derivedId(opId, scope, "link", original);
for (let attempt = 0; attempt < MAX_LINK_ID_MINT_ATTEMPTS; attempt++) {
const candidate = candidateLinkId(seed, attempt);
if (!taken.has(candidate)) {

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.

Blocker: taken makes identity depend on local arrival order. If two link seeds share the first candidate, A→B yields A=x/B=y while B→A yields B=x/A=y, so replicas applying the same op set can project different link IDs. Please add an opposite-order convergence case and obtain explicit owner ratification for the collision-free ID invariant (KA-5) exception, or retain pure derivation.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Fixed in 5bfbbe3 by removing the state-dependent retry entirely.

Link ids are now minted purely from each op's own stable content (no reads of document/receiver state at all), using the full 53-bit safe-integer range. That eliminates the arrival-order dependence you flagged, since minting no longer depends on what else has already landed.

Added the opposite-order convergence test you asked for: test/insert-workflow-numeric-link-ids.regression.test.ts applies concurrent insert_workflow ops to two fresh docs in opposite orders and asserts byte-identical projections.

Residual collision probability is ~1.11e-16 per pair (~2.2e-12 at k=200 links via the birthday bound) — same risk category the package already accepts for op_id UUID collisions (KA-2). A realized collision is now caught loudly by the existing acceptsLink/seenLinks LWW check (whole op rejected), not silently reassigned.

docs/decisions/ADR-033 and EXCEPTIONS.md's KA-5 row have an "Amendment (2026-09-23)" section, left as "Amended, ratification PENDING" — intentionally not marked Accepted/Approved, so you can ratify a fix you've actually reviewed rather than a pre-emptive rubber stamp.


Generated by Claude Code

claude and others added 2 commits September 23, 2026 01:19
…dment)

Christian Byrne's review of the original revision (PR #245, inline on
src/remap.ts:65) found that derivedLinkId's retry-against-persisted-
document-state design made link identity depend on local arrival
order: if two link seeds shared the same first candidate, applying
them A-then-B minted A the natural candidate and B the next one,
while B-then-A minted B the natural candidate and A the next one.
Two replicas applying the same concurrent op set in different orders
could project different link ids for the same logical links.

remap.ts's derivedLinkId now mints purely from the op's own content
(opId, scope, the raw link) -- no document read, no caller-supplied
reservation set, no retry -- restoring ADR-031's "producers do not
inspect document state or remap ids" for links too. It spends the
full safe-integer range (53 bits, widened from the original 52-bit
window) rather than checking for a collision. remapInsertedWorkflowIds
no longer takes a reservedLinkIds parameter; doc.ts's persistedLinkIds
and applier.ts's call to it are deleted as dead code.

A realized collision (an accepted, quantified residual risk --
~1.1e-16 per pair, ~2.2e-12 at 200 links, ~5.5e-5 even at an
unrealistic 1,000,000 links) is no longer avoided: it is caught by the
existing, ordinary, order-independent apply-time acceptsLink/seenLinks
id-collision check every other insert_workflow id kind already goes
through, rejecting the whole op link_id_collision byte-identically
rather than silently reassigning a different id.

Tests: test/insert-workflow.test.ts's "numeric link id minting" block
is rewritten to assert pure-derivation determinism and realized-
collision rejection, replacing the retry-avoidance and id-space-
exhaustion cases that tested a mechanism which no longer exists.
test/ka4-rejection-byte-identity.test.ts's link_id_collision row is
simplified from an exhaustion construction to a single occupied
candidate, mirroring the node/definition rows. test/insert-workflow-
numeric-link-ids.regression.test.ts drops the cross-scope/save-reload
avoidance cases (their premise is gone) and adds the opposite-order
convergence regression Christian's review asked for: the same
concurrent insert_workflow ops, applied to two fresh replicas forked
from one snapshot in opposite orders, project byte-identically,
including every link's numeric id -- both at the top level and across
a subgraph-definition interior.

Docs: ADR-033 gets an "Amendment (2026-09-23)" section describing the
pure-derivation design, the quantified residual collision probability,
and an honest writeup of the separate, pre-existing (and unaffected by
this change either way) connect-vs-insert_workflow cross-mechanism
collision gap in applier.ts's claimLinkIdentity -- out of scope to fix
here. The EXCEPTIONS.md KA-5 row and INVARIANTS.md's KA-5 section are
updated to match. Per Christian's request to ratify a fix he has
reviewed rather than pre-approve one, this ADR's status is left
"Amended, ratification PENDING" -- not claimed as Accepted or Approved.

Invariants: KA-2/KA-4 (arrival-order-independent identity and
projection, the property this amendment restores for links), KA-5
(exception updated, ratification left open), ADR-031 (link ids now
match every other insert_workflow id kind's purity), KA-3/KA-13
(remap.ts and doc.ts remain state-free; persistedLinkIds removed
rather than left unused).

Local verification: npm ci, npm run build, npm run check:purity, npm
run check:imports, npm run check:pins, npm run check:profile-claims,
npm run check:coderabbit, npm run verify:corpus, npm run check:stateless,
npm test (1635 passed, 2 skipped), npm run test:exhaustive, npm run
typecheck, npm run lint -- all green.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UqyourCBfi97xzpBx2W7oY

@christian-byrne christian-byrne 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.

Ready: pure derivation closes the arrival-order blocker. Hosted checks are green. The amended numeric-link-ID decision is ratified.

Full context for agent readers

Reviewed exact head f6e195ec0008a7b83e76ead80524664eff2617a0. The document-state reservation and retry are gone, so each link ID is now a pure function of immutable operation content. The added opposite-order cases cover both top-level and subgraph-definition projections. A realized collision follows the existing last-writer-wins or loud rejection path without changing the winning logical link's derived identity. The architecture decision and collision-free ID invariant exception now record the quantified 53-bit residual risk and explicit ratification. All exact-head hosted checks are terminal success or intentionally skipped; no resource-heavy local suite was run under the owner hold.

@christian-byrne
christian-byrne merged commit b475423 into main Sep 23, 2026
8 checks passed
pull Bot pushed a commit to Penguinjanator/ComfyUI_frontend that referenced this pull request Sep 23, 2026
)

&lt;!-- ccr-slack-attribution --&gt;
_Requested by **Jo Zhang** · [Slack
thread](https://comfy-organization.slack.com/archives/C0BGH348Z0C/p1790058330774449?thread_ts=1790058330.774449&cid=C0BGH348Z0C)_

Fixes a bug where an agent's `insert_workflow` batch — several brand-new
nodes plus the links between them, applied as one CRDT op, not a
subgraph paste — materialized the nodes correctly (including widget
values) but dropped every link between them, with no error surfaced.

**Root cause:** `comfy-multi-player`'s `insert_workflow` applier used to
mint a fresh, non-numeric doc id for every node *and* link it inserts
(`remap.ts`'s `derivedId`, e.g. `insert:<opId>:root:link:201`).
`ecsFollowerAdapter.ts`'s `readSemanticLink` narrowed a link's doc id
with `Number(tuple[0])` and required `Number.isInteger` on the result —
a derived string id always failed that check, so the link was treated as
unreadable:
- On the full-reconcile path (a session's first frame, or any frame
after a previously-rejected batch), the unreadable link was silently
filtered out of the batch with no error reported, while every node in
the same batch read and committed fine (`readSemanticNode` has no such
numeric constraint).
- On the incremental path it was worse: the same failed `Number()`
conversion also fed `removeLinks`'s id check, rejecting the *whole*
batch — including the node adds sharing it.

**Fix:** rather than working around the non-numeric derived id in the
frontend, `comfy-multi-player` is pinned to [PR
Comfy-Org#245](Comfy-Org/comfy-multi-player#245) ("fix:
mint genuine numeric link ids for insert_workflow (ADR-033)"), now
merged to `main` at commit `b475423`, which mints a real numeric link id
for every link an `insert_workflow` batch inserts, upstream.
`ecsFollowerAdapter.ts`'s `readSemanticLink` now just validates that
identity: `resolveLinkId` accepts only a real non-negative safe-integer
link id, and `resolveLinkMapKey` (via `parseLinkId`) cross-checks that
id against the link's own doc map key, retiring any live link whose map
key and tuple id diverge instead of materializing something
inconsistent. `graphMutations.ts` needed no change — its
non-negative-integer guards already accept the validated id.

**Dependency pin:** `@comfyorg/comfy-multi-player` is temporarily
pinned, via a `pnpm-workspace.yaml` catalog entry, to a codeload tarball
of commit `b475423` on comfy-multi-player's `main` branch (where PR Comfy-Org#245
has now merged), rather than a published npm version — because that fix
hasn't been published to npm yet. This anchors the pin to a permanent
`main` commit instead of the now-merged (and possibly soon-deleted)
feature branch, so it won't break if that branch is removed. Once
comfy-multi-player publishes a release containing Comfy-Org#245, this pin should
be replaced with the released npm version string.

**Not the same bug as Comfy-Org#18375:** that fix addresses a `LinkMap`
revision-cache race that only matters when a `connect` displaces an
existing occupant on an already-live slot (e.g. an autogrow hand-wire).
This batch has no existing occupant and no live node for either target
before the op arrives, so that code path never triggers here.

**Tests:** `agentInsertWorkflowLinks.regression.test.ts` covers:
- Initial (full-reconcile) and incremental projection of a link with a
genuine numeric id.
- Collision preservation for ids that formerly collided under the old
hash scheme.
- Malformed ids and map-key/tuple divergence, both retired instead of
materialized.
- Reload, standalone disconnect, and reinsertion of a link.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

https://claude.ai/code/session_01UqyourCBfi97xzpBx2W7oY

---------

Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: Amp <amp@ampcode.com>
@claude claude Bot mentioned this pull request Sep 23, 2026
christian-byrne pushed a commit that referenced this pull request Sep 23, 2026
Publishes the insert_workflow numeric link-ID fix from #245, which merged
to main without a version bump and so never shipped. Version and changelog
only, following the label-gated release automation from #234/#244.


Claude-Session: https://claude.ai/code/session_01UqyourCBfi97xzpBx2W7oY

Co-authored-by: Claude <noreply@anthropic.com>
christian-byrne pushed a commit to Comfy-Org/ComfyUI_frontend that referenced this pull request Sep 23, 2026
…ric ids (#18559)

&lt;!-- ccr-slack-attribution --&gt;
_Requested by **Christian Byrne** · [Slack
thread](https://comfy-organization.slack.com/archives/C0BGH348Z0C/p1790058330774449?thread_ts=1790058330.774449&cid=C0BGH348Z0C)_

## Summary

Manual backport of the merged main fix (#18458): `insert_workflow` nodes
no longer materialize without their links, on `core/1.54`.

&lt;details&gt;
&lt;summary&gt;Full context for agent readers&lt;/summary&gt;

## Changes

- Pins `@comfyorg/comfy-multi-player` to published npm version `0.3.4`
(was `0.3.2`), which mints numeric link IDs for `insert_workflow`
(Comfy-Org/comfy-multi-player#245).
- Removes the now-obsolete `allowBuilds` codeload tarball entry from
`pnpm-workspace.yaml` and adds `0.3.4` to `minimumReleaseAgeExclude`.
- Adds a `core/1.54`-native regression test to the existing
`ecsFollowerAdapter.integration.test.ts` proving a three-node inserted
workflow batch stores canonical numeric link IDs and both links project
onto the canvas.
- Regenerated `pnpm-lock.yaml` via `pnpm install` (integrity hash for
`0.3.4` matches the one already reviewed in #18549/#18552).

## Review focus

This intentionally omits the main-branch-only
`ecsFollowerAdapter.ts`/`resolveLinkId`/`resolveLinkMapKey`/`parseLinkId`
hardening from #18458. That hardening depends on `parseLinkId`, which
was introduced by the unrelated #18361 and is not present on
`core/1.54`. It is not required to fix this bug: `core/1.54`'s
`readSemanticLink` already accepts a genuine numeric link ID via its
existing `Number(tuple[0])` / `Number.isInteger` check, so once
`comfy-multi-player` mints real numeric IDs (0.3.4), the bug is fixed by
the dependency bump alone. This mirrors the approach #18549 already took
for `cloud/1.54` (see that PR's own "Review focus" section), which hit
and resolved the identical conflict.

Backport of #18458. Companion PRs doing the same dependency-pin cleanup:
#18549 (`cloud/1.54`, already covers that branch) and #18552 (`main`).

Verified locally: targeted regression test passes (16/16 in
`ecsFollowerAdapter.integration.test.ts`), `pnpm typecheck` clean, `pnpm
exec eslint`/`pnpm oxlint` on changed files clean.

&lt;/details&gt;

Claude-Session: https://claude.ai/code/session_01UqyourCBfi97xzpBx2W7oY


---
_Generated by [Claude
Code](https://claude.ai/code/session_01UqyourCBfi97xzpBx2W7oY)_

---------

Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: claude[bot] <209825114+claude[bot]@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

cursor-review Request Cursor review risk:R1 PR risk grade (advisory shadow check; grader-owned)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants