feat(write-skill): idempotency keys — manifest replay is a no-op #70

Merged
arcodange merged 1 commits from arcodange/idempotency-keys into main 2026-07-18 23:53:20 +02:00
Owner

Closes #44.

Learning #4 of the 2026-07-11 rehearsal, resolved: every write op now dedupes before any POST, and a replayed manifest is a visible no-op.

  • thirdparty-create.sh — key: exact name (promote #thirdparty:name= semantics); ambiguous or role-mismatch → abort.
  • invoice-create.sh — supplier kind: (socid, ref_supplier), same key + different total = conflict abort; customer kind: (socid, date, total_ttc ±0.02, line fingerprint, HTML-unescaped descs). Deduped draft + validate:true converges an interrupted run.
  • payment-record.sh — (invoice, amount, normalized transaction_id), composing with erp#37 normalization on both sides; no tx id = no dedupe key (loudly warned).
  • All ops refuse to POST blind on any lookup failure other than the documented empty-list 404 (voir_tous trap).
  • promote-apply.sh marks each op created / deduped=true and totals them; promote-plan.sh advertises the keys.

Acceptance evidence (in the #44 evidence comment): live double-apply on the sandbox — run 1 3 created (rows 1/1/1), run 2 3 deduped, row counts unchanged; the historic manifest-B replays 5/5 deduped, zero new rows — the exact replay Learning #4 declared impossible. Offline suite: 11/11 green. SKILL.md + runbook updated same-change.

Known holes, documented in SKILL.md: payments without transaction_id still have no dedupe key; creditnote-create.sh out of scope (follow-up issue suggested).

🤖 Generated with Claude Code

https://claude.ai/code/session_01VRShc4QhLLU73FLHx9vskh

Closes #44. Learning #4 of the 2026-07-11 rehearsal, resolved: every write op now dedupes **before** any POST, and a replayed manifest is a visible no-op. - `thirdparty-create.sh` — key: exact name (promote `#thirdparty:name=` semantics); ambiguous or role-mismatch → abort. - `invoice-create.sh` — supplier kind: (socid, `ref_supplier`), same key + different total = conflict abort; customer kind: (socid, date, total_ttc ±0.02, line fingerprint, HTML-unescaped descs). Deduped draft + `validate:true` converges an interrupted run. - `payment-record.sh` — (invoice, amount, normalized `transaction_id`), composing with erp#37 normalization on both sides; no tx id = no dedupe key (loudly warned). - All ops refuse to POST blind on any lookup failure other than the documented empty-list 404 (`voir_tous` trap). - `promote-apply.sh` marks each op `created` / `deduped=true` and totals them; `promote-plan.sh` advertises the keys. **Acceptance evidence** (in the [#44 evidence comment](https://gitea.arcodange.lab/arcodange-org/erp/issues/44)): live double-apply on the sandbox — run 1 `3 created` (rows 1/1/1), run 2 `3 deduped`, row counts unchanged; **the historic manifest-B replays 5/5 deduped, zero new rows** — the exact replay Learning #4 declared impossible. Offline suite: 11/11 green. SKILL.md + runbook updated same-change. Known holes, documented in SKILL.md: payments without `transaction_id` still have no dedupe key; `creditnote-create.sh` out of scope (follow-up issue suggested). 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01VRShc4QhLLU73FLHx9vskh
arcodange added 1 commit 2026-07-18 23:51:59 +02:00
Learning #4 of the 2026-07-11 rehearsal: manifest B failed mid-run and could
not be re-applied — op 1 (the DARNIS invoice) had already run and a replay
would have duplicated it. Every write op now dedupes BEFORE any POST:

- thirdparty-create.sh: by exact name (promote '#thirdparty:name=' semantics);
  ambiguous (2+) aborts; an existing fiche missing the requested role aborts
  (refuse-never-repair). Emits {"id", "deduped"} instead of a bare id.
- invoice-create.sh: supplier kind by (socid, ref_supplier) — same key with a
  different total aborts as a conflict; customer kind (or supplier without
  ref_supplier) by (socid, date, total_ttc ±0.02, line fingerprint) with descs
  HTML-unescaped. Credit notes are never candidates. A deduped DRAFT with
  validate:true is validated on replay, so an interrupted run converges.
- payment-record.sh: by (invoice, amount, normalized transaction_id), composing
  with the erp#37 varchar(50) normalization on BOTH sides so historical
  long-form nums still match; same tx + different amount aborts; without a tx
  id there is no dedupe key (warned). Dedupe answers id:null (the payments list
  exposes no paiement rowid) + the existing bank line.
- All three refuse to POST blind when the dedupe lookup fails with anything but
  the documented empty-list 404 (the voir_tous trap would otherwise mint dupes).
- promote-apply.sh: marks each op created / deduped=true inline and totals them
  in the summary — an all-deduped second run is visible proof of a no-op.
- promote-plan.sh: advertises each op's dedupe key (and flags tx=MISSING as
  'a replay WILL double-pay').

Proof:
- tests/run-tests.sh: 5 new offline cases (11 total) — dedupe hits POST
  nothing, conflicts/ambiguity abort pre-POST, long-form history dedupes,
  draft convergence validates; stub extended to serve the new lookups with the
  live-observed empty behaviors ([] for invoices/payments, 404 for tiers).
- tests/replay-idempotency.sh (new, live): double-applies a self-contained
  manifest on the sandbox — run 1 '3 created' (rows 1/1/1), run 2 '3 deduped'
  with row counts unchanged and the stored num in erp#37 short form.
- The historic manifest-B now replays on the sandbox as 5/5 deduped, zero new
  rows — the exact replay Learning #4 declared impossible.

SKILL.md updated in the same change (per-op dedupe keys, replay-safety section,
gotchas); the 2026-07-11 runbook's Learning #4 carries a dated resolution
addendum.

Closes erp#44.

Co-Authored-By: Claude Fable 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01VRShc4QhLLU73FLHx9vskh
arcodange merged commit e54b2f0f5d into main 2026-07-18 23:53:20 +02:00
arcodange deleted branch arcodange/idempotency-keys 2026-07-18 23:53:20 +02:00
Sign in to join this conversation.
No Reviewers
No labels
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: arcodange-org/erp#70