diff --git a/docs/architecture/in-app-agent-docframe-typegen.md b/docs/architecture/in-app-agent-docframe-typegen.md new file mode 100644 index 00000000000..5d6c2179e1e --- /dev/null +++ b/docs/architecture/in-app-agent-docframe-typegen.md @@ -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@`). 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. diff --git a/src/workbench/extensions/agent/crdt/docFrameClient.ts b/src/workbench/extensions/agent/crdt/docFrameClient.ts index 81ed2372fed..98cfcddcdeb 100644 --- a/src/workbench/extensions/agent/crdt/docFrameClient.ts +++ b/src/workbench/extensions/agent/crdt/docFrameClient.ts @@ -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 ( + 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' && @@ -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 }) } @@ -343,8 +355,8 @@ function fitsAwarenessBudget(state: Record): 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 @@ -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 }) @@ -387,14 +399,16 @@ const serverFrameParsers: ServerFrameParsers = { }, doc_reset: (workflowId, data) => { const reset: Partial> = 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 }) } } diff --git a/src/workbench/extensions/agent/crdt/docFrameWireContract.test.ts b/src/workbench/extensions/agent/crdt/docFrameWireContract.test.ts new file mode 100644 index 00000000000..7ea8e3c6c53 --- /dev/null +++ b/src/workbench/extensions/agent/crdt/docFrameWireContract.test.ts @@ -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() + }) + + 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) + } + }) + }) +})