Implement Canvas V2 subgraphs, assets and asynchronous AI execution
Foundry Go checks / check (push) Successful in 2m40s
Foundry Go checks / check (pull_request) Successful in 2m36s

This commit is contained in:
2026-11-06 18:36:00 +08:00
parent 7847167043
commit d6ee8942f1
62 changed files with 8339 additions and 35 deletions
+320 -3
View File
@@ -64,9 +64,10 @@ On the deployment host, provision `/opt/endoleap-infra/foundry/codex` with:
With that directory configured, the next normal Foundry deployment starts the
worker using the Linux binary built by ces-control and mounts the worker socket
and grants directory read-only. To replace an existing worker, stop and remove
its container, then run `bash deploy/codex-worker.sh /absolute/path/to/foundry`
with the desired ces-control build. The worker
and grants directory read-only. Normal backend deployments replace the worker with the same reviewed Linux build
and verify its private model catalog, restoring the previous worker if startup
fails. For manual maintenance, stop the managed worker before running
`bash deploy/codex-worker.sh /absolute/path/to/foundry`. The worker
runs the installed Codex CLI with fixed read-only, no-approval arguments and
disables command execution tools. It receives prompts via stdin and returns
the final agent message. The worker has no published port and Foundry receives
@@ -142,3 +143,319 @@ must renew its HttpOnly cookie using that value, with a maximum of 30 days. It m
not extend a cookie beyond the backend-provided remaining lifetime, or expose the
session token to client JavaScript. CORS exposes the lifetime header alongside
ETag where applicable. The absolute deadline stays server-authoritative.
### Canvas V2 contract
Contract version: `canvas-v2-2026-11-06`. These routes are implemented on the
Canvas V2 work branch; they become available after that branch is reviewed,
merged and deployed. Do not infer production availability from this document.
`B` below means `/projects/{project}/workspaces/{workspace}/materials/{board}/canvas`.
Workspace and board path segments accept canonical UUIDs or existing slugs.
Responses and child relationships use canonical IDs. Authentication is the
existing **user session Bearer token**, with inherited material/workspace
permissions; the old project Codex service token is not accepted as a user login.
Reader/viewer accounts may read; mutations require editor/admin access.
The existing 30-day idle renewal and 90-day absolute session expiry are unchanged.
#### Snapshot compatibility and bounds
Use `Accept: application/vnd.foundry.canvas+json;version=2` for V2 clients.
GET remains `{version,document}`; PATCH accepts `{document}` and returns `{version}`.
The actual schema is in `document.schema_version` and `X-Canvas-Schema-Version`;
`ETag: "N"` is the independent canvas version. PATCH requires `If-Match: "N"`:
missing versions return 428, stale versions return 412 with zero writes.
V1 is still supported. Once a board is V2, legacy GET/PATCH and schema downgrades
return 409 `canvas_schema_upgrade_required`; no lossy V1 projection is returned.
GET does not create or migrate child boards.
Each canvas permits 500 nodes, 2,000 edges and 5 MiB of snapshot request data.
Coordinates and control vectors are finite, within ±1,000,000. Ordinary node
width/height are 20–3,000; V2 frame dimensions are 32–100,000. Ephemeral selection,
dragging, measured geometry and editor gesture state are not saved.
V2 edges preserve typed `data.appearance`, `animation`, `path` and `execution`:
| Field | Values / bounds |
| --- | --- |
| appearance | six-digit hex color; width 0.5–20; opacity 0.05–1; solid/dashed/dotted |
| head / tail | none/open-arrow/triangle/circle/diamond/square; size 4–32; boolean filled |
| animation | off/always/executing; flow/dash/pulse; forward/reverse; durationMs 250–30,000; hex color |
| path | bezier-chain; optional startControl/endControl; up to 64 ordered, uniquely identified knots |
| knot | position and relative in/out vectors; corner/smooth/symmetric; collinearity/length tolerance 1e-6 |
| execution.enabled | boolean; omitted means enabled; animation direction does not reverse dependencies |
Omitted appearance/animation fields remain omitted and use the original client
defaults (color `#AA968B`, width 1.5, solid, no markers, animation off).
No arbitrary CSS, SVG path strings, marker URLs or callbacks are accepted.
Text/script/image/plain-text/plain-image nodes can connect; icons cannot.
Frames connect through declared `port:<id>` handles, including nested port chains.
`GET B/capabilities` reports schema versions, actual worker availability and
limits. A configured catalog alone does not imply that every model can generate
images: image variants are enabled only for backend models explicitly verified
by the operator.
#### Subgraphs and cross-canvas transactions
Each linked frame owns one child board in the same project/workspace. The maximum
nesting depth is eight. The parent stores the frame and boundary edges; member
nodes and internal edges have exactly one owner, the child canvas. Child reads
and writes inherit the parent chain, including when addressed directly by ID.
Material lists omit child boards by default; `include_subgraphs=true` includes
accessible children with `parent_board_id` and `frame_id`.
Frame data retains `subgraph.boardId`, `ports`, and presentation:
`collapsed`, `contentScale` (0.05–4), `expandedSize`, `collapsedSize`.
Collapsing/scaling presentation does not rewrite child content. Projection is
`frame.position + (24,36) + contentScale * child.position`; viewport is independent.
| Route | Required input / behavior |
| --- | --- |
| POST B/subgraphs | Parent If-Match; `{frame:{id,title,position,width,height,labelMode}}`; returns 201, child_board, parent/child snapshots and receipt |
| POST B/subgraphs/{frame}/members | `{source_board_id,target_board_id,node_ids,expected_versions}`; parent/child or siblings coordinated by their common parent |
| POST B/subgraphs/{frame}/dissolve | `{expected_versions}`; preserves content in the parent and archives the emptied child |
| POST B/subgraphs/migrate | `{dry_run:true}` creates no data; returns plan_id, digest, parent version and explicit members/edges/issues |
| POST B/subgraphs/migrate | `{dry_run:false,plan_id}` plus parent If-Match; stale plans return 412 |
| POST B/transactions/{id}/undo | `{expected_versions}`; restores snapshots and relationships atomically, increments current versions |
All mutating commands above require a UUID `Idempotency-Key` (case-insensitive).
Scope is project/workspace/user/resource/action. Canonical payload retries return
the same operation; a different payload returns 409 `idempotency_conflict`.
Records remain available for at least 24 hours. Read-only migration preflight
requires editor/admin but does not require an idempotency key or create a plan row.
`expected_versions` must include **every modified canvas**, including an ancestor
whose boundary port must change and child canvases whose ownership changes.
Missing versions return 428; any stale version returns 412 before commit.
All snapshots, versions, relationships, idempotency and receipt records share a
single SQL transaction. Boundary edges retain their IDs/styles/paths; ports are
stable and deduplicated. Node ID collisions and graph capacity errors reject the
entire command. Ordinary PATCH cannot detach linked frames, retarget ownership
or remove nodes still referenced across a boundary.
Undo receipts have an absolute `expires_at` and a seven-day lifetime; retries do
not extend it. Expired undo returns 409 `undo_receipt_expired`. Undo also checks
recorded after-state and current relationships, so incompatible edits return 412.
Undoing a later operation can restore a compatible state for an earlier undo
without resetting version counters. Redo uses the original command and a new key.
Migration considers only explicit legacy `frameId` membership, including empty
frames. It preserves internal and boundary edges, image references and styling,
converts coordinates/control points, and skips already linked frames. Original
snapshots and mapping data remain in the operation record for rollback.
#### Assets
`POST /projects/{project}/workspaces/{workspace}/assets` takes one multipart part
named `image` (or `file`) and an Idempotency-Key. PNG/JPEG/WebP/GIF are decoded,
not trusted by filename. The limit is 20 MiB and 40 million decoded pixels.
The response is `{id,mime_type,bytes,width,height,url}`. PostgreSQL stores the
encoded object, metadata and bindings atomically.
`GET .../assets/{id}` requires a user session and returns the actual image bytes
with the detected MIME and `nosniff`. Unbound objects are readable only by their
uploader or workspace admins; bound objects require access to an owning material
through its current parent chain. URLs are stable HTTPS application URLs, never
worker files or expiring signed URLs. Browser integrations should use an
authenticated fetch/proxy; do not persist temporary blob URLs in snapshots.
`data.assetId` is optional when `src` is already a stable managed URL. Moves,
dissolve and undo retain bindings; referenced images are not prematurely collected.
AI image inputs are frozen as authorized asset references. Existing inline images
and public HTTPS node images can be validated and frozen by Core. Fetches enforce
HTTPS, DNS/IP checks, bounded redirects/bytes/time, and reject private, loopback,
link-local and cloud metadata addresses. The worker receives validated bytes over
private Unix IPC, not arbitrary external download instructions.
#### AI models and runs
`GET B/ai/models` returns opaque IDs derived from the worker's real CLI catalog,
modalities, availability, input/timeout bounds and parameter schemas. Current CLI
variants expose an empty parameter object with `additionalProperties:false`;
raw CLI arguments and unknown parameters are rejected. No token, auth file, raw
CLI output or service configuration is included in browser responses.
Node `data.ai` stores enabled/modelId/prompt/propagate/parameters. Prompt length
is at most 16,000 characters; parameters encode to at most 16 KiB. Global AI panel
state, tool position and animation progress are client state, not snapshot data.
| Route | Input / result |
| --- | --- |
| POST B/ai/runs | If-Match + Idempotency-Key; `{node_id,model_id,prompt,parameters,propagate}`; returns 202 with run_id, poll_url, plan, canvas_version and ETag |
| GET B/ai/runs/{id} | after_seq >= 0, limit 1–100; status, plan, steps, events, next_seq, has_more, output metadata and applied_versions |
| GET B/ai/runs | status=active or a terminal status; include_descendants=true/false; limit 1–50; opaque next_cursor |
| POST B/ai/runs/{id}/cancel | Idempotency-Key; empty object/body; returns preserved applied steps and cancelled steps |
| POST B/ai/runs/{id}/apply | If-Match + Idempotency-Key; `{node_id,output_id}`; explicitly applies retained conflict output to its current target canvas |
Run admission atomically saves node configuration, increments the canvas version,
freezes the plan/fingerprints and records the task and key. A node has at most one
active step; another key targeting a busy node returns 409 `node_busy`. Queue
capacity is 128 active runs per project (429 `queue_full` with Retry-After).
Admission body is at most 256 KiB. Assembled model text is at most 1 MiB; inputs
allow four distinct images totaling 20 MiB. Text timeout is 90 seconds; verified
image variants use 180 seconds. The old `/codex/exec` limits remain unchanged.
Propagation is opt-in. It resolves nested ports to logical nodes, rejects cycles
and plans over 64 steps/depth 32 before invoking the worker, and stops at
unconfigured nodes. A topological schedule runs each node once; diamond joins
wait for every participating predecessor. Other referenced inputs are frozen
from their original snapshots. Incoming logical edge IDs order inputs stably.
Only connected canvases/port chains/static inputs are read, not every child board.
Runs persist across HTTP disconnects and Core restarts. Queue leases serialize
execution; expired uncertain executions fail with `execution_interrupted` rather
than being silently reissued. A worker's explicit pre-execution busy response is
safe to requeue, with completed predecessor results recovered from the database.
Worker output updates only current target text or src/assetId in a SQL transaction.
Node identity, dimensions, position, title and styling are retained. Content/AI
configuration changes produce conflict and retain the output; geometry-only edits
do not. Deletion, recreation, kind/ownership changes, revoked permission or cancel
prevent late writes. Image output must be an actual decoded managed image;
textual URLs are never accepted as completed image generation.
Events have monotonic per-run seq values and are replayable through polling.
Run states: queued/running/succeeded/partially_succeeded/failed/cancelled/conflict.
Step states additionally include skipped. Edge active/completed/failed/skipped
events drive execution-only animation; reverse visual animation does not reverse
execution. Cancellation commits terminal step states before acknowledging, retains
already applied results, and stops the worker through request cancellation at its
next heartbeat. It never implicitly rolls back applied output.
Text output is capped at 100,000 characters; failures keep original content.
Poll event pages are bounded to 100 events and approximately 800 KiB of event data.
Output metadata includes output IDs and image asset metadata; text content patches
are in replayable step.output/step.applied events. Runs/events are retained for at
least 30 days; referenced assets have no automatic destructive cleanup.
Errors use `{error,message?,details?,request_id?}`. Important statuses include
400 invalid_canvas/invalid_ai_request, 409 schema/idempotency/ownership/cycle
conflicts, 412 version_conflict, 428 version_required, 413 graph/context/asset
limits, 422 model_unavailable/model_incompatible and 429 queue_full. Asynchronous
generation failures are terminal step/run results, not successful empty content.
#### Remote verification and deployment
Normal `ces-control` CI runs formatting, tests, builds, migration checks and
isolated PostgreSQL integration tests. `deploy/check-canvas-real.sh bin/foundry`
is an explicit remote-runner-only real-model verification; it does not run in
normal CI. Set `FOUNDRY_CANVAS_IMAGE_MODELS` to backend names already verified for
image output. The check starts a temporary CLI worker and database and removes
both afterwards; the Core/test container never receives CLI login files.
On 2026-11-06, the isolated real check succeeded with text model
`codex-18061daa6ba6e3a576dda453d0df839f` and image variant
`codex-42cfda1d607e416417a1a0ac5c73d437`, backed by the installed CLI's
`gpt-6.1-sol`. The image decoded as PNG, 1254×1254, 857,723 bytes. These are
verification observations, not a hardcoded catalog or a production deployment
claim; temporary run/asset records were cleaned up. Always query the live catalog.
For production, the worker can load operator-controlled `codex/canvas.env` with
`FOUNDRY_CANVAS_IMAGE_MODELS` containing verified backend names. Replace the worker
with the reviewed Linux build through the normal deployment process, apply the
numbered migrations and confirm capabilities before migrating a real canvas.
The user-selected migration target is the board addressed by workspace slug
`workspace-8d775c90-74c9-4109-a1ad-6d0ad3a00ac7` and board slug
`canvas-a9f9a985-e99a-43eb-b088-7edc9301452f`. Production migration remains pending
manual PR merge/deployment. Resolve canonical IDs, take a read-only preflight,
execute only its current plan, and record before/after versions, frame/child IDs,
counts and authenticated V2 rereads. Do not migrate other account resources or let
a legacy client overwrite the migrated board.
#### Reproducible session API examples
These examples require Bash, curl and jq, an editor/admin login session, and an
explicitly selected board. Set `SESSION_TOKEN` in memory; use the user session,
never the legacy Codex service token. Run mutations only on a board intended for
V2 testing. Each successful mutation changes versions: reread before the next
operation. Reuse the same key and identical body when retrying an operation.
```bash
API=https://api.foundry.entroia.com
PROJECT=your-project
WORKSPACE=your-workspace-id-or-slug
BOARD=your-board-id-or-slug
B="$API/projects/$PROJECT/workspaces/$WORKSPACE/materials/$BOARD/canvas"
api() {
curl --fail-with-body --silent --show-error \
-H "Authorization: Bearer $SESSION_TOKEN" \
-H 'Accept: application/vnd.foundry.canvas+json;version=2' "$@"
}
# V2-aware read; capabilities report actual deployment and model availability.
api "$B/capabilities"
snapshot=$(api "$B")
version=$(jq -r '.version' <<<"$snapshot")
# Save an unchanged document, explicitly upgrading the envelope to V2.
payload=$(jq '{document:(.document | .schema_version=2)}' <<<"$snapshot")
api -X PATCH "$B" -H 'Content-Type: application/json' \
-H "If-Match: \"$version\"" --data-binary "$payload"
# Create an empty real child with its parent frame, atomically.
version=$(api "$B" | jq -r '.version')
create_key=$(uuidgen)
api -X POST "$B/subgraphs" -H 'Content-Type: application/json' \
-H "If-Match: \"$version\"" -H "Idempotency-Key: $create_key" \
--data '{"frame":{"id":"example-frame","title":"Example","position":{"x":100,"y":100},"width":640,"height":400,"labelMode":"fixed"}}'
# Read-only old-frame preflight. Inspect issues/counts/mappings before executing.
plan=$(api -X POST "$B/subgraphs/migrate" -H 'Content-Type: application/json' \
--data '{"dry_run":true}')
printf '%s\n' "$plan" | jq .
```
After reviewing that preflight, execute precisely its returned plan with a new
UUID key and the unchanged parent version. Any intervening change returns 412;
repeat preflight instead of forcing a stale migration.
```bash
version=$(api "$B" | jq -r '.version')
migrate_key=$(uuidgen)
payload=$(jq '{dry_run:false,plan_id:.plan_id}' <<<"$plan")
api -X POST "$B/subgraphs/migrate" -H 'Content-Type: application/json' \
-H "If-Match: \"$version\"" -H "Idempotency-Key: $migrate_key" \
--data-binary "$payload"
models=$(api "$B/ai/models")
printf '%s\n' "$models" | jq .
TEXT_MODEL=$(jq -r '[.models[] | select(.available and (.output_modalities | index("text")))][0].id // empty' <<<"$models")
IMAGE_MODEL=$(jq -r '[.models[] | select(.available and (.output_modalities | index("image")))][0].id // empty' <<<"$models")
# Supply existing eligible node IDs from the selected board.
TEXT_NODE=your-text-node
IMAGE_NODE=your-image-node
run_node() {
local node="$1" model="$2" propagate="$3" prompt="$4" version key payload
test -n "$model" || { printf 'No available model for this modality\n' >&2; return 1; }
version=$(api "$B" | jq -r '.version')
key=$(uuidgen)
payload=$(jq -n --arg node "$node" --arg model "$model" --arg prompt "$prompt" \
--argjson propagate "$propagate" \
'{node_id:$node,model_id:$model,prompt:$prompt,parameters:{},propagate:$propagate}')
api -X POST "$B/ai/runs" -H 'Content-Type: application/json' \
-H "If-Match: \"$version\"" -H "Idempotency-Key: $key" --data-binary "$payload"
}
text_run=$(run_node "$TEXT_NODE" "$TEXT_MODEL" false 'Summarize this content')
run_id=$(jq -r '.run_id' <<<"$text_run")
api "$B/ai/runs/$run_id?after_seq=0&limit=100"
api "$B/ai/runs?status=active&include_descendants=true&limit=50"
```
Wait for a terminal status before starting another run on the same node. Continue
polling from `next_seq` while `has_more` is true, then retain the cursor for the
next poll. Image generation and propagation use the same asynchronous contract:
```bash
image_run=$(run_node "$IMAGE_NODE" "$IMAGE_MODEL" false 'Generate an image from this reference')
image_run_id=$(jq -r '.run_id' <<<"$image_run")
api "$B/ai/runs/$image_run_id?after_seq=0&limit=100"
# Once succeeded, outputs[].output.src is an authenticated managed image URL.
# Fetch that URL with api and --output to verify the actual image bytes.
# Configure downstream node data.ai and execution edges before propagation.
propagated_run=$(run_node "$TEXT_NODE" "$TEXT_MODEL" true 'Transform and propagate')
api "$B/ai/runs/$(jq -r '.run_id' <<<"$propagated_run")?after_seq=0&limit=100"
```
The live catalog, rather than the isolated verification IDs above, determines
whether each request can run. A 202 response acknowledges a queued job; use its
terminal status and authenticated canvas/asset rereads as completion evidence.