Skip to content
Merged
Show file tree
Hide file tree
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
16 changes: 15 additions & 1 deletion docs/INVARIANTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -126,8 +126,22 @@ abort-remainder, and a real published-0.3.10 mixed-reader projection check.
That last check is the KA-11 basis for no bump: the old reader projects every
state the new writer persists identically.

Amendment A26 also keeps schema v5, on A24's basis rather than A25's. Row
field keys such as `loras.1.lora_name` are reachable only on a node whose
pinned catalog declares `dynamic_groups`, and no catalog did before A26, so
no existing v5 document can contain them. A bump would instead make every
existing v5 document unreadable under the no-compat-reader policy above.
Backward compatibility does not hold under a DynamicGroup catalog: the
published 0.3.10 reader throws on a stored row key and silently drops rows
that hold no stored value. The protection is therefore the catalog pin, and
reader adoption must precede DynamicGroup catalog adoption.
`test/dynamic-group.test.ts` holds both sides against the published reader.
Under a catalog without `dynamic_groups`, the new writer refuses row names
and the old reader projects its documents identically. Under a DynamicGroup
catalog, the old reader is unsafe in both ways.

### KA-12 — Catalog pinned at mint
**Rule:** `meta.catalog_version` cites the catalog by SHA, not branch; reject NAMED widget writes to uncatalogued classes loudly. A subgraph instance's `type` is a definition UUID that no catalog describes, and its promoted widget values are POSITIONAL by frontend contract (ADR 0009), so a promoted host write (schema Amendment A15) is not a widget-name resolution and needs no catalog entry for the instance — it still needs A CATALOG (`catalog_required` without one) to tell an instance from an unseen class, and still refuses (`uncatalogued_widget_write`) to lay a positional array over named values the catalog cannot describe. A node that DECLARES its own ordered widget identity (`widgets_values_form`, schema Amendment A24) is resolved from that declaration. An object form stays catalog-free and closed; under Amendment A25 an array form may additionally accept names owned by the pinned `dynamic_combos` catalog and persists the resulting realized order after the winning selector write. This does not relax the rule: the package uses only mappings supplied by the producer or the immutable catalog, never guesses one. An undeclared node keeps every refusal above, and `meta.catalog_version` still pins the catalog every other node projects against.
**Rule:** `meta.catalog_version` cites the catalog by SHA, not branch; reject NAMED widget writes to uncatalogued classes loudly. A subgraph instance's `type` is a definition UUID that no catalog describes, and its promoted widget values are POSITIONAL by frontend contract (ADR 0009), so a promoted host write (schema Amendment A15) is not a widget-name resolution and needs no catalog entry for the instance — it still needs A CATALOG (`catalog_required` without one) to tell an instance from an unseen class, and still refuses (`uncatalogued_widget_write`) to lay a positional array over named values the catalog cannot describe. A node that DECLARES its own ordered widget identity (`widgets_values_form`, schema Amendment A24) is resolved from that declaration. An object form stays catalog-free and closed; under Amendment A25 an array form may additionally accept names owned by the pinned `dynamic_combos` catalog and persists the resulting realized order after the winning selector write. This does not relax the rule: the package uses only mappings supplied by the producer or the immutable catalog, never guesses one. Amendment A26 adds one validation exception: supplied `dynamic_groups` metadata identifies count fields for row-count bound checks and refuses a count change that would invalidate the declaration, using the addressed occurrence's current value. The declaration still owns ordering; the catalog does not replace it. Without that metadata, the package cannot identify a count field, so callers must enforce compatible producer, catalog, and reader adoption. An undeclared node keeps every refusal above, and `meta.catalog_version` still pins the catalog every other node projects against.
**Why:** Replay semantics must not drift with a moving vocabulary.
**Enforced by:** `test/roundtrip.test.ts`, `test/catalog-sha-binding-integration.test.ts`, `test/node-local-widget-form.test.ts` (A24's catalog-free object path, and that an undeclared node still takes the catalogued one), `test/node-local-order-overlay.test.ts` (A25's pinned dynamic overlay), [`catalog-pinning`](../.agents/checks/catalog-pinning.md), [ADR-003](decisions/ADR-003-catalog-sha-at-mint.md), and — for the *citations* rather than `meta.catalog_version` itself — `scripts/check-pins.mjs` (`npm run check:pins`) with `docs/upstream-pins.json` and `test/upstream-pins.test.ts`. `test/doc-mint-mutation-survivors.test.ts` additionally pins that an imported workflow cannot forge `catalog_version`/`schema_version` or any `__`-prefixed meta key, and that an unpinned mint records an EMPTY catalog version rather than a plausible-looking default (FC-10). The rule's second clause is narrower than it looks: **`meta.catalog_version` is still UNGUARDED at the write sites — see roadmap.** Neither `mint()` nor `initDoc()` rejects a branch-shaped catalog version; only the citations are linted.

Expand Down
1 change: 1 addition & 0 deletions docs/decisions/EXCEPTIONS.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,3 +24,4 @@ is retained as history, not authorization to accept unprojectable writes.
| ~~2026-09-22 (APPROVED)~~ **AMENDED AND APPROVED 2026-09-23** | KA-5 | ~~`insert_workflow`'s numeric link-id mint consulted mutable document state (a document-verified retry), unlike every other id this op derives.~~ Christian Byrne's review of that design (PR #245, inline on `src/remap.ts:65`) found it made link identity depend on LOCAL ARRIVAL ORDER — two replicas applying the same concurrent op set in opposite orders could project different link ids for the same logical links, the exact class of bug KA-4/KA-2 exist to rule out — and asked for either a fix plus explicit ratification, or a return to pure derivation. **This row now describes the amended design: `derivedLinkId` mints PURELY from the op's own content (`opId`, `scope`, the raw link), with NO document read, no caller-supplied reservation, and no retry.** It spends the FULL safe-integer range (`[1, Number.MAX_SAFE_INTEGER]`, 53 bits, widened from the original's 52-bit window) rather than checking for a collision. ComfyUI_frontend's `LinkId` (a branded `number`, unlike the string-or-number `NodeId`) is still why a link needs a numeric mint at all — ADR-031's pure STRING scheme still can't satisfy it — but the mint no longer tries to guarantee collision-freedom against the document; it accepts a quantified residual risk instead. Residual probability: two independently derived 53-bit candidates collide with probability `1/(2^53-1) ≈ 1.11×10⁻¹⁶` per pair; for `k` links minted into one document the birthday-bound chance ANY two collide is `≈ k²/2^54` — about `2.2×10⁻¹²` at `k=200` (this package's own scale test), about `5.5×10⁻⁵` even at an unrealistic `k=1,000,000` — the same order of "cosmically unlikely, not impossible" risk this package already accepts for UUID4 `op_id` collisions (KA-2). A REALIZED collision is not specially detected: it is caught by `applier.ts`'s pre-existing `acceptsLink`/`seenLinks` apply-time id-collision handling (the same ordinary, order-independent LWW-gated 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 — this check is REACHABLE via realistic input now (not merely via deliberate id-space exhaustion, since there is no more exhaustion to construct). **Separately, a pre-existing, unresolved gap** (out of scope for this amendment): a `connect` op's client-minted `link_id` can collide with an `insert_workflow`-derived numeric id, and `applier.ts`'s `claimLinkIdentity` does not guard against it at all, silently overwriting the `insert_workflow` link when `connect` arrives second — this predates and is unaffected by this amendment either way (the removed retry only ever protected the OPPOSITE arrival order, and only when the `connect` had already landed on that replica). See ADR-033's "Amendment (2026-09-23)" section for the full writeup, including this cross-mechanism note. | `src/remap.ts` `derivedLinkId`; `src/applier.ts` `prepareInsertedWorkflow`, `acceptsLink`, `claimLinkIdentity`; ADR-033 | Owner: Christian Byrne. The amended pure-derivation design was ratified after exact-head review confirmed that the document-state retry was removed, opposite-order convergence coverage was added, and realized collisions remain loud and byte-identical. Sunset (unchanged from the original row): revisit only if ComfyUI_frontend widens `LinkId` to `string \| number` (matching `NodeId`), at which point ADR-031's string form becomes sufficient for links too and this exception can be retired outright. |
| 2026-10-03 (PROPOSED) | KA-5 | **`insert_workflow` derives numeric group ids by the same pure 53-bit hash as KA-5's link ids, and accepts the same residual collision risk** (PR #264). ComfyUI_frontend's workflow schema declares `groups[].id` as `z.number()` (root and `definitions.subgraphs[].groups`) and refuses the whole workflow on a string, so the string `derivedId` groups used to carry made inserted workflows unloadable. `derivedGroupId` folds `insert:<opId>:<scope>:group:<original>` into `[1, Number.MAX_SAFE_INTEGER]` from the op's own content only (no document read, no retry), so replicas converge regardless of arrival order. Residual probability is the KA-5 row's: `≈ k²/2^54` for `k` groups in one document. **Unlike links, a realized group-id collision is NOT detected**: `applier.ts` merges groups by canonical JSON, not by id, so two distinct groups sharing an id both stay in the document and project with the same id; the frontend's behaviour on duplicate group ids is unverified. `project.ts` coerces a stored string group id to a number ONLY when it matches the derived form (`DERIVED_GROUP_ID`), so a workflow's own string group id round-trips `project(mint(wf))` unchanged and still fails the frontend schema exactly as it would without this package. | `src/remap.ts` `derivedGroupId`, `numericId`; `src/project.ts` `projectGroups`, `DERIVED_GROUP_ID`; `test/insert-workflow-numeric-group-ids.regression.test.ts` | Owner and approval: maintainer's to assign (proposed for Christian Byrne, who reviewed #264). Sunset: revisit if ComfyUI_frontend widens a group's `id` to `string \| number`, at which point the string `derivedId` suffices and this exception can be retired; add id-level collision detection to the groups merge before then if duplicate ids prove harmful on the canvas. |
| 2026-10-04 (PROPOSED; amended 2026-10-20 by schema A25) | FC-10 | **`widgets_values_form` is a package-local, provisional workflow FIELD** (schema Amendment A24), because the pinned catalog is per-class while the two shapes that need describing are per-instance: a node with two same-named serializable widgets, and a node whose custom serializer emits an object whose non-widget keys must survive a widget write. Neither is derivable from the end state, so the producer declares its instance's ordered widget identity and this package decomposes, addresses and projects through that declaration. comfy-cli's frozen `op-vocabulary-v1.md` does not define the field, so the deviation is from FC-10's cite-the-pinned-vocabulary rule rather than from KA-12 (a declaration is the name-to-position mapping, supplied by the party that knows it, not a guess at one). Bounded deliberately: ONE declared key, closed to `{order}` and refused rather than ignored when malformed; every other part of the form is derived; an undeclared node keeps the catalog path and all of its existing refusals. **A25's only composition is for ARRAY forms:** `order` is the realized producer order, any pinned dynamic-combo option child is legal independent of selection, and a winning selector replaces only catalog-owned dynamic children in that same stored order; OBJECT/custom-serializer forms remain closed. `SCHEMA_VERSION` stays 5 because `test/node-local-order-overlay.test.ts` proves the real published 0.3.10 reader projects every state the new writer persists identically. **Two residuals, both stated rather than discovered later:** `insert_workflow` strips every `__`-prefixed key at every depth (`prepareInsertedWorkflow` / `scrubPrivateKeys`, a pre-existing anti-forgery guard), so a serializer's own `__`-prefixed data key inside `widgets_values` does not survive THAT path — pinned by test rather than papered over; and the §8.3 autogrow `inputcount` bump still writes the `widgets` map directly and consults no declared order, which is A23's pre-existing gap one op over. | `src/widget-form.ts`; `src/dynamic-combos.ts` `widgetOrderForProducerOrder`; `src/doc.ts` `widgetStorageFor`/`widgetStorageOf`/`storeWidgetValues`; `src/project.ts` `projectWidgets`; `src/applier.ts` `validateWidgetName`/`writeWidgetValue`/`rejectIfOpaqueWidgets`/`hostWriteStorage`/`createAddedNode`/`rejectUnprojectableWidgets`; `src/read.ts`; `fixtures/golden-vectors/wire-layout.json`; `fixtures/golden-vectors/node-local-order-overlay.json`; `test/node-local-widget-form.test.ts`; `test/node-local-order-overlay.test.ts`; schema Amendments A24/A25 | Owner and approval: maintainer's to assign (FE-3036's owner). Sunset: amend comfy-cli's frozen vocabulary to define the field and pin the adopted definition here, reconciling the name and shape if upstream differs; retire outright if the catalog acquisition ever becomes per-instance, at which point the declaration becomes redundant rather than merely unneeded. |
| 2026-10-11 (PROPOSED) | KA-12 | A26 uses supplied DynamicGroup metadata to validate count writes even on an A24 self-described node. Name/occurrence resolution and projection still use the producer declaration; metadata only checks row-count bounds and refuses changing the addressed occurrence's count without an updated form. Metadata omission cannot identify a controller and remains a caller admission concern. | `src/applier.ts` `validateDynamicGroupValue`; `test/dynamic-group.test.ts`; schema Amendments A24/A26 | Owner and approval: maintainer's to assign. Reconcile when count safety becomes part of the producer declaration. |
Loading
Loading