PaperClipAI/packages/paperclip-runner/protocol/schemas/semantic-tool.schema.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://paperclip.dev/schemas/prp/v1/semantic-tool.schema.json",
  "title": "PRP provider-neutral semantic tool envelope",
  "type": "object",
  "required": [
    "schema",
    "schemaVersion",
    "phase",
    "operationId",
    "callId",
    "correlation",
    "idempotencyKey",
    "content"
  ],
  "properties": {
    "schema": { "const": "paperclip.prp.semantic_tool.v1" },
    "schemaVersion": { "const": 1 },
    "phase": { "enum": ["input", "result", "reconciled"] },
    "operationId": { "$ref": "#/$defs/stableId" },
    "callId": { "$ref": "#/$defs/stableId" },
    "correlation": {
      "type": "object",
      "required": ["runId", "normalizedSessionId", "turnId", "itemId"],
      "properties": {
        "runId": { "$ref": "#/$defs/stableId" },
        "normalizedSessionId": { "$ref": "#/$defs/stableId" },
        "turnId": { "$ref": "#/$defs/stableId" },
        "itemId": { "$ref": "#/$defs/stableId" },
        "requestId": { "$ref": "#/$defs/stableId" }
      },
      "additionalProperties": true
    },
    "idempotencyKey": {
      "type": ["string", "null"],
      "minLength": 1,
      "maxLength": 240
    },
    "content": { "$ref": "#/$defs/safeContent" },
    "outcome": {
      "enum": ["succeeded", "denied", "conflict", "duplicate", "unavailable", "failed"]
    },
    "code": { "$ref": "#/$defs/stableCode" },
    "retryable": { "type": "boolean" },
    "authorizationBoundary": {
      "enum": ["company", "actor", "active_task", "grant", "governed_action", "lock", "revision"]
    },
    "operationReceiptId": { "$ref": "#/$defs/stableId" },
    "auditReceiptId": { "$ref": "#/$defs/stableId" },
    "currentRevision": {
      "oneOf": [
        { "type": "integer", "minimum": 0 },
        { "$ref": "#/$defs/stableId" }
      ]
    },
    "duplicateOfReceiptId": { "$ref": "#/$defs/stableId" },
    "artifactRefs": {
      "type": "array",
      "items": {
        "allOf": [
          { "$ref": "#/$defs/safeReference" },
          {
            "type": "object",
            "properties": { "kind": { "enum": ["artifact", "work_product"] } }
          }
        ]
      },
      "uniqueItems": true
    },
    "targets": {
      "type": "array",
      "items": { "$ref": "#/$defs/immutableTarget" },
      "uniqueItems": true
    },
    "causalRefs": {
      "type": "array",
      "items": { "$ref": "#/$defs/safeReference" },
      "uniqueItems": true
    }
  },
  "allOf": [
    {
      "if": {
        "properties": { "phase": { "enum": ["result", "reconciled"] } },
        "required": ["phase"]
      },
      "then": {
        "required": [
          "outcome",
          "code",
          "retryable",
          "authorizationBoundary",
          "operationReceiptId"
        ]
      }
    }
  ],
  "additionalProperties": true,
  "$defs": {
    "stableId": {
      "type": "string",
      "minLength": 1,
      "maxLength": 240,
      "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$"
    },
    "stableCode": {
      "type": "string",
      "minLength": 1,
      "maxLength": 160,
      "pattern": "^[a-z][a-z0-9_.:-]*$"
    },
    "safeContent": {
      "type": "object",
      "required": ["digest", "redactionDisposition", "references"],
      "properties": {
        "digest": {
          "type": "string",
          "pattern": "^sha256:[a-f0-9]{64}$"
        },
        "redactionDisposition": {
          "enum": ["digest_only", "allowlisted_references", "redacted"]
        },
        "references": {
          "type": "array",
          "items": { "$ref": "#/$defs/safeReference" },
          "uniqueItems": true
        }
      },
      "additionalProperties": true
    },
    "safeReference": {
      "type": "object",
      "required": ["kind", "id"],
      "properties": {
        "kind": {
          "enum": [
            "task",
            "document_revision",
            "interaction",
            "approval",
            "decision",
            "artifact",
            "work_product",
            "wake",
            "monitor",
            "audit",
            "operation"
          ]
        },
        "id": { "$ref": "#/$defs/stableId" }
      },
      "additionalProperties": true
    },
    "immutableTarget": {
      "type": "object",
      "required": ["kind", "id", "immutable"],
      "properties": {
        "kind": { "enum": ["document_revision", "interaction", "approval", "decision"] },
        "id": { "$ref": "#/$defs/stableId" },
        "immutable": { "const": true },
        "revisionId": { "$ref": "#/$defs/stableId" },
        "decisionId": { "$ref": "#/$defs/stableId" }
      },
      "additionalProperties": true
    }
  }
}