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

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions .agents/checks/follower-boundary.md
Original file line number Diff line number Diff line change
Expand Up @@ -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),
Expand Down
1 change: 1 addition & 0 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down
1 change: 1 addition & 0 deletions pnpm-workspace.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
221 changes: 221 additions & 0 deletions scripts/check-follower-invariants.test.ts
Original file line number Diff line number Diff line change
@@ -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([])
})
})
Loading
Loading