From 1a6ed11557c2937def9ef85e23babe780253732d Mon Sep 17 00:00:00 2001
From: Thor Whalen <1906276+thorwhalen@users.noreply.github.com>
Date: Fri, 21 Aug 2026 16:16:06 +0100
Subject: [PATCH] docs: refresh fleet figures from the #91 ledger; correct #92
 and #94 scope
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The fleet program's substrate (#91) is built: the one-shot 2026-08-03 import
census is now an append-only ledger in gitignored misc/data/ (full commit pins
+ restore helper, per-dependent baseline suite results, an AST census, a
generated zero-usage report, one immutable record per scan).

Only the doc-side figures are committable — the ledger and its data are
gitignored — so this commit replaces every stale number and the two roadmap
entries whose scope the scan changed:

- 89 direct dependents, not 85 (121 transitive, of 217 registry packages).
- Import != subclass, now measurable: 29 dependents actually subclass a core
  class across 141 classes; 3 more import one and never subclass it.
- #94: 82 of 148 exports have zero fleet usage, but only 58 have been public
  over a year — that cohort is the candidate pool. The other 24 are the
  recently shipped content/autoviv/path_*_writeback surface.
- #92 reframed: the successor spelling is already live (wrap_kvs accepts
  key/value_encoder/_decoder as aliases onto the X_of_Y four) and the fleet is
  already split across both — 34 pkgs/132 sites vs 9 pkgs/28 sites, 5 packages
  using both. Meanwhile kv_wrap's directional kwargs have no named fleet uses
  and key_codec/value_codec have none at all. Two live spellings to converge,
  not three peers to reconcile.

Refs #91, #92, #94
---
 CLAUDE.md                | 13 +++++++---
 misc/docs/README.md      | 14 +++++-----
 misc/docs/dol_roadmap.md | 55 +++++++++++++++++++++++++++-------------
 3 files changed, 54 insertions(+), 28 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 1d8d4c26..b1620206 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -227,10 +227,15 @@ and the full doc index with status labels. The table below is the quick version.
 | [dol_content_metadata_bifurcation.md](misc/docs/dol_content_metadata_bifurcation.md) | The content/metadata split-store problem (feeds issue #80) |
 | [code-quality-improvements.md](misc/docs/code-quality-improvements.md) | Tech-debt tracker: dead code, coverage gaps (feeds issue #94) |
 
-> A **local-only** ecosystem inventory (gitignored) lives in `misc/data/`: dol's 85
-> direct dependents (as of the 2026-08-03 scan), their usages (file:line), a pre-PR
-> test-gate order + runner, and the `wrap_kvs` blast-radius scan. Regenerate with
-> the scripts there. Growing this into a versioned fleet ledger is issue #91.
+> The **fleet usage ledger** ([#91](https://github.com/i2mint/dol/issues/91)) lives
+> in gitignored `misc/data/` — start at its [README](misc/data/README.md).
+> `python -m fleet_ledger scan` records one immutable, timestamped scan: dol's **89
+> direct dependents** pinned at full 40-char commits, their imports, AST-verified
+> subclasses and call-site kwargs (all `file:line`), a generated zero-usage report,
+> and the pre-PR test-gate order. `baseline` captures every dependent's suite result
+> so a candidate's damage can be told apart from pre-existing red; `pin restore`
+> freezes the fleet at a scan and `pin undo` releases it. Scans accumulate — nothing
+> is overwritten. Figures quoted in these docs are from the 2026-08-21 scan.
 
 ---
 
diff --git a/misc/docs/README.md b/misc/docs/README.md
index a8011d8a..8220e3f0 100644
--- a/misc/docs/README.md
+++ b/misc/docs/README.md
@@ -47,7 +47,7 @@ Limitations.
 the `dol-dev-wrap-kvs` skill before touching `trans.py`/`base.py` →
 [dol_roadmap.md](dol_roadmap.md) for what's in flight → then the design-study
 chain for your area (see the index). Before any PR touching `wrap_kvs`: the
-dependents test-gate (local `misc/data/` inventory).
+dependents test-gate (`fleet_ledger baseline`, in local `misc/data/`).
 
 **I'm an agent needing orientation.**
 `llms.txt` → project `CLAUDE.md` → stop. Escalate to
@@ -104,8 +104,10 @@ parallel: [dol_issue16_design.md](dol_issue16_design.md) →
 | [frontend_dol_ideas.md](frontend_dol_ideas.md) | `zoddal`: the TypeScript/Zod incarnation of the dol idea. |
 | [generate_llms_txt_instruction.md](generate_llms_txt_instruction.md) | How the repo's `llms.txt` files are generated. |
 
-> A **local-only** ecosystem inventory (gitignored) lives in `misc/data/`: dol's
-> 85 direct dependents, their usages (file:line), a pre-PR test-gate order +
-> runner, and the `wrap_kvs` blast-radius scan. Regenerate with the scripts
-> there. Growing this into a versioned fleet ledger is
-> [#91](https://github.com/i2mint/dol/issues/91).
+> The **fleet usage ledger** ([#91](https://github.com/i2mint/dol/issues/91)) lives
+> in gitignored `misc/data/` (see its `README.md`). Each `fleet_ledger scan` is one
+> immutable, timestamped record: dol's **89 direct dependents** at full commit pins,
+> their imports / AST-verified subclasses / call-site kwargs, a generated zero-usage
+> report, and the pre-PR test-gate order. `baseline` captures each dependent's suite
+> result — the reference a candidate is judged against — and `pin restore` freezes
+> the fleet at a scan. Scans accumulate; figures below are from the 2026-08-21 scan.
diff --git a/misc/docs/dol_roadmap.md b/misc/docs/dol_roadmap.md
index 7c6919b2..9b8f172e 100644
--- a/misc/docs/dol_roadmap.md
+++ b/misc/docs/dol_roadmap.md
@@ -5,7 +5,7 @@
 > of [dol_issues_report.md](dol_issues_report.md) §2 (kept as the 2026-07-02 triage
 > snapshot — its close-list, dependency map, and verification log remain the
 > evidence record). Design content lives in the linked docs; this file only
-> sequences it. Last updated 2026-08-21.
+> sequences it. Last updated 2026-08-21 (Track D #91 built).
 
 ## The program in one paragraph
 
@@ -54,25 +54,44 @@ P2/P3 design work. Open issues folded in here: [#18](https://github.com/i2mint/d
 
 ## Track D — the fleet program (intent recorded 2026-08-21)
 
-Maintainer intents, recorded as issues; sequencing is **ledger first** — both
-other legs consume it.
-
-1. **[#91 — fleet usage ledger](https://github.com/i2mint/dol/issues/91)**: grow
-   the local import-census (85 direct dependents, 2026-08-03 scan) into a
-   versioned ledger: full commit pins + baseline test results + restore helper;
-   AST-level subclass and kwarg census; zero-usage report; successive scans.
+Sequencing is **ledger first** — both other legs consume it.
+
+1. **[#91 — fleet usage ledger](https://github.com/i2mint/dol/issues/91) — built
+   (2026-08-21)**. The v1 import census is now an append-only ledger under
+   gitignored `misc/data/` (`fleet_ledger`, see `misc/data/README.md`): full 40-char
+   commit pins with a restore/undo helper, per-dependent baseline suite results,
+   an AST census (subclassing and call-site kwargs, not just imports), a generated
+   zero-usage report, and one immutable record per scan. Headline figures from the
+   first v2 scan, superseding the 2026-08-03 numbers everywhere:
+   **89** direct dependents (121 transitive, of 217 registry packages);
+   **29** of them subclass a core class (`Store`/`KvReader`/`KvPersister`/`Collection`)
+   across **141** classes, while 3 more import one without ever subclassing it;
+   **40** call `wrap_kvs` across **112** call sites, 29 of those as a class decorator.
 2. **[#92 — vocabulary horizon](https://github.com/i2mint/dol/issues/92)**:
-   `{kind}_{encoder|decoder|codec}` replaces the `X_of_Y` language (and
-   `kv_wrap`'s `outcoming_*`/`ingoing_*` — three vocabularies to reconcile).
-   Strategy: successor surface, not rename-in-place; `wrap_kvs` stays as a
-   back-compat facade over it. Execution gated on P1 evidence + P2 facade + #91.
-   New surfaces adopt the target vocabulary from day one (the flat engine's
-   `Codec(encoder, decoder)` already does).
+   `{kind}_{encoder|decoder|codec}` replaces the `X_of_Y` language. Strategy:
+   successor surface, not rename-in-place; `wrap_kvs` stays as a back-compat facade
+   over it. Execution gated on P1 evidence + P2 facade + #91. **The ledger reframes
+   the scope** (2026-08-21 scan): the successor spelling is not prospective — dol
+   already accepts `key_encoder`/`key_decoder`/`value_encoder`/`value_decoder` as
+   aliases onto the four `X_of_Y` names (`dol/trans.py`), and the fleet is *already
+   split* across both — **34** packages / **132** call sites on `X_of_Y` versus
+   **9** packages / **28** sites on encoder-decoder, with 5 packages using both.
+   The other two vocabularies are near-dead by comparison and cheap to settle:
+   `kv_wrap` is called by 2 packages (5 calls, none passing its `outcoming_*`/
+   `ingoing_*` kwargs by name), and `key_codec`/`value_codec` have **zero** fleet
+   call sites. So the real work is converging two live spellings of the same four
+   arguments, not reconciling three peers. New surfaces adopt the target vocabulary
+   from day one (the flat engine's `Codec(encoder, decoder)` already does).
 3. **[#94 — cruft audit](https://github.com/i2mint/dol/issues/94)**: relocate
-   fleet-unused, low-value members (→ xdol / tests / recipes). Current scan:
-   86/147 `__init__` exports with zero detected fleet usage (61 public >1 year).
-   Gated on #91's authoritative census (star-imports + submodule-only compat
-   surface). Complementary to [#70](https://github.com/i2mint/dol/issues/70).
+   fleet-unused, low-value members (→ xdol / tests / recipes). Per the 2026-08-21
+   ledger scan: **82 of 148** `__init__` exports have zero detected fleet usage, of
+   which **58** have been public over a year — that cohort, not the 82, is the
+   candidate pool (the other 24 are the recently shipped `content`/`autoviv`/
+   `path_*_writeback` surface, which nothing has had time to adopt). Three caveats
+   ship with the list and are generated into it: fleet-only scope (dol is on PyPI),
+   5 star-importing packages, and **47** submodule-only names that are live compat
+   surface without being exports. Complementary to
+   [#70](https://github.com/i2mint/dol/issues/70).
 
 ## Track E — hygiene and remaining triage