@volter/twin-standard 1.0.149 → 1.0.151

package/dist/src/create-pack.js

@@ -160,6 +160,9 @@ export function packFetchFile(dir, name) {
     const hasLive = existsSync(join(semantics, 'live.ts'));
     // a GraphQL API beside the REST one: its resolvers and the vendor's schema (graphql-wire.ts)
     const hasGraphql = existsSync(join(semantics, 'graphql.ts')) && existsSync(join(dir, 'src', 'generated', 'graphql-sdl.gen.json'));
+    // a stream whose documents are BSON (the MongoDB wire): the pack's own bson library, resolved from the pack as graphql's is
+    const packageJson = existsSync(join(dir, 'package.json')) ? parseExactJson(readFileSync(join(dir, 'package.json'), 'utf8')) : {};
+    const hasBson = existsSync(join(dir, 'src', 'stream.ts')) && packageJson.dependencies?.bson !== undefined;
     const screensDir = join(dir, 'src', 'screens');
     const screens = existsSync(screensDir) ? readdirSync(screensDir).filter((n) => /\.tsx?$/.test(n) && !/\.(test|uitest)\.tsx?$/.test(n) && !/^shared\.tsx?$/.test(n)).sort() : [];
     const id = (file) => file.replace(/\.tsx?$/, '');
@@ -205,6 +208,7 @@ export function packFetchFile(dir, name) {
         ...screens.map((f) => `import { screen as ${identifier(`screen_${id(f)}`)} } from './screens/${f}';`),
         ...laneImports,
         '',
+        ...(hasBson ? ["/** The pack's BSON library, resolved from the pack as graphql's loader is (architecture, the MongoDB wire). */", "export const loadBson = (): Promise<unknown> => import('bson');", ''] : []),
         `export function ${name}(options: PackFetchOptions = {}): DerivedFetch {`,
         '  return createPackFetch({',
         '    manifest,',
@@ -507,6 +511,27 @@ export function laneInitFiles(vendor, lanes) {
     }
     return files;
 }
+/** A unit's fixed files as the manifest and the spec make them now (architecture, "Creating a pack"): a lane's fetch, and
+ *  a pack's fetch, index, server and cli. A pack with a wire of its own (`src/stream.ts`, SMTP's and Redis's byte-stream
+ *  door) writes its server and cli itself: they carry its listener beside the fetch, so they are not fixed. `--index`
+ *  writes these and the grade's `fixed-reproducible` compares them byte for byte. */
+export async function fixedFiles(dir) {
+    const files = { 'src/fetch.ts': packFetchFile(dir, fetchName(dir)) };
+    if (!existsSync(join(dir, 'package.json')))
+        return files;
+    const { manifest } = await import(__rewriteRelativeImportExtension(join(dir, 'src', 'manifest.ts')));
+    const vendor = manifest?.vendor;
+    if (!vendor || !/^[a-z][a-z0-9-]*$/.test(vendor))
+        throw new Error('Pack manifest must declare its vendor identity independently of the npm package name');
+    files['src/index.ts'] = packIndexFile(dir, vendor);
+    if (!existsSync(join(dir, 'src', 'stream.ts'))) {
+        // a unit whose spec is a proto (derive-pack generated its schema) is served over gRPC: its serve seam in that form
+        const lanesOnly = !hasOwnSurface(dir) && readdirSync(dir).some((n) => existsSync(join(dir, n, 'src', 'manifest.ts')));
+        files['src/server.ts'] = serverFile(vendor, !lanesOnly && existsSync(join(dir, 'src', 'generated', 'proto.gen.json')));
+        files['src/cli.ts'] = cliFile(vendor);
+    }
+    return files;
+}
 export async function createPack(args) {
     const [unit, ...rest] = args;
     if (!unit || (!rest.includes('--index') && !rest.includes('--brief') && !rest.includes('--init'))) {
@@ -598,9 +623,12 @@ export async function createPack(args) {
             writeFileSync(path, handlerIndex(dir));
             console.log(`create-pack: wrote ${path}`);
         }
-        // the fetch, again: a door file, the clock or a screen may have been added since
-        writeFileSync(join(dir, 'src', 'fetch.ts'), packFetchFile(dir, fetchName(dir)));
-        console.log(`create-pack: wrote ${join(dir, 'src', 'fetch.ts')}`);
+        // the fixed files, again: a door file, the clock, a screen, a lane or a proto may have been added since, and a pack
+        // made by an earlier create-pack takes the current form
+        for (const [rel, text] of Object.entries(await fixedFiles(dir))) {
+            writeFileSync(join(dir, rel), text);
+            console.log(`create-pack: wrote ${join(dir, rel)}`);
+        }
         // a pack's own index (a lane's is the vendor's to name): the descriptor with what the kernel derives from the surface
         if (existsSync(join(dir, 'package.json'))) {
             const { manifest } = await import(__rewriteRelativeImportExtension(join(dir, 'src', 'manifest.ts')));

package/dist/src/protocol-3.js

@@ -315,6 +315,23 @@ const criteria = [
             return changed.length ? fail(`derive-pack writes differently: ${changed.slice(0, 5).join(', ')}${changed.length > 5 ? ` and ${changed.length - 5} more` : ''}`) : pass(`${filesUnder(gen).length} files reproduced`);
         },
     },
+    {
+        id: 'fixed-reproducible', section: 'form',
+        asks: 'create-pack regenerates the fixed files (fetch, and a pack\'s index, server and cli) byte for byte',
+        async check(unit) {
+            // loaded when graded: create-pack reads this module's handler names, so a static import would be a cycle
+            const { fixedFiles } = await import("./create-pack.js");
+            let want;
+            try {
+                want = await fixedFiles(unit.dir);
+            }
+            catch (error) {
+                return fail(`create-pack cannot write the fixed files: ${error instanceof Error ? error.message : String(error)}`.slice(0, 200));
+            }
+            const differ = Object.entries(want).filter(([rel, text]) => !existsSync(join(unit.dir, rel)) || readFileSync(join(unit.dir, rel), 'utf8') !== text).map(([rel]) => rel);
+            return differ.length ? fail(`create-pack --index writes differently: ${differ.join(', ')} (run it, never edit a fixed file)`) : pass(`${Object.keys(want).length} fixed files reproduced`);
+        },
+    },
     {
         id: 'layout', section: 'form',
         asks: "the unit's files exactly Pack layout's tree: fixed names at src/'s root, semantics/ its fixed files and one per spec family, screens/ one per declared screen, journeys/ its closed set",
@@ -540,8 +557,8 @@ const criteria = [
                 // an error message's "from '<name>'", is none)
                 let text = readFileSync(join(src, f), 'utf8');
                 if (f === 'fetch.ts') {
-                    // The generated fetch supplies the kernel wire with the pack-local parser library.
-                    // Exempt only that exact factory part; other static or dynamic imports still count.
+                    // The generated fetch supplies the kernel wire with the pack-local library: graphql's parser, a stream's BSON.
+                    // Exempt only those exact generated parts; other static or dynamic imports still count.
                     const source = ts.createSourceFile(f, text, ts.ScriptTarget.Latest, true);
                     const loaders = [];
                     const visit = (node) => {
@@ -556,6 +573,17 @@ const criteria = [
                                 factory.arguments[0] === graphql.parent)
                                 loaders.push({ start: node.getStart(source), end: node.end });
                         }
+                        // The generated BSON loader of a stream's pack (architecture, the MongoDB wire): exactly
+                        // `export const loadBson = (): Promise<unknown> => import('bson');`, BSON supplied as graphql is.
+                        if (ts.isCallExpression(node) && node.expression.kind === ts.SyntaxKind.ImportKeyword &&
+                            node.arguments.length === 1 && ts.isStringLiteral(node.arguments[0]) && node.arguments[0].text === 'bson') {
+                            const arrow = node.parent, declaration = arrow.parent, list = declaration?.parent, statement = list?.parent;
+                            if (ts.isArrowFunction(arrow) && arrow.parameters.length === 0 && arrow.body === node &&
+                                declaration && ts.isVariableDeclaration(declaration) && ts.isIdentifier(declaration.name) && declaration.name.text === 'loadBson' &&
+                                statement && ts.isVariableStatement(statement) && statement.parent === source &&
+                                statement.modifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword))
+                                loaders.push({ start: node.getStart(source), end: node.end });
+                        }
                         ts.forEachChild(node, visit);
                     };
                     visit(source);

package/dist/src/spec-ir.d.ts

@@ -37,6 +37,8 @@ export type IrOperation = {
     bodyEncoding: 'json' | 'form' | 'multipart' | 'xml' | 'none';
     /** A form-encoded operation's number and boolean fields, by bracket path (formScalarsOf). */
     scalars?: Record<string, 'integer' | 'number' | 'boolean'>;
+    /** A form-encoded operation's string fields that take only listed values, by bracket path (formEnumsOf). */
+    enums?: Record<string, string[]>;
     successStatus: number;
     /** Binary media types declared by each response status, independent of the twin’s response headers. */
     responseMedia?: Record<string, string[]>;

package/dist/src/spec-ir.js

@@ -295,6 +295,47 @@ function formScalarsOf(doc, op, pathItem, encoding) {
         visit(p, [name], 0);
     return Object.keys(out).length ? Object.fromEntries(Object.entries(out).sort(([a], [b]) => a.localeCompare(b))) : undefined;
 }
+/** A form-encoded operation's string fields whose schema lists the values they take (`status`: active, inactive,
+ *  canceled), by the bracket path formScalarsOf uses; a field another alternative leaves free (a string without an enum,
+ *  or a number) takes any value and is not listed. */
+function formEnumsOf(doc, op, pathItem, encoding) {
+    if (encoding !== 'form')
+        return undefined;
+    const out = {};
+    const visit = (schema, at, depth) => {
+        const s = deref(doc, schema);
+        if (!s || typeof s !== 'object' || depth > 12)
+            return;
+        const alts = [...(Array.isArray(s.anyOf) ? s.anyOf : []), ...(Array.isArray(s.oneOf) ? s.oneOf : [])].map((a) => deref(doc, a));
+        if (alts.length) {
+            const free = alts.some((a) => (a?.type === 'string' && !Array.isArray(a.enum)) || a?.type === 'integer' || a?.type === 'number' || a?.type === 'boolean');
+            const listed = alts.filter((a) => a?.type === 'string' && Array.isArray(a.enum)).flatMap((a) => a.enum.map(String));
+            if (!free && listed.length && at.length)
+                out[at.join('.')] = [...new Set(listed)];
+            for (const a of alts)
+                if (a?.type === 'object' || a?.type === 'array' || a?.properties)
+                    visit(a, at, depth + 1);
+            return;
+        }
+        if (s.type === 'string' && Array.isArray(s.enum) && at.length) {
+            out[at.join('.')] = s.enum.map(String);
+            return;
+        }
+        if (s.type === 'array') {
+            visit(s.items, [...at, '[]'], depth + 1);
+            return;
+        }
+        for (const [name, p] of Object.entries(propsOf(doc, s)))
+            visit(p, [...at, name], depth + 1);
+    };
+    for (const p of [...(pathItem.parameters ?? []), ...(op.parameters ?? [])].map((q) => deref(doc, q)))
+        if (p?.in === 'query')
+            visit(p.schema, [String(p.name)], 0);
+    const body = deref(doc, deref(doc, op.requestBody)?.content?.['application/x-www-form-urlencoded']?.schema);
+    for (const [name, p] of Object.entries(propsOf(doc, body)))
+        visit(p, [name], 0);
+    return Object.keys(out).length ? Object.fromEntries(Object.entries(out).sort(([x], [y]) => x.localeCompare(y))) : undefined;
+}
 /** The class of one operation, from its method, its path and what it answers. An operation this cannot place is `action`, never CRUD. */
 /** A path and its discriminator as one key: `/responses/{id}` and `/responses/{id}?beta=true` are different reads. */
 // a null value (the key present with any value) keys as the bare name
@@ -445,6 +486,7 @@ export function fromOpenAPI(spec) {
             const credentials = [...new Set(security.flatMap((req) => { const names = Object.keys(req ?? {}); return names.length ? names : ['anonymous']; }))].sort();
             const body = bodyOf(doc, op);
             const scalars = formScalarsOf(doc, op, item, body.bodyEncoding);
+            const enums = formEnumsOf(doc, op, item, body.bodyEncoding);
             const ownServer = String((op.servers ?? item.servers)?.[0]?.url ?? '');
             const ownBase = /^https?:\/\//.test(ownServer) ? new URL(ownServer).pathname.replace(/\/+$/, '') : undefined;
             raw.push({
@@ -456,6 +498,7 @@ export function fromOpenAPI(spec) {
                 ...(ownBase !== undefined && ownBase !== docBase ? { basePath: ownBase } : {}),
                 ...body,
                 ...(scalars ? { scalars } : {}),
+                ...(enums ? { enums } : {}),
                 successStatus: success.status,
                 ...(Object.keys(responseMedia).length ? { responseMedia, ...(Object.keys(defaultResponseMedia).length ? { defaultResponseMedia } : {}) } : {}),
                 ...(success.empty ? { emptySuccess: true } : {}),

package/dist/src/tools/judge-brief.d.ts

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

package/dist/src/tools/judge-brief.js

@@ -0,0 +1,67 @@
+// A JUDGE'S BRIEF (pack-done's (f); architecture, "What a judge rejects"): what a judge reads and writes for one vendor's
+// outline, life and published examples, printed for a judge in another session (`codex exec`, `claude -p`, any agent
+// runtime). The verdict names its judge and the authors; the grade refuses one whose judge is an author
+// (packages/twin-standard/src/verdict.ts). One judging per pack: the verdict stands through later changes.
+//
+//   twin-standard judge-brief <vendor> --authors <author name>[,<agent>...]   (from the pack repository's root; twin-world's
+//   bun scripts/judge-brief.ts runs the same)
+import { attributionName } from "../verdict.js";
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { packsRoot } from "./packs-root.js";
+const PACKS = packsRoot();
+/** The architecture a judge's list is read from: the twin-world checkout this standard is in, else its published copy. */
+const ARCHITECTURE = join(import.meta.dir, '..', '..', '..', '..', 'docs', 'contributing', 'architecture.md');
+const PUBLISHED_ARCHITECTURE = 'https://world-docs.volter.ai/docs/contributing/architecture.md';
+const vendor = process.argv[2];
+const authorsAt = process.argv.indexOf('--authors');
+const authors = authorsAt > 0 ? (process.argv[authorsAt + 1] ?? '').split(',').map((a) => a.trim()).filter(Boolean).map((name) => attributionName(name)) : [];
+if (!vendor || vendor.startsWith('-') || !authors.length) {
+    console.error('usage: twin-standard judge-brief <vendor> --authors <author name>[,<agent>...]   (from the pack repository\'s root)');
+    process.exit(2);
+}
+const journeys = join(PACKS, vendor, 'journeys');
+if (!existsSync(journeys)) {
+    console.error(`judge-brief: ${vendor} has no journeys/ in ${PACKS}`);
+    process.exit(2);
+}
+// the list of what a judge rejects, as architecture holds it
+const architecture = existsSync(ARCHITECTURE) ? readFileSync(ARCHITECTURE, 'utf8') : await fetch(PUBLISHED_ARCHITECTURE).then((r) => (r.ok ? r.text() : ''), () => '');
+const listAt = architecture.indexOf('#### What a judge rejects\n');
+if (listAt < 0) {
+    console.error(`judge-brief: the architecture (${existsSync(ARCHITECTURE) ? ARCHITECTURE : PUBLISHED_ARCHITECTURE}) has no "#### What a judge rejects" section`);
+    process.exit(2);
+}
+const listFrom = architecture.indexOf('\n- ', listAt);
+const listTo = architecture.indexOf('\n\n', listFrom + 1);
+const rejects = architecture.slice(listFrom + 1, listTo < 0 ? undefined : listTo).trim();
+const sha = (file) => createHash('sha256').update(readFileSync(file)).digest('hex');
+const judged = [
+    { file: 'customer-life.outline.md', verdict: 'customer-life.outline.verdict.json', what: "the life's outline: the customer's story in acts" },
+    { file: 'customer-life.json', verdict: 'customer-life.verdict.json', what: 'the life: every step an application or person takes, its expectations' },
+    { file: 'vendor-examples.json', verdict: 'vendor-examples.verdict.json', what: "the published examples: the vendor's own documented requests and answers, replayed" },
+].filter((j) => existsSync(join(journeys, j.file)));
+console.log(`You are the judge of the ${vendor} twin's journeys. You did not write them, and you judge them in a session other than
+the run that wrote them. Judge them against the vendor and against the list below; do not edit any judged file, and run no
+test. Read what you need: the pack's spec (${vendor}/spec/, SOURCE.md naming every page read), its demand
+(${vendor}/journeys/demand.json: what the applications call), its decision table (journeys/decisions.json), and the
+vendor's own documentation the spec cites.
+
+What you judge (in ${vendor}/journeys/), each with the sha256 your verdict names:
+${judged.map((j) => `- ${j.file} (${j.what}): sha256 ${sha(join(journeys, j.file))}`).join('\n')}
+
+What a judge rejects (docs/contributing/architecture.md, "What a judge rejects"):
+${rejects}
+
+For each file write its verdict beside it, as JSON:
+${judged.map((j) => `- ${j.verdict}`).join('\n')}
+{
+  "judge": { "agent": "<what you are: your runtime and model>", "name": "<your author name or reviewer role>" },
+  "authors": ${JSON.stringify(authors)},
+  "sha256": "<the judged file's sha256 above>",
+  "judgedAt": "<today, YYYY-MM-DD>",
+  "plausible": <true only when no ruling stands>,
+  "rulings": [ { "id": "<short name>", "steps": [<step indexes, or acts>], "barItem": "<the list's item>", "reason": "<what is wrong, citing the step and the vendor's page>", "correction": "<what the author changes>" } ]
+}
+A correction naming a wait gives it as a life writes one: one number and one unit (\`915m\`, \`3d\`). A verdict with any ruling is not plausible. The authors apply every ruling; this is the one judging, and the verdict stands through their changes.`);

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

@@ -0,0 +1,2 @@
+/** Registers, in the `bun test` run that imports it, the walks of `vendor` in the pack repository at `PACKS`. */
+export declare function coverageWalks(PACKS: string, vendor: string): Promise<void>;

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

@@ -0,0 +1,220 @@
+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;
+};
+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 } from '@volter/world-core/runtime';
+import { inMemoryWorld, walk, usePacks } from "../walk/behavior-journey.js";
+import { lanesOf, shapeChecker } from "../walk/shape.js";
+import { sharingLanesIn } from "../lanes.js";
+/** Registers, in the `bun test` run that imports it, the walks of `vendor` in the pack repository at `PACKS`. */
+export async function coverageWalks(PACKS, vendor) {
+    const { expect, test } = await import('bun:test');
+    usePacks(PACKS);
+    const sharingLanes = (v) => (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();
+    const undeclared = new Set();
+    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 = [];
+            // each declared transition the life moved through or was refused by, named by resource, field and its place
+            const { manifest } = (await import(__rewriteRelativeImportExtension(join(PACKS, vendor, 'src', 'manifest.ts'))));
+            // 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(__rewriteRelativeImportExtension(join(PACKS, vendor, l, 'src', 'manifest.ts')))).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();
+            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();
+            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();
+            const subjectKey = (service, type, id) => 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 = [];
+            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, code) => (value !== null && typeof value === 'object'
+                    ? Object.values(value).some((v) => holds(v, code))
+                    : (typeof value === 'string' || typeof value === 'number') && String(value) === code);
+                const answers = (a, r) => 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();
+                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();
+                // 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) => 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 };
+                    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();
+                    const valueOf = (row, field) => field.split('.').reduce((value, part) => value && typeof value === 'object' ? value[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))
+                            continue;
+                        const from = stateOf(m, valueOf(prev, field));
+                        const to = stateOf(m, valueOf(next, field));
+                        if (from === to)
+                            continue;
+                        const allows = (t, at) => (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 = [];
+            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/dist/src/tools/life-coverage.d.ts

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