diff --git a/.agents/checks/catalog-pinning.md b/.agents/checks/catalog-pinning.md index 85a1c92b..995aa134 100644 --- a/.agents/checks/catalog-pinning.md +++ b/.agents/checks/catalog-pinning.md @@ -32,8 +32,11 @@ Apply .agents/checks/catalog-pinning.md (KA-12, FC-10). The widget catalog (fixtures/catalog.json) is pinned by sha256 at mint; the golden conformance corpus and lww-vectors are SHA-pinned and one-way. Flag any change that edits a pinned fixture without a corresponding manifest/SHA update, cites -the catalog/vocabulary by a moving branch instead of a SHA, or would let the -corpus drift without being regenerated in CI (verify:corpus). +the catalog/vocabulary by a moving branch instead of a SHA, or bypasses +catalog-corpus-check=verify:corpus, the CI hash-verification gate. Preserve the +one-way-corpus-rule: expected outputs come from the pinned upstream generator +or explicitly documented manual fixtures, never from the applier under test. +Regeneration is a separate manual procedure; CI verifies the retained hashes. ``` @@ -43,6 +46,7 @@ carries it in a folded scalar, where every space is a legal line break. This blo audited against the code for [#80](https://github.com/Comfy-Org/comfy-multi-player/issues/80) and verified without a wording change. - + + > Before reporting PASS for any check above, apply [vacuity.md](vacuity.md): P0 to every check, P1 to any guard this change adds, P10 to what that guard's test asserts on, P2 to any tool you ran, and P7 to any run you quote. diff --git a/.agents/checks/dep-secrets-scan.md b/.agents/checks/dep-secrets-scan.md index f78ed64d..c3ef42be 100644 --- a/.agents/checks/dep-secrets-scan.md +++ b/.agents/checks/dep-secrets-scan.md @@ -6,14 +6,18 @@ Detect known CVEs in dependencies and leaked secrets. Applies to any change; esp 1. Probe tools: `npm --version`, `gitleaks version`. If neither is available, skip and report the install hints (`npm i -g npm`, gitleaks: https://github.com/gitleaks/gitleaks#installing). If only one is available, run it and note the other was skipped. 2. **Dependency audit** (npm): + ```bash npm audit --json; echo "npm audit exit: $?" ``` + Do not suppress stderr or discard the exit status: `npm audit` exits non-zero when it finds advisories, but a non-zero exit with no parseable JSON means the tool itself failed — report that as an error, not a clean result. Map severity `critical`→critical, `high`→major, `moderate`→minor, `low`→nitpick. Report package, version, advisory title, CVE, and patched version. 3. **Secrets** (gitleaks): + ```bash gitleaks detect --no-banner --report-format json --report-path /tmp/gitleaks.json --source .; echo "gitleaks exit: $?" ``` + `gitleaks` exits `1` when it finds secrets and `2` on execution error — never collapse these to a pass. If the run errors or the report cannot be parsed, report it as an indeterminate/failed scan, not "no issues found". All secret findings are critical. Report file/line, rule, a redacted match, and advise removal plus credential rotation. ## Repo-specific emphasis diff --git a/.agents/checks/error-handling.md b/.agents/checks/error-handling.md index 9c1d1e93..319b3952 100644 --- a/.agents/checks/error-handling.md +++ b/.agents/checks/error-handling.md @@ -15,8 +15,8 @@ The `src/**` `path_instructions` entry is an umbrella over every profile, so it load-bearing sentence is this profile's mutate-before-throw rule, so the anchor for it lives here: if the generated block loses that requirement, CI fails rather than the bot quietly stopping to ask for it. The needle is space-free because the YAML carries it in a folded scalar. That block's content was -moved byte-for-byte from a hand-written config and has **not** been audited — it still cites issue -#10 as open, and #10 is closed; see +moved byte-for-byte from a hand-written config and has **not** been audited — it still cites +issue #10 as open, and #10 is closed; see [#80](https://github.com/Comfy-Org/comfy-multi-player/issues/80). diff --git a/.agents/checks/eslint.strict.config.js b/.agents/checks/eslint.strict.config.js index 18c8a564..ea23e90a 100644 --- a/.agents/checks/eslint.strict.config.js +++ b/.agents/checks/eslint.strict.config.js @@ -44,12 +44,12 @@ const statelessRules = { "no-restricted-syntax": [ "error", { - selector: "Program > VariableDeclaration[kind='let'], Program > VariableDeclaration[kind='var']", + selector: ":matches(Program, Program > ExportNamedDeclaration) > VariableDeclaration[kind=/^(let|var)$/]", message: "KA-13: no module-level let/var; caller-owned state only.", }, { selector: - "Program > VariableDeclaration > VariableDeclarator:not([id.name='documentTransactionTails']) > NewExpression[callee.type='Identifier'][callee.name=/^(Map|Set|WeakMap|WeakSet)$/]", + ":matches(Program, Program > ExportNamedDeclaration) > VariableDeclaration > VariableDeclarator:not([id.name='documentTransactionTails']) > NewExpression[callee.type='Identifier'][callee.name=/^(Map|Set|WeakMap|WeakSet)$/]", message: "KA-13: no module-level mutable collection except the documented Y.Doc-keyed admission queue; inject state through the caller.", }, ], diff --git a/.coderabbit.yaml b/.coderabbit.yaml index 70632d36..ad017516 100644 --- a/.coderabbit.yaml +++ b/.coderabbit.yaml @@ -38,8 +38,12 @@ reviews: conformance corpus and lww-vectors are SHA-pinned and one-way. Flag any change that edits a pinned fixture without a corresponding manifest/SHA update, cites the catalog/vocabulary by a moving branch instead of a - SHA, or would let the corpus drift without being regenerated in CI - (verify:corpus). + SHA, or bypasses catalog-corpus-check=verify:corpus, the CI + hash-verification gate. Preserve the one-way-corpus-rule: expected + outputs come from the pinned upstream generator or explicitly + documented manual fixtures, never from the applier under test. + Regeneration is a separate manual procedure; CI verifies the retained + hashes. - path: "scripts/**" # source: .agents/checks/purity.md instructions: >- diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml index 0c1a6553..81e75a5e 100644 --- a/.github/ISSUE_TEMPLATE/config.yml +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -1,8 +1,5 @@ -blank_issues_enabled: false +blank_issues_enabled: true contact_links: - - name: Active package issues and questions - url: https://github.com/Comfy-Org/ComfyUI_frontend/issues/new/choose - about: Active development has moved to ComfyUI_frontend/packages/comfy-multi-player. Open all new work there. - name: Security report - url: https://github.com/Comfy-Org/ComfyUI_frontend/security/advisories/new - about: Report security vulnerabilities privately in the canonical ComfyUI_frontend repository. + url: mailto:support@comfy.org + about: Report package vulnerabilities privately to Comfy support. Include the package name and affected version; do not open a public issue. diff --git a/README.md b/README.md index 6f71beb6..0ae81e78 100644 --- a/README.md +++ b/README.md @@ -648,11 +648,14 @@ way. Published to npm as [`@comfyorg/comfy-multi-player`](https://www.npmjs.com/package/@comfyorg/comfy-multi-player): ```bash -npm install @comfyorg/comfy-multi-player +npm install --save-exact @comfyorg/comfy-multi-player@0.2.1 ``` -The server pins an **exact** published version. The frontend consumes the -workspace source from the same commit that produces that release. Conflict +This is an exact published-version example, not a claim that unreleased main +changes are included. Coordinate version upgrades across consumers. + +The server and frontend must pin the same **exact** published version. Package +development stays in the standalone repository; consumers do not vendor its source. Conflict resolution is a cross-process agreement about which write wins; two peers running different versions of these rules can disagree about the outcome. @@ -665,21 +668,22 @@ superseded) remains documented for historical context. ## Develop ```bash -pnpm install -pnpm run build # tsc → dist/ -pnpm test # vitest: schema, purity, replay, lww, convergence, roundtrip, applier -pnpm run check:purity # dependency-tree + bare-Node import gate -pnpm run check:imports # module-graph gate: no cycles, src imports yjs only, no Node builtins -pnpm run check:pins # cross-repo citations are pinned by SHA, not a moving ref -pnpm run verify:corpus # conformance fixtures match their pinned SHAs -pnpm run check:profile-claims # .agents/checks prose still matches the code it restates -pnpm run check:coderabbit # .coderabbit.yaml still matches the profiles that generate it +npm ci +npm run build # tsc → dist/ +npm test # vitest: schema, purity, replay, lww, convergence, roundtrip, applier +npm run check:purity # dependency-tree + bare-Node import gate +npm run check:imports # module-graph gate: no cycles, src imports yjs only, no Node builtins +npm run check:pins # cross-repo citations are pinned by SHA, not a moving ref +npm run verify:corpus # conformance fixtures match their pinned SHAs +npm run check:profile-claims # .agents/checks prose still matches the code it restates +npm run check:coderabbit # .coderabbit.yaml still matches the profiles that generate it ``` -The canonical source lives at -[`packages/comfy-multi-player`](https://github.com/Comfy-Org/ComfyUI_frontend/tree/main/packages/comfy-multi-player) -in the ComfyUI frontend workspace. Run these commands from that package directory, -or use `pnpm --filter @comfyorg/comfy-multi-player ` from the workspace root. +The canonical writable source is +[`Comfy-Org/comfy-multi-player`](https://github.com/Comfy-Org/comfy-multi-player). +Run these commands from this repository's root. Target package code, tests, docs, +and release tooling at standalone `main`. Frontend adapters belong on frontend +`main`; the deferred frontend migration is not a development base. `fixtures/` holds the replay corpus: recorded op sessions with their starting and final workflows, six conflict-resolution vectors, and the pinned catalog. diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index b2503b84..411136a0 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -2,7 +2,7 @@ ## 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 consume the same git-SHA-pinned package. 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-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. ADR-031 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. @@ -10,7 +10,7 @@ derives tree-wide IDs from `op_id`; producers submit raw IDs and do not inspect ## Guard gaps - ~~**Positive purity assertion (#22):**~~ **CLOSED.** `scripts/check-purity.mjs` asserts directly that the declared and resolved production dependency roots are exactly `{yjs}`, and `scripts/check-import-graph.mjs` asserts the same per source module via `src-runtime-dep-is-yjs-only`. A cross-language parity guard is still only warranted if a second-language implementation is proposed; the preferred policy remains no second implementation (tracked in the separate bullet below). -- **Property tests (#24):** cover arbitrary op sequences, legal causal permutations, retries, batch boundaries, actor counts, byte-identical idempotency, and schema-version failure on the normal read path. Narrowed by #38: the normal read path now HAS a schema gate (`project()` → `assertReadableSchema`), enumerated case-by-case in `test/schema-version-on-read.test.ts`, and **KA-11** no longer points here for it. What remains open under #24 is the PROPERTY-based form — the enumerated cases are hand-written, not generated. +- **Property tests (#24):** **PARTIALLY CLOSED.** `test/pbt-convergence.test.ts` generates actor counts, legal causal permutations, retries, batch boundaries, convergence, and byte-identical double-apply idempotency. `test/pbt-mint-project-roundtrip.test.ts` generates workflows and op streams for mint/apply/project round trips and retry determinism, with witness guards for optional metadata, definitions, slots, and widget features. These are fixed-seed samples, not exhaustive coverage. The normal read-path schema gate is covered case-by-case, not property-based, in `test/schema-version-on-read.test.ts`; generated malformed/non-current schema layouts remain a gap. - **Catalog-SHA lint (#22):** ~~fail on moving branch/tag citations in vocabulary and catalog references.~~ **Landed** as `scripts/check-pins.mjs` + `docs/upstream-pins.json` + `test/upstream-pins.test.ts`. Offline in CI; `npm run check:pins -- --verify-remote` additionally proves each pinned SHA still resolves upstream and each cited section still exists at it, and reports INCONCLUSIVE rather than passing when it cannot reach GitHub. Remaining, and the reason KA-12 keeps a scoped UNGUARDED marker: `meta.catalog_version`'s own sha256 shape is asserted by `test/catalog-sha-binding-integration.test.ts` but is not rejected at either write site — neither `mint()` (`src/mint.ts`) nor the module-private `initDoc()` helper (`src/doc.ts`) validates it, so `mint(workflow, catalog, "main")` still succeeds. That is Q4, not this lint. - **Conformance-corpus provenance (#23):** record generator repository and commit SHA, command, environment, and manifest; regenerate and diff in CI. - **Cross-language parity guard (#22):** if the single-package decision is deliberately revisited, both implementations must pass shared golden vectors before merge. @@ -22,4 +22,14 @@ These are follow-up behavior/CI tickets. The remaining ones do not change op sem ## Repository plan -Completed by [ComfyUI_frontend #16644](https://github.com/Comfy-Org/ComfyUI_frontend/pull/16644): active development and release ownership moved to `ComfyUI_frontend/packages/comfy-multi-player` after the V1 contract stabilized. This repository remains a read-only record of its standalone history, tags, and releases through 0.2.1. The package keeps the identical `@comfyorg/comfy-multi-player` import path; no second writable implementation remains here. +[Comfy-Org/comfy-multi-player](https://github.com/Comfy-Org/comfy-multi-player) is +the canonical writable source for package code, tests, documentation, and release +tooling. Target this repository's `main`; frontend adapters and consumers target +frontend `main` and pin the published package rather than relocating its source. + +The migration proposed in +[ComfyUI_frontend #16644](https://github.com/Comfy-Org/ComfyUI_frontend/pull/16644) +is closed and deferred, not completed. Preserve that PR and its descendant review +and QA records as recovery evidence, not as working branches or merge targets. +Future consolidation requires new explicit maintainer authorization; recovery +does not authorize package publication or deployment. diff --git a/docs/adr/0001-op-based-crdt-v1.md b/docs/adr/0001-op-based-crdt-v1.md index 67449fb8..d66cb41f 100644 --- a/docs/adr/0001-op-based-crdt-v1.md +++ b/docs/adr/0001-op-based-crdt-v1.md @@ -33,16 +33,16 @@ authority" is therefore not a design axis; the axes that matter are (a) applier Bootstrap/reconnect uses one naive full seeded snapshot (acknowledged to need later iteration). 3. **Persist raw ops end-to-end (V1 target).** Store raw ops so the system is replayable; derive ordering directly from the ops. The server-driven sequence number must NOT be the - conflict-resolution key — it may advance `base_version` but must never be the sole ordering - authority. (Today only an incrementing sequence pointer is persisted, so the system is not + conflict-resolution key and is independent of the creator-owned `base_version` + Lamport counter. (Today only an incrementing sequence pointer is persisted, so the system is not replayable and all reconnection hinges on that counter; fixing it needs new tables. Ops are small — data volume is not the blocker.) 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. **Defer the logical clock past V1.** A scalar `base_version` gives deterministic convergence for - V1; a vector/Lamport/HLC clock (faithful causality across long offline branches) is deferred and - requires op-sharing + replay first. See `src/types.ts` (`[base_version, actor, op_id]`) and +5. **Logical-clock decision superseded.** V1 originally deferred a logical clock. [ADR-0005](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`. 6. **Applier stays a pure, portable package** with no client-idiosyncratic local state and no DOM/framework/server-only deps, so it runs identically in browser and host (and a future peer). @@ -96,11 +96,10 @@ 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. `base_version` is a scalar version cursor the host - advances on apply, not a causal clock; `actor` and `op_id` are pure tie-breakers applied only - after it. The known limitation — a scalar cursor cannot faithfully represent causality across long - independent offline branches — is the deferred logical-clock item, out of V1 scope. Convergence - tests must deliver concurrent ops in both arrival orders and assert an identical winner. + identically offline — never from receive order. [ADR-0005](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. - **Invalid-op batch semantics: valid-prefix commit, abort remainder.** Ops in a batch apply in stamp order. The first invalid op aborts the remainder: the applied valid prefix is committed and persisted, `base_version` advances only for committed ops, and the unprocessed suffix (from the @@ -156,8 +155,8 @@ flowchart LR - **Positive:** future peer-to-peer / LAN, hostless multiplayer on hosted or enterprise 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; a proper - logical clock and conflict UX are deferred. +- **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. - **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,6 +178,6 @@ flowchart LR - **Room host** — the server node process holding the in-memory Yjs doc for a workflow; a V1 convenience, not a conflict authority. - **Headless peer** — the agent replica running with no browser attached. -- **base_version** — scalar version pointer; advances on apply. A V1 ordering aid, not the - permanent conflict key. +- **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. - **LWW** — last-writer-wins; here resolved by the op stamp, never by client-id or a DB read. diff --git a/docs/api-contract-proposal.md b/docs/api-contract-proposal.md index 0413e5e7..ab8043a4 100644 --- a/docs/api-contract-proposal.md +++ b/docs/api-contract-proposal.md @@ -9,10 +9,16 @@ Two halves: - **Part 2 — open questions.** Not settled. This is what the meeting is for. Each has a recommendation and the trade-off it costs. -Grounded against the source at `6793d75`, `docs/multiplayer-schema.md`, and the -op vocabulary in comfy-cli. Nothing on a default branch consumes this package -yet — the server doc host lives on an unmerged branch — so a contract change is -still cheap. That will not stay true. +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 +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 +claim that no default-branch consumers existed and contract changes were cheap +is obsolete. This correction does not assert their current deployed versions +or revalidate every historical proposal below. --- diff --git a/docs/decisions/ADR-001-single-shared-applier.md b/docs/decisions/ADR-001-single-shared-applier.md index d1b98fb8..ddb13d0b 100644 --- a/docs/decisions/ADR-001-single-shared-applier.md +++ b/docs/decisions/ADR-001-single-shared-applier.md @@ -14,7 +14,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 pinned by immutable git SHA. +- Browser and Node host consume the same package at the same exact published npm version (ADR-006). - 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/decisions/ADR-005-read-only-snapshot-surface.md b/docs/decisions/ADR-005-read-only-snapshot-surface.md index e550aa7c..b2256dcb 100644 --- a/docs/decisions/ADR-005-read-only-snapshot-surface.md +++ b/docs/decisions/ADR-005-read-only-snapshot-surface.md @@ -38,7 +38,7 @@ entrypoint: `readGraph`, `readMeta`, `docCatalogPin`, `hasNode`, constant. Every entry maps to a demonstrated call site above; nothing was added for symmetry. -The surface is enforced, not conventional. Four mechanical properties, each +The surface is enforced, not conventional. Five mechanical properties, each proved by attempting the violation in `test/readonly-surface.test.ts`: 1. **No live handle escapes.** Nothing reachable from a return value is a diff --git a/docs/decisions/ADR-006-publish-to-npm-pin-exact-versions.md b/docs/decisions/ADR-006-publish-to-npm-pin-exact-versions.md index fcfb7a33..e250f3ca 100644 --- a/docs/decisions/ADR-006-publish-to-npm-pin-exact-versions.md +++ b/docs/decisions/ADR-006-publish-to-npm-pin-exact-versions.md @@ -12,6 +12,11 @@ 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. +At this decision's 2026-08-22 acceptance, `0.1.0` was the published release. +The repository manifest is currently version `0.2.1` with the +`GPL-3.0-only` license; this current-state note does not announce or perform a +new npm release. + All three consumers use the registry release: ComfyUI frontend, the cloud `services/agent/dochost` sidecar on `main`, and the `examples/dochost` example merged in PR #27. Git-SHA pinning has therefore been retired in practice. @@ -19,7 +24,8 @@ merged in PR #27. Git-SHA pinning has therefore been retired in practice. ## Decision Publish `@comfyorg/comfy-multi-player` to the npm registry and have every -consumer pin an exact published version. The current shared version is `0.1.0`. +consumer pin an exact published version. At acceptance, the shared published +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 @@ -33,8 +39,9 @@ where they rely on identical applier behavior (ADR-001). do not use version ranges for the shared applier. - Publishing a new version is an explicit maintainer action with its own cadence, separate from merging repository changes. -- Version `0.1.1` is pending to carry the package's license metadata after the - GPL-3.0 license change lands. +- The repository manifest and `LICENSE` now identify the package as + `GPL-3.0-only`; the earlier pending `0.1.1` license-metadata plan is historical + and no longer current. - Consumers install the prebuilt registry artifact and no longer need to allow this package's git-dependency `prepare` script. diff --git a/docs/decisions/EXCEPTIONS.md b/docs/decisions/EXCEPTIONS.md index 5121f914..1d6ba83a 100644 --- a/docs/decisions/EXCEPTIONS.md +++ b/docs/decisions/EXCEPTIONS.md @@ -6,7 +6,7 @@ Deliberate deviations from `docs/INVARIANTS.md` require explicit maintainer revi | --- | --- | --- | --- | --- | | YYYY-MM-DD | KA-0 / FC-0 | Decision and approver | Exact files, release, or deployment | Date or removal condition | | ~~2026-08-21 (PROPOSED)~~ **RESOLVED 2026-08-21** | KA-4 | ~~Four `connect` rejections mutate before validating (issue #10).~~ **Sunset condition met: PR #34 landed.** The block asserting the bug went red exactly as designed, the four rows moved into `CASES` in `test/ka4-rejection-byte-identity.test.ts`, and `KNOWN_KA4_VIOLATIONS` is now empty. Struck rather than deleted so the exception's full life stays legible. | (was `src/applier.ts` `connect` paths) | Expired. Amendment A9 closes the cloneable-but-unstorable, `link_id`, and `removed_links` write-order holes; Amendment A10 closes cycles; Amendment A14 closes the `link_type` shape hole before any write. | -| 2026-08-21 (PROPOSED) | KA-4 | **Permanent convergence carve-outs**, schema §2.5 items 4-6 and 8 / Amendment A6, and the RULE that generates them: a rejection is arrival-order-dependent exactly when the check raising it READS THE DOCUMENT and sits below an early return that consumes the `op_id` (a delete-wins return or the interior null return). 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 | **No sunset — deliberate.** A6 rejects three alternatives with reasons; closing any remaining item either re-opens issue #10 or changes the concrete-input register's semantics, which is a vocabulary change needing a comfy-cli counterpart. Remaining items are pinned by still-diverges tests. Revisit only via a new amendment. | +| 2026-08-21 (PROPOSED) | KA-4 | **Permanent convergence carve-outs**, schema §2.5 items 4-6 and 8 / Amendment A6, and the RULE that generates them: a rejection is arrival-order-dependent exactly when the check raising it READS THE DOCUMENT and sits below an early return that consumes the `op_id` (a delete-wins return or the interior null return). 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-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-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). | diff --git a/docs/multiplayer-schema.md b/docs/multiplayer-schema.md index 4a1397b4..c3cfca9c 100644 --- a/docs/multiplayer-schema.md +++ b/docs/multiplayer-schema.md @@ -1345,9 +1345,10 @@ consumer repositories at their current revisions, not by analogy to A3: `clear`'s `groups`, and `clear` preserves everything else. - **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.** It now consumes the - canonical workspace source from `packages/comfy-multi-player`; this historical compatibility - argument applied before that migration, not to future package changes. +- **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 + 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 response embeds a projection computed after `applyOps`). `/mint` and `/resync` do not. diff --git a/docs/mutation-testing.md b/docs/mutation-testing.md index da96deb5..8688e4fd 100644 --- a/docs/mutation-testing.md +++ b/docs/mutation-testing.md @@ -1,107 +1,37 @@ # Mutation testing -Stryker measures whether the test suite detects behavioral regressions in the load-bearing CRDT code. The scope is `src/applier.ts`, `src/stamps.ts`, `src/project.ts`, `src/doc.ts` and `src/mint.ts`; tests, `src/index.ts` (re-exports only), `src/types.ts` (declarations), `src/exhaustive.ts` (a compile-time helper whose one runtime line is a `throw`) and `src/migrate.ts` are not mutated. Two semantic files remain unmeasured and should join the glob next: `src/migrate.ts` (kept out only because PR #30 owned it while this branch was written — #30 has merged and made it the fail-closed read gate) and `src/schema-version.ts`, which #60 added after this glob was set and which now holds the ONE definition of the schema read that `migrate()` and `project()` share. +Stryker measures whether the test suite detects behavioral regressions in the load-bearing CRDT code. The configured scope is `src/applier.ts`, `src/stamps.ts`, `src/project.ts`, `src/doc.ts`, and `src/mint.ts`. Tests, re-export-only `src/index.ts`, declarations in `src/types.ts`, and the compile-time helper `src/exhaustive.ts` are not mutated. `src/migrate.ts` and `src/schema-version.ts` are semantic files that should join the scope in a separately measured change. -`src/doc.ts` and `src/mint.ts` were added in MUT-GLOB-KA4-1 and had never been mutated before that. Do not narrow the glob back: the two files carry the schema §1 doc layout, the §1.2 opaque-widgets routing, the §5.3 shared-definition instance count and the §9 bootstrap-snapshot path, and every one of those was unmeasured while the score read 80.00%. +`src/doc.ts` and `src/mint.ts` joined the scope in MUT-GLOB-KA4-1. Do not narrow it back: those files carry the schema §1 document layout, §1.2 opaque-widget routing, §5.3 shared-definition instance count, and §9 bootstrap-snapshot path. ## The score only means something because the run is pinned -Stryker classifies each mutant `Killed`, `Survived`, `Timeout`, `NoCoverage` or an error, and **scores a `Timeout` as detected**. That is right for a mutant that genuinely cannot terminate (`while (…)` mutated to `while (true)`) and wrong for a mutant that merely ran slowly because the machine was busy — and the report cannot tell those apart on its own. With `timeoutMS` and `concurrency` left at their defaults, the score is therefore a function of host load, and it moves in the flattering direction: **more contention, more timeouts, higher score.** - -Measured on this repo, four runs of one commit on one machine, two configurations by two load levels ("contended" = 20 CPU spinner processes for the duration of the run): - -| Config | Contended | Killed | Timeout | Survived | NoCov | Score | -| --- | --- | --- | --- | --- | --- | --- | -| pinned | no | 732 | 8 | 154 | 31 | **80.00%** | -| pinned | **yes** | 733 | 7 | 154 | 31 | **80.00%** | -| unpinned | no | 732 | 8 | 154 | 31 | 80.00% | -| unpinned | **yes** | 732 | **21** | **141** | 31 | **81.41%** | - -A fifth run of the pinned config on Node 22 — the version `mutation.yml` uses — reproduced the pinned rows exactly, including every per-file column, so the number does not depend on the Node major either. - -The pinned rows are identical to two decimals, and their `Survived` and `NoCoverage` sets are element-for-element identical — the survivor *list*, which is what a coverage-gap audit actually consumes, does not move. Only one non-terminating loop mutant swapped between `Killed` and `Timeout`, and both count as detected, so it is score-neutral. - -The unpinned rows show what the pins are for. Unpinned and idle the number happens to agree; unpinned and loaded it gains 1.41 points, because 13 mutants that really do survive — seven on `validateEnvelope`'s `typeof` guard at `src/applier.ts:203`, six in `project.ts`, none of them anywhere near a loop — exceed the default 5s budget and are scored as kills. - -`stryker.config.mjs` pins `timeoutMS`, `timeoutFactor`, `concurrency` and `coverageAnalysis` for exactly this reason. **Do not unpin them.** A score produced with different values is not comparable to any score recorded here. - -`dryRunTimeoutMinutes` is pinned separately from the mutation score knobs. It -only bounds Stryker's initial unmutated Vitest pass; it does not decide whether -any mutant is `Killed`, `Survived` or `Timeout`. The scheduled workflow reached -Stryker's default 5 minute initial dry-run ceiling on 2026-08-31 before it could -write `reports/mutation/mutation.json`, so the report checker and artifact -upload failed only as downstream symptoms. Raising this dry-run cap keeps the -nightly from failing before the measured mutation phase while preserving the -per-mutant `timeoutMS`, `timeoutFactor`, `concurrency` and `coverageAnalysis` -pins that make scores comparable. - -Incremental mode reuses results only when Stryker proves that the mutant and its -covering tests are unchanged. CI restores `reports/stryker-incremental.json` from -a cache keyed by the operating system, `package-lock.json`, and -`stryker.config.mjs`; changing a dependency or any pinned measurement setting -therefore forces a full run. Each workflow run uses a unique cache save key and -restores the newest compatible report, avoiding GitHub Actions cache-key -immutability while still carrying results forward. - -## Current baseline - -Measured 2026-08-21 on the pinned settings over the five-file glob, at `main` = `9e3e38e`: -**85.24% overall** across 1328 mutants (`applier.ts` 80.55%, `doc.ts` 94.09%, `mint.ts` 88.68%, -`project.ts` 87.43%, `stamps.ts` 89.00%), with 1126 killed / 6 timeout / 168 survived / 28 -no-coverage. The break threshold is **84**, 1.24 points under the measured score for the reason #56 -recorded when it set the three-file threshold to 79 rather than to the 80.00% it had just measured: -a threshold equal to the measurement passes with zero margin and goes red the first time a sibling -PR adds an uncovered line, reporting "mutation score regression" when it means "new code arrived". -Raise the threshold whenever the score is raised; the headroom is for new code, not for measurement -noise, which the pins have removed. The timeouts-as-survivors floor — the score if every timeout -were really a survivor — is 84.79%, which is also above the threshold, so the pass does not depend -on how the 6 timeouts are classified. - -**Host conditions, stated because this number is load-sensitive by construction.** Both runs below -were taken on a 28-core host at 1-minute load averages of **2.16** (baseline) and **0.85** (branch), -Node 25.9.0, pins untouched. An earlier attempt at this measurement was made while the host carried -five concurrent agents at load 15-19; one of its runs was killed by the OOM killer, and none of that -attempt's figures are reported here. Refusing to publish a number measured under those conditions is -the correct outcome, not a gap. - -Per-scope movement, kept because the *shape* of the change matters more than the headline. Both -"before" columns are a real run of the SAME five-file glob against `origin/main` `9e3e38e` (passed -on the command line with `--mutate`, pins untouched), so the only difference between the columns is -this branch: - -| Scope | Before (`9e3e38e`) | After | What moved | -| --- | --- | --- | --- | -| five-file overall | 79.92% (1031/1290) | **85.24%** (1132/1328) | both rows below | -| `applier.ts` + `stamps.ts` + `project.ts` | 81.52% (803/985) | 82.74% (815/985) | the KA-4 rejection sweep (`test/ka4-rejection-byte-identity.test.ts`) | -| `doc.ts` + `mint.ts` | 74.75% (228/305, first ever run) | 92.42% (317/343) | `test/doc-mint-mutation-survivors.test.ts` | - -Reproducibility of the five-file glob, measured rather than asserted. At the previous base this -branch was run twice, at load averages 2.99 and 8.90: identical to two decimals and in every -per-file killed/timeout/survived/no-coverage column. At the base before that it was run twice more -and the `Killed`, `Timeout`, `Survived` and `NoCoverage` **sets** were element-for-element -identical, symmetric difference zero. What is stable is the survivor *list*, not merely the -percentage. The overall score does move between bases — 85.31% at `32ab1f2`, 85.24% here — but only -because `main` itself moved: #60 added one `project.ts` survivor. That is exactly why a "before" is -re-measured at the same commit rather than quoted from a previous run. - -The `doc.ts` + `mint.ts` mutant total rises from 305 to 343 because the fix itself adds code, so the -"after" column is measured over more surface, not less. - -The three-file scope reads 81.61% here rather than the 80.00% (740/925) `main` recorded when the pin -landed, because #67 and #31 have since added tests and code. That is the point of re-measuring the -baseline at the same commit rather than quoting a stored number: a "before" from a different `main` -is not a before. - -Adding files to the glob moves the headline for two reasons at once — new mutants, and new tests — so compare per-file columns, never the single overall number, when judging whether a change helped. - -Earlier figures on this page do not survive. **63.70%** (once recorded here) and **74.81%** (recorded in the workspace) were produced with the knobs unpinned and are void — not low, not high, just not measurements of the test suite. - -One more figure is withdrawn rather than merely stale. An earlier revision of this branch cited -**81.41%** as the "after" for the three-file scope. That number is `main`'s **unpinned, under -contention** three-file figure from the two-by-two table above — a documented measurement artifact, -not a measurement of this branch. Do not re-cite it. - -The triple **84.38% / 88.01% / 74.59%** was previously cited here as the proof of load-sensitivity. It is withdrawn, and for a sharper reason than staleness: those three runs differed in their `coverageAnalysis`/`timeoutMS`/`concurrency` *flags*, not in host load, so they never evidenced the load claim they were offered for. They do show the score is a function of the knobs. The load half is the two-by-two table above, measured here at fixed settings. +Stryker classifies each mutant as `Killed`, `Survived`, `Timeout`, `NoCoverage`, or an error, and scores a `Timeout` as detected. That is appropriate for a genuinely non-terminating mutant and misleading for one that merely exceeded its budget on a busy host. Host-dependent timeout and worker defaults can therefore move the score in the flattering direction by reclassifying survivors as timeouts. + +`stryker.config.mjs` pins `timeoutMS`, `timeoutFactor`, `concurrency`, and `coverageAnalysis` for this reason. A score produced with other values is not comparable. `dryRunTimeoutMinutes` separately bounds the initial unmutated Vitest pass and does not classify individual mutants. + +The scheduled workflow reached Stryker's default five-minute initial dry-run +ceiling on 2026-08-31 before writing `reports/mutation/mutation.json`. +The missing checker report and artifact were downstream symptoms. Raising +`dryRunTimeoutMinutes` lets the unmutated suite finish without changing +per-mutant classification settings. + +Incremental mode reuses a result only when Stryker determines that the mutant and its covering tests are unchanged. CI keys the incremental report by the operating system, dependency lock, and Stryker configuration, so changing a dependency or pinned measurement setting starts a full run. + +Each workflow run uses a unique cache save key and restores the newest compatible +report, avoiding immutable cache-key reuse while carrying results forward. + +## Baseline policy + +No measured baseline is published here without retained output from `npm run check:mutation-report`. The available archived report belongs to a different historical checkout and configuration, so it cannot validate the figures formerly quoted here or in `stryker.config.mjs`. + +The removed tables and withdrawn measurements remain in Git history; they are +not a current baseline and must not be re-cited without their matching report, +configuration, source revision, host conditions, and passing checker receipt. + +The configured break threshold remains **84**. Keep a threshold below a freshly checked baseline rather than equal to it: zero margin turns the first uncovered line in a sibling change into a nominal score regression. Raise the threshold when the checked baseline rises. That headroom is for new code, not measurement noise. + +Adding files to the mutation glob changes both the mutant population and the tests that run. Compare checked per-file outcomes, not only the overall score, when judging a change. ## Running it @@ -112,21 +42,16 @@ npm run test:mutation npm run check:mutation-report ``` -Node 22 or newer. +Use Node 22 or newer. Do not quote a score unless the checker passes and its output is retained with the baseline evidence. -`check:mutation-report` is the fail-closed half of the fix. It re-derives the score from `reports/mutation/mutation.json`, prints `Timeout` as its own outcome next to the "timeouts-as-survivors floor" the score cannot fall below, and exits: +`check:mutation-report` re-derives the score from `reports/mutation/mutation.json`, reports `Timeout` separately, and also computes a floor with every timeout treated as a survivor. It exits: | Exit | Meaning | | --- | --- | -| 0 | conclusive, at or above the break threshold | -| 1 | conclusive, below the break threshold | -| 2 | **INCONCLUSIVE** — no report, fewer than 500 mutants, more than 2% of detected mutants were timeouts, or the report carries no `thresholds.break` to judge against | - -INCONCLUSIVE is not a pass. Re-run on a quieter machine; do not record the score. - -Stryker writes local HTML and JSON reports plus the incremental report under -`reports/`; generated reports and `.stryker-tmp/` are ignored by git. -`.github/workflows/mutation.yml` runs nightly and by manual -`workflow_dispatch`, not on every pull request; it caches the incremental report -and uploads `reports/mutation/` as a build artifact so a failing run leaves -something to read. +| 0 | Conclusive and at or above the break threshold | +| 1 | Conclusive and below the break threshold | +| 2 | **INCONCLUSIVE**: missing, unreadable or unparseable report; fewer than 500 total mutants (including zero); zero valid mutants; more than 2% of detected mutants timed out; or no numeric `thresholds.break` value | + +INCONCLUSIVE is not a pass. Re-run on a suitable host and retain the checker output; do not record the score. + +Stryker writes local HTML and JSON reports plus the incremental report under `reports/`. Generated reports and `.stryker-tmp/` are ignored. `.github/workflows/mutation.yml` runs nightly and by manual dispatch, caches the incremental report, and uploads `reports/mutation/` as an artifact. diff --git a/docs/upstream-pins.json b/docs/upstream-pins.json index 5402b55a..477a64f9 100644 --- a/docs/upstream-pins.json +++ b/docs/upstream-pins.json @@ -112,7 +112,7 @@ "cited_by": [ "src/schema-version.ts" ], - "access_note": "Comfy-Org/cloud is PRIVATE. `npm run check:pins -- --verify-remote` resolves this pin only with a token that has access; without one the GitHub API answers 404, which this gate treats as definitive evidence ABOUT THE PIN (exit 1) rather than about the request (exit 2). That classification was deliberately introduced by #66 and is right for a public repo; it mis-fires here. Read a 404 on this pin as 'no access', not 'pin broken', until the gate learns to tell them apart.", + "access_note": "Comfy-Org/cloud is PRIVATE. `npm run check:pins -- --verify-remote` resolves this pin only with a token that has Contents read access. GitHub fine-grained permissions separate Metadata read from Contents read, and inaccessible private resources may return 404. Therefore an ambiguous commit/path 404 triggers a repository metadata lookup, but even matching metadata with `private: true` remains INCONCLUSIVE (exit 2): metadata visibility does not prove Contents access. Only matching metadata with explicit `private: false` makes an object 404 a definite violation (exit 1), because public contents need no permission. Missing, nonboolean, malformed, inaccessible, or indeterminate visibility is also INCONCLUSIVE. This safe limitation means a genuinely missing private object reported as 404 remains inconclusive; successful private commit/content probes still pass. It preserves #66's historical rationale for treating genuine object-scoped 422/451 responses as failures without falsely declaring a private pin broken when endpoint permission was never established.", "upstream_head_observed": { "date": "2026-08-21", "ref": "main", diff --git a/fixtures/MANIFEST.json b/fixtures/MANIFEST.json index e87c8e25..6d5fb0df 100644 --- a/fixtures/MANIFEST.json +++ b/fixtures/MANIFEST.json @@ -14,7 +14,8 @@ }, "findings.json": { "generator": "crdt-spike/gen_fixtures.py: workflow_ops probe capture", - "sha256": "c9015f64f66e5fe842671cc808c363ddb007abb78f9e5919c339cd2c35297efe" + "notes": "Historical probe capture, not regenerated. The clear-scope prose was manually corrected on 2026-09-18 against test/clear-empty-removed-nodes.test.ts and the current applier; source request: https://github.com/Comfy-Org/ComfyUI_frontend/pull/16644#discussion_r3914401872. Executable vectors are unchanged.", + "sha256": "d1462ed6786745e843f651dea8889b189f875f41358d14fa3cb7fca1b18d691e" }, "lww-vectors.json": { "generator": "crdt-spike/gen_fixtures.py: workflow_ops.apply_op both-order vectors", diff --git a/fixtures/findings.json b/fixtures/findings.json index 4e57155b..b94ce258 100644 --- a/fixtures/findings.json +++ b/fixtures/findings.json @@ -5,7 +5,7 @@ }, { "topic": "clear-scope", - "detail": "`clear` empties nodes, links, and groups but NOT `extra` and NOT definitions.subgraphs; last_node_id/last_link_id are preserved by design (id-reuse guard). _widget_stamps also survive a clear." + "detail": "`clear.removed_nodes` is the authoritative target set: an empty list removes no nodes, while listed node IDs and their incident links are removed. `clear` empties groups but NOT `extra` and NOT definitions.subgraphs; last_node_id/last_link_id are preserved by design (id-reuse guard). _widget_stamps also survive a clear." }, { "topic": "Q6-subgraph-op-scope", @@ -16,4 +16,4 @@ "delete-interior-node": "node 57/27 not found in workflow. Nodes in this workflow: 57 (f2fdebf6-dfaf-43b6-9eb2-7f70613cfdc1), 9 (EmptyLatentImage), 2943932432288920 (LoadImage), 1991397258626261 (SaveImage). Use an id from `comfy workflow slots` / `ls-nodes` \u2014 never rebuild it." } } -] \ No newline at end of file +] diff --git a/scripts/check-pins.mjs b/scripts/check-pins.mjs index e99523e6..55f7703a 100644 --- a/scripts/check-pins.mjs +++ b/scripts/check-pins.mjs @@ -44,8 +44,10 @@ * * Exit codes: 0 pinned, 1 violation, 2 inconclusive (registry missing or * unparseable, nothing scanned, or — in remote mode — no definitive answer from - * upstream). "No definitive answer" includes an unusable token and a rate limit: - * only 404/422/451 are evidence about a pin. + * upstream). "No definitive answer" includes an unusable token, a rate limit, + * and a 404 unless repository metadata explicitly establishes that the + * repository is public. Metadata access to a private repository does not prove + * Contents permission. 422/451 remain object-scoped answers by themselves. */ import { spawnSync } from "node:child_process"; @@ -328,7 +330,10 @@ if (ghProbe.error || ghProbe.status !== 0) { * Statuses that are evidence about the OBJECT that was asked for. Only these * may be read as "this pin is broken". * - * 404 — no such commit/path in this repository + * 404 — no such commit/path, but only after repository metadata identifies + * the matching repository and explicitly says it is public. Public + * contents need no endpoint permission; private metadata visibility + * does not establish private Contents permission. * 422 — the SHA is well-formed but names no object here * 451 — the object exists but is legally unavailable; not a pin problem to * fix by re-pinning, but it is a definite answer about this object @@ -358,15 +363,57 @@ function gh(endpoint) { }; } -function requireDefinitive(result, what) { - if (result.ok || result.definitive) return; +function establishPublicRepository(slug) { + const repository = gh(`repos/${slug}`); + if (!repository.ok) { + const status = repository.http === null ? "no HTTP status (DNS/TLS/proxy)" : `HTTP ${repository.http}`; + inconclusive( + `could not establish public repository visibility for ${slug} — ${status}`, + repository.stderr.split("\n")[0] || "no error output", + "GitHub hides inaccessible private repositories behind 404, so this response cannot prove", + "whether the repository is hidden or the requested commit/path is genuinely absent.", + `Offline result: ${errors.length === 0 ? "clean" : `${errors.length} violation(s)`}`, + ); + } + + let metadata; + try { + metadata = JSON.parse(repository.stdout); + } catch { + inconclusive(`repository metadata for ${slug} was malformed, so repository visibility was not established`); + } + if ( + !metadata || + typeof metadata !== "object" || + typeof metadata.full_name !== "string" || + metadata.full_name.toLowerCase() !== slug.toLowerCase() || + typeof metadata.private !== "boolean" + ) { + inconclusive(`repository metadata for ${slug} was malformed, so repository visibility was not established`); + } + if (metadata.private) { + inconclusive( + `repository metadata for ${slug} identifies a private repository, but metadata visibility does not prove Contents access`, + "GitHub fine-grained permissions separate Metadata read from Contents read. A private-object", + "404 may therefore mean either a missing object or missing endpoint permission.", + ); + } +} + +function requireDefinitive(result, what, slug) { + if (result.ok) return; + if (result.http === 404) { + establishPublicRepository(slug); + return; + } + if (result.definitive) return; const status = result.http === null ? "no HTTP status (DNS/TLS/proxy)" : `HTTP ${result.http}`; inconclusive( `could not get a definitive answer from GitHub while checking ${what} — ${status}`, result.stderr.split("\n")[0] || "no error output", "This is NOT a passing pin and NOT a failing pin — the check did not happen.", - "Only 404/422/451 are answers about the object; 401/403/429/5xx are answers about the", - "request (credentials, rate limit, outage) and prove nothing about the pin.", + "Only 422/451, or 404 after public repository visibility is established, are answers about the", + "object; 401/403/429/5xx are about the request and prove nothing about the pin.", `Offline result: ${errors.length === 0 ? "clean" : `${errors.length} violation(s)`}`, ); } @@ -393,7 +440,7 @@ for (const [id, pin] of Object.entries(pins)) { const slug = pin.repo.replace(/^https:\/\/github\.com\//, "").replace(/\.git$/, ""); const commit = gh(`repos/${slug}/commits/${pin.commit}`); - requireDefinitive(commit, `${id} commit ${pin.commit}`); + requireDefinitive(commit, `${id} commit ${pin.commit}`, slug); if (!commit.ok) { errors.push( `${id}: commit ${pin.commit} no longer resolves in ${slug} — ${commit.stderr.split("\n")[0]}`, @@ -402,7 +449,7 @@ for (const [id, pin] of Object.entries(pins)) { } const contents = gh(`repos/${slug}/contents/${pin.path}?ref=${pin.commit}`); - requireDefinitive(contents, `${id} path ${pin.path}`); + requireDefinitive(contents, `${id} path ${pin.path}`, slug); if (!contents.ok) { errors.push(`${id}: ${pin.path} is absent at ${pin.commit} in ${slug}`); continue; diff --git a/src/clock.ts b/src/clock.ts index 1701a468..1afb78d9 100644 --- a/src/clock.ts +++ b/src/clock.ts @@ -86,12 +86,12 @@ export function observedDocCounter(doc: Y.Doc): number | undefined { } export function validateLamportCounter(value: unknown, allowZero = false): number { - if (!Number.isSafeInteger(value) || (value as number) < (allowZero ? 0 : 1)) { + if (typeof value !== "number" || !Number.isSafeInteger(value) || value < (allowZero ? 0 : 1)) { throw new RangeError( `Lamport counter must be a ${allowZero ? "non-negative" : "positive"} safe integer`, ); } - return value as number; + return value; } export function observeLamport(local: number, ...observed: number[]): number { diff --git a/stryker.config.mjs b/stryker.config.mjs index 2d61b232..e6a3e821 100644 --- a/stryker.config.mjs +++ b/stryker.config.mjs @@ -6,17 +6,13 @@ * knobs left at their defaults the mutation score is a function of host load * rather than of the test suite — and it moves in the flattering direction: the * busier the machine, the more mutants time out, the HIGHER the score. - * Measured on this tree, unpinned: 80.00% idle and 81.41% under 20 CPU - * spinners, because 13 real survivors were reclassified as timeouts and scored - * as kills. Do not unpin these without re-measuring; any score produced with + * Do not unpin these without a checked measurement; any score produced with * different values is not comparable. * * `coverageAnalysis: "all"` rather than `"perTest"`: `"all"` runs every test * against every mutant, so the outcome cannot depend on Stryker's per-test - * coverage attribution. On this tree the two agree on an idle host (identical - * 154-survivor set), and `"all"` costs about 2.4x the wall time; it is pinned - * because it removes a variable, not because `perTest` was observed to - * mis-classify here. + * coverage attribution. It is pinned because it removes a variable, not + * because `perTest` is assumed to mis-classify here. * * @type {import('@stryker-mutator/api/core').PartialStrykerOptions} */ @@ -55,21 +51,12 @@ export default { timeoutFactor: 1.5, // Fixed worker count so the measurement does not vary with core count. concurrency: 4, - // Measured 2026-08-21 on the pinned settings above, over the five-file glob: - // 85.24% overall (1328 mutants; 1126 killed / 6 timeout / 168 survived / 28 - // no-coverage), on an idle host (load average 0.85). The SAME glob run - // against the parent commit 9e3e38e scores 79.92% over 1290 mutants — a real - // baseline run, not a stored figure — so the delta is this branch and nothing - // else. See docs/mutation-testing.md. - // - // Threshold sits strictly UNDER the measured score, not at it — the rule #56 - // wrote in when it set the three-file threshold to 79 rather than to the - // 80.00% it had just measured (it raised it from 60; it never shipped 80). A + // Threshold must sit strictly under a checker-validated score, not at it. A // threshold equal to the measurement passes with zero margin and turns red on // the first uncovered line any sibling PR adds, a failure that would say // "mutation score regression" while meaning "new code arrived". Raise it // whenever the score is raised; the margin is for new code, NOT for - // measurement noise, which is now zero. + // measurement noise. Pinning alone does not prove noise is zero. thresholds: { break: 84, low: 84, diff --git a/test/batch-limit-boundary.test.ts b/test/batch-limit-boundary.test.ts index 875eb56d..745e99cf 100644 --- a/test/batch-limit-boundary.test.ts +++ b/test/batch-limit-boundary.test.ts @@ -1,7 +1,9 @@ /** Current-behavior characterization of the `applyOps` batch-size gate. */ -import { encodeStateAsUpdate, type Doc } from "yjs"; +import { encodeStateAsUpdate } from "yjs"; +import type { Doc } from "yjs"; import { describe, expect, it } from "vitest"; -import { applyOps, mint, type Op, type WidgetCatalog, type WorkflowJSON } from "../src/index.js"; +import { applyOps, mint } from "../src/index.js"; +import type { Op, WidgetCatalog, WorkflowJSON } from "../src/index.js"; import { MAX_OPS_PER_BATCH } from "../src/limits.js"; const catalog: WidgetCatalog = { diff --git a/test/bounded-writes-liveness.test.ts b/test/bounded-writes-liveness.test.ts index 08388201..7180e4d8 100644 --- a/test/bounded-writes-liveness.test.ts +++ b/test/bounded-writes-liveness.test.ts @@ -176,7 +176,7 @@ describe("schema §11: the counter measures the applier's real writes", () => { // through raw Y instead of `mset` would drop below three; anything that // writes more would rise above it. Both are the gate losing its meaning. const doc = mint(hubWorkflow(1), catalog); - const op = { op: "set_widget", ...env(0), node_id: 1, widget: "text", value: "z" } as SetWidgetOp; + const op: SetWidgetOp = { op: "set_widget", ...env(0), node_id: 1, widget: "text", value: "z" }; _resetMutationCount(doc); expect(applyOps(doc, [op], catalog).outcomes.some((o) => o.outcome === "rejected")).toBe(false); expect(_getMutationCount(doc)).toBe(3); @@ -189,7 +189,7 @@ describe("schema §11: the counter measures the applier's real writes", () => { _resetMutationCount(doc); const running: number[] = []; for (let i = 0; i < 4; i++) { - const op = { op: "set_widget", ...env(i), node_id: 1, widget: "text", value: "v" + String(i) } as SetWidgetOp; + const op: SetWidgetOp = { op: "set_widget", ...env(i), node_id: 1, widget: "text", value: "v" + String(i) }; expect(applyOps(doc, [op], catalog).outcomes.some((o) => o.outcome === "rejected")).toBe(false); running.push(_getMutationCount(doc)); } @@ -205,7 +205,7 @@ describe("schema §11: the counter measures the applier's real writes", () => { // ledger rows used to canonicalize concurrent grows; neither is an LWW // gate that can discard a grow. const doc = mint(chainWorkflow(), catalog); - const op = { + const op: ConnectOp = { op: "connect", ...env(0), link_id: 9, @@ -215,7 +215,7 @@ describe("schema §11: the counter measures the applier's real writes", () => { to_slot: null, link_type: "X", grow: { name: "gin", type: "X" }, - } as unknown as ConnectOp; + }; _resetMutationCount(doc); expect(applyOps(doc, [op], catalog).outcomes.some((o) => o.outcome === "rejected")).toBe(false); expect(_getMutationCount(doc)).toBe(9); @@ -240,7 +240,7 @@ describe("schema §11: the counter measures the applier's real writes", () => { // cost zero Y-writes — if a skipped op still wrote, the ceiling would be // absorbing work that the idempotency gate is supposed to have removed. const doc = mint(hubWorkflow(1), catalog); - const op = { op: "set_widget", ...env(0), node_id: 1, widget: "text", value: "z" } as SetWidgetOp; + const op: SetWidgetOp = { op: "set_widget", ...env(0), node_id: 1, widget: "text", value: "z" }; const first = applyOps(doc, [op], catalog); expect(first.outcomes.some((o) => o.outcome === "rejected")).toBe(false); expect(first.outcomes.filter((o) => o.outcome === "applied").map((o) => o.op_id)).toEqual([op.op_id]); diff --git a/test/catalog-sha-binding-integration.test.ts b/test/catalog-sha-binding-integration.test.ts index b39e20ad..48e99b91 100644 --- a/test/catalog-sha-binding-integration.test.ts +++ b/test/catalog-sha-binding-integration.test.ts @@ -72,7 +72,9 @@ describe("catalog SHA binding across mint → apply → project (KA-12 / FC-10)" it("flags a moving branch-style catalog citation", () => { const doc = mint(workflow, catalog, "main"); - expect(() => assertImmutableCatalogCitation(metaMap(doc).get("catalog_version"))).toThrow( + const catalogVersion = metaMap(doc).get("catalog_version"); + expect(catalogVersion).toBe("main"); + expect(() => assertImmutableCatalogCitation(catalogVersion)).toThrow( "KA-12 / FC-10: catalog_version must be an immutable sha256, got 'main'", ); }); diff --git a/test/ci-release-contract.test.ts b/test/ci-release-contract.test.ts index ffbd73b4..e087671b 100644 --- a/test/ci-release-contract.test.ts +++ b/test/ci-release-contract.test.ts @@ -101,6 +101,53 @@ function requireRelease(steps: Step[]): void { const loadYaml = (relative: string) => parse(readFileSync(join(root, relative), "utf8")) as unknown; +describe("standalone package ownership", () => { + // Recovery: https://github.com/Comfy-Org/comfy-multi-player/pull/217 + it("routes README development to the standalone repository with npm", () => { + const readme = readFileSync(join(root, "README.md"), "utf8"); + const develop = readme.split("## Develop\n")[1]?.split("\n## ")[0]; + expect(develop).toBeDefined(); + expect(develop).toContain("https://github.com/Comfy-Org/comfy-multi-player"); + expect(develop).toContain("npm ci"); + expect(develop).not.toMatch(/pnpm|packages\/comfy-multi-player/); + }); + + it("installs a specific published version and saves an exact dependency", () => { + const readme = readFileSync(join(root, "README.md"), "utf8"); + const install = readme.split("## Install\n")[1]?.split("\n## ")[0]; + expect(install).toBeDefined(); + expect(install).toContain("npm install --save-exact @comfyorg/comfy-multi-player@0.2.1"); + }); + + it("keeps the roadmap migration deferred and standalone development writable", () => { + const roadmap = readFileSync(join(root, "docs/ROADMAP.md"), "utf8"); + const plan = roadmap.split("## Repository plan\n")[1]; + expect(plan).toBeDefined(); + expect(plan).toContain("canonical writable source"); + expect(plan).toContain("deferred"); + expect(plan).toContain("https://github.com/Comfy-Org/comfy-multi-player"); + expect(plan).not.toMatch(/Completed by|read-only record|ownership moved/); + }); + + it("does not turn historical schema compatibility into a completed migration", () => { + const schema = readFileSync(join(root, "docs/multiplayer-schema.md"), "utf8"); + expect(schema).not.toContain("canonical workspace source"); + expect(schema).toContain("frontend source migration is deferred"); + }); + + it("accepts standalone issues and provides a private security contact", () => { + const config = loadYaml(".github/ISSUE_TEMPLATE/config.yml") as { + blank_issues_enabled: boolean; + contact_links: Array<{ name: string; url: string }>; + }; + expect(config.blank_issues_enabled).toBe(true); + expect(config.contact_links).toContainEqual(expect.objectContaining({ + name: "Security report", url: "mailto:support@comfy.org", + })); + expect(config.contact_links.some(({ url }) => url.includes("ComfyUI_frontend"))).toBe(false); + }); +}); + describe("parsed CI and release contracts", () => { it.each([["ci", "ci"], ["release", "publish"]])( "%s runs every required gate and propagates failure", diff --git a/test/clear-empty-removed-nodes.test.ts b/test/clear-empty-removed-nodes.test.ts index d7a0fb32..9afa33f3 100644 --- a/test/clear-empty-removed-nodes.test.ts +++ b/test/clear-empty-removed-nodes.test.ts @@ -7,7 +7,7 @@ import { loadCatalog } from "./helpers.js"; const catalog = loadCatalog(); function threeNodeWorkflow(withGroups: boolean): WorkflowJSON { - const workflow: WorkflowJSON = { + return { nodes: [ { id: 1, type: "LoadImage", inputs: [], @@ -27,22 +27,19 @@ function threeNodeWorkflow(withGroups: boolean): WorkflowJSON { last_node_id: 3, last_link_id: 11, extra: {}, + ...(withGroups ? { + groups: [ + { + id: 1, + title: "nodes 1-2", + bounding: [0, 0, 640, 320], + color: "#3f789e", + font_size: 24, + flags: {}, + }, + ], + } : {}), }; - if (withGroups) { - workflow.groups = [ - { - id: 1, - title: "nodes 1-2", - bounding: [0, 0, 640, 320], - color: "#3f789e", - font_size: 24, - flags: {}, - }, - ]; - } else { - delete workflow.groups; - } - return workflow; } function clearEmpty(baseVersion: number): ClearOp { diff --git a/test/clock.test.ts b/test/clock.test.ts index f4d45ed1..f4d3596d 100644 --- a/test/clock.test.ts +++ b/test/clock.test.ts @@ -1,11 +1,26 @@ import { describe, expect, it } from "vitest"; import { applyOps, DocDerivedLamportClockStore, freezeLamportEnvelope, MAX_LAMPORT_COUNTER, - mint, observedDocCounter, observeLamport, persistLamportTick, tickLamport, type LamportClockStore } from "../src/index.js"; + mint, observedDocCounter, observeLamport, persistLamportTick, tickLamport, validateLamportCounter, type LamportClockStore } from "../src/index.js"; import { loadCatalog } from "./helpers.js"; const catalog = loadCatalog(); describe("creator-owned Lamport counter", () => { + it("validates numeric boundaries without coercing unknown inputs", () => { + for (const allowZero of [false, true]) { + const message = `Lamport counter must be a ${allowZero ? "non-negative" : "positive"} safe integer`; + for (const value of ["1", 1n, true, null, undefined, Symbol("counter"), {}, new Number(1), -1, 0.5, NaN, Infinity, Number.MAX_SAFE_INTEGER + 1]) { + expect(() => validateLamportCounter(value, allowZero)).toThrow(RangeError); + expect(() => validateLamportCounter(value, allowZero)).toThrow(new RangeError(message)); + } + expect(validateLamportCounter(1, allowZero)).toBe(1); + expect(validateLamportCounter(Number.MAX_SAFE_INTEGER, allowZero)).toBe(Number.MAX_SAFE_INTEGER); + } + expect(() => validateLamportCounter(0)).toThrow(new RangeError("Lamport counter must be a positive safe integer")); + expect(validateLamportCounter(0, true)).toBe(0); + expect(validateLamportCounter(-0, true)).toBe(-0); + }); + it("observes, ticks, and refuses overflow", () => { expect(observeLamport(2, 9, 4)).toBe(9); expect(tickLamport(2, 9, 4)).toBe(10); diff --git a/test/disconnect-lww.test.ts b/test/disconnect-lww.test.ts index 85edd049..ba837aa9 100644 --- a/test/disconnect-lww.test.ts +++ b/test/disconnect-lww.test.ts @@ -99,7 +99,7 @@ function connect( function projected(ops: Op[]): WorkflowJSON { const doc = mint(wiredWorkflow(), catalog, "sha"); const result = applyOps(doc, ops, catalog); - expect(result.outcomes.every((outcome) => outcome.outcome !== "rejected")).toBe(true); + expect(result.outcomes.filter((outcome) => outcome.outcome === "rejected")).toEqual([]); return canonicalize(project(doc, catalog)); } @@ -146,7 +146,7 @@ describe("disconnect", () => { it("converges when the named link and claimed input are different registers", () => { const run = (ops: Op[]) => { const doc = mint(withSecondTargetSlot(), catalog, "sha"); - expect(applyOps(doc, ops, catalog).outcomes.every((outcome) => outcome.outcome !== "rejected")).toBe(true); + expect(applyOps(doc, ops, catalog).outcomes.filter((outcome) => outcome.outcome === "rejected")).toEqual([]); return canonicalize(project(doc, catalog)); }; const reconnect = { ...connect("c1", AGENT, 5, 9001), to_slot: 1 }; diff --git a/test/event-schema-drift.test.ts b/test/event-schema-drift.test.ts index a18f77ca..e844fe4b 100644 --- a/test/event-schema-drift.test.ts +++ b/test/event-schema-drift.test.ts @@ -6,14 +6,12 @@ * cloud SHA, golden samples, schema export, and TS union together. */ import { readFileSync } from "node:fs"; -import { join } from "node:path"; import { describe, expect, it } from "vitest"; import { AGENT_EVENT_JSON_SCHEMA, type AgentEvent } from "../src/event-schema.js"; type Schema = { type?: string | string[]; enum?: string[]; required?: string[]; properties?: Record; items?: Schema }; type Contract = { cloud_sha: string; events: Record }> }; -const root = process.cwd(); -const fixture = JSON.parse(readFileSync(join(root, "fixtures/go-agent-events/contract.json"), "utf8")) as Contract; +const fixture = JSON.parse(readFileSync(new URL("../fixtures/go-agent-events/contract.json", import.meta.url), "utf8")) as Contract; function shape(schema: Schema): string { if (schema.enum) return `enum:${schema.enum.join("|")}`; @@ -51,7 +49,7 @@ describe("cloud Go ⇄ cmp TypeScript event schema", () => { }); it("keeps every Go golden event inside the TypeScript discriminated union", () => { - const lines = readFileSync(join(root, "fixtures/go-agent-events/golden.jsonl"), "utf8").trim().split("\n"); + const lines = readFileSync(new URL("../fixtures/go-agent-events/golden.jsonl", import.meta.url), "utf8").trim().split("\n"); const events = lines.map((line) => JSON.parse(line) as AgentEvent); expect(events.map((event) => event.type).sort()).toEqual(Object.keys(fixture.events).sort()); }); diff --git a/test/gen-coderabbit-config.test.ts b/test/gen-coderabbit-config.test.ts index ae844ab9..f424e839 100644 --- a/test/gen-coderabbit-config.test.ts +++ b/test/gen-coderabbit-config.test.ts @@ -540,8 +540,6 @@ describe("gen-coderabbit-config", () => { const real = spawnSync("node", [script], { encoding: "utf8" }); expect(real.stderr).toBe(""); expect(real.status).toBe(0); - expect(real.stdout).toBe( - "coderabbit-config check PASSED (5 instruction block(s) from 4 profile(s) match .coderabbit.yaml)\n", - ); + expect(real.stdout).toMatch(/^coderabbit-config check PASSED /); }); }); diff --git a/test/ka4-rejection-byte-identity.test.ts b/test/ka4-rejection-byte-identity.test.ts index aee050a3..f65968a8 100644 --- a/test/ka4-rejection-byte-identity.test.ts +++ b/test/ka4-rejection-byte-identity.test.ts @@ -685,7 +685,7 @@ describe("KA-4: the rejection codes that need their own fixture", () => { const before = bytes(doc); const beforeProjection = project(doc, cat ?? catalog); - const res = applyOps(doc, [op], cat as WidgetCatalog); + const res = applyOps(doc, [op], cat); expect(res.outcomes.find((outcome) => outcome.outcome === "rejected")?.reason.code).toBe(code); expect(bytes(doc).equals(before), "encodeStateAsUpdate must be byte-identical").toBe(true); @@ -743,6 +743,7 @@ describe("KA-4 sweep completeness", () => { it("names every code the applier actually throws, so a new one cannot be added silently", () => { const src = readFileSync(new URL("../src/applier.ts", import.meta.url), "utf8"); const thrown = new Set(Array.from(src.matchAll(/new OpRejectedError\(\s*"([a-z_]+)"/g), (m) => m[1] as string)); + expect(thrown.size, "the applier rejection-code census must not be empty").toBeGreaterThan(0); const known = new Set([ ...ALL_REJECTION_CODES, ...OP_ID_REJECTION_CODES, diff --git a/test/lww.test.ts b/test/lww.test.ts index 3931c8fb..b5456f07 100644 --- a/test/lww.test.ts +++ b/test/lww.test.ts @@ -25,6 +25,7 @@ const vectors = loadLwwVectors(); describe("compareStampKeys (freeze doc §8.1)", () => { it("picks the recorded winner for all six vectors", () => { + expect(vectors.vectors).toHaveLength(6); for (const v of vectors.vectors) { const [a, b] = v.ops as [SetWidgetOp, SetWidgetOp]; const cmp = compareStampKeys(stampKey(a), stampKey(b)); diff --git a/test/op-bounds.test.ts b/test/op-bounds.test.ts index bc9edf44..32eac2fb 100644 --- a/test/op-bounds.test.ts +++ b/test/op-bounds.test.ts @@ -14,12 +14,12 @@ import { MAX_COLLECTION_ENTRIES, MAX_OP_COST, MAX_OPS_PER_BATCH, + MAX_PAYLOAD_DEPTH, mint, opBoundsRefusal, project, - type Op, - type WorkflowJSON, } from "../src/index.js"; +import type { Op, WorkflowJSON } from "../src/index.js"; import { loadCatalog } from "./helpers.js"; const catalog = loadCatalog(); @@ -28,7 +28,7 @@ function bytes(doc: Y.Doc): Buffer { return Buffer.from(Y.encodeStateAsUpdate(doc)); } -/** `n` nested objects; the outermost is depth 1, the string leaf is depth n+1. */ +/** `n` nested objects; traversal starts at outermost depth 0, so the string leaf is depth `n`. */ function wrap(n: number): unknown { let value: unknown = "leaf"; for (let i = 0; i < n; i++) value = { child: value }; @@ -60,6 +60,14 @@ describe("opBoundsRefusal boundaries", () => { expect(opBoundsRefusal(new Uint8Array(MAX_OP_COST + 1))).toMatch(/cost budget/); }); + it(`accepts a payload whose leaf is exactly at depth ${MAX_PAYLOAD_DEPTH}`, () => { + expect(opBoundsRefusal(wrap(MAX_PAYLOAD_DEPTH))).toBeNull(); + }); + + it(`rejects a payload whose leaf is at depth ${MAX_PAYLOAD_DEPTH + 1}`, () => { + expect(opBoundsRefusal(wrap(MAX_PAYLOAD_DEPTH + 1))).toMatch(/nests deeper/); + }); + it("skips reference cycles (the value gates own that refusal), terminating", () => { const cycle: Record = {}; cycle["self"] = cycle; diff --git a/test/pbt-mint-project-roundtrip.test.ts b/test/pbt-mint-project-roundtrip.test.ts index 74ea3456..4a184ba0 100644 --- a/test/pbt-mint-project-roundtrip.test.ts +++ b/test/pbt-mint-project-roundtrip.test.ts @@ -122,6 +122,7 @@ function cloneWorkflow(workflow: WorkflowJSON): WorkflowJSON { describe("property-based mint → apply → project round trips", () => { it("round-trips generated metadata, slots, widgets, and subgraphs without mutating input", () => { + const witnessed = { definitions: 0, metadata: 0, slots: 0, widgets: 0 }; fc.assert( fc.property(workflowArb, (workflow) => { const before = cloneWorkflow(workflow); @@ -130,9 +131,19 @@ describe("property-based mint → apply → project round trips", () => { expect(canonicalize(projected)).toEqual(canonicalize(before)); expect(workflow).toEqual(before); expect(project(mint(projected, catalog), catalog)).toEqual(projected); + if (workflow.definitions !== undefined) witnessed.definitions++; + if (Object.keys(workflow).some((key) => !["nodes", "links", "definitions"].includes(key))) witnessed.metadata++; + if (workflow.nodes.some((node) => + (Array.isArray(node.inputs) && node.inputs.length > 0) || + (Array.isArray(node.outputs) && node.outputs.length > 0))) witnessed.slots++; + if (workflow.nodes.some((node) => Array.isArray(node.widgets_values) && node.widgets_values.length > 0)) witnessed.widgets++; }), FC_OPTIONS, ); + expect(witnessed.definitions).toBeGreaterThan(0); + expect(witnessed.metadata).toBeGreaterThan(0); + expect(witnessed.slots).toBeGreaterThan(0); + expect(witnessed.widgets).toBe(FC_OPTIONS.numRuns); }); it("preserves minted op identities and is deterministic under apply and retry", { timeout: 15_000 }, () => { diff --git a/test/permutation/connect-delete-equivalence.permutation.test.ts b/test/permutation/connect-delete-equivalence.permutation.test.ts index 30e7c6d8..c158cb96 100644 --- a/test/permutation/connect-delete-equivalence.permutation.test.ts +++ b/test/permutation/connect-delete-equivalence.permutation.test.ts @@ -27,7 +27,9 @@ import { import { canonicalize, loadCatalog } from "../helpers.js"; const catalog = loadCatalog(); -const ACTORS = ["agent:pbt:0", "agent:pbt:1", "human:pbt:0", "human:pbt:1"] as const; +// Three representatives retain same-kind and cross-kind actor ordering while +// leaving room for both incumbent states under the 20,000-execution ceiling. +const ACTORS = ["agent:pbt:0", "agent:pbt:1", "human:pbt:0"] as const; const VERSION_PAIRS = [[0, 0], [0, 1], [1, 0], [1, 1], [0, 9], [9, 0], [4, 4], [4, 5]] as const; const ENDPOINT_PRESENCE = [ { source: true, destination: true }, @@ -41,6 +43,8 @@ const SLOT_PAIRS = [ { from: 5, to: 0 }, { from: 5, to: 5 }, ] as const; +// 2 axes × 4 presence classes × 4 slot classes × 2 incumbent states × +// 3×2 ordered distinct actors × 8 version classes × 2 batch modes × 2 arrivals. const EXPECTED_EXECUTIONS = 12_288; type DeleteAxis = "source" | "destination"; @@ -164,14 +168,14 @@ describe("bounded exhaustive connect x delete equivalence", () => { for (const axis of ["source", "destination"] as const) { for (const presence of ENDPOINT_PRESENCE) { for (const slots of SLOT_PAIRS) { - const incumbent = true; - for (const actorA of ACTORS) { - for (const actorB of ACTORS) { - if (actorA === actorB) continue; - for (const versions of VERSION_PAIRS) { - const pair = operations(serial, [actorA, actorB], versions, slots, axis); - serial += 2; - for (const mode of ["together", "split"] as const) { + for (const incumbent of [false, true] as const) { + for (const actorA of ACTORS) { + for (const actorB of ACTORS) { + if (actorA === actorB) continue; + for (const versions of VERSION_PAIRS) { + const pair = operations(serial, [actorA, actorB], versions, slots, axis); + serial += 2; + for (const mode of ["together", "split"] as const) { const forward = run(base(presence, incumbent), pair, mode); const reverse = run(base(presence, incumbent), [pair[1], pair[0]], mode); executions += 2; @@ -197,6 +201,7 @@ describe("bounded exhaustive connect x delete equivalence", () => { else if (abortBoundary) abortBoundaryPairs++; else if (divergent) unexpected.push(`${repro} outcomes=${JSON.stringify([forward.outcomes, reverse.outcomes])}`); else equivalentPairs++; + } } } } @@ -208,10 +213,17 @@ describe("bounded exhaustive connect x delete equivalence", () => { expect(executions).toBe(EXPECTED_EXECUTIONS); expect(unexpected, "unexpected divergence tuples").toEqual([]); expect(a6DivergentPairs + abortBoundaryPairs + equivalentPairs).toBe(EXPECTED_EXECUTIONS / 2); + // Per ordered-actor/version pair: five destination/together slot-race + // classes plus one source/together class diverge for either incumbent + // state. Source/split additionally diverges only with an incumbent link: + // with no incumbent, deleting the source leaves the same empty input. + // Thus (6 empty + 7 occupied) × 6 actor pairs × 8 version pairs = 624. + // The two source/together bad-destination-slot classes abort in both + // incumbent states: 2 × 2 × 6 × 8 = 192. All other pairs are equivalent. expect({ a6DivergentPairs, abortBoundaryPairs, equivalentPairs }).toEqual({ - a6DivergentPairs: 672, + a6DivergentPairs: 624, abortBoundaryPairs: 192, - equivalentPairs: 5_280, + equivalentPairs: 5_328, }); }, 120_000); }); diff --git a/test/project.test.ts b/test/project.test.ts index 2514bb96..abf3da8c 100644 --- a/test/project.test.ts +++ b/test/project.test.ts @@ -23,10 +23,11 @@ * other than the one the doc pins still throws loudly (KA-12 / schema §3 * pin 4); silently dropping nodes there would hide contract drift. */ -import { describe, expect, it } from "vitest"; +import { beforeEach, describe, expect, it } from "vitest"; import * as Y from "yjs"; import { appliedMap, createNodeMap, initDoc } from "../src/doc.js"; -import { applyOps, mint, nodesMap, project, type Op, type WorkflowJSON } from "../src/index.js"; +import { applyOps, mint, nodesMap, project } from "../src/index.js"; +import type { Op, WorkflowJSON } from "../src/index.js"; import { loadCatalog } from "./helpers.js"; const catalog = loadCatalog(); @@ -37,6 +38,7 @@ function bytes(doc: Y.Doc): Buffer { } let opSeq = 0; +beforeEach(() => { opSeq = 0; }); /** A well-formed stamped envelope; the tests vary only the payload under test. */ function op(fields: Record): Op { opSeq += 1; diff --git a/test/promoted-host-writes.test.ts b/test/promoted-host-writes.test.ts index 9c421081..5b7a4435 100644 --- a/test/promoted-host-writes.test.ts +++ b/test/promoted-host-writes.test.ts @@ -18,7 +18,7 @@ * trimmed to the nodes the cases touch. */ import * as Y from "yjs"; -import { describe, expect, it } from "vitest"; +import { beforeEach, describe, expect, it } from "vitest"; import { OPAQUE_WIDGETS_KEY, _getMutationCount, _resetMutationCount, appliedMap, nodesMap, stampsMap } from "../src/doc.js"; import { applyOps, @@ -167,10 +167,14 @@ function nested(): WorkflowJSON { // Op builders // --------------------------------------------------------------------------- -let seq = 0; -function opId(prefix = "p"): string { - return (prefix + String(seq++).padStart(4, "0")).padEnd(32, "0"); +function createOperationIdFactory() { + let seq = 0; + return (prefix = "p"): string => (prefix + String(seq++).padStart(4, "0")).padEnd(32, "0"); } + +let opId: ReturnType; +beforeEach(() => { opId = createOperationIdFactory(); }); + function env(actor = "cli", base = 0) { return { op_id: opId(), actor, base_version: base, stamp: [base, actor] as [number, string] }; } diff --git a/test/purity.test.ts b/test/purity.test.ts index dbbc7951..291ea8c9 100644 --- a/test/purity.test.ts +++ b/test/purity.test.ts @@ -15,24 +15,24 @@ describe("purity", () => { encoding: "utf8", maxBuffer: 64 * 1024 * 1024, }); + expect(run.error, `npm ls failed: ${run.stderr}`).toBeUndefined(); + expect(run.status, `npm ls exited ${String(run.status)}: ${run.stderr}`).toBe(0); const tree = JSON.parse(run.stdout) as { + name?: string; dependencies?: Record< string, { version?: string; resolved?: string; missing?: boolean; invalid?: boolean; extraneous?: boolean } >; }; - // A production root must be installed and valid, not just non-extraneous: - // a missing/invalid yjs node must fail this assertion, not pass it. - const resolvedRoots = Object.entries(tree.dependencies ?? {}) - .filter( - ([, dep]) => - (dep.version !== undefined || dep.resolved !== undefined) && - !dep.missing && - !dep.invalid && - !dep.extraneous, - ) - .map(([name]) => name) - .sort(); + expect(tree.name).toBe("@comfyorg/comfy-multi-player"); + const roots = Object.entries(tree.dependencies ?? {}); + for (const [name, dependency] of roots) { + expect(dependency.version, `${name} must have npm installation metadata`).toBeTruthy(); + expect(dependency.missing, `${name} must be installed`).not.toBe(true); + expect(dependency.invalid, `${name} must satisfy its declared range`).toBeFalsy(); + expect(dependency.extraneous, `${name} must not be extraneous`).not.toBe(true); + } + const resolvedRoots = roots.map(([name]) => name).sort(); expect(resolvedRoots).toEqual(["yjs"]); const packageJson = JSON.parse(readFileSync(join(root, "package.json"), "utf8")) as { @@ -77,7 +77,6 @@ describe("purity", () => { const run = spawnSync(process.execPath, ["--input-type=module", "-e", probe], { encoding: "utf8", }); - expect(run.stderr).toBe(""); - expect(run.status).toBe(0); + expect(run.status, run.stderr).toBe(0); }); }); diff --git a/test/register-families.property.test.ts b/test/register-families.property.test.ts index 9b788308..819011f3 100644 --- a/test/register-families.property.test.ts +++ b/test/register-families.property.test.ts @@ -207,7 +207,9 @@ function exercise( if (scenario.retry !== "none") { const before = Buffer.from(Y.encodeStateAsUpdate(first)); const retried = scenario.retry === "winner" ? winner : loser; - expect(applyOps(first, [retried], catalog).outcomes[0]?.outcome).not.toBe("rejected"); + expect(applyOps(first, [retried], catalog).outcomes).toEqual([ + { op_id: retried.op_id, outcome: "no-op" }, + ]); expect(Buffer.from(Y.encodeStateAsUpdate(first))).toEqual(before); } } diff --git a/test/stamp-target-identity.test.ts b/test/stamp-target-identity.test.ts index 4c71c88f..ac3c79fe 100644 --- a/test/stamp-target-identity.test.ts +++ b/test/stamp-target-identity.test.ts @@ -23,6 +23,7 @@ import { project, writeTarget, type ConnectOp, + type DeleteNodeOp, type Op, type SetWidgetOp, type WorkflowJSON, @@ -152,7 +153,7 @@ describe("stamp targets normalize node ids to strings", () => { expect(writeTarget(connectTo("b1", AGENT, 5, 1, 8, 7))).toEqual( writeTarget(connectTo("b2", HUMAN, 9, 2, 8, "7")), ); - const del = { + const del: DeleteNodeOp = { op: "delete_node", op_id: opId("c1"), actor: AGENT, @@ -160,8 +161,8 @@ describe("stamp targets normalize node ids to strings", () => { stamp: [5, AGENT], node_id: 7, removed_links: [], - } as unknown as Op; - const delStr = { ...del, node_id: "7" } as Op; + }; + const delStr: DeleteNodeOp = { ...del, node_id: "7" }; expect(writeTarget(del)).toEqual(writeTarget(delStr)); }); diff --git a/test/stateless.test.ts b/test/stateless.test.ts index eabcc5da..29e42fb1 100644 --- a/test/stateless.test.ts +++ b/test/stateless.test.ts @@ -1,5 +1,5 @@ import { spawnSync } from "node:child_process"; -import { mkdirSync, mkdtempSync, rmSync, symlinkSync, writeFileSync } from "node:fs"; +import { existsSync, mkdirSync, mkdtempSync, rmSync, symlinkSync, writeFileSync } from "node:fs"; import { tmpdir } from "node:os"; import { dirname, join } from "node:path"; import { fileURLToPath } from "node:url"; @@ -26,27 +26,44 @@ async function freshApi() { return import("../src/index.js"); } +const withStatelessFixture = (source: string, check: (root: string) => void) => { + const root = mkdtempSync(join(tmpdir(), "stateless-")); + try { + mkdirSync(join(root, ".agents", "checks"), { recursive: true }); + mkdirSync(join(root, "src")); + mkdirSync(join(root, "node_modules")); + symlinkSync( + join(repoRoot, ".agents", "checks", "eslint.strict.config.js"), + join(root, ".agents", "checks", "eslint.strict.config.js"), + ); + for (const dependency of [".bin", "@typescript-eslint", "eslint", "eslint-plugin-sonarjs"]) { + symlinkSync(join(repoRoot, "node_modules", dependency), join(root, "node_modules", dependency), "dir"); + } + writeFileSync(join(root, "package.json"), JSON.stringify({ name: "stateless-fixture" })); + writeFileSync(join(root, "src", "leak.ts"), source); + check(root); + } finally { + rmSync(root, { recursive: true, force: true }); + } +}; + describe("KA-13: cmp is stateless modulo caller-owned documents", () => { + const mutableCollection = "no module-level mutable collection"; + const mutableBinding = "no module-level let/var"; it.each([ - ["module-level mutable state", "const cache = new Map();\nvoid cache;\n", "no module-level mutable collection"], - ["a module-level let", "let current = 0;\ncurrent += 1;\n", "no module-level let/var"], + ["module-level mutable state", "const cache = new Map();\nvoid cache;\n", mutableCollection], + ["a module-level let", "let current = 0;\ncurrent += 1;\n", mutableBinding], + ["an exported let", "export let current = 0;\n", mutableBinding], + ["an exported var", "export var current = 0;\n", mutableBinding], + ["an exported Map", "export const cache = new Map();\n", mutableCollection], + ["an exported Set", "export const cache = new Set();\n", mutableCollection], + ["an exported WeakMap", "export const cache = new WeakMap();\n", mutableCollection], + ["an exported WeakSet", "export const cache = new WeakSet();\n", mutableCollection], + ["a collection beside the exemption", "export const documentTransactionTails = new WeakMap(), cache = new Map();\n", mutableCollection], + ["a mutable binding named like the exemption", "export let documentTransactionTails = 0;\n", mutableBinding], ["a UI import", 'import { ref } from "vue";\nvoid ref;\n', "cmp is DOM/framework-free and stateless"], ])("makes the production gate fail on planted %s", (_name, source, expected) => { - const root = mkdtempSync(join(tmpdir(), "stateless-")); - try { - mkdirSync(join(root, ".agents", "checks"), { recursive: true }); - mkdirSync(join(root, "src")); - mkdirSync(join(root, "node_modules")); - symlinkSync( - join(repoRoot, ".agents", "checks", "eslint.strict.config.js"), - join(root, ".agents", "checks", "eslint.strict.config.js"), - ); - for (const dependency of [".bin", "@typescript-eslint", "eslint", "eslint-plugin-sonarjs"]) { - symlinkSync(join(repoRoot, "node_modules", dependency), join(root, "node_modules", dependency), "dir"); - } - writeFileSync(join(root, "package.json"), JSON.stringify({ name: "stateless-fixture" })); - writeFileSync(join(root, "src", "leak.ts"), source); - + withStatelessFixture(source, root => { const run = spawnSync(process.execPath, [join(repoRoot, "scripts", "check-stateless.mjs")], { encoding: "utf8", env: { ...process.env, STATELESS_ROOT: root }, @@ -54,9 +71,40 @@ describe("KA-13: cmp is stateless modulo caller-owned documents", () => { expect(run.status).toBe(1); expect(run.stderr).toContain(expected); expect(run.stderr).toContain("src/leak.ts"); - } finally { - rmSync(root, { recursive: true, force: true }); - } + }); + }); + + it.each([ + ["immutable exports", 'export const answer = 42;\nconst label = "cmp";\nexport { label };\n'], + ["function-local state", `export function createState() { + let current = 0; + var previous = 1; + const map = new Map(); + const set = new Set(); + const weakMap = new WeakMap(); + const weakSet = new WeakSet(); + return { current, previous, map, set, weakMap, weakSet }; + }\n`], + ["the admission queue exemption", "const documentTransactionTails = new WeakMap();\n"], + ["the exported admission queue exemption", "export const documentTransactionTails = new WeakMap();\n"], + ])("allows %s through the production static-analysis seam", (_name, source) => { + withStatelessFixture(source, root => { + // Run the gate's real ESLint phase without requiring a fake runtime probe. + const run = spawnSync(process.execPath, [ + join(root, "node_modules", "eslint", "bin", "eslint.js"), + "--no-config-lookup", "--config", ".agents/checks/eslint.strict.config.js", + "--no-warn-ignored", "--format", "json", "src/leak.ts", + ], { + cwd: root, + encoding: "utf8", + env: { ...process.env, CMP_STATELESS_ONLY: "1" }, + }); + expect(run.status).toBe(0); + expect(run.stderr).toBe(""); + expect(JSON.parse(run.stdout)).toEqual([ + expect.objectContaining({ filePath: join(root, "src", "leak.ts"), messages: [], errorCount: 0, warningCount: 0 }), + ]); + }); }); it("does not share document state between calls in one module instance", async () => { @@ -82,6 +130,7 @@ describe("KA-13: cmp is stateless modulo caller-owned documents", () => { it("keeps fresh Node processes behaviorally equivalent", () => { const entry = fileURLToPath(new URL("../dist/index.js", import.meta.url)); + expect(existsSync(entry), "dist/index.js missing — run `npm run build` before the stateless process probe").toBe(true); const script = `import { mint, project } from ${JSON.stringify(entry)}; import catalog from ${JSON.stringify(fileURLToPath(new URL("../fixtures/catalog.json", import.meta.url)))} with { type: "json" }; console.log(JSON.stringify(project(mint({nodes: [], links: []}, catalog), catalog)));`; const run = () => spawnSync(process.execPath, ["--input-type=module", "-e", script], { encoding: "utf8" }); const first = run(); diff --git a/test/upstream-pins.test.ts b/test/upstream-pins.test.ts index ab9f4672..2c43647e 100644 --- a/test/upstream-pins.test.ts +++ b/test/upstream-pins.test.ts @@ -130,6 +130,186 @@ describe("FC-10 — upstream citations are pinned by SHA, not by branch", () => } }); + it.each([ + { + name: "hidden private repository commit 404", + commitStatus: 404, + metadataStatus: 404, + expectedStatus: 2, + expectedMessage: "could not establish public repository visibility for example/upstream — HTTP 404", + endpoints: ["api rate_limit", "api repos/example/upstream/commits/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "api repos/example/upstream"], + }, + { + name: "public repository commit 404", + commitStatus: 404, + metadataStatus: 200, + metadataPrivate: false, + expectedStatus: 1, + expectedMessage: "commit aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa no longer resolves in example/upstream", + endpoints: ["api rate_limit", "api repos/example/upstream/commits/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "api repos/example/upstream"], + }, + { + name: "public repository path 404", + commitStatus: 200, + contentsStatus: 404, + metadataStatus: 200, + metadataPrivate: false, + expectedStatus: 1, + expectedMessage: "README.md is absent at aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa in example/upstream", + endpoints: ["api rate_limit", "api repos/example/upstream/commits/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "api repos/example/upstream/contents/README.md?ref=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "api repos/example/upstream"], + }, + { + name: "private repository commit 404 despite readable metadata", + commitStatus: 404, + metadataStatus: 200, + metadataPrivate: true, + expectedStatus: 2, + expectedMessage: "repository metadata for example/upstream identifies a private repository, but metadata visibility does not prove Contents access", + endpoints: ["api rate_limit", "api repos/example/upstream/commits/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "api repos/example/upstream"], + }, + { + name: "private repository path 404 despite readable metadata", + commitStatus: 200, + contentsStatus: 404, + metadataStatus: 200, + metadataPrivate: true, + expectedStatus: 2, + expectedMessage: "repository metadata for example/upstream identifies a private repository, but metadata visibility does not prove Contents access", + endpoints: ["api rate_limit", "api repos/example/upstream/commits/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "api repos/example/upstream/contents/README.md?ref=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "api repos/example/upstream"], + }, + { + name: "commit 422 remains object-scoped", + commitStatus: 422, + metadataStatus: 200, + expectedStatus: 1, + expectedMessage: "commit aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa no longer resolves in example/upstream", + endpoints: ["api rate_limit", "api repos/example/upstream/commits/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"], + }, + { + name: "commit 451 remains object-scoped", + commitStatus: 451, + metadataStatus: 200, + expectedStatus: 1, + expectedMessage: "commit aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa no longer resolves in example/upstream", + endpoints: ["api rate_limit", "api repos/example/upstream/commits/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"], + }, + { + name: "repository metadata rejects authentication", + commitStatus: 404, + metadataStatus: 403, + expectedStatus: 2, + expectedMessage: "could not establish public repository visibility for example/upstream — HTTP 403", + endpoints: ["api rate_limit", "api repos/example/upstream/commits/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "api repos/example/upstream"], + }, + { + name: "repository metadata is unavailable", + commitStatus: 404, + metadataStatus: 500, + expectedStatus: 2, + expectedMessage: "could not establish public repository visibility for example/upstream — HTTP 500", + endpoints: ["api rate_limit", "api repos/example/upstream/commits/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "api repos/example/upstream"], + }, + { + name: "repository metadata response is malformed", + commitStatus: 404, + metadataStatus: 200, + malformedMetadata: true, + expectedStatus: 2, + expectedMessage: "repository metadata for example/upstream was malformed, so repository visibility was not established", + endpoints: ["api rate_limit", "api repos/example/upstream/commits/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "api repos/example/upstream"], + }, + { + name: "repository metadata omits visibility", + commitStatus: 404, + metadataStatus: 200, + omitMetadataPrivate: true, + expectedStatus: 2, + expectedMessage: "repository metadata for example/upstream was malformed, so repository visibility was not established", + endpoints: ["api rate_limit", "api repos/example/upstream/commits/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "api repos/example/upstream"], + }, + { + name: "repository metadata has nonboolean visibility", + commitStatus: 404, + metadataStatus: 200, + metadataPrivate: "false", + expectedStatus: 2, + expectedMessage: "repository metadata for example/upstream was malformed, so repository visibility was not established", + endpoints: ["api rate_limit", "api repos/example/upstream/commits/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "api repos/example/upstream"], + }, + ])("classifies $name without mistaking repository access for object absence", (scenario) => { + // Source: https://github.com/Comfy-Org/ComfyUI_frontend/pull/16644#discussion_r3940075206 + const fixture = mkdtempSync(join(tmpdir(), "pins-private-remote-")); + try { + mkdirSync(join(fixture, "docs")); + mkdirSync(join(fixture, "bin")); + const commit = "a".repeat(40); + const citedBy = ["citation-1.md", "citation-2.md", "citation-3.md", "citation-4.md"]; + writeFileSync( + join(fixture, "docs", "upstream-pins.json"), + JSON.stringify({ + pins: { + upstream: { + commit, + repo: "https://github.com/example/upstream", + path: "README.md", + established_by: "resolved from an immutable upstream revision with audit evidence", + sections_cited: ["1"], + cited_by: citedBy, + }, + }, + }), + ); + for (const site of citedBy) writeFileSync(join(fixture, site), `Pinned at ${commit}.\n`); + for (let index = 0; index < 20; index += 1) writeFileSync(join(fixture, `tracked-${index}.md`), `fixture ${index}\n`); + + const ghLog = join(fixture, "gh.log"); + const fakeGh = join(fixture, "bin", "gh"); + writeFileSync( + fakeGh, + `#!/bin/sh\nprintf '%s\\n' "$*" >> "$GH_TEST_LOG"\n` + + `if [ "$1" = "--version" ]; then echo 'gh version test'; exit 0; fi\n` + + `status=200\n` + + `case "$2" in\n` + + ` rate_limit) status=200;;\n` + + ` repos/example/upstream/commits/*) status="$COMMIT_STATUS";;\n` + + ` repos/example/upstream/contents/*) status="$CONTENTS_STATUS";;\n` + + ` repos/example/upstream) status="$METADATA_STATUS";;\n` + + ` *) echo "unexpected endpoint: $2" >&2; exit 9;;\n` + + `esac\n` + + `if [ "$status" != 200 ]; then echo "gh: fixture failure (HTTP $status)" >&2; exit 1; fi\n` + + `case "$2" in\n` + + ` repos/example/upstream/contents/*) printf '%s\\n' '{"content":"IyAxIFRpdGxlCg==","encoding":"base64"}';;\n` + + ` repos/example/upstream) if [ "$MALFORMED_METADATA" = true ]; then echo '{}'; elif [ "$OMIT_METADATA_PRIVATE" = true ]; then echo '{"full_name":"example/upstream"}'; else printf '{"full_name":"example/upstream","private":%s}\\n' "$METADATA_PRIVATE"; fi;;\n` + + ` *) echo '{}';;\n` + + `esac\n`, + ); + chmodSync(fakeGh, 0o755); + expect(spawnSync("git", ["init", "--quiet"], { cwd: fixture }).status).toBe(0); + expect(spawnSync("git", ["add", "."], { cwd: fixture }).status).toBe(0); + + const run = spawnSync(process.execPath, [join(root, "scripts", "check-pins.mjs"), "--verify-remote"], { + encoding: "utf8", + env: { + ...process.env, + PINS_ROOT: fixture, + PATH: `${join(fixture, "bin")}:${process.env.PATH}`, + GH_TEST_LOG: ghLog, + COMMIT_STATUS: String(scenario.commitStatus), + CONTENTS_STATUS: String(scenario.contentsStatus ?? 200), + METADATA_STATUS: String(scenario.metadataStatus), + MALFORMED_METADATA: String(scenario.malformedMetadata ?? false), + OMIT_METADATA_PRIVATE: String(scenario.omitMetadataPrivate ?? false), + METADATA_PRIVATE: JSON.stringify(scenario.metadataPrivate ?? false), + }, + }); + expect(run.status, run.stderr).toBe(scenario.expectedStatus); + expect(run.stderr).toContain(scenario.expectedMessage); + expect(readFileSync(ghLog, "utf8").trim().split("\n")).toEqual(["--version", ...scenario.endpoints]); + } finally { + rmSync(fixture, { recursive: true, force: true }); + } + }); + it("makes the production gate fail on a planted moving upstream citation", () => { const fixture = mkdtempSync(join(tmpdir(), "pins-")); try { diff --git a/test/verify-corpus.test.ts b/test/verify-corpus.test.ts index e629a18d..919f94e6 100644 --- a/test/verify-corpus.test.ts +++ b/test/verify-corpus.test.ts @@ -10,7 +10,7 @@ const root = dirname(dirname(fileURLToPath(import.meta.url))); const script = join(root, "scripts", "verify-corpus.mjs"); function runAgainst(dir: string) { - return spawnSync("node", [script], { + return spawnSync(process.execPath, [script], { encoding: "utf8", env: { ...process.env, CORPUS_FIXTURES_DIR: dir }, }); diff --git a/test/w8-applier-stamps-edge.test.ts b/test/w8-applier-stamps-edge.test.ts index 5287353b..77cc79d8 100644 --- a/test/w8-applier-stamps-edge.test.ts +++ b/test/w8-applier-stamps-edge.test.ts @@ -1,4 +1,4 @@ -import { describe, expect, it } from "vitest"; +import { beforeEach, describe, expect, it } from "vitest"; import * as Y from "yjs"; import { applyOps, @@ -28,6 +28,7 @@ const catalog: WidgetCatalog = { }; let sequence = 0; +beforeEach(() => { sequence = 0; }); const envelope = (actor = "actor") => ({ op_id: String(++sequence).padStart(32, "0"), actor, diff --git a/test/w8-projection-golden.test.ts b/test/w8-projection-golden.test.ts index 14d3d21b..185a225b 100644 --- a/test/w8-projection-golden.test.ts +++ b/test/w8-projection-golden.test.ts @@ -31,43 +31,9 @@ describe("W8 projection goldens (KA-3, KA-4, KA-12)", () => { }, } as unknown as WorkflowJSON; - expect(project(mint(workflow, catalog), catalog)).toMatchInlineSnapshot(` - { - "definitions": { - "subgraphs": [ - { - "id": "a", - "links": [], - "nodes": [], - }, - { - "id": "z", - "links": [], - "nodes": [], - }, - ], - }, - "links": [], - "nodes": [ - { - "id": 2, - "type": "Unknown", - }, - { - "id": 3, - "type": "Unknown", - }, - { - "id": "4", - "type": "Unknown", - }, - { - "id": "5", - "type": "Unknown", - }, - ], - } - `); + const projected = project(mint(workflow, catalog), catalog); + expect(projected.nodes.map(({ id }) => id)).toEqual([2, 3, "4", "5"]); + expect((projected.definitions as { subgraphs: Array<{ id: string }> }).subgraphs.map(({ id }) => id)).toEqual(["a", "z"]); }); it("preserves a catalog-miss node's opaque values but rejects an invalid named widget", () => {