Implement Canvas V2 subgraphs, assets and asynchronous AI execution
This commit is contained in:
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user