{"ok":true,"tool":"workflow-checkpoint","module_version":"1.1.0","result":{"slug":"workflow-checkpoint","name":"Opaque Workflow Checkpoint","version":"1.1.0","category":"workflow-reliability","status":"beta","mode":"atomic","summary":"Fence and recover an opaque external workflow without claiming external proof.","description":"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.","when_to_use":["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."],"tested_with":["Valkey 8 atomic Lua","100 concurrent claim contenders","MCP Streamable HTTP"],"input_schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","oneOf":[{"type":"object","properties":{"namespace":{"type":"string","minLength":38,"maxLength":77,"pattern":"^[a-zA-Z0-9._-]{1,40}:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"Private workflow namespace formatted as <scope>:<fresh UUID v4>. Generate a new UUID for each independent workflow and share it only with participating agents."},"workflow_key":{"type":"string","minLength":16,"maxLength":256},"holder":{"type":"string","minLength":16,"maxLength":128},"claim_ttl_seconds":{"type":"integer","minimum":60,"maximum":3600},"state_ttl_seconds":{"type":"integer","minimum":60,"maximum":3600},"retry_failed":{"type":"boolean"},"action":{"type":"string","const":"claim"}},"required":["namespace","workflow_key","holder","claim_ttl_seconds","state_ttl_seconds","retry_failed","action"],"additionalProperties":false},{"type":"object","properties":{"namespace":{"type":"string","minLength":38,"maxLength":77,"pattern":"^[a-zA-Z0-9._-]{1,40}:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"Private workflow namespace formatted as <scope>:<fresh UUID v4>. Generate a new UUID for each independent workflow and share it only with participating agents."},"workflow_key":{"type":"string","minLength":16,"maxLength":256},"holder":{"type":"string","minLength":16,"maxLength":128},"expected_generation":{"type":"integer","minimum":1,"maximum":16},"from_stage":{"type":"string","enum":["claimed","external_result_uncertain","caller_verified","failed","compensated"]},"to_stage":{"type":"string","enum":["claimed","external_result_uncertain","caller_verified","failed","compensated"]},"observation_key":{"type":"string","minLength":16,"maxLength":128},"evidence_type":{"anyOf":[{"type":"string","enum":["provider_idempotency_result","atomic_unique_result","stable_marker_readback","conditional_write_result","delivery_status","durable_result_readback","manual_review"]},{"type":"null"}]},"evidence_fingerprint":{"anyOf":[{"type":"string","pattern":"^hmac-sha256:[a-f0-9]{64}$"},{"type":"null"}]},"action":{"type":"string","const":"transition"}},"required":["namespace","workflow_key","holder","expected_generation","from_stage","to_stage","observation_key","evidence_type","evidence_fingerprint","action"],"additionalProperties":false},{"type":"object","properties":{"namespace":{"type":"string","minLength":38,"maxLength":77,"pattern":"^[a-zA-Z0-9._-]{1,40}:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"Private workflow namespace formatted as <scope>:<fresh UUID v4>. Generate a new UUID for each independent workflow and share it only with participating agents."},"workflow_key":{"type":"string","minLength":16,"maxLength":256},"action":{"type":"string","const":"status"}},"required":["namespace","workflow_key","action"],"additionalProperties":false},{"type":"object","properties":{"namespace":{"type":"string","minLength":38,"maxLength":77,"pattern":"^[a-zA-Z0-9._-]{1,40}:[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"Private workflow namespace formatted as <scope>:<fresh UUID v4>. Generate a new UUID for each independent workflow and share it only with participating agents."},"workflow_key":{"type":"string","minLength":16,"maxLength":256},"holder":{"type":"string","minLength":16,"maxLength":128},"expected_generation":{"type":"integer","minimum":1,"maximum":16},"action":{"type":"string","const":"abandon"}},"required":["namespace","workflow_key","holder","expected_generation","action"],"additionalProperties":false}]},"output_schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"action":{"type":"string","enum":["claim","transition","status","abandon"]},"workflow_hash":{"type":"string","pattern":"^hmac-sha256:[a-f0-9]{64}$"},"observed_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"stage":{"type":"string","enum":["claimed","external_result_uncertain","caller_verified","failed","compensated"]},"generation":{"type":"integer","minimum":1,"maximum":16},"acquired":{"type":"boolean"},"recovered":{"type":"boolean"},"reused":{"type":"boolean"},"recovery_required":{"type":"boolean"},"transitioned":{"type":"boolean"},"observation_replayed":{"type":"boolean"},"abandoned":{"type":"boolean"},"claim_active":{"type":"boolean"},"held_by_caller":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"claim_expires_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},{"type":"null"}]},"state_expires_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"claim_ttl_seconds_remaining":{"anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}]},"state_ttl_seconds_remaining":{"type":"integer","minimum":0,"maximum":9007199254740991},"evidence_type":{"anyOf":[{"type":"string","enum":["provider_idempotency_result","atomic_unique_result","stable_marker_readback","conditional_write_result","delivery_status","durable_result_readback","manual_review"]},{"type":"null"}]},"evidence_fingerprint_present":{"type":"boolean"},"retry_failed_allowed":{"type":"boolean"},"allowed_next_actions":{"maxItems":4,"type":"array","items":{"type":"string","enum":["claim","transition","status","abandon"]}},"minimum_action_safety_margin_seconds":{"type":"number","const":15},"external_proof":{"type":"boolean","const":false}},"required":["action","workflow_hash","observed_at","stage","generation","acquired","recovered","reused","recovery_required","transitioned","observation_replayed","abandoned","claim_active","held_by_caller","claim_expires_at","state_expires_at","claim_ttl_seconds_remaining","state_ttl_seconds_remaining","evidence_type","evidence_fingerprint_present","retry_failed_allowed","allowed_next_actions","minimum_action_safety_margin_seconds","external_proof"],"additionalProperties":false},"payment":{"kind":"free"},"side_effects":["Claim creates or recovers an expiring owned generation.","Transition records one bounded caller assertion and may finalize a generation.","Abandon clears only a pre-action claim held by the caller."],"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.","limits":{"min_claim_ttl_seconds":60,"max_claim_ttl_seconds":3600,"max_state_ttl_seconds":3600,"max_generations":16,"max_observations":32,"minimum_action_safety_margin_seconds":15,"max_client_requests_per_minute":30,"max_global_requests_per_minute":120},"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}]},"execution":{"errors":[{"code":"INVALID_INPUT","retryable":false,"charged":false,"recovery":"Correct the request to match input_schema."},{"code":"CHECKPOINT_NOT_FOUND","retryable":false,"recovery":"Claim the known opaque workflow identity before reading or mutating it.","charged":false},{"code":"CHECKPOINT_NOT_HELD","retryable":false,"recovery":"Stand down or recover only after the active claim expires.","charged":false},{"code":"CHECKPOINT_TERMINAL","retryable":false,"recovery":"Read the final state; use a new logical workflow identity for new work.","charged":false},{"code":"STALE_GENERATION","retryable":false,"recovery":"Read current status and replan against the returned generation.","charged":false},{"code":"INVALID_TRANSITION","retryable":false,"recovery":"Follow the published stage transition graph and uncertainty rules.","charged":false},{"code":"OBSERVATION_CONFLICT","retryable":false,"recovery":"Use the observation key only for its original transition body.","charged":false},{"code":"CONFIGURATION_CONFLICT","retryable":false,"recovery":"Reuse the checkpoint's fixed TTL and retry configuration.","charged":false},{"code":"CHECKPOINT_LIMIT_REACHED","retryable":false,"recovery":"Wait for bounded state expiry and review why the workflow exhausted its limits.","charged":false},{"code":"TOOL_PAUSED","retryable":true,"charged":false,"recovery":"Wait for the operator to resume the tool."},{"code":"RATE_LIMITED","retryable":true,"charged":false,"recovery":"Retry after the response Retry-After interval."},{"code":"DEPENDENCY_UNAVAILABLE","retryable":true,"charged":false,"recovery":"Retry with the same idempotency identity."}],"idempotency":{"required":true,"required_by_action":{"claim":true,"transition":true,"status":false,"abandon":true},"mock_or_unpaid_header":"Idempotency-Key","x402_extension":null,"replay_retention":"up to 24 hours"}},"endpoints":{"describe":"/v1/tools/workflow-checkpoint","execute":"/v1/tools/workflow-checkpoint"}},"meta":{"request_id":"req_caafe4101532480c895d0a47d6548fa5","observed_at":"2026-07-26T03:16:41.449Z"}}