Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
19 commits
Select commit Hold shift + click to select a range
00472aa
test: add deterministic agent fixture harness
christian-byrne Aug 28, 2026
d5ecf9d
feat: generate docframe protocol types
christian-byrne Aug 28, 2026
aa85859
fix: format generated docframe types
christian-byrne Aug 28, 2026
1681e72
docs: link docframe typegen contract
christian-byrne Aug 28, 2026
86d4a5a
test: preserve doc_update op id typegen
christian-byrne Aug 31, 2026
9e003a7
fix: satisfy docframe OpenAPI yaml lint
christian-byrne Aug 31, 2026
40259f5
ci: verify generated DocFrame types
christian-byrne Sep 1, 2026
60875a1
test: validate DocUpdateData with Ajv
christian-byrne Sep 1, 2026
0e6808f
test: remove duplicate draft patch applier
christian-byrne Sep 1, 2026
21c537d
test: remove handwritten DocFrame fixture types
christian-byrne Sep 1, 2026
8069606
fix(types): bound doc update operation ids
christian-byrne Sep 4, 2026
eba2ced
chore: merge main into docframe typegen branch
christian-byrne Sep 11, 2026
30dded3
chore: drop frontend-local docframe schema and typegen
christian-byrne Sep 11, 2026
3051159
test: pin doc frame parsing to the authoritative ingest schema
christian-byrne Sep 11, 2026
870b9df
Merge remote-tracking branch 'origin/main' into op385-pr16191
christian-byrne Oct 3, 2026
2df412c
test: adapt doc frame contract coverage
christian-byrne Oct 3, 2026
2bbb13c
test: bind doc frame schema to adapter
christian-byrne Oct 3, 2026
019b5df
fix: preserve results with invalid advisory seq
christian-byrne Oct 3, 2026
3a2cc86
Merge remote-tracking branch 'origin/main' into pr16191-merge
ampagent Oct 7, 2026
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
55 changes: 55 additions & 0 deletions docs/architecture/in-app-agent-docframe-typegen.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,55 @@
# In-App Agent doc-frame type-generation contract

The CRDT doc-frame wire contract is owned by Comfy Cloud's ingest service. The frontend imports its
generated types and schemas. Its production WebSocket boundary remains a handwritten adapter that
independently validates raw JSON before exposing frontend domain objects; a compatibility test feeds
generated schema output through that adapter to detect disagreement between the two representations.

## Contract

```text
cloud services/ingest/openapi.yaml (authority)
├──▶ cloud common/websocket/docframes (generated Go models)
└──▶ packages/ingest-types (generated TS types + Zod schemas)
└──▶ docFrameClient.ts (validation + domain adapter)
```

- `ServerDocFrame`, `DocUpdateFrame`/`DocUpdateData`, `DocResetFrame`/`DocResetData`,
`DocOpsResultFrame`/`DocOpsResultData`, and `DocOpFailure` come from `@comfyorg/ingest-types`.
`@comfyorg/ingest-types/zod` exposes the matching runtime validators.
- `packages/ingest-types` is regenerated from the cloud spec by an automated sync
(`[chore] Update Ingest API types from cloud@<sha>`). That sync is the freshness mechanism; the
frontend does not re-derive the schema locally.
- `doc_ops_result.data.failed` is the wire spelling. A frontend adapter may expose `failure`, but
that mapping must remain at the adapter boundary.
- Generated types describe the `{type,data}` bytes; they do not implement CRDT application,
authority, or mutation semantics.
- `parseServerDocFrame` does not invoke Zod in production. It independently validates raw WebSocket
values, converts the generated schemas' `bigint` int64 output to safe numeric domain values, and
maps snake-case wire fields to frontend names. Its compatibility tests pass representative
generated outputs through that adapter and assert their complete mapped payloads; they do not
claim that the handwritten parser accepts every value admitted by the generated schema.

## Validation the generated schema cannot provide

`update_b64` is an unconstrained string in the authoritative OpenAPI contract, so its generated Zod
schema also accepts malformed payloads. Cloud validates base64 in code (`validateB64` in
`common/websocket/messages`), and the frontend independently validates it in
`parseServerDocFrame`. The adapter can therefore reject schema-conforming input. Conversely, the
adapter accepts some raw frames that the generated schema rejects, such as a `doc_update` without
`lineage_seq`, because the frontend domain object does not use that field. The compatibility test
pins representative generated outputs plus these intentional boundary differences rather than
treating schema conformance as a prerequisite for adapter acceptance.

## References

- Cloud PR [#7730](https://github.com/Comfy-Org/cloud/pull/7730) — generated CRDT doc-frame wire types.
- `docs/guidance/typescript.md` — server/API response types come from the generated shared packages.
- `docs/adr/CRDT-FOLLOWER-0025-in-app-agent-crdt-follower-and-distribution-resolved-boundaries.md` —
frontend follower boundary.

## Glossary

- **Doc frame:** a CRDT message carried by the WebSocket `{type,data}` envelope.
- **Wire spelling:** the serialized field name shared by all producers and consumers.
- **Adapter boundary:** the one place a consumer may map a wire name to an internal name.
28 changes: 21 additions & 7 deletions src/workbench/extensions/agent/crdt/docFrameClient.ts
Original file line number Diff line number Diff line change
Expand Up @@ -214,6 +214,17 @@ function isSequence(value: unknown): value is number {
return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0
}

function parseSequence(value: unknown): number | null {
if (isSequence(value)) return value
if (
Comment thread
christian-byrne marked this conversation as resolved.
Resolved
typeof value === 'bigint' &&
value >= 0n &&
value <= BigInt(Number.MAX_SAFE_INTEGER)
)
return Number(value)
return null
}

function isValidOpId(value: unknown): value is string {
return (
typeof value === 'string' &&
Expand Down Expand Up @@ -329,8 +340,9 @@ type ServerFrameParsers = {
function parseResultMetadata(data: WireData) {
const code = parseBoundedString(data.code, MAX_ERROR_CODE_LENGTH)
const message = parseBoundedString(data.message, MAX_ERROR_MESSAGE_LENGTH)
const seq = parseSequence(data.seq)
return {
...(isSequence(data.seq) && { seq: data.seq }),
...(seq !== null && { seq }),
...(code !== undefined && { code }),
...(message !== undefined && { message })
}
Expand All @@ -343,8 +355,8 @@ function fitsAwarenessBudget(state: Record<string, unknown>): boolean {

const serverFrameParsers: ServerFrameParsers = {
doc_update: (workflowId, data) => {
if (!isSequence(data.seq) || typeof data.update_b64 !== 'string')
return null
const seq = parseSequence(data.seq)
if (seq === null || typeof data.update_b64 !== 'string') return null
const update = decodeBase64(data.update_b64)
if (update === null) return null
if (!isAbsent(data.op_ids) && !isStringArray(data.op_ids)) return null
Expand All @@ -353,7 +365,7 @@ const serverFrameParsers: ServerFrameParsers = {
type: 'doc_update',
data: {
workflowId,
seq: data.seq,
seq,
update,
...(actor !== undefined && { actor }),
...(isStringArray(data.op_ids) && { opIds: data.op_ids })
Expand Down Expand Up @@ -387,14 +399,16 @@ const serverFrameParsers: ServerFrameParsers = {
},
doc_reset: (workflowId, data) => {
const reset: Partial<Record<keyof DocResetData, unknown>> = data
if (!isSequence(reset.seq) || !isSequence(reset.lineage_seq)) return null
const seq = parseSequence(reset.seq)
const lineageSeq = parseSequence(reset.lineage_seq)
if (seq === null || lineageSeq === null) return null
const actor = parseAdvisoryActor(reset.actor)
return {
type: 'doc_reset',
data: {
workflowId,
seq: reset.seq,
lineageSeq: reset.lineage_seq,
seq,
lineageSeq,
...(actor !== undefined && { actor })
}
}
Expand Down
128 changes: 128 additions & 0 deletions src/workbench/extensions/agent/crdt/docFrameWireContract.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,128 @@
import { zDocUpdateFrame, zServerDocFrame } from '@comfyorg/ingest-types/zod'
import { describe, expect, it } from 'vitest'

import { encodeBase64, parseServerDocFrame } from './docFrameClient'

function docUpdateFrame(update_b64: string) {
return {
type: 'doc_update',
data: {
v: 1,
workflow_id: 'wf-1',
seq: 1,
lineage_seq: 1,
update_b64
}
}
}

const representativeFrames = [
{
wire: docUpdateFrame(encodeBase64(Uint8Array.of(1, 2, 3))),
expected: {
type: 'doc_update',
data: {
workflowId: 'wf-1',
seq: 1,
update: Uint8Array.of(1, 2, 3)
}
}
},
{
wire: {
type: 'doc_reset',
data: { v: 1, workflow_id: 'wf-1', seq: 7, lineage_seq: 2 }
},
expected: {
type: 'doc_reset',
data: { workflowId: 'wf-1', seq: 7, lineageSeq: 2 }
}
},
{
wire: {
type: 'doc_ops_result',
data: {
v: 1,
workflow_id: 'wf-1',
ok: false,
seq: 8,
applied: ['op-1'],
skipped: ['op-3'],
failed: { index: 1, op_id: 'op-2', code: 'invalid', message: 'bad op' }
}
},
expected: {
type: 'doc_ops_result',
data: {
workflowId: 'wf-1',
ok: false,
seq: 8,
applied: ['op-1'],
skipped: ['op-3'],
failed: {
index: 1,
op_id: 'op-2',
code: 'invalid',
message: 'bad op'
}
}
}
}
]

describe('doc frame wire contract', () => {
it.for(representativeFrames)(
'adapts representative generated $wire.type frames without losing payload fields',
({ wire, expected }) => {
const generatedFrame = zServerDocFrame.parse(wire)

expect(parseServerDocFrame(generatedFrame)).toEqual(expected)
}
)

it.for(['not base64!', 'AQE', 'AQ== ', 'AQB=', 'AR=='])(
'rejects update_b64 %j, which the wire schema admits',
(update_b64) => {
const generatedFrame = zDocUpdateFrame.parse(docUpdateFrame(update_b64))

expect(parseServerDocFrame(generatedFrame)).toBeNull()
}
)

it.for([null, '', {}])('rejects empty external input %#', (value) => {
expect(parseServerDocFrame(value)).toBeNull()
})

it('rejects a generated int64 sequence outside the frontend safe-integer domain', () => {
const wire = docUpdateFrame(encodeBase64(Uint8Array.of(1)))
const generatedFrame = zDocUpdateFrame.parse({
...wire,
data: {
...wire.data,
seq: BigInt(Number.MAX_SAFE_INTEGER) + 1n
}
})

expect(parseServerDocFrame(generatedFrame)).toBeNull()
Comment thread
christian-byrne marked this conversation as resolved.
Resolved
})

it('accepts a generated int64 sequence at the frontend safe-integer boundary', () => {
const wire = docUpdateFrame(encodeBase64(Uint8Array.of(1)))
const generatedFrame = zDocUpdateFrame.parse({
...wire,
data: {
...wire.data,
seq: BigInt(Number.MAX_SAFE_INTEGER)
}
})

expect(parseServerDocFrame(generatedFrame)).toEqual({
type: 'doc_update',
data: {
workflowId: 'wf-1',
seq: Number.MAX_SAFE_INTEGER,
update: Uint8Array.of(1)
}
})
})
})
Loading