Skip to content
Closed
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
5 changes: 5 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -380,6 +380,11 @@ ADR-032 and schema Amendment A21.
| `delete_node` | `node_id`, `removed_links` | yes |
| `clear` | `removed_nodes` | no |
| `insert_workflow` | `workflow` containing required raw-ID `nodes` plus optional `links`, `groups`, and `definitions`; the applier remaps IDs deterministically from `op_id` | no |
| `dynamic_group_insert_rows` | Row owner/lifetime/group, immutable anchor, complete field values; row IDs derive from op ID and ordinal. Provisional schema-v7 extension | yes |
| `dynamic_group_set_row` | Row owner/lifetime/group/ID and field values; optional promoted host address. Provisional schema-v7 extension | yes |
| `dynamic_group_delete_rows` | Row owner/lifetime/group and row IDs, delete-wins. Provisional schema-v7 extension | yes |
| `dynamic_group_connect` | Row/field address, source output, link identity and input/link types. Provisional schema-v7 extension | yes |
| `dynamic_group_disconnect` | Row/field address. Provisional schema-v7 extension | yes |
| `reset_doc` | see [open questions](docs/api-contract-proposal.md) — currently rejected `op_deferred` by this package | no |

`FROZEN_OPS`, `DEFERRED_OPS`, and `BATCHABLE_OPS` are exported so you can check
Expand Down
4 changes: 3 additions & 1 deletion docs/INVARIANTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ This is the machine-addressable review log for the package. IDs are stable; do n
**Rule:** Applier, projection, and mint have zero DOM/framework/LiteGraph/server-only dependencies and run identically in browser and host; assert `yjs`-only directly, not merely by denylist.
**Why:** A peer, edge, browser, and Node host must execute one implementation identically.
Schema v3 added the first-class `__link_state` root; v4 adds `__clock_reservations`, keeping `__stamps` limited to winning write-target stamps. Private alpha has no compatibility reader: old layouts are re-minted, while `migrate()` refuses to relabel them.
**Enforced by:** `scripts/check-purity.mjs` (package level), `scripts/check-import-graph.mjs` + `.dependency-cruiser.cjs` rule `src-runtime-dep-is-yjs-only` (module-graph level, per source module), `test/purity.test.ts`, `test/parity.test.ts`, and [`purity`](../.agents/checks/purity.md). Cross-language implementations must pass the canonical golden vectors in `fixtures/golden-vectors/`. The current schema §1 root-map NAMES (`nodes`, `links`, `definitions`, `meta`, `__applied`, `__stamps`, `__link_state`, `__clock_reservations`) and the reserved per-node `__widgets_opaque`, `__incarnation` and (Amendment A24) `__widgets_form` keys are the shared wire layout. Before schema v3 added `__link_state`, the historical inventory was seven names: six roots plus that reserved widget key. Those seven were pinned by name in `test/doc-mint-mutation-survivors.test.ts`; every other reader in this package went through `nodesMap()`/`linksMap()`/… , so a consistent rename was invisible to most of the suite: measured one key at a time against the pre-existing tests, renaming `links`, `definitions`, `__applied` or `__stamps` left 277/277 green, while `nodes` reddened 2 and `meta` reddened 6. Four of those historical seven names had no holder at all before this file. The current nine names are additionally published as the language-agnostic vector `fixtures/golden-vectors/wire-layout.json` and held against the ENCODED bootstrap snapshot, against a replica that has only those bytes, and against this file and schema §1, by `test/wire-layout-contract.test.ts` — so a rename must move code, vector and both documents together, which is what makes a deliberate one visible in review. **Scoped, because the wording invites the wider reading:** that test does NOT force the `SCHEMA_VERSION` bump or the old-layout disposition KA-11 and schema §1/§10 require of a layout change. Its last case checks only that the three declarations of `SCHEMA_VERSION` agree with each other, and a rename applied consistently to all four places leaves them agreeing at 1 — measured, with that file fully green. The bump obligation is **UNGUARDED — see roadmap**; only its consistency once taken is held.
**Enforced by:** `scripts/check-purity.mjs` (package level), `scripts/check-import-graph.mjs` + `.dependency-cruiser.cjs` rule `src-runtime-dep-is-yjs-only` (module-graph level, per source module), `test/purity.test.ts`, `test/parity.test.ts`, and [`purity`](../.agents/checks/purity.md). Cross-language implementations must pass the canonical golden vectors in `fixtures/golden-vectors/`. The current schema §1 root-map NAMES (`nodes`, `links`, `definitions`, `meta`, `__applied`, `__stamps`, `__link_state`, `__clock_reservations`) and the reserved per-node `__widgets_opaque`, `__incarnation` and (Amendment A24) `__widgets_form`, (Amendment A27) `__dynamic_group_state` node keys and `__dynamic_group_slot` input marker are the shared wire layout. Before schema v3 added `__link_state`, the historical inventory was seven names: six roots plus that reserved widget key. Those seven were pinned by name in `test/doc-mint-mutation-survivors.test.ts`; every other reader in this package went through `nodesMap()`/`linksMap()`/… , so a consistent rename was invisible to most of the suite: measured one key at a time against the pre-existing tests, renaming `links`, `definitions`, `__applied` or `__stamps` left 277/277 green, while `nodes` reddened 2 and `meta` reddened 6. Four of those historical seven names had no holder at all before this file. The current nine names are additionally published as the language-agnostic vector `fixtures/golden-vectors/wire-layout.json` and held against the ENCODED bootstrap snapshot, against a replica that has only those bytes, and against this file and schema §1, by `test/wire-layout-contract.test.ts` — so a rename must move code, vector and both documents together, which is what makes a deliberate one visible in review. **Scoped, because the wording invites the wider reading:** that test does NOT force the `SCHEMA_VERSION` bump or the old-layout disposition KA-11 and schema §1/§10 require of a layout change. Its last case checks only that the three declarations of `SCHEMA_VERSION` agree with each other, and a rename applied consistently to all four places leaves them agreeing at 1 — measured, with that file fully green. The bump obligation is **UNGUARDED — see roadmap**; only its consistency once taken is held.

### KA-4 — The applier is deterministic and idempotent
**Rule:** Same op-set + causal order gives the same projection; an identical duplicate `op_id` is a true no-op with byte-identical `encodeStateAsUpdate`, while reuse with a different canonical payload is rejected without mutation.
Expand Down Expand Up @@ -115,6 +115,8 @@ the pins move in one coordinated step.

Schema v6 adds validated producer-owned DynamicGroup row IDs in node properties (schema A26). Earlier readers could resize a tagged group without updating those IDs, so v1–v5 documents are refused and re-minted from source. Reader/document-host adoption and FE sign-off remain release prerequisites.

Schema v7 adds private atomic row registers and stable row link destinations (schema A27). A v6 reader cannot project them; v1–v6 layouts remain refused. `test/atomic-dynamic-group-rows.test.ts` holds stable addressing, exact retry bytes, row wire keys and opposite-order row replay. Reader/host adoption and FE sign-off remain required before rollout.

### 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) resolves names and occurrences from that declaration without a catalog mapping. A25 makes one validation exception: supplied `dynamic_groups` metadata identifies count fields for allocation-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.
Expand Down
2 changes: 2 additions & 0 deletions docs/decisions/EXCEPTIONS.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,3 +26,5 @@ is retained as history, not authorization to accept unprojectable writes.
| 2026-10-04 (PROPOSED) | 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 with no catalog lookup. 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; `SCHEMA_VERSION` is unchanged on A2's precedent and under A2's exact condition. **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/doc.ts` `widgetStorageFor`/`widgetStorageOf`/`storeWidgetValues`; `src/project.ts` `projectWidgets`; `src/applier.ts` `validateWidgetName`/`rejectIfOpaqueWidgets`/`hostWriteStorage`/`createAddedNode`/`rejectUnprojectableWidgets`; `src/read.ts`; `fixtures/golden-vectors/wire-layout.json`; `test/node-local-widget-form.test.ts`; schema Amendment A24 | 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 | A25 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 allocation 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/A25 | Owner and approval: maintainer's to assign. Reconcile when count safety becomes part of the producer declaration or atomic row-operation protocol. |
| 2026-10-11 (PROPOSED) | FC-10 / KA-12 | A26's `properties.dynamicGroupRows` is a package-local draft field, not part of the frozen vocabulary. It preserves producer-owned IDs and requires supplied catalog group metadata for membership/allocation validation, including on self-described nodes; widget mapping still follows the declaration. Schema v6 fences older writers, and tagged scalar resize is refused until an atomic row protocol exists. | `src/dynamic-group-rows.ts`; `src/doc.ts`; `src/read.ts`; `src/applier.ts`; schema Amendment A26 | Owner and approval: maintainer's to assign. Sunset: adopt and pin the reviewed row-operation/producer contract, reconciling the field and schema before enabling writers. |

| 2026-10-11 (PROPOSED) | FC-10 / KA-12 | A27 adds five package-local DynamicGroup row operations and schema-v7 private registers/link destinations. They are not in the pinned upstream vocabulary. Tagged rows require a supplied compatible group catalog and stable-ID operations; writer min/max admission is separate from receiver replay. The draft implements the requested full row-editing contract without enabling producers or claiming consumer sign-off. | `src/dynamic-row-state.ts`, `src/dynamic-row-ops.ts`, `src/dynamic-row-topology.ts`, `src/applier.ts`; schema Amendment A27 | Owner and approval: maintainer's to assign. Sunset: adopt/pin the reviewed CLI and FE producer contract, wire admission into the host sequence-CAS, and verify compatible readers before rollout. |
Loading
Loading