Deferred Operation v1¶
Source schema: doc/schemas/deferred-operation.v1.schema.json
Initial 202 Accepted control payload for an explicitly opted-in deferred operation. This is not domain data; it tells the caller that processing is suspended and may be resumed by polling or a stored continuation.
Governing Basis¶
Project Lineage¶
Fields¶
| Field | Required | Shape | Description |
|---|---|---|---|
schema |
yes |
const: deferred-operation.v1 |
Schema tag for the initial deferred operation payload. |
schema/v |
yes |
const: 1 |
Schema version. |
status |
yes |
const: deferred |
Initial control status. Callers MUST suspend downstream domain processing instead of treating this payload as ordinary output. |
operation/id |
yes |
string | Stable id for the deferred operation. Implementations SHOULD derive it deterministically from the operation kind and an idempotency seed when duplicate suppression matters. |
operation/kind |
yes |
string | Operation class that owns the continuation semantics, e.g. sensorium.directive.invoke or json-e-flow.step. |
created_at |
yes |
string | RFC 3339 timestamp at which the host accepted the deferred operation. |
retry_after_seconds |
yes |
integer | Host-clamped lower bound before the caller or scheduler should poll/resume the operation. It maps to HTTP Retry-After for HTTP surfaces. |
expires_at |
yes |
string | Host-clamped absolute deadline after which the operation MUST be treated as expired if no terminal result exists. |
status_href |
no |
string | Optional local status endpoint for polling. Omitted when the caller must resume through a stored continuation rather than HTTP polling. |
cancel_href |
no |
string | Optional local cancel endpoint. Absence means cancellation is unsupported for this operation kind. |
cancel/unavailable-reason |
no |
string | Reason cancellation is not available for this operation. Exactly one of cancel_href or cancel/unavailable-reason MUST be present. |
correlation/id |
no |
string | Optional correlation id from the parent flow or workflow. |
audit/outcome-ref |
no |
string | Optional reference to the host/runtime audit outcome that recorded acceptance of this deferred operation. |
continuation |
no |
object | Explicit serializable continuation context. It is a host/runtime value, not a captured language stack. |
diagnostics |
no |
array | Optional diagnostics for operator and caller visibility. |
extensions |
no |
object | Open extension map for experimental or deployment-local metadata. Stable protocol fields MUST be promoted to first-class schema properties. |
| ## Field Semantics |
schema¶
- Required:
yes - Shape: const:
deferred-operation.v1
Schema tag for the initial deferred operation payload.
schema/v¶
- Required:
yes - Shape: const:
1
Schema version.
status¶
- Required:
yes - Shape: const:
deferred
Initial control status. Callers MUST suspend downstream domain processing instead of treating this payload as ordinary output.
operation/id¶
- Required:
yes - Shape: string
Stable id for the deferred operation. Implementations SHOULD derive it deterministically from the operation kind and an idempotency seed when duplicate suppression matters.
operation/kind¶
- Required:
yes - Shape: string
Operation class that owns the continuation semantics, e.g. sensorium.directive.invoke or json-e-flow.step.
created_at¶
- Required:
yes - Shape: string
RFC 3339 timestamp at which the host accepted the deferred operation.
retry_after_seconds¶
- Required:
yes - Shape: integer
Host-clamped lower bound before the caller or scheduler should poll/resume the operation. It maps to HTTP Retry-After for HTTP surfaces.
expires_at¶
- Required:
yes - Shape: string
Host-clamped absolute deadline after which the operation MUST be treated as expired if no terminal result exists.
status_href¶
- Required:
no - Shape: string
Optional local status endpoint for polling. Omitted when the caller must resume through a stored continuation rather than HTTP polling.
cancel_href¶
- Required:
no - Shape: string
Optional local cancel endpoint. Absence means cancellation is unsupported for this operation kind.
cancel/unavailable-reason¶
- Required:
no - Shape: string
Reason cancellation is not available for this operation. Exactly one of cancel_href or cancel/unavailable-reason MUST be present.
correlation/id¶
- Required:
no - Shape: string
Optional correlation id from the parent flow or workflow.
audit/outcome-ref¶
- Required:
no - Shape: string
Optional reference to the host/runtime audit outcome that recorded acceptance of this deferred operation.
continuation¶
- Required:
no - Shape: object
Explicit serializable continuation context. It is a host/runtime value, not a captured language stack.
diagnostics¶
- Required:
no - Shape: array
Optional diagnostics for operator and caller visibility.
extensions¶
- Required:
no - Shape: object
Open extension map for experimental or deployment-local metadata. Stable protocol fields MUST be promoted to first-class schema properties.