Opaque Workflow Checkpoint

Coordinates one bounded workflow generation through claimed, uncertain, caller-verified, retry-gated failure, or compensated state. It stores only keyed identity digests, bounded evidence metadata, and expiring caller assertions; it never contacts or attests to the external service.

Use when

An external side effect needs an expiring owned generation plus explicit uncertain, caller-verified, failed, or compensated recovery state.
Workers must recover after a crash without treating a lock or seen stamp as proof that the external action completed.

Do not use when

A permanent audit log, cross-plugin transaction, or external exactly-once guarantee is required.
An ordinary one-time low-risk operation does not need recovery coordination.
The request is simply to create one note or record now.

Invocation contract

HTTP: /v1/tools/workflow-checkpoint
Version: 1.1.0
Mode: atomic
Idempotency: required
Retention: Keyed HMAC digests, stage, generation, TTL configuration, and at most 32 bounded observation records remain in Valkey for at most 3,600 seconds. Raw namespace, workflow key, holder, observation key, and external content are never stored or returned.
Tested with: Valkey 8 atomic Lua, 100 concurrent claim contenders, MCP Streamable HTTP

Positive and negative examples

{
  "input": {
    "action": "claim",
    "namespace": "notion-import:31a0dca1-fd36-4748-a5c5-91d63a611a09",
    "workflow_key": "w_01J9N7K4Y8Q2M5T6R3P0S1U4V7",
    "holder": "h_01J9N7M1A2B3C4D5E6F7G8H9J0",
    "claim_ttl_seconds": 120,
    "state_ttl_seconds": 600,
    "retry_failed": false
  },
  "output": {
    "action": "claim",
    "workflow_hash": "hmac-sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "observed_at": "2026-07-25T12:00:00.000Z",
    "stage": "claimed",
    "generation": 1,
    "acquired": true,
    "recovered": false,
    "reused": false,
    "recovery_required": false,
    "transitioned": false,
    "observation_replayed": false,
    "abandoned": false,
    "claim_active": true,
    "held_by_caller": true,
    "claim_expires_at": "2026-07-25T12:02:00.000Z",
    "state_expires_at": "2026-07-25T12:10:00.000Z",
    "claim_ttl_seconds_remaining": 120,
    "state_ttl_seconds_remaining": 600,
    "evidence_type": null,
    "evidence_fingerprint_present": false,
    "retry_failed_allowed": false,
    "allowed_next_actions": [
      "transition",
      "status",
      "abandon"
    ],
    "minimum_action_safety_margin_seconds": 15,
    "external_proof": false
  },
  "negative": [
    {
      "scenario": "A permanent audit log, cross-plugin transaction, or external exactly-once guarantee is required.",
      "expected_error": "INVALID_INPUT",
      "charged": false
    }
  ]
}

Deterministic errors

Code	Retry	Charged	Recovery
INVALID_INPUT	false	false	Correct the request to match input_schema.
CHECKPOINT_NOT_FOUND	false	false	Claim the known opaque workflow identity before reading or mutating it.
CHECKPOINT_NOT_HELD	false	false	Stand down or recover only after the active claim expires.
CHECKPOINT_TERMINAL	false	false	Read the final state; use a new logical workflow identity for new work.
STALE_GENERATION	false	false	Read current status and replan against the returned generation.
INVALID_TRANSITION	false	false	Follow the published stage transition graph and uncertainty rules.
OBSERVATION_CONFLICT	false	false	Use the observation key only for its original transition body.
CONFIGURATION_CONFLICT	false	false	Reuse the checkpoint's fixed TTL and retry configuration.
CHECKPOINT_LIMIT_REACHED	false	false	Wait for bounded state expiry and review why the workflow exhausted its limits.
TOOL_PAUSED	true	false	Wait for the operator to resume the tool.
RATE_LIMITED	true	false	Retry after the response Retry-After interval.
DEPENDENCY_UNAVAILABLE	true	false	Retry with the same idempotency identity.

Full machine manifest

The HTTP, OpenAPI, MCP, llms.txt, and ARD descriptions are generated from this same registry record.

Open JSON manifest →