{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://asd-spec.example/schema/uas-1.0.schema.json", "title": "UAS/1.0 - Unified Agent Spec for Supply-Chain AI Agents", "description": "Single canonical, machine-friendly document combining declared business intent (formerly ASD/1.0) and validator-computable test content (formerly ATS/1.0) for one agent. Supersedes the ASD+Functional-Spec+Test-Spec split; see asd-spec/DERIVED_ARTIFACTS.md. A human-friendly Word rendering is a generated, round-trippable view of this document (uas2docx/docx2uas), not a separate source of truth.", "type": "object", "required": [ "uas", "agent", "capabilities", "decisions", "interfaces", "operations", "oversight", "lifecycle", "references", "execution" ], "properties": { "uas": { "type": "object", "required": [ "version" ], "properties": { "version": { "const": "1.0" } }, "patternProperties": { "^x-": {} }, "additionalProperties": false }, "agent": { "$ref": "#/$defs/agent" }, "capabilities": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/capability" } }, "decisions": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/decision" } }, "policies": { "type": "array", "items": { "$ref": "#/$defs/policy" } }, "interfaces": { "$ref": "#/$defs/interfaces" }, "operations": { "$ref": "#/$defs/operations" }, "oversight": { "$ref": "#/$defs/oversight" }, "acceptance_criteria": { "type": "array", "description": "KPI-engine pass/fail gates. Same shape as the old ASD assurance.acceptance / ATS acceptance_criteria.", "items": { "$ref": "#/$defs/acceptanceCriterion" } }, "scenarios": { "type": "array", "description": "Expanded, executable scenarios (concrete given/when/then with typed assertions) — the merged, computable form of the old ASD assurance.scenarios stubs and ATS scenarios[].", "items": { "$ref": "#/$defs/scenario" } }, "failure_mode_tests": { "type": "array", "description": "Expanded, executable form of operations.failure_modes — negative/resilience test cases.", "items": { "$ref": "#/$defs/failureModeTest" } }, "combinatorial": { "$ref": "#/$defs/combinatorial" }, "limitations": { "type": "array", "items": { "type": "object", "required": [ "id", "statement" ], "properties": { "id": { "$ref": "#/$defs/id" }, "statement": { "type": "string", "maxLength": 300 }, "impact": { "type": "string", "maxLength": 160 }, "workaround": { "type": "string", "maxLength": 200 } }, "patternProperties": { "^x-": {} }, "additionalProperties": false } }, "execution": { "$ref": "#/$defs/execution" }, "governance": { "$ref": "#/$defs/governance" }, "lifecycle": { "$ref": "#/$defs/lifecycle" }, "references": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/reference" } }, "extensions": { "type": "object", "propertyNames": { "pattern": "^[a-z][a-z0-9-]*(\\.[a-z0-9-]+)+$" }, "additionalProperties": true } }, "patternProperties": { "^x-": {} }, "additionalProperties": false, "$defs": { "id": { "type": "string", "pattern": "^[a-z][a-z0-9]*(-[a-z0-9]+)*$", "maxLength": 64 }, "ref": { "$ref": "#/$defs/id" }, "agentId": { "type": "string", "pattern": "^[a-z][a-z0-9]*([.-][a-z0-9]+)*$", "maxLength": 64 }, "semver": { "type": "string", "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(-[0-9A-Za-z.-]+)?(\\+[0-9A-Za-z.-]+)?$" }, "duration": { "type": "string", "pattern": "^P(?!$)(\\d+Y)?(\\d+M)?(\\d+W)?(\\d+D)?(T(?=\\d)(\\d+H)?(\\d+M)?(\\d+S)?)?$" }, "date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "format": "date" }, "quantity": { "type": "object", "required": [ "value", "unit" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 16 } }, "patternProperties": { "^x-": {} }, "additionalProperties": false }, "money": { "type": "object", "required": [ "value", "currency" ], "properties": { "value": { "type": "number" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "period": { "$ref": "#/$defs/duration" } }, "patternProperties": { "^x-": {} }, "additionalProperties": false }, "operator": { "enum": [ "eq", "neq", "lt", "lte", "gt", "gte", "in", "not-in", "exists", "absent", "matches" ] }, "objectiveOp": { "enum": [ "lt", "lte", "gte", "gt", "eq" ] }, "authority": { "enum": [ "observe", "recommend", "act-with-approval", "act-with-oversight", "act-autonomous" ] }, "locator": { "type": "object", "description": "Where this declared element actually lives in the agent's implementation. Enables free, deterministic grounding (a location-existence check, not semantic understanding) instead of expensive search. Optional — its absence just routes that element to a cheaper/lower-confidence grounding tier.", "required": [ "file", "symbol" ], "properties": { "file": { "type": "string", "maxLength": 300, "description": "Path relative to the agent's source root" }, "symbol": { "type": "string", "maxLength": 160, "description": "Function/class/route/tool name — never a raw line number, which drifts" } }, "patternProperties": { "^x-": {} }, "additionalProperties": false }, "category": { "anyOf": [ { "enum": [ "forecasting", "demand-planning", "supply-planning", "inventory", "replenishment", "procurement", "supplier-management", "manufacturing", "quality", "warehouse", "logistics", "transportation", "order-management", "returns", "finance", "analytics", "risk", "compliance", "sustainability", "control-tower", "copilot", "orchestration" ] }, { "type": "string", "pattern": "^x-[a-z0-9]+(-[a-z0-9]+)*$" } ] }, "metric": { "anyOf": [ { "enum": [ "forecast-mape", "forecast-wmape", "forecast-bias", "forecast-value-added", "fill-rate", "stockout-rate", "excess-inventory-ratio", "inventory-turns", "days-of-supply", "otif", "perfect-order-rate", "order-cycle-time", "backorder-rate", "po-cycle-time", "po-first-pass-yield", "realized-savings", "maverick-spend-ratio", "on-time-delivery", "transit-time-variance", "freight-cost-per-unit", "capacity-utilization", "dock-to-stock-time", "schedule-adherence", "first-pass-yield", "defect-rate", "scrap-rate", "decision-latency", "availability", "task-success-rate", "explanation-coverage", "automation-rate", "escalation-rate", "override-rate", "guardrail-breach-rate" ] }, { "type": "string", "pattern": "^x-[a-z0-9]+(-[a-z0-9]+)*$" } ] }, "condition": { "type": "object", "required": [ "subject", "operator" ], "properties": { "subject": { "type": "string", "maxLength": 120 }, "operator": { "$ref": "#/$defs/operator" }, "value": {} }, "patternProperties": { "^x-": {} }, "additionalProperties": false }, "agent": { "type": "object", "required": [ "id", "name", "version", "status", "summary", "categories", "kind", "owner", "context" ], "properties": { "id": { "$ref": "#/$defs/agentId" }, "name": { "type": "string", "maxLength": 80 }, "version": { "$ref": "#/$defs/semver" }, "status": { "enum": [ "draft", "pilot", "production", "deprecated", "retired" ] }, "summary": { "type": "string", "maxLength": 200 }, "description": { "type": "string", "maxLength": 500 }, "categories": { "type": "array", "minItems": 1, "maxItems": 3, "items": { "$ref": "#/$defs/category" } }, "scor": { "type": "array", "items": { "type": "string", "maxLength": 16 } }, "kind": { "enum": [ "single", "orchestrator", "member" ] }, "owner": { "type": "object", "required": [ "organization", "contact" ], "properties": { "organization": { "type": "string", "maxLength": 120 }, "contact": { "type": "string", "maxLength": 120 }, "team": { "type": "string", "maxLength": 80 } }, "patternProperties": { "^x-": {} }, "additionalProperties": false }, "operating_regions": { "type": "array", "items": { "type": "string", "pattern": "^[A-Z]{2}$" } }, "composition": { "$ref": "#/$defs/composition" }, "context": { "type": "object", "required": [ "excluded" ], "properties": { "excluded": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "id", "statement" ], "properties": { "id": { "$ref": "#/$defs/id" }, "statement": { "type": "string", "maxLength": 200 } }, "patternProperties": { "^x-": {} }, "additionalProperties": false } }, "assumptions": { "type": "array", "items": { "type": "object", "required": [ "id", "statement", "criticality" ], "properties": { "id": { "$ref": "#/$defs/id" }, "statement": { "type": "string", "maxLength": 300 }, "criticality": { "enum": [ "high", "medium", "low" ] } }, "patternProperties": { "^x-": {} }, "additionalProperties": false } }, "constraints": { "type": "array", "items": { "type": "object", "required": [ "id", "statement" ], "properties": { "id": { "$ref": "#/$defs/id" }, "statement": { "type": "string", "maxLength": 300 }, "source": { "type": "string", "maxLength": 80 } }, "patternProperties": { "^x-": {} }, "additionalProperties": false } }, "dependencies": { "type": "array", "items": { "type": "object", "required": [ "id", "statement" ], "properties": { "id": { "$ref": "#/$defs/id" }, "statement": { "type": "string", "maxLength": 200 } }, "patternProperties": { "^x-": {} }, "additionalProperties": false } } }, "patternProperties": { "^x-": {} }, "additionalProperties": false } }, "patternProperties": { "^x-": {} }, "additionalProperties": false, "if": { "properties": { "kind": { "const": "orchestrator" } } }, "then": { "required": [ "id", "name", "version", "status", "summary", "categories", "kind", "owner", "context", "composition" ] } }, "composition": { "type": "object", "required": [ "members", "coordination" ], "properties": { "members": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "id", "agent_ref", "role", "authority_ceiling" ], "properties": { "id": { "$ref": "#/$defs/id" }, "agent_ref": { "type": "string", "maxLength": 200 }, "role": { "type": "string", "maxLength": 160 }, "authority_ceiling": { "$ref": "#/$defs/authority" } }, "patternProperties": { "^x-": {} }, "additionalProperties": false } }, "coordination": { "type": "string", "maxLength": 300 }, "conflict_resolution": { "type": "string", "maxLength": 200 }, "parent": { "type": "string", "maxLength": 200 } }, "patternProperties": { "^x-": {} }, "additionalProperties": false }, "capability": { "type": "object", "required": [ "id", "name", "statement" ], "properties": { "id": { "$ref": "#/$defs/id" }, "name": { "type": "string", "maxLength": 80 }, "statement": { "type": "string", "maxLength": 300 }, "kind": { "enum": [ "sense", "analyze", "predict", "recommend", "execute", "converse", "orchestrate" ] }, "scor": { "type": "array", "items": { "type": "string", "maxLength": 16 } }, "metrics": { "type": "array", "items": { "$ref": "#/$defs/metric" } }, "locator": { "$ref": "#/$defs/locator" } }, "patternProperties": { "^x-": {} }, "additionalProperties": false }, "guardrail": { "type": "object", "required": [ "id", "parameter", "operator", "threshold", "on_breach" ], "properties": { "id": { "$ref": "#/$defs/id" }, "parameter": { "type": "string", "maxLength": 120 }, "operator": { "$ref": "#/$defs/operator" }, "threshold": { "anyOf": [ { "type": "number" }, { "type": "string", "maxLength": 120 }, { "type": "array" }, { "$ref": "#/$defs/quantity" }, { "$ref": "#/$defs/money" } ] }, "scope": { "type": "object", "required": [ "basis" ], "properties": { "basis": { "enum": [ "per-decision", "per-period" ] }, "period": { "$ref": "#/$defs/duration" } }, "patternProperties": { "^x-": {} }, "additionalProperties": false, "if": { "properties": { "basis": { "const": "per-period" } } }, "then": { "required": [ "basis", "period" ] } }, "on_breach": { "enum": [ "block", "require-approval", "escalate", "degrade" ] }, "locator": { "$ref": "#/$defs/locator" } }, "patternProperties": { "^x-": {} }, "additionalProperties": false }, "decision": { "type": "object", "required": [ "id", "name", "capability", "statement", "authority", "trigger", "reversibility" ], "properties": { "id": { "$ref": "#/$defs/id" }, "name": { "type": "string", "maxLength": 80 }, "capability": { "$ref": "#/$defs/ref" }, "statement": { "type": "string", "maxLength": 300 }, "authority": { "$ref": "#/$defs/authority" }, "trigger": { "type": "object", "required": [ "kind", "detail" ], "properties": { "kind": { "enum": [ "event", "schedule", "threshold", "request" ] }, "detail": { "type": "string", "maxLength": 200 } }, "patternProperties": { "^x-": {} }, "additionalProperties": false }, "inputs": { "type": "array", "items": { "$ref": "#/$defs/ref" } }, "executes_via": { "type": "array", "items": { "$ref": "#/$defs/ref" } }, "reversibility": { "enum": [ "reversible", "compensable", "irreversible" ] }, "reversal": { "type": "string", "maxLength": 200 }, "blast_radius": { "type": "object", "required": [ "scope" ], "properties": { "scope": { "enum": [ "item", "order", "shipment", "site", "network", "enterprise" ] }, "max_exposure": { "$ref": "#/$defs/money" } }, "patternProperties": { "^x-": {} }, "additionalProperties": false }, "guardrails": { "type": "array", "items": { "$ref": "#/$defs/guardrail" } }, "escalation": { "type": "object", "required": [ "to", "when" ], "properties": { "to": { "type": "string", "maxLength": 80 }, "when": { "type": "string", "maxLength": 200 }, "within": { "$ref": "#/$defs/duration" } }, "patternProperties": { "^x-": {} }, "additionalProperties": false }, "policy_refs": { "type": "array", "items": { "$ref": "#/$defs/ref" } }, "risk_refs": { "type": "array", "items": { "$ref": "#/$defs/ref" } }, "formulas": { "type": "array", "description": "Business calculations this decision relies on (reorder point, order quantity, allocation share...). The Analyzer verifies each one against the implementation, so state the intended arithmetic here rather than only in prose.", "items": { "$ref": "#/$defs/formula" } }, "locator": { "$ref": "#/$defs/locator" } }, "patternProperties": { "^x-": {} }, "additionalProperties": false, "allOf": [ { "if": { "properties": { "reversibility": { "enum": [ "compensable", "irreversible" ] } } }, "then": { "required": [ "id", "name", "capability", "statement", "authority", "trigger", "reversibility", "reversal" ] } }, { "if": { "properties": { "authority": { "enum": [ "act-with-oversight", "act-autonomous" ] } } }, "then": { "required": [ "id", "name", "capability", "statement", "authority", "trigger", "reversibility", "guardrails", "escalation" ], "properties": { "guardrails": { "type": "array", "minItems": 1 } } } } ] }, "formula": { "type": "object", "required": [ "id", "name", "output", "expression" ], "properties": { "id": { "$ref": "#/$defs/id" }, "name": { "type": "string", "maxLength": 80 }, "output": { "type": "string", "maxLength": 64, "description": "The quantity computed, named the way the agent's code names it (variable, field or returned value)." }, "expression": { "type": "string", "maxLength": 300, "description": "Arithmetic over the variables below: + - * / ** and max, min, abs, ceil, floor, sqrt. Parsed by a whitelist parser, never evaluated as code." }, "variables": { "type": "array", "items": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "maxLength": 64 }, "binds_to": { "type": "string", "maxLength": 64, "description": "Identifier in the code this variable corresponds to, when the code names it differently." }, "unit": { "type": "string", "maxLength": 16 }, "meaning": { "type": "string", "maxLength": 120 } }, "patternProperties": { "^x-": {} }, "additionalProperties": false } }, "locator": { "$ref": "#/$defs/locator" } }, "patternProperties": { "^x-": {} }, "additionalProperties": false }, "policy": { "type": "object", "required": [ "id", "class", "statement", "verification" ], "properties": { "id": { "$ref": "#/$defs/id" }, "class": { "enum": [ "invariant", "constraint", "preference" ] }, "statement": { "type": "string", "maxLength": 300 }, "rule": { "type": "object", "required": [ "applies_to", "then" ], "properties": { "applies_to": { "type": "array", "minItems": 1, "items": { "anyOf": [ { "const": "all" }, { "$ref": "#/$defs/ref" } ] } }, "when": { "type": "array", "items": { "$ref": "#/$defs/condition" } }, "then": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/condition" } } }, "patternProperties": { "^x-": {} }, "additionalProperties": false }, "exceptions": { "type": "object", "required": [ "statement", "approver" ], "properties": { "statement": { "type": "string", "maxLength": 300 }, "approver": { "type": "string", "maxLength": 80 } }, "patternProperties": { "^x-": {} }, "additionalProperties": false }, "source": { "type": "object", "required": [ "owner" ], "properties": { "owner": { "type": "string", "maxLength": 80 }, "document": { "$ref": "#/$defs/ref" } }, "patternProperties": { "^x-": {} }, "additionalProperties": false }, "verification": { "enum": [ "scenario", "static", "runtime", "attestation" ] }, "locator": { "$ref": "#/$defs/locator" } }, "patternProperties": { "^x-": {} }, "additionalProperties": false, "if": { "properties": { "class": { "const": "constraint" } } }, "then": { "required": [ "id", "class", "statement", "verification", "exceptions" ] } }, "interfaces": { "type": "object", "required": [ "consumes", "produces", "systems" ], "properties": { "consumes": { "type": "array", "items": { "$ref": "#/$defs/consumedInterface" } }, "produces": { "type": "array", "items": { "$ref": "#/$defs/producedInterface" } }, "systems": { "type": "array", "items": { "$ref": "#/$defs/system" } } }, "patternProperties": { "^x-": {} }, "additionalProperties": false }, "interfaceCommon": { "type": "object", "properties": { "id": { "$ref": "#/$defs/id" }, "name": { "type": "string", "maxLength": 80 }, "kind": { "enum": [ "api", "event", "file", "database", "stream", "ui", "document" ] }, "system": { "$ref": "#/$defs/ref" }, "schema": { "$ref": "#/$defs/ref", "description": "Optional pointer to a full external spec (e.g. an OpenAPI doc) in references[] — json_schema below is the computable copy validators actually use." }, "json_schema": { "type": "object", "description": "Inline JSON Schema for this interface's payload shape — concrete and validator-computable, not just a reference." }, "examples": { "type": "array", "description": "Representative valid payloads, for synthetic test-data generation." }, "boundary_values": { "type": "array", "description": "Edge-case values per field (min/max/empty/null-where-forbidden) for boundary test generation." }, "adversarial_hints": { "type": "array", "items": { "type": "string", "maxLength": 120 }, "description": "Known attack-relevant input shapes for this interface (oversized payload, injected control characters, malformed encoding, etc.)." }, "fields": { "type": "array", "items": { "type": "object", "required": [ "name", "meaning" ], "properties": { "name": { "type": "string", "maxLength": 64 }, "meaning": { "type": "string", "maxLength": 120 }, "unit": { "type": "string", "maxLength": 16 } }, "patternProperties": { "^x-": {} }, "additionalProperties": false } }, "semantics": { "type": "string", "maxLength": 200 }, "classification": { "enum": [ "public", "internal", "confidential", "restricted" ] }, "pii": { "type": "boolean" }, "locator": { "$ref": "#/$defs/locator" } } }, "consumedInterface": { "allOf": [ { "$ref": "#/$defs/interfaceCommon" } ], "type": "object", "required": [ "id", "name", "kind", "semantics", "classification", "pii", "json_schema", "if_unavailable" ], "properties": { "id": true, "name": true, "kind": true, "system": true, "schema": true, "json_schema": true, "examples": true, "boundary_values": true, "adversarial_hints": true, "fields": true, "semantics": true, "classification": true, "pii": true, "locator": true, "freshness": { "$ref": "#/$defs/duration" }, "quality": { "type": "array", "items": { "type": "object", "required": [ "dimension", "threshold" ], "properties": { "dimension": { "enum": [ "completeness", "accuracy", "consistency", "validity", "uniqueness", "timeliness" ] }, "threshold": { "type": "number", "minimum": 0, "maximum": 1 } }, "patternProperties": { "^x-": {} }, "additionalProperties": false } }, "if_unavailable": { "enum": [ "halt", "degrade", "use-stale", "substitute" ] } }, "patternProperties": { "^x-": {} }, "additionalProperties": false }, "producedInterface": { "allOf": [ { "$ref": "#/$defs/interfaceCommon" } ], "type": "object", "required": [ "id", "name", "kind", "semantics", "classification", "pii", "side_effect", "json_schema" ], "properties": { "id": true, "name": true, "kind": true, "system": true, "schema": true, "json_schema": true, "examples": true, "boundary_values": true, "adversarial_hints": true, "fields": true, "semantics": true, "classification": true, "pii": true, "locator": true, "side_effect": { "type": "boolean" }, "consumers": { "type": "array", "items": { "type": "string", "maxLength": 80 } } }, "patternProperties": { "^x-": {} }, "additionalProperties": false }, "system": { "type": "object", "required": [ "id", "name", "role", "direction", "criticality" ], "properties": { "id": { "$ref": "#/$defs/id" }, "name": { "type": "string", "maxLength": 80 }, "role": { "enum": [ "system-of-record", "execution", "data-source", "notification", "model-service", "other" ] }, "direction": { "enum": [ "read", "write", "read-write" ] }, "criticality": { "enum": [ "required", "degradable", "optional" ] }, "interface": { "$ref": "#/$defs/ref" } }, "patternProperties": { "^x-": {} }, "additionalProperties": false }, "operations": { "type": "object", "required": [ "failure_modes", "safe_states" ], "properties": { "failure_modes": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "id", "condition", "detection", "response" ], "properties": { "id": { "$ref": "#/$defs/id" }, "condition": { "type": "string", "maxLength": 200 }, "affects": { "type": "array", "items": { "$ref": "#/$defs/ref" } }, "detection": { "type": "string", "maxLength": 160 }, "response": { "enum": [ "halt", "degrade", "fallback", "queue", "escalate", "retry-bounded" ] }, "safe_state": { "$ref": "#/$defs/ref" }, "notify": { "type": "array", "items": { "$ref": "#/$defs/ref" } } }, "patternProperties": { "^x-": {} }, "additionalProperties": false } }, "safe_states": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "id", "statement", "entry", "exit" ], "properties": { "id": { "$ref": "#/$defs/id" }, "statement": { "type": "string", "maxLength": 200 }, "entry": { "enum": [ "automatic", "manual" ] }, "exit": { "enum": [ "automatic", "manual" ] } }, "patternProperties": { "^x-": {} }, "additionalProperties": false } }, "slos": { "type": "array", "items": { "type": "object", "required": [ "metric", "objective", "value", "unit", "window" ], "properties": { "metric": { "$ref": "#/$defs/metric" }, "objective": { "$ref": "#/$defs/objectiveOp" }, "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 16 }, "window": { "$ref": "#/$defs/duration" } }, "patternProperties": { "^x-": {} }, "additionalProperties": false } }, "observability": { "type": "object", "required": [ "decision_log" ], "properties": { "decision_log": { "type": "object", "required": [ "location", "format", "fields", "retention" ], "properties": { "location": { "$ref": "#/$defs/ref" }, "format": { "type": "string", "maxLength": 80 }, "fields": { "type": "array", "minItems": 1, "items": { "type": "string", "maxLength": 64 } }, "retention": { "$ref": "#/$defs/duration" } }, "patternProperties": { "^x-": {} }, "additionalProperties": false }, "traces": { "type": "object", "required": [ "standard" ], "properties": { "standard": { "enum": [ "w3c-trace-context", "custom" ] }, "note": { "type": "string", "maxLength": 120 } }, "patternProperties": { "^x-": {} }, "additionalProperties": false }, "metrics": { "type": "object", "required": [ "location" ], "properties": { "location": { "$ref": "#/$defs/ref" } }, "patternProperties": { "^x-": {} }, "additionalProperties": false } }, "patternProperties": { "^x-": {} }, "additionalProperties": false } }, "patternProperties": { "^x-": {} }, "additionalProperties": false }, "oversight": { "type": "object", "required": [ "posture", "controls", "escalations" ], "properties": { "posture": { "enum": [ "human-in-the-loop", "human-on-the-loop", "human-out-of-the-loop" ] }, "roles": { "type": "array", "items": { "type": "object", "required": [ "id", "title", "duties" ], "properties": { "id": { "$ref": "#/$defs/id" }, "title": { "type": "string", "maxLength": 80 }, "duties": { "type": "array", "minItems": 1, "items": { "enum": [ "approve", "monitor", "override", "audit", "configure" ] } }, "decisions": { "type": "array", "items": { "$ref": "#/$defs/ref" } } }, "patternProperties": { "^x-": {} }, "additionalProperties": false } }, "controls": { "type": "object", "required": [ "pause", "override", "rollback" ], "properties": { "pause": { "$ref": "#/$defs/control" }, "override": { "$ref": "#/$defs/control" }, "rollback": { "$ref": "#/$defs/control" } }, "patternProperties": { "^x-": {} }, "additionalProperties": false }, "escalations": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "id", "when", "to" ], "properties": { "id": { "$ref": "#/$defs/id" }, "when": { "type": "string", "maxLength": 200 }, "to": { "type": "string", "maxLength": 80 }, "within": { "$ref": "#/$defs/duration" }, "channel": { "type": "string", "maxLength": 80 } }, "patternProperties": { "^x-": {} }, "additionalProperties": false } }, "explainability": { "type": "array", "items": { "type": "object", "required": [ "decisions", "artifacts", "audience" ], "properties": { "decisions": { "type": "array", "minItems": 1, "items": { "anyOf": [ { "const": "all" }, { "$ref": "#/$defs/ref" } ] } }, "artifacts": { "type": "array", "minItems": 1, "items": { "enum": [ "decision-record", "reason-codes", "rule-trace", "feature-attribution", "confidence-score", "natural-language-rationale" ] } }, "audience": { "enum": [ "operator", "approver", "auditor", "customer", "regulator" ] }, "location": { "$ref": "#/$defs/ref" } }, "patternProperties": { "^x-": {} }, "additionalProperties": false } } }, "patternProperties": { "^x-": {} }, "additionalProperties": false }, "control": { "type": "object", "required": [ "available" ], "properties": { "available": { "type": "boolean" }, "method": { "type": "string", "maxLength": 160 }, "actor": { "type": "string", "maxLength": 80 }, "locator": { "$ref": "#/$defs/locator" } }, "patternProperties": { "^x-": {} }, "additionalProperties": false, "if": { "properties": { "available": { "const": true } } }, "then": { "required": [ "available", "method" ] } }, "acceptanceCriterion": { "type": "object", "required": [ "id", "metric", "objective", "value", "unit", "basis", "gate" ], "properties": { "id": { "$ref": "#/$defs/id" }, "metric": { "$ref": "#/$defs/metric" }, "objective": { "$ref": "#/$defs/objectiveOp" }, "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 16 }, "basis": { "type": "string", "maxLength": 120 }, "gate": { "enum": [ "pre-production", "continuous", "both" ] } }, "patternProperties": { "^x-": {} }, "additionalProperties": false }, "assertion": { "type": "object", "required": [ "subject", "operator", "value" ], "properties": { "subject": { "type": "string", "maxLength": 120, "description": "Field path on the actual output/decision being checked" }, "operator": { "$ref": "#/$defs/operator" }, "value": {} }, "patternProperties": { "^x-": {} }, "additionalProperties": false }, "scenario": { "type": "object", "required": [ "id", "name", "category", "priority", "verifies", "given", "when", "then", "severity_if_failed", "traceability" ], "properties": { "id": { "$ref": "#/$defs/id" }, "name": { "type": "string", "maxLength": 80 }, "category": { "type": "string", "maxLength": 40, "description": "e.g. inventory, demand, supplier, procurement, warehouse, runtime, security, stress, concurrency, replay" }, "priority": { "enum": [ "critical", "high", "medium", "low" ] }, "verifies": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/ref" }, "description": "decision/policy/capability/failure_mode ids this scenario proves" }, "given": { "type": "object", "required": [ "inputs" ], "properties": { "initial_state": { "type": "object", "description": "Concrete pre-state, e.g. repository/db seed" }, "inputs": { "type": "object", "description": "Concrete payload per interfaces.consumes id" } }, "patternProperties": { "^x-": {} }, "additionalProperties": false }, "when": { "type": "object", "required": [ "action" ], "properties": { "trigger": { "type": "string", "maxLength": 200 }, "action": { "type": "string", "maxLength": 200, "description": "What the harness does to invoke the agent for this scenario" } }, "patternProperties": { "^x-": {} }, "additionalProperties": false }, "then": { "type": "object", "required": [ "expected_behaviour" ], "properties": { "expected_behaviour": { "type": "string", "maxLength": 300 }, "expected_outputs": { "type": "array", "items": { "type": "object", "required": [ "output_id", "assert" ], "properties": { "output_id": { "$ref": "#/$defs/ref" }, "assert": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/assertion" } } }, "patternProperties": { "^x-": {} }, "additionalProperties": false } }, "expected_decision": { "type": "array", "items": { "type": "object", "required": [ "decision_id", "assert" ], "properties": { "decision_id": { "$ref": "#/$defs/ref" }, "assert": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/assertion" } } }, "patternProperties": { "^x-": {} }, "additionalProperties": false } } }, "patternProperties": { "^x-": {} }, "additionalProperties": false }, "severity_if_failed": { "enum": [ "critical", "high", "medium", "low" ] }, "traceability": { "type": "object", "required": [ "requirement_ids" ], "properties": { "requirement_ids": { "type": "array", "items": { "$ref": "#/$defs/ref" } }, "standard_refs": { "type": "array", "items": { "type": "string", "maxLength": 40 } }, "pairwise_case": { "type": [ "object", "null" ] } }, "patternProperties": { "^x-": {} }, "additionalProperties": false } }, "patternProperties": { "^x-": {} }, "additionalProperties": false }, "failureModeTest": { "type": "object", "required": [ "id", "verifies_failure_mode", "simulate", "expected_response", "expected_safe_state" ], "properties": { "id": { "$ref": "#/$defs/id" }, "verifies_failure_mode": { "$ref": "#/$defs/ref" }, "simulate": { "type": "object", "required": [ "target", "fault" ], "properties": { "target": { "$ref": "#/$defs/ref" }, "fault": { "enum": [ "unavailable", "latency", "error-5xx", "corrupt-data", "stale", "partial" ] }, "detail": { "type": "string", "maxLength": 160 } }, "patternProperties": { "^x-": {} }, "additionalProperties": false }, "expected_response": { "enum": [ "halt", "degrade", "fallback", "queue", "escalate", "retry-bounded" ] }, "expected_safe_state": { "$ref": "#/$defs/ref" } }, "patternProperties": { "^x-": {} }, "additionalProperties": false }, "combinatorial": { "type": "object", "properties": { "axes": { "type": "array", "items": { "type": "object", "required": [ "variable", "values" ], "properties": { "variable": { "type": "string", "maxLength": 80 }, "values": { "type": "array", "minItems": 2 } }, "patternProperties": { "^x-": {} }, "additionalProperties": false } }, "exclusions": { "type": "array", "items": { "type": "object", "required": [ "without" ], "properties": { "without": { "type": "array", "description": "Combination of {variable, value} pairs that must never co-occur" }, "reason": { "type": "string", "maxLength": 120, "description": "Usually a policy id this exclusion enforces" } }, "patternProperties": { "^x-": {} }, "additionalProperties": false } }, "strategy": { "enum": [ "pairwise", "n-wise" ], "default": "pairwise" }, "n": { "type": "integer", "minimum": 2, "default": 2 }, "target_coverage": { "type": "number", "minimum": 0, "maximum": 1 } }, "patternProperties": { "^x-": {} }, "additionalProperties": false }, "execution": { "type": "object", "description": "Implementation binding no declaration of business intent can carry — how the harness actually invokes and sandboxes the agent under test. Doubles as the sandbox provisioning manifest.", "required": [ "candidate_ref", "invocation_kind", "sandbox", "timeout_s" ], "properties": { "candidate_ref": { "type": "string", "maxLength": 300, "description": "CLI command, function import path, or API endpoint that invokes the agent" }, "invocation_kind": { "enum": [ "cli", "http", "grpc", "function", "queue-consumer" ] }, "sandbox": { "type": "boolean" }, "isolated_state": { "enum": [ "per-scenario", "shared" ], "default": "per-scenario" }, "idempotency_check": { "type": "boolean", "default": true }, "timeout_s": { "type": "number", "exclusiveMinimum": 0 }, "retry_policy": { "type": "object", "properties": { "max_attempts": { "type": "integer", "minimum": 1 }, "backoff_s": { "type": "number", "minimum": 0 } }, "patternProperties": { "^x-": {} }, "additionalProperties": false }, "env": { "type": "array", "description": "Required environment variable NAMES only — never values or secrets.", "items": { "type": "object", "required": [ "name", "secret" ], "properties": { "name": { "type": "string", "maxLength": 80 }, "secret": { "type": "boolean" }, "required": { "type": "boolean" }, "purpose": { "type": "string", "maxLength": 40 }, "source": { "enum": [ "declared", "extracted" ] } }, "patternProperties": { "^x-": {} }, "additionalProperties": false } }, "service_mocks": { "type": "array", "description": "One entry per interfaces.systems id — how the sandbox virtualizes that dependency so the agent runs unmodified.", "items": { "type": "object", "required": [ "system_id", "protocol" ], "properties": { "system_id": { "$ref": "#/$defs/ref" }, "protocol": { "type": "string", "maxLength": 40 }, "base_path": { "type": "string", "maxLength": 200 } }, "patternProperties": { "^x-": {} }, "additionalProperties": false } }, "resource_limits": { "type": "object", "properties": { "cpu": { "type": "string", "maxLength": 16 }, "memory": { "type": "string", "maxLength": 16 }, "network_egress_allowlist": { "type": "array", "items": { "$ref": "#/$defs/ref" }, "description": "system ids the sandbox permits; anything else attempted is itself a security finding" } }, "patternProperties": { "^x-": {} }, "additionalProperties": false }, "observability_hooks": { "type": "object", "properties": { "decision_log_location": { "type": "string", "maxLength": 300 }, "trace_location": { "type": "string", "maxLength": 300 } }, "patternProperties": { "^x-": {} }, "additionalProperties": false }, "runtime": { "type": "object", "description": "Optional. Runtime, dependencies and services the sandbox needs. The analyzer fills this from the source when it is omitted; declared values win.", "properties": { "language": { "type": [ "string", "null" ], "maxLength": 40 }, "language_version": { "type": [ "string", "null" ], "maxLength": 60 }, "frameworks": { "type": "array", "items": { "type": "string", "maxLength": 60 } }, "dependencies": { "type": "object" }, "system_packages": { "type": "array", "items": { "type": "string", "maxLength": 80 } }, "install_commands": { "type": "array", "items": { "type": "string", "maxLength": 300 } }, "start_commands": { "type": "array", "items": { "type": "string", "maxLength": 300 } }, "services": { "type": "array", "items": { "type": "object" } }, "model_providers": { "type": "array", "items": { "type": "string", "maxLength": 60 } }, "data_files": { "type": "array", "items": { "type": "string", "maxLength": 300 } }, "source": { "enum": [ "declared", "extracted" ] } }, "patternProperties": { "^x-": {} }, "additionalProperties": false }, "entrypoints": { "type": "array", "description": "Optional. How the agent is invoked, with the shape of its input and output. The analyzer fills this from the source when it is omitted.", "items": { "type": "object", "required": [ "kind", "path" ], "properties": { "id": { "type": "string", "maxLength": 40 }, "kind": { "enum": [ "http", "cli", "ui", "script", "agent", "mcp-tool", "function" ] }, "method": { "type": [ "string", "null" ], "maxLength": 12 }, "path": { "type": "string", "maxLength": 300 }, "handler": { "type": "string", "maxLength": 300 }, "invocation": { "type": [ "string", "null" ], "maxLength": 300 }, "invocation_source": { "type": [ "string", "null" ], "maxLength": 40 }, "input_schema": { "type": "object" }, "output_schema": { "type": "object" }, "framework": { "type": [ "string", "null" ], "maxLength": 60 }, "confidence": { "type": "number", "minimum": 0, "maximum": 1 }, "source": { "enum": [ "declared", "extracted" ] } }, "patternProperties": { "^x-": {} }, "additionalProperties": false } } }, "patternProperties": { "^x-": {} }, "additionalProperties": false }, "governance": { "type": "object", "properties": { "accountability": { "type": "object", "required": [ "executive_owner", "operational_owner" ], "properties": { "executive_owner": { "$ref": "#/$defs/accountableRole" }, "operational_owner": { "$ref": "#/$defs/accountableRole" }, "risk_owner": { "$ref": "#/$defs/accountableRole" } }, "patternProperties": { "^x-": {} }, "additionalProperties": false }, "risk_class": { "type": "object", "required": [ "framework", "class" ], "properties": { "framework": { "anyOf": [ { "enum": [ "eu-ai-act", "nist-ai-rmf", "internal" ] }, { "type": "string", "pattern": "^x-[a-z0-9]+(-[a-z0-9]+)*$" } ] }, "class": { "type": "string", "maxLength": 40 }, "rationale": { "type": "string", "maxLength": 300 } }, "patternProperties": { "^x-": {} }, "additionalProperties": false }, "risks": { "type": "array", "items": { "type": "object", "required": [ "id", "category", "statement", "likelihood", "severity" ], "properties": { "id": { "$ref": "#/$defs/id" }, "category": { "enum": [ "operational", "financial", "safety", "security", "privacy", "compliance", "reputational", "model-behavior" ] }, "statement": { "type": "string", "maxLength": 300 }, "likelihood": { "enum": [ "rare", "unlikely", "possible", "likely", "almost-certain" ] }, "severity": { "enum": [ "negligible", "minor", "moderate", "major", "severe" ] }, "mitigations": { "type": "array", "items": { "$ref": "#/$defs/ref" }, "description": "ids of real controls elsewhere in this document — the Analyzer confirms each one grounds" }, "residual_accepted_by": { "type": "string", "maxLength": 80 } }, "patternProperties": { "^x-": {} }, "additionalProperties": false } }, "security": { "type": "object", "required": [ "identity", "authorization", "secrets", "data_protection" ], "properties": { "identity": { "enum": [ "service-account", "delegated-user", "hybrid" ] }, "authorization": { "type": "string", "maxLength": 200 }, "secrets": { "enum": [ "vault-managed", "platform-managed", "environment", "none" ] }, "data_protection": { "type": "object", "required": [ "in_transit", "at_rest" ], "properties": { "in_transit": { "type": "string", "maxLength": 40 }, "at_rest": { "type": "string", "maxLength": 40 } }, "patternProperties": { "^x-": {} }, "additionalProperties": false }, "threats_considered": { "type": "array", "items": { "type": "string", "maxLength": 80 } } }, "patternProperties": { "^x-": {} }, "additionalProperties": false }, "privacy": { "type": "object", "required": [ "processes_pii" ], "properties": { "processes_pii": { "type": "boolean" }, "categories": { "type": "array", "items": { "type": "string", "maxLength": 40 } }, "purpose": { "type": "string", "maxLength": 200 }, "legal_basis": { "type": "string", "maxLength": 80 }, "retention": { "$ref": "#/$defs/duration" }, "contact": { "type": "string", "maxLength": 120 } }, "patternProperties": { "^x-": {} }, "additionalProperties": false }, "compliance": { "type": "array", "items": { "type": "object", "required": [ "id", "framework", "requirement", "status" ], "properties": { "id": { "$ref": "#/$defs/id" }, "framework": { "anyOf": [ { "enum": [ "iso-42001", "iso-27001", "iso-9001", "iso-31000", "soc2", "gdpr", "eu-ai-act", "c-tpat", "ctpat-tsp", "itar", "sox" ] }, { "type": "string", "pattern": "^x-[a-z0-9]+(-[a-z0-9]+)*$" } ] }, "requirement": { "type": "string", "maxLength": 160 }, "status": { "enum": [ "claimed", "assessed", "certified", "not-applicable" ] }, "evidence": { "$ref": "#/$defs/ref" } }, "patternProperties": { "^x-": {} }, "additionalProperties": false } }, "audit": { "type": "object", "required": [ "immutability", "access" ], "properties": { "immutability": { "enum": [ "append-only", "worm", "mutable" ] }, "access": { "type": "array", "minItems": 1, "items": { "type": "string", "maxLength": 80 } }, "regulator_access": { "type": "boolean" } }, "patternProperties": { "^x-": {} }, "additionalProperties": false } }, "patternProperties": { "^x-": {} }, "additionalProperties": false }, "accountableRole": { "type": "object", "required": [ "role", "contact" ], "properties": { "role": { "type": "string", "maxLength": 80 }, "contact": { "type": "string", "maxLength": 120 } }, "patternProperties": { "^x-": {} }, "additionalProperties": false }, "lifecycle": { "type": "object", "required": [ "change_log" ], "properties": { "change_log": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "version", "date", "type", "breaking", "revalidation", "summary" ], "properties": { "version": { "$ref": "#/$defs/semver" }, "date": { "$ref": "#/$defs/date" }, "type": { "type": "array", "minItems": 1, "items": { "enum": [ "added", "changed", "deprecated", "removed", "fixed", "security" ] } }, "breaking": { "type": "boolean" }, "revalidation": { "enum": [ "required", "not-required" ] }, "summary": { "type": "string", "maxLength": 300 } }, "patternProperties": { "^x-": {} }, "additionalProperties": false } }, "model_dependencies": { "type": "array", "description": "Declared LLM/model dependencies. The Analyzer diffs this against the observed technology inventory (imports, SDK usage) to catch undeclared model/provider usage.", "items": { "type": "object", "required": [ "id", "role", "update_policy", "revalidation" ], "properties": { "id": { "$ref": "#/$defs/id" }, "role": { "type": "string", "maxLength": 120 }, "update_policy": { "enum": [ "pinned", "managed-upgrade", "provider-continuous" ] }, "revalidation": { "enum": [ "full", "affected", "none" ] } }, "patternProperties": { "^x-": {} }, "additionalProperties": false } }, "reviews": { "type": "object", "required": [ "cadence" ], "properties": { "cadence": { "$ref": "#/$defs/duration" }, "last": { "$ref": "#/$defs/date" } }, "patternProperties": { "^x-": {} }, "additionalProperties": false }, "deprecation": { "type": "object", "required": [ "notice" ], "properties": { "notice": { "$ref": "#/$defs/duration" }, "migration": { "type": "string", "maxLength": 200 } }, "patternProperties": { "^x-": {} }, "additionalProperties": false } }, "patternProperties": { "^x-": {} }, "additionalProperties": false }, "reference": { "type": "object", "required": [ "id", "kind", "title", "location" ], "properties": { "id": { "$ref": "#/$defs/id" }, "kind": { "enum": [ "repository", "api-spec", "data-schema", "model-card", "runbook", "dashboard", "policy-document", "risk-assessment", "audit-report", "dataset", "agent-spec", "other" ] }, "title": { "type": "string", "maxLength": 80 }, "location": { "type": "string", "maxLength": 500 }, "access": { "enum": [ "public", "credentialed", "on-request" ] }, "note": { "type": "string", "maxLength": 160 } }, "patternProperties": { "^x-": {} }, "additionalProperties": false } } }