The runtime request contract is the versioned boundary between product workflow and governed AI execution.
Status and scope
Identity, tenancy, task risk, input references, authority, context, routing, tools, memory, budgets, approvals, outputs, traces, classification, retention, idempotency, and deadlines.
Fields
| Field | Type | Required | Contract meaning |
|---|---|---|---|
contractVersion | constant | Yes | See the schema constraints and examples for this versioned field. Required value: aruntime.runtime-request.v1. |
requestId | string | Yes | See the schema constraints and examples for this versioned field. |
correlationId | string | Yes | See the schema constraints and examples for this versioned field. |
idempotencyKey | string | Yes | See the schema constraints and examples for this versioned field. |
timestampUtc | string | Yes | UTC ISO 8601 timestamp ending in Z. |
deadlineUtc | object | No | See the schema constraints and examples for this versioned field. |
actor | object | Yes | See the schema constraints and examples for this versioned field. |
tenant | object or null | No | See the schema constraints and examples for this versioned field. |
session | object or null | No | See the schema constraints and examples for this versioned field. |
taskType | string | Yes | See the schema constraints and examples for this versioned field. |
riskLevel | enum | Yes | See the schema constraints and examples for this versioned field. Allowed values: low, medium, high, critical. |
input | object | Yes | Task-specific input. Avoid embedding secrets when references are sufficient. |
permissions | array | Yes | See the schema constraints and examples for this versioned field. |
contextPolicy | object | Yes | See the schema constraints and examples for this versioned field. |
modelRouteConstraints | object | Yes | See the schema constraints and examples for this versioned field. |
allowedTools | array | No | See the schema constraints and examples for this versioned field. |
toolPolicy | object | Yes | See the schema constraints and examples for this versioned field. |
memoryPolicy | object | Yes | See the schema constraints and examples for this versioned field. |
budget | object | Yes | See the schema constraints and examples for this versioned field. |
approvalPolicy | object | Yes | See the schema constraints and examples for this versioned field. |
outputContract | object | Yes | See the schema constraints and examples for this versioned field. |
traceSettings | object | Yes | See the schema constraints and examples for this versioned field. |
dataClassification | enum | Yes | See the schema constraints and examples for this versioned field. Allowed values: public, internal, confidential, restricted. |
retentionPolicy | object | Yes | See the schema constraints and examples for this versioned field. |
metadata | object | No | See the schema constraints and examples for this versioned field. |
Versioning and compatibility rules
- Producers must send exactly `aruntime.runtime-request.v1`; consumers must reject unsupported major versions rather than guessing.
- Additive optional fields may be introduced within a major version only when older consumers ignore them safely. Required-field or semantic changes require a new major contract identifier.
- The idempotency key names the intended effect, not one transport attempt. A repeated key must return the recorded outcome or an explicit in-progress conflict.
- Deadlines use UTC ISO 8601 values ending in `Z`. A runtime must not begin a high-impact side effect when insufficient time remains to validate and record it.
Validation and error behavior
Validate the complete envelope before model execution or credential resolution. Return a stable machine code, a safe human explanation, the failing JSON Pointer, and the supported contract versions. Never “repair” missing authority or risk fields with model-generated values.
{
"error": {
"code": "contract-validation-failed",
"contractVersion": "aruntime.runtime-request.v1",
"path": "/idempotencyKey",
"message": "A stable idempotency key is required.",
"retryable": false
}
}Security, redaction, and minimization
- Use actor and tenant references rather than embedding credentials or personal records.
- Treat context, tool results, traces, and memory writes as independent data-egress and retention decisions.
- A model must never expand its own permissions, allowed tools, approval authority, or retention policy.
- Diagnostic tracing does not override classification, redaction, consent, or legal-retention controls.
Validated examples
Minimal governed request
{
"contractVersion": "aruntime.runtime-request.v1",
"requestId": "req_20260623_001",
"correlationId": "corr_20260623_001",
"idempotencyKey": "idem_answer_001",
"timestampUtc": "2026-06-23T14:30:00Z",
"deadlineUtc": "2026-06-23T14:30:20Z",
"actor": {
"type": "user",
"idRef": "user:example"
},
"tenant": {
"idRef": "tenant:demo",
"region": "us-central"
},
"session": {
"idRef": "session:001",
"sequence": 3
},
"taskType": "answer-with-evidence",
"riskLevel": "medium",
"input": {
"question": "Summarize the approved architecture record."
},
"permissions": [
"read:approved-architecture"
],
"contextPolicy": {
"classificationMax": "internal",
"citeSources": true,
"allowExternalRetrieval": false,
"allowedRepositories": [
"architecture-records"
],
"maxContextTokens": 12000
},
"modelRouteConstraints": {
"allowHosted": true,
"allowedRoutes": [
"hosted-general-v3"
],
"deniedProviders": [],
"maxLatencyMs": 8000,
"requiredCapabilities": [
"structured-output"
]
},
"allowedTools": [
"document.search.v2"
],
"toolPolicy": {
"defaultDecision": "deny",
"maxCalls": 4,
"allowSideEffects": false,
"requiredPermissionClasses": [
"read"
]
},
"memoryPolicy": {
"readScopes": [
"session"
],
"writeScopes": [],
"writeRequiresApproval": true,
"ttlSeconds": 3600
},
"budget": {
"maxInputTokens": 14000,
"maxOutputTokens": 1200,
"maxToolCalls": 4,
"maxCostUsd": 0.25,
"currency": "USD"
},
"approvalPolicy": {
"mode": "policy-driven",
"requiredFor": [],
"timeoutSeconds": 300,
"authorityRefs": []
},
"outputContract": {
"format": "json-schema",
"schemaRef": "answer-with-citations.v1.json",
"maxBytes": 64000,
"requiresCitations": true
},
"traceSettings": {
"level": "standard",
"redactInputs": true,
"captureToolResults": false,
"samplingDecision": "record-and-sample"
},
"dataClassification": "internal",
"retentionPolicy": {
"policyId": "retention:standard-30d",
"days": 30,
"storeRawInputs": false,
"legalHold": false
},
"metadata": {
"channel": "web"
}
}High-risk request with approval
{
"contractVersion": "aruntime.runtime-request.v1",
"requestId": "req_20260623_002",
"correlationId": "corr_20260623_002",
"idempotencyKey": "idem_refund_case_882",
"timestampUtc": "2026-06-23T14:30:00Z",
"deadlineUtc": "2026-06-23T14:30:20Z",
"actor": {
"type": "user",
"idRef": "user:example"
},
"tenant": {
"idRef": "tenant:demo",
"region": "us-central"
},
"session": {
"idRef": "session:001",
"sequence": 3
},
"taskType": "customer-refund",
"riskLevel": "high",
"input": {
"caseRef": "case:882",
"amountUsd": 125
},
"permissions": [
"read:customer-account",
"write:refund"
],
"contextPolicy": {
"classificationMax": "internal",
"citeSources": true,
"allowExternalRetrieval": false,
"allowedRepositories": [
"architecture-records"
],
"maxContextTokens": 12000
},
"modelRouteConstraints": {
"allowHosted": true,
"allowedRoutes": [
"hosted-general-v3"
],
"deniedProviders": [],
"maxLatencyMs": 8000,
"requiredCapabilities": [
"structured-output"
]
},
"allowedTools": [
"customer.read.v3",
"refund.create.v2"
],
"toolPolicy": {
"defaultDecision": "deny",
"maxCalls": 5,
"allowSideEffects": true,
"requiredPermissionClasses": [
"read",
"financial-high-impact"
]
},
"memoryPolicy": {
"readScopes": [
"session"
],
"writeScopes": [],
"writeRequiresApproval": true,
"ttlSeconds": 3600
},
"budget": {
"maxInputTokens": 14000,
"maxOutputTokens": 1200,
"maxToolCalls": 4,
"maxCostUsd": 1,
"currency": "USD"
},
"approvalPolicy": {
"mode": "always",
"requiredFor": [
"financial-high-impact"
],
"timeoutSeconds": 900,
"authorityRefs": [
"role:refund-approver"
]
},
"outputContract": {
"format": "json-schema",
"schemaRef": "answer-with-citations.v1.json",
"maxBytes": 64000,
"requiresCitations": true
},
"traceSettings": {
"level": "standard",
"redactInputs": true,
"captureToolResults": false,
"samplingDecision": "record-and-sample"
},
"dataClassification": "confidential",
"retentionPolicy": {
"policyId": "retention:financial-365d",
"days": 365,
"storeRawInputs": false,
"legalHold": false
},
"metadata": {
"channel": "web"
}
}Deliberately invalid request
{
"contractVersion": "aruntime.runtime-request.v1",
"requestId": "req_20260623_001",
"correlationId": "corr_20260623_001",
"timestampUtc": "2026-06-23T14:30:00-05:00",
"deadlineUtc": "2026-06-23T14:30:20Z",
"actor": {
"type": "user",
"idRef": "user:example"
},
"tenant": {
"idRef": "tenant:demo",
"region": "us-central"
},
"session": {
"idRef": "session:001",
"sequence": 3
},
"taskType": "answer-with-evidence",
"riskLevel": "urgent",
"input": {
"question": "Summarize the approved architecture record."
},
"permissions": [
"read:approved-architecture"
],
"contextPolicy": {
"classificationMax": "internal",
"citeSources": true,
"allowExternalRetrieval": false,
"allowedRepositories": [
"architecture-records"
],
"maxContextTokens": 12000
},
"modelRouteConstraints": {
"allowHosted": true,
"allowedRoutes": [
"hosted-general-v3"
],
"deniedProviders": [],
"maxLatencyMs": 8000,
"requiredCapabilities": [
"structured-output"
]
},
"allowedTools": [
"document.search.v2"
],
"toolPolicy": {
"defaultDecision": "deny",
"maxCalls": 4,
"allowSideEffects": false,
"requiredPermissionClasses": [
"read"
]
},
"memoryPolicy": {
"readScopes": [
"session"
],
"writeScopes": [],
"writeRequiresApproval": true,
"ttlSeconds": 3600
},
"budget": {
"maxInputTokens": 14000,
"maxOutputTokens": 1200,
"maxToolCalls": 4,
"maxCostUsd": 0.25,
"currency": "USD"
},
"approvalPolicy": {
"mode": "policy-driven",
"requiredFor": [],
"timeoutSeconds": 300,
"authorityRefs": []
},
"outputContract": {
"format": "json-schema",
"schemaRef": "answer-with-citations.v1.json",
"maxBytes": 64000,
"requiresCitations": true
},
"traceSettings": {
"level": "standard",
"redactInputs": true,
"captureToolResults": false,
"samplingDecision": "record-and-sample"
},
"dataClassification": "internal",
"retentionPolicy": {
"policyId": "retention:standard-30d",
"days": 30,
"storeRawInputs": false,
"legalHold": false
},
"metadata": {
"channel": "web"
}
}Reference implementation
The bundled PHP 8.1 example validates admission fields, selects a constrained model route, checks tool permission and approval requirements, performs an idempotent synthetic operation, creates minimized evidence, handles errors, and prints expected JSON output.
Download the runnable PHP example
php examples/php/runtime_pipeline.php