Repository navigation
chore(types): drop frontend-local docframe schema in favor of ingest-types #16191
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
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 d5ecf9d
feat: generate docframe protocol types
christian-byrne aa85859
fix: format generated docframe types
christian-byrne 1681e72
docs: link docframe typegen contract
christian-byrne 86d4a5a
test: preserve doc_update op id typegen
christian-byrne 9e003a7
fix: satisfy docframe OpenAPI yaml lint
christian-byrne 40259f5
ci: verify generated DocFrame types
christian-byrne 60875a1
test: validate DocUpdateData with Ajv
christian-byrne 0e6808f
test: remove duplicate draft patch applier
christian-byrne 21c537d
test: remove handwritten DocFrame fixture types
christian-byrne 8069606
fix(types): bound doc update operation ids
christian-byrne eba2ced
chore: merge main into docframe typegen branch
christian-byrne 30dded3
chore: drop frontend-local docframe schema and typegen
christian-byrne 3051159
test: pin doc frame parsing to the authoritative ingest schema
christian-byrne 870b9df
Merge remote-tracking branch 'origin/main' into op385-pr16191
christian-byrne 2df412c
test: adapt doc frame contract coverage
christian-byrne 2bbb13c
test: bind doc frame schema to adapter
christian-byrne 019b5df
fix: preserve results with invalid advisory seq
christian-byrne 3a2cc86
Merge remote-tracking branch 'origin/main' into pr16191-merge
ampagent File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Some comments aren't visible on the classic Files Changed page.
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
128 changes: 128 additions & 0 deletions
128
src/workbench/extensions/agent/crdt/docFrameWireContract.test.ts
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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() | ||
|
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) | ||
| } | ||
| }) | ||
| }) | ||
| }) | ||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.