{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://tekcapitol.com/schema/write-intent/v1/write-intent.v1.json",
  "title": "TC Protect Write Intent v1",
  "description": "Metadata-only package the orchestrator emits to check_write before a mutating side effect. TekCapitol does not query the system of record.",
  "type": "object",
  "additionalProperties": false,
  "required": ["schemaVersion", "system", "objectType", "objectRef", "intendedChanges"],
  "properties": {
    "schemaVersion": {
      "const": "write_intent.v1"
    },
    "system": {
      "type": "string",
      "description": "System of record id, e.g. Salesforce, SAP, Snowflake."
    },
    "objectType": {
      "type": "string",
      "description": "Object / entity type, e.g. Opportunity, Contract."
    },
    "objectRef": {
      "type": "string",
      "description": "Record id in the system of record."
    },
    "intendedChanges": {
      "type": "array",
      "minItems": 1,
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": ["field", "newValue"],
        "properties": {
          "field": { "type": "string" },
          "newValue": {}
        }
      }
    },
    "authority": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "value": {},
        "fields": { "type": "object" },
        "bindings": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "field": { "type": "string" },
              "agentValue": {},
              "authorityValue": {}
            }
          }
        },
        "source": {
          "type": "string",
          "description": "Independent SoR id. Prefer billing_sor / crm_entitlement, not prompt or agent_spec."
        },
        "found": { "type": "boolean" },
        "checkedAt": {
          "type": "string",
          "description": "ISO-8601 time the orchestrator read authority (not the Salesforce SystemModstamp alone)."
        },
        "maxAgeMs": {
          "type": "integer",
          "minimum": 0,
          "description": "Freshness window for checkedAt."
        },
        "stalePolicy": {
          "type": "string",
          "enum": ["warn", "pause", "block"],
          "default": "warn"
        }
      }
    },
    "freshness": {
      "type": "object",
      "additionalProperties": false,
      "description": "Optional lightweight SoR verification signals emitted by the orchestrator.",
      "properties": {
        "recordVersion": {
          "type": "string",
          "description": "e.g. Salesforce SystemModstamp or row version."
        },
        "stampType": {
          "type": "string",
          "description": "e.g. SystemModstamp, hash, etag."
        },
        "hash": {
          "type": "string",
          "description": "Optional hash of critical fields known to the orchestrator."
        }
      }
    },
    "workflowId": { "type": "string" },
    "agentIdentity": { "type": "string" },
    "runId": { "type": "string" },
    "policyTags": {
      "type": "array",
      "items": { "type": "string" }
    },
    "requireApproval": {
      "type": "boolean",
      "description": "If true, check_write returns decision=pause (HITL) even when values match."
    },
    "idempotencyKey": { "type": "string" },
    "requiredControls": {
      "type": "array",
      "description": "Optional per-request override of required control IDs. Prefer workflow registry required_controls for production.",
      "items": { "type": "string" }
    },
    "controlEvidence": {
      "type": "array",
      "description": "Caller-supplied enterprise control results (Okta, ServiceNow, fraud, policy engines). TekCapitol evaluates; it does not query those systems.",
      "items": {
        "type": "object",
        "additionalProperties": true,
        "required": ["controlId", "result"],
        "properties": {
          "controlId": { "type": "string" },
          "source": { "type": "string" },
          "result": {
            "type": "string",
            "description": "PASS | FAIL | UNKNOWN | PENDING"
          },
          "checkedAt": { "type": "string", "description": "ISO-8601" },
          "evidenceRef": { "type": "string" }
        }
      }
    },
    "writeIntentEnvelope": {
      "type": "object",
      "description": "Signed attestation envelope included on check_write for identity, workflow, and authority revalidation. TekCapitol verifies signatures server-side and compares attested fields to the envelope payload.",
      "additionalProperties": false,
      "required": ["run_id", "agent", "workflow", "actor", "write", "context", "signature"],
      "properties": {
        "run_id": { "type": "string" },
        "agent": {
          "type": "object",
          "additionalProperties": false,
          "required": ["agent_id", "agent_version", "service_account", "identity_provider", "token_issuer"],
          "properties": {
            "agent_id": { "type": "string" },
            "agent_version": { "type": "string" },
            "service_account": { "type": "string" },
            "identity_provider": { "type": "string" },
            "token_issuer": { "type": "string" }
          }
        },
        "workflow": {
          "type": "object",
          "additionalProperties": false,
          "required": ["workflow_id", "workflow_version", "orchestrator", "deployment_id", "definition_hash"],
          "properties": {
            "workflow_id": { "type": "string" },
            "workflow_version": { "type": "string" },
            "orchestrator": { "type": "string" },
            "deployment_id": { "type": "string" },
            "definition_hash": { "type": "string" }
          }
        },
        "actor": {
          "type": "object",
          "additionalProperties": false,
          "required": ["on_behalf_of"],
          "properties": {
            "on_behalf_of": { "type": "string" }
          }
        },
        "write": {
          "type": "object",
          "additionalProperties": false,
          "required": ["system", "object", "record_id", "operation", "fields"],
          "properties": {
            "system": { "type": "string" },
            "object": { "type": "string" },
            "record_id": { "type": "string" },
            "operation": { "type": "string" },
            "fields": {
              "type": "object",
              "description": "Field changes intended for this write operation. Metadata-only by default; do not store raw prompts or sensitive payloads in TekCapitol unless explicitly configured.",
              "additionalProperties": {}
            }
          }
        },
        "context": {
          "type": "object",
          "additionalProperties": false,
          "required": ["approval_id", "policy_version", "timestamp"],
          "properties": {
            "approval_id": { "type": "string" },
            "approval_expires_at": { "type": "string" },
            "approval_checked_at": { "type": "string" },
            "policy_version": { "type": "string" },
            "timestamp": { "type": "string" }
          }
        },
        "signature": {
          "type": "string",
          "description": "Preferred: JWT (JWS compact) signature. Also supports legacy hex HMAC-SHA256 over canonicalized envelope payload. Server validates signature and attested claims.",
          "minLength": 1
        }
      }
    }
  }
}