Deferred Operation Status v2

Source schema: doc/schemas/deferred-operation-status.v2.schema.json

Versioned private status preserving v1 lifecycle and adding typed bounded replacement progress. Discovery progress and terminal results are private; remove them, diagnostics, extensions and their derived digests BEFORE durable status/event hashing. Every read requires current authority. V1 remains unchanged. Revision monotonicity and actual candidate encoded-byte budgets are host invariants.

Governing Basis

• doc/project/40-proposals/055-bounded-deferred-operation-contract.md

Project Lineage

Fields

Field	Required	Shape	Description
schema	yes	const: deferred-operation-status.v2	Schema tag for deferred operation status payloads.
schema/v	yes	const: 2	Schema version.
status	yes	enum: pending, running, completed, failed, timed-out, cancelled, expired, unknown	Lifecycle status. pending/running suspend processing; completed resumes with result; failed/timed-out/cancelled/expired/unknown are terminal failures unless the parent runtime has an explicit retry policy.
operation/id	yes	string	Id from the initial deferred-operation.v1 payload.
operation/kind	yes	string	Operation class that owns the continuation semantics.
updated_at	yes	string	RFC 3339 timestamp at which this status was produced.
retry_after_seconds	no	integer	Host-clamped lower bound before the next poll/resume attempt. Required by convention for pending/running statuses that are not immediately resumable.
expires_at	no	string	Current absolute expiry deadline, if still applicable.
causal/context	no	ref: causal-context.v1.schema.json	Optional canonical P081 causal context preserved on status and continuation responses.
result	no	unspecified	Domain result only for completed status. It MUST be validated by the owning operation kind before downstream use.
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.
progress	no	object

Definitions

Definition	Shape	Description
discovery-progress	object

Conditional Rules

Rule 1

When:

{
  "properties": {
    "status": {
      "const": "completed"
    }
  },
  "required": [
    "status"
  ]
}

Then:

{
  "required": [
    "result"
  ]
}

Rule 2

When:

{
  "properties": {
    "operation/kind": {
      "const": "sensorium.device-discovery"
    }
  },
  "required": [
    "operation/kind"
  ]
}

Then:

{
  "properties": {
    "operation/id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 132,
      "pattern": "^deferred:sensorium.device-discovery:[A-Za-z0-9_-]{16,96}$"
    },
    "result": {
      "$ref": "sensorium-device-discovery-result.v1.schema.json"
    }
  }
}

Rule 3

When:

{
  "required": [
    "progress"
  ]
}

Then:

{
  "properties": {
    "operation/kind": {
      "const": "sensorium.device-discovery"
    }
  }
}

Rule 4

When:

{
  "properties": {
    "operation/kind": {
      "const": "sensorium.device-discovery"
    },
    "status": {
      "not": {
        "const": "completed"
      }
    }
  },
  "required": [
    "operation/kind",
    "status"
  ]
}

Then:

{
  "not": {
    "required": [
      "result"
    ]
  }
}

Rule 5

When:

{
  "properties": {
    "operation/kind": {
      "const": "sensorium.device-discovery"
    },
    "status": {
      "const": "completed"
    }
  },
  "required": [
    "operation/kind",
    "status",
    "progress"
  ]
}

Then:

{
  "properties": {
    "progress": {
      "properties": {
        "data": {
          "properties": {
            "phase": {
              "const": "stopped"
            }
          }
        }
      }
    }
  }
}

Field Semantics

schema

• Required: yes
• Shape: const: deferred-operation-status.v2

Schema tag for deferred operation status payloads.

schema/v

• Required: yes
• Shape: const: 2

Schema version.

status

• Required: yes
• Shape: enum: pending, running, completed, failed, timed-out, cancelled, expired, unknown

Lifecycle status. pending/running suspend processing; completed resumes with result; failed/timed-out/cancelled/expired/unknown are terminal failures unless the parent runtime has an explicit retry policy.

operation/id

• Required: yes
• Shape: string

Id from the initial deferred-operation.v1 payload.

operation/kind

• Required: yes
• Shape: string

Operation class that owns the continuation semantics.

updated_at

• Required: yes
• Shape: string

RFC 3339 timestamp at which this status was produced.

retry_after_seconds

• Required: no
• Shape: integer

Host-clamped lower bound before the next poll/resume attempt. Required by convention for pending/running statuses that are not immediately resumable.

expires_at

• Required: no
• Shape: string

Current absolute expiry deadline, if still applicable.

causal/context

• Required: no
• Shape: ref: causal-context.v1.schema.json

Optional canonical P081 causal context preserved on status and continuation responses.

result

• Required: no
• Shape: unspecified

Domain result only for completed status. It MUST be validated by the owning operation kind before downstream use.

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.

progress

• Required: no
• Shape: object

Definition Semantics

$defs.discovery-progress

• Shape: object