TaskAuthoringHttpContract.schema.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://das.local/schemas/task-authoring-http.schema.json",
  "title": "DAS Task Authoring HTTP Contract (Phase 84 strict)",
  "$comment": "Strict Phase 84 authoring wire. additionalProperties:false is the default on every structural object; debugInfo is the sole opaque-object exception. Legacy aliases (kind, properties, migration, sourceFingerprint, sequence, settings, children, applyPreset, addSequenceItem/moveSequenceItem/removeSequenceItem, addNode/removeNode/connectPorts/disconnectPorts/updateNodeConfig, change.op wrapper, {name,label} candidates, string diagnostic code/source, document-level diagnostics) are rejected. Schema and C++ validators in das/Core/TaskScheduler/src/TaskAuthoringContract.cpp must stay in lockstep.",
  "oneOf": [
    { "$ref": "#/$defs/AuthoringGetRequest" },
    { "$ref": "#/$defs/AuthoringApplyRequest" },
    { "$ref": "#/$defs/AuthoringCompileRequest" },
    { "$ref": "#/$defs/AuthoringGetSuccessResponse" },
    { "$ref": "#/$defs/AuthoringApplySuccessResponse" },
    { "$ref": "#/$defs/AuthoringCompileSuccessResponse" },
    { "$ref": "#/$defs/AuthoringErrorResponse" }
  ],
  "$defs": {
    "JsonValue": {
      "oneOf": [
        { "type": "null" },
        { "type": "boolean" },
        { "type": "number" },
        { "type": "string" },
        { "type": "array", "items": { "$ref": "#/$defs/JsonValue" } },
        {
          "type": "object",
          "additionalProperties": { "$ref": "#/$defs/JsonValue" }
        }
      ]
    },
    "Endpoint": {
      "type": "object",
      "required": ["method", "path"],
      "additionalProperties": false,
      "properties": {
        "method": { "const": "POST" },
        "path": {
          "type": "string",
          "pattern": "^/api/v1/scheduler/[^/]+/tasks/[0-9]+/authoring/(get|apply|compile)$"
        }
      }
    },
    "Diagnostic": {
      "type": "object",
      "required": ["severity", "message"],
      "additionalProperties": false,
      "properties": {
        "severity": {
          "type": "string",
          "enum": ["info", "warning", "error"]
        },
        "message": {
          "type": "string",
          "minLength": 1
        },
        "code": {
          "type": "integer",
          "$comment": "Optional DasResult integer code (decimal in logs)."
        },
        "path": {
          "type": "string",
          "$comment": "Opaque provider-authored path string."
        }
      }
    },
    "IconString": {
      "type": "string",
      "pattern": "^(https?://|[A-Za-z]:[\\\\/]|/|\\\\\\\\)",
      "$comment": "Provider-resolved absolute local path (Windows drive, POSIX, or UNC) or http(s) URL. Rejects relative paths, data: URIs, builtin icon names, and resource keys."
    },
    "FieldValidation": {
      "type": "object",
      "required": ["pattern", "message"],
      "additionalProperties": false,
      "properties": {
        "pattern": { "type": "string", "minLength": 1 },
        "message": { "type": "string", "minLength": 1 }
      }
    },
    "CandidateDescriptor": {
      "type": "object",
      "required": ["value", "label"],
      "additionalProperties": false,
      "properties": {
        "value": {
          "$comment": "Non-null JSON scalar (bool/number/string). Rejects null, object, array.",
          "oneOf": [
            { "type": "boolean" },
            { "type": "number" },
            { "type": "string" }
          ]
        },
        "label": { "type": "string", "minLength": 1 },
        "icon": { "$ref": "#/$defs/IconString" }
      }
    },
    "CommandApplyTemplate": {
      "type": "object",
      "required": ["kind", "payload"],
      "additionalProperties": false,
      "$comment": "AuthoringChange template without baseRevision; the client injects the current revision at submit time.",
      "properties": {
        "kind": { "$ref": "#/$defs/AuthoringChangeKind" },
        "payload": { "type": "object" }
      }
    },
    "CommandResult": {
      "type": "object",
      "required": ["commandId", "data"],
      "additionalProperties": false,
      "$comment": "D-92-17: invokeCommand 命令业务结果回传，可选（无业务结果的命令不带）；checkUpdate 用它返回 progressKey。",
      "properties": {
        "commandId": { "type": "string", "minLength": 1 },
        "data": { "$ref": "#/$defs/JsonValue" }
      }
    },
    "FieldDescriptor": {
      "type": "object",
      "required": ["name", "label", "valueType", "inputType", "value"],
      "additionalProperties": false,
      "properties": {
        "name": { "type": "string", "minLength": 1 },
        "label": { "type": "string", "minLength": 1 },
        "valueType": {
          "type": "integer",
          "enum": [0, 1, 2, 4, 8, 16, 32],
          "$comment": "0=int 1=uint 2=float 4=string 8=bool 16=jsonObject 32=jsonArray."
        },
        "inputType": {
          "type": "integer",
          "enum": [0, 1, 2, 3, 4, 5, 6, 7, 8, 9],
          "$comment": "0=plain 1=select 2=multiselect 3=long-input 4=region-select 5=filePath 6=directoryPath 7=markdown (readonly, release note/welcome; value may be markdown text or http(s) URL — URL triggers client-side fetch + RFC 7234 cache + markdown render). 8=time (24h \"HH:MM\" string; requires valueType=4). 9=button (name=commandId; apply template rides on the FieldDescriptor; disabled coexists with readonly; value is always null; requires valueType=4 and apply). The vocabulary is closed at 0-9: component-domain type words (taskRepositoryRef) never extend it — their typed dispatch rides on the optional \"type\" config type word instead."
        },
        "value": { "$ref": "#/$defs/JsonValue" },
        "type": {
          "type": "string",
          "minLength": 1,
          "$comment": "Optional manifest config type word carried verbatim on config-declared fields (e.g. \"int64\", \"object\", \"taskRepositoryRef\"). Graph editors dispatch on this word BEFORE entering the generic field control; the inputType pair stays within the official 0-8 vocabulary. For a taskRepositoryRef field the value is a plain repository entry id integer (or null when unset)."
        },
        "taskGuid": {
          "type": "string",
          "minLength": 1,
          "$comment": "Optional declared target task type (taskGuid) of a component-domain field — the manifest declaration names the task type the field binds to (e.g. a taskRepositoryRef pointing at one task type), so editors resolve the picker's entry source without a component→task reverse lookup. Engaged-only: emitted when the manifest declaration names one."
        },
        "description": { "type": "string" },
        "required": { "type": "boolean" },
        "readonly": { "type": "boolean" },
        "candidates": {
          "type": "array",
          "items": { "$ref": "#/$defs/CandidateDescriptor" },
          "$comment": "Only valid when inputType is select(1) or multiselect(2)."
        },
        "validation": { "$ref": "#/$defs/FieldValidation" },
        "icon": { "$ref": "#/$defs/IconString" },
        "apply": {
          "$ref": "#/$defs/CommandApplyTemplate",
          "$comment": "Button field (inputType=9) submit template riding on the FieldDescriptor itself."
        },
        "disabled": {
          "type": "boolean",
          "$comment": "Button field availability driven by backend state; absent means false. Pushed to clients via object-valued SSE setValue field increments ({\"disabled\": bool} merged into the matching fields[i])."
        },
        "confirmation": {
          "type": "string",
          "minLength": 1,
          "$comment": "Only allowed when apply is present."
        }
      },
      "allOf": [
        {
          "if": {
            "properties": {
              "inputType": { "const": 7 }
            },
            "required": ["inputType"]
          },
          "then": {
            "properties": {
              "readonly": { "const": true }
            },
            "required": ["readonly"]
          },
          "$comment": "inputType==7 (markdown) requires readonly==true (schema side; the C++ validator enforces the same)."
        },
        {
          "if": {
            "properties": {
              "inputType": { "const": 8 }
            },
            "required": ["inputType"]
          },
          "then": {
            "properties": {
              "valueType": { "const": 4 }
            },
            "required": ["valueType"]
          },
          "$comment": "inputType==8 (time) requires valueType==4 (string \"HH:MM\" 24h); the C++ validator enforces the same."
        },
        {
          "if": {
            "properties": {
              "inputType": { "const": 9 }
            },
            "required": ["inputType"]
          },
          "then": {
            "properties": {
              "valueType": { "const": 4 }
            },
            "required": ["valueType", "apply"]
          },
          "$comment": "inputType==9 (button) requires valueType==4 and the apply template; the C++ validator enforces the same."
        }
      ]
    },
    "FieldLayoutLeafField": {
      "type": "object",
      "required": ["fieldName"],
      "additionalProperties": false,
      "properties": {
        "fieldName": { "type": "string", "minLength": 1 }
      }
    },
    "FieldLayoutRow": {
      "type": "object",
      "required": ["row"],
      "additionalProperties": false,
      "$comment": "row 横向容器（与 section 纵向容器对称）。只在 section.entries 内合法（FieldLayoutSection.entries.items.oneOf 含本项；FieldLayoutNode oneOf 不含本项，顶层拒绝 rowOutsideSection）。",
      "properties": {
        "row": {
          "type": "array",
          "items": {
            "oneOf": [
              { "$ref": "#/$defs/FieldLayoutLeafField" },
              { "$ref": "#/$defs/FieldLayoutRow" }
            ]
          }
        }
      }
    },
    "FieldLayoutSection": {
      "type": "object",
      "required": ["id", "label", "entries"],
      "additionalProperties": false,
      "properties": {
        "id": { "type": "string", "minLength": 1 },
        "label": { "type": "string", "minLength": 1 },
        "description": { "type": "string" },
        "icon": { "$ref": "#/$defs/IconString" },
        "defaultExpanded": { "type": "boolean" },
        "entries": {
          "type": "array",
          "items": {
            "oneOf": [
              { "$ref": "#/$defs/FieldLayoutLeafField" },
              { "$ref": "#/$defs/FieldLayoutRow" }
            ]
          }
        }
      }
    },
    "FieldLayoutNode": {
      "oneOf": [
        { "$ref": "#/$defs/FieldLayoutLeafField" },
        { "$ref": "#/$defs/FieldLayoutSection" }
      ],
      "$comment": "顶层 layout node 不含 FieldLayoutRow — row 只能在 section.entries 内（validator 拒绝 rowOutsideSection）。命令不再是 layout 控件：按钮统一为 inputType=9 FieldDescriptor，叶子只有 {fieldName}。"
    },
    "EntryRef": {
      "type": "object",
      "required": ["entryId"],
      "additionalProperties": false,
      "properties": {
        "entryId": { "type": "integer", "minimum": 0 }
      }
    },
    "FieldContainer": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "fields": {
          "type": "array",
          "items": { "$ref": "#/$defs/FieldDescriptor" }
        },
        "fieldLayout": {
          "type": "array",
          "items": { "$ref": "#/$defs/FieldLayoutNode" }
        }
      }
    },
    "FormSequenceItem": {
      "type": "object",
      "required": ["id"],
      "additionalProperties": false,
      "properties": {
        "id": { "type": "string", "minLength": 1 },
        "componentGuid": { "type": "string" },
        "targetKind": {
          "type": "string",
          "enum": ["componentRef", "entryRef"]
        },
        "entryRef": { "$ref": "#/$defs/EntryRef" },
        "enabled": { "type": "boolean" },
        "debugInfo": { "type": "object" },
        "fields": {
          "type": "array",
          "items": { "$ref": "#/$defs/FieldDescriptor" }
        },
        "fieldLayout": {
          "type": "array",
          "items": { "$ref": "#/$defs/FieldLayoutNode" }
        }
      }
    },
    "GraphNode": {
      "type": "object",
      "required": ["id"],
      "additionalProperties": false,
      "$comment": "label/description/icon are presentation metadata: label follows the store-user-label > catalog-default-name priority chain (omitted when neither source provided one — clients fall back to the node id); description/icon merge from the matching actionCatalog entry.",
      "properties": {
        "id": { "type": "string", "minLength": 1 },
        "label": { "type": "string" },
        "description": { "type": "string" },
        "icon": { "$ref": "#/$defs/IconString" },
        "componentGuid": { "type": "string" },
        "targetKind": {
          "type": "string",
          "enum": ["componentRef", "entryRef"]
        },
        "entryRef": { "$ref": "#/$defs/EntryRef" },
        "debugInfo": { "type": "object" },
        "fields": {
          "type": "array",
          "items": { "$ref": "#/$defs/FieldDescriptor" }
        },
        "fieldLayout": {
          "type": "array",
          "items": { "$ref": "#/$defs/FieldLayoutNode" }
        },
        "ports": {
          "type": "array",
          "items": { "$ref": "#/$defs/GraphNodePort" }
        }
      }
    },
    "GraphNodePort": {
      "type": "object",
      "required": ["portId", "displayLabel", "portType", "direction", "category"],
      "additionalProperties": false,
      "$comment": "Node port projection (drag-link precheck data source): thin-map of the declared port surface — registry-declared static component ports (direction by inputs/outputs list membership) plus session-projected boundary ports on bound call nodes. The document itself carries no port declarations. portType is a free-form pass-through string; category is the Core-derived execution/data split (a port whose type is the \"signal\" protocol literal is execution, everything else is data). The client consumes both for soft filtering; compile stays the authoritative validation. The optional \"value\" key carries the raw node settings entry bound to an unconnected input data port (any JSON shape, emitted only when the settings carry a matching key). The optional \"connectedFrom\" key carries the backend-generated origin of a connected input data port.",
      "properties": {
        "portId": { "type": "string", "minLength": 1 },
        "displayLabel": { "type": "string" },
        "portType": { "type": "string" },
        "direction": { "type": "string", "enum": ["input", "output"] },
        "category": { "type": "string", "enum": ["execution", "data"] },
        "value": {
          "$comment": "Optional default-value channel for unconnected input data ports: the verbatim settings[portId] entry. Engaged-only on the wire — absent key, never an explicit null; never present on output or execution ports."
        },
        "connectedFrom": {
          "type": "string",
          "$comment": "Optional source-indicator channel for connected input data ports: \"sourceNodeId::sourcePortId\" of the first matching incoming edge, generated by the server projection (the UI never assembles it from the connections list). Engaged-only on the wire — absent key, never an explicit null; never present on output or execution ports."
        },
        "dynamic": {
          "type": "boolean",
          "$comment": "Optional dynamic-port marker for begin/end dynamic port merges: present only on projected dynamic ports so the client can offer deletion/rename where fixed manifest ports cannot. Engaged-only on the wire — absent key on static ports, never an explicit false."
        }
      }
    },
    "FormSequence": {
      "type": "object",
      "required": ["items"],
      "additionalProperties": false,
      "$comment": "List-editor view object. The three chrome keys (addButtonLabel/emptyStateHint/listTitle) document the list UI copy that used to be hardcoded client-side; they are engaged-only — present means a non-empty string, absent means the client falls back to its built-in defaults (existing projections without them stay byte-identical).",
      "properties": {
        "items": {
          "type": "array",
          "items": { "$ref": "#/$defs/FormSequenceItem" }
        },
        "addButtonLabel": {
          "type": "string",
          "minLength": 1,
          "$comment": "Optional add-button label; defaults to the client's built-in copy when omitted."
        },
        "emptyStateHint": {
          "type": "string",
          "minLength": 1,
          "$comment": "Optional empty-state hint; defaults to the client's built-in copy when omitted."
        },
        "listTitle": {
          "type": "string",
          "minLength": 1,
          "$comment": "Optional list title; defaults to the client's built-in copy when omitted."
        }
      }
    },
    "GraphDocument": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "nodes": {
          "type": "array",
          "items": { "$ref": "#/$defs/GraphNode" }
        },
        "connections": {
          "type": "array",
          "$comment": "Projected edges (the wire name for the document's edge list)."
        }
      }
    },
    "ActionCatalogEntry": {
      "type": "object",
      "required": ["actionId", "label"],
      "additionalProperties": false,
      "properties": {
        "actionId": { "type": "string", "minLength": 1 },
        "label": { "type": "string", "minLength": 1 },
        "description": { "type": "string" },
        "icon": { "$ref": "#/$defs/IconString" }
      }
    },
    "ActionCatalogGroup": {
      "type": "object",
      "required": ["id", "label", "actionIds"],
      "additionalProperties": false,
      "properties": {
        "id": { "type": "string", "minLength": 1 },
        "label": { "type": "string", "minLength": 1 },
        "description": { "type": "string" },
        "icon": { "$ref": "#/$defs/IconString" },
        "actionIds": {
          "type": "array",
          "items": { "type": "string", "minLength": 1 }
        }
      }
    },
    "ActionCatalog": {
      "type": "object",
      "required": ["entries"],
      "additionalProperties": false,
      "properties": {
        "entries": {
          "type": "array",
          "items": { "$ref": "#/$defs/ActionCatalogEntry" }
        },
        "groups": {
          "type": "array",
          "items": { "$ref": "#/$defs/ActionCatalogGroup" }
        }
      }
    },
    "PortDeclaration": {
      "type": "object",
      "required": ["id", "type", "direction"],
      "additionalProperties": false,
      "$comment": "Document-level declared port. id follows the node-port name field discipline (non-empty, at most 100 UTF-8 bytes, no leading '$') and must be unique within the section; label defaults to id when omitted; type is a builtin value type or a name registered in the same document's types[]; direction is the signature direction. The same-document closure of type is enforced by the C++ validator (a JSON schema cannot reference sibling array entries).",
      "properties": {
        "id": {
          "type": "string",
          "minLength": 1,
          "maxLength": 100,
          "pattern": "^[^$].*$",
          "$comment": "UTF-8 byte length cap and reserved-prefix ban, matching AddNodePort.portId."
        },
        "label": {
          "type": "string",
          "minLength": 1,
          "$comment": "Optional display label; defaults to id when omitted. Engaged-only: present means non-empty."
        },
        "type": {
          "type": "string",
          "minLength": 1,
          "$comment": "Nine builtin value types (bool/int/int64/float/double/string/image/base/component) or a name registered in the same document's types[]. Cross-document/plugin names are rejected by the C++ validator."
        },
        "direction": {
          "type": "string",
          "enum": ["input", "output"]
        }
      }
    },
    "TypeDeclaration": {
      "type": "object",
      "required": ["name"],
      "additionalProperties": false,
      "$comment": "Document-level registered type. name follows the node-port name field discipline (non-empty, at most 100 UTF-8 bytes, no leading '$') and must be unique within the document (a registration-name ambiguity is a port-surface ambiguity). compatibleWith is scoped to builtin value types x names registered in the same document — cross-plugin references are rejected.",
      "properties": {
        "name": {
          "type": "string",
          "minLength": 1,
          "maxLength": 100,
          "pattern": "^[^$].*$"
        },
        "compatibleWith": {
          "type": "array",
          "items": { "type": "string", "minLength": 1 },
          "$comment": "Optional; each entry must be a builtin value type or a name registered in the same document's types[] (first-stage scope: own types x builtins)."
        }
      }
    },
    "AuthoringDocument": {
      "type": "object",
      "required": ["contractVersion", "viewKind", "revision"],
      "additionalProperties": false,
      "properties": {
        "contractVersion": { "const": 1 },
        "viewKind": {
          "type": "string",
          "enum": ["formSequence", "graph"]
        },
        "revision": { "type": "integer", "minimum": 0 },
        "fields": {
          "type": "array",
          "items": { "$ref": "#/$defs/FieldDescriptor" }
        },
        "fieldLayout": {
          "type": "array",
          "items": { "$ref": "#/$defs/FieldLayoutNode" }
        },
        "formSequence": { "$ref": "#/$defs/FormSequence" },
        "graph": { "$ref": "#/$defs/GraphDocument" },
        "actionCatalog": { "$ref": "#/$defs/ActionCatalog" },
        "ports": {
          "type": "array",
          "items": { "$ref": "#/$defs/PortDeclaration" },
          "$comment": "Document-level port declaration section (engaged-only: absent key is the norm for existing documents; a pure manifest component document stays valid without it)."
        },
        "types": {
          "type": "array",
          "items": { "$ref": "#/$defs/TypeDeclaration" },
          "$comment": "Document-level type registration section (engaged-only). Registered names extend the ports[].type vocabulary of the SAME document only."
        },
        "viewData": { "type": "object" }
      }
    },
    "AuthoringChangeKind": {
      "type": "string",
      "enum": [
        "setValue",
        "invokeCommand",
        "convertView",
        "addFormSequenceItem",
        "moveFormSequenceItem",
        "removeFormSequenceItem",
        "addGraphNode",
        "removeGraphNode",
        "connectGraphPorts",
        "disconnectGraphPorts",
        "uiEvent",
        "moveGraphNode",
        "removeGraphNodes",
        "moveGraphNodes",
        "renameGraphNode",
        "addNodePort",
        "removeNodePort",
        "renameNodePort"
      ]
    },
    "GraphConnectionEndpoints": {
      "type": "object",
      "required": ["fromNodeId", "fromPortId", "toNodeId", "toPortId"],
      "additionalProperties": false,
      "$comment": "Four-key connection endpoint shape shared by connect/disconnect payloads and the removeGraphNodes batch connections[].",
      "properties": {
        "fromNodeId": { "type": "string", "minLength": 1 },
        "fromPortId": { "type": "string", "minLength": 1 },
        "toNodeId": { "type": "string", "minLength": 1 },
        "toPortId": { "type": "string", "minLength": 1 }
      }
    },
    "MoveGraphNode": {
      "type": "object",
      "required": ["nodeId", "position"],
      "additionalProperties": false,
      "$comment": "Node layout coordinates ride the document-level viewData partition; a successful moveGraphNode does not bump the semantic revision.",
      "properties": {
        "nodeId": { "type": "string", "minLength": 1 },
        "position": {
          "type": "object",
          "required": ["x", "y"],
          "additionalProperties": false,
          "properties": {
            "x": { "type": "number" },
            "y": { "type": "number" }
          }
        }
      }
    },
    "RemoveGraphNodes": {
      "type": "object",
      "additionalProperties": false,
      "$comment": "Atomic batch node removal: validate-all-then-mutate — any NodeNotFound/EdgeNotFound rejects the whole batch (no partial mutation), success bumps the semantic revision exactly once. connections[] names extra edges to drop while keeping their endpoint nodes (connection-only batches are valid).",
      "properties": {
        "nodeIds": {
          "type": "array",
          "minItems": 1,
          "items": { "type": "string", "minLength": 1 }
        },
        "connections": {
          "type": "array",
          "items": { "$ref": "#/$defs/GraphConnectionEndpoints" }
        }
      },
      "anyOf": [
        { "required": ["nodeIds"] },
        { "required": ["connections"] }
      ]
    },
    "MoveGraphNodes": {
      "type": "object",
      "required": ["moves"],
      "additionalProperties": false,
      "$comment": "Batch coordinate commit onto the document-level viewData partition; a successful moveGraphNodes does not bump the semantic revision (same exemption family as moveGraphNode).",
      "properties": {
        "moves": {
          "type": "array",
          "minItems": 1,
          "items": {
            "type": "object",
            "required": ["nodeId", "position"],
            "additionalProperties": false,
            "properties": {
              "nodeId": { "type": "string", "minLength": 1 },
              "position": {
                "type": "object",
                "required": ["x", "y"],
                "additionalProperties": false,
                "properties": {
                  "x": { "type": "number" },
                  "y": { "type": "number" }
                }
              }
            }
          }
        }
      }
    },
    "RenameGraphNode": {
      "type": "object",
      "required": ["nodeId", "label"],
      "additionalProperties": false,
      "$comment": "User-authored display label on the store node. Pure presentation: the node id, viewData.positions keys and edge endpoints are untouched and addressing never uses the label. A successful rename bumps the semantic revision exactly once.",
      "properties": {
        "nodeId": { "type": "string", "minLength": 1 },
        "label": {
          "type": "string",
          "minLength": 1,
          "maxLength": 200,
          "$comment": "UTF-8 byte length cap (defensive upper bound against unbounded text entering the persisted store)."
        }
      }
    },
    "AddNodePort": {
      "type": "object",
      "required": ["nodeId", "name", "direction", "valueType"],
      "additionalProperties": false,
      "$comment": "Add one port entry to a document's port list — the standard vocabulary for editing a port list in any authoring document (the same family MaaPI's task list uses). The graph document stores no port partitions, so on a graph only begin/end boundary nodes accept it (their port list lives in the node settings); any other node's dynamic ports belong to that node's own authoring document and are computed live from it (the legacy repository-bound call-node port materialization channel is retired) — adding there rejects with a pointer to the owning document. The direction gate (Begin accepts input, End accepts output — the signature direction), '$'-prefixed and duplicate names are enforced in the Core dispatch layer. The port id IS the port name (boundary single-id form); a successful add bumps the semantic revision exactly once.",
      "properties": {
        "nodeId": { "type": "string", "minLength": 1 },
        "name": {
          "type": "string",
          "minLength": 1,
          "maxLength": 100,
          "$comment": "UTF-8 byte length cap, matching RenameGraphNode's defensive upper bound."
        },
        "direction": {
          "type": "string",
          "enum": ["input", "output"],
          "$comment": "Signature direction (see $comment above); the wire projection flips it to the anchor side."
        },
        "valueType": {
          "type": "string",
          "enum": [
            "bool",
            "int",
            "int64",
            "float",
            "double",
            "string",
            "image",
            "base",
            "component"
          ],
          "$comment": "Full type vocabulary of the boundary signature (bool/int family/float family/string/image/Base/Component)."
        },
        "portId": {
          "type": "string",
          "minLength": 1,
          "maxLength": 100,
          "pattern": "^[^$].*$",
          "$comment": "Optional explicit port id. The boundary single-id form makes the port id and its name one channel: when present it must equal name (a divergent value rejects); omitting it is equivalent to passing name. The historical call-node materialization channel (the child graph's boundary port id as a stable value-plane key) is retired."
        }
      }
    },
    "RemoveNodePort": {
      "type": "object",
      "required": ["nodeId", "portId"],
      "additionalProperties": false,
      "$comment": "Remove one dynamic port declaration by its stable partition id. Static manifest ports (not in the partition, e.g. the End '值' port) reject; edges referencing the port id cascade-delete inside the same atomic change. A successful remove bumps the semantic revision exactly once.",
      "properties": {
        "nodeId": { "type": "string", "minLength": 1 },
        "portId": { "type": "string", "minLength": 1 }
      }
    },
    "RenameNodePort": {
      "type": "object",
      "required": ["nodeId", "portId", "name"],
      "additionalProperties": false,
      "$comment": "Change a dynamic port's display name only: the stable port id and the edge coordinates referencing it are untouched (addressing never uses the name). Name rules match AddNodePort. A successful rename bumps the semantic revision exactly once.",
      "properties": {
        "nodeId": { "type": "string", "minLength": 1 },
        "portId": { "type": "string", "minLength": 1 },
        "name": {
          "type": "string",
          "minLength": 1,
          "maxLength": 100
        }
      }
    },
    "SetValueTarget": {
      "oneOf": [
        {
          "type": "object",
          "required": ["kind"],
          "additionalProperties": false,
          "properties": { "kind": { "const": "document" } }
        },
        {
          "type": "object",
          "required": ["kind", "id"],
          "additionalProperties": false,
          "properties": {
            "kind": { "const": "formSequenceItem" },
            "id": { "type": "string", "minLength": 1 }
          }
        },
        {
          "type": "object",
          "required": ["kind", "id"],
          "additionalProperties": false,
          "properties": {
            "kind": { "const": "graphNode" },
            "id": { "type": "string", "minLength": 1 }
          }
        }
      ]
    },
    "AuthoringChangePayload": {
      "oneOf": [
        {
          "type": "object",
          "required": ["target", "fieldName", "value"],
          "additionalProperties": false,
          "properties": {
            "target": { "$ref": "#/$defs/SetValueTarget" },
            "fieldName": { "type": "string", "minLength": 1 },
            "value": { "$ref": "#/$defs/JsonValue" }
          }
        },
        {
          "type": "object",
          "required": ["commandId"],
          "additionalProperties": false,
          "properties": {
            "commandId": { "type": "string", "minLength": 1 }
          }
        },
        {
          "type": "object",
          "required": ["targetViewKind"],
          "additionalProperties": false,
          "properties": {
            "targetViewKind": {
              "type": "string",
              "enum": ["formSequence", "graph"]
            }
          }
        },
        {
          "type": "object",
          "required": ["actionId"],
          "additionalProperties": false,
          "properties": {
            "actionId": { "type": "string", "minLength": 1 },
            "insertionIndex": { "type": "integer", "minimum": 0 }
          }
        },
        {
          "type": "object",
          "required": ["formSequenceItemId", "destinationIndex"],
          "additionalProperties": false,
          "properties": {
            "formSequenceItemId": { "type": "string", "minLength": 1 },
            "destinationIndex": { "type": "integer", "minimum": 0 }
          }
        },
        {
          "type": "object",
          "required": ["formSequenceItemId"],
          "additionalProperties": false,
          "properties": {
            "formSequenceItemId": { "type": "string", "minLength": 1 }
          }
        },
        {
          "type": "object",
          "required": ["actionId"],
          "additionalProperties": false,
          "properties": {
            "actionId": { "type": "string", "minLength": 1 }
          }
        },
        {
          "type": "object",
          "required": ["nodeId"],
          "additionalProperties": false,
          "properties": {
            "nodeId": { "type": "string", "minLength": 1 }
          }
        },
        {
          "type": "object",
          "required": [
            "fromNodeId",
            "fromPortId",
            "toNodeId",
            "toPortId"
          ],
          "additionalProperties": false,
          "properties": {
            "fromNodeId": { "type": "string", "minLength": 1 },
            "fromPortId": { "type": "string", "minLength": 1 },
            "toNodeId": { "type": "string", "minLength": 1 },
            "toPortId": { "type": "string", "minLength": 1 }
          }
        },
        { "$ref": "#/$defs/MoveGraphNode" },
        { "$ref": "#/$defs/RemoveGraphNodes" },
        { "$ref": "#/$defs/MoveGraphNodes" },
        { "$ref": "#/$defs/RenameGraphNode" },
        { "$ref": "#/$defs/AddNodePort" },
        { "$ref": "#/$defs/RemoveNodePort" },
        { "$ref": "#/$defs/RenameNodePort" }
      ]
    },
    "AuthoringApplyRequest": {
      "type": "object",
      "required": ["baseRevision", "changes"],
      "additionalProperties": false,
      "$comment": "Batch atomic apply: wire is {baseRevision, changes:[{kind,payload},...]}; the backend applies the whole batch all-or-nothing (a mid-batch failure mutates nothing and persists nothing). Legacy single-change top-level kind/payload shape is retired (rejected).",
      "properties": {
        "endpoint": { "$ref": "#/$defs/Endpoint" },
        "componentContext": {
          "type": "boolean",
          "$comment": "Optional component-context flag (default false): when the UI drills into a component from inside a graph, the projector gates component-only projections on it. Absent = standalone editing, byte-identical legacy behavior."
        },
        "componentGuid": {
          "type": "string",
          "$comment": "Optional component document identity (e.g. a graph begin/end boundary component GUID): routes the apply to that component's own authoring session within the host graph addressed by the URL. Absent = the host document's own apply. Never a node-scoped nodeId key."
        },
        "baseRevision": { "type": "integer", "minimum": 0 },
        "changes": {
          "type": "array",
          "minItems": 1,
          "maxItems": 256,
          "items": {
            "type": "object",
            "required": ["kind", "payload"],
            "additionalProperties": false,
            "properties": {
              "kind": { "$ref": "#/$defs/AuthoringChangeKind" },
              "payload": { "type": "object" }
            }
          }
        }
      }
    },
    "AuthoringGetRequest": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "endpoint": { "$ref": "#/$defs/Endpoint" },
        "componentContext": {
          "type": "boolean",
          "$comment": "Optional component-context flag (default false): when the UI drills into a component from inside a graph, the projector gates component-only projections on it. Same key, same semantics as the Apply side. Absent = standalone editing, byte-identical legacy behavior."
        },
        "componentGuid": {
          "type": "string",
          "$comment": "Optional component document identity (e.g. a graph begin/end boundary component GUID): routes the get to that component's own authoring document within the host graph addressed by the URL. Same key, same semantics as the Apply side. Absent = the host document's own get."
        }
      }
    },
    "AuthoringCompileRequest": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "endpoint": { "$ref": "#/$defs/Endpoint" }
      }
    },
    "HttpSuccessEnvelope": {
      "type": "object",
      "required": ["code", "message", "data"],
      "additionalProperties": false,
      "properties": {
        "code": { "const": 0 },
        "message": { "type": "string" },
        "data": { "$ref": "#/$defs/JsonValue" }
      }
    },
    "AuthoringGetSuccessResponse": {
      "allOf": [
        { "$ref": "#/$defs/HttpSuccessEnvelope" },
        {
          "type": "object",
          "properties": {
            "data": {
              "type": "object",
              "required": ["diagnostics"],
              "additionalProperties": false,
              "properties": {
                "document": { "$ref": "#/$defs/AuthoringDocument" },
                "diagnostics": {
                  "type": "array",
                  "items": { "$ref": "#/$defs/Diagnostic" }
                }
              }
            }
          }
        }
      ]
    },
    "AuthoringApplySuccessResponse": {
      "allOf": [
        { "$ref": "#/$defs/HttpSuccessEnvelope" },
        {
          "type": "object",
          "properties": {
            "data": {
              "type": "object",
              "required": ["acceptedProperties", "document", "diagnostics"],
              "additionalProperties": false,
              "properties": {
                "acceptedProperties": { "$ref": "#/$defs/JsonValue" },
                "document": { "$ref": "#/$defs/AuthoringDocument" },
                "diagnostics": {
                  "type": "array",
                  "items": { "$ref": "#/$defs/Diagnostic" }
                },
                "commandResult": { "$ref": "#/$defs/CommandResult" }
              },
              "$comment": "On success document.revision must stay within [baseRevision, baseRevision + bumping-change count] (each semantic change bumps +1; moveGraphNode/moveGraphNodes bump 0 — checked by the C++ validator). A failed batch keeps document.revision == baseRevision. commandResult is optional (D-92-17); responses without business results omit it."
            }
          }
        }
      ]
    },
    "AuthoringCompileSuccessResponse": {
      "allOf": [
        { "$ref": "#/$defs/HttpSuccessEnvelope" },
        {
          "type": "object",
          "properties": {
            "data": {
              "type": "object",
              "required": ["compile", "diagnostics"],
              "additionalProperties": false,
              "properties": {
                "compile": { "$ref": "#/$defs/JsonValue" },
                "diagnostics": {
                  "type": "array",
                  "items": { "$ref": "#/$defs/Diagnostic" }
                }
              }
            }
          }
        }
      ]
    },
    "AuthoringErrorKind": {
      "type": "string",
      "enum": [
        "taskNotFound",
        "taskUnavailable",
        "capabilityMissing",
        "revisionConflict",
        "authoringValidationFailed",
        "pluginFailure",
        "componentFailure",
        "persistenceFailure",
        "invalidRequest"
      ]
    },
    "AuthoringErrorResponse": {
      "type": "object",
      "required": ["code", "message", "data"],
      "additionalProperties": false,
      "properties": {
        "code": { "type": "integer", "not": { "const": 0 } },
        "message": { "type": "string" },
        "data": {
          "type": "object",
          "required": ["errorKind"],
          "additionalProperties": false,
          "properties": {
            "errorKind": { "$ref": "#/$defs/AuthoringErrorKind" },
            "diagnostics": {
              "type": "array",
              "items": { "$ref": "#/$defs/Diagnostic" }
            },
            "baseRevision": { "type": "integer", "minimum": 0 },
            "currentRevision": { "type": "integer", "minimum": 0 }
          }
        }
      }
    }
  }
}