{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "contract:agent-wait/v0/agent-wait-message.schema.json",
"title": "Agent Wait Message",
"description": "Discriminated entry schema for contract: agent-wait/v0. Six message kinds only. Provider-opaque exclusive anchors are distinct from source event IDs. Registration sets carry principal, authn, aggregate limits, and a registration digest. Poll ack/retention is per-registration. The prose standard remains normative for deadline ordering, coverage, fairness, ack/retention, replay, bounds, and revision freeze.",
"oneOf": [
{ "$ref": "#/$defs/registrationSet" },
{ "$ref": "#/$defs/liveWaitRequest" },
{ "$ref": "#/$defs/liveWaitOutcome" },
{ "$ref": "#/$defs/pollCycleRequest" },
{ "$ref": "#/$defs/pollCycleOutcome" },
{ "$ref": "#/$defs/pollCycleAck" }
],
"properties": {
"capabilities": {
"type": "array",
"description": "Host-less capability tokens. Must include the exact opaque agent-wait contract token.",
"items": { "type": "string" },
"contains": { "const": "contract: agent-wait/v0" },
"minItems": 1,
"uniqueItems": true
}
},
"$defs": {
"capabilities": {
"type": "array",
"description": "Host-less capability tokens. Must include the exact opaque agent-wait contract token.",
"items": { "type": "string" },
"contains": { "const": "contract: agent-wait/v0" },
"minItems": 1,
"uniqueItems": true
},
"idToken": {
"type": "string",
"minLength": 1,
"description": "Stable identifier. Never a credential."
},
"actorRef": {
"type": "string",
"minLength": 1,
"pattern": "^[A-Za-z0-9][A-Za-z0-9._:/-]*$",
"description": "Actor identity reference. Never a credential, raw token, or machine-local path."
},
"refToken": {
"type": "string",
"minLength": 1,
"pattern": "^[A-Za-z0-9][A-Za-z0-9._:/-]*$",
"description": "Symbolic reference. Never a credential, raw token, or machine-local path."
},
"rfc3339": {
"type": "string",
"format": "date-time",
"description": "Absolute RFC3339 timestamp."
},
"sha256": {
"type": "string",
"pattern": "^[a-f0-9]{64}$"
},
"digest": {
"type": "object",
"additionalProperties": false,
"required": ["algorithm", "value"],
"properties": {
"algorithm": { "const": "sha256" },
"value": { "$ref": "#/$defs/sha256" }
}
},
"jcsDigest": {
"type": "object",
"additionalProperties": false,
"required": ["canonicalization", "algorithm", "value"],
"properties": {
"canonicalization": { "const": "rfc8785" },
"algorithm": { "const": "sha256" },
"value": { "$ref": "#/$defs/sha256" }
}
},
"anchor": {
"type": "object",
"additionalProperties": false,
"required": ["kind", "value"],
"properties": {
"kind": { "const": "provider_opaque" },
"value": { "$ref": "#/$defs/idToken" }
},
"description": "Provider-opaque exclusive continuation cursor. Distinct from a source event_id. The value MUST NOT be treated as an event identifier."
},
"registrationAnchorMap": {
"type": "object",
"additionalProperties": { "$ref": "#/$defs/anchor" },
"description": "Map keyed by registration_id. Empty object is a first-cycle or no-ack map."
},
"registrationEventMap": {
"type": "object",
"additionalProperties": {
"type": "array",
"uniqueItems": true,
"items": { "$ref": "#/$defs/idToken" }
},
"description": "Map of event id lists keyed by registration_id."
},
"waitBound": {
"type": "object",
"additionalProperties": false,
"required": ["max_events", "max_bytes"],
"properties": {
"max_events": { "type": "integer", "minimum": 0 },
"max_bytes": { "type": "integer", "minimum": 0 }
}
},
"payloadRef": {
"type": "object",
"additionalProperties": false,
"required": ["payload_ref", "content_digest"],
"properties": {
"payload_ref": { "$ref": "#/$defs/refToken" },
"content_digest": { "$ref": "#/$defs/digest" },
"media_type": { "type": "string", "minLength": 1 }
},
"description": "Structured payload reference. payload_ref is never a bare token at the event surface."
},
"outcomeKind": {
"enum": [
"events",
"no_change",
"logical_deadman",
"partial",
"cancelled",
"coverage_degraded",
"refused",
"reauthentication_required",
"failed"
]
},
"reasonOutcomeKind": {
"enum": ["cancelled", "refused", "reauthentication_required", "failed"]
},
"authnMode": {
"enum": ["required", "optional", "disabled"],
"description": "Aggregate authentication posture for the registration set."
},
"baselinePolicy": {
"enum": ["latest", "earliest", "provider_defined"],
"description": "Explicit start-position policy. There is no implicit provider default."
},
"replayStatus": {
"enum": ["fresh", "replay"]
},
"waitEvent": {
"type": "object",
"additionalProperties": false,
"required": [
"event_id",
"registration_id",
"source_instance_ref",
"method_id",
"subject_kind",
"subject_id",
"occurred_at",
"observed_at",
"start_anchor",
"proposed_next_anchor",
"replay_status",
"correlation_id",
"payload"
],
"properties": {
"event_id": { "$ref": "#/$defs/idToken" },
"registration_id": { "$ref": "#/$defs/idToken" },
"source_instance_ref": { "$ref": "#/$defs/refToken" },
"method_id": { "$ref": "#/$defs/idToken" },
"subject_kind": { "$ref": "#/$defs/idToken" },
"subject_id": { "$ref": "#/$defs/idToken" },
"occurred_at": {
"$ref": "#/$defs/rfc3339",
"description": "Provider timestamp. Mapped equivalent of the frozen provider-occurred instant."
},
"observed_at": { "$ref": "#/$defs/rfc3339" },
"start_anchor": { "$ref": "#/$defs/anchor" },
"proposed_next_anchor": { "$ref": "#/$defs/anchor" },
"replay_status": { "$ref": "#/$defs/replayStatus" },
"correlation_id": { "$ref": "#/$defs/idToken" },
"causation_id": { "$ref": "#/$defs/idToken" },
"payload": { "$ref": "#/$defs/payloadRef" },
"delivery_ref": { "$ref": "#/$defs/refToken" },
"activation_ref": { "$ref": "#/$defs/refToken" }
},
"description": "Stable source event identity plus structured payload. event_id is not an exclusive cursor."
},
"coverageArm": {
"type": "object",
"additionalProperties": false,
"required": [
"arm_id",
"registration_id",
"required",
"status",
"degraded",
"start_anchor",
"proposed_next_anchor",
"event_count",
"byte_count"
],
"properties": {
"arm_id": { "$ref": "#/$defs/idToken" },
"registration_id": { "$ref": "#/$defs/idToken" },
"required": { "type": "boolean" },
"status": {
"enum": ["no_change", "events", "observed", "outage", "cursor_uncertain", "deferred"]
},
"degraded": { "type": "boolean" },
"start_anchor": { "$ref": "#/$defs/anchor" },
"proposed_next_anchor": { "$ref": "#/$defs/anchor" },
"event_count": { "type": "integer", "minimum": 0 },
"byte_count": { "type": "integer", "minimum": 0 },
"reason_code": { "$ref": "#/$defs/idToken" }
},
"allOf": [
{
"if": {
"anyOf": [
{
"properties": { "status": { "enum": ["outage", "cursor_uncertain"] } },
"required": ["status"]
},
{ "properties": { "degraded": { "const": true } }, "required": ["degraded"] }
]
},
"then": { "required": ["reason_code"] }
}
]
},
"pollBound": {
"type": "object",
"additionalProperties": false,
"properties": {
"max_events": { "type": "integer", "minimum": 1 },
"max_payload_refs": { "type": "integer", "minimum": 1 },
"max_bytes": { "type": "integer", "minimum": 1 }
}
},
"registration": {
"type": "object",
"additionalProperties": false,
"required": [
"registration_id",
"method_id",
"subject_kind",
"subject_id",
"required",
"source_instance_ref",
"predicate_ref",
"capability_ref",
"lease_expires_at",
"bounds"
],
"properties": {
"registration_id": { "$ref": "#/$defs/idToken" },
"method_id": { "$ref": "#/$defs/idToken" },
"subject_kind": { "$ref": "#/$defs/idToken" },
"subject_id": { "$ref": "#/$defs/idToken" },
"required": { "type": "boolean" },
"source_instance_ref": { "$ref": "#/$defs/refToken" },
"predicate_ref": { "$ref": "#/$defs/refToken" },
"capability_ref": { "$ref": "#/$defs/refToken" },
"lease_expires_at": { "$ref": "#/$defs/rfc3339" },
"bounds": { "$ref": "#/$defs/waitBound" },
"start_anchor": { "$ref": "#/$defs/anchor" },
"baseline_policy": { "$ref": "#/$defs/baselinePolicy" }
},
"oneOf": [
{
"required": ["start_anchor"],
"not": { "required": ["baseline_policy"] }
},
{
"required": ["baseline_policy"],
"not": { "required": ["start_anchor"] }
}
]
},
"registrationSet": {
"type": "object",
"additionalProperties": false,
"required": [
"capabilities",
"message_type",
"message_id",
"correlation_id",
"created_at",
"actor_ref",
"principal_ref",
"waiter_id",
"seat_ref",
"registration_revision",
"logical_deadline",
"authn_mode",
"aggregate_limits",
"registration_digest",
"registrations"
],
"properties": {
"capabilities": { "$ref": "#/$defs/capabilities" },
"message_type": { "const": "registration_set" },
"message_id": { "$ref": "#/$defs/idToken" },
"correlation_id": { "$ref": "#/$defs/idToken" },
"created_at": { "$ref": "#/$defs/rfc3339" },
"actor_ref": { "$ref": "#/$defs/actorRef" },
"principal_ref": { "$ref": "#/$defs/actorRef" },
"causation_id": { "$ref": "#/$defs/idToken" },
"grant_ref": { "$ref": "#/$defs/refToken" },
"verification_receipt_ref": { "$ref": "#/$defs/refToken" },
"policy_decision_ref": { "$ref": "#/$defs/refToken" },
"waiter_id": { "$ref": "#/$defs/idToken" },
"seat_ref": { "$ref": "#/$defs/refToken" },
"registration_revision": { "$ref": "#/$defs/idToken" },
"logical_deadline": { "$ref": "#/$defs/rfc3339" },
"authn_mode": { "$ref": "#/$defs/authnMode" },
"aggregate_limits": { "$ref": "#/$defs/waitBound" },
"registration_digest": { "$ref": "#/$defs/jcsDigest" },
"registrations": {
"type": "array",
"minItems": 1,
"items": { "$ref": "#/$defs/registration" }
}
}
},
"liveWaitRequest": {
"type": "object",
"additionalProperties": false,
"required": [
"capabilities",
"message_type",
"message_id",
"correlation_id",
"created_at",
"actor_ref",
"waiter_id",
"registration_set_ref",
"registration_revision",
"logical_deadline",
"run_deadline"
],
"properties": {
"capabilities": { "$ref": "#/$defs/capabilities" },
"message_type": { "const": "live_wait_request" },
"message_id": { "$ref": "#/$defs/idToken" },
"correlation_id": { "$ref": "#/$defs/idToken" },
"created_at": { "$ref": "#/$defs/rfc3339" },
"actor_ref": { "$ref": "#/$defs/actorRef" },
"causation_id": { "$ref": "#/$defs/idToken" },
"grant_ref": { "$ref": "#/$defs/refToken" },
"verification_receipt_ref": { "$ref": "#/$defs/refToken" },
"policy_decision_ref": { "$ref": "#/$defs/refToken" },
"waiter_id": { "$ref": "#/$defs/idToken" },
"registration_set_ref": { "$ref": "#/$defs/idToken" },
"registration_revision": { "$ref": "#/$defs/idToken" },
"logical_deadline": { "$ref": "#/$defs/rfc3339" },
"run_deadline": { "$ref": "#/$defs/rfc3339" }
}
},
"liveWaitOutcome": {
"type": "object",
"additionalProperties": false,
"required": [
"capabilities",
"message_type",
"message_id",
"correlation_id",
"created_at",
"actor_ref",
"waiter_id",
"request_ref",
"completed_at",
"outcome_kind"
],
"properties": {
"capabilities": { "$ref": "#/$defs/capabilities" },
"message_type": { "const": "live_wait_outcome" },
"message_id": { "$ref": "#/$defs/idToken" },
"correlation_id": { "$ref": "#/$defs/idToken" },
"created_at": { "$ref": "#/$defs/rfc3339" },
"actor_ref": { "$ref": "#/$defs/actorRef" },
"causation_id": { "$ref": "#/$defs/idToken" },
"grant_ref": { "$ref": "#/$defs/refToken" },
"verification_receipt_ref": { "$ref": "#/$defs/refToken" },
"policy_decision_ref": { "$ref": "#/$defs/refToken" },
"waiter_id": { "$ref": "#/$defs/idToken" },
"request_ref": { "$ref": "#/$defs/idToken" },
"completed_at": { "$ref": "#/$defs/rfc3339" },
"logical_deadline": { "$ref": "#/$defs/rfc3339" },
"outcome_kind": { "$ref": "#/$defs/outcomeKind" },
"events": {
"type": "array",
"items": { "$ref": "#/$defs/waitEvent" }
},
"proposed_next_anchor": { "$ref": "#/$defs/anchor" },
"coverage_complete": { "type": "boolean" },
"arms": {
"type": "array",
"minItems": 1,
"items": { "$ref": "#/$defs/coverageArm" }
},
"reason_code": { "$ref": "#/$defs/idToken" }
},
"allOf": [
{
"if": {
"properties": { "outcome_kind": { "const": "events" } },
"required": ["outcome_kind"]
},
"then": {
"required": ["events", "proposed_next_anchor"],
"properties": { "events": { "minItems": 1 } }
}
},
{
"if": {
"properties": { "outcome_kind": { "enum": ["no_change", "logical_deadman"] } },
"required": ["outcome_kind"]
},
"then": {
"required": ["events", "coverage_complete", "arms", "logical_deadline"],
"properties": { "events": { "maxItems": 0 } }
}
},
{
"if": {
"properties": { "outcome_kind": { "const": "partial" } },
"required": ["outcome_kind"]
},
"then": {
"required": ["events", "arms", "coverage_complete"]
}
},
{
"if": {
"properties": { "outcome_kind": { "const": "coverage_degraded" } },
"required": ["outcome_kind"]
},
"then": {
"required": ["arms", "coverage_complete"]
}
},
{
"if": {
"properties": { "outcome_kind": { "$ref": "#/$defs/reasonOutcomeKind" } },
"required": ["outcome_kind"]
},
"then": { "required": ["reason_code"] }
}
]
},
"pollCycleRequest": {
"type": "object",
"additionalProperties": false,
"required": [
"capabilities",
"message_type",
"message_id",
"correlation_id",
"created_at",
"actor_ref",
"waiter_id",
"registration_set_ref",
"registration_revision",
"logical_deadline",
"run_deadline",
"required_arms",
"fairness_cursor",
"acknowledged_anchors",
"activation_ref",
"cycle_id"
],
"properties": {
"capabilities": { "$ref": "#/$defs/capabilities" },
"message_type": { "const": "poll_cycle_request" },
"message_id": { "$ref": "#/$defs/idToken" },
"correlation_id": { "$ref": "#/$defs/idToken" },
"created_at": { "$ref": "#/$defs/rfc3339" },
"actor_ref": { "$ref": "#/$defs/actorRef" },
"causation_id": { "$ref": "#/$defs/idToken" },
"grant_ref": { "$ref": "#/$defs/refToken" },
"verification_receipt_ref": { "$ref": "#/$defs/refToken" },
"policy_decision_ref": { "$ref": "#/$defs/refToken" },
"waiter_id": { "$ref": "#/$defs/idToken" },
"registration_set_ref": { "$ref": "#/$defs/idToken" },
"registration_revision": { "$ref": "#/$defs/idToken" },
"logical_deadline": { "$ref": "#/$defs/rfc3339" },
"run_deadline": { "$ref": "#/$defs/rfc3339" },
"required_arms": {
"type": "array",
"minItems": 1,
"uniqueItems": true,
"items": { "$ref": "#/$defs/idToken" }
},
"fairness_cursor": { "$ref": "#/$defs/idToken" },
"acknowledged_anchors": { "$ref": "#/$defs/registrationAnchorMap" },
"activation_ref": { "$ref": "#/$defs/refToken" },
"cycle_id": { "$ref": "#/$defs/idToken" },
"bound": { "$ref": "#/$defs/pollBound" }
}
},
"pollCycleOutcome": {
"type": "object",
"additionalProperties": false,
"required": [
"capabilities",
"message_type",
"message_id",
"correlation_id",
"created_at",
"actor_ref",
"waiter_id",
"request_ref",
"completed_at",
"logical_deadline",
"outcome_kind",
"events",
"coverage_complete",
"arms",
"retained_through",
"retained_events",
"proposed_next_anchors",
"fairness_cursor",
"next_fairness_cursor"
],
"properties": {
"capabilities": { "$ref": "#/$defs/capabilities" },
"message_type": { "const": "poll_cycle_outcome" },
"message_id": { "$ref": "#/$defs/idToken" },
"correlation_id": { "$ref": "#/$defs/idToken" },
"created_at": { "$ref": "#/$defs/rfc3339" },
"actor_ref": { "$ref": "#/$defs/actorRef" },
"causation_id": { "$ref": "#/$defs/idToken" },
"grant_ref": { "$ref": "#/$defs/refToken" },
"verification_receipt_ref": { "$ref": "#/$defs/refToken" },
"policy_decision_ref": { "$ref": "#/$defs/refToken" },
"waiter_id": { "$ref": "#/$defs/idToken" },
"request_ref": { "$ref": "#/$defs/idToken" },
"completed_at": { "$ref": "#/$defs/rfc3339" },
"logical_deadline": { "$ref": "#/$defs/rfc3339" },
"outcome_kind": { "$ref": "#/$defs/outcomeKind" },
"events": {
"type": "array",
"items": { "$ref": "#/$defs/waitEvent" }
},
"coverage_complete": { "type": "boolean" },
"arms": {
"type": "array",
"minItems": 1,
"items": { "$ref": "#/$defs/coverageArm" }
},
"retained_through": { "$ref": "#/$defs/registrationAnchorMap" },
"retained_events": { "$ref": "#/$defs/registrationEventMap" },
"proposed_next_anchors": { "$ref": "#/$defs/registrationAnchorMap" },
"fairness_cursor": { "$ref": "#/$defs/idToken" },
"next_fairness_cursor": { "$ref": "#/$defs/idToken" },
"acknowledged_anchors": { "$ref": "#/$defs/registrationAnchorMap" },
"bound": { "$ref": "#/$defs/pollBound" },
"reason_code": { "$ref": "#/$defs/idToken" }
},
"allOf": [
{
"if": {
"properties": { "outcome_kind": { "$ref": "#/$defs/reasonOutcomeKind" } },
"required": ["outcome_kind"]
},
"then": { "required": ["reason_code"] }
}
]
},
"pollCycleAck": {
"type": "object",
"additionalProperties": false,
"required": [
"capabilities",
"message_type",
"message_id",
"correlation_id",
"created_at",
"actor_ref",
"waiter_id",
"outcome_ref",
"committed_anchors",
"retained_events"
],
"properties": {
"capabilities": { "$ref": "#/$defs/capabilities" },
"message_type": { "const": "poll_cycle_ack" },
"message_id": { "$ref": "#/$defs/idToken" },
"correlation_id": { "$ref": "#/$defs/idToken" },
"created_at": { "$ref": "#/$defs/rfc3339" },
"actor_ref": { "$ref": "#/$defs/actorRef" },
"causation_id": { "$ref": "#/$defs/idToken" },
"grant_ref": { "$ref": "#/$defs/refToken" },
"verification_receipt_ref": { "$ref": "#/$defs/refToken" },
"policy_decision_ref": { "$ref": "#/$defs/refToken" },
"waiter_id": { "$ref": "#/$defs/idToken" },
"outcome_ref": { "$ref": "#/$defs/idToken" },
"committed_anchors": { "$ref": "#/$defs/registrationAnchorMap" },
"retained_events": { "$ref": "#/$defs/registrationEventMap" }
}
}
}
}