# Durable deploy request acknowledgement — request

**Status:** complete and installed on 2026-08-16 at `c510d7f9`. Focused failure injection
passed for every terminal step. Installed deployment finished with stamp `c510d7f9…`,
`queue_before=0`, `queue_after=0`, and `restarted:none`; proof log:
`~/.cache/overdeck/queue-ack-installed-1786882213.log`.

**Owner-visible evidence first:** an injected failure at each terminal deploy step leaves the
original `req-*` files in the queue; a successful installed deploy reports completion and removes
exactly the request snapshot it covered. A later request is never removed by the earlier run.

**Goal:** a deploy request remains durable until the deployment has completed every fail-closed
terminal step and recorded the full successful commit stamp. Today the full path removes its queue
snapshot before live-report refresh, stamp publication, and release-tree locking; a failure in any
of those steps loses the retry.

**Scope:**
- Modify `packaging/deploy-local.sh`.
- Add `packaging/tests/deploy-queue-ack.test.sh`.
- Update `docs/specs/2026-08-16-cd-structural-review.md` when installed proof is captured.

**Contract:**
1. The authoritative request coverage remains the existing `queue_snapshot`, taken under the
   deploy lock after settling. Requests arriving later remain queued.
2. Full deploy finalization order is: refresh live report (currently fail-closed) → validate full
   target SHA → atomically publish successful stamp → make release tree read-only → run the
   existing fail-open main-checkout sync → acknowledge only `queue_snapshot` → publish finished
   state and owner notification.
3. Extract the commit boundary into named shell functions so failure injection exercises the same
   production code rather than a copied model. Acknowledgement failure is fail-closed; files that
   could not be removed remain available to retrigger the consumer.
4. Docs-only paths acknowledge only after all of their fail-closed work is complete. Their state
   write and output are observability and remain fail-open/non-failing.
5. Coalesced waiters still exit only when their own request is absent because a successful holder
   acknowledged it. A failed holder cannot create that condition.
6. Never broaden deletion beyond the captured snapshot; never clear the queue directory.

**Acceptance:**
- Focused test extracts the production finalizer and injects failure at live-report refresh, SHA
  validation, stamp publication, release-tree lock, and acknowledgement. Every pre-ack failure
  leaves all covered request files; stamp publication failure leaves the old stamp; success writes
  the full SHA and removes covered requests; an uncaptured late request remains.
- Static order assertions cover pre-lock docs-only, locked docs-only, and full deployment paths.
- `bash -n packaging/deploy-local.sh packaging/tests/deploy-queue-ack.test.sh`.
- Existing `packaging/tests/deploy-idle-work.test.sh` and
  `packaging/tests/collector-restart-gate.test.sh` stay green.
- Installed proof: enqueue a request, run the standing consumer, and observe its covered request
  disappear only with a `finished/deployed` state whose SHA equals the deploy stamp. No synthetic
  live failure will be introduced on the owner machine.