@volter/twin-standard 1.0.149 → 1.0.151

package/dist/src/tools/life-coverage.js

@@ -0,0 +1,271 @@
+#!/usr/bin/env bun
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+// 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 } from 'node:path';
+import { functionIndex, stateCoverage } from "../walk/journey-kit.js";
+import { sharingLanesIn } from "../lanes.js";
+import { packsRoot, toolPath } from "./packs-root.js";
+const PACKS = packsRoot();
+const sharingLanes = (v) => (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) => {
+    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`);
+}
+/** 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) => u.world !== undefined && WORLDS.has(u.world);
+const unreachablePath = join(PKG, 'journeys', 'unreachable.json');
+const unreachable = existsSync(unreachablePath) ? JSON.parse(readFileSync(unreachablePath, 'utf8')) : {};
+const recordedCode = (file, fn) => (unreachable.code ?? []).some((u) => ruled(u) && u.file === file && u.declarations.includes(fn ?? '(module scope)'));
+const recordedState = (item) => (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) => [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) => {
+    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) => (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.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, text) => 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) => 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(__rewriteRelativeImportExtension(join(PKG, 'src', 'manifest.ts'))));
+const laneManifests = await Promise.all(sharedLanes.map(async (l) => (await import(__rewriteRelativeImportExtension(join(PKG, l, 'src', 'manifest.ts')))).manifest));
+const observed = existsSync(transitionsPath) ? JSON.parse(readFileSync(transitionsPath, 'utf8')) : { seen: [], undeclared: [] };
+const seen = new Set(observed.seen);
+const was = (at, outcome, from) => [...seen].some((s) => s.startsWith(`${at}|${outcome}|`) && (from === undefined || s.endsWith(`|${from}`)));
+const state = [];
+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();
+        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]] : []), ...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 = [];
+/** Records whose declaration may have run in part: to read, and split where it did (architecture.md, Coverage). */
+const partlyRun = [];
+const keptCode = [];
+for (const u of unreachable.code ?? []) {
+    const keep = [];
+    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 = [];
+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, found) => (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();
+    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/dist/src/tools/packs-root.d.ts

@@ -0,0 +1,9 @@
+/** The pack repository the tools read (`<root>/<vendor>/`). */
+export declare const packsRoot: () => string;
+export declare function setPacksRoot(dir: string): void;
+/** 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 declare const kernelCheckout: () => string | undefined;
+export declare function setKernelCheckout(dir: string): void;
+/** A tool of this directory, by name, in the form this module was loaded as (source `.ts`, or the published `.js`). */
+export declare const toolPath: (name: string) => string;

package/dist/src/tools/packs-root.js

@@ -0,0 +1,17 @@
+// 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;
+/** The pack repository the tools read (`<root>/<vendor>/`). */
+export const packsRoot = () => packs;
+export function setPacksRoot(dir) { 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 = () => kernel;
+export function setKernelCheckout(dir) { 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) => join(import.meta.dir, `${name}${import.meta.path.endsWith('.js') ? '.js' : '.ts'}`);

package/dist/src/tools/run-tool.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/tools/run-tool.js

@@ -0,0 +1,18 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+// 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.js";
+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(__rewriteRelativeImportExtension(tool));

package/dist/src/tools/score-pack.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+export {};

package/dist/src/tools/score-pack.js

@@ -0,0 +1,264 @@
+#!/usr/bin/env bun
+// score-pack — a Protocol 3 pack's report (docs/contributing/architecture.md, "Protocol 3", Scoring). One customer
+// life per pack is walked through the pack's own fetch on the in-memory World, and the report says:
+//   - the life: whether a judge's plausible verdict names its current content (a verdict its author wrote is not one);
+//   - correctness: every check on every step (status, expectations, captures, SHAPE, the beats) and the life
+//     answering byte for byte the same on a second fresh World;
+//   - coverage: the hand-written code the life and the vendor's published examples run and the declared state logic
+//     they reach (life-coverage.ts), with what they never reach;
+//   - the vendor's published examples: replayed and judged (vendor-examples.ts);
+//   - breadth: the spec's operations (a line protocol's commands) by what serves them (a handler, the generated
+//     core, a legacy fallback, nothing).
+// This is source-journey evidence, not installed readiness or pack completion. pack-done owns completion and consumes
+// this report alongside the exact artifact's installed customer assessment in the one final run.
+//
+// Usage: twin-standard walk <vendor> [--write] [--report <path>]   (from the pack repository's root; twin-world's
+//        bun scripts/score-pack.ts <vendor> runs the same)
+//   --write keeps journeys/score.json and journeys/coverage.json; --report writes the report and what it lacks for done
+//   to <path> as JSON and changes nothing in the checkout
+import { parseExactJson } from '@volter/world-core/exact-json';
+import { notIndependent } from "../verdict.js";
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdtempSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { tmpdir } from 'node:os';
+import { dirname, join, sep } from 'node:path';
+import { inMemoryWorld, walk, withPinnedWorldDraws, usePacks } from "../walk/behavior-journey.js";
+import { expandFills, waitMs } from "../walk/journey-kit.js";
+import { vendorFetch, vendorStream } from "../walk/vendor-fetch.js";
+import { existenceProbe } from "../walk/journey-kit.js";
+import { kernelCheckout, packsRoot, toolPath } from "./packs-root.js";
+const PACKS = packsRoot();
+usePacks(PACKS);
+const vendor = process.argv[2];
+if (!vendor || vendor.startsWith('-')) {
+    console.error('usage: twin-standard walk <vendor> [--write] [--report <path>]   (from the pack repository\'s root)');
+    process.exit(1);
+}
+// The surface measured: the kernel the pack repository resolves, named in the report. twin-world's own scripts require
+// it to be their checkout's (linked in development, decision 0029): a pack repository whose node_modules resolves
+// @volter/* into another checkout scores the pack against someone else's kernel, no measurement of this one.
+const kernel = (() => {
+    try {
+        return realpathSync(join(PACKS, 'node_modules', '@volter', 'world-core'));
+    }
+    catch { /* resolved through a parent's node_modules */ }
+    try {
+        let at = dirname(realpathSync(createRequire(join(PACKS, 'package.json')).resolve('@volter/world-core')));
+        while (!existsSync(join(at, 'package.json')) && dirname(at) !== at)
+            at = dirname(at);
+        return at;
+    }
+    catch {
+        return '(unresolved)';
+    }
+})();
+const checkout = kernelCheckout();
+if (checkout && !kernel.startsWith(realpathSync(checkout) + sep)) { // the platform's separator: '/' never prefixes a Windows path
+    console.error(`score-pack: @volter/world-core resolves to ${kernel}, outside this checkout (${realpathSync(checkout)}); link the pack repository's node_modules/@volter/* to this checkout's packages before scoring`);
+    process.exit(2);
+}
+const PKG = join(PACKS, vendor);
+const lifePath = join(PKG, 'journeys', 'customer-life.json');
+if (!existsSync(lifePath)) {
+    console.error(`${vendor}: no journeys/customer-life.json`);
+    process.exit(1);
+}
+// ── the life and its verdict ─────────────────────────────────────────────────────────────────
+const text = readFileSync(lifePath, 'utf8');
+// its fills written out once, so the steps the walk hands back are the life's own (a sitting is found by position)
+const life = expandFills(parseExactJson(text));
+const verdictPath = join(PKG, 'journeys', 'customer-life.verdict.json');
+const verdict = existsSync(verdictPath) ? parseExactJson(readFileSync(verdictPath, 'utf8')) : undefined;
+// A verdict is a judge's in another session: one its author wrote (marked self-judged) rules nothing, however it reads.
+// The dispatcher stamps the judge’s author name (`judge.agent`) and every author of the life
+// (`authors`) consistently when it commits the verdict; a verdict without them,
+// or whose judge is among the authors, is not independent.
+// one judging per pack: the verdict stands, and the life's changes since (its rulings applied, a review's fixes, steps for
+// coverage) keep it (architecture, "Writing a life", Judge)
+const dependent = verdict ? notIndependent(verdict, life.author) : undefined;
+const judged = life.steps.length === 0 || !verdict ? 'unjudged' : dependent ? dependent : verdict.plausible ? 'plausible' : 'rejected';
+// ── correctness ──────────────────────────────────────────────────────────────────────────────
+const world = inMemoryWorld(`score-${vendor}`);
+const failures = [];
+await walk(life, world.root(), failures, { beats: true });
+const answers = async () => {
+    const seen = [];
+    // the World's own draws (its seed, its keys) are the same in both: two Worlds differ only by what is beyond them (R9)
+    await withPinnedWorldDraws(() => walk(life, world.root(), [], { beats: false, hooks: { after: (step, p, a) => seen.push(`${step.name ?? ''}\u0000${p} ${a.status} ${JSON.stringify(a.body)}`) } }));
+    return seen;
+};
+const [first, second] = [await answers(), await answers()];
+const flags = [];
+// CRED: a life where steps act with different credentials carries no life-wide default one; a default leaks one actor's
+// credential into every step that forgot its own (a judge found octocat's token on a server's call).
+{
+    const auth = (h) => Object.entries(h ?? {}).find(([k]) => k.toLowerCase() === 'authorization')?.[1];
+    const own = new Set(life.steps.flatMap((st) => { const a = auth(st.headers); return a ? [a] : []; }));
+    const fallback = auth(life.headers);
+    if (fallback && own.size > 0) {
+        const leaning = life.steps.filter((st) => 'method' in st && !auth(st.headers));
+        if (leaning.length)
+            flags.push({ step: leaning[0].name, pattern: 'CRED', detail: `${leaning.length} steps act with the life-wide default credential in a life of ${own.size + 1} credentials; give each its actor's own` });
+    }
+}
+{
+    const walked = [];
+    const refusedAnswer = (a) => {
+        const b = a.body;
+        return a.status >= 400 || (!!b && typeof b === 'object' && (b.ok === false || (Array.isArray(b.errors) && b.errors.length > 0 && b.data === undefined) || typeof b.error === 'string'));
+    };
+    // CRED too: a credential a person was shown once (a key on a dashboard, a token in a mail) is read off what showed it
+    // (a capture), never typed in: a literal equal to what an earlier answer showed means the life knows how the twin mints it
+    const shown = new Set();
+    let literalFlags = 0;
+    await walk(life, inMemoryWorld(`flags-${vendor}`).root(), [], { beats: false, hooks: { after: (step, path, answer) => {
+                const s = step;
+                for (const [k, v] of Object.entries(s.headers ?? {})) {
+                    if (!/^(authorization|x-api-key|api-key|cookie)$/i.test(k) || v.includes('{'))
+                        continue;
+                    const secret = v.replace(/^(bearer|token|basic)\s+/i, '').replace(/^[a-z_]+=/i, '');
+                    if (secret.length >= 16 && shown.has(secret) && literalFlags++ < 3)
+                        flags.push({ step: s.name, pattern: 'CRED', detail: `sends as a literal the credential an earlier answer showed (${secret.slice(0, 12)}…): capture it where it was shown` });
+                }
+                const text = typeof answer.body === 'string' ? answer.body : JSON.stringify(answer.body ?? '');
+                // a token ends before trailing punctuation (a key closing a sentence); a JWT's inner dots stay
+                for (const t of text.match(/[A-Za-z0-9_-]+(?:\.[A-Za-z0-9_-]+)*/g) ?? [])
+                    if (t.length >= 16)
+                        shown.add(t);
+                const method = s.method ?? (s.mysql !== undefined || s.signIn ? `MySQL ${s.link ?? 'mysql'}` : s.connection ? `RESP ${s.connection}` : s.socket ? `socket ${s.open ? 'open' : s.close ? 'close' : 'send'}` : s.git ? `git ${s.git}${s.delete ? ' delete' : ''}` : `line ${s.on}`);
+                const body = JSON.stringify(s.mysql !== undefined || s.signIn ? { mysql: s.mysql ?? null, values: s.values ?? null, signIn: s.signIn?.user ?? null } : s.resp ?? s.body ?? s.send ?? (s.ref ? { ref: s.ref } : null));
+                // an operation named in a header (AWS's X-Amz-Target) is part of what the request is; who sends it is not
+                const named = Object.entries(s.headers ?? {}).filter(([k]) => !/^(authorization|stripe-account|x-slack-|cookie)/i.test(k)).sort().map(([k, v]) => `${k}=${v}`).join('&');
+                // and so is the region an AWS request is signed for (its credential scope), which says where it goes
+                const region = /Credential=[^/]+\/\d{8}\/([a-z0-9-]+)\//.exec((s.headers ?? {}).authorization ?? (life.headers ?? {}).authorization ?? '')?.[1];
+                const where = named || region ? `${path} [${[named, region ? `region=${region}` : ''].filter(Boolean).join('&')}]` : path;
+                walked.push({ index: life.steps.indexOf(step), name: s.name, key: `${method} ${where} ${body}`, path: where, method, body, refused: s.socket ? (answer.status !== 101 && answer.status !== 1000) : refusedAnswer(answer), status: answer.status });
+            } } });
+    const sitting = (i) => life.steps.slice(0, i).filter((x) => 'wait' in x).length;
+    // a client asking whether something exists before it makes it is not a refusal (existenceProbe, journey-kit)
+    const probe = (n) => existenceProbe(walked.map((w) => ({ ...w, sitting: sitting(w.index) })), n);
+    let run = [];
+    const endRun = () => { if (run.length >= 3)
+        flags.push({ step: run[0].name, pattern: 'RUN', detail: `${run.length} refusals in a row, from "${run[0].name.slice(0, 50)}" to "${run.at(-1).name.slice(0, 50)}"` }); run = []; };
+    walked.forEach((w, n) => {
+        if (w.refused && !probe(n))
+            run.push(w);
+        else if (!w.refused)
+            endRun();
+        const earlier = walked.slice(0, n).filter((e) => sitting(e.index) === sitting(w.index));
+        if (w.refused && earlier.some((e) => !e.refused && e.key === w.key))
+            flags.push({ step: w.name, pattern: 'REPEAT', detail: `repeats a request that succeeded earlier in the sitting (${w.method} ${w.path.slice(0, 60)})` });
+        if (!w.refused && /^(POST|PUT|PATCH)$/.test(w.method)) {
+            const writes = earlier.filter((e) => !e.refused && e.method === w.method && e.path === w.path);
+            if (writes.length >= 2 && writes.at(-2).body === w.body && writes.at(-1).body !== w.body)
+                flags.push({ step: w.name, pattern: 'TOGGLE', detail: `writes ${w.path.slice(0, 60)} back to what it was two writes before, in one sitting` });
+        }
+        if (!w.refused && w.method === 'DELETE' && earlier.some((e) => !e.refused && (e.method === 'PUT' || e.method === 'POST') && e.path === w.path))
+            flags.push({ step: w.name, pattern: 'TOGGLE', detail: `removes ${w.path.slice(0, 60)}, made earlier in the same sitting` });
+    });
+    endRun();
+    // a time of day a step names that its hour on the World clock contradicts (the clock starts at startsAt or the default and
+    // moves only by `wait` steps; a wait's name tells what happens once it has passed)
+    const hours = [[/\bmorning\b/i, 5, 12], [/\blunch\b/i, 11, 15], [/\bafternoon\b/i, 12, 18], [/\bevening\b/i, 17, 23]];
+    const WEEKDAYS = ['sunday', 'monday', 'tuesday', 'wednesday', 'thursday', 'friday', 'saturday'];
+    const MONTHS = ['january', 'february', 'march', 'april', 'may', 'june', 'july', 'august', 'september', 'october', 'november', 'december'];
+    const DATED = /\b(Monday|Tuesday|Wednesday|Thursday|Friday|Saturday|Sunday),? (\d{1,2}) (January|February|March|April|May|June|July|August|September|October|November|December)(?:,? (\d{4}))?/g;
+    let clock = Date.parse(life.startsAt ?? '2026-01-01T00:00:00Z');
+    for (const step of life.steps) {
+        if ('wait' in step)
+            clock += waitMs(step.wait);
+        const hour = new Date(clock).getUTCHours();
+        for (const [word, from, to] of hours) {
+            if (word.test(step.name) && (hour < from || hour >= to))
+                flags.push({ step: step.name, pattern: 'TIME', detail: `says ${word.source.replace(/\\b/g, '')} at ${String(hour).padStart(2, '0')}:00 on the World clock` });
+        }
+        // a weekday named with its date is a fact of the calendar, and a wait's name says the date the clock reaches
+        for (const m of step.name.matchAll(DATED)) {
+            const [, weekday, day, month, year] = m;
+            const at = new Date(Date.UTC(year ? Number(year) : new Date(clock).getUTCFullYear(), MONTHS.indexOf(month.toLowerCase()), Number(day)));
+            if (WEEKDAYS[at.getUTCDay()] !== weekday.toLowerCase())
+                flags.push({ step: step.name, pattern: 'TIME', detail: `says ${weekday} ${day} ${month}, which is a ${WEEKDAYS[at.getUTCDay()]}` });
+            else if ('wait' in step && at.toISOString().slice(0, 10) !== new Date(clock).toISOString().slice(0, 10))
+                flags.push({ step: step.name, pattern: 'TIME', detail: `its wait reaches ${new Date(clock).toISOString().slice(0, 10)}, not ${weekday} ${day} ${month}` });
+        }
+    }
+}
+const differs = first.findIndex((line, i) => line !== second[i]);
+if (differs >= 0 || first.length !== second.length)
+    failures.push({ step: '(whole life)', beat: 'REPLAYABLE', detail: `a second fresh World answered differently at "${(first[differs] ?? second[differs] ?? first.at(-1) ?? '').split('\u0000')[0]}" (the ${differs + 1}th answered step; waits are not counted)` });
+// ── breadth ──────────────────────────────────────────────────────────────────────────────────
+const factory = await vendorFetch(PACKS, vendor);
+const fetch = factory?.(world.root());
+// a line protocol's commands are served on its stream
+const stream = (await vendorStream(PACKS, vendor))?.(world.root());
+const owners = fetch?.owners?.() ?? stream?.owners?.() ?? {};
+world.restore();
+const breadth = {};
+for (const o of Object.values(owners))
+    breadth[o] = (breadth[o] ?? 0) + 1;
+const operations = Object.keys(owners).length;
+// ── coverage ─────────────────────────────────────────────────────────────────────────────────
+// the measurement is kept (journeys/coverage.json) only with --write; a plain run leaves the checkout as it found it
+const keep = process.argv.includes('--write');
+const coveragePath = keep ? join(PKG, 'journeys', 'coverage.json') : join(mkdtempSync(join(tmpdir(), 'score-coverage-')), 'coverage.json');
+// each tool in a process of its own, run from the pack repository, naming it as this one does
+const tool = (name, args) => spawnSync(process.execPath, [toolPath('run-tool'), PACKS, checkout ?? '', toolPath(name), ...args], { cwd: PACKS, stdio: ['ignore', 'pipe', 'pipe'] });
+const measured = tool('life-coverage', [vendor, ...(keep ? ['--write'] : ['--out', coveragePath])]);
+// a measurement that failed reports so, never the last one it kept
+const coverage = measured.status === 0 && existsSync(coveragePath) ? parseExactJson(readFileSync(coveragePath, 'utf8')) : undefined;
+// ── the vendor's published examples (vendor-examples.ts) ────────────────────────────────────────
+const replay = tool('vendor-examples', [vendor]);
+const replayOut = String(replay.stdout).trim().split('\n');
+const replayLine = replayOut.at(-1) ?? '';
+// replayed and judged are two lacks: the replay is the twin's, the verdict a judge's (pack-done's (d) and (f))
+const examples = {
+    done: replay.status === 0,
+    replayed: replayOut.some((l) => l.trim() === 'replayed: yes'),
+    verdict: replayOut.find((l) => l.trim().startsWith('verdict: '))?.trim().slice('verdict: '.length) ?? 'not measured',
+    failures: replayOut.filter((line) => /^\s*(?:FAIL|GAP)\s/.test(line)).map((line) => line.trim()),
+    line: replayLine.replace(/^\S+\s+/, ''),
+};
+const pct = (hit, found) => (found ? `${((hit / found) * 100).toFixed(1)}%` : 'n/a');
+const score = {
+    scope: 'source-customer-life-and-published-examples',
+    vendor,
+    life: { steps: life.steps.length, verdict: judged, judge: verdict?.judge?.agent ?? verdict?.judge?.name ?? null, authors: verdict?.authors ?? [] },
+    failures: failures.map((f) => ({ step: f.step, beat: f.beat, detail: f.detail })),
+    flags,
+    coverage: coverage ?? null,
+    examples,
+    breadth: { operations, ...breadth },
+};
+console.log(`  measured through: ${kernel}`);
+console.log(`${vendor}: life of ${life.steps.length} steps, ${judged}; ${failures.length} checks failing`);
+if (!coverage)
+    console.log(`  coverage: NOT MEASURED — life-coverage failed: ${String(measured.stderr).trim().split('\n').slice(-3).join(' ')}`);
+if (coverage)
+    console.log(`  coverage: ${coverage.missing === 0 ? 'meets the standard' : `${coverage.missing} missing`} — hand-written lines ${pct(coverage.code.run, coverage.code.lines)} run, ${coverage.code.recorded} recorded unreachable, ${coverage.code.missing} missing; state logic ${coverage.state.reached}/${coverage.state.declared} reached, ${coverage.state.recorded} recorded, ${coverage.state.missing.length} missing, ${coverage.state.undeclared.length} undeclared moves`);
+console.log(`  ${examples.line || 'examples: not measured'}`);
+console.log(`  breadth: ${operations} spec operations — ${Object.entries(breadth).map(([k, n]) => `${n} ${k}`).join(', ')}`);
+for (const f of failures.slice(0, 20))
+    console.log(`  FAIL ${f.beat} ${f.step.slice(0, 60)}: ${f.detail.slice(0, 140)}`);
+console.log(`  judge flags: ${flags.length ? `${flags.length} (${['REPEAT', 'RUN', 'TOGGLE', 'TIME', 'CRED'].map((p) => `${flags.filter((f) => f.pattern === p).length} ${p}`).join(', ')}) — what judges reject on sight; resolve each or give it a cause the story shows` : 'none'}`);
+for (const f of flags.slice(0, 30))
+    console.log(`  FLAG ${f.pattern} ${f.step.slice(0, 60)}: ${f.detail}`);
+// Source requirements used by pack-done's report step; keep the field name for existing report consumers.
+const missingForDone = [
+    judged !== 'plausible' ? `a plausible verdict from another session (now: ${judged})` : '',
+    failures.length ? `${failures.length} checks failing` : '',
+    flags.length ? `${flags.length} judge flags` : '',
+    !coverage ? 'coverage not measured' : coverage.missing ? `${coverage.missing} coverage items missing` : '',
+    breadth.legacy ? `${breadth.legacy} operations on a legacy fallback` : '',
+    examples.replayed ? '' : "the vendor's published examples not all replayed",
+    examples.verdict === 'plausible' ? '' : `a plausible verdict on the vendor's published examples (now: ${examples.verdict})`,
+].filter(Boolean);
+console.log(`  source journey: ${missingForDone.length ? `incomplete — ${missingForDone.join('; ')}` : 'meets the source requirements'}`);
+console.log('  pack completion: not assessed — pack-done consumes the exact installed assessment in the final run');
+const reportAt = process.argv.indexOf('--report');
+if (reportAt >= 0 && process.argv[reportAt + 1]) {
+    writeFileSync(process.argv[reportAt + 1], `${JSON.stringify({ ...score, missingForDone }, null, 2)}\n`);
+}
+if (process.argv.includes('--write')) {
+    writeFileSync(join(PKG, 'journeys', 'score.json'), `${JSON.stringify(score, null, 2)}\n`);
+}

package/dist/src/tools/vendor-examples.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+export {};