diff --git a/.agents/checks/follower-boundary.md b/.agents/checks/follower-boundary.md index cc2bfb160a7..0c9c3b864b1 100644 --- a/.agents/checks/follower-boundary.md +++ b/.agents/checks/follower-boundary.md @@ -10,6 +10,16 @@ Check changes under `src/workbench/extensions/agent/**` (and anything importing [ADR-CRDT-FOLLOWER-0025](../../docs/adr/CRDT-FOLLOWER-0025-in-app-agent-crdt-follower-and-distribution-resolved-boundaries.md) and the CRDT layout split in [ADR-CRDT-LAYOUT-0003](../../docs/adr/CRDT-LAYOUT-0003-crdt-layout-intent-and-local-measurement.md). +**Mechanical subset now machine-checked (FE-1968):** the outbound `update_b64` construction +check, the `op_id`-regeneration-on-retry check, the second-applier-import check, the +branch-pinned-catalog-citation check, the scattered-distribution-check check, and the +hardcoded-endpoint check below no longer depend on this LLM pass — run +`pnpm follower-invariants:check` (`scripts/check-follower-invariants.ts`, tested by +`scripts/check-follower-invariants.test.ts`). Treat a failure there as the same `issue:` +severity as a manual finding of the same kind; this review pass should still flag the +semantic/data-flow judgment calls the script cannot make (e.g. "is this really the shared +doc", "does this new path count as a second writer"). + These are load-bearing: a low-context change that violates one can silently foreclose the future P2P / offline / multi-writer / multi-agent story, or ship a follower that renders in one distribution and fails as a product in another. Flag violations as `issue:` (blocking), diff --git a/package.json b/package.json index 61f65bdf63a..85306cd1517 100644 --- a/package.json +++ b/package.json @@ -9,6 +9,7 @@ "type": "module", "scripts": { "adr:check": "tsx scripts/check-adrs.ts", + "follower-invariants:check": "tsx scripts/check-follower-invariants.ts", "build:cloud": "cross-env DISTRIBUTION=cloud vite build --config vite.config.mts", "build:desktop-dist": "cross-env DISTRIBUTION=desktop vite build --config vite.config.mts", "build-storybook": "storybook build", diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml index e3fffb33527..319771a53cb 100644 --- a/pnpm-workspace.yaml +++ b/pnpm-workspace.yaml @@ -154,6 +154,7 @@ catalog: vue-tsc: ^3.3.11 vuefire: ^3.2.1 wwobjloader2: ^6.2.1 + yaml: ^2.8.3 yjs: ^13.6.27 zod: ^3.23.8 zod-to-json-schema: ^3.24.1 diff --git a/scripts/check-follower-invariants.test.ts b/scripts/check-follower-invariants.test.ts new file mode 100644 index 00000000000..2db4ae9dbaf --- /dev/null +++ b/scripts/check-follower-invariants.test.ts @@ -0,0 +1,221 @@ +import { readFileSync } from 'node:fs' +import { resolve } from 'node:path' +import { describe, expect, test } from 'vitest' + +import { + checkCatalogPinnedBySha, + checkFile, + checkNoHardcodedEndpoint, + checkNoOpIdRegeneration, + checkNoOutboundUpdateB64, + checkNoScatteredDistributionChecks, + checkSingleApplier, + FOLLOWER_CORE_FILES +} from './check-follower-invariants' + +const FOLLOWER_FILE = FOLLOWER_CORE_FILES[0] + +describe('checkNoOutboundUpdateB64', () => { + test('fails a forbidden mutation fixture: constructing an outbound update_b64 frame', () => { + const fixture = ` + function sendUpdate(encoded: string) { + socket.send(JSON.stringify({ type: 'doc_update', update_b64: encoded })) + } + ` + const violations = checkNoOutboundUpdateB64(FOLLOWER_FILE, fixture) + expect(violations).toHaveLength(1) + expect(violations[0].rule).toBe('no-outbound-update-b64') + }) + + test('passes the allowed follower projection: decoding an inbound update_b64', () => { + const fixture = ` + if (typeof data.update_b64 === 'string') { + const update = decodeBase64(data.update_b64) + followerDoc.applyRemoteUpdate(update) + } + ` + expect(checkNoOutboundUpdateB64(FOLLOWER_FILE, fixture)).toEqual([]) + }) + + test('passes a type/interface member declaration named update_b64', () => { + const fixture = ` + interface DocUpdateFrame { + update_b64?: unknown + } + ` + expect(checkNoOutboundUpdateB64(FOLLOWER_FILE, fixture)).toEqual([]) + }) +}) + +describe('checkNoOpIdRegeneration', () => { + test('fails a forbidden mutation fixture: re-minting op_id on retry outside opEnvelope.ts', () => { + const fixture = ` + function retrySend(op: Op) { + return { ...op, op_id: createUuidv4() } + } + ` + const violations = checkNoOpIdRegeneration( + 'src/workbench/extensions/agent/crdt/opSender.ts', + fixture + ) + expect(violations).toHaveLength(1) + expect(violations[0].rule).toBe('no-op-id-regeneration') + }) + + test('passes the allowed follower projection: minting once in opEnvelope.ts', () => { + const fixture = ` + function withEnvelope(operation, context) { + return { ...operation, op_id: mintOpId(), actor: context.actor } + } + ` + expect( + checkNoOpIdRegeneration( + 'src/workbench/extensions/agent/crdt/opEnvelope.ts', + fixture + ) + ).toEqual([]) + }) + + test('passes a resend that reuses the same minted ops without reassigning op_id', () => { + const fixture = ` + function resend(ops: Op[]) { + return ops.map((op) => ({ ...op })) // same op_id, no re-mint + } + ` + expect(checkNoOpIdRegeneration(FOLLOWER_FILE, fixture)).toEqual([]) + }) +}) + +describe('checkSingleApplier', () => { + test('fails a forbidden mutation fixture: importing a local applier reimplementation', () => { + const fixture = ` + import { applyOp } from './applier' + ` + const violations = checkSingleApplier(FOLLOWER_FILE, fixture) + expect(violations).toHaveLength(1) + expect(violations[0].rule).toBe('single-applier') + }) + + test('passes the allowed follower projection: importing the pinned shared package', () => { + const fixture = ` + import type { Op } from '@comfyorg/comfy-multi-player' + import { BATCHABLE_OPS } from '@comfyorg/comfy-multi-player' + ` + expect(checkSingleApplier(FOLLOWER_FILE, fixture)).toEqual([]) + }) +}) + +describe('checkCatalogPinnedBySha', () => { + test('fails a forbidden mutation fixture: citing the catalog by moving branch', () => { + const fixture = ` + // fetched from the widget catalog @main + ` + const violations = checkCatalogPinnedBySha(FOLLOWER_FILE, fixture) + expect(violations).toHaveLength(1) + expect(violations[0].rule).toBe('catalog-pinned-by-sha') + }) + + test('passes the allowed follower projection: citing the catalog by SHA', () => { + const fixture = ` + // catalog pinned at meta.catalog_version, cited by sha256 8d062714 + ` + expect(checkCatalogPinnedBySha(FOLLOWER_FILE, fixture)).toEqual([]) + }) +}) + +describe('checkNoScatteredDistributionChecks', () => { + test('fails a forbidden mutation fixture: DISTRIBUTION conditional inside follower core', () => { + const fixture = ` + const endpoint = isCloud ? cloudEndpoint : localEndpoint + ` + const violations = checkNoScatteredDistributionChecks( + FOLLOWER_FILE, + fixture + ) + expect(violations).toHaveLength(1) + expect(violations[0].rule).toBe('no-scattered-distribution-checks') + }) + + test('passes the allowed follower projection: no distribution reference in follower core', () => { + const fixture = ` + const endpoint = resolveAgentBaseUrl() + ` + expect(checkNoScatteredDistributionChecks(FOLLOWER_FILE, fixture)).toEqual( + [] + ) + }) + + test('passes a debug-report file reading DISTRIBUTION for display only', () => { + const fixture = ` + lines.push(\`- **Distribution:** \${DISTRIBUTION}\`) + ` + expect( + checkNoScatteredDistributionChecks( + 'src/workbench/extensions/agent/crdt/crdtDebugReport.ts', + fixture + ) + ).toEqual([]) + }) +}) + +describe('checkNoHardcodedEndpoint', () => { + test('fails a forbidden mutation fixture: a hardcoded wss:// literal in follower core', () => { + const fixture = ` + const socket = new WebSocket('wss://agent.comfy.org/ws') + ` + const violations = checkNoHardcodedEndpoint(FOLLOWER_FILE, fixture) + expect(violations).toHaveLength(1) + expect(violations[0].rule).toBe('no-hardcoded-endpoint') + }) + + test('passes the allowed follower projection: resolving through the centralized seam', () => { + const fixture = ` + const socket = api.socket(resolveAgentBaseUrl()) + ` + expect(checkNoHardcodedEndpoint(FOLLOWER_FILE, fixture)).toEqual([]) + }) + + test('passes an endpoint literal mentioned only in a comment', () => { + const fixture = ` + // legacy endpoint was wss://old.example.com/ws, now resolved dynamically + const socket = api.socket(resolveAgentBaseUrl()) + ` + expect(checkNoHardcodedEndpoint(FOLLOWER_FILE, fixture)).toEqual([]) + }) +}) + +describe('checkFile (combined) — allowed follower projection', () => { + test('a realistic allowed follower projection passes every rule at once', () => { + const fixture = ` + import type { Op } from '@comfyorg/comfy-multi-player' + + import { resolveAgentBaseUrl } from '@/platform/agent/agentBaseUrl' + + // catalog pinned at meta.catalog_version, cited by sha256 8d062714 + + export function connect(): WebSocket { + return new WebSocket(resolveAgentBaseUrl()) + } + + export function onFrame(data: { update_b64?: unknown }) { + if (typeof data.update_b64 === 'string') { + const update = decodeBase64(data.update_b64) + followerDoc.applyRemoteUpdate(update) + } + } + ` + expect(checkFile(FOLLOWER_FILE, fixture)).toEqual([]) + }) +}) + +describe('checkFile against the real follower-core sources', () => { + test.for(FOLLOWER_CORE_FILES)('%s has zero violations today', (file) => { + let source: string + try { + source = readFileSync(resolve(process.cwd(), file), 'utf8') + } catch { + return // file may not exist yet (e.g. followerSubscription.ts is a .ts vs actual .test.ts split) + } + expect(checkFile(file, source)).toEqual([]) + }) +}) diff --git a/scripts/check-follower-invariants.ts b/scripts/check-follower-invariants.ts new file mode 100644 index 00000000000..acf35ace53f --- /dev/null +++ b/scripts/check-follower-invariants.ts @@ -0,0 +1,318 @@ +/** + * Deterministic (non-LLM) guards for the mechanical CRDT follower invariants + * described in `.agents/checks/follower-boundary.md`. That reviewer profile + * currently delegates repeatable syntax/import checks to LLM inference + * (lines 31-33, 62-72, 82-93); this script covers the syntactic subset with + * plain source scanning so those cases no longer depend on a model call. + * Semantic/data-flow cases (e.g. "is this really the shared doc") stay with + * the LLM reviewer — see the profile for what remains judgment-based. + * + * ADR: docs/adr/CRDT-FOLLOWER-0025-in-app-agent-crdt-follower-and-distribution-resolved-boundaries.md + * Linear: FE-1968 (github.com/Comfy-Org/ComfyUI_frontend/issues/16497) + * + * Each exported `check*` function takes a file path + source text and + * returns a list of violations (empty = pass). `main()` walks the real + * follower-core file set; `check-follower-invariants.test.ts` drives the + * same functions against in-memory fixtures (one forbidden-mutation fixture + * per rule, plus one allowed-projection fixture that must pass every rule). + */ +import { readFileSync } from 'node:fs' +import { resolve } from 'node:path' +import { fileURLToPath } from 'node:url' + +export interface Violation { + file: string + line: number + rule: string + message: string +} + +/** + * Files that make up the follower "apply seam" per ADR-CRDT-FOLLOWER-0025: + * the wire client, the follower doc/gate/bridge, the ECS adapter, and the + * op mint/send path. Distribution and endpoint checks (rules 3-4) apply only + * here. Debug/report/log files intentionally read `DISTRIBUTION` for display + * strings and are out of scope for those two rules (see + * `crdtDebugReport.ts`'s `- **Distribution:** ${DISTRIBUTION}` line). + */ +export const FOLLOWER_CORE_FILES = [ + 'src/workbench/extensions/agent/crdt/docFrameClient.ts', + 'src/workbench/extensions/agent/crdt/useAgentCrdtFollower.ts', + 'src/workbench/extensions/agent/crdt/followerDoc.ts', + 'src/workbench/extensions/agent/crdt/followerGate.ts', + 'src/workbench/extensions/agent/crdt/ecsFollowerAdapter.ts', + 'src/workbench/extensions/agent/crdt/layoutFollowerBridge.ts', + 'src/workbench/extensions/agent/crdt/opSender.ts', + 'src/workbench/extensions/agent/crdt/opEnvelope.ts', + 'src/workbench/extensions/agent/crdt/mintPortWiring.ts', + 'src/workbench/extensions/agent/crdt/mintSession.ts', + 'src/workbench/extensions/agent/crdt/mintGate.ts' +] as const + +/** + * Files under `crdt/` that are exempt from the "second applier" import + * ban (rule 2) and the distribution/endpoint rules (rules 3-4) because they + * are debug/report/log utilities, not the apply seam, or are test-scenario + * simulators that intentionally reimplement merge behaviour offline for + * fixtures (never wired into the live follower path). + */ +const NON_SEAM_ALLOWLIST = new Set([ + 'src/workbench/extensions/agent/crdt/crdtDebugReport.ts', + 'src/workbench/extensions/agent/crdt/crdtDebugGate.ts', + 'src/workbench/extensions/agent/crdt/crdtLog.ts', + 'src/workbench/extensions/agent/crdt/devPanelLog.ts', + 'src/workbench/extensions/agent/crdt/mergeScenarios.ts', + 'src/workbench/extensions/agent/crdt/mergeTrace.ts' +]) + +const isTestOrFixture = (file: string): boolean => + /\.(test|spec)\.ts$/.test(file) || file.includes('__fixtures__/') + +function scan( + source: string, + pattern: RegExp, + build: (line: string, lineNumber: number) => Violation | null +): Violation[] { + const violations: Violation[] = [] + const lines = source.split('\n') + for (let index = 0; index < lines.length; index++) { + const line = lines[index] + if (!pattern.test(line)) continue + const violation = build(line, index + 1) + if (violation) violations.push(violation) + } + return violations +} + +/** + * Rule 1 (profile lines 31-33): the client never sends raw Yjs binary + * (`update_b64`) upstream — it only ever *decodes* an inbound `update_b64` + * field. Flags any object literal or send-call that constructs an outbound + * `update_b64` key, while allowing the existing inbound `data.update_b64` + * read/decode shape. + */ +export function checkNoOutboundUpdateB64( + file: string, + source: string +): Violation[] { + if (isTestOrFixture(file)) return [] + // Constructing a frame: `{ ... update_b64: ... }` as an object we + // are building (not destructuring/reading). A read looks like + // `data.update_b64` or `.update_b64 ===`/`typeof x.update_b64`; a + // construction looks like `update_b64:` immediately followed by a value, + // inside code that is not a type/interface member declaration (those use + // `update_b64?: unknown` or `update_b64: string` as a *type*, which this + // rule must not flag). + const CONSTRUCTION_PATTERN = + /(? { + if (READ_PATTERN.test(line)) return null + if (TYPE_MEMBER_PATTERN.test(line)) return null + if (!CONSTRUCTION_PATTERN.test(line)) return null + return { + file, + line: lineNumber, + rule: 'no-outbound-update-b64', + message: + 'constructs an outbound update_b64 field — the client emits stamped doc_ops only; ' + + 'raw Yjs binary flows host -> follower one-way (KEEP-ALIVE #6, ADR-CRDT-FOLLOWER-0025)' + } + }) +} + +/** + * Rule 2 (profile lines 62-72, first bullet): `op_id` is minted exactly + * once by `mintOpId()` before dispatch and never regenerated on retry. + * Flags any second call site that assigns a freshly generated id onto an + * `op_id` field outside `opEnvelope.ts`'s own mint function, and any + * `op_id:` object field assigned directly from a uuid/random call. + */ +export function checkNoOpIdRegeneration( + file: string, + source: string +): Violation[] { + if (isTestOrFixture(file)) return [] + if (file.endsWith('opEnvelope.ts')) return [] // the one legitimate mint site + const REGEN_PATTERN = + /op_id\s*:\s*(createUuidv4|uuidv4|uuid|crypto\.randomUUID|mintOpId)\s*\(/ + + return scan(source, /op_id\s*:/, (line, lineNumber) => { + if (!REGEN_PATTERN.test(line)) return null + return { + file, + line: lineNumber, + rule: 'no-op-id-regeneration', + message: + 'assigns a freshly minted op_id outside opEnvelope.ts — op_id is minted exactly once ' + + 'by mintOpId() before dispatch; a retry resends the same minted ops (FORECLOSE #7, ADR-CRDT-FOLLOWER-0025)' + } + }) +} + +/** + * Rule 3 (profile lines 68-70): there must be exactly one applier + * (`@comfyorg/comfy-multi-player`, pinned by SHA in package.json). Flags any + * import from a package-manager-relative or local reimplementation path + * that looks like a second applier: a local module literally named + * `applier`/`docHost`/`opApplier`, or importing merge/conflict-resolution + * helpers from anywhere other than the pinned package. + */ +export function checkSingleApplier(file: string, source: string): Violation[] { + if (isTestOrFixture(file)) return [] + if (NON_SEAM_ALLOWLIST.has(file)) return [] + const FORBIDDEN_LOCAL_APPLIER_IMPORT = + /^\s*import\s+.*from\s+['"](?!@comfyorg\/comfy-multi-player)[^'"]*\/(applier|docHost|opApplier|docApplier)['"]/ + + return scan(source, /^\s*import\s+/, (line, lineNumber) => { + if (!FORBIDDEN_LOCAL_APPLIER_IMPORT.test(line)) return null + return { + file, + line: lineNumber, + rule: 'single-applier', + message: + 'imports a locally implemented applier module — op-to-doc/conflict-resolution logic must ' + + 'come from the single shared @comfyorg/comfy-multi-player package (FORECLOSE #3, ADR-CRDT-FOLLOWER-0025)' + } + }) +} + +/** + * Rule 4 (profile lines 71-72): the widget catalog/vocabulary must be cited + * by pinned SHA, never a moving branch name. Flags a catalog/vocabulary + * reference alongside a `refs/heads/`, `HEAD`, or bare branch-name pattern + * such as `main`/`master`/`develop` immediately following `catalog` or + * `vocabulary` in the same line — the mechanical subset of "branch-pinned + * citation"; judging an unfamiliar ref as a SHA vs. a branch name stays with + * the LLM reviewer. + */ +export function checkCatalogPinnedBySha( + file: string, + source: string +): Violation[] { + if (isTestOrFixture(file)) return [] + if (NON_SEAM_ALLOWLIST.has(file)) return [] + const BRANCH_CITATION_PATTERN = + /(catalog|vocabulary)[^\n]{0,40}(refs\/heads\/[\w-]+|@(main|master|develop|HEAD)\b)/i + + return scan(source, /(catalog|vocabulary)/i, (line, lineNumber) => { + if (!BRANCH_CITATION_PATTERN.test(line)) return null + return { + file, + line: lineNumber, + rule: 'catalog-pinned-by-sha', + message: + 'cites the widget catalog/vocabulary by moving branch instead of a pinned SHA ' + + '(FORECLOSE #10, ADR-CRDT-FOLLOWER-0025)' + } + }) +} + +/** + * Rule 5 (profile lines 82-84): distribution conditionals must not scatter + * through follower core — they belong only in the agent connection/config + * boundary. Flags any reference to `DISTRIBUTION`, `isCloud`, or `isDesktop` + * inside a `FOLLOWER_CORE_FILES` entry. + */ +export function checkNoScatteredDistributionChecks( + file: string, + source: string +): Violation[] { + if (isTestOrFixture(file)) return [] + if (!(FOLLOWER_CORE_FILES as readonly string[]).includes(file)) return [] + const DISTRIBUTION_PATTERN = /\b(DISTRIBUTION|isCloud|isDesktop)\b/ + + return scan(source, DISTRIBUTION_PATTERN, (_line, lineNumber) => ({ + file, + line: lineNumber, + rule: 'no-scattered-distribution-checks', + message: + 'references DISTRIBUTION/isCloud/isDesktop inside the follower apply seam — distribution ' + + 'conditionals belong only in the agent connection/configuration boundary (Priority 4, ADR-CRDT-FOLLOWER-0025)' + })) +} + +/** + * Rule 6 (profile lines 90-93): no hardcoded agent base URL. Flags a literal + * `ws://`, `wss://`, `http://`, or `https://` endpoint string inside a + * `FOLLOWER_CORE_FILES` entry, outside of comments/tests. The centralized + * `AGENT_BASE_URL`-style resolver is the only place an endpoint literal may + * live. + */ +export function checkNoHardcodedEndpoint( + file: string, + source: string +): Violation[] { + if (isTestOrFixture(file)) return [] + if (!(FOLLOWER_CORE_FILES as readonly string[]).includes(file)) return [] + const ENDPOINT_LITERAL_PATTERN = /['"](wss?|https?):\/\/[^'"]+['"]/ + + return scan(source, ENDPOINT_LITERAL_PATTERN, (line, lineNumber) => { + const trimmed = line.trim() + if (trimmed.startsWith('//') || trimmed.startsWith('*')) return null + return { + file, + line: lineNumber, + rule: 'no-hardcoded-endpoint', + message: + 'hardcodes an agent endpoint literal in follower core — resolve the endpoint through the ' + + 'centralized distribution-resolved AGENT_BASE_URL-style seam (Priority 4, ADR-CRDT-FOLLOWER-0025)' + } + }) +} + +export const CHECKS = [ + checkNoOutboundUpdateB64, + checkNoOpIdRegeneration, + checkSingleApplier, + checkCatalogPinnedBySha, + checkNoScatteredDistributionChecks, + checkNoHardcodedEndpoint +] + +export function checkFile(file: string, source: string): Violation[] { + return CHECKS.flatMap((check) => check(file, source)) +} + +function main(): void { + const repositoryRoot = process.cwd() + const violations: Violation[] = [] + const scannedFiles = new Set([...FOLLOWER_CORE_FILES]) + + for (const file of scannedFiles) { + let source: string + try { + source = readFileSync(resolve(repositoryRoot, file), 'utf8') + } catch { + continue // file removed/renamed; nothing to scan + } + violations.push(...checkFile(file, source)) + } + + if (violations.length === 0) { + process.stdout.write( + `Follower invariant guard passed (${scannedFiles.size} files scanned)\n` + ) + return + } + + process.stderr.write( + `Follower invariant guard found ${violations.length} violation(s):\n\n` + + violations + .map((v) => `${v.file}:${v.line} [${v.rule}] ${v.message}`) + .join('\n') + + '\n\nSee .agents/checks/follower-boundary.md and ' + + 'docs/adr/CRDT-FOLLOWER-0025-in-app-agent-crdt-follower-and-distribution-resolved-boundaries.md\n' + ) + process.exitCode = 1 +} + +if ( + process.argv[1] && + fileURLToPath(import.meta.url) === resolve(process.argv[1]) +) { + main() +}