Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 26 additions & 0 deletions .agents/checks/adr-compliance.md
Original file line number Diff line number Diff line change
@@ -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.

<!-- coderabbit-instructions: {src/**,docs/adr/**} -->
```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.
```
<!-- /coderabbit-instructions -->
4 changes: 2 additions & 2 deletions .agents/checks/api-contract.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

<!-- claim: "encodingLosses", :: test/public-api.regression.test.ts -->
Expand Down
22 changes: 22 additions & 0 deletions .coderabbit.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -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: >-
Expand Down
22 changes: 22 additions & 0 deletions .github/workflows/adr-links.yml
Original file line number Diff line number Diff line change
@@ -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
2 changes: 1 addition & 1 deletion .github/workflows/auto-tag-release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
3 changes: 3 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
# <!-- coderabbit-instructions --> blocks in .agents/checks/*.md. This
# fails when the committed file no longer matches them. CodeRabbit reads
Expand Down
34 changes: 34 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 `<DOMAIN>[-<SUBDOMAIN>]-<NNNN>-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-<IDENTIFIER>: 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
Comment thread
christian-byrne marked this conversation as resolved.
Resolved
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.
Expand Down
8 changes: 4 additions & 4 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -250,17 +250,17 @@ 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
`AGENT_EVENT_JSON_SCHEMA`, `CMP_EVENT_SCHEMA_VERSION`, and event types.
- 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.

Expand Down
13 changes: 12 additions & 1 deletion CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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<version>` at the merge commit and starts `release.yml` at that tag, which
Expand Down
Loading
Loading