@volter/twin-standard 1.0.149 → 1.0.151

package/src/tools/life-coverage-walk.ts

@@ -0,0 +1,173 @@
+import { parseExactJson } from '@volter/world-core/exact-json';
+// The walks `life-coverage.ts` measures: one pack's customer life, walked with its beats on
+// the in-memory World, and the vendor's published examples replayed (journeys/vendor-examples.json, vendor-examples.ts)
+// on a World of their own: a line only the vendor's own example reaches is reached for the reason the vendor gives. Bun measures coverage only inside `bun test`, so the measurement runs the walk through
+// a test file life-coverage writes, which registers them (coverageWalks), and reads the lcov it leaves; the walk holding
+// is its precondition, not what it measures. This module is no test file itself, so a published package holds it.
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { listActions, observeTransitions, stateOf, type Actor, type DerivedManifest, type Transition } from '@volter/world-core/runtime';
+import { inMemoryWorld, walk, type Failure, usePacks } from '../walk/behavior-journey.ts';
+import { lanesOf, shapeChecker } from '../walk/shape.ts';
+import { sharingLanesIn } from '../lanes.ts';
+
+/** Registers, in the `bun test` run that imports it, the walks of `vendor` in the pack repository at `PACKS`. */
+export async function coverageWalks(PACKS: string, vendor: string): Promise<void> {
+const { expect, test } = await import('bun:test');
+usePacks(PACKS);
+const sharingLanes = (v: string): string[] => (v.includes('/') ? [] : sharingLanesIn(join(PACKS, v), v));
+
+const journeys = join(PACKS, vendor, 'journeys');
+const walks = [{ file: 'customer-life.json', beats: true }, { file: 'vendor-examples.json', beats: false }].filter((w) => existsSync(join(journeys, w.file)));
+const seen = new Set<string>();
+const undeclared = new Set<string>();
+
+for (const [n, w] of walks.entries()) test(`${vendor}: ${w.file} walks`, async () => {
+  const life = parseExactJson(readFileSync(join(journeys, w.file), 'utf8'));
+  const world = inMemoryWorld(`coverage-${vendor}-${n}`);
+  const failures: Failure[] = [];
+  // each declared transition the life moved through or was refused by, named by resource, field and its place
+  const { manifest } = (await import(join(PACKS, vendor, 'src', 'manifest.ts'))) as { manifest: DerivedManifest };
+  // the lanes over the vendor's state its serve factory serves are walked by this life, their machines with the vendor's
+  // ("Pack layout"); two manifests naming one resource's field would collide in the keys below, so that refuses
+  const laneManifests = await Promise.all(sharingLanes(vendor).map(async (l) => ((await import(join(PACKS, vendor, l, 'src', 'manifest.ts'))) as { manifest: DerivedManifest }).manifest));
+  // a vendor of lanes' root (a VendorManifest) declares no resources of its own: its lanes do
+  const allResources = [manifest, ...laneManifests].flatMap((mf) => Object.entries(mf.resources ?? {}));
+  const machines = new Map<string, unknown>();
+  for (const [resource, decl] of allResources) for (const [field, machine] of Object.entries(decl.state ?? {})) {
+    const name = `${resource}.${field}`;
+    const previous = machines.get(name);
+    // Lanes sharing one vendor import the same state declaration; distinct declarations still collide.
+    if (previous && previous !== machine) throw new Error(`${vendor}: ${name} is declared by two manifests (the vendor's and a lane's)`);
+    machines.set(name, machine);
+  }
+  const where = new Map<Transition, Array<{ at: string; field: string; type: string; service: string }>>();
+  for (const mf of [manifest, ...laneManifests]) for (const [resource, decl] of Object.entries(mf.resources ?? {})) {
+    for (const [field, m] of Object.entries(decl.state ?? {})) m.transitions.forEach((t, i) => {
+      const place = { at: `${resource}.${field}#${i}`, field, type: decl.storedAs ?? resource, service: mf.service ?? mf.vendor };
+      const places = where.get(t) ?? [];
+      if (!places.some((p) => p.at === place.at && p.type === place.type && p.service === place.service)) where.set(t, [...places, place]);
+    });
+  }
+  const moves = new Map<string, Array<{ transition: Transition; from: string; field: string; actor: Actor; subject: string }>>();
+  const subjectKey = (service: string, type: string, id: string): string => JSON.stringify([service, type, id]);
+  observeTransitions((_decl, t, outcome, from, entry) => {
+    const places = where.get(t) ?? [];
+    if (outcome === 'refused') {
+      // A failed check on an already committed write is no refusal the application received.
+      if (entry) return;
+      const groups = new Set(places.map((p) => JSON.stringify([p.service, p.type, p.field])));
+      if (groups.size === 1) for (const p of places) seen.add(`${p.at}|refused|${from}`);
+      return;
+    }
+    // a move the machine allowed on a step with no write behind it (a line protocol's session, whose stage is the
+    // connection's): reached, as a refusal given is, where its declaration is unambiguous
+    if (!entry) {
+      const groups = new Set(places.map((p) => JSON.stringify([p.service, p.type, p.field])));
+      if (groups.size === 1) for (const p of places) seen.add(`${p.at}|moved|${from}`);
+      return;
+    }
+    if ((t.actor ?? 'api') !== entry.actor) return;
+    const { action, field, actor } = entry;
+    const matching = places.filter((p) => p.service === action.service && p.type === action.subject.type && p.field === field);
+    if (!matching.length) return;
+    for (const p of matching) seen.add(`${p.at}|moved|${from}`);
+    const on = moves.get(action.id) ?? [];
+    on.push({ transition: t, from, field, actor, subject: subjectKey(action.service, action.subject.type, action.subject.id) });
+    moves.set(action.id, on);
+  });
+  const root = world.root();
+  // what each step was answered, by the spec operation it called: a refusal is seen at the wire, whichever code gave it
+  const shape = await shapeChecker(join(PACKS, vendor));
+  const answered: Array<{ op: string; text: string; body: unknown }> = [];
+  try {
+    await walk(life, root, failures, { beats: w.beats, hooks: { after: (step, path, answer) => {
+      // a line step's refusals are the machine's own (observeTransitions); a request's are read off its answer
+      const op = 'method' in step ? shape?.operationOf(step.method, path, { ...(life.headers ?? {}), ...(step.headers ?? {}) })?.op.id : undefined;
+      if (op) answered.push({ op, text: JSON.stringify(answer.body ?? ''), body: answer.body });
+    } } });
+    // a declared refusal is reached when a step on its operation was answered with it: its code, or its message
+    // up to the first placeholder
+    // a code is a value of the answer (X's `89` at errors[].code), never a run of digits inside another value (a token)
+    const holds = (value: unknown, code: string): boolean => (value !== null && typeof value === 'object'
+      ? Object.values(value as Record<string, unknown>).some((v) => holds(v, code))
+      : (typeof value === 'string' || typeof value === 'number') && String(value) === code);
+    const answers = (a: { text: string; body: unknown }, r: { code?: string | number; message: string }): boolean =>
+      r.code !== undefined ? holds(a.body, String(r.code)) : a.text.includes(r.message.split('{')[0]!.trim());
+    for (const [resource, decl] of allResources) {
+      for (const [field, m] of Object.entries(decl.state ?? {})) {
+        m.transitions.forEach((t, i) => {
+          if (!t.operation) return;
+          const on = answered.filter((a) => a.op === t.operation);
+          if (t.refusal && on.some((a) => answers(a, t.refusal!))) seen.add(`${resource}.${field}#${i}|refused|*`);
+          for (const [from, r] of Object.entries(t.refusals ?? {})) if (on.some((a) => answers(a, r))) seen.add(`${resource}.${field}#${i}|refused|${from}`);
+        });
+      }
+    }
+    // every change the life made to a declared state field, from the World's log in order: a move is the declared
+    // transition that allows it (from its state to the next, by its operation when both name one); a change no
+    // transition allows is an undeclared move
+    const fieldsOf = new Map<string, Array<[string, string, (typeof manifest.resources)[string]['state'] extends infer S ? S extends Record<string, infer F> ? F : never : never]>>();
+    for (const mf of [manifest, ...laneManifests]) for (const [resource, decl] of Object.entries(mf.resources ?? {})) {
+      const key = JSON.stringify([mf.service ?? mf.vendor, decl.storedAs ?? resource]);
+      for (const [field, m] of Object.entries(decl.state ?? {})) fieldsOf.set(key, [...(fieldsOf.get(key) ?? []), [resource, field, m]]);
+    }
+    const current = new Map<string, Record<string, unknown>>();
+    // the services the life wrote: the vendor's, or its lanes' (a vendor of lanes' root names none of its own)
+    const services = [...new Set([manifest, ...laneManifests].map((mf) => mf.service).filter((x): x is string => typeof x === 'string'))];
+    if (!services.length) services.push(manifest.vendor);
+    for (const a of services.flatMap((service) => listActions(service, root))) {
+      if (a.op !== 'set' || !a.fields) continue;
+      const key = subjectKey(a.service, a.subject.type, a.subject.id);
+      const prev = current.get(key);
+      const next = { ...(prev ?? {}), ...(a.fields as Record<string, unknown>) };
+      current.set(key, next);
+      if (!prev) continue;
+      const opId = typeof a.input?.operationId === 'string' ? a.input.operationId : undefined;
+      // resources stored as one type (a response the beta and the GA API both serve) share its fields: a
+      // change is declared when any of their machines allows it
+      const changed = new Map<string, { declared: boolean; name: string }>();
+      const valueOf = (row: Record<string, unknown>, field: string): unknown => field.split('.').reduce<unknown>((value, part) => value && typeof value === 'object' ? (value as Record<string, unknown>)[part] : undefined, row);
+      for (const [resource, field, m] of fieldsOf.get(JSON.stringify([a.service, a.subject.type])) ?? []) {
+        if (!(field.split('.')[0]! in (a.fields as Record<string, unknown>))) continue;
+        const from = stateOf(m, valueOf(prev, field));
+        const to = stateOf(m, valueOf(next, field));
+        if (from === to) continue;
+        const allows = (t: (typeof m.transitions)[number], at: string): boolean => (moves.get(a.id) ?? []).some((move) =>
+          move.transition === t && move.from === at && move.field === field && move.actor === (t.actor ?? 'api') &&
+          move.subject === subjectKey(a.service, a.subject.type, a.subject.id));
+        const i = m.transitions.findIndex((t) => allows(t, from) && (t.to ?? from) === to);
+        if (i >= 0) seen.add(`${resource}.${field}#${i}|moved|${from}`);
+        // one write may carry several declared moves the machine walked (a batch the vendor works from
+        // validating through to completed as a read first looks); each step was observed as it was asked
+        const reached = new Set([from]);
+        for (let grew = true; grew && !reached.has(to);) {
+          grew = false;
+          for (const at of [...reached]) for (const t of m.transitions) if (allows(t, at) && t.to && !reached.has(t.to)) { reached.add(t.to); grew = true; }
+        }
+        const was = changed.get(field);
+        changed.set(field, { declared: (was?.declared ?? false) || reached.has(to), name: was?.name ?? `${resource}.${field}: ${from} → ${to} by ${opId ?? a.operation ?? '(unnamed)'}` });
+      }
+      for (const c of changed.values()) if (!c.declared) undeclared.add(c.name);
+    }
+  } finally { world.restore(); observeTransitions(undefined); }
+  // each walk adds what it reached; the last one written holds them all
+  if (process.env.LIFE_TRANSITIONS) writeFileSync(process.env.LIFE_TRANSITIONS, JSON.stringify({ seen: [...seen].sort(), undeclared: [...undeclared].sort() }));
+  expect(failures.filter((f) => f.beat !== 'SHAPE')).toEqual([]);
+// a walk's time grows with its steps and the state they build (Stripe's 609 example steps took 70 s uninstrumented,
+// measured 2026-09-26, each request catching the World up over every row it holds)
+}, 180_000);
+
+// A pack's lanes reach its code through the pack's router (a management-API life making a database branch the data
+// plane then serves): their lives and examples, walked here too, count toward the pack's code, not its state logic
+// (each lane's machines are its own, measured when the lane is). A lane is measured alone, with no lanes of its own.
+const PACK = join(PACKS, vendor);
+const laneWalks = vendor.includes('/') ? [] : lanesOf(PACK).flatMap((dir) => [{ file: 'customer-life.json', beats: true }, { file: 'vendor-examples.json', beats: false }]
+  .filter((w) => existsSync(join(dir, 'journeys', w.file))).map((w) => ({ ...w, path: join(dir, 'journeys', w.file), lane: dir.split('/').slice(-2).join('/') })));
+for (const [n, w] of laneWalks.entries()) test(`${vendor}: ${w.lane} ${w.file} walks for the pack's code`, async () => {
+  const world = inMemoryWorld(`coverage-${vendor}-lane-${n}`);
+  const failures: Failure[] = [];
+  try { await walk(parseExactJson(readFileSync(w.path, 'utf8')), world.root(), failures, { beats: w.beats }); } finally { world.restore(); }
+  expect(failures.filter((f) => f.beat !== 'SHAPE')).toEqual([]);
+}, 180_000);
+}

package/src/tools/life-coverage.ts

@@ -0,0 +1,237 @@
+#!/usr/bin/env bun
+// life-coverage — how much of a pack's hand-written code and declared state logic its customer life and its vendor's
+// published examples (vendor-examples.ts) reach
+// (docs/contributing/architecture.md, "Protocol 3", Coverage). Hand-written is every file under the pack's src/ on disk
+// (its sharing lanes' too), but for the generated core (src/generated/) and the command line (src/cli.ts), which no
+// World's fetch runs; a file of data (seed.ts, budget.ts) is in scope and has nothing to reach. State logic is every declared transition and every refusal its guard gives, read from the World's
+// log and the answers. The standard is all of it: each item is reached, or recorded in journeys/unreachable.json with
+// the reason no World reaches it; what is neither is missing, and a pack is done when nothing is missing.
+//
+// The instrument's limits, measured on Bun 1.3.10 (`bun test --coverage --coverage-reporter=lcov`): a line is counted
+// by its first statement, so both sides of `a ? b : c` count once either runs; the last line of a block that never ran
+// can read as run once (a function `if (x > 0) { return x; } const y = x * 7; return y - 1;` called with 5 marked
+// `return y - 1` hit while `const y` read 0), so a lone unrun statement at a block's end can be counted reached; and a
+// function declared below module-scope constants it follows was seen to mark every line above it unrun (aws's
+// schedule.ts, until the function moved above them). A function that never runs still reads 0 on its first line, so
+// an unreached function is never counted reached.
+//
+// Whether a recorded declaration ran in part is printed as advice, never counted: a `function`'s first line ran, or a
+// body line before its last did, but measured on planetscale (life, 2026-09-26) an arrow constant read 0 on its first
+// line and 140 on a property line inside it (SHOW_TABLES_FIELD, which nothing in that life calls), while arrow
+// functions every UPDATE and GROUP BY runs (targetRows, computeAggregate) read 0 on their first line. The judge reads
+// the advice; a record whose declaration did run in part is split, its unrun branch recorded as its own function.
+//
+// A walk that fails, and a file in scope (the pack's src/ on disk, its sharing lanes' too) that declares code yet
+// measures no line, stop the measurement: neither is a file with nothing to reach.
+//
+// Usage: twin-standard coverage <vendor> [--write | --out <file>] [--prune]   (from the pack repository's root; twin-world's
+//        bun scripts/life-coverage.ts runs the same)   (--prune removes the stale records)   (--write keeps journeys/coverage.json)
+import { spawnSync } from 'node:child_process';
+import ts from 'typescript';
+import { existsSync, mkdtempSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, normalize, resolve } from 'node:path';
+import type { DerivedManifest } from '@volter/world-core/runtime';
+import { functionIndex, stateCoverage } from '../walk/journey-kit.ts';
+import { sharingLanesIn } from '../lanes.ts';
+import { packsRoot, toolPath } from './packs-root.ts';
+const PACKS = packsRoot();
+const sharingLanes = (v: string): string[] => (v.includes('/') ? [] : sharingLanesIn(join(PACKS, v), v));
+
+const vendor = process.argv[2];
+if (!vendor || vendor.startsWith('-')) { console.error('usage: twin-standard coverage <vendor> [--write | --out <file>] [--prune]   (from the pack repository\'s root)'); process.exit(1); }
+const PKG = join(PACKS, vendor);
+// An unsuccessful current walk replaces stale retained coverage with explicit failed measurement evidence.
+const invalidMeasurement = (error: string): never => {
+  const outAt = process.argv.includes('--out') ? process.argv[process.argv.indexOf('--out') + 1] : undefined;
+  if (process.argv.includes('--write') || outAt) writeFileSync(outAt ?? join(PKG, 'journeys', 'coverage.json'), `${JSON.stringify({ vendor, measured: false, error }, null, 2)}\n`);
+  console.error(error); process.exit(1);
+};
+
+// a lane of a multi-API vendor (`aws/secretsmanager`) is named with a slash
+const dir = mkdtempSync(join(tmpdir(), `life-coverage-${vendor.replaceAll('/', '-')}-`));
+const transitionsPath = join(dir, 'transitions.json');
+// Bun measures coverage only inside `bun test`: a test file of the scratch directory's registers the walks
+// (life-coverage-walk.ts), which a published package holds as a module, never as a test file of its own
+const walkTest = join(dir, 'life-coverage.walk.test.ts');
+writeFileSync(walkTest, `import { coverageWalks } from ${JSON.stringify(toolPath('life-coverage-walk'))};\nawait coverageWalks(${JSON.stringify(PACKS)}, ${JSON.stringify(vendor)});\n`);
+const child = spawnSync(process.execPath, ['test', '--coverage', '--coverage-reporter=lcov', `--coverage-dir=${dir}`, walkTest], {
+  // run from the pack repository, so the pack's files lie under the walk's directory and bun measures them
+  cwd: PACKS, stdio: ['ignore', 'ignore', 'inherit'], env: { ...process.env, LIFE_TRANSITIONS: transitionsPath },
+});
+const lcovPath = join(dir, 'lcov.info');
+if (!existsSync(lcovPath)) { invalidMeasurement(`${vendor}: the walk left no coverage`); }
+// a walk that failed measured only what loaded before it failed: its coverage is no measure of the pack (a vendor of
+// lanes' walk once threw before its fetch loaded, and the manifests alone read as all of its code, all of it run)
+if (child.status !== 0) { invalidMeasurement(`${vendor}: the coverage walk failed (journey instrument exited ${child.status}); its coverage measures nothing`); }
+
+/** What the pack records no World reaches: code by file and declaration, state logic by name, each with its reason. */
+type Unreachable = { code?: Array<{ file: string; declarations: string[]; world?: string; why: string }>; state?: Array<{ item: string; world?: string; why: string }> };
+/** Why no World reaches it (architecture, "Coverage"), each record naming one in `world`: a record
+ *  naming none, or another, is no exemption and its code counts as missing. */
+const WORLDS = new Set(['host-process', 'door', 'configured-otherwise', 'hostile-peer', 'bug-guard', 'vendor-backed', 'sealed-refusal']);
+const ruled = (u: { world?: string }): boolean => u.world !== undefined && WORLDS.has(u.world);
+const unreachablePath = join(PKG, 'journeys', 'unreachable.json');
+const unreachable = existsSync(unreachablePath) ? (JSON.parse(readFileSync(unreachablePath, 'utf8')) as Unreachable) : {};
+const recordedCode = (file: string, fn: string | undefined): boolean => (unreachable.code ?? []).some((u) => ruled(u) && u.file === file && u.declarations.includes(fn ?? '(module scope)'));
+const recordedState = (item: string): boolean => (unreachable.state ?? []).some((u) => ruled(u) && u.item === item);
+
+// ── code ─────────────────────────────────────────────────────────────────────────────────────
+const lcov = readFileSync(lcovPath, 'utf8');
+const prefix = `${vendor}/src/`;
+// the lanes over this vendor's state that its serve factory serves ("Pack layout"): their code and states are this
+// life's to reach, measured here beside the vendor's own
+const sharedLanes = sharingLanes(vendor);
+const lanePrefixes = sharedLanes.map((l) => `${vendor}/${l}/src/`);
+const inScope = (f: string): string | undefined => [prefix, ...lanePrefixes].find((p) => f.startsWith(p) && !f.startsWith(`${p}generated/`));
+// the scope is the pack's hand-written files ON DISK (its src/ and its sharing lanes'), never the files the walk happened to
+// load: a screen not wired into fetch.ts or a family missing from the handler map is in scope and measures nothing
+const onDisk = (rel: string): string[] => {
+  const at = join(PACKS, rel);
+  if (!existsSync(at)) return [];
+  return readdirSync(at, { withFileTypes: true }).flatMap((e) => (e.isDirectory() ? onDisk(`${rel}${e.name}/`) : /\.tsx?$/.test(e.name) ? [`${rel}${e.name}`] : []));
+};
+const handWritten = [prefix, ...lanePrefixes].flatMap(onDisk)
+  .filter((f) => inScope(f) !== undefined && !/\.(test|uitest)\.tsx?$/.test(f) && !/\.d\.ts$/.test(f))
+  // the command line a person runs the twin with (a unit's src/cli.ts) is code no World's fetch runs; everything else is
+  // in scope, a unit's budget.ts (D8's data) and seed.ts (data) passing as data below
+  .filter((f) => !/^[^/]+(?:\/[^/]+)?\/src\/cli\.ts$/.test(f));
+const readSource = (file: string): string | undefined => (existsSync(join(PACKS, file)) ? readFileSync(join(PACKS, file), 'utf8') : undefined);
+const measuredFiles = stateCoverage(lcov, handWritten, readSource);
+// a file in scope that measures no line is not dropped: one that declares code and reads 0 lines found was not loaded by
+// the walk or not measured, an error of the measurement, never a file with nothing to reach. Data is not code: a module
+// of only imports, re-exports, types and constants whose values are data (literals, with no function, call, `new`,
+// accessor or tagged template in them, as the grade holds a manifest's data: twin-standard's manifest-data) has nothing a
+// walk could run, loaded or not: `semantics/seed.ts`'s `seed: SeedCall[]`, which `volter-world init` copies into a World
+// and sends as requests, never a module the twin's fetch loads. A function, a class, an enum or any other statement is
+// code, so no handler hides as data.
+const isCode = (n: ts.Node): boolean => ts.isCallExpression(n) || ts.isNewExpression(n) || ts.isArrowFunction(n) || ts.isFunctionExpression(n)
+  || ts.isClassExpression(n) || ts.isTaggedTemplateExpression(n) || ts.isGetAccessor(n) || ts.isSetAccessor(n) || ts.isMethodDeclaration(n)
+  || ts.forEachChild(n, isCode) === true;
+const declaresCode = (file: string, text: string): boolean => ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true, file.endsWith('.tsx') ? ts.ScriptKind.TSX : ts.ScriptKind.TS).statements.some((st) => {
+  if (ts.isImportDeclaration(st) || ts.isImportEqualsDeclaration(st) || ts.isTypeAliasDeclaration(st) || ts.isInterfaceDeclaration(st)) return false;
+  if (ts.isExportDeclaration(st)) return false;
+  // an ambient declaration (`declare const x: T`) is a type, nothing that runs
+  if (ts.canHaveModifiers(st) && ts.getModifiers(st)?.some((m) => m.kind === ts.SyntaxKind.DeclareKeyword)) return false;
+  // `export default <data>` is data as a constant's value is
+  if (ts.isExportAssignment(st)) return isCode(st.expression);
+  if (ts.isVariableStatement(st)) return st.declarationList.declarations.some((d) => !d.initializer || isCode(d.initializer));
+  return true;
+});
+const unmeasured = measuredFiles.filter((c) => c.lines.found === 0 && declaresCode(c.file, readSource(c.file) ?? ''));
+if (unmeasured.length) { invalidMeasurement(`${vendor}: ${unmeasured.length} file(s) in the pack's scope declare code and measure no line (the walk did not load them, or bun did not measure them): ${unmeasured.map((c) => c.file).join(', ')}`); }
+const files = measuredFiles.filter((c) => c.lines.found > 0).map((c) => {
+  // a lane's file is named from the vendor's src/ (`../fapi/src/semantics/client.ts`), as unreachable.json records it
+  const file = c.file.startsWith(prefix) ? c.file.slice(prefix.length) : `../${c.file.slice(`${vendor}/`.length)}`;
+  const recorded = c.never.filter((n) => recordedCode(file, n.fn));
+  const missing = c.never.filter((n) => !recordedCode(file, n.fn));
+  const size = (ns: typeof c.never): number => ns.reduce((s, n) => s + n.to - n.from + 1, 0);
+  return { file, lines: c.lines, recorded: size(recorded), missing, missingLines: size(missing) };
+});
+const total = files.reduce((t, c) => ({ found: t.found + c.lines.found, hit: t.hit + c.lines.hit, recorded: t.recorded + c.recorded, missing: t.missing + c.missingLines }), { found: 0, hit: 0, recorded: 0, missing: 0 });
+
+// ── state logic ──────────────────────────────────────────────────────────────────────────────
+const { manifest } = (await import(join(PKG, 'src', 'manifest.ts'))) as { manifest: DerivedManifest };
+const laneManifests = await Promise.all(sharedLanes.map(async (l) => ((await import(join(PKG, l, 'src', 'manifest.ts'))) as { manifest: DerivedManifest }).manifest));
+const observed = existsSync(transitionsPath) ? (JSON.parse(readFileSync(transitionsPath, 'utf8')) as { seen: string[]; undeclared: string[] }) : { seen: [], undeclared: [] };
+const seen = new Set<string>(observed.seen);
+const was = (at: string, outcome: string, from?: string): boolean => [...seen].some((s) => s.startsWith(`${at}|${outcome}|`) && (from === undefined || s.endsWith(`|${from}`)));
+const state: Array<{ item: string; reached: boolean }> = [];
+for (const [resource, decl] of [manifest, ...laneManifests].flatMap((mf) => Object.entries(mf.resources ?? {}))) {
+  for (const [field, m] of Object.entries(decl.state ?? {})) {
+    // transitions of one operation from the same states refuse as one rule (a confirm that lands on one of
+    // four outcomes refuses with the first of its four identical refusals), so their refusal is one item
+    const refusalOf = new Map<string, { item: string; reached: boolean }>();
+    m.transitions.forEach((t, i) => {
+      const at = `${resource}.${field}#${i}`;
+      const name = `${resource}.${field}: ${t.operation ?? t.actor ?? 'api'} ${t.from === '*' ? '*' : t.from.join('|')} → ${t.to ?? '(stays)'}`;
+      if (!(t.to === undefined && t.refusal !== undefined)) state.push({ item: `move ${name}`, reached: was(at, 'moved') });
+      const refusals = [...(t.refusal ? [['', t.refusal] as const] : []), ...Object.entries(t.refusals ?? {})];
+      for (const [from, r] of refusals) {
+        const key = JSON.stringify([t.operation ?? t.actor, t.from, from, r]);
+        const known = refusalOf.get(key);
+        const reached = from ? was(at, 'refused', from) : was(at, 'refused');
+        if (known) { known.reached ||= reached; continue; }
+        const item = { item: `refusal ${name}${from ? ` from ${from}` : ''}`, reached };
+        refusalOf.set(key, item);
+        state.push(item);
+      }
+    });
+  }
+}
+const stateMissing = state.filter((s) => !s.reached && !recordedState(s.item)).map((s) => s.item);
+
+// ── stale records ────────────────────────────────────────────────────────────────────────────
+// a record is a claim that no World reaches something: one that names a declaration, a file or a state item the pack
+// no longer has, or one the walks now reach, is false, and counts as missing until it is corrected
+const stale: string[] = [];
+/** Records whose declaration may have run in part: to read, and split where it did (architecture.md, Coverage). */
+const partlyRun: string[] = [];
+const keptCode: NonNullable<Unreachable['code']> = [];
+for (const u of unreachable.code ?? []) {
+  const keep: string[] = [];
+  const source = readSource(`${prefix}${u.file}`);
+  const names = new Set(source === undefined ? [] : functionIndex(source).map((f) => f.name));
+  const measured = files.find((f) => f.file === u.file);
+  const coverage = stateCoverage(lcov, [normalize(`${prefix}${u.file}`)], readSource)[0];
+  const unrun = new Set([...(measured?.missing ?? []), ...(coverage?.never ?? [])].map((n) => n.fn ?? '(module scope)'));
+  // a record is by declaration: one part of whose body ran is not unreachable, its unrun branch is (architecture.md,
+  // Coverage: "the branch moves into its own function first")
+  const partly = new Set(coverage?.ran ?? []);
+  for (const d of u.declarations) {
+    if (source === undefined) stale.push(`${u.file}: no such file`);
+    else if (d !== '(module scope)' && !names.has(d)) stale.push(`${u.file}: no declaration ${d}`);
+    else if (measured && !unrun.has(d)) stale.push(`${u.file}: ${d} is reached`);
+    else {
+      // advice, not a count: bun's line hits cannot always tell a declaration that ran in part (see the header)
+      if (measured && partly.has(d)) partlyRun.push(`${u.file}: ${d}`);
+      keep.push(d);
+    }
+  }
+  if (keep.length) keptCode.push({ ...u, declarations: keep });
+}
+const keptState: NonNullable<Unreachable['state']> = [];
+for (const u of unreachable.state ?? []) {
+  if (!state.some((s) => s.item === u.item)) stale.push(`state: no item ${u.item}`);
+  else if (state.some((s) => s.item === u.item && s.reached)) stale.push(`state: ${u.item} is reached`);
+  else keptState.push(u);
+}
+// `--prune` removes exactly the false records: a record removed wrongly shows again as missing, so pruning hides nothing
+if (stale.length && process.argv.includes('--prune')) {
+  writeFileSync(unreachablePath, `${JSON.stringify({ ...unreachable, code: keptCode, state: keptState }, null, 2)}\n`);
+  console.log(`${vendor}: pruned ${stale.length} stale records from journeys/unreachable.json`);
+  stale.length = 0;
+}
+const stateRecorded = state.filter((s) => !s.reached && recordedState(s.item)).length;
+
+// ── the report ───────────────────────────────────────────────────────────────────────────────
+const pct = (hit: number, found: number): string => (found ? `${((hit / found) * 100).toFixed(1)}%` : 'n/a');
+const missing = (child.status === 0 ? 0 : 1) + total.missing + stateMissing.length + observed.undeclared.length + stale.length;
+console.log(`${vendor}: ${missing === 0 ? 'meets the standard' : `${missing} missing`}${child.status === 0 ? '' : ' (the walk did not hold)'}`);
+// a record whose reason is none the standard names exempts nothing: say which, so the author reaches it or names its World
+const unruled = [...(unreachable.code ?? []).map((u) => `${u.file} ${u.declarations.join(', ')}`), ...(unreachable.state ?? []).map((u) => u.item)]
+  .filter((_, i) => !ruled([...(unreachable.code ?? []), ...(unreachable.state ?? [])][i]!));
+if (unruled.length) console.log(`  ${unruled.length} record(s) name no World of the standard (world: ${[...WORLDS].join(' | ')}), so they exempt nothing: ${unruled.slice(0, 6).join('; ')}${unruled.length > 6 ? ' …' : ''}`);
+console.log(`  code: the life and the vendor's examples run ${pct(total.hit, total.found)} of ${total.found} hand-written lines; ${total.recorded} recorded unreachable; ${total.missing} missing`);
+console.log(`  state: ${state.filter((s) => s.reached).length}/${state.length} declared moves and refusals reached; ${stateRecorded} recorded unreachable; ${stateMissing.length} missing; ${observed.undeclared.length} moves no declared transition allows`);
+for (const u of observed.undeclared) console.log(`    undeclared: ${u}`);
+if (stale.length) console.log(`  records: ${stale.length} stale`);
+for (const r of stale) console.log(`    stale ${r}`);
+for (const s of stateMissing) console.log(`    missing ${s}`);
+if (partlyRun.length) console.log(`  advice: ${partlyRun.length} recorded declaration(s) may have run in part (read each; split where it did):\n${partlyRun.map((p) => `    ${p}`).join('\n')}`);
+for (const f of files.filter((c) => c.missingLines).sort((a, b) => b.missingLines - a.missingLines)) {
+  const byFn = new Map<string, number>();
+  for (const n of f.missing) byFn.set(n.fn ?? '(module scope)', (byFn.get(n.fn ?? '(module scope)') ?? 0) + n.to - n.from + 1);
+  console.log(`    ${f.file} (${f.missingLines} lines): ${[...byFn].sort((a, b) => b[1] - a[1]).map(([fn, n]) => `${fn} ${n}`).join(', ')}`);
+}
+// `--write` keeps journeys/coverage.json; `--out <file>` writes the same report elsewhere (score-pack's own measurement,
+// which leaves the checkout as it found it)
+const outAt = process.argv.includes('--out') ? process.argv[process.argv.indexOf('--out') + 1] : undefined;
+if (process.argv.includes('--write') || outAt) {
+  writeFileSync(outAt ?? join(PKG, 'journeys', 'coverage.json'), `${JSON.stringify({
+    vendor, missing, stale,
+    code: { lines: total.found, run: total.hit, recorded: total.recorded, missing: total.missing },
+    state: { declared: state.length, reached: state.filter((s) => s.reached).length, recorded: stateRecorded, missing: stateMissing, undeclared: observed.undeclared },
+    files: files.map((f) => ({ file: f.file, lines: f.lines, missing: f.missing.map((n) => ({ from: n.from, to: n.to, fn: n.fn })) })),
+  }, null, 2)}\n`);
+}

package/src/tools/packs-root.ts

@@ -0,0 +1,21 @@
+// Where the contributor's tools (walk, examples, coverage, judge-brief) find the pack they are given: a vendor's directory
+// under the pack repository they run from. A contributor runs them from their own repository's root (`twin-standard walk
+// <vendor>`), so that root is the working directory; twin-world's scripts, which find Volter's pack repository beside
+// their checkout, name it before loading a tool (setPacksRoot), and the kernel checkout a walk must measure
+// (setKernelCheckout). Each tool reads both once, when it loads.
+import { join } from 'node:path';
+
+let packs = process.cwd();
+let kernel: string | undefined;
+
+/** The pack repository the tools read (`<root>/<vendor>/`). */
+export const packsRoot = (): string => packs;
+export function setPacksRoot(dir: string): void { packs = dir; }
+
+/** The checkout whose kernel a walk measures, when one is required (twin-world's own scripts); a contributor's walk
+ *  measures whichever kernel its repository resolves, and says which. */
+export const kernelCheckout = (): string | undefined => kernel;
+export function setKernelCheckout(dir: string): void { kernel = dir; }
+
+/** A tool of this directory, by name, in the form this module was loaded as (source `.ts`, or the published `.js`). */
+export const toolPath = (name: string): string => join(import.meta.dir, `${name}${import.meta.path.endsWith('.js') ? '.js' : '.ts'}`);

package/src/tools/run-tool.ts

@@ -0,0 +1,10 @@
+// Runs one contributor tool in a process of its own, as the tool that started it names the pack repository and the
+// kernel checkout (packs-root.ts):  bun run-tool.ts <packs root> <kernel checkout or ''> <tool path> <tool args…>
+import { setKernelCheckout, setPacksRoot } from './packs-root.ts';
+
+const [packs, checkout, tool, ...args] = process.argv.slice(2);
+setPacksRoot(packs!);
+if (checkout) setKernelCheckout(checkout);
+// a tool is a script over process.argv: its first argument is its own
+process.argv = [process.argv[0]!, tool!, ...args];
+await import(tool!);