diff --git a/.agents/checks/adr-compliance.md b/.agents/checks/adr-compliance.md new file mode 100644 index 00000000..80778468 --- /dev/null +++ b/.agents/checks/adr-compliance.md @@ -0,0 +1,26 @@ +# ADR compliance + +Treat accepted records in `docs/adr/` as architectural constraints until a +replacement record has itself been accepted. A proposed replacement does not +lift the existing constraint. Treat proposed records as review guidance. Read the decision and consequences for +every record relevant to the changed surface, and report only contradictions +introduced by the diff. Cite the full semantic identifier in every finding. + +An architecture change needs an ADR when it establishes a durable boundary, +changes an invariant, chooses among viable system designs, or creates a +compatibility or migration policy. Implementation detail, transient test +evidence, and routine maintenance do not need ADRs. A deliberate deviation from +the package invariants still belongs in `docs/decisions/EXCEPTIONS.md`. + +The template sections are recommendations. Do not report a finding solely +because an ADR omits or renames Context, Decision, Alternatives considered, +What we reject, Consequences, or Revisit triggers. Review whether the record +preserves enough rationale and impact to be useful for its specific decision, +including typed relations, testable proof, standing rejections, known limits, +and measurable revisit conditions when relevant. + + +```text +Treat accepted ADRs in docs/adr/ as constraints until a replacement is itself Accepted; a Proposed replacement does not lift the existing constraint. Treat proposed ADRs as directional guidance. For source changes, read the decisions relevant to the affected op, state, replication, API, ordering, validation, or distribution surface. Flag only contradictions introduced by this diff, cite the full ADR identifier, and distinguish a conflict with an accepted record from disagreement with a proposal. If the diff establishes a durable architecture boundary, changes an invariant, chooses among viable system designs, or creates compatibility or migration policy without recording the tradeoff in docs/adr/, ask for an ADR. Do not demand an ADR for implementation detail, transient evidence, tests, or routine maintenance. Context, Decision, Alternatives considered, What we reject, Consequences, and Revisit triggers are recommended prompts, not required headings; do not fail an ADR solely because one is omitted or renamed. Review whether typed relations, testable proof, standing rejections, known limits, measurable revisit conditions, compatibility, and supersession are concrete and mutually consistent for the decision at hand. +``` + diff --git a/.agents/checks/api-contract.md b/.agents/checks/api-contract.md index 6a0feecc..4f5085ca 100644 --- a/.agents/checks/api-contract.md +++ b/.agents/checks/api-contract.md @@ -4,8 +4,8 @@ Catch breaking changes to this package's public surface. Applies to `src/index.t ## What to check -1. **Public exports** — `src/index.ts` re-exports the op layer (including ADR-022's pure `inspectOps` storage preflight), KA-11 read gate, ADR-004 follower reads, #71's payload-bound constants and `opBoundsRefusal` from `src/limits.ts`, the snapshot surface from `src/read.ts`, and everything from `types` and `stamps`. A removed or renamed export without a compatibility alias is breaking. New exports are fine only when deliberately classified. - Most of `src/doc.ts` stays private because its accessors and mutators bypass the op layer (KA-1, KA-2, KA-4, FC-5). Re-adding `export * from "./doc.js"`, or adding a `./doc` subpath, or exposing any further `doc.ts` runtime export from the entrypoint, is a blocking finding, not a compatibility fix. The named exceptions are `nodesMap`, `linksMap`, and `OPAQUE_WIDGETS_KEY` (ADR-004's frontend-follower reads) plus `encodingLosses` (KA-1's read-only value diagnostic, which takes no document); `test/public-api.regression.test.ts` guards that exact list, and widening it is a diff rather than a silent consequence of adding an export. +1. **Public exports** — `src/index.ts` re-exports the op layer (including ADR-API-0022's pure `inspectOps` storage preflight), KA-11 read gate, ADR-DISTRIBUTION-0004 follower reads, #71's payload-bound constants and `opBoundsRefusal` from `src/limits.ts`, the snapshot surface from `src/read.ts`, and everything from `types` and `stamps`. A removed or renamed export without a compatibility alias is breaking. New exports are fine only when deliberately classified. + Most of `src/doc.ts` stays private because its accessors and mutators bypass the op layer (KA-1, KA-2, KA-4, FC-5). Re-adding `export * from "./doc.js"`, or adding a `./doc` subpath, or exposing any further `doc.ts` runtime export from the entrypoint, is a blocking finding, not a compatibility fix. The named exceptions are `nodesMap`, `linksMap`, and `OPAQUE_WIDGETS_KEY` (ADR-DISTRIBUTION-0004's frontend-follower reads) plus `encodingLosses` (KA-1's read-only value diagnostic, which takes no document); `test/public-api.regression.test.ts` guards that exact list, and widening it is a diff rather than a silent consequence of adding an export. Prefer snapshot reads for new consumers: values returned by `src/read.ts` must not expose a live `Y.AbstractType`, at any depth. `test/readonly-surface.test.ts` proves its current functions return deep-copied, deep-frozen plain data, and that they refuse a document carrying content under an unreadable schema on the same predicate `project()` uses (KA-11). Not the same DISPOSITION, and do not report it as such: for a document carrying NOTHING the snapshot surface returns its empty value where `project()` refuses — Amendment A12 records that divergence against A5's consumer-impact note. Two things are blocking findings here: a gate on this surface that asks "does the document carry content" by enumerating the §1 root NAMES (blind to a v2 that renamed them, which is the canonical bump trigger), and a new entrypoint export not classified by that test. diff --git a/.coderabbit.yaml b/.coderabbit.yaml index ad017516..4ae069ee 100644 --- a/.coderabbit.yaml +++ b/.coderabbit.yaml @@ -30,6 +30,28 @@ reviews: skipped op_id record) is a blocking KA-4 issue (see issue #10); require validate-before-mutate. Any second op-to-document implementation is a blocking FC-3 issue. + - path: "{src/**,docs/adr/**}" + # source: .agents/checks/adr-compliance.md + instructions: >- + Treat accepted ADRs in docs/adr/ as constraints until a replacement is + itself Accepted; a Proposed replacement does not lift the existing + constraint. Treat proposed ADRs as directional guidance. For source + changes, read the decisions relevant to the affected op, state, + replication, API, ordering, validation, or distribution surface. Flag + only contradictions introduced by this diff, cite the full ADR + identifier, and distinguish a conflict with an accepted record from + disagreement with a proposal. If the diff establishes a durable + architecture boundary, changes an invariant, chooses among viable + system designs, or creates compatibility or migration policy without + recording the tradeoff in docs/adr/, ask for an ADR. Do not demand an + ADR for implementation detail, transient evidence, tests, or routine + maintenance. Context, Decision, Alternatives considered, What we + reject, Consequences, and Revisit triggers are recommended prompts, not + required headings; do not fail an ADR solely because one is omitted or + renamed. Review whether typed relations, testable proof, standing + rejections, known limits, measurable revisit conditions, compatibility, + and supersession are concrete and mutually consistent for the decision + at hand. - path: "{fixtures/**,.agents/checks/catalog-pinning.md}" # source: .agents/checks/catalog-pinning.md instructions: >- diff --git a/.github/workflows/adr-links.yml b/.github/workflows/adr-links.yml new file mode 100644 index 00000000..95b0a935 --- /dev/null +++ b/.github/workflows/adr-links.yml @@ -0,0 +1,22 @@ +name: ADR link validation + +on: + push: + branches: [main] + pull_request: + +permissions: + contents: read + +jobs: + adr-links: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0 + with: + node-version: 22 + - name: Check ADR references resolve + run: node scripts/check-adr-links.mjs diff --git a/.github/workflows/auto-tag-release.yml b/.github/workflows/auto-tag-release.yml index a5ba882e..acec3cc4 100644 --- a/.github/workflows/auto-tag-release.yml +++ b/.github/workflows/auto-tag-release.yml @@ -4,7 +4,7 @@ name: Auto-tag release PR # release PR. It does NOT make merging a release: the deliberate act is the # maintainer applying the `release` label to a version-bump PR and approving # it. Nothing here fires without that label. See the amendment in -# docs/decisions/ADR-006-publish-to-npm-pin-exact-versions.md. +# docs/adr/DISTRIBUTION-0006-publish-to-npm-pin-exact-versions.md. # # WHY IT DISPATCHES INSTEAD OF RELYING ON THE TAG PUSH: a ref created with the # default GITHUB_TOKEN never raises `push`, so Release would not start from the diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 3220cb6c..7cde03bb 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -69,6 +69,9 @@ jobs: - name: Profile-claim staleness gate run: npm run check:profile-claims + - name: ADR governance gate + run: npm run check:adrs + # .coderabbit.yaml's path_instructions are generated from the # blocks in .agents/checks/*.md. This # fails when the committed file no longer matches them. CodeRabbit reads diff --git a/AGENTS.md b/AGENTS.md index 7cede99a..7a8915a8 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -40,6 +40,40 @@ CI deliberately omits a raw line or branch coverage floor. The mutation threshol Reviewer-agent concern profiles live in `.agents/checks/`. Apply every relevant profile to semantic, export, dependency, catalog, and replication-boundary changes. +## Architecture decision records + +Architectural decisions live only in `docs/adr/`. Accepted records are +constraints; proposed records are guidance. Create an ADR when a change sets a +durable boundary, changes an invariant, chooses among viable system designs, or +defines compatibility or migration policy. Do not use an ADR for implementation +detail or transient test evidence. Deliberate invariant exceptions remain in +`docs/decisions/EXCEPTIONS.md`. + +Name records `[-]--descriptive-title.md`, with one or +two broad-to-narrow domain tags and the next unused four-digit number for that +domain. The heading must be `# ADR-: Title`, followed by a +`Date: YYYY-MM-DD` line and a `## Status` value of `Proposed`, `Accepted`, +`Rejected`, `Deprecated`, or `Superseded`. Start from `docs/ADR-TEMPLATE.md`. +Run `npm run check:adrs`; CI enforces naming, metadata, identifier uniqueness, +companion-directory ownership, and links to ADR files. Superseded records stay +in place and link to their replacement. Relate records with Builds on, Refines, +Amends, or Supersedes and state what remains true. An Accepted record remains +binding until its replacement is also Accepted; a Proposed replacement is review +context, not permission to contradict it. `Context`, `Decision`, `Alternatives +considered`, `What we reject`, `Consequences`, and `Revisit triggers` are +recommended prompts, not mandatory headings; the validator deliberately does +not enforce content-section shape. + +The validator tests replay the shared conformance cases in this repository's +native toolchain: exact status values, real calendar dates, full-identifier +collisions, companion ownership, and direct/reference-style ADR links. A workflow +run is not itself proof that the ADR check is a required merge gate. + +Comfy repositories standardize this ADR behavior and lifecycle, not one tool +implementation. Keep the validator, tests, and CI integration native to this +repository's language and package manager; this TypeScript package uses Node, +Vitest, npm scripts, and GitHub Actions. + ## Permutation and property testing Use permutation-exhaustive tests when a concurrency surface has a small, explicitly bounded domain: enumerate every legal arrival order and every selected equivalence-class value, assert the exact case count, and include the full case dimensions in assertion messages so a failure is directly reproducible. Prefer this for two-writer register contention, normalized-ID collisions, batch-boundary choices, and short causal interleavings. diff --git a/CHANGELOG.md b/CHANGELOG.md index 522327fd..7e95fc41 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -167,7 +167,7 @@ the schema-4 line: the 0.3.7 code relicensed to MIT.) content (`op_id`, graph scope, and raw link ID) via SHA-256 folded into the full JavaScript safe-integer range, matching the branded-number `LinkId` type ComfyUI_frontend expects and removing the reproducible collisions the - prior 32-bit string-folding workaround produced (ADR-033). + prior 32-bit string-folding workaround produced (ADR-WORKFLOW-0033). ### Changed @@ -250,9 +250,9 @@ the schema-4 line: the 0.3.7 code relicensed to MIT.) ### Changed -- Breaking: replaced the 0.1.0 `ApplyResult` shape with ADR-007's ordered, +- Breaking: replaced the 0.1.0 `ApplyResult` shape with ADR-API-0007's ordered, discriminated per-op `outcomes` records and renamed `version` to `ops_seen`. -- Added ADR-008's caller-owned event sink contract so hosts can receive +- Added ADR-OBSERVABILITY-0008's caller-owned event sink contract so hosts can receive structured cmp events without a package-global registry or telemetry dependency. - Exported the agent event schema surface from `src/index.ts`, including @@ -260,7 +260,7 @@ the schema-4 line: the 0.3.7 code relicensed to MIT.) - Added the ADR-011 replay-never-wipe reconnect contract to the 0.2.0 surface: reconnects continue from document state and state-vector delta replay instead of replacing follower documents during ordinary catch-up. -- Added ADR-021's `DocDerivedLamportClockStore`, deriving Lamport floors from +- Added ADR-ORDERING-0021's `DocDerivedLamportClockStore`, deriving Lamport floors from the caller-owned document's committed `__stamps` ledger rather than package process state. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7763abe9..503b96df 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -99,13 +99,24 @@ sign-off — the browser is a co-equal host of this document. Contract changes are amendments appended to the schema document with reasoning, never silent edits to a decided section. +## Architecture decision records + +Significant, durable architecture choices live in `docs/adr/`. Start from +`docs/ADR-TEMPLATE.md`, select the next unused number within the owning domain, +and use the canonical filename, heading, date, and status shape documented in +`AGENTS.md`. Run `npm run check:adrs` before review. Keep superseded records and +link them to their replacements so old source and PR references remain useful. +The template's content sections are recommended prompts rather than required +headings. Across Comfy repositories the ADR behavior is consistent, while the +validator and CI wiring remain native to each repository's language and tools. + ## Cutting a release Releases are cut from a **version-bump-only PR**: `package.json`, `package-lock.json`, and a `CHANGELOG.md` entry, nothing else. Apply the **`release` label** to that PR before merging it. The label is the deliberate publish decision — see the 2026-09-21 amendment in -[`docs/decisions/ADR-006-publish-to-npm-pin-exact-versions.md`](docs/decisions/ADR-006-publish-to-npm-pin-exact-versions.md). +[`docs/adr/DISTRIBUTION-0006-publish-to-npm-pin-exact-versions.md`](docs/adr/DISTRIBUTION-0006-publish-to-npm-pin-exact-versions.md). When a labelled PR merges, `.github/workflows/auto-tag-release.yml` creates `v` at the merge commit and starts `release.yml` at that tag, which diff --git a/README.md b/README.md index 478ca626..5bdbf2ca 100644 --- a/README.md +++ b/README.md @@ -61,8 +61,8 @@ Each side looks correct alone, so this is silent until the merge. ## 0.2.0 release scope Version 0.2.0 is a breaking release because it replaces the 0.1.0 -`ApplyResult` shape with ADR-007's ordered, discriminated outcomes and renames -the old version-like count to `ops_seen`. It also adds ADR-008's explicitly +`ApplyResult` shape with ADR-API-0007's ordered, discriminated outcomes and renames +the old version-like count to `ops_seen`. It also adds ADR-OBSERVABILITY-0008's explicitly passed, caller-owned event sink and the public event schema surface: `AGENT_EVENT_JSON_SCHEMA`, `CMP_EVENT_SCHEMA_VERSION`, `AgentEvent`, `CmpEvent`, `CmpEventType`, `CmpEventSink`, and `CmpCallContext`. @@ -136,7 +136,7 @@ document mutation, and retry with the same operation identity. `add_node` carrying positional widget values is rejected `catalog_required`, and unknown widget names are no longer caught. -`context` may carry ADR-008's caller-owned `eventSink`. The sink receives +`context` may carry ADR-OBSERVABILITY-0008's caller-owned `eventSink`. The sink receives versioned, JSON-safe `CmpEvent` diagnostics and cannot change semantic results; there is no global registration or package-owned telemetry state. The API also exports the host event contract (`CMP_EVENT_SCHEMA_VERSION`, `CmpEvent`, @@ -197,7 +197,7 @@ Schema v5 adds `(name, occurrence)` widget identity; schema v4 separated Lamport reservations into `__clock_reservations`; `readStamps()` contains only winning write-target stamps. Clock admissions require a current-schema caller document and recover their floor from both -ledgers, including after snapshot restart (ADR-021, Amendment CLK-3). +ledgers, including after snapshot restart (ADR-ORDERING-0021, Amendment CLK-3). `migrate()` is **no longer the only fail-closed read gate** — it was, and nothing forced a caller through it, which is the fail-open gap #38 closed by @@ -254,14 +254,14 @@ outside that domain. An absent stamp still falls back to the envelope's ### Follower read surface and document internals The entrypoint exports the op layer (`mint`, `applyOps`, `project`, `migrate`), -the KA-11 read gate, the stamp machinery above, the ADR-004 follower read +the KA-11 read gate, the stamp machinery above, the ADR-DISTRIBUTION-0004 follower read surface (`nodesMap`, `linksMap`, `OPAQUE_WIDGETS_KEY`), KA-1's `encodingLosses` diagnostic, the payload bounds (`MAX_OPS_PER_BATCH`, `MAX_PAYLOAD_DEPTH`, `MAX_COLLECTION_ENTRIES`, `MAX_OP_COST`, `opBoundsRefusal`), the safer snapshot surface below, and the types. That is the whole public surface. The three layout exports are a deliberate exception for the frontend follower -documented by ADR-004. They are read-only by contract: that follower consumes +documented by ADR-DISTRIBUTION-0004. They are read-only by contract: that follower consumes the host's layout and never writes the shared document or calls `applyOps`. `initDoc`, `definitionsMap`, `metaMap`, `appliedMap`, `stampsMap`, `createNodeMap`, `resolveDefinition`, `countDefinitionInstances`, @@ -283,7 +283,7 @@ with no diagnostic. See [issue #18][issue-18] and KA-1, KA-2, KA-4, FC-5 in General consumers should call `project(doc, catalog)` for canonical workflow JSON, or use the safer snapshot surface below when projection cannot serve the read. There is no `./doc` subpath export and none will be added; of `doc.ts` -only ADR-004's three deliberate layout exports and KA-1's `encodingLosses` +only ADR-DISTRIBUTION-0004's three deliberate layout exports and KA-1's `encodingLosses` remain reachable from the entrypoint. [issue-18]: https://github.com/Comfy-Org/comfy-multi-player/issues/18 @@ -367,7 +367,7 @@ Every op carries the same envelope, minted by its creator before dispatch: Nine kinds, frozen. Eight mirror comfy-cli's pinned vocabulary; `set_node_field` is the package-local, provisional addition recorded by -ADR-032 and schema Amendment A21. +ADR-OPS-NODE-0032 and schema Amendment A21. | Kind | Payload beyond the envelope | Batchable (authoring) | |---|---|---| @@ -376,7 +376,7 @@ ADR-032 and schema Amendment A21. | `connect` | `link_id`, `from_node`, `from_slot`, `to_node`, `link_type`, then EITHER a numeric `to_slot` (`ConcreteConnectOp`) OR a `grow` payload with `to_slot` null/absent (`GrowConnectOp`); `grow.promoted: true` names a subgraph instance's DECLARED input, materialized on the instance and LWW-gated as one register (schema Amendment A15) | yes | | `disconnect` | `link_id`, `to_node`, `to_slot`; claims the same concrete input register as `connect` and removes the winning slot occupant | yes | | `set_widget` | `node_id`, `widget` (name, never index), `value`, optional `old`; an interior write adds `path` AND `inner_widget` together (`InteriorSetWidgetOp`); a promoted HOST write adds `promoted: {value_index, instance_path, host_widgets_values}` instead — a positional write into a subgraph instance's opaque array (schema Amendment A15) | yes | -| `set_node_field` | `node_id`, `field` (one of `title`, `mode`, `flags.collapsed`, `flags.pinned` — exported as `WRITABLE_NODE_FIELDS`), and a field-typed `value`: string for `title`, non-negative integer for `mode`, boolean for flags, or `null` to delete. One LWW register per `(node lifetime, field)`, so two fields of one node never contend and neither disturbs that node's widget stamps. Package-local and provisional (ADR-032) | yes | +| `set_node_field` | `node_id`, `field` (one of `title`, `mode`, `flags.collapsed`, `flags.pinned` — exported as `WRITABLE_NODE_FIELDS`), and a field-typed `value`: string for `title`, non-negative integer for `mode`, boolean for flags, or `null` to delete. One LWW register per `(node lifetime, field)`, so two fields of one node never contend and neither disturbs that node's widget stamps. Package-local and provisional (ADR-OPS-NODE-0032) | yes | | `delete_node` | `node_id`, `removed_links`; an interior delete also carries a non-empty instance `path` and optional `container_incarnation` | 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 | @@ -453,7 +453,7 @@ replays already-minted ops under [abort-remainder](#what-applyops-returns), the same as comfy-cli's `apply_op`, which replays `clear` in any position. So a `clear` in the middle of an op array is applied here, deliberately: the `edit-heavy` conformance session contains exactly that, and -[`docs/portability.md`](docs/portability.md) requires every language +[`ADR-PORTABILITY-0001`](docs/adr/PORTABILITY-0001-op-layer-contract.md) requires every language implementation to replay it with no failures. If you are building a submission surface in front of the applier, that admission layer is where `BATCHABLE_OPS` belongs. `test/batch-policy.test.ts` pins all of this. @@ -464,7 +464,7 @@ The historical op envelope and six-kind base vocabulary are defined by amendment pinned separately below. The complete current eight-kind implemented surface is defined locally by `src/types.ts` and [`docs/multiplayer-schema.md`](docs/multiplayer-schema.md): `define_subgraph` -and ADR-031's standalone `insert_workflow` are local extensions, not claims +and ADR-WORKFLOW-0031's standalone `insert_workflow` are local extensions, not claims about the historical comfy-cli pin. This package tracks that document at comfy-cli commit @@ -724,9 +724,9 @@ resolution is a cross-process agreement about which write wins; two peers running different versions of these rules can disagree about the outcome. See -[`docs/decisions/ADR-006-publish-to-npm-pin-exact-versions.md`](docs/decisions/ADR-006-publish-to-npm-pin-exact-versions.md) +[`docs/adr/DISTRIBUTION-0006-publish-to-npm-pin-exact-versions.md`](docs/adr/DISTRIBUTION-0006-publish-to-npm-pin-exact-versions.md) for the consumption decision. The earlier git-SHA pinning model -([ADR-004](docs/decisions/ADR-004-consumers-pin-by-sha-no-registry-yet.md), +([ADR-DISTRIBUTION-0004](docs/adr/DISTRIBUTION-0004-consumers-pin-by-sha-no-registry-yet.md), superseded) remains documented for historical context. ## Develop diff --git a/docs/ADR-TEMPLATE.md b/docs/ADR-TEMPLATE.md new file mode 100644 index 00000000..106204dd --- /dev/null +++ b/docs/ADR-TEMPLATE.md @@ -0,0 +1,44 @@ +# ADR-[-]-: Decision title + +The sections below are recommended prompts, not a required schema. Keep the +sections that preserve useful decision context, rename or omit those that do +not fit, and add domain-specific evidence where it helps. The ADR validator +enforces only the filename, heading, date, status, identifier uniqueness, +companion-directory ownership, and resolvable ADR links. + +Date: YYYY-MM-DD + +Relation: ADR--. State +what remains true in that ADR. Omit this line when the ADR stands alone. + +## Status + +Proposed + +## Context + +Describe the forces and constraints that make a durable decision necessary. + +## Decision + +State the chosen direction, boundaries, and invariants. Name how implementation +will prove them; for production behavior, include health and rollback evidence. + +## Alternatives considered + +Record viable alternatives and why they were not chosen. + +## What we reject + +Record patterns later work must not introduce and why. These are standing rules, +distinct from alternatives considered at decision time. + +## Consequences + +Record positive, negative, operational, and migration consequences. Name known +limits explicitly, including why each gap remains open. + +## Revisit triggers + +State measurable conditions that reopen this decision after acceptance, including +the value and direction that matter. diff --git a/docs/INVARIANTS.md b/docs/INVARIANTS.md index 52c00929..8a1b9927 100644 --- a/docs/INVARIANTS.md +++ b/docs/INVARIANTS.md @@ -13,7 +13,7 @@ This is the machine-addressable review log for the package. IDs are stable; do n ### KA-1 — Ops are the replication unit end-to-end **Rule:** Between any two replicas that edited independently, exchange semantic ops, never raw Yjs updates. **Why:** Convergence holds iff independently edited replicas exchange ops. -**Enforced by:** `test/public-api.regression.test.ts` (the package entrypoint exposes the op layer plus only ADR-004's three follower layout reads and KA-1's `encodingLosses` diagnostic — four names, and the guard's list is exactly those four; every other mutation helper stays private, and the follower is read-only by KA-6/FC-5) and `test/readonly-surface.test.ts` (the safer snapshot functions return deep-copied, deep-frozen plain data with no live `Y.AbstractType` at any depth); reviewer profiles [`convergence-idempotency`](../.agents/checks/convergence-idempotency.md), [`follower-boundary`](../.agents/checks/follower-boundary.md), and [`api-contract`](../.agents/checks/api-contract.md); architecture decision [ADR-002](decisions/ADR-002-ops-replication-unit.md). The schema §5.3 corollary — one op must not mutate N nodes through a shared subgraph definition — is held by `test/mutation-survivors.test.ts` (top-level instances), `test/promoted-host-writes.test.ts` (a NESTED promoted host write — Amendment A15's `instance_path` — resolves through the same guard, while a top-level host write never descends and is legal on a shared definition) and `test/doc-mint-mutation-survivors.test.ts` (instances reached from INSIDE another definition, and instances addressed by the definition's unique cosmetic NAME rather than its id). The name case was a live corruption bug until MUT-GLOB-KA4-1: `resolveDefinition` reaches a definition by id or by unique name, `countDefinitionInstances` matched the id string alone, so one definition instantiated under both spellings counted as ONE, the guard did not fire, and an interior `set_widget` mutated a definition backing two nodes while `applyOps` reported success. The count is now taken over the definition's resolvable aliases, so the guard's input and the resolver agree by construction — with one narrowing the first attempt missed: a display name the pinned catalogue describes as a node CLASS is not an alias, because naming a subgraph after the node it wraps is common (three shipped template workflows do) and counting those class nodes as instances rejected legal interior writes. A `nodes` entry that is not a `Y.Map` throws rather than being skipped, since skipping undercounts and makes this guard fail OPEN. +**Enforced by:** `test/public-api.regression.test.ts` (the package entrypoint exposes the op layer plus only ADR-DISTRIBUTION-0004's three follower layout reads and KA-1's `encodingLosses` diagnostic — four names, and the guard's list is exactly those four; every other mutation helper stays private, and the follower is read-only by KA-6/FC-5) and `test/readonly-surface.test.ts` (the safer snapshot functions return deep-copied, deep-frozen plain data with no live `Y.AbstractType` at any depth); reviewer profiles [`convergence-idempotency`](../.agents/checks/convergence-idempotency.md), [`follower-boundary`](../.agents/checks/follower-boundary.md), and [`api-contract`](../.agents/checks/api-contract.md); architecture decision [ADR-REPLICATION-0002](adr/REPLICATION-0002-ops-replication-unit.md). The schema §5.3 corollary — one op must not mutate N nodes through a shared subgraph definition — is held by `test/mutation-survivors.test.ts` (top-level instances), `test/promoted-host-writes.test.ts` (a NESTED promoted host write — Amendment A15's `instance_path` — resolves through the same guard, while a top-level host write never descends and is legal on a shared definition) and `test/doc-mint-mutation-survivors.test.ts` (instances reached from INSIDE another definition, and instances addressed by the definition's unique cosmetic NAME rather than its id). The name case was a live corruption bug until MUT-GLOB-KA4-1: `resolveDefinition` reaches a definition by id or by unique name, `countDefinitionInstances` matched the id string alone, so one definition instantiated under both spellings counted as ONE, the guard did not fire, and an interior `set_widget` mutated a definition backing two nodes while `applyOps` reported success. The count is now taken over the definition's resolvable aliases, so the guard's input and the resolver agree by construction — with one narrowing the first attempt missed: a display name the pinned catalogue describes as a node CLASS is not an alias, because naming a subgraph after the node it wraps is common (three shipped template workflows do) and counting those class nodes as instances rejected legal interior writes. A `nodes` entry that is not a `Y.Map` throws rather than being skipped, since skipping undercounts and makes this guard fail OPEN. ### KA-2 — The ordering/identity key rides inside the op **Rule:** `[base_version, actor, op_id]` is a total order any replica can evaluate offline; `op_id` is uuid4 hex minted by the creator before dispatch and never regenerated. @@ -41,27 +41,27 @@ The *rejection* half — "a rejected op leaves the doc untouched", stated in the ### KA-5 — IDs are collision-free without coordination **Rule:** Use 53-bit random mint; document high-water marks are advisory, never allocators; FE stable IDs must be non-colliding strings. **Why:** Offline peers must create entities without a central allocator. -**Enforced by:** `insert_workflow` derives every carried ID inside the applier from the immutable `op_id`, scope, kind, and raw ID (ADR-031); producers send raw workflows and perform no allocation against document state. General producer randomness remains **UNGUARDED — see roadmap**. +**Enforced by:** `insert_workflow` derives every carried ID inside the applier from the immutable `op_id`, scope, kind, and raw ID (ADR-WORKFLOW-0031); producers send raw workflows and perform no allocation against document state. General producer randomness remains **UNGUARDED — see roadmap**. -**Logged exception (2026-09-22, ADR-033; amended and ratified 2026-09-23):** +**Logged exception (2026-09-22, ADR-WORKFLOW-0033; amended and ratified 2026-09-23):** a link's derived id is the ONE carried-ID kind whose numeric type this rule's "53-bit random mint" clause is worth stating explicitly for. ComfyUI_frontend's `LinkId` is a branded `number`, unlike the string-or-number `NodeId`, so `insert_workflow`'s usual pure string derivation cannot satisfy it; `remap.ts`'s `derivedLinkId` mints a candidate -purely from the op's own content (SHA-256 of the ADR-031 seed, folded into +purely from the op's own content (SHA-256 of the ADR-WORKFLOW-0031 seed, folded into the full `[1, Number.MAX_SAFE_INTEGER]` range) with **no document read and no retry** — an earlier revision retried against `doc.ts`'s `persistedLinkIds`, which review found made link identity depend on local arrival order (KA-2), so that retry and `persistedLinkIds` were both -removed. See `docs/decisions/EXCEPTIONS.md`'s KA-5 row and ADR-033's +removed. See `docs/decisions/EXCEPTIONS.md`'s KA-5 row and ADR-WORKFLOW-0033's "Amendment (2026-09-23)" section for the full reasoning, the quantified residual collision probability, and the ratification record. ### KA-6 — Raw struct updates flow host → follower one-way only **Rule:** Followers never write the shared doc. **Why:** Reverse-flow Yjs structs from independently edited docs can corrupt or diverge state. -**Enforced by:** [`follower-boundary`](../.agents/checks/follower-boundary.md) and [ADR-002](decisions/ADR-002-ops-replication-unit.md); runtime boundary enforcement is outside this package. +**Enforced by:** [`follower-boundary`](../.agents/checks/follower-boundary.md) and [ADR-REPLICATION-0002](adr/REPLICATION-0002-ops-replication-unit.md); runtime boundary enforcement is outside this package. ### KA-7 — Presence/awareness is ephemeral **Rule:** Cursors, selection, and hover use the awareness channel and are never persisted into the doc. @@ -92,7 +92,7 @@ Two corrections recorded by MUT-GLOB-KA4-1, both measured on this tree rather th **Why:** Readers must not silently mis-project an incompatible document. **Enforced by:** `test/roundtrip.test.ts`, `test/schema-version-on-read.test.ts`, `test/readonly-surface.test.ts`, and the 22 byte-identical old-layout refusal counterexamples retained by the schema-v3 integration. `project()` and `migrate()` share `readSchemaVersion`; both refuse old, absent, unreadable, or newer versions without mutation. Snapshot reads use the same predicate but return empty data for a document carrying no structs, as recorded by Amendment A12. Old private-alpha layouts are re-minted from source rather than relabelled. -Schema v4 adds the separate clock reservation root (schema A20 / ADR-021 CLK-3). +Schema v4 adds the separate clock reservation root (schema A20 / ADR-ORDERING-0021 CLK-3). A v3 clock would miss those counters, so the layout is not silently extended. `observedDocCounter()` also requires the current schema, even for an empty doc; clock admission is not a follower's empty snapshot read. `test/clock.test.ts` @@ -129,10 +129,10 @@ state the new writer persists identically. ### 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. **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. +**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-CATALOG-0003](adr/CATALOG-0003-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. ### KA-13 — The package owns no state outside the caller's document -**Rule:** The package holds no caller-independent durable state: no module-level `let`/`var`, no module-level mutable collection, and no UI/reactivity/framework import. Every document is caller-owned and injected, so behavior must not depend on process lifetime or module-registry identity. There is exactly one documented exception — the `Y.Doc`-keyed `documentTransactionTails` weak registry of [ADR-021](decisions/ADR-021-doc-derived-lamport-clock-store.md) amendment CLK-2 — which is named in the gate's allowlist, keyed by caller-owned document identity, and creates no durable or cross-document state. +**Rule:** The package holds no caller-independent durable state: no module-level `let`/`var`, no module-level mutable collection, and no UI/reactivity/framework import. Every document is caller-owned and injected, so behavior must not depend on process lifetime or module-registry identity. There is exactly one documented exception — the `Y.Doc`-keyed `documentTransactionTails` weak registry of [ADR-ORDERING-0021](adr/ORDERING-0021-doc-derived-lamport-clock-store.md) amendment CLK-2 — which is named in the gate's allowlist, keyed by caller-owned document identity, and creates no durable or cross-document state. **Why:** One implementation must run identically in a browser bundle, at a peer or edge, and in a bare Node doc-host serving many documents from one process, so restart and reconnect reseed from committed document state rather than package-owned persistence and two documents in one process cannot leak into each other. **This is not an alias of KA-3, and the overlap is the reason it reads like one:** KA-3 constrains the *dependency surface* (portability), KA-13 constrains *state ownership*. They coincide only on the framework-import ban, which is why `scripts/check-stateless.mjs` cites both and why the framework rules in the strict config are labelled `KA-3/KA-13`. **Enforced by:** `scripts/check-stateless.mjs` (`npm run check:stateless`), which lints every `src/**/*.ts` file against the `statelessRules` set in [`eslint.strict.config.js`](../.agents/checks/eslint.strict.config.js) under `CMP_STATELESS_ONLY=1` and then runs the colocated `test/stateless.test.ts` probe — no state shared between documents in one module instance, identical public behavior from fresh module registries, and a fresh Node process. The gate exits 2 (INCONCLUSIVE, never a pass) when a precondition or the per-file lint floor is missing, and it is merge-blocking in fact rather than by convention: [`.github/workflows/ci.yml`](../.github/workflows/ci.yml) runs it on every push and pull request. `test/invariant-ids.test.ts` holds this register itself — every `KA-*`/`FC-*` id cited anywhere in the package must resolve to a heading in this file, which is the guard that was missing while this entry was ([comfy-multi-player #152](https://github.com/Comfy-Org/comfy-multi-player/issues/152)). @@ -163,13 +163,13 @@ refuses old layouts; it re-mints source workflows rather than providing a compatibility reader or relabelling an old document. **Enforced by:** `test/clock.test.ts`, the existing LWW/convergence suites, the -four-family merge harness, and [`ADR-0005`](adr/0005-lamport-ordering-v1-migration.md). +four-family merge harness, and [`ADR-ORDERING-0005`](adr/ORDERING-0005-lamport-ordering-v1-migration.md). ## FORECLOSE ### FC-1 — Never exchange raw Yjs struct updates between independently edited docs **Why:** This is the length-8 KSampler corruption path. -**Enforced by:** [`follower-boundary`](../.agents/checks/follower-boundary.md) and [ADR-002](decisions/ADR-002-ops-replication-unit.md). +**Enforced by:** [`follower-boundary`](../.agents/checks/follower-boundary.md) and [ADR-REPLICATION-0002](adr/REPLICATION-0002-ops-replication-unit.md). ### FC-2 — Never make the server the only thing that can assign order **Rule:** Server sequence must not be the sole conflict resolver beyond merely advancing `base_version`. @@ -178,7 +178,7 @@ four-family merge harness, and [`ADR-0005`](adr/0005-lamport-ordering-v1-migrati ### FC-3 — Never couple the applier/op layer to server-only or DOM/framework-only dependencies **Why:** Such coupling prevents execution at a peer, edge, or browser and invites a second implementation. -**Enforced by:** `scripts/check-purity.mjs`, `scripts/check-import-graph.mjs` + `.dependency-cruiser.cjs` rule `src-no-node-builtins`, `test/purity.test.ts`, [`purity`](../.agents/checks/purity.md), and [ADR-001](decisions/ADR-001-single-shared-applier.md). +**Enforced by:** `scripts/check-purity.mjs`, `scripts/check-import-graph.mjs` + `.dependency-cruiser.cjs` rule `src-no-node-builtins`, `test/purity.test.ts`, [`purity`](../.agents/checks/purity.md), and [ADR-APPLIER-0001](adr/APPLIER-0001-single-shared-applier.md). ### FC-4 — Never use full-document replace as the mutation primitive **Why:** It increases ingress/egress, clobbers concurrent edits, and kills op-log replay and observability. @@ -209,4 +209,4 @@ four-family merge harness, and [`ADR-0005`](adr/0005-lamport-ordering-v1-migrati ### FC-10 — Never cite the frozen vocabulary/catalog by moving branch instead of SHA **Rule:** Every cross-repository citation names a commit SHA registered in `docs/upstream-pins.json` with the derivation that established it; the branch a pin replaced may be recorded as provenance but is never the citation. Moving a pin is a contract change — re-read the cited sections, reconcile the code, then move the registry and every citation together. **Why:** A moving reference causes silent contract drift. Observed, not hypothetical: the branch this package cited for the op vocabulary was deleted upstream on 2026-08-21 while three citations still named it, and two contract drifts reached this repository through it: the `reset_doc` deferred status (`docs/api-contract-proposal.md` Q5) and the batch-policy error codes (#19 — the pinned revision names one code, `workflow_clear_not_batchable`; the amendment already cited by SHA in Amendment A1 names two). -**Enforced by:** `scripts/check-pins.mjs` (`npm run check:pins`, offline in CI; `-- --verify-remote` also proves each pinned SHA still resolves, each cited Markdown section still has its heading, and each cited Python symbol still has its definition, at that revision), `test/upstream-pins.test.ts`, [`catalog-pinning`](../.agents/checks/catalog-pinning.md), and [ADR-003](decisions/ADR-003-catalog-sha-at-mint.md). +**Enforced by:** `scripts/check-pins.mjs` (`npm run check:pins`, offline in CI; `-- --verify-remote` also proves each pinned SHA still resolves, each cited Markdown section still has its heading, and each cited Python symbol still has its definition, at that revision), `test/upstream-pins.test.ts`, [`catalog-pinning`](../.agents/checks/catalog-pinning.md), and [ADR-CATALOG-0003](adr/CATALOG-0003-catalog-sha-at-mint.md). diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index 411136a0..5d6072c2 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -2,9 +2,9 @@ ## Current state -V1 is an op-based Yjs document applier implemented once in the shared `@comfyorg/comfy-multi-player` TypeScript package. The browser and Node doc-host sidecar must consume the same exact published npm version (ADR-006); merging recovery code does not publish it or update consumers. Semantic ops are the replication unit; the widget catalog is sha256-pinned and fail-closed in the deployed architecture. +V1 is an op-based Yjs document applier implemented once in the shared `@comfyorg/comfy-multi-player` TypeScript package. The browser and Node doc-host sidecar must consume the same exact published npm version (ADR-DISTRIBUTION-0006); merging recovery code does not publish it or update consumers. Semantic ops are the replication unit; the widget catalog is sha256-pinned and fail-closed in the deployed architecture. -ADR-031 adds the standalone-only `insert_workflow` kind for atomic template insertion. The applier +ADR-WORKFLOW-0031 adds the standalone-only `insert_workflow` kind for atomic template insertion. The applier derives tree-wide IDs from `op_id`; producers submit raw IDs and do not inspect document state. ## Guard gaps diff --git a/docs/decisions/ADR-005-read-only-snapshot-surface.md b/docs/adr/API-0005-read-only-snapshot-surface.md similarity index 94% rename from docs/decisions/ADR-005-read-only-snapshot-surface.md rename to docs/adr/API-0005-read-only-snapshot-surface.md index b2256dcb..f57665e6 100644 --- a/docs/decisions/ADR-005-read-only-snapshot-surface.md +++ b/docs/adr/API-0005-read-only-snapshot-surface.md @@ -1,13 +1,17 @@ -# ADR-005: Reads get a snapshot surface, not the document handles back +# ADR-API-0005: Reads get a snapshot surface, not the document handles back + +Date: 2026-08-20 + +## Status + +Accepted -**Status:** Accepted -**Date:** 2026-08-20 **Invariant:** KA-1, KA-2, KA-4, KA-6, KA-12, FC-5 (and KA-3 — the surface is pure) -**Supersedes in part:** ADR-004 §Context, third bullet +**Supersedes in part:** ADR-DISTRIBUTION-0004 §Context, third bullet ## Context -Issue #18 stopped the entrypoint wholesale re-exporting `src/doc.ts`. ADR-004's +Issue #18 stopped the entrypoint wholesale re-exporting `src/doc.ts`. ADR-DISTRIBUTION-0004's `nodesMap`, `linksMap`, and `OPAQUE_WIDGETS_KEY` remain public for follower compatibility. The vulnerability was reachability, not intent: the same import that hands a caller `nodesMap` for @@ -25,7 +29,7 @@ are reads**: | cloud `services/agent/dochost/src/server.ts` `requirePin()` | `meta.catalog_version` | It is the KA-12 guard that decides whether projecting under the request's catalog is safe at all — it must run *before* `project()`. | | cloud `server.ts` `detectIDCollision()` | `nodes.has(id)`, `__applied.has(op_id)` | Two `has()` probes per op on the pre-apply path; projecting the whole document per op is the wrong shape and needs a catalog it may not trust yet. There is no projection of `__applied`. | | cloud `scripts/introspect-state.mjs` | `__applied` keys, `__stamps`, `meta` | The cross-language conformance harness compares the bookkeeping ledgers. No projection contains them. | -| frontend `crdt/docSchema.ts` `readDocSnapshot()` | `nodes`, `links`, `__widgets_opaque` | The follower holds no catalog for the document it renders, so it cannot call `project()` — and ADR-004 records that it deliberately does not. | +| frontend `crdt/docSchema.ts` `readDocSnapshot()` | `nodes`, `links`, `__widgets_opaque` | The follower holds no catalog for the document it renders, so it cannot call `project()` — and ADR-DISTRIBUTION-0004 records that it deliberately does not. | The op layer is for writes. "Migrate the consumers to ops" is not available for any of these. @@ -64,7 +68,7 @@ proved by attempting the violation in `test/readonly-surface.test.ts`: therefore refuses — same `SchemaVersionError`, same message shape — **when the document carries content under a schema this package cannot read**, and returns its empty value **when the document carries nothing**. The second - clause is not a softening: ADR-004's follower reads a document that has no + clause is not a softening: ADR-DISTRIBUTION-0004's follower reads a document that has no roots at all before its first frame, there is no content there to mis-key, and the surface already reads it as empty on `main` with two tests pinning that. (`migrate()` *does* refuse that document — #30 — but that is a role @@ -86,7 +90,7 @@ proved by attempting the violation in `test/readonly-surface.test.ts`: one definition of "readable". `test/public-api.regression.test.ts` keeps deriving the forbidden set from -`src/doc.ts` at runtime, with ADR-004's exact three-entry follower allowlist +`src/doc.ts` at runtime, with ADR-DISTRIBUTION-0004's exact three-entry follower allowlist plus the KA-1 `encodingLosses` diagnostic retained by main. `test/readonly-surface.test.ts` additionally fails on any entrypoint export it has not been told how to @@ -98,7 +102,7 @@ classify, so a future export cannot widen the surface unreviewed. restores `mset`/`mdel`/`initDoc`/`createNodeMap` reachability behind a longer specifier, which is exactly what #18 exists to remove. `.agents/checks/api-contract.md` already classifies it as a blocking finding. -- **Using the retained raw accessors for new consumers.** ADR-004 keeps these +- **Using the retained raw accessors for new consumers.** ADR-DISTRIBUTION-0004 keeps these public for compatibility, but property 2 above shows why they are not the preferred surface: even a caller who only reads gets a mutable reference into the document's own storage. @@ -117,7 +121,7 @@ classify, so a future export cannot widen the surface unreviewed. - The pin bump is unblocked: the FE follower and the cloud doc-host can both move past #18 without hand-mirroring schema v1 in raw `yjs`, which is what - ADR-004 closed. The migration is import-level; see the PR body for the exact + ADR-DISTRIBUTION-0004 closed. The migration is import-level; see the PR body for the exact before/after per call site. - `readGraph` costs about **2x** a raw live-handle read of the same four fields. Re-measured on Node 25 at this commit over three runs each @@ -180,7 +184,7 @@ classify, so a future export cannot widen the surface unreviewed. `schemaGuard` already refuses that state today, more strictly than this gate does (it has no empty-document escape at all). What the empty-document clause covers is "no frame has arrived yet", not "a frame arrived out of order". -- **`readGraph` can throw where `nodesMap` could not**, so ADR-004's +- **`readGraph` can throw where `nodesMap` could not**, so ADR-DISTRIBUTION-0004's description of it as a migration target for the frontend follower now comes with that caveat; see the migration note below. - **Migration note for the consumer that adopts this surface.** The frontend diff --git a/docs/decisions/ADR-007-discriminated-apply-outcomes.md b/docs/adr/API-0007-discriminated-apply-outcomes.md similarity index 92% rename from docs/decisions/ADR-007-discriminated-apply-outcomes.md rename to docs/adr/API-0007-discriminated-apply-outcomes.md index c5d4edb7..5f6785f1 100644 --- a/docs/decisions/ADR-007-discriminated-apply-outcomes.md +++ b/docs/adr/API-0007-discriminated-apply-outcomes.md @@ -1,7 +1,11 @@ -# ADR-007: Report one discriminated outcome per submitted op +# ADR-API-0007: Report one discriminated outcome per submitted op + +Date: 2026-08-22 + +## Status + +Accepted -**Status:** Accepted -**Date:** 2026-08-22 **Issue:** #16 ## Context diff --git a/docs/decisions/ADR-022-canonical-op-inspection.md b/docs/adr/API-0022-canonical-op-inspection.md similarity index 97% rename from docs/decisions/ADR-022-canonical-op-inspection.md rename to docs/adr/API-0022-canonical-op-inspection.md index 036b5533..a8e572d9 100644 --- a/docs/decisions/ADR-022-canonical-op-inspection.md +++ b/docs/adr/API-0022-canonical-op-inspection.md @@ -1,7 +1,11 @@ -# ADR-022: pure canonical operation inspection +# ADR-API-0022: pure canonical operation inspection + +Date: 2026-09-03 + +## Status + +Accepted -- **Status:** Accepted -- **Date:** 2026-09-03 - **Invariants:** KA-2, KA-3, KA-4; FC-2, FC-3 ## Context diff --git a/docs/decisions/ADR-001-single-shared-applier.md b/docs/adr/APPLIER-0001-single-shared-applier.md similarity index 90% rename from docs/decisions/ADR-001-single-shared-applier.md rename to docs/adr/APPLIER-0001-single-shared-applier.md index ddb13d0b..398f8611 100644 --- a/docs/decisions/ADR-001-single-shared-applier.md +++ b/docs/adr/APPLIER-0001-single-shared-applier.md @@ -1,7 +1,11 @@ -# ADR-001: Applier is a single shared package, no second implementation +# ADR-APPLIER-0001: Applier is a single shared package, no second implementation + +Date: 2026-08-20 + +## Status + +Accepted -**Status:** Accepted -**Date:** 2026-08-20 **Invariant:** FC-3 ## Context @@ -14,7 +18,7 @@ The deployed cloud architecture runs this TypeScript package in a stateless Node `@comfyorg/comfy-multi-player` is the one implementation of op-to-document semantics. -- Browser and Node host consume the same package at the same exact published npm version (ADR-006). +- Browser and Node host consume the same package at the same exact published npm version (ADR-DISTRIBUTION-0006). - Do not add op-to-document logic in Go or another language. - Keep applier, projection, and mint pure and portable, with `yjs` as the only runtime dependency. - If a second implementation is ever unavoidable, record an invariant exception first and require shared golden-vector parity before use. diff --git a/docs/adr/0002-systems-apis-data-flows.md b/docs/adr/ARCHITECTURE-0002-systems-apis-data-flows.md similarity index 97% rename from docs/adr/0002-systems-apis-data-flows.md rename to docs/adr/ARCHITECTURE-0002-systems-apis-data-flows.md index 67091a47..895759fb 100644 --- a/docs/adr/0002-systems-apis-data-flows.md +++ b/docs/adr/ARCHITECTURE-0002-systems-apis-data-flows.md @@ -1,7 +1,11 @@ -# ADR 0002 — In-App Agent: systems, public APIs, and data flows (cloud and local) +# ADR-ARCHITECTURE-0002: In-App Agent systems, public APIs, and data flows + +Date: 2026-08-20 + +## Status + +Proposed -- Status: Draft (for review) -- Date: 2026-08-20 - Verified against: `Comfy-Org/cloud` @ `070dce96` (`origin/main`, 2026-08-21) — `services/agent/ARCHITECTURE.md`, `common/websocket/messages/crdt.go`, `.github/workflows/multiplayer-contract.yml`, `services/agent/dochost/`. @@ -11,7 +15,7 @@ > **STALENESS FLAG (2026-08-22):** Cloud `main` has advanced to `84890f9a`; spot checks at that > revision still confirm the listed REST routes, CRDT frame types/caps, event schema, and doc-host, > but this document has not been exhaustively re-verified against every intervening cloud change. -- Related: ADR 0001 (op-based CRDT for graph state), `docs/multiplayer-schema.md`, +- Related: ADR-CRDT-0001 (op-based CRDT for graph state), `docs/multiplayer-schema.md`, `docs/api-contract-proposal.md` ## Context @@ -39,7 +43,7 @@ browser imports it, and the cloud backend runs the **same** package inside a sma > **STALENESS FLAG (2026-08-22):** The dependency-source claim is obsolete. The package is now > published publicly as `@comfyorg/comfy-multi-player@0.1.0`; cloud `main` consumes version `0.1.0` > from `services/agent/dochost/package.json`, and the frontend integration branch consumes the -> published package as well. ADR-004's “git SHA; no registry publish yet” policy is pending separate +> published package as well. ADR-DISTRIBUTION-0004's “git SHA; no registry publish yet” policy is pending separate > supersession under `CMP-ADR004-SUPERSEDE`. ## Cloud topology (verified) diff --git a/docs/decisions/ADR-003-catalog-sha-at-mint.md b/docs/adr/CATALOG-0003-catalog-sha-at-mint.md similarity index 93% rename from docs/decisions/ADR-003-catalog-sha-at-mint.md rename to docs/adr/CATALOG-0003-catalog-sha-at-mint.md index 49125318..4b67f496 100644 --- a/docs/decisions/ADR-003-catalog-sha-at-mint.md +++ b/docs/adr/CATALOG-0003-catalog-sha-at-mint.md @@ -1,7 +1,11 @@ -# ADR-003: Catalog pinned by sha256 at mint +# ADR-CATALOG-0003: Catalog pinned by sha256 at mint + +Date: 2026-08-20 + +## Status + +Accepted -**Status:** Accepted -**Date:** 2026-08-20 **Invariants:** KA-12, FC-10 ## Context diff --git a/docs/adr/0001-op-based-crdt-v1.md b/docs/adr/CRDT-0001-op-based-crdt-v1.md similarity index 95% rename from docs/adr/0001-op-based-crdt-v1.md rename to docs/adr/CRDT-0001-op-based-crdt-v1.md index d66cb41f..7537bb8e 100644 --- a/docs/adr/0001-op-based-crdt-v1.md +++ b/docs/adr/CRDT-0001-op-based-crdt-v1.md @@ -1,7 +1,13 @@ -# ADR-0001: Op-based CRDT for in-app-agent graph state (V1) +# ADR-CRDT-0001: Op-based CRDT for in-app-agent graph state (V1) + +Date: 2026-08-17 + +## Status + +Proposed + +Status note: aligned in the 2026-08-17 CRDT handoff sync. -**Status:** Proposed (aligned 2026-08-17 CRDT handoff sync) -**Date:** 2026-08-17 **Deciders:** Kishore Shimikeri (BE/CRDT), Christian Byrne (FE) ## Context @@ -40,7 +46,7 @@ authority" is therefore not a design axis; the axes that matter are (a) applier 4. **Persistence is separate from merge.** Every writer applies then writes; ensure no pending ops before a write; never pull the DB as a higher authority (that collapses back to de-facto full-document last-writer-wins). -5. **Logical-clock decision superseded.** V1 originally deferred a logical clock. [ADR-0005](0005-lamport-ordering-v1-migration.md) +5. **Logical-clock decision superseded.** V1 originally deferred a logical clock. [ADR-ORDERING-0005](ORDERING-0005-lamport-ordering-v1-migration.md) supersedes that choice: producers mint `base_version` as a durable, creator-owned Lamport counter, while the total winner key remains `[base_version, actor, op_id]`. See `src/types.ts` and `src/stamps.ts`. @@ -50,7 +56,7 @@ authority" is therefore not a design axis; the axes that matter are (a) applier > **STALENESS FLAG (2026-08-22):** The package now also exports a constrained read-only snapshot > surface from `src/read.ts`; it returns deep-frozen plain data and applies the KA-11 schema read - > gate rather than exposing mutable Yjs handles. See PR #55 (ADR-005) and the A12 schema-guard + > gate rather than exposing mutable Yjs handles. See PR #55 (ADR-API-0005) and the A12 schema-guard > correction in PR #76. 7. **Conflict UX disabled for V1** (conflicts are now node-level, not full-doc); re-derive later. @@ -96,7 +102,7 @@ flowchart LR re-minted). - **Ordering is independent of arrival order.** The canonical winner of two concurrent ops is computed from the op stamp `[base_version, actor, op_id]`, which every replica evaluates - identically offline — never from receive order. [ADR-0005](0005-lamport-ordering-v1-migration.md) + identically offline — never from receive order. [ADR-ORDERING-0005](ORDERING-0005-lamport-ordering-v1-migration.md) supersedes V1's scalar-cursor design: `base_version` is now a durable, creator-owned Lamport counter; `actor` and `op_id` remain deterministic tie-breakers. Convergence tests must deliver concurrent ops in both arrival orders and assert an identical winner. @@ -156,7 +162,7 @@ flowchart LR deployments, multi-agent replay, offline and double-offline all remain reachable from the V1 shape. Ops give replay, observability, and cheap deltas. - **Cost:** raw-ops persistence needs new DB tables; reconnect seeding is naive in V1; conflict UX - is deferred. The original logical-clock deferral was superseded by ADR-0005. + is deferred. The original logical-clock deferral was superseded by ADR-ORDERING-0005. - **Non-goals for V1:** vector clock, node-level conflict UX, separate-repo extraction of the applier (the package boundary is kept, but extraction into a standalone repo is not required yet). @@ -179,5 +185,5 @@ flowchart LR convenience, not a conflict authority. - **Headless peer** — the agent replica running with no browser attached. - **base_version** — the numeric element of the winner key; originally a V1 scalar version pointer, - now a durable, creator-owned Lamport counter under ADR-0005. + now a durable, creator-owned Lamport counter under ADR-ORDERING-0005. - **LWW** — last-writer-wins; here resolved by the op stamp, never by client-id or a DB read. diff --git a/docs/decisions/ADR-022-durable-link-intent.md b/docs/adr/CRDT-LINKS-0022-durable-link-intent.md similarity index 98% rename from docs/decisions/ADR-022-durable-link-intent.md rename to docs/adr/CRDT-LINKS-0022-durable-link-intent.md index b360f58c..f7925b28 100644 --- a/docs/decisions/ADR-022-durable-link-intent.md +++ b/docs/adr/CRDT-LINKS-0022-durable-link-intent.md @@ -1,7 +1,11 @@ -# ADR-022: Preserve durable link intent across node-presence races +# ADR-CRDT-LINKS-0022: Preserve durable link intent across node-presence races + +Date: 2026-09-03 + +## Status + +Accepted -- **Status:** Accepted -- **Date:** 2026-09-03 - **Depends on:** [Amendment A7](../multiplayer-schema.md#amendment-a7--2026-08-21--stamp-gated-node-presence-canonical-autogrow-naming-scoped-clear-issue-11) (node presence), [Amendment A18](../multiplayer-schema.md#amendment-a18--2026-08-30--normalized-stamped-link-identity) (normalized link identity) - **Implemented by:** [#206](https://github.com/Comfy-Org/comfy-multi-player/pull/206), [#196](https://github.com/Comfy-Org/comfy-multi-player/pull/196), and [#243](https://github.com/Comfy-Org/comfy-multi-player/pull/243) diff --git a/docs/adr/0004-incarnation-namespaced-stamps.md b/docs/adr/CRDT-STAMPS-0004-incarnation-namespaced-stamps.md similarity index 96% rename from docs/adr/0004-incarnation-namespaced-stamps.md rename to docs/adr/CRDT-STAMPS-0004-incarnation-namespaced-stamps.md index 97726ec7..6923f250 100644 --- a/docs/adr/0004-incarnation-namespaced-stamps.md +++ b/docs/adr/CRDT-STAMPS-0004-incarnation-namespaced-stamps.md @@ -1,7 +1,11 @@ -# ADR-0004: Namespace widget stamps by node incarnation +# ADR-CRDT-STAMPS-0004: Namespace widget stamps by node incarnation + +Date: 2026-08-28 + +## Status + +Accepted -**Status:** Accepted -**Date:** 2026-08-28 **Decision:** DQ-11, option (c) ## Context diff --git a/docs/decisions/ADR-016-dq11-incarnation-namespaced-stamps.md b/docs/adr/CRDT-STAMPS-0016-dq11-incarnation-namespaced-stamps.md similarity index 98% rename from docs/decisions/ADR-016-dq11-incarnation-namespaced-stamps.md rename to docs/adr/CRDT-STAMPS-0016-dq11-incarnation-namespaced-stamps.md index eac26ca3..ca1d742b 100644 --- a/docs/decisions/ADR-016-dq11-incarnation-namespaced-stamps.md +++ b/docs/adr/CRDT-STAMPS-0016-dq11-incarnation-namespaced-stamps.md @@ -1,7 +1,11 @@ -# ADR-016: Namespace widget LWW stamps by node incarnation +# ADR-CRDT-STAMPS-0016: Namespace widget LWW stamps by node incarnation + +Date: 2026-08-28 + +## Status + +Accepted -**Status:** accepted -**Date:** 2026-08-28 **Decider:** Christian Byrne **Decision queue:** DQ-11, option (c) diff --git a/docs/decisions/ADR-004-consumers-pin-by-sha-no-registry-yet.md b/docs/adr/DISTRIBUTION-0004-consumers-pin-by-sha-no-registry-yet.md similarity index 88% rename from docs/decisions/ADR-004-consumers-pin-by-sha-no-registry-yet.md rename to docs/adr/DISTRIBUTION-0004-consumers-pin-by-sha-no-registry-yet.md index 75c20548..8aeaea8c 100644 --- a/docs/decisions/ADR-004-consumers-pin-by-sha-no-registry-yet.md +++ b/docs/adr/DISTRIBUTION-0004-consumers-pin-by-sha-no-registry-yet.md @@ -1,14 +1,20 @@ -# ADR-004: Consumers pin by git SHA; no registry publish yet +# ADR-DISTRIBUTION-0004: Consumers pin by git SHA; no registry publish yet + +Date: 2026-08-20 + +## Status + +Superseded + +Superseded by [ADR-DISTRIBUTION-0006](DISTRIBUTION-0006-publish-to-npm-pin-exact-versions.md). -**Status:** Superseded by [ADR-006](ADR-006-publish-to-npm-pin-exact-versions.md) -**Date:** 2026-08-20 **Invariant:** KA-1, FC-3 (both hosts run the *same* applier bytes) ## Context Both hosts of this document — the browser (ComfyUI frontend) and the stateless Node doc-host sidecar in cloud — must run the identical op-to-document -implementation (ADR-001). Consumers therefore need a way to depend on this +implementation (ADR-APPLIER-0001). Consumers therefore need a way to depend on this package that makes "same bytes on both hosts" mechanically checkable, without prematurely committing to a registry and publish pipeline while the schema and op vocabulary are still stabilizing. @@ -30,10 +36,10 @@ Verified 2026-08-20 (frontend `poc/fe-crdt-follower`, PR #15457): `project`, because a follower never writes the shared doc (KA-6). Consuming the package for *types and layout* does not imply running the applier. - **Amended 2026-08-20 (see [ADR-005](ADR-005-read-only-snapshot-surface.md)):** + **Amended 2026-08-20 (see [ADR-API-0005](API-0005-read-only-snapshot-surface.md)):** that bullet describes the surface at the pinned SHA `6793d754`. Issue #18 - removed most doc-layout helpers from the entrypoint; the ADR-004 follower trio - remains public for compatibility. ADR-005 adds `readGraph()` as the safer + removed most doc-layout helpers from the entrypoint; the ADR-DISTRIBUTION-0004 follower trio + remains public for compatibility. ADR-API-0005 adds `readGraph()` as the safer migration target: unlike `nodesMap`, it returns plain frozen data. **With one caveat a migrating follower must handle:** `nodesMap` never throws, and `readGraph` does — it carries the KA-11 read gate (Amendment A12), so a @@ -52,7 +58,7 @@ Consumers depend on this package by **immutable git SHA**, and the package is - Pin by SHA: `npm install github:Comfy-Org/comfy-multi-player#` (pnpm: `github:Comfy-Org/comfy-multi-player#`). - The frontend and the server MUST pin the same SHA. This is load-bearing for - outcome agreement, not just hygiene (ADR-001; README "Install"). + outcome agreement, not just hygiene (ADR-APPLIER-0001; README "Install"). - A git dependency runs this package's `prepare` script to build `dist` on install. Consumers whose package manager gates install-time build scripts must allow this build explicitly. For pnpm this is an `allowBuilds` entry in diff --git a/docs/decisions/ADR-006-publish-to-npm-pin-exact-versions.md b/docs/adr/DISTRIBUTION-0006-publish-to-npm-pin-exact-versions.md similarity index 92% rename from docs/decisions/ADR-006-publish-to-npm-pin-exact-versions.md rename to docs/adr/DISTRIBUTION-0006-publish-to-npm-pin-exact-versions.md index 35487a26..32e42764 100644 --- a/docs/decisions/ADR-006-publish-to-npm-pin-exact-versions.md +++ b/docs/adr/DISTRIBUTION-0006-publish-to-npm-pin-exact-versions.md @@ -1,13 +1,17 @@ -# ADR-006: Publish to npm; consumers pin exact published versions +# ADR-DISTRIBUTION-0006: Publish to npm; consumers pin exact published versions + +Date: 2026-08-22 + +## Status + +Accepted -**Status:** Accepted -**Date:** 2026-08-22 **Invariant:** KA-1, FC-3 (both hosts run the *same* applier bytes) -**Supersedes:** ADR-004 +**Supersedes:** ADR-DISTRIBUTION-0004 ## Context -ADR-004 chose immutable git-SHA dependencies while the package contract was +ADR-DISTRIBUTION-0004 chose immutable git-SHA dependencies while the package contract was stabilizing and no registry release existed. The package is now published to npm as `@comfyorg/comfy-multi-player@0.1.0`, so consumers no longer need a git checkout or an install-time `prepare` build. @@ -29,7 +33,7 @@ version was `0.1.0`; the repository manifest is currently `0.2.1`. Version updates remain explicit, reviewable changes in each consumer. The frontend, cloud doc-host, and examples MUST use the same exact package version -where they rely on identical applier behavior (ADR-001). +where they rely on identical applier behavior (ADR-APPLIER-0001). ## Consequences diff --git a/docs/adr/0003-lifecycle-and-reconnect-semantics.md b/docs/adr/LIFECYCLE-0003-lifecycle-and-reconnect-semantics.md similarity index 94% rename from docs/adr/0003-lifecycle-and-reconnect-semantics.md rename to docs/adr/LIFECYCLE-0003-lifecycle-and-reconnect-semantics.md index 8e56b312..8646dc41 100644 --- a/docs/adr/0003-lifecycle-and-reconnect-semantics.md +++ b/docs/adr/LIFECYCLE-0003-lifecycle-and-reconnect-semantics.md @@ -1,7 +1,10 @@ -# ADR-0003: Lifecycle and reconnect semantics — three lifetimes, atomic batches, resync as authority +# ADR-LIFECYCLE-0003: Lifecycle and reconnect semantics — three lifetimes, atomic batches, resync as authority -**Status**: accepted -**Date**: 2026-08-21 +Date: 2026-08-21 + +## Status + +Accepted ## Context @@ -70,5 +73,5 @@ CRDT source `cloud@8d062714` — since merged to `main` (superset; re-pointed 20 - `reports/lifecycle/*.mmd` (diagram sources), especially `01-three-lifetimes.mmd`, `02-agent-turn.mmd`, `04-reconnect-catchup.mmd` - `cloud@8d062714`: `services/agent/internal/docstore/docstore.go:101-131` (CAS), `services/agent/internal/loop/crdt.go:401-455` (lost-CAS re-derivation). On `main@070dce96` (2026-08-21) these live at `docstore.go:109-129` (`Advance` CAS, `ErrSeqConflict`) and `crdt.go:416-457`. -- ADR-004 (state authority & sync), ADR-007 (op-based CRDT V1), ADR-008 (local persistence) +- ADR-DISTRIBUTION-0004 (state authority & sync), ADR-API-0007 (op-based CRDT V1), ADR-OBSERVABILITY-0008 (local persistence) - Persistence & Data Model subpage: https://www.notion.so/3c36d73d365081759641d9b80600f9cc diff --git a/docs/decisions/ADR-008-caller-owned-event-sink.md b/docs/adr/OBSERVABILITY-0008-caller-owned-event-sink.md similarity index 93% rename from docs/decisions/ADR-008-caller-owned-event-sink.md rename to docs/adr/OBSERVABILITY-0008-caller-owned-event-sink.md index 2f7f0501..90636124 100644 --- a/docs/decisions/ADR-008-caller-owned-event-sink.md +++ b/docs/adr/OBSERVABILITY-0008-caller-owned-event-sink.md @@ -1,8 +1,14 @@ -# ADR-008: caller-owned, explicitly passed event sink +# ADR-OBSERVABILITY-0008: caller-owned, explicitly passed event sink -- Status: Accepted (Option B approved in `christian-byrne/blocked-on-christian#121`) -- Date: 2026-08-29 -- Invariants: KA-3, KA-4, KA-11; FC-3; ADR-021 statelessness boundary +Date: 2026-08-29 + +## Status + +Accepted + +Status note: Option B was approved in `christian-byrne/blocked-on-christian#121`. + +- Invariants: KA-3, KA-4, KA-11; FC-3; ADR-ORDERING-0021 statelessness boundary ## Context @@ -12,7 +18,7 @@ need structured notice of rejected input and unexpected failures so the frontend and the Node doc host can forward them across its HTTP boundary to Go structured logs/`agenttel`. cmp must not import a telemetry SDK or know either host. -ADR-021 made the state boundary explicit: process-global mutable state in cmp is not an acceptable +ADR-ORDERING-0021 made the state boundary explicit: process-global mutable state in cmp is not an acceptable substitute for caller-owned state. The `check:stateless` gate enforces this boundary. ## Decision model @@ -24,7 +30,7 @@ and the ability to preserve a language-agnostic contract. This matches the frontend service's register/dispatch ergonomics and requires no applier signature change. It also makes importing cmp mutate process-wide behavior, creates test and multi-tenant -cross-talk, and directly contradicts ADR-021's statelessness decision. Rejected. +cross-talk, and directly contradicts ADR-ORDERING-0021's statelessness decision. Rejected. ### Option B: explicitly pass a sink in caller-owned call context @@ -60,7 +66,7 @@ change an outcome, mutation, abort-remainder behavior, or thrown error. Call sites test for `eventSink` before constructing the event. With no sink, the path performs only the branch and allocates no telemetry object. No `EXCEPTIONS.md` entry is needed: this preserves -KA-3 and ADR-021's statelessness boundary and adds no runtime dependency. +KA-3 and ADR-ORDERING-0021's statelessness boundary and adds no runtime dependency. ## Versioned wire schema diff --git a/docs/decisions/ADR-032-set-node-field-op.md b/docs/adr/OPS-NODE-0032-set-node-field-op.md similarity index 91% rename from docs/decisions/ADR-032-set-node-field-op.md rename to docs/adr/OPS-NODE-0032-set-node-field-op.md index 5216e1ec..fd24b928 100644 --- a/docs/decisions/ADR-032-set-node-field-op.md +++ b/docs/adr/OPS-NODE-0032-set-node-field-op.md @@ -1,7 +1,13 @@ -# ADR-032: Field-addressed node metadata writes +# ADR-OPS-NODE-0032: Field-addressed node metadata writes + +Date: 2026-09-21 + +## Status + +Accepted + +Status note: the protocol shape remains provisional until comfy-cli adopts it. -- **Status:** Accepted; protocol shape remains provisional until comfy-cli adopts it -- **Date:** 2026-09-21 - **Decider:** Christian Byrne ## Context diff --git a/docs/adr/0005-lamport-ordering-v1-migration.md b/docs/adr/ORDERING-0005-lamport-ordering-v1-migration.md similarity index 90% rename from docs/adr/0005-lamport-ordering-v1-migration.md rename to docs/adr/ORDERING-0005-lamport-ordering-v1-migration.md index 81f22796..37aa1e2c 100644 --- a/docs/adr/0005-lamport-ordering-v1-migration.md +++ b/docs/adr/ORDERING-0005-lamport-ordering-v1-migration.md @@ -1,6 +1,12 @@ -# ADR-0005: Direct Lamport counter semantics +# ADR-ORDERING-0005: Direct Lamport counter semantics -Status: accepted for private alpha. +Date: 2026-08-29 + +## Status + +Accepted + +Status note: accepted for private alpha. ## Decision diff --git a/docs/decisions/ADR-020-lamport-vs-vector-vs-base-version.md b/docs/adr/ORDERING-0020-lamport-vs-vector-vs-base-version.md similarity index 96% rename from docs/decisions/ADR-020-lamport-vs-vector-vs-base-version.md rename to docs/adr/ORDERING-0020-lamport-vs-vector-vs-base-version.md index 596439c7..071a3495 100644 --- a/docs/decisions/ADR-020-lamport-vs-vector-vs-base-version.md +++ b/docs/adr/ORDERING-0020-lamport-vs-vector-vs-base-version.md @@ -1,14 +1,20 @@ -# ADR-020: Lamport vs vector clocks vs `base_version` for graph ordering +# ADR-ORDERING-0020: Lamport vs vector clocks vs `base_version` for graph ordering + +Date: 2026-08-29 + +## Status + +Proposed + +Status note: Christian rules; pending shadow-comparison verification. -**Status:** Proposed (Christian rules; pending shadow-comparison verification) -**Date:** 2026-08-29 **Decider:** Christian Byrne **Verification owner:** shadow-comparison lane -> **Mirror note (superseded in part):** [ADR-021](ADR-021-doc-derived-lamport-clock-store.md) +> **Mirror note (superseded in part):** [ADR-ORDERING-0021](ORDERING-0021-doc-derived-lamport-clock-store.md) > (accepted) supersedes and narrows this ADR to a concrete doc-derived Lamport clock store. > The `Proposed` status and shadow-comparison verification gate below are preserved as the -> historical decision record; the current decision state is ADR-021 together with the +> historical decision record; the current decision state is ADR-ORDERING-0021 together with the > portability constraints (KA-2) and foreclose rules (FC-2, FC-9) it operates under. ## Context @@ -24,7 +30,7 @@ The decision is not whether the package should grow a second applier. There is o portable `@comfyorg/comfy-multi-player` applier. At pinned cmp commit [`8636af3e`](https://github.com/Comfy-Org/comfy-multi-player/tree/8636af3e42e1f81d942bd861aa604f770de73769), `clock.ts` contains pure Lamport helpers and a `LamportClockStore` interface; state is supplied by -the caller. cmp ADR-0005 settles the package shape: Lamport is the smallest creator-owned clock, +the caller. cmp ADR-ORDERING-0005 settles the package shape: Lamport is the smallest creator-owned clock, the total key is `[counter, actor, op_id]`, there is no concurrency detection, and there is no schema-v3 or compatibility reader. This ADR is the program-level ordering and rollback decision; it must not contradict or replace that package decision. @@ -87,7 +93,7 @@ sequence may coordinate persistence, but it is not the permanent conflict key. ## Decision The proposal is to use **Lamport-as-merged for V1**, conditional on the shadow-comparison gate -below, while retaining the cmp ADR-0005 package contract. The Lamport numeric component remains +below, while retaining the cmp ADR-ORDERING-0005 package contract. The Lamport numeric component remains the creator-owned counter in the existing tuple `[counter, actor, op_id]`; `op_id` is minted once by the creator and never regenerated. DQ-11 incarnation-qualified target keys remain required: Lamport ordering chooses a winner *within* the correct incarnation namespace; it does not replace @@ -194,7 +200,7 @@ widens. Any rollout must preserve the host-is-writer and semantic-op replication - Workspace [ADR-007: Op-based CRDT for in-app-agent graph state](https://github.com/christian-byrne/in-app-agent-program/blob/main/decisions/ADR-007-op-based-crdt-v1.md) (workspace repo, `decisions/ADR-007-op-based-crdt-v1.md` — not mirrored here), especially its portability, semantic-op, and logical-clock constraints. -- [`comfy-multi-player` ADR-0005 at `8636af3e`](https://github.com/Comfy-Org/comfy-multi-player/blob/8636af3e42e1f81d942bd861aa604f770de73769/docs/adr/0005-lamport-ordering-v1-migration.md), +- [`comfy-multi-player` ADR-0005 at `8636af3e`](https://github.com/Comfy-Org/comfy-multi-player/blob/8636af3e42e1f81d942bd861aa604f770de73769/docs/adr/ORDERING-0005-lamport-ordering-v1-migration.md), the package-level Lamport decision this ADR preserves. - [DQ-10 Lamport feasibility evidence](https://github.com/christian-byrne/in-app-agent-program/blob/main/reports/spikes/dq10-lamport-feasibility.md) (workspace repo), including the DQ-11 conditional result and persistence-loss boundary. @@ -231,4 +237,3 @@ widens. Any rollout must preserve the host-is-writer and semantic-op replication - **LWW:** Last-writer-wins selection using a deterministic total ordering key. - **`op_id`:** The creator-minted immutable operation identifier used for idempotency and as the final ordering tie-break; retries never mint a replacement. - diff --git a/docs/decisions/ADR-021-doc-derived-lamport-clock-store.md b/docs/adr/ORDERING-0021-doc-derived-lamport-clock-store.md similarity index 96% rename from docs/decisions/ADR-021-doc-derived-lamport-clock-store.md rename to docs/adr/ORDERING-0021-doc-derived-lamport-clock-store.md index 35942dad..c98b27eb 100644 --- a/docs/decisions/ADR-021-doc-derived-lamport-clock-store.md +++ b/docs/adr/ORDERING-0021-doc-derived-lamport-clock-store.md @@ -1,9 +1,13 @@ -# ADR-021: Doc-derived Lamport clock store (winning stamps + reservations) - Option A locked +# ADR-ORDERING-0021: Doc-derived Lamport clock store (winning stamps + reservations) - Option A locked + +Date: 2026-08-29 + +## Status + +Accepted -- **Status:** Accepted -- **Date:** 2026-08-29 - **Decider:** Christian (in-thread ruling, approximately 12:20Z) -- **Supersedes:** narrows ADR-020 to a concrete mechanism; complements ADR-0004 and ADR-0005 +- **Supersedes:** narrows ADR-ORDERING-0020 to a concrete mechanism; complements ADR-CRDT-STAMPS-0004 and ADR-ORDERING-0005 ## Context diff --git a/docs/portability.md b/docs/adr/PORTABILITY-0001-op-layer-contract.md similarity index 96% rename from docs/portability.md rename to docs/adr/PORTABILITY-0001-op-layer-contract.md index e2c7440c..94c3377c 100644 --- a/docs/portability.md +++ b/docs/adr/PORTABILITY-0001-op-layer-contract.md @@ -1,4 +1,10 @@ -# Op-layer portability contract +# ADR-PORTABILITY-0001: Op-layer portability contract + +Date: 2026-08-19 + +## Status + +Accepted The TypeScript package is the reference implementation of semantic-op-to-Yjs-document behavior. `yjs` must remain its only production dependency root, and the built package must import in bare Node without reading or creating DOM globals. `npm run check:purity` enforces those KA-3 and FC-3 boundaries at the package level, and `npm run check:imports` enforces them per source module at the module-graph level. @@ -19,7 +25,7 @@ For `wire_layout`, a conforming runner must resolve the doc's root types by the **Not vectored, but normative:** the schema §10 read gate is a conformance obligation the manifest cannot express. The vectors are all `applyOps` cases, so a runner in another language can pass 100% of them while accepting a document with no readable `meta.schema_version` as current — precisely the fail-open KA-11 forbids. Until a schema-version rejection vector exists, a conforming reader must implement it from the prose: an unreadable or disagreeing `meta.schema_version` is rejected, and both the rejection and the current-version no-op leave the encoded document unchanged. -**The gate is now on TWO entrypoints, and the projection one is the load-bearing half (Amendment A5).** A3 refined `migrate()`, but nothing forces a caller through `migrate()` — so a port that implemented A3 faithfully and stopped there is still fail-open in the way that matters, because `project()` is what every consumer actually calls. A conforming reader must refuse an unreadable or non-current `meta.schema_version` **on the projection path**, before it reads any workflow content, and that refusal must leave the encoded document unchanged AND materialize no root type. The same sentence as `portability.md`'s standing warning applies here: a port could pass 100% of the golden vectors and still be fail-open on read. +**The gate is now on TWO entrypoints, and the projection one is the load-bearing half (Amendment A5).** A3 refined `migrate()`, but nothing forces a caller through `migrate()` — so a port that implemented A3 faithfully and stopped there is still fail-open in the way that matters, because `project()` is what every consumer actually calls. A conforming reader must refuse an unreadable or non-current `meta.schema_version` **on the projection path**, before it reads any workflow content, and that refusal must leave the encoded document unchanged AND materialize no root type. The standing warning applies here: a port could pass 100% of the golden vectors and still be fail-open on read. **Also not vectored, but normative:** how a runner counts *instances* of a subgraph definition for schema §5.3's "reject an interior write whose head definition is shared by more than one instance". An instance is a node whose `type` **resolves** to the definition, not a node whose `type` string equals the definition id. Four conditions, and the last two are the ones a re-implementation will get wrong: diff --git a/docs/decisions/ADR-002-ops-replication-unit.md b/docs/adr/REPLICATION-0002-ops-replication-unit.md similarity index 92% rename from docs/decisions/ADR-002-ops-replication-unit.md rename to docs/adr/REPLICATION-0002-ops-replication-unit.md index a6b33fbf..70b31839 100644 --- a/docs/decisions/ADR-002-ops-replication-unit.md +++ b/docs/adr/REPLICATION-0002-ops-replication-unit.md @@ -1,7 +1,11 @@ -# ADR-002: Ops are the replication unit; raw Yjs updates only host→follower +# ADR-REPLICATION-0002: Ops are the replication unit; raw Yjs updates only host→follower + +Date: 2026-08-20 + +## Status + +Accepted -**Status:** Accepted -**Date:** 2026-08-20 **Invariants:** KA-1, KA-6, FC-1 ## Context diff --git a/docs/decisions/ADR-009-fail-closed-op-validation.md b/docs/adr/VALIDATION-0009-fail-closed-op-validation.md similarity index 82% rename from docs/decisions/ADR-009-fail-closed-op-validation.md rename to docs/adr/VALIDATION-0009-fail-closed-op-validation.md index ee2445f4..90c5dfba 100644 --- a/docs/decisions/ADR-009-fail-closed-op-validation.md +++ b/docs/adr/VALIDATION-0009-fail-closed-op-validation.md @@ -1,7 +1,11 @@ -# ADR-009: Fail closed — validate the whole op before any mutation +# ADR-VALIDATION-0009: Fail closed — validate the whole op before any mutation + +Date: 2026-09-21 + +## Status + +Accepted -**Status:** Accepted -**Date:** 2026-09-21 **Invariants:** KA-4 **Issue:** #228 @@ -16,11 +20,11 @@ rule itself: - KA-4 states it as an applier invariant, enforced by tests, not as a decision with rationale and alternatives. -- [ADR-003](ADR-003-catalog-sha-at-mint.md) states the "no guessing" half of this rule, but scopes +- [ADR-CATALOG-0003](CATALOG-0003-catalog-sha-at-mint.md) states the "no guessing" half of this rule, but scopes it to catalog widget-name matching only: "Widget writes to uncatalogued classes fail closed and loudly," rejected as an alternative to "guess unknown widget layout... because silent mis-keying is worse than a loud failure." -- [ADR-007](ADR-007-discriminated-apply-outcomes.md) touches op rejection only as an outcome-shape +- [ADR-API-0007](API-0007-discriminated-apply-outcomes.md) touches op rejection only as an outcome-shape concern, and explicitly disclaims changing this rule: "Op classification and mutation semantics remain unchanged; only reporting changes." @@ -34,7 +38,7 @@ op's `op_id`, and the accepted value made the whole document unprojectable, not widget. The fix in PR #228 tightened validation back to exact catalog membership and added `test/mint-dynamic-combo-catalog-mismatch.test.ts` plus regression coverage asserting byte-identical `Y.encodeStateAsUpdate` and that `op_id` is not consumed on rejection. The gap the -incident exposed was not specific to catalog lookups; it was a validation path, outside ADR-003's +incident exposed was not specific to catalog lookups; it was a validation path, outside ADR-CATALOG-0003's narrower scope, that accepted a partially-guessed op. `connect` is the motivating general case: it touches the link tuple plus both endpoint slot references in one logical edit, and those three writes must succeed or fail together, not split into a partially-applied edge. @@ -57,17 +61,17 @@ it is or which specific check would reject it: resubmits the exact same op after a rejection is doing the correct thing, not working around a bug. -This generalizes ADR-003's catalog-specific "no guessing" clause to every graph op and every kind +This generalizes ADR-CATALOG-0003's catalog-specific "no guessing" clause to every graph op and every kind of validation failure, not only catalog/widget-name mismatches. It formalizes, at ADR level, the rule KA-4 already states as an invariant. -This decision does not change ADR-007's outcome-reporting shape, and it does not touch multi-op +This decision does not change ADR-API-0007's outcome-reporting shape, and it does not touch multi-op batch semantics. Today, when a batch of ops is submitted and one op is rejected, only the remaining (not-yet-processed) ops in that batch are rejected with it; already-applied ops in the batch keep their effect. Making batch submission fully transactional (all-or-nothing across the whole batch) is a separate, more disruptive question — it would require producers to submit only mutually-commutative or fully-independent ops, or accept that a late failure discards otherwise -valid earlier work — and is explicitly out of scope here. ADR-007's abort-remainder behavior is +valid earlier work — and is explicitly out of scope here. ADR-API-0007's abort-remainder behavior is unchanged by this ADR. ## Consequences @@ -77,10 +81,10 @@ unchanged by this ADR. enforced by tests and scattered ADR-scoped clauses. - A validation check for any new op type must be written to confirm its inputs against an authoritative source before writing, not to accept a plausible-looking but unconfirmed guess. - Reviewers can point at this ADR instead of re-deriving the rule from KA-4 and ADR-003 each time. -- ADR-003 remains the authority for the catalog-specific case; this ADR is the general rule it is + Reviewers can point at this ADR instead of re-deriving the rule from KA-4 and ADR-CATALOG-0003 each time. +- ADR-CATALOG-0003 remains the authority for the catalog-specific case; this ADR is the general rule it is an instance of. Neither document needs to restate the other's scope. -- ADR-007 remains the authority for outcome-reporting shape and for abort-remainder batch +- ADR-API-0007 remains the authority for outcome-reporting shape and for abort-remainder batch semantics; this ADR does not reopen either. - No code change accompanies this ADR. `validateWidgetName` and the KA-4 test suite (`test/ka4-rejection-byte-identity.test.ts`, `test/reject-no-mutation.regression.test.ts`, @@ -89,15 +93,15 @@ unchanged by this ADR. ## Alternatives considered -- **Leave the rule split across KA-4, ADR-003, and ADR-007.** Rejected: PR #228 was a real - violation that fell outside ADR-003's catalog-only scope and ADR-007's reporting-only scope, +- **Leave the rule split across KA-4, ADR-CATALOG-0003, and ADR-API-0007.** Rejected: PR #228 was a real + violation that fell outside ADR-CATALOG-0003's catalog-only scope and ADR-API-0007's reporting-only scope, which shows the split leaves gaps rather than merely duplicating text. - **Make multi-op batches fully transactional (abort the whole batch, not just the remainder, on any failure).** Rejected for this ADR by explicit decision: it would require agents to submit perfectly commutative or independent ops, is a significant user-facing behavior change from today's abort-remainder semantics, and is a separate question from the single-op contract this - ADR states. ADR-007's abort-remainder behavior stands as-is. + ADR states. ADR-API-0007's abort-remainder behavior stands as-is. - **Scope this rule to `connect` only, since that is the motivating multi-part op.** Rejected: the PR #228 incident that motivated writing this down was a `set_widget` validation gap, not a - `connect` gap, so scoping to one op type would repeat ADR-003's mistake of a narrower-than-needed + `connect` gap, so scoping to one op type would repeat ADR-CATALOG-0003's mistake of a narrower-than-needed rule. diff --git a/docs/decisions/ADR-031-insert-workflow-op.md b/docs/adr/WORKFLOW-0031-insert-workflow-op.md similarity index 94% rename from docs/decisions/ADR-031-insert-workflow-op.md rename to docs/adr/WORKFLOW-0031-insert-workflow-op.md index f0dc0f6d..1a16484e 100644 --- a/docs/decisions/ADR-031-insert-workflow-op.md +++ b/docs/adr/WORKFLOW-0031-insert-workflow-op.md @@ -1,7 +1,11 @@ -# ADR-031: cmp-owned, op-id-derived workflow-template insertion +# ADR-WORKFLOW-0031: cmp-owned, op-id-derived workflow-template insertion + +Date: 2026-09-11 + +## Status + +Accepted -- **Status:** Accepted -- **Date:** 2026-09-11 - **Decider:** Christian - **Source:** in-app-agent program ADR-031 and frozen FE #17501 head `8491ba33fa` diff --git a/docs/decisions/ADR-033-insert-workflow-numeric-link-ids.md b/docs/adr/WORKFLOW-0033-insert-workflow-numeric-link-ids.md similarity index 91% rename from docs/decisions/ADR-033-insert-workflow-numeric-link-ids.md rename to docs/adr/WORKFLOW-0033-insert-workflow-numeric-link-ids.md index b36945d1..48179335 100644 --- a/docs/decisions/ADR-033-insert-workflow-numeric-link-ids.md +++ b/docs/adr/WORKFLOW-0033-insert-workflow-numeric-link-ids.md @@ -1,13 +1,22 @@ -# ADR-033: numeric link ids for `insert_workflow` +# ADR-WORKFLOW-0033: numeric link ids for `insert_workflow` + +Date: 2026-09-22 + +## Status + +Accepted + +Status note: amended and accepted on 2026-09-23. The original decision shipped +a document-state-verified retry mint. The amendment replaces it with pure +derivation and was ratified after exact-head review and opposite-order +convergence coverage. The amendment section below is authoritative. -- **Status:** Amended and accepted — see "Amendment (2026-09-23)" below. The original decision (2026-09-22, below) shipped a document-state-verified retry mint; Christian Byrne's review of that revision (PR #245) found it broke link identity's order-independence and asked for either a fix plus explicit sign-off on the residual risk, or a return to pure derivation. This amendment takes the pure-derivation path and was ratified after exact-head review of that fix and its opposite-order convergence coverage. **The "Accepted" disposition below describes the ORIGINAL decision only** and is superseded by this accepted amendment. -- **Date:** 2026-09-22 (original), amended 2026-09-23 - **Decider:** Christian Byrne - **Source:** ComfyUI_frontend#18458 (interim 32-bit-hash review) and the Slack thread it was raised in; the amendment's source is Christian Byrne's PR #245 review (inline comment on `src/remap.ts:65`, review summary "Not merge-ready: link identity becomes arrival-order-dependent"). ## Context -ADR-031 remaps every id `insert_workflow` carries — node, link, group, and +ADR-WORKFLOW-0031 remaps every id `insert_workflow` carries — node, link, group, and nested-definition id — to a deterministic **string** derived from the op envelope id, graph scope, id kind, and original id (`insert:::link:`). That is a correct fit for a @@ -44,14 +53,14 @@ happens to read it. subgraph-definition interior scope, so the fix does not regress comfy-multi-player#230's `remapLinkIdArray`/definition-interior handling. Every other kind `insert_workflow` derives (node, group, definition) is -UNCHANGED: still the ADR-031 string, still a pure function of +UNCHANGED: still the ADR-WORKFLOW-0031 string, still a pure function of (`opId`, `scope`, `kind`, `original`) with no document-state dependency. The link-id mint is NOT a wider hash gambled to be "unlikely enough" — the same failure mode being fixed. It is: 1. **Hashed**: SHA-256 of the same `insert:::link:` - seed ADR-031 already uses, keeping 52 bits (well inside + seed ADR-WORKFLOW-0031 already uses, keeping 52 bits (well inside `Number.MAX_SAFE_INTEGER`) as the first candidate. 2. **Verified against every id the caller can see**, not assumed collision-free by width alone: the caller (`applier.ts`) passes `derivedLinkId` (via @@ -76,12 +85,12 @@ second op's mint sees the first op's already-committed numeric id in `persistedLinkIds` and retries past it — the exact cross-op collision the 32-bit interim hash reproduced. -## Deviation from KA-5 / ADR-031 +## Deviation from KA-5 / ADR-WORKFLOW-0031 Every other id `insert_workflow` derives is intentionally **pure**: a function of the op's own fields alone, with producers/the applier never inspecting document state to decide an id (KA-5's "IDs are collision-free -without coordination" and ADR-031's "Producers do not inspect document +without coordination" and ADR-WORKFLOW-0031's "Producers do not inspect document state or remap ids"). `derivedLinkId` breaks that purity for links, and only for links: a truly information-theoretic collision-free encoding of an unbounded set of possible (`opId`, link) pairs into a fixed 53-bit numeric @@ -119,7 +128,7 @@ package, KA-2) an accepted risk elsewhere in this same system. ## Amendment (2026-09-23): pure derivation, no document-state retry -**This amendment supersedes the "Decision" and "Deviation from KA-5 / ADR-031" +**This amendment supersedes the "Decision" and "Deviation from KA-5 / ADR-WORKFLOW-0031" sections above for the CURRENT behavior.** They are kept as written for history — they are what actually shipped in the original PR #245 revision — but `derivedLinkId` no longer works the way they describe. @@ -153,12 +162,12 @@ no longer accepts a `reservedLinkIds` parameter; `applier.ts`'s output — including every link's numeric id — on any replica, in any document state, regardless of what other ops have or have not been applied yet, at the top-level scope AND at every subgraph-definition interior scope. -This restores ADR-031's "producers do not inspect document state or remap +This restores ADR-WORKFLOW-0031's "producers do not inspect document state or remap ids" for links, closing the gap this ADR's original "Deviation" section opened. The mint also widens its candidate from 52 to the FULL safe-integer range: -it hashes the ADR-031 seed with SHA-256, takes 32 hex characters (128 bits, +it hashes the ADR-WORKFLOW-0031 seed with SHA-256, takes 32 hex characters (128 bits, comfortably enough to keep the reduction below close to uniform), and folds that down via `% (Number.MAX_SAFE_INTEGER)` into `[1, Number.MAX_SAFE_INTEGER]` — `[1, 2^53 - 1]`, all of it, rather than the narrower `2^52` window the @@ -243,7 +252,7 @@ claimed as fixed and not newly introduced by this amendment. now (any real collision reaches it, since nothing avoids one), not merely via deliberate id-space exhaustion — there is no more exhaustion to construct, because there is no more retry sequence. -- `test/insert-workflow.test.ts`'s "numeric link id minting (ADR-033, pure +- `test/insert-workflow.test.ts`'s "numeric link id minting (ADR-WORKFLOW-0033, pure derivation)" block and `test/insert-workflow-numeric-link-ids.regression.test.ts`'s "opposite-order convergence" block replace the retry/exhaustion-focused @@ -255,6 +264,6 @@ claimed as fixed and not newly introduced by this amendment. ## Glossary -- **Derived id:** ADR-031's deterministic string, `insert::::`. +- **Derived id:** ADR-WORKFLOW-0031's deterministic string, `insert::::`. - **Candidate:** the single hashed numeric value `derivedLinkId` computes for one link (post-amendment: there is exactly one, never retried). - **Reservation set (historical, pre-amendment only):** the ids the original retry-based mint call was required not to choose — persisted document ids plus ids already minted in the same call. Not part of the amended design. diff --git a/docs/decisions/ADR-038-cmp-owned-op-id-derived-insert-workflow-remapping.md b/docs/adr/WORKFLOW-0038-cmp-owned-op-id-derived-insert-workflow-remapping.md similarity index 93% rename from docs/decisions/ADR-038-cmp-owned-op-id-derived-insert-workflow-remapping.md rename to docs/adr/WORKFLOW-0038-cmp-owned-op-id-derived-insert-workflow-remapping.md index b345def8..8e2e175b 100644 --- a/docs/decisions/ADR-038-cmp-owned-op-id-derived-insert-workflow-remapping.md +++ b/docs/adr/WORKFLOW-0038-cmp-owned-op-id-derived-insert-workflow-remapping.md @@ -1,11 +1,15 @@ -# ADR-038: cmp-owned, op-id-derived ID remapping for `insert_workflow` +# ADR-WORKFLOW-0038: cmp-owned, op-id-derived ID remapping for `insert_workflow` + +Date: 2026-09-12 + +## Status + +Accepted -**Status**: accepted -**Date**: 2026-09-12 **Implementation-status**: implemented -**Renumbered**: was `ADR-031` from 2026-09-13 (`5a2355dc6b00`) to 2026-09-24 (`clean-5`). It -collided with `ADR-031-renderer-provided-layout-port-for-agent-materializer.md`, which was added -first (2026-09-10, `50a0a2752ebf`) and keeps the number. Any citation of "ADR-031" that concerns +**Renumbered**: was `ADR-WORKFLOW-0031` from 2026-09-13 (`5a2355dc6b00`) to 2026-09-24 (`clean-5`). It +collided with `ADR-WORKFLOW-0031-renderer-provided-layout-port-for-agent-materializer.md`, which was added +first (2026-09-10, `50a0a2752ebf`) and keeps the number. Any citation of "ADR-WORKFLOW-0031" that concerns `insert_workflow`, op-id-derived remapping, or the rejection of producer-side pre-remapping means this ADR. diff --git a/docs/api-contract-proposal.md b/docs/api-contract-proposal.md index b9042ff6..983d65b9 100644 --- a/docs/api-contract-proposal.md +++ b/docs/api-contract-proposal.md @@ -12,7 +12,7 @@ Two halves: Originally grounded against the source at `6793d75`, `docs/multiplayer-schema.md`, and the op vocabulary in comfy-cli. **Consumer-status correction, 2026-09-18:** the newer -[ADR-006](decisions/ADR-006-publish-to-npm-pin-exact-versions.md) records that +[ADR-DISTRIBUTION-0006](adr/DISTRIBUTION-0006-publish-to-npm-pin-exact-versions.md) records that the frontend, cloud `services/agent/dochost` sidecar, and `examples/dochost` consumed the published `0.1.0` package at its 2026-08-22 acceptance. Consumers pin exact published versions and must be upgraded deliberately. The former @@ -26,7 +26,7 @@ or revalidate every historical proposal below. ### D0. Workflow templates insert as one standalone op -**Accepted by ADR-031.** `insert_workflow` requires `nodes`; `links`, `groups`, and `definitions` +**Accepted by ADR-WORKFLOW-0031.** `insert_workflow` requires `nodes`; `links`, `groups`, and `definitions` are optional and default to empty. Producers send raw workflows. The applier remaps every carried id and internal reference deterministically from the op envelope id plus the original id and graph scope. Different ops therefore cannot collide or depend on arrival order, while exact replay derives diff --git a/docs/decisions/EXCEPTIONS.md b/docs/decisions/EXCEPTIONS.md index 506b6c32..d94982e9 100644 --- a/docs/decisions/EXCEPTIONS.md +++ b/docs/decisions/EXCEPTIONS.md @@ -18,9 +18,9 @@ is retained as history, not authorization to accept unprojectable writes. | 2026-08-21 (PROPOSED) | KA-4 | **Permanent convergence carve-outs**, schema §2.5 items 4-6 and 8 / Amendment A6, and the two mechanisms that generate them: a rejection can be arrival-order-dependent because its throw sits below an early return that consumes the `op_id` (a delete-wins return or the interior null return), or because its own verdict depends on mutable document state. Under §4 abort-remainder such a rejection also decides whether the rest of the batch applies, which turns a bookkeeping difference into a projection difference. Item 7's `add_node` exception was resolved by Amendment A7's node-presence stamp gate and its pin flipped positive. Every OP-ONLY precondition is hoisted above those returns and does NOT carve out. Measured in both orders with converging controls. | `src/applier.ts` `applyConnect` / `applySetWidget` / `resolveInteriorNode`; schema §2.5 items 4-6 and 8 | Owner: UNASSIGNED. Sunset PROPOSED, not agreed: revisit only through a new amendment; A6 rejects three alternatives with reasons, and closing a remaining item either re-opens issue #10 or changes concrete-input register semantics, requiring a comfy-cli vocabulary counterpart. | | 2026-08-21 (PROPOSED; scope widened 2026-08-27 by schema Amendment A15 — a NESTED promoted host write resolves its `instance_path` through the same guard and is rejected the same way) | KA-3 | This applier REJECTS an interior write into a shared subgraph definition where comfy-cli FORKS it, and it counts instances by resolved definition where comfy-cli's `engine._count_instances` matches the literal id string. Pre-declared by schema §5.3, which keeps forking OPEN; recorded here so the divergence has an owner and a sunset rather than living only in source comments. | `src/doc.ts` `countDefinitionInstances`/`definitionAliases`; `src/applier.ts` §5.3 guard | Owner: UNASSIGNED. Sunset PROPOSED, not agreed: the schema §5.3 forking amendment lands and both implementations adopt it. | | 2026-09-20 (PROPOSED) | KA-12 | **The pinned widget catalog is trusted as an UPPER, not exact, bound on a catalogued class's `widget_order` (BE-9176).** The catalog acquisition this package receives (comfy-cli `Graph.widget_order_default`, a different repo on a different release cycle) expands a `COMFY_DYNAMICCOMBO_V3` dynamic combo at its FIRST declared key only, so a real node selecting any other key has a `widgets_values` longer than the pinned order — a real, reported failure (Get Template on the Magnific Skin Enhancer template, `test/mint-dynamic-combo-catalog-mismatch.test.ts`), not a hypothetical one. Two consuming-boundary workarounds, not a catalog fix: (1) `doc.ts`'s `widgetsToYMap`/`createNodeMap` no longer reject an overrun `widgets_values` — the entries past `widget_order.length` are named positionally (`overflowWidgetName`, e.g. `"_extra_3"`) instead of the whole node being lost, and `project.ts`'s `widgetsToPositional` reads the same shape back to its original index so the mint/project round trip still holds. **BOUNDED 2026-10-04 (BE-17528), after the overrun's index turned out to be caller-chosen and unbounded:** a 216-byte Yjs snapshot carrying one widget named `_extra_1000000` projected a 1,000,001-element array, because the index is read out of the NAME and the name arrives in document bytes rather than in an op, so neither `opBoundsRefusal` nor `validateWidgetName` is on the path (reported from doc-host review of `cloud`#10824, reproduced end to end through `/project` at HTTP 200). Both legs now refuse an index at or past `MAX_OVERFLOW_WIDGETS`, loudly rather than by skipping. The bound is ABSOLUTE rather than `order.length + N`: review of the first version showed the relative form moved under an ordinary dynamic-combo selector write, so one applied op could turn a projectable node into a permanently unprojectable one — the mint-then-refuse failure the two-leg design exists to prevent, caused by the guard. It equals `MAX_COLLECTION_ENTRIES` so it cannot refuse an overrun this package would itself mint from an op. The workaround is unchanged in kind — it is still the same value-blind positional naming — only its reach is now finite; (2) **WITHDRAWN 2026-09-21, see the correction above this table — retained as history, NOT as an active exception:** ~~`applier.ts`'s `validateWidgetName` accepts a dotted `set_widget` name (`"mode.skin_detail"`) as a plausible dynamic-combo sub-field write when its prefix (`"mode"`) IS a catalogued widget of the node's class, rather than rejecting every such write `unknown_widget`.~~ The surviving workaround (1) is a plausibility check on the one thing the pinned catalog CAN confirm (the name is a real, catalogued widget of this class, or an honestly-labelled overflow slot within a finite region), not a validation that the specific value or sub-field is correct for the node's current selection — that would need the same value-aware expansion the pinned catalog does not carry. | `src/doc.ts` `overflowWidgetName`/`parseOverflowWidgetName`/`overflowBoundRefusal`/`widgetsToYMap`; `src/limits.ts` `MAX_OVERFLOW_WIDGETS`; `src/project.ts` `positionalIndexOf`/`widgetsToPositional`; ~~`src/applier.ts` `isPlausibleDynamicComboSubfield`/`validateWidgetName`~~ (withdrawn, see above); `test/overflow-allocation-bound.regression.test.ts` | Owner: UNASSIGNED. Sunset PROPOSED, not agreed: revisit when the pinned catalog acquisition (comfy-cli `widget_order_for_node`) becomes value-aware for dynamic combos and `services/agent/internal/loop/widget_catalog.go` in `cloud` hands this package the node's actual selected-key expansion, at which point both workarounds become unreachable rather than merely unneeded. | -| 2026-08-21 (PROPOSED) | KA-11 | **The snapshot read surface's fail-closed gate is CONDITIONAL**: `src/read.ts` refuses a document carrying content under an unreadable schema, but returns its empty value for a document carrying nothing, where `project()` refuses that document too. Deliberate — ADR-004's follower reads a root-less document before its first frame and there is no content there to mis-key — but it is a read path that answers where a sibling read path throws, so it is recorded rather than left in source comments. Normative text: Amendment A12. The divergence is disposition-only; both paths use `readSchemaVersion` as the predicate. Mitigated by asking "carries content" against the struct store rather than the v1 root names, so a v2 that renamed its roots is refused rather than read as empty. | `src/read.ts` `assertSnapshotReadable`/`carriesContent`; schema §10 + Amendment A12 | Owner: UNASSIGNED. Sunset PROPOSED, not agreed: revisit when `SCHEMA_VERSION` first moves past 1, since a real v2 makes the disposition split observable to a deployed follower for the first time. | +| 2026-08-21 (PROPOSED) | KA-11 | **The snapshot read surface's fail-closed gate is CONDITIONAL**: `src/read.ts` refuses a document carrying content under an unreadable schema, but returns its empty value for a document carrying nothing, where `project()` refuses that document too. Deliberate — ADR-DISTRIBUTION-0004's follower reads a root-less document before its first frame and there is no content there to mis-key — but it is a read path that answers where a sibling read path throws, so it is recorded rather than left in source comments. Normative text: Amendment A12. The divergence is disposition-only; both paths use `readSchemaVersion` as the predicate. Mitigated by asking "carries content" against the struct store rather than the v1 root names, so a v2 that renamed its roots is refused rather than read as empty. | `src/read.ts` `assertSnapshotReadable`/`carriesContent`; schema §10 + Amendment A12 | Owner: UNASSIGNED. Sunset PROPOSED, not agreed: revisit when `SCHEMA_VERSION` first moves past 1, since a real v2 makes the disposition split observable to a deployed follower for the first time. | | ~~2026-08-27 (PROPOSED)~~ **RESOLVED 2026-08-28** | KA-3 | ~~**A promoted `connect` (`grow.promoted: true`, schema Amendment A15) is LWW-gated here on `("input", to_node, "grow", name)` and moves the materialized slot's `grow_id` to the winning link; comfy-cli's `_apply_connect` gates neither.**~~ **Sunset condition met: comfy-cli PR #818 (amendment v1.5, `ba0b0b92abcc86b01e8a6704d07088f92afe7aa7`) gates the same register, spelled with the FULL declared name on both sides, and moves `grow_id` to the winner.** Struck rather than deleted so the exception's life stays legible. Both spell the register identically (`_write_target`), so the divergence is in GATING only and is observable only under concurrency comfy-cli's single-writer apply never sees — the corpus session it generated replays green. Gating is required for §2.5 convergence (two connects into one declared input contend for one slot exactly as two concrete connects do, A1). | `src/applier.ts` `claimPromotedInput`; schema Amendment A15 | Owner: UNASSIGNED. Sunset PROPOSED, not agreed: comfy-cli `_lww_gate`s promoted grows on the same register (asked for in the PR that lands A15). | -| 2026-09-21 (APPROVED) | FC-10 | `set_node_field` is a package-local, provisional operation because post-creation title and flag changes otherwise have no non-clobbering write path. The owner requested consolidation on the general per-field architecture rather than the competing title-only operation. Its field set and value types are closed, its incarnation semantics match `set_widget`, and a language-neutral conformance session is included here; the upstream comfy-cli vocabulary has not yet adopted the kind. | `src/types.ts`, `src/applier.ts`, `src/stamps.ts`, `src/collab-trace.ts`; schema Amendment A21; ADR-032 | Owner: Christian Byrne. Sunset: amend comfy-cli's frozen vocabulary and pin the adopted definition here, reconciling the name/payload if upstream differs. | -| ~~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-09-21 (APPROVED) | FC-10 | `set_node_field` is a package-local, provisional operation because post-creation title and flag changes otherwise have no non-clobbering write path. The owner requested consolidation on the general per-field architecture rather than the competing title-only operation. Its field set and value types are closed, its incarnation semantics match `set_widget`, and a language-neutral conformance session is included here; the upstream comfy-cli vocabulary has not yet adopted the kind. | `src/types.ts`, `src/applier.ts`, `src/stamps.ts`, `src/collab-trace.ts`; schema Amendment A21; ADR-OPS-NODE-0032 | Owner: Christian Byrne. Sunset: amend comfy-cli's frozen vocabulary and pin the adopted definition here, reconciling the name/payload if upstream differs. | +| ~~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-WORKFLOW-0031'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-WORKFLOW-0033'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-WORKFLOW-0033 | 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-WORKFLOW-0031'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:::group:` 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. | diff --git a/docs/multiplayer-schema.md b/docs/multiplayer-schema.md index 3793420f..f3eaedba 100644 --- a/docs/multiplayer-schema.md +++ b/docs/multiplayer-schema.md @@ -44,7 +44,7 @@ Normative inputs, in precedence order: `fixtures/` (the evidence: three replayable sessions, six LWW vectors, the exported catalog, machine-captured findings). Every DECISION below cites the spike finding that forced it. -3. **ADR-022 / ADR-T8** — the local decision and accepted in-app-agent program +3. **ADR-WORKFLOW-0031 / ADR-T8** — the local decision and accepted in-app-agent program TDD add `insert_workflow` as the eighth implemented op without moving the pinned comfy-cli vocabulary. @@ -98,7 +98,7 @@ Winning stamps may have counter zero; reservations may not. Missing ledgers are empty, and neither a read nor a rejected admission creates them. Snapshot roots are typed without writing structs; sequence content is refused rather than silently viewed as an empty map. A malformed entry fails the entire scan. -Store wrappers for one caller-owned document still share ADR-021's weakly keyed +Store wrappers for one caller-owned document still share ADR-ORDERING-0021's weakly keyed transaction queue; no durable counter lives outside that document. ### 1.1 Per-node Y.Map @@ -968,7 +968,7 @@ and first-class definitions (§5.1) only shrink these): | `connect` (autogrow) | ~4 → **+2 under A7** | yes — `grow_id` identity keeps replays non-clobbering; A7 adds the `("grow", …)` stamp and the `("grow_request", …)` row, plus renames bounded by the family's concurrent-grow count | | `delete_node` | 4.7–5 / 6 → **+1 under A7** | yes — writes bounded by the node's degree, plus the `("node", id)` stamp; the dangling-reference *scan* is O(nodes) read cost, accepted | | `set_node_field` (package-local, A21) | 2 — one node/nested-flag write + one field stamp | yes | -| `clear` | O(doc), **+1 stamp per `removed_nodes` entry under A7** | **no — inherent.** Rare; standalone-only at the *authoring* surface (vocabulary §1.5: `apply_specs` rejects a spec batch containing it, code `workflow_clear_not_batchable`) — the *replay* surface (`apply_op` / `applyOps`, §4 abort-remainder) accepts it in any position and must, per `docs/portability.md`. SHOULD be host-mediated and never merged casually | +| `clear` | O(doc), **+1 stamp per `removed_nodes` entry under A7** | **no — inherent.** Rare; standalone-only at the *authoring* surface (vocabulary §1.5: `apply_specs` rejects a spec batch containing it, code `workflow_clear_not_batchable`) — the *replay* surface (`apply_op` / `applyOps`, §4 abort-remainder) accepts it in any position and must, per `docs/adr/PORTABILITY-0001-op-layer-contract.md`. SHOULD be host-mediated and never merged casually | --- @@ -1371,7 +1371,7 @@ A3 is not wrong; it is incomplete. This amendment supersedes A3's first rule bul - **An OLDER document is refused, not migrated in place.** `project()` is a read ANY replica may call, browser follower included; migrating inside it would make a read WRITE the shared document. (Stated as a rule about the API, not an observation about callers: no follower calls it - today — the frontend does not depend on this package at all, exactly as ADR-004 records. + today — the frontend does not depend on this package at all, exactly as ADR-DISTRIBUTION-0004 records. `follower-boundary.md` requires treating such an API as a blocking violation "even if current callers behave correctly".) That breaks KA-6/FC-5 outright (followers never write the shared doc), and a follower that self-migrated becomes an independently edited replica, which is the FC-1 raw-struct @@ -1437,7 +1437,7 @@ consumer repositories at their current revisions, not by analogy to A3: - **The op producer never constructs a document at all.** `comfy-cli` emits ops as plain JSON; it has no Yjs dependency, no `Y.Doc`, no snapshot handling. - **At the time of this amendment, the frontend did not consume this package.** That historical - observation does not establish present consumer compatibility. ADR-006 requires consumers to pin + observation does not establish present consumer compatibility. ADR-DISTRIBUTION-0006 requires consumers to pin the same exact published npm version; frontend source migration is deferred and package development remains in standalone `Comfy-Org/comfy-multi-player`. Future changes require fresh consumer checks. - **Two endpoints reach `project()`**, both in the doc-host sidecar: `/project` and `/apply` (whose @@ -1822,7 +1822,7 @@ over a v2 document. materializing no root — and **returns its empty value** for a document that carries **nothing**. -**Why the condition, since a conditional gate deserves a reason.** ADR-004's +**Why the condition, since a conditional gate deserves a reason.** ADR-DISTRIBUTION-0004's frontend follower reads a document that has no roots at all between construction and its first `doc_update` frame. There is no content there to mis-key, and KA-11 is a rule about MIS-PROJECTING an incompatible document, @@ -2185,7 +2185,7 @@ schema at that integration was v3; A20 advances it to v4. ## Amendment A19 — 2026-09-11 — atomic workflow-template insertion -ADR-031 adds the standalone-only `insert_workflow` op. Its payload is one +ADR-WORKFLOW-0031 adds the standalone-only `insert_workflow` op. Its payload is one authoritative workflow containing required top-level `nodes` and optional `links`, `groups`, and `definitions`. The applier deterministically remaps every inserted id from the immutable `op_id`, graph scope, id kind, and original id, @@ -2214,7 +2214,7 @@ in [frontend PR #16644](https://github.com/Comfy-Org/ComfyUI_frontend/pull/16644 identified `commitCounter()` writing non-write-target reservations into `__stamps`, which the public `readStamps()` returns as the LWW ledger. §1.6 moves those rows to `__clock_reservations`, preserving their identity and tuple. -ADR-021 Amendment CLK-3 records the clock contract and test scope. Prior QA is +ADR-ORDERING-0021 Amendment CLK-3 records the clock contract and test scope. Prior QA is historical evidence, not approval of this new layout. **Version decision (KA-11): bump 3 → 4.** A v3 clock scans only `__stamps` and @@ -2251,7 +2251,7 @@ whole-node `add_node` upsert is not an equivalent substitute: it rewrites the node payload and clears widget stamps, which can clobber concurrent work. This operation is package-local and provisional. comfy-cli's pinned -`op-vocabulary-v1.md` does not yet define it, so ADR-032 and the FC-10 row in +`op-vocabulary-v1.md` does not yet define it, so ADR-OPS-NODE-0032 and the FC-10 row in `docs/decisions/EXCEPTIONS.md` require reconciliation when upstream adopts a field-write operation. A language-neutral hand-authored session in `fixtures/golden-vectors/session-node-fields.session.jsonl` covers all four fields in the diff --git a/fixtures/README.md b/fixtures/README.md index f0d1a101..7ff3a830 100644 --- a/fixtures/README.md +++ b/fixtures/README.md @@ -1,7 +1,8 @@ # Replay fixtures The canonical cross-language parity contract is -`golden-vectors/conformance.json`; see [`docs/portability.md`](../docs/portability.md). +`golden-vectors/conformance.json`; see +[`ADR-PORTABILITY-0001`](../docs/adr/PORTABILITY-0001-op-layer-contract.md). It references the replay-corpus sessions below plus package-local vectors kept alongside the manifest, so every language runner consumes the same inputs and recorded outputs rather than maintaining a private corpus. @@ -101,7 +102,7 @@ asserts that, so "fixing" notes by adding catalog entries fails loudly instead of making the regression tests vacuous. `golden-vectors/session-node-fields.session.jsonl` is hand-authored because -`set_node_field` is the package-local FC-10 exception recorded by ADR-032; +`set_node_field` is the package-local FC-10 exception recorded by ADR-OPS-NODE-0032; comfy-cli cannot generate the operation until its vocabulary adopts the shape. It lives with the shared conformance manifest, rather than in the replay corpus, so other-language consumers cannot omit it without enrolling the provisional diff --git a/fixtures/golden-vectors/session-node-fields.session.jsonl b/fixtures/golden-vectors/session-node-fields.session.jsonl index 9d9ddcab..8b65e49c 100644 --- a/fixtures/golden-vectors/session-node-fields.session.jsonl +++ b/fixtures/golden-vectors/session-node-fields.session.jsonl @@ -1,4 +1,4 @@ -{"session":"session-node-fields","authored_by":"hand-authored package-local set_node_field conformance vector (ADR-032)","base_workflow":{"nodes":[{"id":11,"type":"LoadImage","pos":[10,20],"size":[200,100],"title":"Original","mode":0,"flags":{},"inputs":[],"outputs":[],"widgets_values":[]}],"links":[]},"workflow_final":{"nodes":[{"id":11,"type":"LoadImage","pos":[10,20],"size":[200,100],"title":"Renamed","mode":4,"flags":{"collapsed":true,"pinned":true},"inputs":[],"outputs":[],"widgets_values":[]}],"links":[]}} +{"session":"session-node-fields","authored_by":"hand-authored package-local set_node_field conformance vector (ADR-OPS-NODE-0032)","base_workflow":{"nodes":[{"id":11,"type":"LoadImage","pos":[10,20],"size":[200,100],"title":"Original","mode":0,"flags":{},"inputs":[],"outputs":[],"widgets_values":[]}],"links":[]},"workflow_final":{"nodes":[{"id":11,"type":"LoadImage","pos":[10,20],"size":[200,100],"title":"Renamed","mode":4,"flags":{"collapsed":true,"pinned":true},"inputs":[],"outputs":[],"widgets_values":[]}],"links":[]}} {"op":"set_node_field","op_id":"a0000000000000000000000000000001","actor":"human:qa:tab1","base_version":1,"stamp":[1,"human:qa:tab1"],"node_id":11,"field":"title","value":"Renamed"} {"op":"set_node_field","op_id":"b0000000000000000000000000000002","actor":"human:qa:tab1","base_version":2,"stamp":[2,"human:qa:tab1"],"node_id":11,"field":"mode","value":4} {"op":"set_node_field","op_id":"c0000000000000000000000000000003","actor":"human:qa:tab1","base_version":3,"stamp":[3,"human:qa:tab1"],"node_id":11,"field":"flags.collapsed","value":true} diff --git a/package.json b/package.json index 98087f03..dfc3e7ba 100644 --- a/package.json +++ b/package.json @@ -36,6 +36,7 @@ "check:purity": "node scripts/check-purity.mjs", "check:pins": "node scripts/check-pins.mjs", "check:profile-claims": "node scripts/check-profile-claims.mjs", + "check:adrs": "node scripts/check-adrs.mjs && node scripts/check-adr-links.mjs", "check:coderabbit": "node scripts/gen-coderabbit-config.mjs", "gen:coderabbit": "node scripts/gen-coderabbit-config.mjs --write", "check:imports": "node scripts/check-import-graph.mjs", diff --git a/scripts/check-adr-links.mjs b/scripts/check-adr-links.mjs new file mode 100644 index 00000000..33614212 --- /dev/null +++ b/scripts/check-adr-links.mjs @@ -0,0 +1,73 @@ +#!/usr/bin/env node + +import { execFileSync } from "node:child_process"; +import { existsSync, readFileSync } from "node:fs"; +import { dirname, join, relative, resolve, sep } from "node:path"; + +const root = process.cwd(); +const files = execFileSync( + "git", + ["ls-files", "--cached", "--others", "--exclude-standard", "-z"], + { encoding: "utf8" }, +) + .split("\0") + .filter(Boolean); +const markdownTargetPattern = /\]\(\s*]+)>?/g; +const markdownReferenceTargetPattern = /^[ \t]{0,3}\[[^\]]+\]:[ \t]*\s]+)>?/gm; +const repositoryAdrPattern = /docs\/adr\/[A-Za-z0-9._/-]+\.md/g; +const failures = []; + +function adrTargets(filename, text) { + const targets = new Map(); + const add = (target, index) => { + if (!targets.has(target)) { + targets.set(target, text.slice(0, index).split("\n").length); + } + }; + for (const match of text.matchAll(repositoryAdrPattern)) { + add(match[0], match.index); + } + for (const match of [ + ...text.matchAll(markdownTargetPattern), + ...text.matchAll(markdownReferenceTargetPattern), + ]) { + const rawTarget = match[1]; + if (!rawTarget || rawTarget.startsWith("#") || /^[a-z][a-z0-9+.-]*:/i.test(rawTarget)) { + continue; + } + let pathname; + try { + pathname = decodeURIComponent(rawTarget.split(/[?#]/, 1)[0] ?? ""); + } catch { + continue; + } + if (!pathname.endsWith(".md")) continue; + const resolved = resolve(root, dirname(filename), pathname); + const fromRoot = relative(root, resolved); + if (fromRoot === "docs/adr" || fromRoot.startsWith(`docs${sep}adr${sep}`)) { + add(fromRoot, match.index); + } + } + return targets; +} + +for (const filename of files) { + const absolute = join(root, filename); + if (!existsSync(absolute)) continue; + const contents = readFileSync(absolute); + if (contents.includes(0)) continue; + const text = contents.toString("utf8"); + for (const [target, line] of adrTargets(filename, text)) { + if (existsSync(join(root, target))) continue; + failures.push(`${filename}:${line} -> ${target}`); + } +} + +if (failures.length > 0) { + process.stderr.write( + `Dangling docs/adr references:\n${failures.join("\n")}\n`, + ); + process.exit(1); +} + +process.stdout.write("ADR link validation passed\n"); diff --git a/scripts/check-adrs.mjs b/scripts/check-adrs.mjs new file mode 100644 index 00000000..26372c8b --- /dev/null +++ b/scripts/check-adrs.mjs @@ -0,0 +1,77 @@ +#!/usr/bin/env node + +import { existsSync, readdirSync, readFileSync } from "node:fs"; +import { join } from "node:path"; + +const ADR_FILE_PATTERN = + /^([A-Z][A-Z0-9]*(?:-[A-Z][A-Z0-9]*)?-\d{4})-([a-z0-9]+(?:-[a-z0-9]+)*)\.md$/; + +export function validateAdrDirectory(directory) { + const entries = readdirSync(directory, { withFileTypes: true }); + const markdownFiles = entries + .filter((entry) => entry.isFile()) + .map((entry) => entry.name); + const invalidFiles = markdownFiles.filter( + (filename) => !ADR_FILE_PATTERN.test(filename), + ); + if (invalidFiles.length > 0) { + throw new Error(`Invalid ADR filenames: ${invalidFiles.join(", ")}`); + } + + const identifiers = []; + for (const filename of markdownFiles) { + const identifier = ADR_FILE_PATTERN.exec(filename)?.[1]; + if (!identifier) throw new Error(`Invalid ADR filename: ${filename}`); + identifiers.push(identifier); + + const contents = readFileSync(join(directory, filename), "utf8"); + if (!contents.split(/\r?\n/, 1)[0]?.startsWith(`# ADR-${identifier}: `)) { + throw new Error( + `${filename}: expected heading "# ADR-${identifier}: Title"`, + ); + } + const dateMatch = /^Date: (\d{4})-(\d{2})-(\d{2})$/m.exec(contents); + const statusIndex = contents.search(/^## Status[ \t]*$/m); + if (!dateMatch || statusIndex < 0 || (dateMatch.index ?? 0) > statusIndex) { + throw new Error(`${filename}: missing a valid Date field`); + } + const [, year, month, day] = dateMatch; + const parsed = new Date(Date.UTC(Number(year), Number(month) - 1, Number(day))); + if ( + parsed.getUTCFullYear() !== Number(year) || + parsed.getUTCMonth() !== Number(month) - 1 || + parsed.getUTCDate() !== Number(day) + ) { + throw new Error(`${filename}: missing a valid Date field`); + } + if ( + !/^## Status[ \t]*\r?\n(?:[ \t]*\r?\n)*(Proposed|Accepted|Rejected|Deprecated|Superseded)[ \t]*$/m.test( + contents, + ) + ) { + throw new Error(`${filename}: missing a valid Status value`); + } + } + + const duplicates = identifiers.filter( + (identifier, index) => identifiers.indexOf(identifier) !== index, + ); + if (duplicates.length > 0) { + throw new Error( + `Duplicate ADR identifiers: ${[...new Set(duplicates)].join(", ")}`, + ); + } + + for (const companion of entries.filter((entry) => entry.isDirectory())) { + if (!markdownFiles.includes(`${companion.name}.md`)) { + throw new Error( + `ADR companion directory has no matching ADR: ${companion.name}`, + ); + } + } +} + +if (process.argv[1] && existsSync(process.argv[1])) { + validateAdrDirectory(join(process.cwd(), "docs", "adr")); + process.stdout.write("ADR validation passed\n"); +} diff --git a/scripts/gen-coderabbit-config.mjs b/scripts/gen-coderabbit-config.mjs index 42ca8803..397fce1d 100644 --- a/scripts/gen-coderabbit-config.mjs +++ b/scripts/gen-coderabbit-config.mjs @@ -73,7 +73,7 @@ const configPath = join(root, ".coderabbit.yaml"); // counts blocks rather than content, so it catches a deletion and not a // one-for-one swap; the per-block content anchors in the profiles // (`claim: … :: .coderabbit.yaml`) are what cover that. -const MIN_BLOCKS = 5; +const MIN_BLOCKS = 6; const BEGIN = " # BEGIN GENERATED path_instructions"; const END = " # END GENERATED path_instructions"; diff --git a/src/applier.ts b/src/applier.ts index 9629412b..066ea073 100644 --- a/src/applier.ts +++ b/src/applier.ts @@ -415,7 +415,7 @@ export function canonicalOp(op: Op): string { * ~326 bytes/op against schema §4's ≈64 byte budget, which pushes a doc past * §4's 25%-of-bytes compaction trigger after a few dozen ops and turns every * crossing into a doc-epoch bump plus a full follower re-fetch. A 64-hex - * digest is ~96 bytes/op and still satisfies ADR-007's "existing `op_id` + * digest is ~96 bytes/op and still satisfies ADR-API-0007's "existing `op_id` * accepted only if canonical bytes are identical": a false accept needs two * different payloads under the SAME `op_id` whose SHA-256 also collides. */ @@ -426,7 +426,7 @@ export function opDigest(op: Op): string { /** * Validate and inspect stamped operations without reading or mutating a doc. * - * This is the storage preflight boundary from ADR-022. Canonical bytes and + * This is the storage preflight boundary from ADR-API-0022. Canonical bytes and * their digest are produced together through the same canonicalizer and * SHA-256 implementation as {@link applyOps}. Input order is preserved. * Identical repeated ids remain inspectable; reuse with different canonical @@ -1032,7 +1032,7 @@ function prepareInsertedWorkflow(op: InsertWorkflowOp): Record } validateRawGraphIds(wf["nodes"] as unknown[], (wf["links"] as unknown[] | undefined) ?? [], "workflow"); validateDefinitionInputs((subgraphs as unknown[] | undefined) ?? []); - // ADR-033 (amended): every id this op derives, including a link's numeric + // ADR-WORKFLOW-0033 (amended): every id this op derives, including a link's numeric // id, is a PURE function of the op's own content — no document state is // read here. See `remap.ts`'s `derivedLinkId` for why `LinkId` (a branded // `number`, unlike the string-or-number `NodeId`) needed a numeric mint at @@ -1217,7 +1217,7 @@ function updateInsertedWorkflowMeta( // `last_link_id` is deliberately NOT advanced from `linkWrites` (KA-5: // "document high-water marks are advisory, never allocators"). Every // inserted link's own id is now a large, arbitrary-looking derived number - // (ADR-033 — `remap.ts`'s `derivedLinkId`, needed only because ComfyUI_ + // (ADR-WORKFLOW-0033 — `remap.ts`'s `derivedLinkId`, needed only because ComfyUI_ // frontend's `LinkId` is a branded `number`), not a small sequential one, // so folding it into the high-water mark would pin the doc's bookkeeping // field to that value forever after the FIRST insert_workflow — a new, diff --git a/src/clock.ts b/src/clock.ts index cd51068c..ead003e0 100644 --- a/src/clock.ts +++ b/src/clock.ts @@ -32,7 +32,7 @@ const documentTransactionTails = new WeakMap>(); * Both ledgers are validated rather than silently skipped. Malformed state * must fail closed before a producer mints an unsafe counter. * Incarnation-qualified target keys all belong to this document lineage, so - * old node lives remain part of the observed floor (DQ-11 / ADR-021). A + * old node lives remain part of the observed floor (DQ-11 / ADR-ORDERING-0021). A * successful transaction writes `__clock_reservations` so the next transaction * observes it even before the producer's semantic op is applied. `__stamps` * remains exclusively the semantic write-target ledger exposed by readStamps. diff --git a/src/doc.ts b/src/doc.ts index 80be3bba..e4b93b4a 100644 --- a/src/doc.ts +++ b/src/doc.ts @@ -269,7 +269,7 @@ export function nodeIncarnation(node: Y.Map): string { * both address the document by these keys. Naming them once is what keeps the * two from drifting: a reader that hardcodes `"nodes"` while the layout moves * silently reads an empty graph, which is the failure mode a consumer - * hand-mirroring the schema has (ADR-004). + * hand-mirroring the schema has (ADR-DISTRIBUTION-0004). */ export const ROOT_NODES = "nodes"; export const ROOT_LINKS = "links"; diff --git a/src/index.ts b/src/index.ts index 1b091382..dc0acee5 100644 --- a/src/index.ts +++ b/src/index.ts @@ -24,7 +24,7 @@ * - `applyOps(doc, ops, catalog?)` — idempotent, LWW-gated, abort-remainder * op application (schema §2–§4); * - `inspectOps(ops)` — pure validation and canonical bytes/digest/stamp - * extraction for storage preflight (ADR-022); + * extraction for storage preflight (ADR-API-0022); * - `project(doc, catalog)` — canonical workflow JSON projection (schema §7), * fail-closed on a schema this package cannot read (KA-11); * - `migrate(doc, fromVersion)` — layout versioning, fail-closed (schema §10); @@ -37,12 +37,12 @@ * hosts that need conflict identity or watermark bookkeeping; * - evidence-only collaboration trace declarations and * `assertCollabReplayTraceV1` for fail-closed trace reads; - * - the ADR-004 follower read surface (`nodesMap`, `linksMap`, + * - the ADR-DISTRIBUTION-0004 follower read surface (`nodesMap`, `linksMap`, * `OPAQUE_WIDGETS_KEY`) for consuming the wire layout without applying ops; * - the safer snapshot surface (`readGraph`, `readMeta`, `docCatalogPin`, * `hasNode`, `hasAppliedOp`, `appliedOpIds`, `readApplied`, `readStamps`) for * consumers - * that do not need ADR-004's live follower handles — see src/read.ts; + * that do not need ADR-DISTRIBUTION-0004's live follower handles — see src/read.ts; * - operation, workflow, catalog, and result types. * * Every other Y.Doc layout and low-level mutation helper is deliberately @@ -67,7 +67,7 @@ export { } from "./events.js"; export * from "./collab-trace.js"; /** - * ADR-004 follower read-surface. These helpers expose the established wire + * ADR-DISTRIBUTION-0004 follower read-surface. These helpers expose the established wire * layout only so the frontend follower can consume host updates. They are * read-only by contract: followers never write and never call `applyOps` * (KA-1, KA-6, FC-5); the host remains the sole op applier. diff --git a/src/read.ts b/src/read.ts index 1a58ef3b..07b33e15 100644 --- a/src/read.ts +++ b/src/read.ts @@ -2,7 +2,7 @@ * Read-only snapshot surface — the supported way to READ a shared document * without being handed anything you can write. * - * WHY THIS EXISTS. The entrypoint deliberately re-exports only ADR-004's three + * WHY THIS EXISTS. The entrypoint deliberately re-exports only ADR-DISTRIBUTION-0004's three * layout reads and the KA-1 encoding diagnostic from `src/doc.ts` (issue #18): * the same import that hands you `nodesMap` for a read hands you a * live `Y.Map`, and a `.set()` on it is an UNSTAMPED write — invisible to @@ -17,7 +17,7 @@ * `project()` cannot serve: * * - a follower that renders a document it holds NO catalog for, so it cannot - * project (and must not — ADR-004); + * project (and must not — ADR-DISTRIBUTION-0004); * - the doc host's pre-apply guards, which must read `meta.catalog_version` * and probe node/op identity BEFORE (and precisely in order to decide * whether) projecting is safe; @@ -78,7 +78,7 @@ import { WIDGET_FORM_KEY } from "./widget-form.js"; * string literal: a primitive carries no reachability, so it cannot be a route * back to a live Y type. A follower that needs to tell "no widgets" from "opaque * widgets" needs this key, and hardcoding `"__widgets_opaque"` on the consumer - * side is exactly the schema-drift ADR-004 closed. + * side is exactly the schema-drift ADR-DISTRIBUTION-0004 closed. */ export { OPAQUE_WIDGETS_KEY }; @@ -316,7 +316,7 @@ function assertSnapshotReadable(doc: Y.Doc, context: string): void { * raw live-handle read against `readGraph`'s 2.0x, re-measured at this commit * with `node scripts/bench-read.mjs` — for data no current consumer reads. * (An earlier "~5x" here was against a different baseline and is withdrawn; - * README and ADR-005 both say "twice", and now so does this.) Adding a key here is a one-line, + * README and ADR-API-0005 both say "twice", and now so does this.) Adding a key here is a one-line, * reviewable change; handing back the whole node forever is not. * * `project(doc, catalog)` remains the full-fidelity read for a caller that has diff --git a/src/remap.ts b/src/remap.ts index 68ed3914..855ce341 100644 --- a/src/remap.ts +++ b/src/remap.ts @@ -19,7 +19,7 @@ function derivedDefinitionId(opId: string, scope: string, original: unknown): st * `derivedLinkId` folds the digest into the FULL safe-integer range * (`[1, Number.MAX_SAFE_INTEGER]`, i.e. `[1, 2^53 - 1]`) rather than the * narrower 52-bit window an earlier revision used, so the mint spends every - * bit of entropy `LinkId`'s numeric type can safely hold (ADR-033 amendment, + * bit of entropy `LinkId`'s numeric type can safely hold (ADR-WORKFLOW-0033 amendment, * review discussion on PR #245). 32 hex characters (128 bits) are taken from * the digest before the modulus is applied so the reduction to 53 bits stays * close to uniform; sha256Hex's 64-character output has plenty to spare. @@ -32,7 +32,7 @@ const SAFE_INTEGER_MODULUS = BigInt(Number.MAX_SAFE_INTEGER); /** * Mint a numeric id for a link `insert_workflow` carries — PURELY as a * function of the op's own content (`opId`, `scope`, `original`), with NO - * document-state dependency (ADR-033 amendment, superseding the + * document-state dependency (ADR-WORKFLOW-0033 amendment, superseding the * document-verified retry mint the original revision of this PR shipped). * * Christian Byrne's review of the original revision (PR #245, inline on this @@ -48,7 +48,7 @@ const SAFE_INTEGER_MODULUS = BigInt(Number.MAX_SAFE_INTEGER); * The fix removes the retry (and the document read it required) entirely: * the SAME op, applied to ANY document state, in ANY order relative to any * other op, always derives the SAME numeric id — because nothing but the - * op's own fields feeds the hash. This restores ADR-031's "producers do not + * op's own fields feeds the hash. This restores ADR-WORKFLOW-0031's "producers do not * inspect document state or remap ids" for links too, at the cost of the * "checked collision-free against this document" property the retry design * offered: two derived ids (or a derived id and something already persisted) @@ -260,8 +260,8 @@ function remapGraph( * nested definition graphs. * * Every id this function derives — node, link, group, and definition — is a - * PURE function of (`opId`, `scope`, `kind`, `original`) alone (ADR-031, - * amended for links by the ADR-033 revision on PR #245). No document, no + * PURE function of (`opId`, `scope`, `kind`, `original`) alone (ADR-WORKFLOW-0031, + * amended for links by the ADR-WORKFLOW-0033 revision on PR #245). No document, no * caller-supplied reservation set, and no state from any other call factors * into the result: the same `(wf, opId)` pair always produces byte-identical * output, on any replica, regardless of what else that replica's document diff --git a/src/stamps.ts b/src/stamps.ts index a959b5d3..850e8b2b 100644 --- a/src/stamps.ts +++ b/src/stamps.ts @@ -141,7 +141,7 @@ export function writeTarget(op: WireOp): unknown[] { // One insertion is one register: the op is idempotent by `op_id` (exact // replay is a no-op via the applied-set gate), and two distinct // insertions never contend because the minter allocates fresh ids - // (ADR-022). Keyed by op_id so a stamp lookup is per-insertion. + // (ADR-WORKFLOW-0031). Keyed by op_id so a stamp lookup is per-insertion. return ["insert_workflow", op.op_id]; case "clear": case "reset_doc": diff --git a/src/types.ts b/src/types.ts index d395c40a..b7cfa85e 100644 --- a/src/types.ts +++ b/src/types.ts @@ -5,7 +5,7 @@ * stamp shapes minted by `comfy_cli/workflow_ops.py` (`_new_op`), pinned by * SHA at comfy-cli `7e732242d971daf0d2d30f22f997abfacd78986e` (FC-10: never by * branch — the branch this file used to cite has since been deleted upstream). - * `set_node_field` is the one package-local, provisional addition; ADR-032 + * `set_node_field` is the one package-local, provisional addition; ADR-OPS-NODE-0032 * records its closed field set and the upstream reconciliation requirement. * Every `§` below is a section of that revision; see docs/upstream-pins.json * for the pin registry and the amendments upstream has added since. @@ -95,7 +95,7 @@ export const DEFERRED_OPS = ["reset_doc"] as const; * position. Gating dispatch on this list would diverge from `apply_op` (KA-3 * one-implementation parity) and would reject `fixtures/golden-vectors/ * conformance.json`'s `edit-heavy` case, which carries a `clear` at index 36 - * of a 61-op stream that `docs/portability.md` requires every conforming + * of a 61-op stream that ADR-PORTABILITY-0001 requires every conforming * runner to apply "in file order with no failures or skips". * * Exported for a HOST that fronts the applier with its own submission surface: @@ -201,7 +201,7 @@ export interface AddNodeOp extends OpBase { /** * Merge a workflow template (nodes, links, `definitions.subgraphs`) into an - * existing doc in one transaction (ADR-022; agent-subgraph TDD V1.5). + * existing doc in one transaction (ADR-WORKFLOW-0031; agent-subgraph TDD V1.5). * * The applier remaps every carried id deterministically from `op_id` and the * original id. Exact replay therefore chooses the same ids, while distinct diff --git a/test/batch-policy.test.ts b/test/batch-policy.test.ts index d3d888c1..d301e59a 100644 --- a/test/batch-policy.test.ts +++ b/test/batch-policy.test.ts @@ -12,7 +12,7 @@ * `apply_op`, whose batch protocol is §4 abort-remainder with no kind * restriction. Gating `applyOps` on `BATCHABLE_OPS` would diverge from * `apply_op` (KA-3 — one implementation, golden-vector parity) and would - * reject the `edit-heavy` conformance case, which `docs/portability.md` + * reject the `edit-heavy` conformance case, which ADR-PORTABILITY-0001 * requires every language runner to replay "in file order with no failures or * skips". * @@ -42,7 +42,7 @@ import { loadCatalog, loadSession, sessionFiles } from "./helpers.js"; const repoRoot = dirname(dirname(fileURLToPath(import.meta.url))); const batchable = new Set(BATCHABLE_OPS); -/** Kinds the vocabulary or ADR-022 calls standalone-only. */ +/** Kinds the vocabulary or ADR-WORKFLOW-0031 calls standalone-only. */ const STANDALONE_ONLY = ["clear", "insert_workflow", "reset_doc"]; const catalog: WidgetCatalog = { types: { Sampler: { widget_order: ["steps"] } } }; diff --git a/test/check-adr-links.test.ts b/test/check-adr-links.test.ts new file mode 100644 index 00000000..e2d564a3 --- /dev/null +++ b/test/check-adr-links.test.ts @@ -0,0 +1,72 @@ +import { execFileSync } from "node:child_process"; +import { mkdirSync, rmSync, writeFileSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; +import { afterEach, describe, expect, test } from "vitest"; + +const fixtures: string[] = []; +const script = join(process.cwd(), "scripts", "check-adr-links.mjs"); +const adrPath = (filename: string) => ["docs", "adr", filename].join("/"); +const gitCommand = process.env.GIT_EXECUTABLE ?? "git"; + +function fixture() { + const root = join(tmpdir(), `cmp-adr-links-${process.pid}-${fixtures.length}`); + mkdirSync(join(root, "docs", "adr"), { recursive: true }); + execFileSync(gitCommand, ["init", "-q"], { cwd: root }); + fixtures.push(root); + return root; +} + +function write(root: string, filename: string, contents: string) { + const absolute = join(root, filename); + mkdirSync(join(absolute, ".."), { recursive: true }); + writeFileSync(absolute, contents); +} + +function run(root: string) { + return execFileSync(process.execPath, [script], { + cwd: root, + encoding: "utf8", + stdio: "pipe", + }); +} + +afterEach(() => { + for (const root of fixtures.splice(0)) rmSync(root, { recursive: true }); +}); + +describe("ADR link validation", () => { + test("accepts references to existing ADRs", () => { + const root = fixture(); + const target = adrPath("CRDT-0001-real.md"); + write(root, target, "# real\n"); + write(root, "README.md", `See ${target}.\n`); + expect(run(root)).toContain("ADR link validation passed"); + }); + + test("rejects dangling ADR references with their source line", () => { + const root = fixture(); + write(root, "README.md", `first\nSee ${adrPath("CRDT-0001-missing.md")}.\n`); + expect(() => run(root)).toThrow(/README\.md:2/); + }); + + test("checks sibling links from one ADR to another", () => { + const root = fixture(); + const source = adrPath("CRDT-0001-source.md"); + write(root, source, "See [missing](CRDT-0002-missing.md).\n"); + expect(() => run(root)).toThrow(/CRDT-0002-missing\.md/); + }); + + test("checks reference-style sibling links from one ADR to another", () => { + const root = fixture(); + const source = adrPath("CRDT-0001-source.md"); + write(root, source, "See [missing][decision].\n\n[decision]: CRDT-0002-missing.md\n"); + expect(() => run(root)).toThrow(/CRDT-0002-missing\.md/); + }); + + test("ignores references outside the ADR directory", () => { + const root = fixture(); + write(root, "README.md", "See docs/architecture/overview.md.\n"); + expect(run(root)).toContain("ADR link validation passed"); + }); +}); diff --git a/test/check-adrs.test.ts b/test/check-adrs.test.ts new file mode 100644 index 00000000..e1425570 --- /dev/null +++ b/test/check-adrs.test.ts @@ -0,0 +1,104 @@ +import { execFileSync } from "node:child_process"; +import { mkdirSync, rmSync, writeFileSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; +import { afterEach, describe, expect, test } from "vitest"; + +const fixtures: string[] = []; +const script = join(process.cwd(), "scripts", "check-adrs.mjs"); + +function fixture(filename = "CRDT-0001-test-decision.md") { + const root = join(tmpdir(), `cmp-adr-check-${process.pid}-${fixtures.length}`); + const directory = join(root, "docs", "adr"); + mkdirSync(directory, { recursive: true }); + fixtures.push(root); + writeFileSync( + join(directory, filename), + "# ADR-CRDT-0001: Test decision\n\nDate: 2026-10-17\n\n## Status\n\nProposed\n", + ); + return root; +} + +function run(root: string) { + return execFileSync(process.execPath, [script], { + cwd: root, + encoding: "utf8", + stdio: "pipe", + }); +} + +afterEach(() => { + for (const root of fixtures.splice(0)) rmSync(root, { recursive: true }); +}); + +describe("ADR validation", () => { + test("accepts canonical ADR metadata", () => { + expect(run(fixture())).toContain("ADR validation passed"); + }); + + test("accepts a status immediately below its heading", () => { + const root = fixture(); + writeFileSync( + join(root, "docs", "adr", "CRDT-0001-test-decision.md"), + "# ADR-CRDT-0001: Test decision\n\nDate: 2026-10-17\n\n## Status\nProposed\n", + ); + expect(run(root)).toContain("ADR validation passed"); + }); + + test("rejects a status value with an unrecognized suffix", () => { + const root = fixture(); + writeFileSync( + join(root, "docs", "adr", "CRDT-0001-test-decision.md"), + "# ADR-CRDT-0001: Test decision\n\nDate: 2026-10-17\n\n## Status\n\nProposed-extra\n", + ); + expect(() => run(root)).toThrow(/missing a valid Status value/); + }); + + test("rejects numeric-only legacy filenames", () => { + expect(() => run(fixture("0001-test-decision.md"))).toThrow( + /Invalid ADR filenames/, + ); + }); + + test("rejects a heading that disagrees with its filename", () => { + const root = fixture(); + writeFileSync( + join(root, "docs", "adr", "CRDT-0001-test-decision.md"), + "# ADR-CRDT-0002: Test decision\n\nDate: 2026-10-17\n\n## Status\n\nProposed\n", + ); + expect(() => run(root)).toThrow(/expected heading/); + }); + + test("rejects metadata that appears only in body examples", () => { + const root = fixture(); + writeFileSync( + join(root, "docs", "adr", "CRDT-0001-test-decision.md"), + "Example follows\n\n# ADR-CRDT-0001: Test decision\n\nDate: 2026-10-17\n\n## Status\n\nProposed\n", + ); + expect(() => run(root)).toThrow(/expected heading/); + }); + + test("rejects impossible calendar dates", () => { + const root = fixture(); + writeFileSync( + join(root, "docs", "adr", "CRDT-0001-test-decision.md"), + "# ADR-CRDT-0001: Test decision\n\nDate: 2026-02-31\n\n## Status\n\nProposed\n", + ); + expect(() => run(root)).toThrow(/missing a valid Date field/); + }); + + test("rejects a Date that appears after Status", () => { + const root = fixture(); + writeFileSync( + join(root, "docs", "adr", "CRDT-0001-test-decision.md"), + "# ADR-CRDT-0001: Test decision\n\n## Status\n\nProposed\n\nDate: 2026-10-17\n", + ); + expect(() => run(root)).toThrow(/missing a valid Date field/); + }); + + test("rejects companion directories without a matching ADR", () => { + const root = fixture(); + mkdirSync(join(root, "docs", "adr", "CRDT-0002-evidence")); + expect(() => run(root)).toThrow(/companion directory has no matching ADR/); + }); +}); diff --git a/test/durable-link-state.acceptance.test.ts b/test/durable-link-state.acceptance.test.ts index d4df1248..4f03a196 100644 --- a/test/durable-link-state.acceptance.test.ts +++ b/test/durable-link-state.acceptance.test.ts @@ -129,7 +129,7 @@ const readdPromoted: AddNodeOp = { node: promotedInstance, }; -describe("ADR-022 bounded durable-link acceptance", () => { +describe("ADR-CRDT-LINKS-0022 bounded durable-link acceptance", () => { it("restores concrete intent and the exact endpoint references after delete/re-add", () => { const connect: ConnectOp = { op: "connect", ...envelope(0xc1, 1), link_id: 100, from_node: 10, from_slot: 0, diff --git a/test/gen-coderabbit-config.test.ts b/test/gen-coderabbit-config.test.ts index 32966024..6002e9fa 100644 --- a/test/gen-coderabbit-config.test.ts +++ b/test/gen-coderabbit-config.test.ts @@ -65,7 +65,7 @@ describe("gen-coderabbit-config", () => { let root: string; let checks: string; - /** Five blocks, because the generator's floor is five — see MIN_BLOCKS. */ + /** Six blocks, because the generator's floor is six — see MIN_BLOCKS. */ const fillers = (from: number, to: number) => Array.from({ length: to - from }, (_, i) => block(`filler${from + i}/**`, `Filler instruction number ${from + i}.`), @@ -88,16 +88,16 @@ describe("gen-coderabbit-config", () => { // parser sees is the text the profile wrote. const body = "Rejection tests must assert the document state, not only failed.code.\nFor a REJECTED op\nthe oracle is byte identity under Y.encodeStateAsUpdate plus the op_id absent from __applied."; - writeFileSync(join(checks, "a.md"), block("test/**", body) + "\n" + fillers(1, 5)); + writeFileSync(join(checks, "a.md"), block("test/**", body) + "\n" + fillers(1, 6)); expect(run(root, "--write").status).toBe(0); const emitted = unfold(readFileSync(join(root, ".coderabbit.yaml"), "utf8")); expect(emitted.get("test/**")).toBe(body.split(/\s+/).join(" ")); - expect(emitted.size).toBe(5); + expect(emitted.size).toBe(6); }); it("is a fixpoint: regenerating an already-generated file changes nothing", () => { - writeFileSync(join(checks, "a.md"), fillers(1, 6)); + writeFileSync(join(checks, "a.md"), fillers(1, 7)); expect(run(root, "--write").status).toBe(0); const once = readFileSync(join(root, ".coderabbit.yaml"), "utf8"); expect(run(root, "--write").status).toBe(0); @@ -109,7 +109,7 @@ describe("gen-coderabbit-config", () => { // The recurrence this whole mechanism exists to stop: someone corrects the // machine-consumed copy in place, the profile keeps the old wording, and the // two are never reconciled. - writeFileSync(join(checks, "a.md"), fillers(1, 6)); + writeFileSync(join(checks, "a.md"), fillers(1, 7)); run(root, "--write"); const generated = readFileSync(join(root, ".coderabbit.yaml"), "utf8"); writeConfig(generated.replace("Filler instruction number 1.", "Edited in place.")); @@ -125,9 +125,9 @@ describe("gen-coderabbit-config", () => { }); it("fails (exit 1) when the source block is edited and the file is not regenerated", () => { - writeFileSync(join(checks, "a.md"), fillers(1, 6)); + writeFileSync(join(checks, "a.md"), fillers(1, 7)); run(root, "--write"); - writeFileSync(join(checks, "a.md"), fillers(1, 6).replace("number 1.", "number one.")); + writeFileSync(join(checks, "a.md"), fillers(1, 7).replace("number 1.", "number one.")); const drifted = run(root); expect(drifted.status).toBe(1); // Assert the rule that fired, not just the exit code: six rules exit 1, so @@ -142,7 +142,7 @@ describe("gen-coderabbit-config", () => { // The realistic drift is a word swapped for another of the same length — // "NOT the projection" for "and the projection" inverts the rejection // oracle without changing a single count. - writeFileSync(join(checks, "a.md"), fillers(1, 6)); + writeFileSync(join(checks, "a.md"), fillers(1, 7)); run(root, "--write"); const generated = readFileSync(join(root, ".coderabbit.yaml"), "utf8"); const edited = generated.replace("Filler instruction number 1.", "Filler instruction number 7."); @@ -154,7 +154,7 @@ describe("gen-coderabbit-config", () => { it("fails (exit 1) when a second path_instructions key would win over the generated one", () => { // The coexistence affordance is also the sharpest hazard: the region can be // byte-perfect and inert. A duplicate key silently replaces it. - writeFileSync(join(checks, "a.md"), fillers(1, 6)); + writeFileSync(join(checks, "a.md"), fillers(1, 7)); run(root, "--write"); writeConfig( readFileSync(join(root, ".coderabbit.yaml"), "utf8") + @@ -169,7 +169,7 @@ describe("gen-coderabbit-config", () => { it("fails (exit 1) on a duplicate key in any of its four YAML spellings", () => { // Counting only the bare `path_instructions:` left three ways to override // the whole region with a differently-spelled duplicate. - writeFileSync(join(checks, "a.md"), fillers(1, 6)); + writeFileSync(join(checks, "a.md"), fillers(1, 7)); run(root, "--write"); const generated = readFileSync(join(root, ".coderabbit.yaml"), "utf8"); for (const dup of [ @@ -193,7 +193,7 @@ describe("gen-coderabbit-config", () => { // It evaded both counters at once: REVIEWS_KEY ended with `$`, so a line // with a flow mapping after the colon was not a `reviews:` line; and DUP_KEY // was anchored at `^\s*`, so a key inside `{...}` was not a key. - writeFileSync(join(checks, "a.md"), fillers(1, 6)); + writeFileSync(join(checks, "a.md"), fillers(1, 7)); run(root, "--write"); const generated = readFileSync(join(root, ".coderabbit.yaml"), "utf8"); for (const override of [ @@ -214,7 +214,7 @@ describe("gen-coderabbit-config", () => { // this arm accepted only the bare, comment-free spelling while the comment // beside it claimed the quoted forms too — so `? "path_instructions"` and a // trailing `# comment` each replaced all five entries with one, gate green. - writeFileSync(join(checks, "a.md"), fillers(1, 6)); + writeFileSync(join(checks, "a.md"), fillers(1, 7)); run(root, "--write"); const generated = readFileSync(join(root, ".coderabbit.yaml"), "utf8"); for (const key of [ @@ -235,7 +235,7 @@ describe("gen-coderabbit-config", () => { // and an earlier draft therefore matched the bare word anywhere — reddening // configs that work. `.coderabbit.yaml` legitimately carries prose fields, // and a gate that fires on a working config is how a gate gets switched off. - writeFileSync(join(checks, "a.md"), fillers(1, 6)); + writeFileSync(join(checks, "a.md"), fillers(1, 7)); for (const preamble of [ 'tone_instructions: "Never add a second path_instructions: key."\n', "tone_instructions: |\n Do not add a second\n path_instructions: key anywhere.\n", @@ -257,7 +257,7 @@ describe("gen-coderabbit-config", () => { // under `code_generation.docstrings` and `code_generation.unit_tests`. // Counting those reddened a config that works and delivers all five // entries. Only indent 0 or 2 can be a child of top-level `reviews:`. - writeFileSync(join(checks, "a.md"), fillers(1, 6)); + writeFileSync(join(checks, "a.md"), fillers(1, 7)); writeConfig( "code_generation:\n docstrings:\n path_instructions:\n" + ' - path: "**"\n instructions: doc it\n' + @@ -270,7 +270,7 @@ describe("gen-coderabbit-config", () => { it("recognises a block-scalar header with a trailing comment or a quoted key", () => { // Both are legal YAML. Missing the header meant the BODY was scanned as // keys, so a note mentioning the key reddened a working config. - writeFileSync(join(checks, "a.md"), fillers(1, 6)); + writeFileSync(join(checks, "a.md"), fillers(1, 7)); // Every body line below BEGINS with the key, so if the header is not // recognised the body is scanned in key position and the gate goes red. // That is what makes these fixtures reach the clause they are testing. @@ -292,7 +292,7 @@ describe("gen-coderabbit-config", () => { // The hole direction: if the body is taken to start at column 0, every // following indented line is swallowed — including real keys after the // scalar ends. Here the duplicate at indent 2 must still be counted. - writeFileSync(join(checks, "a.md"), fillers(1, 6)); + writeFileSync(join(checks, "a.md"), fillers(1, 7)); writeConfig( "outer:\n inner: |\n body text\n" + ' path_instructions: [{path: "**", instructions: x}]\n' + @@ -307,7 +307,7 @@ describe("gen-coderabbit-config", () => { it("measures a block-scalar body from the key, not from the `- ` of its item", () => { // Taking the column from the dash swallowed the item's SIBLING keys, which // is the hole direction: real keys silently dropped from the scan. - writeFileSync(join(checks, "a.md"), fillers(1, 6)); + writeFileSync(join(checks, "a.md"), fillers(1, 7)); run(root, "--write"); writeConfig( readFileSync(join(root, ".coderabbit.yaml"), "utf8") + @@ -322,7 +322,7 @@ describe("gen-coderabbit-config", () => { // Isolates the `,` half of the flow arm: `{profile: chill, path_…}` is a // duplicate reached through a comma, and dropping `,` from the character // class left it uncounted. - writeFileSync(join(checks, "a.md"), fillers(1, 6)); + writeFileSync(join(checks, "a.md"), fillers(1, 7)); run(root, "--write"); writeConfig( readFileSync(join(root, ".coderabbit.yaml"), "utf8") + @@ -336,7 +336,7 @@ describe("gen-coderabbit-config", () => { it("stays green on a document-START marker, which begins no second document", () => { // `---` on the first content line is legal YAML and delivers every entry; // refusing it was this gate firing on a config that works. - writeFileSync(join(checks, "a.md"), fillers(1, 6)); + writeFileSync(join(checks, "a.md"), fillers(1, 7)); writeConfig(`---\nreviews:\n${BEGIN}\n${END}\n`); expect(run(root, "--write").status).toBe(0); expect(run(root).status).toBe(0); @@ -346,7 +346,7 @@ describe("gen-coderabbit-config", () => { // Comments are invisible to YAML, so a note about the key is not a key — // including a comment that spells out the flow-mapping form, which is the // shape the duplicate scan looks for and the only one that reaches it. - writeFileSync(join(checks, "a.md"), fillers(1, 6)); + writeFileSync(join(checks, "a.md"), fillers(1, 7)); for (const note of [ "# the path_instructions: below are generated", ' # never write: reviews: {path_instructions: [{path: "**"}]}', @@ -361,7 +361,7 @@ describe("gen-coderabbit-config", () => { // Isolates the trailer INDENT clause from the list-item clause: this is not // a list item, the file stays valid YAML, and it rewrites the last generated // entry's path to `**` in place. - writeFileSync(join(checks, "a.md"), fillers(1, 6)); + writeFileSync(join(checks, "a.md"), fillers(1, 7)); run(root, "--write"); writeConfig(readFileSync(join(root, ".coderabbit.yaml"), "utf8") + ' path: "**"\n'); const rewritten = run(root); @@ -372,7 +372,7 @@ describe("gen-coderabbit-config", () => { it("fails (exit 1) on a `...` document-end marker after the region", () => { // Isolates the separators clause: `...` is not caught by the trailer's // `--- ` test, so removing the separators check alone must still be visible. - writeFileSync(join(checks, "a.md"), fillers(1, 6)); + writeFileSync(join(checks, "a.md"), fillers(1, 7)); run(root, "--write"); writeConfig(readFileSync(join(root, ".coderabbit.yaml"), "utf8") + "...\n"); const ended = run(root); @@ -386,7 +386,7 @@ describe("gen-coderabbit-config", () => { // every generated byte intact — and one more instruction than the profiles // wrote. This one injects rather than replaces, which makes it the worst of // the family. - writeFileSync(join(checks, "a.md"), fillers(1, 6)); + writeFileSync(join(checks, "a.md"), fillers(1, 7)); run(root, "--write"); writeConfig( readFileSync(join(root, ".coderabbit.yaml"), "utf8") + @@ -399,7 +399,7 @@ describe("gen-coderabbit-config", () => { }); it("fails (exit 1) on a second YAML document, which makes the whole file unloadable", () => { - writeFileSync(join(checks, "a.md"), fillers(1, 6)); + writeFileSync(join(checks, "a.md"), fillers(1, 7)); run(root, "--write"); writeConfig( readFileSync(join(root, ".coderabbit.yaml"), "utf8") + '---\nreviews:\n profile: chill\n', @@ -411,7 +411,7 @@ describe("gen-coderabbit-config", () => { it("fails (exit 1) when reviews: appears twice and the region is under the second", () => { // Isolates the reviews-count clause: the parent check alone passes here. - writeFileSync(join(checks, "a.md"), fillers(1, 6)); + writeFileSync(join(checks, "a.md"), fillers(1, 7)); writeConfig(`reviews:\n profile: chill\nchat:\n auto_reply: false\nreviews:\n${BEGIN}\n${END}\n`); const twice = run(root); expect(twice.status).toBe(1); @@ -421,7 +421,7 @@ describe("gen-coderabbit-config", () => { it("fails (exit 1) when the region sits under the wrong key while reviews: exists elsewhere", () => { // Isolates the parent clause: the reviews-count check alone passes here. - writeFileSync(join(checks, "a.md"), fillers(1, 6)); + writeFileSync(join(checks, "a.md"), fillers(1, 7)); writeConfig(`chat:\n${BEGIN}\n${END}\nreviews:\n profile: chill\n`); const orphan = run(root); expect(orphan.status).toBe(1); @@ -430,7 +430,7 @@ describe("gen-coderabbit-config", () => { }); it("fails (exit 1) when the region is no longer nested under reviews:", () => { - writeFileSync(join(checks, "a.md"), fillers(1, 6)); + writeFileSync(join(checks, "a.md"), fillers(1, 7)); run(root, "--write"); writeConfig( readFileSync(join(root, ".coderabbit.yaml"), "utf8").replace("reviews:\n", "chat:\n"), @@ -443,7 +443,7 @@ describe("gen-coderabbit-config", () => { it("fails (exit 1) on a glob the emitter cannot quote", () => { // Neutering this rule emits `- path: "a"b/**"`, which is not parseable YAML // — so the config silently stops applying rather than failing loudly. - writeFileSync(join(checks, "a.md"), fillers(1, 6) + "\n" + block('a"b/**', "Body.")); + writeFileSync(join(checks, "a.md"), fillers(1, 7) + "\n" + block('a"b/**', "Body.")); const quoted = run(root); expect(quoted.status).toBe(1); expect(quoted.stderr).toContain("path glob contains a double quote"); @@ -452,7 +452,7 @@ describe("gen-coderabbit-config", () => { it("is INCONCLUSIVE (exit 2), not a crash, when the config or the profiles are missing", () => { // `1` means "ran and found drift"; a missing precondition is `2`. An // uncaught ENOENT would report the wrong one of the two. - writeFileSync(join(checks, "a.md"), fillers(1, 6)); + writeFileSync(join(checks, "a.md"), fillers(1, 7)); rmSync(join(root, ".coderabbit.yaml")); const noConfig = run(root); expect(noConfig.status).toBe(2); @@ -469,7 +469,7 @@ describe("gen-coderabbit-config", () => { // A generated file that could not carry hand-written config would be a // worse trade than the drift it prevents, so the generator owns one region // and splices. - writeFileSync(join(checks, "a.md"), fillers(1, 6)); + writeFileSync(join(checks, "a.md"), fillers(1, 7)); writeConfig( `language: en-US\nreviews:\n profile: chill\n${BEGIN}\n${END}\nchat:\n auto_reply: false\n`, ); @@ -482,7 +482,7 @@ describe("gen-coderabbit-config", () => { }); it("is INCONCLUSIVE (exit 2) when the config has no generated region", () => { - writeFileSync(join(checks, "a.md"), fillers(1, 6)); + writeFileSync(join(checks, "a.md"), fillers(1, 7)); writeConfig("reviews:\n path_instructions: []\n"); const missing = run(root); expect(missing.status).toBe(2); @@ -493,35 +493,35 @@ describe("gen-coderabbit-config", () => { // Without the floor, deleting a block regenerates to a smaller config that // still parses and still passes — the empty-work green this repo's gate // convention exists to forbid. - writeFileSync(join(checks, "a.md"), fillers(1, 5)); + writeFileSync(join(checks, "a.md"), fillers(1, 6)); const short = run(root); expect(short.status).toBe(2); - expect(short.stderr).toContain("found 4 instruction block(s)"); - expect(short.stderr).toContain("below the floor of 5"); + expect(short.stderr).toContain("found 5 instruction block(s)"); + expect(short.stderr).toContain("below the floor of 6"); }); it("ignores an indented example but fails on a column-0 marker with a malformed body", () => { // .agents/checks/README.md documents the syntax and also hosts three real // blocks, so the two have to be distinguishable. const example = block("test/**", "example").replace(/^/gm, " "); - writeFileSync(join(checks, "a.md"), fillers(1, 6) + "\n" + example); + writeFileSync(join(checks, "a.md"), fillers(1, 7) + "\n" + example); expect(run(root, "--write").status).toBe(0); - // Five blocks collected, not six: the indented copy is documentation. - expect(unfold(readFileSync(join(root, ".coderabbit.yaml"), "utf8")).size).toBe(5); + // Six blocks collected, not seven: the indented copy is documentation. + expect(unfold(readFileSync(join(root, ".coderabbit.yaml"), "utf8")).size).toBe(6); writeFileSync( join(checks, "a.md"), - fillers(1, 6) + "\n\nno fence here\n", + fillers(1, 7) + "\n\nno fence here\n", ); const malformed = run(root); expect(malformed.status).toBe(1); expect(malformed.stderr).toContain( - "a.md has 6 instruction marker(s) at column 0 but 5 well-formed block(s)", + "a.md has 7 instruction marker(s) at column 0 but 6 well-formed block(s)", ); }); it("fails (exit 1) when two blocks claim the same glob", () => { - writeFileSync(join(checks, "a.md"), fillers(1, 6)); + writeFileSync(join(checks, "a.md"), fillers(1, 7)); writeFileSync(join(checks, "b.md"), block("filler1/**", "A second claim on one glob.")); const dup = run(root); expect(dup.status).toBe(1); @@ -529,7 +529,7 @@ describe("gen-coderabbit-config", () => { }); it("fails (exit 1) on an empty instruction body", () => { - writeFileSync(join(checks, "a.md"), fillers(1, 6) + "\n" + block("empty/**", " ")); + writeFileSync(join(checks, "a.md"), fillers(1, 7) + "\n" + block("empty/**", " ")); const empty = run(root); expect(empty.status).toBe(1); expect(empty.stderr).toContain("empty instruction block for empty/**"); diff --git a/test/insert-workflow-numeric-group-ids.regression.test.ts b/test/insert-workflow-numeric-group-ids.regression.test.ts index afed67e0..8248400b 100644 --- a/test/insert-workflow-numeric-group-ids.regression.test.ts +++ b/test/insert-workflow-numeric-group-ids.regression.test.ts @@ -13,7 +13,7 @@ * The frontend then keeps its own copy of the graph and stops taking the * document's projection, so later edits land in the document but never on the * canvas. Groups now get the same pure numeric derivation links do - * (ADR-033): a function of the op's own content, never of document state. + * (ADR-WORKFLOW-0033): a function of the op's own content, never of document state. * * A document that already stores the old string form projects it through the * same hash, so it reads back as the number a fresh insert of that op derives. diff --git a/test/insert-workflow-numeric-link-ids.regression.test.ts b/test/insert-workflow-numeric-link-ids.regression.test.ts index 41ac59d5..eced93dd 100644 --- a/test/insert-workflow-numeric-link-ids.regression.test.ts +++ b/test/insert-workflow-numeric-link-ids.regression.test.ts @@ -1,5 +1,5 @@ /** - * `insert_workflow` numeric link ids (ADR-033, amended). + * `insert_workflow` numeric link ids (ADR-WORKFLOW-0033, amended). * * ComfyUI_frontend's `LinkId` is `number & { __brand: 'LinkId' }`, unlike the * string-or-number `NodeId`, so `remap.ts`'s usual string `derivedId` @@ -30,10 +30,10 @@ * (53 bits, `[1, Number.MAX_SAFE_INTEGER]`) so a genuine collision is an * accepted, quantified residual risk rather than something the mint tries to * avoid by reading state. See - * `docs/decisions/ADR-033-insert-workflow-numeric-link-ids.md` and the KA-5 + * `docs/adr/WORKFLOW-0033-insert-workflow-numeric-link-ids.md` and the KA-5 * row in `docs/decisions/EXCEPTIONS.md`. * - * `test/insert-workflow.test.ts`'s "numeric link id minting (ADR-033, pure + * `test/insert-workflow.test.ts`'s "numeric link id minting (ADR-WORKFLOW-0033, pure * derivation)" block covers the single-op determinism and realized-collision * cases directly against `occupiedIdVectors`' existing node/definition * siblings. This file covers the harder cross-cutting properties: multiple @@ -74,7 +74,7 @@ function linkNamed(wf: WorkflowJSON, label: unknown): [unknown, unknown, unknown return found; } -describe("insert_workflow numeric link ids (ADR-033, pure derivation)", () => { +describe("insert_workflow numeric link ids (ADR-WORKFLOW-0033, pure derivation)", () => { it("mints a real number for a top-level link while node ids stay derived strings", () => { const doc = mint({ nodes: [], links: [] }, catalog); const op = opEnvelope({ workflow: { nodes: [{ id: 1, type: "Src" }, { id: 2, type: "Sink" }], links: [[10, 1, 0, 2, 0, "L"]] } }); diff --git a/test/insert-workflow.test.ts b/test/insert-workflow.test.ts index ab796a2d..dddfd3ac 100644 --- a/test/insert-workflow.test.ts +++ b/test/insert-workflow.test.ts @@ -18,7 +18,7 @@ * target document's already-persisted numeric link ids to avoid a collision. * Review (Christian Byrne, PR #245) found that retry made link identity * depend on local arrival order, so `remap.ts`'s `derivedLinkId` mints - * PURELY from the op's own content instead (ADR-033, amended), spending the + * PURELY from the op's own content instead (ADR-WORKFLOW-0033, amended), spending the * full safe-integer range (53 bits) so a genuine collision is an accepted, * quantified residual risk (`docs/decisions/EXCEPTIONS.md`'s KA-5 row) * rather than something the mint tries to avoid by reading state. @@ -109,7 +109,7 @@ function replaySnapshot(seed: Uint8Array, ops: Op[]): WorkflowJSON { /** * One link's numeric id, as `remap.ts`'s `derivedLinkId` mint would produce * it for (`opId`, `"root"`, `rawLinkId`) — a pure function of those two - * inputs alone (ADR-033, amended), so this is exactly what a real apply of + * inputs alone (ADR-WORKFLOW-0033, amended), so this is exactly what a real apply of * the same (opId, rawLinkId) will also compute, regardless of document * state or arrival order. */ @@ -430,7 +430,7 @@ describe("insert_workflow: happy path", () => { const wf = project(doc, catalog); expect(ids(wf).slice(0, 5)).toEqual([1, 2, 3, 4, 6]); expect(ids(wf).slice(5).every((id) => typeof id === "string" && id.includes(op.op_id))).toBe(true); - // Link ids are minted numeric (ADR-033 — `remap.ts`'s `derivedLinkId`), + // Link ids are minted numeric (ADR-WORKFLOW-0033 — `remap.ts`'s `derivedLinkId`), // unlike the op-id-embedding derived STRING every other insert_workflow // id keeps: ComfyUI_frontend's `LinkId` is a branded `number`. expect(typeof linkIds(wf)[1]).toBe("number"); @@ -626,7 +626,7 @@ describe("insert_workflow: happy path", () => { seq--; // `remap.ts`'s `derivedLinkId` is a pure function of (opId, scope, - // original) alone (ADR-033, amended), so the candidate this direct call + // original) alone (ADR-WORKFLOW-0033, amended), so the candidate this direct call // computes for the surviving link (903, "sibling") is exactly what the // real apply below will also compute — independent of what else the // target doc holds. @@ -892,7 +892,7 @@ describe("insert_workflow: rejection (KA-4 byte identity, op_id absent from appl }); } - describe("numeric link id minting (ADR-033, pure derivation)", () => { + describe("numeric link id minting (ADR-WORKFLOW-0033, pure derivation)", () => { it("derives the identical numeric id whether or not that id already exists in the target document", () => { // The whole point of the amended design: the candidate is a function // of (opId, rawLinkId) ALONE. Computing it against an empty workflow diff --git a/test/invariant-ids.test.ts b/test/invariant-ids.test.ts index 4d7ec665..9ee7a4c9 100644 --- a/test/invariant-ids.test.ts +++ b/test/invariant-ids.test.ts @@ -5,7 +5,7 @@ * `docs/INVARIANTS.md` calls itself "the machine-addressable review log", and * `AGENTS.md` requires every semantics-touching change to cite the affected ids * in its PR description — but nothing checked that a cited id exists. `KA-13` - * was cited by the stateless gate, the strict ESLint config, `ADR-021` and + * was cited by the stateless gate, the strict ESLint config, `ADR-ORDERING-0021` and * `test/stateless.test.ts` while the register stopped at `KA-12`, so the label * was unresolvable for every reader who followed it (#152). * @@ -106,7 +106,7 @@ describe("invariant register integrity (KA-*/FC-* ids resolve)", () => { expect(cited.get("test/stateless.test.ts")).toContain("KA-13"); expect(cited.get("scripts/check-stateless.mjs")).toContain("KA-13"); expect(cited.get(".agents/checks/eslint.strict.config.js")).toContain("KA-13"); - expect(cited.get("docs/decisions/ADR-021-doc-derived-lamport-clock-store.md")).toContain("KA-13"); + expect(cited.get("docs/adr/ORDERING-0021-doc-derived-lamport-clock-store.md")).toContain("KA-13"); }); it("would catch an unregistered id (the #152 shape), rather than only the fixed instance", () => { diff --git a/test/ka4-rejection-byte-identity.test.ts b/test/ka4-rejection-byte-identity.test.ts index f580d3cf..da9a5ee3 100644 --- a/test/ka4-rejection-byte-identity.test.ts +++ b/test/ka4-rejection-byte-identity.test.ts @@ -231,7 +231,7 @@ const CASES: Row[] = [ }, }, { - // ADR-033 (amended): `derivedLinkId` is now a PURE function of the op's + // ADR-WORKFLOW-0033 (amended): `derivedLinkId` is now a PURE function of the op's // own content, with no retry against document state (removing the // arrival-order dependence Christian Byrne's review of the original // revision found — see `remap.ts`'s `derivedLinkId` doc comment). A diff --git a/test/public-api.regression.test.ts b/test/public-api.regression.test.ts index 78e6230b..193a368a 100644 --- a/test/public-api.regression.test.ts +++ b/test/public-api.regression.test.ts @@ -7,7 +7,7 @@ * without going through `applyOps` and bypass stamp gating (KA-2), idempotency * and convergence (KA-4), and the catalog check at mint (KA-12). * - * ADR-004 deliberately retains three layout reads for the frontend follower; + * ADR-DISTRIBUTION-0004 deliberately retains three layout reads for the frontend follower; * The internals list is derived from `src/doc.ts` at runtime rather than * hardcoded, so a newly added document internal is covered the moment it exists. * @@ -45,7 +45,7 @@ describe("public API", () => { } }); - it("pins the op layer, stamp helpers, and ADR-004 follower read surface", () => { + it("pins the op layer, stamp helpers, and ADR-DISTRIBUTION-0004 follower read surface", () => { expect(publicApi).toEqual( expect.objectContaining({ mint: expect.any(Function), diff --git a/test/readonly-surface.test.ts b/test/readonly-surface.test.ts index 11817e32..5817a766 100644 --- a/test/readonly-surface.test.ts +++ b/test/readonly-surface.test.ts @@ -438,7 +438,7 @@ describe("read-only surface — the KA-11 read gate (#38)", () => { * The rule has TWO clauses and both are load-bearing: * 1. REFUSE when the document carries content under a schema this package * cannot read; - * 2. STAY EMPTY when it carries nothing. ADR-004's follower reads a + * 2. STAY EMPTY when it carries nothing. ADR-DISTRIBUTION-0004's follower reads a * root-less document before its first frame and there is nothing there * to mis-key. NOT because #30 said so — #30 made `migrate()` REFUSE * that same document, which is a role split (a write may refuse an diff --git a/test/wire-layout-contract.test.ts b/test/wire-layout-contract.test.ts index c9c12a07..7ba570b1 100644 --- a/test/wire-layout-contract.test.ts +++ b/test/wire-layout-contract.test.ts @@ -16,7 +16,7 @@ * The names are the wire contract. A follower forks from ONE bootstrap * snapshot (KA-10) — `Y.applyUpdate(new Y.Doc(), Y.encodeStateAsUpdate(minted))` * — and resolves roots BY NAME out of those bytes; so does the Node doc host, - * which runs this package by SHA pin (ADR-001, ADR-004). So the property that + * which runs this package by SHA pin (ADR-APPLIER-0001, ADR-DISTRIBUTION-0004). So the property that * actually matters is not "this Y.Doc has a root called nodes", it is "the * encoded update spells these names, and a reader that has only the bytes * recovers exactly these roots".