@sogni-ai/sogni-protocol 1.0.0-alpha.10

package/prompts/tools/set_content_filter.json

@@ -0,0 +1,9 @@
+{
+  "contractId": "set_content_filter_v1",
+  "version": "1.0.0",
+  "toolName": "set_content_filter",
+  "baseDescription": "set_content_filter enables or disables the Safe Content Filter. Call only when the user\nexplicitly asks to change this setting. Do not toggle it as part of ordinary generation.\n\nIf disabling requires host-side confirmation, let the handler surface that permission flow;\ndo not claim the setting changed unless the tool result says it did.",
+  "parameterDocs": {
+    "enabled": "true to enable the filter, false to disable it. Only set from explicit user intent."
+  }
+}

package/prompts/tools/sound_to_video.json

@@ -0,0 +1,9 @@
+{
+  "contractId": "sound_to_video_v1",
+  "version": "1.0.0",
+  "toolName": "sound_to_video",
+  "baseDescription": "sound_to_video creates audio-synced video from an audio source. Works with uploaded audio\nfiles (mp3, m4a, wav) OR previously generated music from generate_music (auto-detected).\n\nWhen the user asks to \"turn that song/music into a video\" after generate_music, use\nsound_to_video — it will automatically find the generated audio.\n\nFor music visualization (syncing video to a specific song or audio track), use the\ngenerate_music → sound_to_video pipeline. Do NOT use animate_photo or generate_video for\naudio-driven visualization.\n\nanimate_photo and generate_video produce audio natively via LTX 2.3 — never pre-generate\naudio for those tools. sound_to_video is only for when the audio IS the primary creative\ninput driving the video output.",
+  "parameterDocs": {
+    "audioSource": "Uploaded audio file or reference to a prior generate_music result. Auto-detected when omitted after generate_music."
+  }
+}

package/prompts/tools/stitch_video.json

@@ -0,0 +1,9 @@
+{
+  "contractId": "stitch_video_v1",
+  "version": "1.0.0",
+  "toolName": "stitch_video",
+  "baseDescription": "stitch_video joins multiple video clips into one. Reference generated videos by their\n0-based video indices (from videoStartIndex in prior tool results). Reference uploaded\nvideos with negative indices in current UI order: -1 = first uploaded video, -2 = second, etc.\nWhen the user asks to stitch these/all uploaded videos and does not name a different order,\nuse the current UI order exactly: [-1,-2,...].\nIf the user explicitly names a different playback order, preserve that requested order exactly;\ndo not rewrite it back to UI order.\n\nNEVER tell the user to \"upload\" a video that was already generated in this conversation —\nstitch_video can reference them directly by index.\n\nWhen stitching results from a batch video tool, use ONLY the video indices actually returned\nby that tool. Do not infer the stitch list from the number of source images, keyframes, or\nstoryboard panels. Example: if 5 uploaded keyframes create 4 adjacent animate_photo\ntransition clips and the tool result returns videos at indices 0,1,2,3, call stitch_video\nwith videoIndices=[0,1,2,3] — never include index 4 unless a fifth video was returned.\n\nDo not use stitch_video for alternating/interleaved time slices such as \"alternate\n1s from each video\"; stitch_video joins whole clips end-to-end, while interleaving existing\nvideo slices belongs to repeated replace_video_segment calls with replacementVideoIndex and\nreplacementStartSeconds/replacementEndSeconds.\n\nNote: video_to_video requires an actual uploaded video file and cannot use generated video\nindices. Do not claim exact final runtime, dimensions, or aspect ratio after a tool finishes\nunless that value was explicitly requested by the user or explicitly returned by the tool.",
+  "parameterDocs": {
+    "videoIndices": "Ordered source video indices. Use non-negative generated-video indices from prior tool results; use negative uploaded-video indices in current UI order (-1 first uploaded video, -2 second, etc.)."
+  }
+}

package/prompts/tools/validate_asset_references.json

@@ -0,0 +1,10 @@
+{
+  "contractId": "validate_asset_references_v1",
+  "version": "1.0.0",
+  "toolName": "validate_asset_references",
+  "baseDescription": "validate_asset_references checks a prompt for provider-specific manifest reference tokens\nand reports which resolve or dangle. Call right before dispatching a prompt that names\nmanifest assets with model_ref tokens.\n\nDo not use this for plain uploaded references. If validation finds dangling refs, repair the\nprompt or register/map the asset before running an expensive generation tool.",
+  "parameterDocs": {
+    "model_id": "Target provider/model id whose reference token format should be scanned.",
+    "prompt": "Prompt text about to be sent to the model."
+  }
+}

package/prompts/tools/video_to_video.json

@@ -0,0 +1,13 @@
+{
+  "contractId": "video_to_video_v1",
+  "version": "1.0.0",
+  "toolName": "video_to_video",
+  "baseDescription": "video_to_video transforms an uploaded video. Use for uploaded-video restyling, enhancement,\nupscaling/remastering, motion transfer from video to image, subject replacement, edge/pose/\ndepth-guided restyle, or explicit Seedance V2V transforms.\n\nThis tool requires an uploaded video source. Do not use it for generated video indices. For\ngenerated or uploaded partial edits use replace_video_segment; for appended time use\nextend_video; for logos/text overlays use overlay_video; for stitching use stitch_video.\n\nChoose controlMode by intent. Use detailer for quality-only enhancement without restyling.\nUse seedance-v2v only when the user asks to transform/enhance/remaster an uploaded video\nwith Seedance. For detailer, describe the original scene plus quality terms, not new content.",
+  "parameterDocs": {
+    "prompt": "Describe the target appearance in present tense. For detailer, describe the original content plus quality qualifiers only.",
+    "videoSourceIndex": "Uploaded video index. Omit when there is one uploaded video; use 0 for first uploaded video or -1 if using negative upload notation.",
+    "controlMode": "Pick from intent: detailer for enhance, seedance-v2v for explicit Seedance V2V, canny/depth/pose for control-net restyles, animate-move/replace for WAN Animate.",
+    "sourceImageIndex": "Required for animate-move and animate-replace. Ignored by canny, depth, and detailer.",
+    "duration": "Set only when the user requests a different output length; otherwise let the tool match/cap the source duration."
+  }
+}

package/schemas/agent/intent-input.schema.json

@@ -0,0 +1,128 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.sogni.ai/creative-agent/2026-05-20.1/agent/intent-input.schema.json",
+  "title": "L1 IntentClassifier input packet",
+  "schemaVersion": "2026-05-20.1",
+  "description": "Compact context packet handed to the L1 IntentClassifier at the start of every user turn. Qwen3 256k context window comfortably holds 16-reference-image generations and multi-segment storyboard frames; the runtime never silently drops artifacts. Trim only when measured budget pressure forces it. This contract is built deterministically by the host (browser or cloud runner) from explicit runtime state; it never re-derives semantics from transcript regex.",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "currentMessage": {
+      "type": "string",
+      "description": "Raw user message text for this turn. Verbatim; sanitization belongs to boundary code, not this contract."
+    },
+    "currentMessageDetails": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Optional structured form of the user's latest message. Producers MAY emit either currentMessage or this; consumers MUST handle BOTH. `text` is required so consumers can always derive a string-level view.",
+      "properties": {
+        "id": { "type": "string" },
+        "role": { "type": "string", "enum": ["user", "system"] },
+        "text": { "type": "string" },
+        "createdAt": { "type": "string", "format": "date-time" },
+        "localeHint": { "type": "string" }
+      },
+      "required": ["text"]
+    },
+    "runtimeFlags": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Optional runtime feature flags the planner reads to decide tool surface and confirmation policy.",
+      "properties": {
+        "surface": {
+          "type": "string",
+          "enum": ["browser", "hosted_chat", "durable_chat", "workflow", "native", "skill"],
+          "description": "Originating producer surface."
+        },
+        "allowPaidTools": { "type": "boolean" },
+        "allowMutatingTools": { "type": "boolean" },
+        "durableRequired": { "type": "boolean" }
+      }
+    },
+    "activeState": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Currently-resolved focus state owned by the runtime (artifact graph + workflow runner). Populated from explicit runtime references — never from prose extraction.",
+      "properties": {
+        "activeArtifactId": { "type": "string" },
+        "activeArtifactType": {
+          "type": "string",
+          "enum": ["image", "video", "audio", "text", "workflow", "collection"]
+        },
+        "pendingAction": {
+          "type": "object",
+          "description": "Opaque reference to a runtime-tracked pending action (e.g. proposed plan awaiting selection). Shape is owned by the runtime, not this schema.",
+          "additionalProperties": true
+        },
+        "awaitingConfirmation": { "type": "boolean" },
+        "lastToolResult": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "toolName": { "type": "string" },
+            "toolCallId": { "type": "string" },
+            "status": { "type": "string" }
+          },
+          "required": ["toolName", "toolCallId", "status"]
+        },
+        "activeWorkflowRunId": { "type": "string" }
+      }
+    },
+    "artifactState": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Stable artifact identifiers owned by the ArtifactGraph. Qwen3 256k context window comfortably holds 16-reference-image generations and multi-segment storyboard frames; the runtime never silently drops artifacts. Trim only when measured budget pressure forces it.",
+      "properties": {
+        "selectedArtifactIds": {
+          "type": "array",
+          "description": "Artifacts the user or planner has explicitly focused (e.g. multi-select for batch edit).",
+          "items": { "type": "string" }
+        },
+        "artifactIds": {
+          "type": "array",
+          "description": "Full conversation artifact id list. UNBOUNDED by default. Qwen3 256k context window comfortably holds 16-reference-image generations and multi-segment storyboard frames; the runtime never silently drops artifacts. Trim only when measured budget pressure forces it.",
+          "items": { "type": "string" }
+        },
+        "lastGeneratedArtifactId": { "type": "string" },
+        "lastEditedArtifactId": { "type": "string" }
+      },
+      "required": ["selectedArtifactIds", "artifactIds"]
+    },
+    "recentTurns": {
+      "type": "array",
+      "description": "Recent transcript window. UNBOUNDED by default. Qwen3 256k context window comfortably holds 16-reference-image generations and multi-segment storyboard frames; the runtime never silently drops artifacts. Trim only when measured budget pressure forces it. Sliding-window trimming from contextWindow.ts only fires after measured token budget pressure, and writes the trimmed prefix into conversationSummary.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "role": { "type": "string", "enum": ["user", "assistant", "tool", "system"] },
+          "content": { "type": "string" },
+          "sequence": { "type": "integer", "minimum": 0 }
+        },
+        "required": ["role", "content", "sequence"]
+      }
+    },
+    "conversationSummary": {
+      "type": "string",
+      "description": "Rolling summary of trimmed prefix. Empty string until the first measured-budget-pressure trim event."
+    },
+    "userPreferences": {
+      "type": "object",
+      "description": "Free-form preference payload (e.g. preferred model tier, default aspect ratio). Deliberate exception: additionalProperties is true here, mirroring the data/metadata pattern in other contracts, because preferences evolve faster than the schema.",
+      "additionalProperties": true
+    },
+    "availableCapabilitiesSummary": {
+      "type": "array",
+      "description": "Short human-readable capability strings the planner can quote when answering capability questions without invoking any tool.",
+      "items": { "type": "string" }
+    }
+  },
+  "required": [
+    "currentMessage",
+    "activeState",
+    "artifactState",
+    "recentTurns",
+    "conversationSummary",
+    "availableCapabilitiesSummary"
+  ]
+}

package/schemas/agent/turn-analysis.schema.json

@@ -0,0 +1,75 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.sogni.ai/creative-agent/2026-05-20.1/agent/turn-analysis.schema.json",
+  "title": "L1 IntentClassifier output",
+  "schemaVersion": "2026-05-20.1",
+  "description": "Structured output of the L1 IntentClassifier. Produced by an LLM-backed classifier, a typed planner, runtime state inspection, the artifact graph, or an explicit user signal — never by regex. Per the Codex reconciliation in v2 plan §1.A, the legacy SignalSource value 'regex' is intentionally absent from SignalProvenance; regex is demoted to bounded fact extraction (dimensions, durations, file types) which does not produce semantic intent.",
+  "type": "object",
+  "additionalProperties": false,
+  "$defs": {
+    "SignalProvenance": {
+      "type": "string",
+      "description": "Which layer authored this TurnAnalysis. The value 'regex' is intentionally absent — regex extracts bounded facts only and never decides intent, tool surface, or routing.",
+      "enum": [
+        "classifier",
+        "planner",
+        "runtime_state",
+        "artifact_graph",
+        "user_explicit"
+      ]
+    }
+  },
+  "properties": {
+    "domain": {
+      "type": "string",
+      "enum": ["chat", "image", "video", "audio", "analysis", "workflow", "memory", "settings", "unknown"]
+    },
+    "intent": {
+      "type": "string",
+      "enum": ["generate", "edit", "analyze", "transform", "question", "capability", "continue", "reference", "configure", "clarify", "unknown"]
+    },
+    "executionMode": {
+      "type": "string",
+      "enum": ["none", "tool", "multi_tool", "workflow"]
+    },
+    "userWantsExecution": { "type": "boolean" },
+    "isCapabilityQuestion": { "type": "boolean" },
+    "isFutureInstruction": { "type": "boolean" },
+    "isReferenceOnly": { "type": "boolean" },
+    "needsPriorContext": { "type": "boolean" },
+    "needsClarification": { "type": "boolean" },
+    "referencedArtifacts": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Artifact ids the classifier resolved from the user's message via the artifact graph (positional references like 'the second image' resolve to stable ids before this list is emitted)."
+    },
+    "requiredCapabilities": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Free-form capability tags the planner must satisfy (e.g. 'image_generation', 'video_stitch')."
+    },
+    "confidence": {
+      "type": "number",
+      "minimum": 0,
+      "maximum": 1
+    },
+    "provenance": {
+      "$ref": "#/$defs/SignalProvenance"
+    }
+  },
+  "required": [
+    "domain",
+    "intent",
+    "executionMode",
+    "userWantsExecution",
+    "isCapabilityQuestion",
+    "isFutureInstruction",
+    "isReferenceOnly",
+    "needsPriorContext",
+    "referencedArtifacts",
+    "requiredCapabilities",
+    "needsClarification",
+    "confidence",
+    "provenance"
+  ]
+}

package/schemas/artifacts/artifact-graph.schema.json

@@ -0,0 +1,42 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.sogni.ai/creative-agent/2026-05-20.1/artifacts/artifact-graph.schema.json",
+  "title": "Artifact graph serialization",
+  "schemaVersion": "2026-05-20.1",
+  "description": "Durable serialization of the in-memory ArtifactGraph. The same shape mirrors into ChatRunRecord.artifacts[] and WorkflowRunRecord.artifacts[] so cloud and hosted runners can reconstitute the graph on resume. The runtime Map<string, ArtifactNode> serializes as a positional nodes[] array; artifactId uniqueness is a runtime invariant, not expressible cheaply in JSON Schema.",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "nodes": {
+      "type": "array",
+      "description": "All artifact nodes in the graph. Uniqueness on artifactId is enforced by the runtime, not the schema.",
+      "items": {
+        "$ref": "./artifact-node.schema.json"
+      }
+    },
+    "selectedId": {
+      "type": "string",
+      "description": "Optional currently-selected artifact id. When present, MUST match an artifactId in nodes."
+    },
+    "compatibilityProjections": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Read-only legacy projections derived from nodes[]. Populated during the Phase 1-4 transition so existing chat-side code that still reads positional URL arrays keeps working. Deleted after plan Phase 5.",
+      "properties": {
+        "resultUrls": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "videoResultUrls": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "audioResultUrls": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      }
+    }
+  },
+  "required": ["nodes"]
+}

package/schemas/artifacts/artifact-node.schema.json

@@ -0,0 +1,137 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.sogni.ai/creative-agent/2026-05-20.1/artifacts/artifact-node.schema.json",
+  "title": "Artifact graph node",
+  "schemaVersion": "2026-05-20.1",
+  "description": "One node in the v2 ArtifactGraph. ArtifactNode replaces positional URL arrays (resultUrls / videoResultUrls / audioResultUrls) deleted in plan Phase 5. Every tool result auto-registers one node. Lineage edges resolve continuation ('use the second image', 'make it cinematic') without transcript scraping. Per-model token shape lives in modelRefs (gpt-image-2 'Image 1', seedance-2 '@Image1', ltx-2.3 'context_image_0').",
+  "type": "object",
+  "additionalProperties": false,
+  "$defs": {
+    "ArtifactEdge": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Typed lineage edge from this artifact to one of its parents.",
+      "properties": {
+        "parentId": { "type": "string" },
+        "relation": {
+          "type": "string",
+          "enum": [
+            "derived_from",
+            "edited_from",
+            "styled_from",
+            "animated_from",
+            "stitched_from",
+            "extended_from",
+            "segmented_from",
+            "reference_for"
+          ]
+        }
+      },
+      "required": ["parentId", "relation"]
+    },
+    "ArtifactVersion": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "One version of an artifact. Retries, refinements, and user-driven redos all append a version rather than mutating an existing one.",
+      "properties": {
+        "versionId": { "type": "string" },
+        "uri": { "type": "string" },
+        "createdAt": { "type": "string", "format": "date-time" },
+        "reason": {
+          "type": "string",
+          "enum": ["initial", "retry", "refinement", "audit_repair", "user_redo"]
+        },
+        "jobId": {
+          "type": "string",
+          "description": "Optional sogni-socket job id that produced this version."
+        }
+      },
+      "required": ["versionId", "createdAt", "reason"]
+    },
+    "ArtifactSource": {
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "type": { "const": "upload" },
+            "uploadId": { "type": "string" }
+          },
+          "required": ["type", "uploadId"]
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "type": { "const": "tool_result" },
+            "runId": { "type": "string" },
+            "toolCallId": { "type": "string" }
+          },
+          "required": ["type", "toolCallId"]
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "type": { "const": "workflow_stage" },
+            "workflowRunId": { "type": "string" },
+            "stageId": { "type": "string" },
+            "itemId": { "type": "string" }
+          },
+          "required": ["type", "workflowRunId", "stageId"]
+        }
+      ]
+    }
+  },
+  "properties": {
+    "artifactId": {
+      "type": "string",
+      "pattern": "^art_(?:[0-9A-Z]{26}|[0-9a-fA-F]{32}|[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$",
+      "description": "Stable artifact id. ULID form (`art_` + 26-char Crockford base32 body) is RECOMMENDED for new ids — use `generateUlidArtifactId()` from `@sogni-ai/sogni-intelligence-client/artifacts`. Two legacy forms remain accepted so existing in-wild ids stay valid: `art_` + 32 hex chars (UUID with hyphens stripped, the historical `createArtifactNode` output) and `art_` + canonical UUID with hyphens. Read-side validators must keep accepting all three; write-side code SHOULD enforce ULID via `preferUlid()`."
+    },
+    "kind": {
+      "type": "string",
+      "enum": ["image", "video", "audio", "text", "workflow", "collection"]
+    },
+    "uri": {
+      "type": "string",
+      "description": "Canonical resolvable URI for the current version (mirrors versions[last].uri for convenience)."
+    },
+    "mimeType": { "type": "string" },
+    "userLabel": {
+      "type": "string",
+      "description": "Friendly label the user (or the system on the user's behalf) chose. Optional; planner falls back to artifactId + kind."
+    },
+    "modelRefs": {
+      "type": "object",
+      "additionalProperties": { "type": "string" },
+      "description": "Per-model formatter mapping. Keys are model ids; values are the token that model expects in prompts. Examples: gpt-image-2 -> 'Image 1', seedance-2 -> '@Image1', ltx-2.3 -> 'context_image_0'. Use the asset-reference helpers in @sogni/creative-agent rather than hand-formatting."
+    },
+    "source": { "$ref": "#/$defs/ArtifactSource" },
+    "parents": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/ArtifactEdge" }
+    },
+    "versions": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "$ref": "#/$defs/ArtifactVersion" }
+    },
+    "metadata": {
+      "type": "object",
+      "additionalProperties": true,
+      "description": "Free-form artifact metadata (width/height, durationSeconds, seed, prompt summary, etc.). Boundary code populates known fields; consumers must not assume any specific field is present."
+    },
+    "createdAt": { "type": "string", "format": "date-time" }
+  },
+  "required": [
+    "artifactId",
+    "kind",
+    "modelRefs",
+    "source",
+    "parents",
+    "versions",
+    "metadata",
+    "createdAt"
+  ]
+}

package/schemas/billing/spend-gate.schema.json

@@ -0,0 +1,151 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.sogni.ai/creative-agent/2026-05-20.1/billing/spend-gate.schema.json",
+  "title": "Spend gate request and state",
+  "schemaVersion": "2026-05-20.1",
+  "description": "Single shared spend-approval state machine for atomic tool calls (scope='tool_call'), grouped concurrent dispatches (scope='parallel_batch'), and workflow authorizations (scope='workflow_run'). One envelope, one state enum, one transition log. Per-job settlement remains on the sogni-socket project+N path — this gate authorizes spend, it does not move funds. Note: additionalProperties:false is applied per oneOf branch, not at the root — a root-level additionalProperties has no sibling properties to whitelist against and would reject every payload.",
+  "type": "object",
+  "$defs": {
+    "SpendGateState": {
+      "type": "string",
+      "description": "Canonical lifecycle states for a spend gate. 'not_required' = free / no-cost tool. 'preview_required' = estimate must be shown to the user. 'waiting_for_user' = awaiting confirm or cancel. 'confirmed' = user accepted; runner may dispatch. 'cancelled' = user declined. 'insufficient_credit' = wallet balance below estimate. 'safety_review_required' = blocked pending human or automated safety review. 'failed' = unrecoverable error in the gate itself.",
+      "enum": [
+        "not_required",
+        "preview_required",
+        "waiting_for_user",
+        "confirmed",
+        "cancelled",
+        "insufficient_credit",
+        "safety_review_required",
+        "failed"
+      ]
+    },
+    "SpendGateDecision": {
+      "type": "string",
+      "description": "Decision recorded when the gate leaves waiting_for_user. Three historical vocabularies are accepted: 'confirm'/'cancel' (canonical), 'approved'/'rejected' (pre-2026-05-20 aliases still emitted by sogni-api and sogni-creative-agent durable runs), and 'cancelled' (alternate past-tense spelling collapsing to 'cancel'). Consumers normalize via normalizeSpendDecision so business logic only sees the canonical pair.",
+      "enum": ["confirm", "cancel", "approved", "rejected", "cancelled"]
+    },
+    "SpendEstimateLineItem": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "One row of the spend estimate breakdown. Sum of (units * model price) across line items yields the estimate's capacityUnits.",
+      "properties": {
+        "model": { "type": "string" },
+        "units": { "type": "number", "minimum": 0 },
+        "tokenType": {
+          "type": "string",
+          "enum": ["spark", "sogni"]
+        }
+      },
+      "required": ["model", "units", "tokenType"]
+    },
+    "SpendGateEstimate": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Estimate payload carried on the gate itself. capacityUnits = sum of breakdown units; tokenType = denomination the breakdown is in; maxAcceptableUnits = optional caller-supplied cap.",
+      "properties": {
+        "capacityUnits": { "type": "number", "minimum": 0 },
+        "breakdown": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "$ref": "#/$defs/SpendEstimateLineItem" }
+        },
+        "tokenType": {
+          "type": "string",
+          "enum": ["spark", "sogni"]
+        },
+        "maxAcceptableUnits": { "type": "number", "minimum": 0 }
+      },
+      "required": ["capacityUnits", "breakdown", "tokenType"]
+    },
+    "PendingToolCall": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Minimal reference to a tool call this gate covers (when scope='tool_call' the array has one entry; when scope='parallel_batch' it carries the constituent calls of the fan-out; when scope='workflow_run' the gate authorizes the umbrella and pendingToolCalls may be empty).",
+      "properties": {
+        "toolCallId": { "type": "string" },
+        "toolName": { "type": "string" },
+        "estimateUnits": { "type": "number", "minimum": 0 }
+      },
+      "required": ["toolCallId", "toolName"]
+    },
+    "PendingWorkflowPlan": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Reference to the workflow run this gate authorizes (only meaningful when scope='workflow_run').",
+      "properties": {
+        "workflowRunId": { "type": "string" },
+        "templateId": { "type": "string" }
+      },
+      "required": ["workflowRunId", "templateId"]
+    }
+  },
+  "oneOf": [
+    {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "gateId": { "type": "string" },
+        "runId": { "type": "string" },
+        "scope": { "const": "tool_call" },
+        "toolCallId": { "type": "string" },
+        "pendingToolCalls": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/PendingToolCall" }
+        },
+        "estimate": { "$ref": "#/$defs/SpendGateEstimate" },
+        "state": { "$ref": "#/$defs/SpendGateState" },
+        "reason": { "type": "string" },
+        "decision": { "$ref": "#/$defs/SpendGateDecision" },
+        "createdAt": { "type": "string", "format": "date-time" },
+        "decidedAt": { "type": "string", "format": "date-time" },
+        "updatedAt": { "type": "string", "format": "date-time" },
+        "failureReason": { "type": "string" }
+      },
+      "required": ["gateId", "scope", "toolCallId", "estimate", "state", "updatedAt"]
+    },
+    {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "gateId": { "type": "string" },
+        "runId": { "type": "string" },
+        "scope": { "const": "parallel_batch" },
+        "pendingToolCalls": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "$ref": "#/$defs/PendingToolCall" }
+        },
+        "estimate": { "$ref": "#/$defs/SpendGateEstimate" },
+        "state": { "$ref": "#/$defs/SpendGateState" },
+        "reason": { "type": "string" },
+        "decision": { "$ref": "#/$defs/SpendGateDecision" },
+        "createdAt": { "type": "string", "format": "date-time" },
+        "decidedAt": { "type": "string", "format": "date-time" },
+        "updatedAt": { "type": "string", "format": "date-time" },
+        "failureReason": { "type": "string" }
+      },
+      "required": ["gateId", "scope", "pendingToolCalls", "estimate", "state", "updatedAt"]
+    },
+    {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "gateId": { "type": "string" },
+        "runId": { "type": "string" },
+        "scope": { "const": "workflow_run" },
+        "workflowRunId": { "type": "string" },
+        "pendingWorkflowPlan": { "$ref": "#/$defs/PendingWorkflowPlan" },
+        "estimate": { "$ref": "#/$defs/SpendGateEstimate" },
+        "state": { "$ref": "#/$defs/SpendGateState" },
+        "reason": { "type": "string" },
+        "decision": { "$ref": "#/$defs/SpendGateDecision" },
+        "createdAt": { "type": "string", "format": "date-time" },
+        "decidedAt": { "type": "string", "format": "date-time" },
+        "updatedAt": { "type": "string", "format": "date-time" },
+        "failureReason": { "type": "string" }
+      },
+      "required": ["gateId", "scope", "workflowRunId", "estimate", "state", "updatedAt"]
+    }
+  ]
+}