{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://tiffany.systems/api/schema/operation-envelope.schema.json",
  "title": "OperationEnvelope",
  "description": "One proposed machine operation against the canonical record model. This is a contract, not a live endpoint: nothing on this site accepts an envelope over the network, and no actor holds a delegation that would let one execute. Unknown fields fail closed, because a field the contract does not model may be the one carrying the claim.",
  "x-schema-version": "1.0.0",
  "type": "object",
  "additionalProperties": false,
  "required": ["operation_id", "idempotency_key", "actor", "delegation_id", "capability", "operation", "target", "environment", "mode", "policy_version", "submitted_at"],
  "properties": {
    "operation_id": {"type": "string", "pattern": "^op-[a-z0-9-]+$"},
    "idempotency_key": {"type": "string", "minLength": 8, "description": "Retrying with the same key and the same payload returns the original result. The same key with a different payload is a collision and stops."},
    "actor": {"type": "object", "additionalProperties": false, "required": ["id", "type"], "properties": {"id": {"type": "string"}, "type": {"type": "string", "enum": ["HUMAN", "ORGANISATION", "SOFTWARE_AGENT", "TIFFANY"]}}},
    "delegation_id": {"type": "string"},
    "capability": {"type": "string", "enum": ["OBSERVE", "PREPARE_DRAFT", "PROPOSE_UPDATE", "ATTACH_APPROVED_EVIDENCE", "VALIDATE", "REQUEST_PUBLICATION", "EXECUTE_REVERSIBLE", "PUBLISH_APPROVED", "SUPERSEDE_APPROVED", "WITHDRAW_APPROVED", "RELEASE_APPROVED_SOFTWARE"]},
    "operation": {"type": "string", "enum": ["READ", "DRAFT", "PROPOSE", "ATTACH_EVIDENCE", "VALIDATE", "REQUEST_PUBLICATION", "PUBLISH", "SUPERSEDE", "WITHDRAW", "RELEASE_SOFTWARE"]},
    "operation_class": {"type": ["string", "null"], "enum": ["TIFFANY_PROFILE", "RESOURCE", "SYSTEM_MODULE", "CAPABILITY", "USE_CASE", "ARCHITECTURE", "SCHEMATIC", "EVIDENCE", "DOCUMENTATION", "API_METADATA", "RELEASE", "DOWNLOAD", "DATASET", "STATUS_INCIDENT", null]},
    "target": {"type": "object", "additionalProperties": false, "required": ["resource_id", "resource_type"], "properties": {"resource_id": {"type": "string"}, "resource_type": {"type": "string"}}},
    "environment": {"type": "string", "enum": ["SHADOW", "PREVIEW", "PRODUCTION"]},
    "mode": {"type": "string", "enum": ["SHADOW", "LIVE"], "description": "SHADOW produces a full result with no effect. LIVE requires an active delegation covering the capability, the target and the environment."},
    "expected_current_version": {"type": ["string", "null"], "description": "Required for any consequential mutation. A mismatch parks the operation as a conflict; consequential meaning is never auto-merged."},
    "expected_current_digest": {"type": ["string", "null"]},
    "proposed_record": {"type": ["object", "null"], "description": "The canonical record being proposed, satisfying the portal contract."},
    "rationale": {"type": ["string", "null"], "description": "Human-readable reason. Carries no weight in any gate: rationale explains a decision, it never influences one."},
    "evidence_refs": {"type": ["array", "null"], "items": {"type": "string"}},
    "publication_decision": {"type": ["object", "null"], "additionalProperties": false, "properties": {"decision_ref": {"type": "string"}, "authority": {"type": "string"}, "decided_at": {"type": "string"}}},
    "classification": {"type": ["string", "null"]},
    "preconditions": {"type": ["array", "null"], "items": {"type": "string"}},
    "policy_version": {"type": "string", "description": "Must equal the policy version in force. Supplied for comparison, never to select which rules apply."},
    "submitted_at": {"type": "string"},
    "audit_event_id": {"type": ["string", "null"]}
  }
}