arcaeon-once 0.1.0__tar.gz

arcaeon_once-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.pyc
+.venv/
+dist/
+build/
+*.egg-info/
+*.jsonl
+*.sqlite3
+!server.json

arcaeon_once-0.1.0/CHANGELOG.md

@@ -0,0 +1,128 @@
+# Changelog
+
+## 0.1.0 — the WAL-init race, found and fixed BEFORE first publish (2026-08-14)
+
+The hold below did its job. The race is fixed, the fix is signed off, the gate
+was run and passed **20/20 consecutive full-suite runs with zero flakes**
+(`test_once.py` + `test_concurrency.py` + `selftest`, 283s), `dist/` was
+rebuilt from the fixed source, and `ArcaeonOncePyPIRetry` is re-enabled for
+14:10 on 8/15. Nothing was ever published from the raced code — PyPI returned
+404 for the project at fix time — so this folds into 0.1.0 rather than
+minting a 0.1.1 whose predecessor never existed.
+
+**What changed:**
+
+- **First-touch index setup is serialized by a cross-process file lock**
+  (`msvcrt` byte-range on Windows, `fcntl.flock` on POSIX). The one-time
+  `delete`→`wal` journal-mode switch now happens ONCE, by one process, with
+  everybody else queued *outside the database* — instead of N processes
+  simultaneously fighting for an exclusive lock that ignores `busy_timeout`.
+- **The hot path takes no exclusive lock at all.** `_init_index()` now starts
+  with a lock-free, read-only check (file exists + table present + journal
+  mode settled) and returns immediately once the index is up. Only genuine
+  first touch reaches the locked setup path, double-checked on the way in.
+- **WAL is treated as what it actually is — an optimisation, not the safety
+  mechanism.** The real race serialization is `BEGIN IMMEDIATE`, which *does*
+  honour `busy_timeout`. So the WAL switch is bounded-retry and best-effort:
+  an index stuck in `delete` mode is slower under load, never less correct,
+  and must not take down a guarded side effect.
+- **New typed outcome: `IndexUnavailable`.** Every SQLite path in the index
+  (`_init_index`, `_claim`, `_mark_executed`, `_reclaim_after_indeterminate`,
+  `rebuild_index`) now converts residual `sqlite3.Error` into this documented
+  exception after a bounded retry. Nothing untyped escapes `guard()` any
+  more. It fails safe — raised before any claim row and any ledger row.
+  The single documented nuance rides on the instance as `.ledger_committed`:
+  raised from `done()`/`complete()`, the executed row is already durable in
+  the ledger and only the accelerator is stale (duplicate refusal still
+  works, `rebuild_index()` resyncs). Don't re-run the effect on that one.
+- **`rebuild_index()` now removes orphaned `-wal`/`-shm` sidecars** before
+  recreating the index, so a stale WAL can't outlive the database it belonged
+  to.
+
+**New regression test** —
+`test_first_touch_index_race_is_typed_and_exactly_once`, 5 trials × 12
+processes. Workers import the library, signal ready, and wait on a `go` file;
+the parent writes it — carrying an absolute release timestamp — only once
+every worker has armed, and workers then BUSY-SPIN to that instant, so all
+twelve land on the journal-mode switch inside the same millisecond.
+
+The release time is chosen AFTER everyone arms on purpose. The first version
+of this test guessed a fixed 3-second lead up front, and on a loaded machine
+that guess was wrong: a gate run caught it arming 9/10 and then 0/10 workers.
+That test was itself flaky, which is precisely the disease under treatment —
+so the barrier was rebuilt rather than papered over with a longer sleep.
+
+Reproduction measured against the pre-fix code (the check that the test isn't
+vacuous — a regression test that can't fail on the buggy code proves nothing):
+**19 of 30 workers crashed** with exactly the traceback below under the first
+barrier, and 2–8 of 30–80 workers under the final one, with run-level
+reproduction — at least one trial red — in every attempt. Five trials, not
+one, because the crash window is the sub-millisecond in which the first
+process creates the database and flips its journal mode, and a single trial
+can miss it by luck.
+
+On the fixed code: 0 crashes, every outcome typed, exactly one execution per
+trial, across 20 consecutive full-suite runs including three where the
+machine was loaded enough to double the runtime.
+
+## Superseded — the hold that produced the fix (2026-08-14 QA sweep)
+
+_Kept as the audit trail. Every claim below was true when written; the
+"Candidate fix" is what got implemented, plus the file lock and the typed
+outcome._
+
+**The 0.1.0 PyPI publish was held back, and the `ArcaeonOncePyPIRetry` scheduled
+task that would have shipped it unattended at 14:10 on 8/15 is DISABLED.**
+Re-arm with `schtasks /change /tn "ArcaeonOncePyPIRetry" /enable` once the item
+below is signed off. The task publishes unconditionally — it has no test gate —
+and 14:10 falls inside a work shift, so nobody would have been watching.
+
+**Why:** `test_concurrency.py` fails roughly 30% of runs, always the same way:
+
+```
+File "arcaeon_once\__init__.py", line 438, in _enter_for_key
+    _init_index(self.state_db)
+File "arcaeon_once\__init__.py", line 119, in _init_index
+    con.execute("PRAGMA journal_mode=WAL")
+sqlite3.OperationalError: database is locked
+```
+
+`_init_index()` runs on every `guard()` entry and unconditionally re-issues
+`PRAGMA journal_mode=WAL`. The first-time `delete`→`wal` switch needs an
+EXCLUSIVE lock and does **not** honour `busy_timeout` — measured: the pragma
+gave up after 0.003s against a 15s timeout. Two processes first-touching the
+same ledger at once collide there, and one crashes out of
+`guard().__enter__()` with an untyped `OperationalError` instead of one of this
+library's typed outcomes.
+
+**What is NOT broken:** the exactly-once guarantee holds. The crash lands before
+any intent or claim row is written, so it fails safe — no double-fire. 120
+concurrent claims and 40 barrier-synchronised races each produced exactly one
+winner. This is an availability defect, not a correctness one.
+
+**Why it still blocks the release:** `README.md` sells this exact test as the
+proof — "Verified with two real OS processes hammering the same key" — and that
+proof is red a third of the time. Shipping a reliability library whose own
+advertised evidence is flaky is the wrong first impression, and PyPI version
+numbers cannot be reused.
+
+**Candidate fix** (shape verified in a scratch copy, deliberately NOT applied):
+read `PRAGMA journal_mode` first and only switch when it is not already `wal`,
+tolerating `OperationalError` on the switch — WAL is a concurrency optimisation,
+and the real serialization comes from `BEGIN IMMEDIATE`. It touches the
+concurrency core of an exactly-once library, so it wants a sign-off plus 20+
+consecutive green suite runs before the publish is re-armed.
+
+## 0.1.0 — initial release contents (2026-08-14)
+
+- `guard(key, *, ledger_path=None, on_duplicate="raise", allow_retry_after_indeterminate=False, verify_integrity=False, store_outcome=False)` — context manager / decorator around a non-idempotent side effect, backed by an `arcaeon-ledger` hash chain.
+- Two-phase `once.intent` / `once.executed` ledger rows: a crash between them leaves the key `Indeterminate` (typed, refuse-by-default) instead of silently assumed either way.
+- `AlreadyExecuted`, `Indeterminate`, `TamperDetected` — typed, structured refusals, never a silent pass.
+- `receipt(key, ledger_path=...)` — the tamper-evident state of a key, read straight from the hash chain.
+- `complete(key, outcome, ledger_path=...)` — crash-recovery path: mark a key executed after manually confirming the effect actually ran.
+- `rebuild_index(ledger_path)` — replay the ledger into a fresh SQLite concurrency index if the index file is lost.
+- SQLite `BEGIN IMMEDIATE` race serialization on brand-new keys (same pattern as `arcaeon-meter`'s usage counter); every other decision is re-derived fresh from the ledger, so an out-of-band ledger edit is reflected immediately.
+- MCP server (`arcaeon_once.mcp_server`) — one tool, `guard_side_effect`, with `claim`/`complete` actions mirroring the library's own two-phase design across the MCP boundary.
+- CLI (`arcaeon_once.cli`) — `receipt` and `rebuild-index` commands.
+- Tests: duplicate refusal, crash-window indeterminacy (real subprocess hard-exit via `os._exit`), chain tamper detection (in-place edit and tail-drop), and a real two-OS-process concurrency race (`test_concurrency.py`).
+- `python -m arcaeon_once.selftest` — golden outcome-digest vector + planted-tamper fixture, runnable on any machine.

arcaeon_once-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Arcaeon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

arcaeon_once-0.1.0/PKG-INFO

@@ -0,0 +1,234 @@
+Metadata-Version: 2.5
+Name: arcaeon-once
+Version: 0.1.0
+Summary: Executed-once receipts for non-idempotent agent side effects. Refuses silent double-fires, flags crash-window uncertainty honestly.
+Project-URL: Homepage, https://arcaeon.io
+Author: Arcaeon
+License: MIT
+License-File: LICENSE
+Keywords: agents,ai,audit,hash-chain,idempotency,mcp,reliability,tamper-evident
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.9
+Requires-Dist: arcaeon-ledger>=0.5.2
+Description-Content-Type: text/markdown
+
+# arcaeon-once
+
+**Kybernis-shaped enforcement stops the double-fire. `arcaeon-once` is the
+evidence layer: a tamper-evident receipt proving a side effect ran exactly
+once — or an honest flag when it didn't know.**
+
+Agents retry. Refunds, deploys, and outbound emails do not want to be
+retried. `arcaeon-once` wraps a non-idempotent side effect with an
+idempotency key: it refuses to re-run a key that already executed and hands
+back the original receipt instead, hash-chained via
+[`arcaeon-ledger`](https://pypi.org/project/arcaeon-ledger/) so nobody can
+quietly delete the record to enable a re-fire.
+
+```
+pip install arcaeon-once      # then:  from arcaeon_once import guard
+```
+
+```python
+from arcaeon_once import guard
+
+with guard(f"refund:{charge_id}", ledger_path="ops.log.jsonl") as g:
+    result = stripe.Refund.create(charge=charge_id)
+    g.done(result)
+```
+
+Call it again with the same key and it raises `AlreadyExecuted` — carrying
+the original receipt — instead of refunding twice.
+
+## The non-proof, stated before any feature, because it is the point
+
+**This library gives you at-most-once-or-flagged. Not exactly-once.**
+
+Exactly-once over a real, non-transactional side effect — an HTTP call to a
+payment processor, a `kubectl apply`, an SMTP send — is not achievable by any
+wrapper running in the same process as the effect. If the process dies
+between the effect executing and the record being written, nobody, this
+library included, can know from the outside whether the effect happened.
+Anyone telling you their idempotency library gives you exactly-once across
+that boundary is telling you a story, not an engineering fact — say so
+plainly, because the crowded "AI agent reliability" space is not short on
+confident claims that don't survive a `kill -9` at the wrong instant.
+
+What you actually get:
+
+- **At-most-once**, when nothing crashes. A second call with the same key,
+  while the ledger is intact, is refused. Period.
+- **Or-flagged**, when something crashes mid-effect. The key comes back
+  `Indeterminate` — a typed, refuse-by-default outcome — instead of a silent
+  double-fire or a silent skip. You check the real system (did the refund
+  post? did the deploy land?) and either `complete()` it (it did happen) or
+  retry with `allow_retry_after_indeterminate=True` (it didn't).
+
+## The crash window, designed, not hidden
+
+Every guarded call is two-phase in the ledger: an `once.intent` row is
+appended **before** the effect runs, an `once.executed` row **after** (via
+`g.done(outcome)` or the module-level `complete()`). A key with an `intent`
+row and no matching `executed` row means: something started and this library
+does not know if it finished.
+
+```python
+from arcaeon_once import guard, receipt, complete, Indeterminate, AlreadyExecuted
+
+try:
+    with guard("deploy:build-4471", ledger_path="ops.log.jsonl") as g:
+        run_deploy()          # process dies here -> intent, no executed
+        g.done({"status": "ok"})
+except AlreadyExecuted as e:
+    print("already ran:", e.receipt.executed_ts, e.receipt.executed_chain)
+
+# next run, same key:
+r = receipt("deploy:build-4471", ledger_path="ops.log.jsonl")
+r.state   # "intent" -- the crash window, exactly as it happened, not glossed
+try:
+    with guard("deploy:build-4471", ledger_path="ops.log.jsonl"):
+        ...
+except Indeterminate as e:
+    # go check the actual deploy target by hand, THEN:
+    complete("deploy:build-4471", {"status": "ok"}, ledger_path="ops.log.jsonl")
+    # -- or, if it truly didn't land --
+    # guard("deploy:build-4471", ledger_path="ops.log.jsonl",
+    #       allow_retry_after_indeterminate=True)
+```
+
+That's honest exactly-once-**or-tell-you** semantics. `Indeterminate` is
+refused by default — never silently treated as "safe to retry," never
+silently treated as "must have worked." Resolving it is a manual step on
+purpose: only you (or your ops tooling) can look at the real system and know
+which way it actually went.
+
+## What proves the "once" — the hash chain, not a promise
+
+Every `intent`/`executed` row is appended to an `arcaeon-ledger` hash chain:
+`chain = sha256(prev_chain + canonical_json(row_without_chain))[:32]`. Delete
+or edit an inconvenient `executed` row to re-enable a re-fire, and every
+later link in the chain breaks — `receipt()` reports `ledger_ok=False` with a
+`ledger_first_break` naming the row. Deletion doesn't erase the fact that a
+deletion happened.
+
+`guard()` does **not** re-verify the whole chain on every call by default —
+that's an `O(rows)` scan of the file, and paying it on every single side
+effect would not scale to a high-volume tool. Pass `verify_integrity=True`
+for that stronger (and slower) guarantee inline, or call `receipt()` /
+`arcaeon_ledger.verify_file()` on your own cadence (a pre-ship gate, a
+nightly job). Tamper caught late is still tamper caught. Tamper never
+checked is a receipt you shouldn't have trusted in the first place — this
+library will not pretend otherwise to look faster in a benchmark.
+
+## Concurrency: exactly one process wins the claim
+
+Two processes racing the **same brand-new key** resolve through a single
+SQLite `BEGIN IMMEDIATE` transaction against a small index file next to the
+ledger — the same WAL + immediate-transaction pattern
+[`arcaeon-meter`](https://pypi.org/project/arcaeon-meter/) uses for its usage
+counter. Exactly one caller, ever, gets back the execution claim for a given
+key; the loser gets `AlreadyExecuted` or `Indeterminate` depending on timing,
+never a green light to also run the effect. Verified with two real OS
+processes hammering the same key, and with ten processes released onto a
+brand-new ledger by a wall-clock start barrier (see `test_concurrency.py`),
+not simulated with threads and a comforting mock.
+
+The index is created lazily, and that first-touch setup is serialized by a
+cross-process **file lock** — switching a brand-new SQLite file into WAL
+journal mode needs a momentary EXCLUSIVE database lock that does *not* honour
+`busy_timeout`, so without that serialization, N processes first-using the
+same fresh ledger collide on it. If contention still can't be absorbed you get
+`IndexUnavailable`: a typed, documented outcome raised **before** any claim or
+ledger row, never a raw `sqlite3.OperationalError` leaking out of `guard()`.
+(One documented nuance, carried on the exception as `.ledger_committed`: if it
+comes from `done()`/`complete()`, the executed row is already durable in the
+ledger and only the index is stale — duplicate refusal still works, and
+`rebuild_index()` resyncs it. Don't re-run the effect on that one.)
+
+That index is consulted **only** to serialize the race at the "nobody has
+claimed this key yet" boundary — every other decision (already executed?
+still an unresolved intent?) is re-derived fresh from the ledger itself on
+every `guard()` call, on purpose: an out-of-band edit to the ledger file
+(a dropped row, a tampered byte) must be reflected immediately even though
+the index file wasn't touched, so a truncation attack degrades to a safe
+refusal (`Indeterminate`) rather than the index quietly vouching for a row
+that's no longer there. The honest cost of that choice: `guard()` scans the
+ledger for the key on every call — `O(rows)` in the ledger's total size, not
+`O(1)`. Fine for a day's or a service's worth of idempotency keys; if you're
+guarding millions of distinct keys against one ledger file, shard the ledger
+(one file per key prefix / tenant / day) rather than expecting this to stay
+`O(1)` — that sharding is on you for now, stated rather than hidden. Lose the
+index file entirely and you lose only the race-serialization fast path, not
+correctness: `rebuild_index()` replays the ledger into a fresh one.
+
+## API surface
+
+```python
+guard(key, *, ledger_path=None, state_db=None, on_duplicate="raise",
+      allow_retry_after_indeterminate=False, verify_integrity=False,
+      store_outcome=False) -> GuardContext
+```
+Context manager (`with guard(key) as g: ...; g.done(outcome)`) or decorator
+(`@guard(key)` for a static key, or `@guard(lambda *a, **kw: f"job:{a[0]}")`
+for a key resolved per call). `on_duplicate="raise"` (default) raises
+`AlreadyExecuted`; `"return_receipt"` returns without executing — check
+`g.already_executed` / `g.receipt`, or for the decorator, the call returns
+the `Receipt` directly instead of the wrapped function's result.
+
+```python
+receipt(key, *, ledger_path) -> Receipt
+```
+The tamper-evident state of a key, read straight from the hash chain (never
+from the SQLite index). `Receipt.state` is `"never"`, `"intent"`, or
+`"executed"`. `bool(receipt)` is `True` only for a clean, verified,
+`"executed"` record — a tampered ledger or an unresolved intent never reads
+as success.
+
+```python
+complete(key, outcome=None, *, ledger_path, store_outcome=False) -> Receipt
+```
+Mark a key executed directly, without an open `guard()` context — the
+crash-recovery path once you've manually confirmed the effect actually ran.
+
+```python
+rebuild_index(ledger_path, state_db=None) -> int
+```
+Replay the ledger into a fresh SQLite concurrency index. Restores
+correctness after the index file is lost; not needed for normal operation.
+
+## Drop it into any MCP agent
+
+```json
+{
+  "mcpServers": {
+    "once": {
+      "command": "python",
+      "args": ["-m", "arcaeon_once.mcp_server"]
+    }
+  }
+}
+```
+
+One tool, two actions mirroring the library's own two-phase design so the
+crash window is real even across the MCP boundary: `guard_side_effect(action=
+"claim", key, ...)` before the agent performs the effect (skip it if
+`claimed: false`), `guard_side_effect(action="complete", key, outcome, ...)`
+after it succeeds. If the agent session dies between the two calls, the key
+is left `intent`-only — indeterminate on the next claim, not silently
+resolved by the wrapping.
+
+## Status
+
+Core library, CLI, MCP server, all tested: duplicate execution refused with
+the original receipt returned, the crash window (INTENT with no EXECUTED)
+resolving to a typed `Indeterminate` refusal, chain tampering on an executed
+row detected by `receipt()`, a real two-OS-process race resolving to exactly
+one execution, and a ten-process barrier-released first-touch race that lands
+zero untyped exceptions. `python -m arcaeon_once.selftest` ships in the
+package so you can verify the golden digest vector and the planted-tamper
+case on your own machine.
+
+MIT.

arcaeon_once-0.1.0/README.md

@@ -0,0 +1,217 @@
+# arcaeon-once
+
+**Kybernis-shaped enforcement stops the double-fire. `arcaeon-once` is the
+evidence layer: a tamper-evident receipt proving a side effect ran exactly
+once — or an honest flag when it didn't know.**
+
+Agents retry. Refunds, deploys, and outbound emails do not want to be
+retried. `arcaeon-once` wraps a non-idempotent side effect with an
+idempotency key: it refuses to re-run a key that already executed and hands
+back the original receipt instead, hash-chained via
+[`arcaeon-ledger`](https://pypi.org/project/arcaeon-ledger/) so nobody can
+quietly delete the record to enable a re-fire.
+
+```
+pip install arcaeon-once      # then:  from arcaeon_once import guard
+```
+
+```python
+from arcaeon_once import guard
+
+with guard(f"refund:{charge_id}", ledger_path="ops.log.jsonl") as g:
+    result = stripe.Refund.create(charge=charge_id)
+    g.done(result)
+```
+
+Call it again with the same key and it raises `AlreadyExecuted` — carrying
+the original receipt — instead of refunding twice.
+
+## The non-proof, stated before any feature, because it is the point
+
+**This library gives you at-most-once-or-flagged. Not exactly-once.**
+
+Exactly-once over a real, non-transactional side effect — an HTTP call to a
+payment processor, a `kubectl apply`, an SMTP send — is not achievable by any
+wrapper running in the same process as the effect. If the process dies
+between the effect executing and the record being written, nobody, this
+library included, can know from the outside whether the effect happened.
+Anyone telling you their idempotency library gives you exactly-once across
+that boundary is telling you a story, not an engineering fact — say so
+plainly, because the crowded "AI agent reliability" space is not short on
+confident claims that don't survive a `kill -9` at the wrong instant.
+
+What you actually get:
+
+- **At-most-once**, when nothing crashes. A second call with the same key,
+  while the ledger is intact, is refused. Period.
+- **Or-flagged**, when something crashes mid-effect. The key comes back
+  `Indeterminate` — a typed, refuse-by-default outcome — instead of a silent
+  double-fire or a silent skip. You check the real system (did the refund
+  post? did the deploy land?) and either `complete()` it (it did happen) or
+  retry with `allow_retry_after_indeterminate=True` (it didn't).
+
+## The crash window, designed, not hidden
+
+Every guarded call is two-phase in the ledger: an `once.intent` row is
+appended **before** the effect runs, an `once.executed` row **after** (via
+`g.done(outcome)` or the module-level `complete()`). A key with an `intent`
+row and no matching `executed` row means: something started and this library
+does not know if it finished.
+
+```python
+from arcaeon_once import guard, receipt, complete, Indeterminate, AlreadyExecuted
+
+try:
+    with guard("deploy:build-4471", ledger_path="ops.log.jsonl") as g:
+        run_deploy()          # process dies here -> intent, no executed
+        g.done({"status": "ok"})
+except AlreadyExecuted as e:
+    print("already ran:", e.receipt.executed_ts, e.receipt.executed_chain)
+
+# next run, same key:
+r = receipt("deploy:build-4471", ledger_path="ops.log.jsonl")
+r.state   # "intent" -- the crash window, exactly as it happened, not glossed
+try:
+    with guard("deploy:build-4471", ledger_path="ops.log.jsonl"):
+        ...
+except Indeterminate as e:
+    # go check the actual deploy target by hand, THEN:
+    complete("deploy:build-4471", {"status": "ok"}, ledger_path="ops.log.jsonl")
+    # -- or, if it truly didn't land --
+    # guard("deploy:build-4471", ledger_path="ops.log.jsonl",
+    #       allow_retry_after_indeterminate=True)
+```
+
+That's honest exactly-once-**or-tell-you** semantics. `Indeterminate` is
+refused by default — never silently treated as "safe to retry," never
+silently treated as "must have worked." Resolving it is a manual step on
+purpose: only you (or your ops tooling) can look at the real system and know
+which way it actually went.
+
+## What proves the "once" — the hash chain, not a promise
+
+Every `intent`/`executed` row is appended to an `arcaeon-ledger` hash chain:
+`chain = sha256(prev_chain + canonical_json(row_without_chain))[:32]`. Delete
+or edit an inconvenient `executed` row to re-enable a re-fire, and every
+later link in the chain breaks — `receipt()` reports `ledger_ok=False` with a
+`ledger_first_break` naming the row. Deletion doesn't erase the fact that a
+deletion happened.
+
+`guard()` does **not** re-verify the whole chain on every call by default —
+that's an `O(rows)` scan of the file, and paying it on every single side
+effect would not scale to a high-volume tool. Pass `verify_integrity=True`
+for that stronger (and slower) guarantee inline, or call `receipt()` /
+`arcaeon_ledger.verify_file()` on your own cadence (a pre-ship gate, a
+nightly job). Tamper caught late is still tamper caught. Tamper never
+checked is a receipt you shouldn't have trusted in the first place — this
+library will not pretend otherwise to look faster in a benchmark.
+
+## Concurrency: exactly one process wins the claim
+
+Two processes racing the **same brand-new key** resolve through a single
+SQLite `BEGIN IMMEDIATE` transaction against a small index file next to the
+ledger — the same WAL + immediate-transaction pattern
+[`arcaeon-meter`](https://pypi.org/project/arcaeon-meter/) uses for its usage
+counter. Exactly one caller, ever, gets back the execution claim for a given
+key; the loser gets `AlreadyExecuted` or `Indeterminate` depending on timing,
+never a green light to also run the effect. Verified with two real OS
+processes hammering the same key, and with ten processes released onto a
+brand-new ledger by a wall-clock start barrier (see `test_concurrency.py`),
+not simulated with threads and a comforting mock.
+
+The index is created lazily, and that first-touch setup is serialized by a
+cross-process **file lock** — switching a brand-new SQLite file into WAL
+journal mode needs a momentary EXCLUSIVE database lock that does *not* honour
+`busy_timeout`, so without that serialization, N processes first-using the
+same fresh ledger collide on it. If contention still can't be absorbed you get
+`IndexUnavailable`: a typed, documented outcome raised **before** any claim or
+ledger row, never a raw `sqlite3.OperationalError` leaking out of `guard()`.
+(One documented nuance, carried on the exception as `.ledger_committed`: if it
+comes from `done()`/`complete()`, the executed row is already durable in the
+ledger and only the index is stale — duplicate refusal still works, and
+`rebuild_index()` resyncs it. Don't re-run the effect on that one.)
+
+That index is consulted **only** to serialize the race at the "nobody has
+claimed this key yet" boundary — every other decision (already executed?
+still an unresolved intent?) is re-derived fresh from the ledger itself on
+every `guard()` call, on purpose: an out-of-band edit to the ledger file
+(a dropped row, a tampered byte) must be reflected immediately even though
+the index file wasn't touched, so a truncation attack degrades to a safe
+refusal (`Indeterminate`) rather than the index quietly vouching for a row
+that's no longer there. The honest cost of that choice: `guard()` scans the
+ledger for the key on every call — `O(rows)` in the ledger's total size, not
+`O(1)`. Fine for a day's or a service's worth of idempotency keys; if you're
+guarding millions of distinct keys against one ledger file, shard the ledger
+(one file per key prefix / tenant / day) rather than expecting this to stay
+`O(1)` — that sharding is on you for now, stated rather than hidden. Lose the
+index file entirely and you lose only the race-serialization fast path, not
+correctness: `rebuild_index()` replays the ledger into a fresh one.
+
+## API surface
+
+```python
+guard(key, *, ledger_path=None, state_db=None, on_duplicate="raise",
+      allow_retry_after_indeterminate=False, verify_integrity=False,
+      store_outcome=False) -> GuardContext
+```
+Context manager (`with guard(key) as g: ...; g.done(outcome)`) or decorator
+(`@guard(key)` for a static key, or `@guard(lambda *a, **kw: f"job:{a[0]}")`
+for a key resolved per call). `on_duplicate="raise"` (default) raises
+`AlreadyExecuted`; `"return_receipt"` returns without executing — check
+`g.already_executed` / `g.receipt`, or for the decorator, the call returns
+the `Receipt` directly instead of the wrapped function's result.
+
+```python
+receipt(key, *, ledger_path) -> Receipt
+```
+The tamper-evident state of a key, read straight from the hash chain (never
+from the SQLite index). `Receipt.state` is `"never"`, `"intent"`, or
+`"executed"`. `bool(receipt)` is `True` only for a clean, verified,
+`"executed"` record — a tampered ledger or an unresolved intent never reads
+as success.
+
+```python
+complete(key, outcome=None, *, ledger_path, store_outcome=False) -> Receipt
+```
+Mark a key executed directly, without an open `guard()` context — the
+crash-recovery path once you've manually confirmed the effect actually ran.
+
+```python
+rebuild_index(ledger_path, state_db=None) -> int
+```
+Replay the ledger into a fresh SQLite concurrency index. Restores
+correctness after the index file is lost; not needed for normal operation.
+
+## Drop it into any MCP agent
+
+```json
+{
+  "mcpServers": {
+    "once": {
+      "command": "python",
+      "args": ["-m", "arcaeon_once.mcp_server"]
+    }
+  }
+}
+```
+
+One tool, two actions mirroring the library's own two-phase design so the
+crash window is real even across the MCP boundary: `guard_side_effect(action=
+"claim", key, ...)` before the agent performs the effect (skip it if
+`claimed: false`), `guard_side_effect(action="complete", key, outcome, ...)`
+after it succeeds. If the agent session dies between the two calls, the key
+is left `intent`-only — indeterminate on the next claim, not silently
+resolved by the wrapping.
+
+## Status
+
+Core library, CLI, MCP server, all tested: duplicate execution refused with
+the original receipt returned, the crash window (INTENT with no EXECUTED)
+resolving to a typed `Indeterminate` refusal, chain tampering on an executed
+row detected by `receipt()`, a real two-OS-process race resolving to exactly
+one execution, and a ten-process barrier-released first-touch race that lands
+zero untyped exceptions. `python -m arcaeon_once.selftest` ships in the
+package so you can verify the golden digest vector and the planted-tamper
+case on your own machine.
+
+MIT.