Audit question: is the documentation coherent, and is the app portable
to a fresh machine (macOS) with proper isolation? Findings and fixes:
- README never mentioned the cockpit/deck/lab manual (three rounds of UI
evolution invisible at the front door). Added: human-surface section
with the one command, expanded Install (editable-from-clone is the
supported mode — repo files are part of the product; zero-install
PYTHONPATH=src alternative; fresh-machine skip behavior), macOS
openssl/LibreSSL Ed25519 prerequisite with a one-line self-check,
wallet commands in the command list.
- The lab manual violated the repo's own macOS law (AGENTS.md): GNU
sha256sum -> shasum -a 256; GNU sed -i -> portable python3 -c
one-liner (executed and output-matched before shipping: entry 0 hash
mismatch, BROKEN, exit 1).
- Fresh-clone bootstrap was actually tested end to end in a scratch
clone: zero-install suite 130 passed / 0 failed / 14 skipped after
fixing the one unguarded test (test_ledger_is_hash_chained now skips
like its siblings when the dogfood binary is absent - capability gap,
not failure); venv + pip install -e . -> pacta console script serves
bridge/deck/manual/sample-prefill/drift-tripwire with no PYTHONPATH.
- PYTHONPATH incantations simplified: cockpit needs src only (provider
never imported by src/pacta); manual + cockpit.md updated.
- threat-model.md: cockpit attack-surface note (no mutating routes,
no auth because nothing to operate, localhost-only disclosure risk,
probe-only network I/O, fake-cockpit = host-compromise boundary).
- products.md: cockpit named as the shared human surface of all four
profiles. AGENTS.md: doc-portability law + the cockpit's three laws
added to the standing guidance.
Suite 144 green here; 130/0/14 on a bare clone.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Correctness:
- ledger: single-flight fcntl lock over read-modify-append + fsync. Two
concurrent writers previously could fork the hash chain (read same tail,
same prev_hash). New test races 8 threads x6 appends; chain stays intact
with contiguous indices.
- small-order list: the order-8 encodings were hand-typed and unverifiable
and diverged from the canonical libsodium blocklist. A BOGUS entry is the
only dangerous direction (it down-grades a real tamper to a note, skipping
the latch), so the list is now the certain-low-order set only (y in
{0,1,-1}, reduced/non-reduced, both sign bits); order-8 edges escalate to
tamper until a derived list lands. Fail-safe asymmetry documented + tested.
- freshness: removed a tautological .
Non-functional:
- quorum members now run concurrently (ThreadPoolExecutor): a verify costs
one member's latency, not the sum (~17ms for 4 members, live).
- Wallet.quorum() memoized per state_dir: binary swap-detection hashes run
once at assembly, not on every verify; documented rationale.
85 tests green; live 4-fork wallet re-verified end-to-end.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
