From dbf26844bb7b7b49e5c3d1d27365e6c657643f26 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 8 Sep 2026 12:30:03 +0000
Subject: [PATCH 1/5] directory/1: re-vendor check-directory.mjs to the
 shipping canonical
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The vendored copy of @flashyos/directory's checker had drifted behind the
authoritative EDGE_REQUIRES: it required settled edges to carry only
['sealed'], where packages/directory/src/types.ts (origin/main) requires
['sealed', 'capability']. A lagging copy does not fail — it disagrees
silently, validating a settled edge the estate's own spec rejects.

Re-vendored byte-identical to flashyos origin/main
packages/directory/vendor-check-directory.mjs (the shipping canonical, not a
stale working tree). Verified: the re-vendored checker still validates this
repo's own directory.fragment.json (16 nodes, 22 edges, 0 problems). The
estate-level differential tools/vendored-directory.test.mjs in flashyos is
the guard that catches this class of drift.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01X8LDnsexvNjSkqc2ihZR7U
---
 scripts/check-directory.mjs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/scripts/check-directory.mjs b/scripts/check-directory.mjs
index 7b91e56..c104e5c 100644
--- a/scripts/check-directory.mjs
+++ b/scripts/check-directory.mjs
@@ -60,7 +60,7 @@ const REQUIRES = {
   convenes: [],
   spokeAt: ['year'],
   issued: ['date'],
-  settled: ['sealed'],
+  settled: ['sealed', 'capability'],
   publishes: [],
   supersededBy: ['reason'],
 }

From 2994a146e5363d84eb7aaac0933e5cf9a41241de Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sun, 4 Oct 2026 13:20:34 +0000
Subject: [PATCH 2/5] Architecture audit: pin domain purity as I-9, write
 CLAUDE.md
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The ledger's headline architectural claim — the domain reads no database,
calls no clock, and generates no randomness, which is the whole reason it can
move onto a chain without its rules changing — was only half enforced. eslint
guards the runtime half (Date, Date.now, Math.random banned in src/domain),
but nothing guarded the dependency direction: a domain module importing an
adapter, a port, node:fs, or a third-party package would pass lint, typecheck
and every behavioural test, silently breaking the seam the package is built on.

- tests/domain-purity.test.ts reads the real import graph of src/domain with
  ts.preProcessFile (not a regex) and refuses any specifier that is not a
  domain sibling or node:crypto. Verified non-vacuous: it goes red when an
  adapter import or node:fs is injected into a domain file.
- docs/INVARIANTS.md gains I-9, making purity a numbered, cited invariant;
  tests/invariants.test.ts holds the doc and the suite together as before.
- CLAUDE.md gains the "what makes this repository different" section the file
  template asked for: what it is, that it ships as a library with no deploy
  target, the ports-and-adapters shape, and the invariants an agent must not
  break.

Full suite 198 passing, typecheck clean, new test lint-clean.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01X8LDnsexvNjSkqc2ihZR7U
---
 CLAUDE.md                   |  37 +++++++++++--
 docs/INVARIANTS.md          |  38 ++++++++++++++
 tests/domain-purity.test.ts | 101 ++++++++++++++++++++++++++++++++++++
 3 files changed, 171 insertions(+), 5 deletions(-)
 create mode 100644 tests/domain-purity.test.ts

diff --git a/CLAUDE.md b/CLAUDE.md
index e9e0d1e..1797c07 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,11 +1,38 @@
 # flashy-ledger
 
-<!-- What is this repository, what does it deploy to, and what must an agent
-     not break? Two or three sentences from somebody who knows is worth more
-     than everything below, which is only what is true everywhere. -->
+`@flashylabs/ledger` — an append-only, multi-asset settlement ledger, published
+to npm under Apache-2.0. It is the estate's **verification layer**: the rules
+flashynetwork.com checks the books against, published in the open so nobody
+takes "verifiable" on faith. It ships as a **library, not a site** — there is no
+`public/` build and no deploy target, which is why the estate fold-coverage
+survey reads it as a record repo with no served URL rather than a gap. It is
+consumed by `@flashylabs/ledger` in ClaimYour.Gold and flashy.gold. The default
+branch is `main`.
 
-_Not yet described. The house rules below are estate-wide and were synced
-here; what makes this repository different is still to be written._
+**The shape is the product, and it is ports-and-adapters with teeth.** `src/domain/`
+is a pure core — it reads no database, calls no clock, generates no randomness —
+and everything that touches storage sits behind one interface, `LedgerStore`
+(`src/ports/store.ts`). That seam is the entire migration story: a chain-backed
+store can implement it later and the rules above do not change, because the rules
+never knew where entries were kept. `src/adapters/` holds the implementations
+(in-memory, Mongo, the read-only `GoldLedgerReader`, and the `field-map` that
+lets this package's rules sit on top of a collection it did not design).
+
+**What an agent must not break** is enumerated and executable: the numbered
+guarantees in [`docs/INVARIANTS.md`](docs/INVARIANTS.md), each mapped to the test
+that proves it, with `tests/invariants.test.ts` failing the build if the doc and
+the suite drift. In particular — **`LedgerStore` has no update and no delete**,
+and that absence is the append-only invariant (I-1); correct a mistake with
+`reverse()`, never a mutation. **The `hashEntry` field order is frozen** —
+changing it invalidates every chain that exists, so it is fixed deliberately, not
+derived from object keys. **Amounts are signed integer `Minor` units**, never a
+float or a formatted string (I-2/I-3). **Identities are opaque and tenant-scoped**,
+enforced in `post()` before anything is hashed (I-8). And **the domain stays
+pure** — no adapter, port, I/O builtin or third-party import reaches into
+`src/domain/` (I-9, guarded by eslint for clocks/randomness and by
+`tests/domain-purity.test.ts` for the import graph). Run `npm run check`
+(typecheck + lint + coverage) before pushing; the roadmap, which is North Star
+beyond Phase 1, is [`docs/ROADMAP.md`](docs/ROADMAP.md).
 
 <!-- estate:house-rules -->
 <!-- Synced from flashyos/tools/estate-house-rules.mjs. Edit it there, not here.
diff --git a/docs/INVARIANTS.md b/docs/INVARIANTS.md
index 7f83286..b656990 100644
--- a/docs/INVARIANTS.md
+++ b/docs/INVARIANTS.md
@@ -181,3 +181,41 @@ guards the one consumer this package has. The surrogate is held to
 message would be wrong — and
 › *refuses a salt short enough to be brute-forced*.
 
+## I-9 · The domain is pure and storage-agnostic
+
+**Claim.** `src/domain/**` reads no database, calls no clock, and generates no
+randomness. Its only dependencies are other domain modules and `node:crypto`
+for hashing, which is deterministic. The dependency arrow points one way:
+`index` and `ports` and `adapters` may import the domain; the domain imports
+none of them.
+
+**Why.** This is the sentence the README and the roadmap rest the whole package
+on — it is *the entire reason the ledger can move onto a chain without its rules
+changing*, and why the rules can be tested exhaustively with no database in
+sight. Purity has two halves and they fail differently. A clock or a random
+source in the domain makes a hash non-replayable, so a verifier recomputing it
+later disagrees with the sealed value — the invariant that Phase 2 anchoring
+depends on. A dependency pointing the wrong way — a domain module importing an
+adapter or `node:fs` — is quieter still: it typechecks, it lints, it passes
+every behavioural test, and the seam that lets storage be swapped is gone with
+nothing red to say so.
+
+**Enforced by.** Two guards for the two halves. The runtime half is eslint on
+`src/domain/**`: `no-restricted-globals` bans `Date`, and `no-restricted-properties`
+bans `Date.now` and `Math.random`, each with the message that points at the
+fix (pass `occurredAt` in from the caller). The dependency half is
+`domain-purity.test.ts`, which reads the real import graph with the compiler's
+own `ts.preProcessFile` — never a regex, which would read an `import` inside a
+comment the same as a real one — and refuses any specifier that is not a domain
+sibling or `node:crypto`: an adapter, a port, an I/O builtin, or a third-party
+package. The two are complementary: lint catches a global *used*, the test
+catches a module *imported*, and neither alone is the invariant.
+
+**Proved by.** `domain-purity.test.ts` › *imports no adapter and no port, so storage never leaks upward*,
+› *imports no I/O builtin, only deterministic node:crypto*, and
+› *takes no third-party dependency* — the last two run over a set the suite
+first proves non-empty, so a walk that resolved nothing cannot pass them
+vacuously. The runtime half shows up as determinism:
+`ledger.test.ts` › *is pure: the same inputs always produce the same hash* and
+`merkle.test.ts` › *is deterministic regardless of input order*.
+
diff --git a/tests/domain-purity.test.ts b/tests/domain-purity.test.ts
new file mode 100644
index 0000000..bb18f02
--- /dev/null
+++ b/tests/domain-purity.test.ts
@@ -0,0 +1,101 @@
+import { describe, it, expect } from 'vitest'
+import { readFileSync, readdirSync } from 'node:fs'
+import { join, dirname, relative, resolve } from 'node:path'
+import ts from 'typescript'
+
+/**
+ * The domain is pure, and purity is a dependency rule as much as a runtime one.
+ *
+ * The README and the roadmap both rest the whole package on one sentence: the
+ * domain reads no database, calls no clock, and generates no randomness, which
+ * is the entire reason the ledger can move onto a chain without its rules
+ * changing. eslint already guards the runtime half for `src/domain/**` — `Date`,
+ * `Date.now` and `Math.random` are restricted there.
+ *
+ * It does NOT guard the other half: which way the dependency arrow points. A
+ * domain module that did `import { MongoLedgerStore } from '../adapters/mongo.js'`
+ * or `import { readFileSync } from 'node:fs'` would pass lint, typecheck and
+ * every existing test, and the seam the architecture is built on — the domain
+ * never knowing where entries are kept — would be broken silently, in exactly
+ * the direction that makes a chain migration a research project again.
+ *
+ * So this reads the real import graph of `src/domain/**`, with the compiler's
+ * own preprocessor rather than a regex (a regex reads `import` inside a comment
+ * or a string the same as a real one), and asserts the arrow only ever points
+ * at other domain modules or the one deterministic builtin the hashes need.
+ * It is structure, not prose: it resolves specifiers, it does not grep for a
+ * rule's name.
+ */
+
+const DOMAIN_DIR = resolve('src/domain')
+
+/** Every .ts file under src/domain, recursively. */
+function domainFiles(dir: string = DOMAIN_DIR): string[] {
+  const out: string[] = []
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const full = join(dir, entry.name)
+    if (entry.isDirectory()) out.push(...domainFiles(full))
+    else if (entry.name.endsWith('.ts')) out.push(full)
+  }
+  return out
+}
+
+/** Import specifiers, type-only imports included, read by the compiler not a regex. */
+function importsOf(file: string): string[] {
+  const pre = ts.preProcessFile(readFileSync(file, 'utf8'), true, true)
+  return pre.importedFiles.map((i) => i.fileName)
+}
+
+/** The one builtin the domain is allowed: sha256 hashing is deterministic and pure. */
+const ALLOWED_BUILTINS = new Set(['node:crypto'])
+
+const files = domainFiles()
+
+describe('domain purity', () => {
+  it('finds the domain modules it is meant to be guarding', () => {
+    // A walk that resolved nothing would pass every assertion below vacuously —
+    // a green check over an empty set reads exactly like a clean one.
+    expect(files.length).toBeGreaterThan(5)
+  })
+
+  it('imports no adapter and no port, so storage never leaks upward', () => {
+    const violations: string[] = []
+    for (const file of files) {
+      for (const spec of importsOf(file)) {
+        if (!spec.startsWith('.')) continue
+        const target = resolve(dirname(file), spec)
+        const within = relative(DOMAIN_DIR, target)
+        if (within.startsWith('..')) {
+          violations.push(`${relative(DOMAIN_DIR, file)} imports '${spec}' — outside the domain`)
+        }
+      }
+    }
+    expect(violations, violations.join('\n')).toEqual([])
+  })
+
+  it('imports no I/O builtin, only deterministic node:crypto', () => {
+    const violations: string[] = []
+    for (const file of files) {
+      for (const spec of importsOf(file)) {
+        if (spec.startsWith('node:') && !ALLOWED_BUILTINS.has(spec)) {
+          violations.push(`${relative(DOMAIN_DIR, file)} imports '${spec}' — a builtin the pure domain may not reach for`)
+        }
+      }
+    }
+    expect(violations, violations.join('\n')).toEqual([])
+  })
+
+  it('takes no third-party dependency', () => {
+    const violations: string[] = []
+    for (const file of files) {
+      for (const spec of importsOf(file)) {
+        const isRelative = spec.startsWith('.')
+        const isBuiltin = spec.startsWith('node:')
+        if (!isRelative && !isBuiltin) {
+          violations.push(`${relative(DOMAIN_DIR, file)} imports '${spec}' — a third-party package the domain must not depend on`)
+        }
+      }
+    }
+    expect(violations, violations.join('\n')).toEqual([])
+  })
+})

From 480412c656e871364d7596e619feb50974e9d740 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sun, 4 Oct 2026 14:06:36 +0000
Subject: [PATCH 3/5] Audit: derive the conformance population; document + test
 Mongo atomicity
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two audit findings from the ports-and-adapters layer, each closed with tests
and documentation.

1. The conformance suite's worth is the set of adapters it is pointed at, and
   that set was a hand-kept list — the shape of failure this estate has hit
   before (pulse.yml over a population of zero). The population is now derived:
   - tests/adapters.catalog.ts declares every writable LedgerStore the package
     ships, as the single source of truth.
   - conformance.test.ts builds its harnesses from the catalog (Mongo skipped
     without a database but never dropped from the count) and asserts the
     harnessed classes equal the catalog.
   - tests/adapter-coverage.test.ts checks the catalog against the package's
     real exports, recognising a writable store by structure (an append method)
     so the read-only GoldLedgerReader is excluded by that same fact. A new
     adapter exported-but-uncataloged, or cataloged-but-unharnessed, now fails
     the build. Documented in docs/INVARIANTS.md, "Coverage".

2. The Mongo adapter's refusal to tear a transfer — reject a multi-entry append
   when constructed without a client — had no test, because conformance always
   passes one. tests/mongo-adapter.test.ts covers it with a fake Db that runs on
   any machine, no infrastructure. The concurrency and atomicity design (indexes
   as the guarantee, the duplicate-key disambiguation, the session requirement)
   is recorded in docs/adr/0004-mongo-concurrency-and-atomicity.md.

Full suite 205 passing, typecheck clean, new files lint-clean.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01X8LDnsexvNjSkqc2ihZR7U
---
 docs/INVARIANTS.md                            | 25 +++++
 .../0004-mongo-concurrency-and-atomicity.md   | 78 ++++++++++++++++
 tests/adapter-coverage.test.ts                | 59 ++++++++++++
 tests/adapters.catalog.ts                     | 40 ++++++++
 tests/conformance.test.ts                     | 92 +++++++++++-------
 tests/mongo-adapter.test.ts                   | 93 +++++++++++++++++++
 6 files changed, 353 insertions(+), 34 deletions(-)
 create mode 100644 docs/adr/0004-mongo-concurrency-and-atomicity.md
 create mode 100644 tests/adapter-coverage.test.ts
 create mode 100644 tests/adapters.catalog.ts
 create mode 100644 tests/mongo-adapter.test.ts

diff --git a/docs/INVARIANTS.md b/docs/INVARIANTS.md
index b656990..b5b4890 100644
--- a/docs/INVARIANTS.md
+++ b/docs/INVARIANTS.md
@@ -219,3 +219,28 @@ vacuously. The runtime half shows up as determinism:
 `ledger.test.ts` › *is pure: the same inputs always produce the same hash* and
 `merkle.test.ts` › *is deterministic regardless of input order*.
 
+## Coverage · the suite runs against every adapter, and that is derived
+
+Every invariant above that names `conformance.test.ts` is run *against every
+adapter* — the phrase does the work only if "every adapter" is a fact rather
+than a hand-kept list that quietly stopped matching the package. A guarantee
+proven against the in-memory reference and no one else is a guarantee about the
+reference, not about the Mongo store a network actually runs.
+
+So the population is **derived**. `tests/adapters.catalog.ts` declares every
+writable `LedgerStore` the package ships; `conformance.test.ts` builds its
+harnesses from that catalog (so the suite runs exactly those classes, Mongo
+skipped without a database but never dropped from the count); and
+`adapter-coverage.test.ts` checks the catalog against the package's real
+exports, recognising a writable store by structure — an `append` method — so
+the read-only `GoldLedgerReader` is excluded by the same fact that makes it
+read-only. A new writable adapter that is exported and not cataloged, or
+cataloged and not harnessed, fails the build rather than shipping with no
+conformance behind it. This is the `pulse.yml` lesson applied locally: a check
+is only as good as the population it is pointed at, and that population is the
+part nobody re-reads, so it is computed rather than trusted.
+
+**Proved by.** `conformance.test.ts` › *harnesses every writable store class the catalog declares, and no stranger*
+and `adapter-coverage.test.ts` › *catalogs exactly the writable stores the package exports — no more, no fewer*,
+› *excludes the read-only reader by structure, not by an allowlist*.
+
diff --git a/docs/adr/0004-mongo-concurrency-and-atomicity.md b/docs/adr/0004-mongo-concurrency-and-atomicity.md
new file mode 100644
index 0000000..9bf6654
--- /dev/null
+++ b/docs/adr/0004-mongo-concurrency-and-atomicity.md
@@ -0,0 +1,78 @@
+# ADR 0004 — Concurrency and atomicity live in the Mongo adapter, as indexes
+
+**Status:** Accepted · 2026-10-04
+
+## Context
+
+ADR 0003 made the domain pure and put persistence behind `LedgerStore`. That
+leaves the hard operational guarantees — a replay never becomes a second entry,
+two concurrent appends never both build on one chain head, a transfer never
+lands half — to the adapter. The domain cannot help here: it reads no database,
+so it cannot see the race. The port (`src/ports/store.ts`) states the
+guarantees; this ADR records how the Mongo adapter keeps them, because the
+reasoning is not obvious from the code and the wrong fix (enforcing them in
+application code) looks correct right up until two processes race.
+
+## Decision
+
+**The guarantees are indexes, not code.** `ensureIndexes()` creates two unique
+indexes, and they — not the `findByIdempotencyKey` pre-check in `append()` — are
+the real guard, because code in this file runs once per process and an index
+runs on every write from every process forever.
+
+- `uniq_tenant_idempotency` on `(tenantId, idempotencyKey)` makes a replay a
+  no-op even when two processes submit the same key in the same instant, and
+  scopes the key to the tenant so two networks deriving a similar key from
+  similar source events do not deduplicate against each other.
+- `uniq_tenant_chain_head` on `(tenantId, identityId, assetId, previousHash)`
+  lets exactly one of two appends that read the same head actually land; the
+  loser gets a duplicate-key error. It needs no partial filter: `identityId` and
+  `assetId` are in the key, so "one entry with no predecessor" is scoped per
+  chain rather than one null across the collection.
+
+**A duplicate-key error is disambiguated, not swallowed.** On `insertOne`
+failing with code 11000, `append()` re-reads by idempotency key. A winner found
+means this was a replay — return it, `deduplicated: true`. No winner means the
+collision was on the chain head — a genuine conflict, thrown so the caller
+re-reads state and retries. Collapsing those two into one outcome would turn a
+lost update into a silent success.
+
+**Legacy indexes are dropped by name, first.** The pre-0.2 indexes were globally
+unique rather than tenant-scoped. A surviving `uniq_idempotency` would keep
+rejecting a second tenant's legitimate write that the new index permits, so
+creating the new indexes without dropping the old would look like a migration
+and behave like none.
+
+**A multi-entry append requires a session, and refuses without one.** A
+transfer's two legs must both commit or neither, which a single-document
+database cannot give for free. `appendAll` opens a transaction via a
+`MongoClient`; constructed without one, it rejects any batch of more than one
+entry rather than writing the first leg and failing on the second. A torn
+transfer is worse than a refused one. (A single-entry batch and an empty batch
+need no session and are allowed.)
+
+## Consequences
+
+Good: the guarantees hold under real concurrency, across processes, without a
+lock the application has to remember to take. The same conformance suite that
+the in-memory reference passes runs against this adapter unchanged (ADR 0003),
+against real Mongo in CI (`MONGO_URL` set), so "behaves like the reference" is
+proven, not asserted.
+
+Costs: multi-entry atomicity needs a replica set, so a standalone `mongod`
+cannot run transfers — which the adapter surfaces as a refusal, not a
+half-write. Transactions carry retry semantics: `withTransaction` may re-run the
+callback, so `appendAll` resets its per-attempt results rather than appending
+across attempts.
+
+## How it is proved
+
+- The concurrency and atomicity behaviour: `tests/conformance.test.ts` —
+  idempotent replay, the chain-head race, tenant isolation, and transfer
+  atomicity, run against every adapter the catalog declares (see
+  `docs/INVARIANTS.md`, *Coverage*), with Mongo exercised in CI.
+- The refusal without a client, which conformance does not reach because it
+  always passes one: `tests/mongo-adapter.test.ts` — a multi-entry append with
+  no client throws before touching the collection, and names the fix.
+- The amount-encoding boundary that an adoption is most likely to relax:
+  `tests/field-map.test.ts`, *the amount guard* (invariant I-2).
diff --git a/tests/adapter-coverage.test.ts b/tests/adapter-coverage.test.ts
new file mode 100644
index 0000000..486fc2b
--- /dev/null
+++ b/tests/adapter-coverage.test.ts
@@ -0,0 +1,59 @@
+import { describe, it, expect } from 'vitest'
+import * as pkg from '../src/index.js'
+import { WRITABLE_STORE_CLASSES, isWritableStoreClass } from './adapters.catalog.js'
+
+/**
+ * The conformance population is the package's population — derived, not trusted.
+ *
+ * `conformance.test.ts` proves every adapter it is pointed at behaves like the
+ * reference. This proves it is pointed at every adapter there is. The gap it
+ * closes is the one this estate has hit before from the other side: a suite
+ * whose worth is silently decided by a hand-kept list that stopped matching
+ * what the package actually ships. A new writable `LedgerStore` exported without
+ * a catalog entry would ship with no conformance behind it and nothing red;
+ * this fails the build instead.
+ *
+ * It reads the real module exports, so it cannot drift from them, and it
+ * recognises a writable store by structure (an `append` method), so the
+ * read-only `GoldLedgerReader` is excluded by the same fact that makes it
+ * read-only rather than by a name on a list.
+ */
+
+/** Every exported value that is a writable store class, by export name. */
+const exportedWritable = Object.entries(pkg)
+  .filter(([, value]) => isWritableStoreClass(value))
+  .map(([name, value]) => ({ name, value }))
+
+describe('adapter coverage', () => {
+  it('finds the writable stores it is meant to be guarding', () => {
+    // Vacuity guard: a green check over an empty export set would read exactly
+    // like a clean one, which is the failure this whole file exists to prevent.
+    expect(exportedWritable.length).toBeGreaterThan(0)
+  })
+
+  it('catalogs exactly the writable stores the package exports — no more, no fewer', () => {
+    const exported = new Set(exportedWritable.map((e) => e.value as unknown))
+    const cataloged = new Set<unknown>(WRITABLE_STORE_CLASSES)
+
+    const missing = [...exported].filter((c) => !cataloged.has(c))
+    const stale = [...cataloged].filter((c) => !exported.has(c))
+
+    expect(
+      missing,
+      'a writable LedgerStore is exported but not in tests/adapters.catalog.ts, so conformance never runs against it',
+    ).toEqual([])
+    expect(
+      stale,
+      'the catalog lists a class the package no longer exports as a writable store',
+    ).toEqual([])
+  })
+
+  it('excludes the read-only reader by structure, not by an allowlist', () => {
+    // GoldLedgerReader is a real export and deliberately not a LedgerStore: it
+    // has no append, so it is neither detected as writable nor cataloged, and
+    // the exclusion needs no special-case.
+    expect('GoldLedgerReader' in pkg).toBe(true)
+    expect(isWritableStoreClass((pkg as Record<string, unknown>).GoldLedgerReader)).toBe(false)
+    expect(exportedWritable.map((e) => e.name)).not.toContain('GoldLedgerReader')
+  })
+})
diff --git a/tests/adapters.catalog.ts b/tests/adapters.catalog.ts
new file mode 100644
index 0000000..c8f0b0f
--- /dev/null
+++ b/tests/adapters.catalog.ts
@@ -0,0 +1,40 @@
+import { InMemoryLedgerStore, MongoLedgerStore, type LedgerStore } from '../src/index.js'
+
+/**
+ * The writable-adapter population, declared once.
+ *
+ * `LedgerStore` is the seam the whole migration story rests on, and the
+ * conformance suite's worth is exactly the set of adapters it is pointed at — a
+ * guarantee proven against the in-memory reference and no one else is a
+ * guarantee about the reference, not about the adapter a network actually runs.
+ * This estate has paid for the other shape of that mistake (`pulse.yml` ran for
+ * nine days over a population of zero and reported success), and the lesson it
+ * wrote down is the one applied here: **the population is derived, never
+ * hand-kept beside the thing it measures.**
+ *
+ * So this is the single list of every *writable* `LedgerStore` the package
+ * ships. `tests/conformance.test.ts` builds its harnesses from it, so the suite
+ * runs exactly these classes; `tests/adapter-coverage.test.ts` checks it against
+ * the package's real exports, so a new adapter that is exported and not listed
+ * here — or listed and not exported — fails the build rather than shipping with
+ * no conformance behind it.
+ *
+ * Read-only adapters are deliberately absent. `GoldLedgerReader` is not a
+ * `LedgerStore` (it has no `append`), so it cannot be asked to satisfy a
+ * suite about writes, and the coverage guard excludes it by that same
+ * structural fact rather than by a name on an allowlist.
+ */
+export type WritableStoreClass = new (...args: never[]) => LedgerStore
+
+export const WRITABLE_STORE_CLASSES: readonly WritableStoreClass[] = [
+  InMemoryLedgerStore,
+  MongoLedgerStore,
+]
+
+/** The structural mark of a writable store: an `append` method on the prototype. */
+export function isWritableStoreClass(value: unknown): value is WritableStoreClass {
+  return (
+    typeof value === 'function' &&
+    typeof (value as { prototype?: { append?: unknown } }).prototype?.append === 'function'
+  )
+}
diff --git a/tests/conformance.test.ts b/tests/conformance.test.ts
index 5739095..2a19d7d 100644
--- a/tests/conformance.test.ts
+++ b/tests/conformance.test.ts
@@ -13,6 +13,7 @@ import {
   type ProposedEntry,
   type TransactionalLedgerStore,
 } from '../src/index.js'
+import { WRITABLE_STORE_CLASSES, type WritableStoreClass } from './adapters.catalog.js'
 
 /**
  * The conformance suite.
@@ -48,7 +49,17 @@ const MONGO_URL = process.env.MONGO_URL
 
 interface Harness {
   name: string
+  /** The adapter class this harness exercises — checked against the catalog. */
+  ctor: WritableStoreClass
   make: () => Promise<LedgerStore>
+  /**
+   * Whether this harness runs on THIS machine. Mongo needs a database, so it
+   * skips without MONGO_URL — but it stays in the list either way, so that
+   * which classes the suite COVERS is a fact about the suite, not about whether
+   * one machine happened to set an env var. The coverage assertion reads the
+   * whole list; `describe.each` runs only the un-skipped ones.
+   */
+  skip: boolean
   cleanup?: () => Promise<void>
 }
 
@@ -94,46 +105,48 @@ async function proposeFor(
   })
 }
 
-const harnesses: Harness[] = [
-  { name: 'InMemoryLedgerStore', make: async () => new InMemoryLedgerStore() },
-]
-
 let client: MongoClient | undefined
 
-if (MONGO_URL) {
-  const connect = async () => {
-    if (!client) {
-      client = new MongoClient(MONGO_URL)
-      await client.connect()
-    }
-    return client.db(`ledger_conformance_${Date.now()}_${Math.floor(Math.random() * 1e6)}`)
+/**
+ * Connect once and hand out a fresh database per call. Only ever reached from a
+ * Mongo harness, which is skipped without MONGO_URL, so the assertion is a type
+ * narrowing rather than a new failure mode.
+ */
+const connect = async () => {
+  if (!MONGO_URL) throw new Error('connect() reached with no MONGO_URL — a Mongo harness ran while skipped')
+  if (!client) {
+    client = new MongoClient(MONGO_URL)
+    await client.connect()
   }
+  return client.db(`ledger_conformance_${Date.now()}_${Math.floor(Math.random() * 1e6)}`)
+}
 
-  harnesses.push({
+/**
+ * Every writable adapter the suite covers, declared unconditionally. The Mongo
+ * entries skip without a database; they do not leave the list, because coverage
+ * is a property of the suite and not of this machine's env. The "mapped to
+ * gold_ledger" entry is the same class addressing a collection it did not
+ * design — the field map's claim tested rather than asserted: a network that
+ * already runs a ledger puts this package's rules on its existing rows, and
+ * every guarantee here (idempotency, the chain-head race, tenant isolation,
+ * transfer atomicity) still holds, or the build fails.
+ */
+const harnesses: Harness[] = [
+  { name: 'InMemoryLedgerStore', ctor: InMemoryLedgerStore, skip: false, make: async () => new InMemoryLedgerStore() },
+  {
     name: 'MongoLedgerStore',
+    ctor: MongoLedgerStore,
+    skip: !MONGO_URL,
     make: async () => {
       const store = new MongoLedgerStore(await connect(), { client })
       await store.ensureIndexes()
       return store
     },
-  })
-
-  /**
-   * The same adapter, addressing a collection it did not design.
-   *
-   * This is the claim the field map makes, tested rather than asserted: a
-   * network that already runs a ledger can put this package's rules on its
-   * existing rows, and every guarantee in this suite still holds — the
-   * idempotency uniqueness, the chain-head race, the tenant isolation, the
-   * transfer atomicity. Different column names, different source layout,
-   * different order field, same behaviour or the build fails.
-   *
-   * Without this, "you can adopt an existing collection" is a sentence in a
-   * README, and the first person to try it finds out which of these guarantees
-   * quietly stopped applying.
-   */
-  harnesses.push({
+  },
+  {
     name: 'MongoLedgerStore (mapped to gold_ledger)',
+    ctor: MongoLedgerStore,
+    skip: !MONGO_URL,
     make: async () => {
       const store = new MongoLedgerStore(await connect(), {
         client,
@@ -143,14 +156,25 @@ if (MONGO_URL) {
       await store.ensureIndexes()
       return store
     },
-  })
-}
+  },
+]
 
 afterAll(async () => {
   await client?.close()
 })
 
-describe.each(harnesses)('$name', ({ make }) => {
+describe('the conformance population', () => {
+  it('harnesses every writable store class the catalog declares, and no stranger', () => {
+    // The pulse.yml lesson, enforced locally: the suite's population is derived
+    // from the catalog, not hand-kept beside it, so an adapter cannot be added
+    // to the catalog and silently never harnessed, nor harnessed here under a
+    // class the catalog does not know.
+    const harnessed = new Set(harnesses.map((h) => h.ctor))
+    expect(harnessed).toEqual(new Set(WRITABLE_STORE_CLASSES))
+  })
+})
+
+describe.each(harnesses.filter((h) => !h.skip))('$name', ({ make }) => {
   let store: LedgerStore
 
   beforeAll(async () => {
@@ -247,7 +271,7 @@ describe.each(harnesses)('$name', ({ make }) => {
   })
 })
 
-describe.each(harnesses)('$name — transfers', ({ make }) => {
+describe.each(harnesses.filter((h) => !h.skip))('$name — transfers', ({ make }) => {
   let store: TransactionalLedgerStore
 
   beforeAll(async () => {
@@ -313,7 +337,7 @@ describe.each(harnesses)('$name — transfers', ({ make }) => {
  * Every case here fails against the pre-0.2 adapters, where `tenantId` was
  * written onto every entry and used in no query, no index and no signature.
  */
-describe.each(harnesses)('$name — tenant isolation', ({ make }) => {
+describe.each(harnesses.filter((h) => !h.skip))('$name — tenant isolation', ({ make }) => {
   let store: LedgerStore
 
   beforeEach(async () => {
diff --git a/tests/mongo-adapter.test.ts b/tests/mongo-adapter.test.ts
new file mode 100644
index 0000000..45a974f
--- /dev/null
+++ b/tests/mongo-adapter.test.ts
@@ -0,0 +1,93 @@
+import { describe, it, expect } from 'vitest'
+import { MongoLedgerStore, post, fromDecimal, type Asset, type ProposedEntry } from '../src/index.js'
+import type { Db } from 'mongodb'
+
+/**
+ * The Mongo adapter's safety edges, tested without a database.
+ *
+ * The conformance suite proves the adapter behaves like the reference, but it
+ * only runs with `MONGO_URL` set and always passes a `{ client }`. That leaves
+ * one guarantee with no test anywhere: what the adapter does when it is asked to
+ * commit a transfer and was NOT given the client a transaction needs. The port
+ * is explicit that a torn transfer is worse than a refused one, so the adapter
+ * must refuse — and a refusal is exactly the kind of path that rots unnoticed,
+ * because the happy path (a client was passed) is the one every other test
+ * exercises.
+ *
+ * These reach only the code before any collection call, so a fake `Db` whose
+ * collection is never touched is enough. They run on every machine, with no
+ * infrastructure, which is the point: the safety behaviour should not depend on
+ * whether this laptop has a replica set.
+ */
+
+const GOLD: Asset = {
+  id: 'asset_fg',
+  slug: 'flashy-gold',
+  symbol: 'FG',
+  decimals: 2,
+  class: 'REWARD_CURRENCY',
+  tenantId: 'flashy',
+}
+
+/**
+ * A Db whose collection the constructor may hold, but whose methods must never
+ * be CALLED — a query or write on a refusal path trips the stub itself. (The
+ * constructor does take the collection handle, so the handle exists; it is any
+ * read or write THROUGH it that a refusal must not perform.)
+ */
+function untouchedDb(): Db {
+  const used = () => {
+    throw new Error('the collection was used — a refusal should never reach the database')
+  }
+  const collectionStub = new Proxy({}, { get: () => used })
+  return { collection: () => collectionStub } as unknown as Db
+}
+
+/** Two legs of a transfer, built through the domain so they are real entries. */
+function transferPair(): ProposedEntry[] {
+  const zero = { balance: fromDecimal(0, GOLD.decimals), headHash: null }
+  const debit = post(zero, {
+    tenantId: 'flashy',
+    identityId: 'alice',
+    asset: GOLD,
+    amount: fromDecimal(-5, GOLD.decimals),
+    kind: 'TRANSFER_OUT',
+    source: { type: 'transfer', id: 't_1' },
+    idempotencyKey: 'transfer:t_1:alice',
+    occurredAt: new Date('2026-01-01T00:00:00Z'),
+    allowNegative: true,
+  })
+  const credit = post(zero, {
+    tenantId: 'flashy',
+    identityId: 'bob',
+    asset: GOLD,
+    amount: fromDecimal(5, GOLD.decimals),
+    kind: 'TRANSFER_IN',
+    source: { type: 'transfer', id: 't_1' },
+    idempotencyKey: 'transfer:t_1:bob',
+    occurredAt: new Date('2026-01-01T00:00:00Z'),
+  })
+  return [debit, credit]
+}
+
+describe('MongoLedgerStore without a client', () => {
+  it('refuses a multi-entry append rather than tearing a transfer', async () => {
+    // No client means no session means no atomicity. The adapter must reject the
+    // batch before writing anything, not write the first leg and discover the
+    // problem on the second.
+    const store = new MongoLedgerStore(untouchedDb())
+    await expect(store.appendAll(transferPair())).rejects.toThrow(/needs a MongoClient/)
+  })
+
+  it('names the fix in the refusal, so the caller knows to pass { client }', async () => {
+    const store = new MongoLedgerStore(untouchedDb())
+    await expect(store.appendAll(transferPair())).rejects.toThrow(/Pass \{ client \}/)
+  })
+
+  it('treats an empty batch as a no-op, never a session', async () => {
+    // Zero entries need no transaction at all, so this must succeed with no
+    // client and without reaching the collection.
+    const store = new MongoLedgerStore(untouchedDb())
+    expect(await store.appendAll([])).toEqual([])
+  })
+})

From 524ad8af47e38b6823f888847791b29721474898 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sun, 4 Oct 2026 14:09:38 +0000
Subject: [PATCH 4/5] Fix pre-existing lint break: type the parsed charter in
 charter-served test
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

npm run lint (hence npm run check, hence CI) was red before this branch:
charter-served.test.ts did `const parsed = JSON.parse(served)` — an `any` —
and then `parsed.slug` / `parsed.roles`, three no-unsafe-member-access errors
under the repo's strictTypeChecked config (typescript 5.9.3, as the lockfile
pins). Not introduced here, but it blocks the repo's own gate and this PR.

Typed the parse as Record<string, unknown> and narrowed `roles` through
Array.isArray before reading .length — no behaviour change, the two
assertions are identical. npm run check now passes: typecheck + lint +
coverage (98.24% stmts, above the 90/85/90/90 thresholds).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01X8LDnsexvNjSkqc2ihZR7U
---
 tests/charter-served.test.ts | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/tests/charter-served.test.ts b/tests/charter-served.test.ts
index c4b78c3..c4f90c6 100644
--- a/tests/charter-served.test.ts
+++ b/tests/charter-served.test.ts
@@ -30,9 +30,10 @@ describe('/.well-known/flashyos-charter.json', () => {
   });
 
   it('is a charter, not an empty file that happens to exist', () => {
-    const parsed = JSON.parse(served);
+    const parsed = JSON.parse(served) as Record<string, unknown>;
     expect(parsed.slug, 'a charter with no slug names no organisation').toBeTruthy();
-    expect(Array.isArray(parsed.roles) && parsed.roles.length > 0,
+    const roles = parsed.roles;
+    expect(Array.isArray(roles) && roles.length > 0,
       'a roster of zero roles reads to the network as an org that declares nothing').toBe(true);
   });
 });

From a18b48723739bb3282b359a7c8100528bc95bf3f Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 5 Oct 2026 01:15:59 +0000
Subject: [PATCH 5/5] Clear #14's two base-CI failures: brace-expansion audit +
 the 1.0.0 release row
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Both were pre-existing on main and red on this PR; the user asked for the
brace-expansion fix and for the record to reflect production reality.

- Dependency audit: `npm audit fix --package-lock-only` bumps the transitive
  brace-expansion past the quadratic-expansion / recursion DoS advisories
  (GHSA-q2hr-2g5m-vwhr and siblings). Lockfile-only, package.json untouched;
  `npm ci` clean, `npm audit --audit-level=high` reports 0 vulnerabilities, and
  the full suite still passes (the bump is transitive under eslint's matcher).

- releases.test: `package.json` declares 1.0.0 (cf4d9ba) with no ledger row.
  Measured the publish rather than assuming it: all three publish.yml runs for
  v1.0.0 (2026-09-25) failed at "Publish to npm" with `npm error code
  ENEEDAUTH` — the tarball built but never authenticated to npm.pkg.github.com,
  so 1.0.0 is NOT on the registry. A `v1.0.0` git tag was pushed anyway, which
  the ledger's own rule forbids (a tag must back a landed publish), so the row
  records the tag as unbacked, not ✅. The 2026-10-05 note explains the
  regression and that fixing the publish auth is an operator action.

npm run check green: typecheck + lint + coverage (98.24% stmts), 219 tests,
0 vulnerabilities.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01X8LDnsexvNjSkqc2ihZR7U
---
 RELEASES.md       | 20 ++++++++++++++++++++
 package-lock.json | 16 ++++++++--------
 2 files changed, 28 insertions(+), 8 deletions(-)

diff --git a/RELEASES.md b/RELEASES.md
index 581a8f5..208e4f5 100644
--- a/RELEASES.md
+++ b/RELEASES.md
@@ -56,6 +56,7 @@ tagged never succeeded.
 | 0.6.3 | `d10f9dc` | ✅ v0.6.3 | **landed** (run 13) | publish succeeded; the mirror step failed after it, so the tag was skipped. Tagged 2026-09-05; run 17 then answered E409, confirming it is on the registry |
 | 0.7.0 | `6af5ee1` | ❌ | never dispatched | "declare the civilization commodities"; superseded by 0.8.0 the same day |
 | 0.8.0 | `e52704b` | ✅ v0.8.0 | **landed** (run 14) | same shape as 0.6.3. Tagged 2026-09-05; runs 15 and 16 both answered E409 |
+| 1.0.0 | `cf4d9ba` | ⚠️ `v1.0.0` unbacked | ❌ **ENEEDAUTH** (not on the registry) | the major bump. `publish.yml` runs on 2026-09-25 built the 1.0.0 tarball (89 files, 311 kB) but every run failed at **Publish to npm** with `npm error code ENEEDAUTH` — never authenticated to `npm.pkg.github.com`. A `v1.0.0` git tag (`1a8aba65`) was pushed anyway, so it backs **no published release** — the one thing the rule below forbids. The tag is still a valid git ref, so a consumer can install 1.0.0 from it (`#v1.0.0` builds from source via `prepare`); it is just not on the registry. See the 2026-10-05 note |
 
 **Confirmed 2026-09-05.** Pushing v0.6.3 and v0.8.0 fired the tag flow, and both
 runs reached `npm publish` and stopped at **E409 Cannot publish over existing
@@ -80,6 +81,25 @@ were pushed on 2026-09-05 and each names a release that actually landed.
 Every version this package has ever declared now has either a tag or a
 recorded reason for not having one. The next release tags itself.
 
+## 1.0.0 regressed the publish — measured 2026-10-05
+
+The line above — "the workflow... can no longer fail a release" — did not hold
+for 1.0.0, and saying so is the point of a measured trail. The three
+`publish.yml` runs for `v1.0.0` on 2026-09-25 all failed, and not the way 0.8.0
+did. 0.8.0 reached `npm publish` and was refused E409 (already present), which
+proves the token authenticates. 1.0.0 got as far as building the tarball and
+then failed at **Publish to npm** with `npm error code ENEEDAUTH` — "need auth…
+requires you to be logged in to https://npm.pkg.github.com". It never
+authenticated at all.
+
+So the registry carries the record through **0.8.0**; `1.0.0` is a declared,
+tagged version that was never published. Fixing it is an operator action on the
+publish workflow's auth (the `setup-node` registry/token wiring for the publish
+step), not a code change in this package — tracked for the owner. Until it
+lands, a consumer adopting 1.0.0 pins the **git tag** (`git+https://github.com/FlashyLabs/flashy-ledger.git#v1.0.0`),
+which installs from source via `prepare` and needs no registry; a consumer on
+the registry stays at `^0.8.0`, the newest version actually published.
+
 Optional, and unrelated to the trail: set **`NPM_TOKEN`** (read-write on
 `@flashylabs`) to mirror releases to public npm, where a stranger can install
 with no auth. GitHub Packages requires a token even for a public package.
diff --git a/package-lock.json b/package-lock.json
index 2864071..50a776f 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,12 +1,12 @@
 {
   "name": "@flashylabs/ledger",
-  "version": "0.8.0",
+  "version": "1.0.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@flashylabs/ledger",
-      "version": "0.8.0",
+      "version": "1.0.0",
       "license": "Apache-2.0",
       "devDependencies": {
         "@eslint/js": "^9.17.0",
@@ -875,9 +875,9 @@
       }
     },
     "node_modules/@typescript-eslint/typescript-estree/node_modules/brace-expansion": {
-      "version": "5.0.9",
-      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-5.0.9.tgz",
-      "integrity": "sha512-ScQ4IuvIEF1TMlP7Zt+vjJ//9zlPb2SDcxWxM3bk8s6t6GGdJ7KO1dCcTidOPJKePW30LE/2cT7wCyPho9/Wxg==",
+      "version": "5.0.12",
+      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-5.0.12.tgz",
+      "integrity": "sha512-YovQ3rzhaLMIrDjNDMkNS01tea93qhEhG5xy8f6+R0l+dw3Ki+5sCoIoI942iuLZTHWogWktgwVDhU09iNEimQ==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
@@ -1195,9 +1195,9 @@
       "license": "MIT"
     },
     "node_modules/brace-expansion": {
-      "version": "1.1.18",
-      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.18.tgz",
-      "integrity": "sha512-Edep/X9fGqVNmzKBVsDYIOtD+z1tuezV70LBjdCst9Tqu76lsnvRiZ6oTic1n+/BIwX6QDGAO94PN4N2SADvtw==",
+      "version": "1.1.21",
+      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.21.tgz",
+      "integrity": "sha512-9zeA+KLZNNzglF2TPKRQEDyx6Yby7daAkuy8MiPzpXPsYDWi/DRM8jmwUDxokQjYqBpv5DgPiwD4h4ZZSy1Ujw==",
       "dev": true,
       "license": "MIT",
       "dependencies": {