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

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

.claude/skills/dolibarr-sandbox-write/SKILL.md

@@ -8,8 +8,13 @@ description: >-
   with a before/after read-back diff), add contacts idempotently (dedupe by email
   then name), customer + supplier invoices with product/service lines and the
   supplier's own reference, validate them, and record règlements (payments). Every
-  write goes through dol-write.sh, which REFUSES any host that is not the sandbox —
-  the structural guarantee (ADR-0003) that this skill can never mutate production.
+  create is IDEMPOTENT (erp#44): before any POST it dedupes against the target
+  (thirdparty by exact name, supplier invoice by socid+ref_supplier, customer
+  invoice by socid+date+total+line fingerprint, payment by invoice+amount+
+  normalized transaction id; credit notes excepted, a follow-up), so replaying
+  a manifest — even one that failed mid-run — is a no-op, never a duplicate. Every write goes through dol-write.sh,
+  which REFUSES any host that is not the sandbox — the structural guarantee
+  (ADR-0003) that this skill can never mutate production.
   Use when the user asks to "create a thirdparty / supplier / client fiche",
   "compléter / mettre à jour la fiche client", "add a contact to a thirdparty",
   "saisir une facture", "record an invoice with lines", "enregistrer un règlement /
@@ -77,7 +82,15 @@ echo '{"name":"OVH","role":"supplier","siret":"..."}'            | scripts/third
 `role`: `client` | `supplier` | `both`. Codes auto-assign from the mask
 (`CL{0000}` / `FO{0000}`) via the `-1` sentinel; pass `client_code`/`supplier_code`
 to override. Optional: `country_id` (default 1=FR), `siret`, `tva_intra`,
-`address`, `zip`, `town`, `email`, `phone`, `idprof1`. Emits the new id.
+`address`, `zip`, `town`, `email`, `phone`, `idprof1`.
+
+**Idempotent (erp#44): dedupe by exact name.** Before any POST the name is looked
+up on the target with the same semantics as promote's `#thirdparty:name=` lookup:
+one match whose roles cover the requested `role` → `{"id": <existing>,
+"deduped": true}`, no write; **2+ matches abort** (ambiguous — never guess); a
+match **missing the requested role aborts** too (refuse-never-repair: reusing a
+client fiche as a supplier would skip the code mask and hide a data problem).
+Otherwise it creates and emits `{"id": <new>, "deduped": false}`.
 
 ### 2 · Invoice (facture) — `scripts/invoice-create.sh`
 
@@ -95,7 +108,26 @@ echo '{"socid":7,"kind":"supplier","ref_supplier":"INV-2026-042","validate":true
 `desc, qty, price_ht, tva, type` (product|service) and optional `product_id`
 (`fk_product`) to link a catalogue product. Totals + TVA are computed by Dolibarr.
 `validate:true` turns the draft (`PROV…`) into a final numbered invoice; omit it
-to leave a draft. Emits `{id, ref, ref_supplier, total_ht, total_ttc, statut}`.
+to leave a draft. Emits `{id, ref, ref_supplier, total_ht, total_ttc, statut,
+deduped}`.
+
+**Idempotent (erp#44).** Before any POST the thirdparty's invoices of the same
+kind are listed and deduped:
+
+- **supplier with `ref_supplier`** → by **(socid, ref_supplier)** — the
+  supplier's own ref is the natural key. Same key with a *different* total
+  **aborts** (a conflict to resolve, never a dedupe).
+- **customer** (or supplier without `ref_supplier`) → by **(socid, date,
+  total_ttc ±0.02, line fingerprint)** — the multiset of (desc, qty, subprice,
+  tva_tx), desc HTML-unescaped/whitespace-collapsed since Dolibarr returns
+  stored text HTML-encoded. Credit notes (`type=2`) are never candidates;
+  2+ matches abort.
+
+A hit emits the **existing** invoice with `"deduped": true` — and if
+`validate:true` was asked while the match is still a draft (run 1 died between
+create and validate), it is **validated now**, so a replayed manifest converges
+instead of stalling on a half-done op. A listing failure other than 404 aborts
+(POSTing blind would mint duplicates — the exact erp#44 failure mode).
 
 ### 3 · Payment (règlement) — `scripts/payment-record.sh`
 
@@ -129,10 +161,24 @@ an explicit error — never truncated silently. `arcodange-bank-reco`'s bank-mat
 normalizes feed ids the same way, so short-form nums keep reconciling by id
 (historical long-form nums too). Pass the raw feed id; the script does the rest.
 
-Emits **`{id, bank_transaction_id, transaction_id}`**. `bank_transaction_id` is the
-Dolibarr bank line (`llx_bank.fk_bank_line`) the payment created — the id the
-reconciliation (`arcodange-bank-reco`) keys on. `transaction_id` echoes the
-**normalized** num actually stored. Both ends are captured at write time.
+**Idempotent (erp#44), composing with the normalization above.** Before any POST
+the invoice's payment list is fetched and deduped by **(invoice, amount,
+normalized transaction_id)**: a row whose stored num — normalized the same way,
+so historical long-form Qonto nums still match — equals the normalized
+`transaction_id` is a replay. Supplier payments also require the amounts to
+agree (±0.005; same tx with a *different* amount **aborts** as a conflict);
+customer payments settle the full remaining, so the tx id alone is the key. A
+hit emits `{"id": null, "bank_transaction_id": <existing line>,
+"transaction_id": <normalized>, "deduped": true}` without posting (`id` is null
+by honesty — Dolibarr's payment list does not expose the paiement rowid; the
+bank line is the stable handle). **Without a `transaction_id` there is no dedupe
+key — a replay WILL double-pay**, one more reason it is always passed.
+
+Emits **`{id, bank_transaction_id, transaction_id, deduped}`**.
+`bank_transaction_id` is the Dolibarr bank line (`llx_bank.fk_bank_line`) the
+payment created — the id the reconciliation (`arcodange-bank-reco`) keys on.
+`transaction_id` echoes the **normalized** num actually stored. Both ends are
+captured at write time.
 
 ### 4 · Credit note (avoir) — `scripts/creditnote-create.sh`
 
@@ -212,6 +258,16 @@ dependent ops wire up on the target. `--target sandbox` writes via `dol-write.sh
 `ARCO_PROMOTE_CONFIRM` is set exactly. Pair it with `dolibarr-data-snapshot` (prod
 before/after) to confirm only the intended records changed.
 
+**Replay is safe (erp#44).** Every op script dedupes before POSTing, so a
+manifest that failed mid-run — the 2026-07-11 rehearsal's manifest B, whose op 1
+had already created the DARNIS invoice — can simply be re-applied: already-done
+ops answer `deduped=true`, the rest execute. `promote-apply` marks each op
+`created` or `deduped=true` inline and totals them in the summary line
+(`OK — promote complete (1 created, 2 deduped)`), so an all-`deduped` second run
+is visible proof of a no-op. Live acceptance: `tests/replay-idempotency.sh`
+double-applies a self-contained manifest (thirdparty + supplier invoice +
+payment) on the sandbox and asserts run 2 dedupes all ops with zero new rows.
+
 A manifest value can reference another entity two ways, both resolved against the
 **target** so the same file is portable sandbox↔prod:
 
@@ -253,9 +309,21 @@ sandbox KissMetrics on `--target sandbox` and the prod one on `--target prod`.
   anything else (`code_client`, roles, payment conditions…) *before* any request:
   a typo'd field must fail loudly, not silently mutate the ledger. Offline proof
   in `tests/run-tests.sh`.
-- **Contacts dedupe by (socid, email) then (socid, lastname+firstname)**, both
-  case-insensitive — `contact-create.sh` answers `{"id": …, "deduped": true}`
-  instead of minting a duplicate, so replaying a manifest is always safe.
+- **Every create dedupes before POSTing (erp#44)** — thirdparty by exact name
+  (ambiguous or role-mismatch aborts), supplier invoice by (socid, ref_supplier)
+  (total mismatch aborts), customer invoice by (socid, date, total, line
+  fingerprint), payment by (invoice, amount, normalized tx id), contact by
+  (socid, email) then (socid, lastname+firstname) — each answering
+  `{"deduped": true}` instead of minting a duplicate, so replaying a manifest is
+  always safe. Two holes: a **payment without a `transaction_id`** has no
+  dedupe key and WILL double-pay on a replay, and **`creditnote-create.sh` does
+  not dedupe yet** (supplier-avoir parity follow-up) — do not replay a manifest
+  containing a creditnote op past a mid-run failure. Offline proof:
+  `tests/run-tests.sh`; live double-apply proof: `tests/replay-idempotency.sh`.
+- **A dedupe lookup that fails (non-404) aborts the op** — the scripts refuse to
+  POST blind, because assuming "no match" on a 403/timeout is precisely how
+  duplicates get minted (cf. the `voir_tous` ACL trap in the `dolibarr` skill:
+  missing permissions masquerade as empty lists).
 - **`poste`, not `soc2`.** The job-title field on a Dolibarr contact is `poste`;
   `soc2` (seen in WIP operator payloads) is not a Dolibarr field and the API
   would drop it silently — `contact-create.sh` refuses it with a pointer to