feat(bap): bind lifecycle receipts to idempotency keys

[seonghobae]

Buyer-visible boundary

This is the next bounded slice of #200, stacked on the independently resolved current head of #208.

• live base BAP branch/head: feat/bap-task-lifecycle / e41d3be4c290c4e434aac33d777e511dfb94e03d;
• protected main: b05d5acca82b9d916ada2c8e82f59f92a89817e1;
• exact current branch head: 6ce74587dcfeede71ad6ceea94fe5c72dc0f244a.

The BAP lifecycle owns an immutable in-memory command receipt binding a bounded caller-supplied tenant namespace, idempotency key, task identifier, lifecycle event, and accepted transition. Exact replay requires exact retry metadata and exact equality with the lifecycle's most recently accepted transition. Ambiguous, stale, foreign, divergent-history, or state-only restored snapshots fail closed without a second lifecycle mutation.

This branch exposes storage-neutral typed seams needed to reconstruct both sides of that replay identity from persisted primitive fields: BapTaskTransition::restore(...) revalidates an accepted transition against the lifecycle state machine; BapTaskLifecycle::restore_with_transition(...) requires exact validated last-transition evidence for every non-created snapshot; and BapCommandReceipt::restore(...) revalidates bounded retry identifiers before reconstructing the immutable receipt. The persistence boundary remains responsible for integrity/authenticity of supplied evidence and for atomicity with any external side effect.

Test-first repair lineage

The receipt/recovery contract covers exact retry, metadata conflicts, foreign lifecycle reuse, stale reuse after lifecycle advancement, same-state/different-sequence reuse, divergent histories, identifier validation, Debug redaction, state-only recovery refusing replay, transition reconstruction, transition-backed lifecycle restoration, and persisted receipt reconstruction.

A commercial recovery defect was reproduced earlier on this canonical branch: persisted transition/lifecycle state could be reconstructed through the public typed API, but a persisted BapCommandReceipt could not, so true cross-process replay was impossible. Test-only RED head 794e532dd70c1f03416b87016ec8f10d565ee6cc failed with the expected missing-API error; production repair df89f56a7976447da76214c7d8300633d600639d added the restore boundary while reusing fail-closed retry-identity validation. Those RED/repair heads remain historical lineage only.

The current stack reconstruction non-destructively merged live #208 head e41d3be4c290c4e434aac33d777e511dfb94e03d into the existing #211 branch while preserving the unique idempotency/recovery production code, tests, API/TRD/traceability changes, and the live parent's newer documentation. Against the live parent, the exact current head is 0 behind and its diff is limited to the intended BAP receipt/recovery boundary and documentation.

Exact-current verification

On unchanged exact head 6ce74587dcfeede71ad6ceea94fe5c72dc0f244a against exact live base e41d3be4c290c4e434aac33d777e511dfb94e03d:

• CI run 32905311901 / Rust contracts job 97987976065: success;
• CI run 32905311901 / Production coverage job 97987975883: success, including the repository's exact owned-production function/line/region/branch coverage enforcement;
• Dependabot configuration validation: success;
• fresh formal review inventory contains no submitted reviews;
• fresh inline review inventory contains no review threads; and
• exact-head workflow inventory currently exposes this CI evidence only. Same-head SAST, Security Scan, Manifest V3, Noema, and Strix results are absent and are not claimed.

No predecessor-head check, scanner result, review, status, comment, synthetic merge, or model output transfers to this head or counts as independent approval.

Safety and truth boundary

This remains an in-memory lifecycle/idempotency primitive plus typed recovery-validation/reconstruction seams. It does not authenticate the caller or tenant, authorize an operation, persist receipts or transition evidence, authenticate persisted evidence, provide durable concurrent deduplication or locking, atomically couple receipt storage to browser/network side effects, or reconcile ambiguous external outcomes. A durable owner must persist receipt + exact transition evidence atomically at the appropriate production boundary, authenticate that evidence on restore, preserve policy/tenant/session authority, and reconcile uncertain side effects before commercial crash recovery can be claimed.

Keep this PR Draft while prerequisite #208 remains active. No workflow, secret, governance, release, tag, publish, approval, Ready-state, or merge mutation is included.

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}