{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://structureclerk.ca/spec/authority-decision-v0.1.schema.json",
  "title": "Authority Decision Contract v0.1",
  "description": "Request and response contract for an advisory authority decision: whether an AI agent may execute an action, in a given jurisdiction and sector, at a given autonomy level. Decisions are advisory — the issuer decides, the caller's infrastructure enforces.",
  "license": "MIT",
  "version": "0.1",
  "$defs": {
    "primitive": {
      "type": "string",
      "enum": ["ALLOW", "APPROVE", "DENY", "ESCALATE"],
      "description": "ALLOW: the agent may act alone. APPROVE: the agent prepares, a human approves. DENY: reserved for humans. ESCALATE: confidence below the doubt threshold, route to human review."
    },
    "request": {
      "type": "object",
      "required": ["agent", "action", "context"],
      "properties": {
        "agent": {
          "type": "object",
          "required": ["id", "autonomy_level"],
          "properties": {
            "id": { "type": "string", "minLength": 1, "maxLength": 200 },
            "autonomy_level": {
              "type": "integer",
              "minimum": 1,
              "maximum": 3,
              "description": "1 supervised, 2 augmented, 3 autonomous. Level 1 downgrades a final ALLOW to APPROVE."
            }
          }
        },
        "action": {
          "type": "object",
          "required": ["type"],
          "properties": {
            "type": {
              "type": "string",
              "maxLength": 100,
              "pattern": "^[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*)+$",
              "description": "Dotted lowercase action type, e.g. payment.execute or read.contract. An unrecognized type escalates rather than being guessed at."
            },
            "amount": { "type": "number", "minimum": 0 },
            "currency": { "type": "string", "pattern": "^[A-Za-z]{3}$" },
            "data_categories": {
              "type": "array",
              "maxItems": 20,
              "items": { "type": "string" },
              "description": "e.g. personal, health, biometric, minors, financial."
            },
            "irreversible": { "type": "boolean", "default": false }
          }
        },
        "context": {
          "type": "object",
          "required": ["jurisdictions", "sector"],
          "properties": {
            "jurisdictions": {
              "type": "array",
              "maxItems": 10,
              "items": { "type": "string" },
              "description": "Jurisdiction codes, e.g. QC, EU, FR. Unknown codes produce a warning, not an error."
            },
            "sector": { "type": "string", "minLength": 1, "maxLength": 100 }
          }
        },
        "org_profile_id": {
          "type": "string",
          "format": "uuid",
          "description": "Optional. Modulates the decision with an organisation's assessed posture. Requires an authenticated, entitled session that owns the profile; rejected on unauthenticated transports."
        }
      }
    },
    "evidence": {
      "type": "object",
      "required": ["id", "timestamp", "sha256"],
      "properties": {
        "id": { "type": "string", "pattern": "^EVD-" },
        "timestamp": { "type": "string", "format": "date-time" },
        "sha256": {
          "type": "string",
          "pattern": "^[0-9a-f]{64}$",
          "description": "SHA-256 over canonical JSON of { request, decision, timestamp }, where decision is the response minus advisory, evidence and disclaimer. Canonicalization: object keys sorted recursively, undefined-valued keys omitted, no whitespace. Evidence is excluded from its own hash."
        },
        "signature": {
          "type": "string",
          "description": "Optional. Ed25519 over the UTF-8 string 'structureclerk-authority-v1:' + sha256, base64url. Absent when the issuer has no signing key configured."
        },
        "key_id": {
          "type": "string",
          "description": "Identifier of the signing key, derived as 'sck-ed25519-' + first 16 hex chars of sha256(raw public key). Verifiable against the published key document."
        }
      }
    },
    "response": {
      "type": "object",
      "required": ["advisory", "decision", "reason", "confidence", "evidence", "disclaimer", "rules_version"],
      "properties": {
        "advisory": { "const": true, "description": "Always true. These decisions do not enforce anything." },
        "decision": { "$ref": "#/$defs/primitive" },
        "zone": {
          "type": ["integer", "null"],
          "enum": [1, 2, 3, null],
          "description": "Three Zones Framework: 1 automated, 2 augmented, 3 sanctuary. Null when no rule matched."
        },
        "reason": { "type": "string" },
        "reasons": { "type": "array", "items": { "type": "string" } },
        "confidence": {
          "type": "number",
          "minimum": 0,
          "maximum": 1,
          "description": "Below 0.90 the decision is forced to ESCALATE regardless of the matched rule."
        },
        "pre_escalation_decision": {
          "oneOf": [{ "$ref": "#/$defs/primitive" }, { "type": "null" }],
          "description": "What the rule would have returned before the doubt threshold forced ESCALATE."
        },
        "autonomy_adjustment": { "type": ["string", "null"] },
        "matched_rules": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": { "type": "string" },
              "specificity": { "type": "string", "enum": ["exact", "prefix", "heuristic"] },
              "confidence": { "type": "number" }
            }
          }
        },
        "frameworks": {
          "type": "array",
          "description": "Applicable frameworks, cited at framework level only — never article numbers.",
          "items": {
            "type": "object",
            "properties": {
              "name": { "type": "string" },
              "domain": { "type": "string" },
              "jurisdiction": { "type": "string" },
              "status": { "type": "string" }
            }
          }
        },
        "sector_risk_level": { "type": ["string", "null"] },
        "warnings": { "type": "array", "items": { "type": "string" } },
        "rules_version": { "type": "string" },
        "profile_adjustments": {
          "type": "array",
          "description": "Present only on org-scoped decisions. Each entry is a modulation that actually changed the outcome. Modulations may only increase human oversight, never reduce it.",
          "items": {
            "type": "object",
            "properties": {
              "id": { "type": "string" },
              "effect": {
                "type": "string",
                "enum": ["threshold_lowered", "category_extended", "severity_raised", "autonomy_capped"]
              },
              "reason": { "type": "string" },
              "from": { "type": ["string", "number", "null"] },
              "to": { "type": ["string", "number"] },
              "detail": { "type": "string" }
            }
          }
        },
        "org_profile": {
          "type": "object",
          "description": "Present only on org-scoped decisions. Echoes which posture applied, including its content hash, so the modulation is independently auditable.",
          "properties": {
            "id": { "type": "string" },
            "version": { "type": "integer" },
            "profile_sha256": { "type": "string" },
            "age_days": { "type": "integer" },
            "effective_financial_threshold": { "type": "number" },
            "sensitive_categories_added": { "type": "array", "items": { "type": "string" } },
            "weak_domains": { "type": "array", "items": { "type": "string" } }
          }
        },
        "evidence": { "$ref": "#/$defs/evidence" },
        "disclaimer": { "type": "string" }
      }
    }
  },
  "oneOf": [{ "$ref": "#/$defs/request" }, { "$ref": "#/$defs/response" }]
}