@volter/twin-standard 1.0.29 → 1.0.31

package/dist/src/protocol-3.js

@@ -12,7 +12,10 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 // Version 1 checks what the repository's tools can decide today. Criteria the grade section names that no tool
 // decides yet (a credential stored as issued; hollow capabilities; the invariants row) are listed in PLANNED and
 // counted in no grade until a version of this standard checks them.
+import { unpublishedUnitFiles } from "./conformance.js";
+import { attributionName, notIndependent } from "./verdict.js";
 import { spawnSync } from 'node:child_process';
+import { AsyncLocalStorage } from 'node:async_hooks';
 import { createHash } from 'node:crypto';
 import { existsSync, mkdtempSync, readdirSync, readFileSync, rmSync, statSync } from 'node:fs';
 import { tmpdir } from 'node:os';
@@ -21,6 +24,7 @@ import { gunzipSync } from 'node:zlib';
 import ts from 'typescript';
 import { fileURLToPath } from 'node:url';
 import { sharingLanesIn } from "./lanes.js";
+import { isPackArtifact } from "./pack-files.js";
 /** The lanes over the unit's vendor's state, when the unit is one of them ("Pack layout"), else none: a lane over its
  *  vendor's state takes the vendor's states, shared helpers, manifest and engine from the vendor's src/, and nothing of
  *  another lane. */
@@ -49,31 +53,69 @@ catch {
 } };
 /** What spec/ holds beside the vendored documents: provenance, corrections, the grouping, the examples index, recordings. */
 const SPEC_METADATA = /^(SOURCE\.md|sources\.json|patches\.json|grouping\.json|doc-examples\.json|README\.md|[^/]*\.sha256|recordings\/.*)$/;
-/** A tool in spec/ is not a vendored document (it belongs in scripts/): named by the layout criterion, never hashed. */
+/** A tool in spec/ is not a vendored document: never hashed, and outside the layout unless it is the script that wrote
+ *  the document from the vendor's reference page, which SOURCE.md names (architecture, "Creating a pack", step 2). */
 const SPEC_TOOL = /\.(py|sh|ts|js|mjs|cjs|rb)$/;
+/** spec/'s tools SOURCE.md names: the writers of a document a vendor publishes only as a page. */
+function namedSpecTools(unit) {
+    const path = join(unit.dir, 'spec', 'SOURCE.md');
+    const source = existsSync(path) ? readFileSync(path, 'utf8') : '';
+    return new Set(filesUnder(join(unit.dir, 'spec')).filter((f) => SPEC_TOOL.test(f) && !f.includes('/') && source.includes(`\`${f}\``)));
+}
 /** The vendored documents: every file under spec/ that is not its metadata. */
 function specFiles(unit) {
     const dir = join(unit.dir, 'spec');
     return filesUnder(dir).filter((f) => !SPEC_METADATA.test(f) && !SPEC_TOOL.test(f)).map((f) => join(dir, f));
 }
-/** Every file under a directory git does not ignore, relative to it (the checkout's tree, never runtime state). */
+/** The checkout a directory is in: the nearest ancestor holding `.git` (a directory, or a worktree's file). */
+function checkoutOf(dir) {
+    for (let d = dir;; d = dirname(d)) {
+        if (existsSync(join(d, '.git')))
+            return d;
+        if (dirname(d) === d)
+            return undefined;
+    }
+}
+// Grading fans out over a checkout's directories. A caller explicitly owns the immutable listing for one pass;
+// nested gates share it, while concurrent passes have separate snapshots and direct checks always read git afresh.
+const checkoutFiles = new AsyncLocalStorage();
+export function withCheckoutFiles(fn) {
+    return checkoutFiles.getStore() ? fn() : checkoutFiles.run(new Map(), fn);
+}
+/** Files relative to a directory: Git's tree in a checkout (one listing per checkout per pass), the disk tree of an
+ *  unpacked package outside one. A failed Git listing refuses; it never reads as an empty tree. */
 function filesUnder(dir, base = dir) {
     if (!existsSync(dir))
         return [];
-    // tracked and not-yet-added files alike (T0 runs before the commit); ignored runtime state (.volter) never
-    const run = spawnSync('git', ['ls-files', '-z', '--cached', '--others', '--exclude-standard', '--', '.'], { cwd: dir, stdio: ['ignore', 'pipe', 'ignore'] });
-    const tracked = run.status === 0 ? [...new Set(String(run.stdout).split('\0').filter(Boolean))] : [];
-    return tracked.map((f) => relative(base, join(dir, f))).filter((f) => existsSync(join(base, f)));
+    const top = checkoutOf(dir);
+    if (!top)
+        return allFilesUnder(dir, base, true);
+    const listing = checkoutFiles.getStore();
+    let files = listing?.get(top);
+    if (!files) {
+        // tracked and not-yet-added files alike (T0 runs before the commit); ignored runtime state (.volter) never
+        const run = spawnSync('git', ['ls-files', '-z', '--cached', '--others', '--exclude-standard', '--', '.'], { cwd: top, stdio: ['ignore', 'pipe', 'pipe'], maxBuffer: 256 * 1024 * 1024 });
+        if (run.status !== 0 || run.error) {
+            throw new Error(`git ls-files failed: directory=${JSON.stringify(top)} status=${run.status} signal=${JSON.stringify(run.signal)} error=${JSON.stringify(run.error?.message ?? null)} stderr=${JSON.stringify(String(run.stderr ?? ''))}`);
+        }
+        files = [...new Set(String(run.stdout).split('\0').filter(Boolean))];
+        listing?.set(top, files);
+    }
+    const under = relative(top, dir);
+    const mine = under === '' ? files : files.filter((f) => f.startsWith(`${under}/`)).map((f) => f.slice(under.length + 1));
+    return mine.map((f) => relative(base, join(dir, f))).filter((f) => existsSync(join(base, f)));
 }
-/** Every file under a directory, tracked or not (a directory the grader itself wrote). */
-function allFilesUnder(dir, base = dir) {
+/** Disk files outside a checkout, or the complete output of the grader's own derivation. */
+function allFilesUnder(dir, base = dir, excludeArtifacts = false) {
     if (!existsSync(dir))
         return [];
     const out = [];
     for (const name of readdirSync(dir)) {
         const path = join(dir, name);
+        if (excludeArtifacts && isPackArtifact(relative(base, path)))
+            continue;
         if (statSync(path).isDirectory())
-            out.push(...allFilesUnder(path, base));
+            out.push(...allFilesUnder(path, base, excludeArtifacts));
         else
             out.push(relative(base, path));
     }
@@ -97,15 +139,28 @@ const isLane = (unit) => unit.name.includes('/');
 function srcFileInForm(unit, name) {
     if (name.endsWith('.d.ts'))
         return true; // the types of a vendor SDK the pack's tests drive
-    return (isLane(unit) ? ['manifest.ts', 'index.ts', 'fetch.ts', 'budget.ts'] : ['manifest.ts', 'index.ts', 'cli.ts', 'fetch.ts', 'server.ts', 'budget.ts']).includes(name);
+    return (isLane(unit) ? ['manifest.ts', 'index.ts', 'fetch.ts', 'budget.ts'] : ['manifest.ts', 'index.ts', 'cli.ts', 'fetch.ts', 'server.ts', 'stream.ts', 'budget.ts']).includes(name);
 }
 /** The fixed files of semantics/ besides the families' handler files and their tests. */
-const SEMANTICS_FIXED = new Set(['states.ts', 'index.ts', 'shared.ts', 'doors.ts', 'seed.ts', 'around.ts', 'events.ts', 'clock.ts', 'tenant.ts', 'scenario.ts', 'gap.ts', 'graphql.ts', 'sockets.ts', 'board.ts']);
+const SEMANTICS_FIXED = new Set(['answer-views.ts', 'states.ts', 'index.ts', 'shared.ts', 'doors.ts', 'seed.ts', 'around.ts', 'events.ts', 'clock.ts', 'tenant.ts', 'scenario.ts', 'gap.ts', 'graphql.ts', 'sockets.ts', 'board.ts']);
 /** journeys/'s closed set. */
 const JOURNEY_FILES = new Set(['customer-life.outline.md', 'customer-life.outline.verdict.json', 'customer-life.json', 'customer-life.verdict.json', 'decisions.json',
     'vendor-examples.json', 'vendor-examples.verdict.json', 'demand.json', 'unreachable.json', 'score.json', 'coverage.json',
     // a generative pack's life names the World's scenario it walks under (architecture, "Writing a life")
     'scenario.json']);
+/** Only scenario basenames the two walks explicitly declare extend the closed layout. */
+function journeyFiles(unit) {
+    const files = new Set(JOURNEY_FILES);
+    for (const name of ['customer-life.json', 'vendor-examples.json']) {
+        try {
+            const journey = JSON.parse(readFileSync(join(unit.dir, 'journeys', name), 'utf8'));
+            if (typeof journey.scenario === 'string' && /^[a-z0-9][a-z0-9.-]*\.json$/i.test(journey.scenario))
+                files.add(journey.scenario);
+        }
+        catch { /* malformed or absent journeys get no additional files */ }
+    }
+    return files;
+}
 /** Entries at the unit's root the form does not name (a vendor's lanes are units of their own). */
 function rootOutsideForm(unit) {
     return entriesOf(unit.dir).filter((name) => {
@@ -144,7 +199,7 @@ const FORBIDDEN_REACH = [
     [/\bprocess\.env\b|\bBun\.env\b|\bDeno\.env\b/, 'the environment'],
     [/(^|[^\w])fetch\s*\(|\bXMLHttpRequest\b|\bnode:(net|http|https|tls|dgram)\b/m, 'the network'],
     [/\bimport\s*\(|\brequire\s*\(/, 'a module loaded at run time'],
-    [/\bctx\.(now|core|atomically|tree|writeDetailed)\b|\}\s*=\s*ctx\b|\bctx\s*\[/, 'a context member outside the contract, or the context taken apart'],
+    [/\bctx\.(now|core|atomically|tree|writeDetailed)\b|\}\s*=\s*ctx\b(?!\s*[.?])|\bctx\s*\[/, 'a context member outside the contract, or the context taken apart'],
     [/\bSemanticsContext\b|\bSemantics\b|\bsemanticsContext\b/, "the kernel's wide context (a handler is typed Handler, over HandlerContext; a lane reaches its vendor's through ctx.over)"],
 ];
 /** A handler's name for an operationId: the id with every character a JavaScript name cannot hold made `_`, and a
@@ -215,7 +270,7 @@ const criteria = [
             const patches = doc?.patches;
             if (!Array.isArray(patches))
                 return fail('spec/patches.json is not { patches: [...] }');
-            const bare = patches.filter((p) => !p.why || !(p.source?.url || p.source?.spec || /https?:\/\//.test(p.why))).length;
+            const bare = patches.filter((p) => !p.why || !(p.source?.url || p.source?.spec || p.source?.recording || /https?:\/\//.test(p.why))).length;
             return bare ? fail(`${bare} of ${patches.length} corrections lack a reason or a source`) : pass(`${patches.length} corrections, each sourced`);
         },
     },
@@ -261,7 +316,8 @@ const criteria = [
             const families = new Set(operationsOf(unit).values());
             const outside = [
                 ...rootOutsideForm(unit),
-                ...filesUnder(join(unit.dir, 'spec')).filter((f) => SPEC_TOOL.test(f)).map((f) => `spec/${f}`),
+                ...unpublishedUnitFiles(unit.dir),
+                ...filesUnder(join(unit.dir, 'spec')).filter((f) => SPEC_TOOL.test(f) && !namedSpecTools(unit).has(f)).map((f) => `spec/${f}`),
                 ...entriesOf(src).filter((name) => statSync(join(src, name)).isDirectory() ? !LAYOUT_DIRS.has(name) : !srcFileInForm(unit, name)).map((n) => `src/${n}`),
                 ...filesUnder(join(src, 'semantics')).filter((f) => {
                     if (f.includes('/'))
@@ -270,7 +326,7 @@ const criteria = [
                     return !(SEMANTICS_FIXED.has(f) || SEMANTICS_FIXED.has(`${stem}.ts`) || (families.has(stem.replace(/-ops$/, '')) && /\.(test\.)?ts$/.test(f)));
                 }).map((f) => `src/semantics/${f}`),
                 // a lane over its vendor's state has no journeys of its own: the vendor's life walks it ("Pack layout")
-                ...filesUnder(join(unit.dir, 'journeys')).filter((f) => vendorLanes(unit).length > 0 || !JOURNEY_FILES.has(f)).map((f) => `journeys/${f}`),
+                ...filesUnder(join(unit.dir, 'journeys')).filter((f) => vendorLanes(unit).length > 0 || !journeyFiles(unit).has(f)).map((f) => `journeys/${f}`),
             ];
             // screens/: one file per screen the manifest declares, named by its id
             if (existsSync(join(src, 'screens'))) {
@@ -353,6 +409,12 @@ const criteria = [
                         found.push(`clock.ts exports ${names.join(', ') || 'nothing'}, not only clock`);
                     continue;
                 }
+                if (f === 'answer-views.ts') {
+                    const names = [...text.matchAll(/^export\s+const\s+([A-Za-z0-9_$]+)/gm)].map((m) => m[1]);
+                    if (names.join() !== 'answerViews' || /^export\s+(?:async\s+)?function\s|^export\s+(let|var|class)\s|^export\s*\{/m.test(text))
+                        found.push(`answer-views.ts exports ${names.join(', ') || 'nothing'}, not only answerViews`);
+                    continue;
+                }
                 if (f === 'board.ts') {
                     const names = [...text.matchAll(/^export\s+(?:async\s+)?function\s+([A-Za-z0-9_$]+)/gm)].map((m) => m[1]);
                     if (names.join() !== 'board' || /^export\s+(const|let|var|class)\s|^export\s*\{/m.test(text))
@@ -605,18 +667,15 @@ const criteria = [
             const verdict = readJson(join(journeys, 'customer-life.outline.verdict.json'));
             if (!existsSync(outline))
                 return fail('no journeys/customer-life.outline.md');
+            const author = /^Author:\s*(.+?)\.?\s*$/m.exec(readFileSync(outline, 'utf8'))?.[1];
+            attributionName(author);
             if (!verdict)
                 return fail('no outline verdict');
             if (!verdict.plausible)
                 return fail('judged not plausible');
-            if (/self-judged/i.test(verdict.judge?.session ?? ''))
-                return fail('self-judged (not a verdict)');
-            if (!verdict.judge?.agent)
-                return fail('the verdict does not name its judge (judge.agent)');
-            if (!verdict.authors?.length)
-                return fail('the verdict does not name the authors, so the judge is not shown to be another session');
-            if (verdict.authors.includes(verdict.judge.agent))
-                return fail('the judge is among the authors');
+            const dependent = notIndependent(verdict);
+            if (dependent)
+                return fail(dependent);
             return pass(`plausible, judge ${verdict.judge.agent}`);
         },
     },
@@ -627,7 +686,7 @@ const criteria = [
             const r = report(unit);
             if (!r)
                 return fail(noReport(unit));
-            return r.life.verdict === 'plausible' ? pass(`${r.life.steps} steps, judge ${r.life.judge}`) : fail(`verdict: ${r.life.verdict}`);
+            return r.life.steps > 0 && r.life.verdict === 'plausible' ? pass(`${r.life.steps} steps, judge ${r.life.judge}`) : fail(`verdict: ${r.life.verdict}`);
         },
     },
     {

package/dist/src/published.d.ts

@@ -1,3 +1,4 @@
+import { type ConformanceResult } from './conformance.js';
 export type PublishedGate = {
     spec: string;
     failures: Array<{
@@ -7,6 +8,11 @@ export type PublishedGate = {
 };
 /** The vendor a package twins: its name without its scope and the `twin-` prefix (`@volter/twin-supabase` is supabase). */
 export declare const vendorOfPackage: (name: string) => string;
+/** The conformance of `spec` as the registry serves it: the published tarball with its own dependencies installed,
+ *  served and read against the kernel (kernelDir). */
+export declare function conformPublished(spec: string, opts?: {
+    registry?: string;
+}): Promise<ConformanceResult[]>;
 /** The gate over `spec` (`<name>@<version>`) as the registry serves it; throws when it cannot be fetched or unpacked. */
 export declare function gatePublished(spec: string, opts?: {
     registry?: string;

package/dist/src/published.js

@@ -2,14 +2,17 @@
 // twins come from"): its tarball fetched from the registry, unpacked under its vendor's name (so its lanes are read as
 // the vendor's), and every unit in it — the pack and each lane — put through the gate.
 import { spawnSync } from 'node:child_process';
-import { existsSync, mkdtempSync, readdirSync, readFileSync, renameSync, rmSync } from 'node:fs';
+import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, renameSync, rmSync, symlinkSync } from 'node:fs';
+import { createRequire } from 'node:module';
 import { tmpdir } from 'node:os';
-import { join } from 'node:path';
+import { dirname, join } from 'node:path';
+import { conformance } from "./conformance.js";
 import { p3Gate } from "./gate.js";
 /** The vendor a package twins: its name without its scope and the `twin-` prefix (`@volter/twin-supabase` is supabase). */
 export const vendorOfPackage = (name) => name.replace(/^@[^/]+\//, '').replace(/^twin-/, '');
-/** The gate over `spec` (`<name>@<version>`) as the registry serves it; throws when it cannot be fetched or unpacked. */
-export async function gatePublished(spec, opts = {}) {
+/** `spec` (`<name>@<version>`) as the registry serves it, unpacked under its vendor's name in a scratch directory, handed
+ *  to `use`; throws when it cannot be fetched or unpacked. */
+async function withPublished(spec, opts, use) {
     const tmp = mkdtempSync(join(tmpdir(), 'twin-standard-'));
     try {
         const pack = spawnSync('npm', ['pack', spec, '--pack-destination', tmp, '--silent', ...(opts.registry ? ['--registry', opts.registry] : [])], { encoding: 'utf8' });
@@ -22,15 +25,66 @@ export async function gatePublished(spec, opts = {}) {
         const name = JSON.parse(readFileSync(join(tmp, 'package', 'package.json'), 'utf8')).name;
         const dir = join(tmp, vendorOfPackage(name));
         renameSync(join(tmp, 'package'), dir);
-        const lanes = readdirSync(dir).filter((l) => existsSync(join(dir, l, 'src', 'manifest.ts')) && !existsSync(join(dir, l, 'package.json'))).map((l) => join(dir, l));
-        const results = await p3Gate([dir, ...lanes]);
-        const unit = (u) => u.slice(tmp.length + 1);
-        return {
-            spec,
-            failures: results.filter((r) => r.failures.length).map((r) => ({ unit: unit(r.unit), failures: r.failures })),
-        };
+        return await use(dir, tmp);
     }
     finally {
         rmSync(tmp, { recursive: true, force: true });
     }
 }
+/** A platform package a published pack is served with (`@volter/world-core`, `@volter/world-ui`): the one beside this
+ *  standard (twin-world's, where the catalog clones it), else one the caller installed. Found by its package's entry,
+ *  walked up to its root (an `exports` that names no `./package.json` is refused by Node). */
+function platformDir(name) {
+    for (const from of [import.meta.url, join(process.cwd(), 'package.json')]) {
+        let at;
+        try {
+            at = dirname(createRequire(from).resolve(name));
+        }
+        catch {
+            continue;
+        }
+        for (; at !== dirname(at); at = dirname(at)) {
+            const pkg = join(at, 'package.json');
+            if (existsSync(pkg) && JSON.parse(readFileSync(pkg, 'utf8')).name === name)
+                return at;
+        }
+    }
+    return undefined;
+}
+/** The conformance of `spec` as the registry serves it: the published tarball with its own dependencies installed,
+ *  served and read against the kernel (kernelDir). */
+export async function conformPublished(spec, opts = {}) {
+    const kernel = platformDir('@volter/world-core');
+    if (!kernel)
+        throw new Error('no @volter/world-core to serve the pack with: install it beside the standard');
+    return withPublished(spec, opts, async (dir) => {
+        // what the pack depends on: the platform's packages (`@volter/*`) the same as the kernel, every other (react for its
+        // screens, a database client) installed as an application installing the pack gets it
+        const deps = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8')).dependencies ?? {};
+        const platform = Object.keys(deps).filter((d) => d.startsWith('@volter/'));
+        const others = Object.entries(deps).filter(([d]) => !d.startsWith('@volter/')).map(([d, v]) => `${d}@${v}`);
+        if (others.length) {
+            const install = spawnSync('npm', ['install', '--no-save', '--omit=dev', '--omit=peer', '--ignore-scripts', '--no-audit', '--no-fund', '--no-package-lock', ...(opts.registry ? ['--registry', opts.registry] : []), ...others], { cwd: dirname(dir), encoding: 'utf8' });
+            if (install.status !== 0)
+                throw new Error(`${spec}: its dependencies do not install (${String(install.stderr).trim().split('\n').at(-1) ?? ''})`);
+        }
+        mkdirSync(join(dir, 'node_modules', '@volter'), { recursive: true });
+        for (const name of ['@volter/world-core', ...platform]) {
+            const at = name === '@volter/world-core' ? kernel : platformDir(name);
+            if (!at)
+                throw new Error(`${spec}: depends on ${name}, which is not beside the standard`);
+            rmSync(join(dir, 'node_modules', name), { recursive: true, force: true });
+            symlinkSync(at, join(dir, 'node_modules', name));
+        }
+        return conformance(dir);
+    });
+}
+/** The gate over `spec` (`<name>@<version>`) as the registry serves it; throws when it cannot be fetched or unpacked. */
+export async function gatePublished(spec, opts = {}) {
+    return withPublished(spec, opts, async (dir, tmp) => {
+        const lanes = readdirSync(dir).filter((l) => existsSync(join(dir, l, 'src', 'manifest.ts')) && !existsSync(join(dir, l, 'package.json'))).map((l) => join(dir, l));
+        const results = await p3Gate([dir, ...lanes]);
+        const unit = (u) => u.slice(tmp.length + 1);
+        return { spec, failures: results.filter((r) => r.failures.length).map((r) => ({ unit: unit(r.unit), failures: r.failures })) };
+    });
+}

package/dist/src/spec-documents.js

@@ -1,3 +1,4 @@
+import { parseExactJson, exactInteger } from '@volter/world-core/exact-json';
 // One API published as several OpenAPI documents (Upstash publishes QStash's and Workflow's, both served on
 // qstash-{region}.upstash.io with one key set, and sharing endpoints): the pack vendors each as published under
 // `spec/openapi/<name>.{json,yaml}[.gz]`, patches address a document as `/documents/<name>/...`, and the documents are
@@ -17,7 +18,7 @@ export function readSpecDocuments(specDir) {
     for (const f of readdirSync(dir).filter((f) => /\.(json|ya?ml)(\.gz)?$/.test(f)).sort()) {
         const bytes = readFileSync(join(dir, f));
         const text = (f.endsWith('.gz') ? gunzipSync(bytes) : bytes).toString('utf8');
-        documents[f.replace(/\.(json|ya?ml)(\.gz)?$/, '')] = /\.ya?ml(\.gz)?$/.test(f) ? parseYaml(text) : JSON.parse(text);
+        documents[f.replace(/\.(json|ya?ml)(\.gz)?$/, '')] = /\.ya?ml(\.gz)?$/.test(f) ? parseExactJson(JSON.stringify(parseYaml(text, { intAsBigInt: true }), (_, v) => typeof v === 'bigint' ? exactInteger(String(v)) : v)) : parseExactJson(text);
     }
     if (Object.keys(documents).length < 2)
         throw new Error(`${dir}: one API in several documents needs at least two; a single document is spec/openapi.{json,yaml}`);

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

@@ -1,10 +1,13 @@
-import type { SpecIR } from './spec-ir.js';
+import type { IrOperation, IrResource, SpecIR } from './spec-ir.js';
 export type ClientCall = {
     /** the client method that makes the call, and its line */
     client: string;
     line: number;
     method: string;
     url: string;
+    /** Response declarations supplied by cited reference-page patches, absent from extracted calls. */
+    answers?: IrOperation['answers'];
+    resource?: string;
     query?: Record<string, string | null>;
     body?: {
         encoding: 'json' | 'form' | 'raw';
@@ -16,5 +19,6 @@ export type ClientOpsSpec = {
     format: 'client';
     version: string;
     calls: ClientCall[];
+    resources?: IrResource[];
 };
 export declare function fromClientCalls(spec: ClientOpsSpec): SpecIR;

package/dist/src/spec-ir-client.js

@@ -36,6 +36,14 @@ export function fromClientCalls(spec) {
             byRoute.set(key, { first: call, path, labels, calls: [call] });
     }
     const operations = [...byRoute.values()].map(({ first, path, labels, calls }) => {
+        const declared = (key) => {
+            const values = calls.map((c) => c[key]).filter((v) => v !== undefined);
+            if (values.some((v) => JSON.stringify(v) !== JSON.stringify(values[0])))
+                throw new Error(`client response declarations conflict at ${first.method} ${path}: ${key}`);
+            return values[0];
+        };
+        const answers = declared('answers');
+        const resource = declared('resource') ?? answers?.resource;
         const query = new Map();
         const body = new Map();
         const encodings = new Set();
@@ -62,7 +70,9 @@ export function fromClientCalls(spec) {
             body: [...body.values()].sort((a, b) => a.name.localeCompare(b.name)),
             bodyEncoding,
             successStatus: 200,
-            class: 'action',
+            class: first.method.toUpperCase() === 'GET' && answers ? (answers.list ? 'list' : 'retrieve') : 'action',
+            ...(answers ? { answers } : {}),
+            ...(resource ? { resource } : {}),
         };
     });
     // two routes whose first calls share a client method (one method calling twice) keep distinct ids
@@ -73,5 +83,5 @@ export function fromClientCalls(spec) {
         if (n > 1)
             o.id = `${o.id}_${n}`;
     }
-    return { format: 'client', version: spec.version, resources: [], operations };
+    return { format: 'client', version: spec.version, resources: spec.resources ?? [], operations };
 }

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

@@ -1,5 +1,7 @@
 type Json = any;
 export type OperationClass = 'create' | 'retrieve' | 'list' | 'update' | 'delete' | 'action' | 'computed' | 'non-resource';
+/** Binary media whose resource shape is the response bytes, rather than JSON metadata. */
+export declare const binaryMedia: (media: string) => boolean;
 export declare const CRUD_CLASSES: ReadonlySet<OperationClass>;
 /** A parameter or body field: its name, type and whether it is required, and the numeric bounds the spec states
  *  (`minimum`, `maximum`), which a strict body (the manifest's `body.strict`, `ctx.fields`) refuses outside of. */
@@ -7,8 +9,8 @@ export type IrParam = {
     name: string;
     type: string;
     required: boolean;
-    minimum?: number;
-    maximum?: number;
+    minimum?: number | string;
+    maximum?: number | string;
 };
 export type IrOperation = {
     /** The spec's operationId, or the `method_path` slug when the spec has none. */
@@ -36,6 +38,9 @@ export type IrOperation = {
     /** A form-encoded operation's number and boolean fields, by bracket path (formScalarsOf). */
     scalars?: Record<string, 'integer' | 'number' | 'boolean'>;
     successStatus: number;
+    /** Binary media types declared by each response status, independent of the twin’s response headers. */
+    responseMedia?: Record<string, string[]>;
+    defaultResponseMedia?: Record<string, string>;
     /** the success is documented with no content at all (a 200 with nothing in it) */
     emptySuccess?: true;
     /** The success answer may be a server-sent event stream (`text/event-stream`). */

package/dist/src/spec-ir.js

@@ -1,14 +1,11 @@
-// THE SPEC IR — one representation of a vendor's published surface, beneath every spec format, that
-// the derived-pack generator reads (docs/contributing/architecture.md, "Protocol 3"). A front end
-// turns a spec into the IR; the generator only ever sees the IR. `fromOpenAPI` is the first front end, and `fromSmithy`
-// reads an AWS Smithy JSON model
-// (OpenAPI 3.x; Stripe's vendor extensions `x-resourceId` and `x-expandableFields` are read where
-// present). Pure and deterministic: the same document always yields the same IR, byte for byte.
+import { isExactIntegerValue } from '@volter/world-core/exact-json';
+/** Binary media whose resource shape is the response bytes, rather than JSON metadata. */
+export const binaryMedia = (media) => /^(?:application\/(?:octet-stream|pdf|zip|gzip)|(?:image|audio|video)\/[^/]+)$/.test(media.toLowerCase());
 export const CRUD_CLASSES = new Set(['create', 'retrieve', 'list', 'update', 'delete']);
 /** A schema's stated numeric bounds, when it states any. */
 function boundsOf(doc, schema) {
     const s = deref(doc, schema);
-    return { ...(typeof s?.minimum === 'number' ? { minimum: s.minimum } : {}), ...(typeof s?.maximum === 'number' ? { maximum: s.maximum } : {}) };
+    return { ...((typeof s?.minimum === 'number' || typeof s?.minimum === 'string' && isExactIntegerValue(s.minimum)) ? { minimum: s.minimum } : {}), ...((typeof s?.maximum === 'number' || typeof s?.maximum === 'string' && isExactIntegerValue(s.maximum)) ? { maximum: s.maximum } : {}) };
 }
 // every operation an OpenAPI path item may hold (a HEAD is as published as a GET: Vercel's /v8/artifacts/{hash})
 const METHODS = ['get', 'post', 'put', 'patch', 'delete', 'head', 'options', 'trace'];
@@ -180,6 +177,19 @@ function successOf(doc, op, resources) {
     const listed = items ? resourcesOfSchema(doc, items, resources) : [];
     if (listed.length)
         return { status, answers: answer(listed, true) };
+    // a single object under `data` (X's create: a thin data object beside partial errors); a `data` that is an array, named
+    // by reference or inline, is a list's envelope, read below
+    if (s?.properties?.data && deref(doc, s.properties.data)?.type !== 'array') {
+        const payload = s.properties.data;
+        const name = refName(payload);
+        const found = resourcesOfSchema(doc, payload, resources);
+        if (found.length)
+            return { status, answers: answer(found, false, 'data') };
+        if (name && propsOf(doc, payload).id)
+            return { status, answers: answer([name], false, 'data') };
+        // A data payload without a modeled identity cannot make the accompanying errors the resource.
+        return { status };
+    }
     // An envelope that holds exactly one resource, or one list of them, under a named property, beside
     // at most a few scalars (`ok`, a cursor). An object with an `id` of its own, or with other objects
     // in it, is not an envelope: it is something that embeds another (a Pages site, a branch).
@@ -218,7 +228,17 @@ function paramsOf(doc, op, pathItem) {
     return { pathParams, query };
 }
 function bodyOf(doc, op) {
-    const content = deref(doc, op.requestBody)?.content ?? {};
+    const request = deref(doc, op.requestBody);
+    const content = request?.content ?? {};
+    // A whole binary body is the payload itself, not a JSON object with no fields. Keep the existing blob contract so
+    // the kernel leaves its bytes opaque even when a caller labels them application/json.
+    const representations = Object.values(content);
+    const binary = representations.length > 0 && representations.every((media) => {
+        const schema = deref(doc, media?.schema);
+        return schema?.type === 'string' && schema.format === 'binary';
+    });
+    if (binary)
+        return { body: [{ name: 'body', type: 'blob', required: request?.required === true }], bodyEncoding: 'none' };
     const mediaOf = { json: 'application/json', form: 'application/x-www-form-urlencoded', multipart: 'multipart/form-data' };
     const encoding = content[mediaOf.json] ? 'json' : content[mediaOf.form] ? 'form' : content[mediaOf.multipart] ? 'multipart' : 'none';
     if (encoding === 'none')
@@ -384,8 +404,8 @@ export function fromOpenAPI(spec) {
             if (d?.type === 'array')
                 return named(d.items);
             const props = propsOf(doc, schema);
-            if (props.data && deref(doc, props.data)?.type === 'array')
-                return named(deref(doc, props.data).items);
+            if (props.data)
+                return deref(doc, props.data)?.type === 'array' ? named(deref(doc, props.data).items) : named(props.data);
             const held = Object.values(props).filter((p) => !envelopeMeta(doc, p)).map((p) => (deref(doc, p)?.type === 'array' ? named(deref(doc, p).items) : named(p))).filter((n) => n.length);
             return held.length === 1 ? held[0] : [];
         };
@@ -408,6 +428,17 @@ export function fromOpenAPI(spec) {
             if (!op)
                 continue;
             const success = successOf(doc, op, resourceBySchema);
+            const responseMedia = Object.fromEntries(Object.entries(op.responses ?? {}).flatMap(([code, response]) => {
+                const media = Object.keys(deref(doc, response)?.content ?? {}).filter(binaryMedia).sort();
+                return media.length ? [[code, media]] : [];
+            }));
+            const defaultResponseMedia = Object.fromEntries(Object.entries(op.responses ?? {}).flatMap(([code, response]) => {
+                if (!responseMedia[code])
+                    return [];
+                const media = Object.keys(deref(doc, response)?.content ?? {});
+                const defaultMedia = media.includes('application/json') ? 'application/json' : media.length === 1 ? media[0] : undefined;
+                return defaultMedia ? [[code, defaultMedia]] : [];
+            }));
             const streams = Object.entries(op.responses ?? {}).some(([code, r]) => /^2\d\d$/.test(code) && deref(doc, r)?.content?.['text/event-stream']);
             const security = (op.security ?? doc.security ?? []);
             const scopes = [...new Set(security.flatMap((req) => Object.values(req ?? {}).flat()))].sort();
@@ -426,6 +457,7 @@ export function fromOpenAPI(spec) {
                 ...body,
                 ...(scalars ? { scalars } : {}),
                 successStatus: success.status,
+                ...(Object.keys(responseMedia).length ? { responseMedia, ...(Object.keys(defaultResponseMedia).length ? { defaultResponseMedia } : {}) } : {}),
                 ...(success.empty ? { emptySuccess: true } : {}),
                 ...(streams ? { streams: true } : {}),
                 ...(scopes.length ? { scopes } : {}),

package/dist/src/verdict.d.ts

@@ -0,0 +1,14 @@
+/** Committed attribution names people or author roles, never execution identities. */
+export declare function attributionName(name: string | undefined): string | undefined;
+export type Verdict = {
+    judge?: {
+        agent?: string;
+        name?: string;
+        session?: string;
+        review?: string;
+    };
+    authors?: string[];
+};
+/** Why the verdict is no verdict, or undefined when it rules. `author` is the name the judged file itself names as
+ *  its author (a life's `author`). */
+export declare function notIndependent(verdict: Verdict, author?: string): string | undefined;

package/dist/src/verdict.js

@@ -0,0 +1,30 @@
+// A JUDGE'S INDEPENDENCE (the grade's outline-judged and life-judged, the published examples' verdict): a verdict rules
+// only when it names its judge (`judge.agent`) and the authors of what it judges (`authors`), and the judge is none of
+// them. The dispatcher stamps author names consistently; a judge started independently
+// (scripts/judge-brief.ts prints its brief) names its reviewer role (`judge.name`). One judging per pack: the
+// verdict stands, and later changes to what it judged keep it (architecture, "Writing a life", Judge).
+/** Committed attribution names people or author roles, never execution identities. */
+export function attributionName(name) {
+    if (name === undefined)
+        return undefined;
+    if (/\bcx-|\bt_[0-9a-f]{8}|wt\/|\/root(?:\/|$|[: )])|\b(?:pane|session)[ -:]|[0-9a-f]{8}-[0-9a-f-]{27}|\b[0-9a-f]{16,64}\b/i.test(name))
+        throw new Error('attribution must use an author name, not an execution identifier');
+    return name;
+}
+/** Why the verdict is no verdict, or undefined when it rules. `author` is the name the judged file itself names as
+ *  its author (a life's `author`). */
+export function notIndependent(verdict, author) {
+    const agent = attributionName(verdict.judge?.agent);
+    verdict.authors?.forEach(attributionName);
+    attributionName(author);
+    attributionName(verdict.judge?.session);
+    attributionName(verdict.judge?.review);
+    const session = attributionName(verdict.judge?.name ?? verdict.judge?.session);
+    if (/self-judged/i.test(session ?? '') || (!!author && session === author))
+        return 'self-judged (not a verdict)';
+    if (!agent || !verdict.authors?.length)
+        return 'unattributed (the dispatcher has not stamped judge.agent and authors)';
+    if (verdict.authors.includes(agent))
+        return `the judge is among the authors (${agent})`;
+    return undefined;
+}

package/dist/src/walk/behavior-journey.d.ts

@@ -0,0 +1,47 @@
+import { type TwinStream } from '@volter/world-core/runtime';
+import { type Captured, type GitStep, type Journey, type JourneyStep, type LineStep, type RespStep } from './journey-kit.js';
+export declare function usePacks(dir: string): void;
+/** The walk's World: the twin's own code on its in-memory World and blob stores (the backends a serverless
+ *  entry runs on), so a walk of any length is state changes in memory and never touches the disk; the World
+ *  clock, pinned to 2026-01-01, is world state in the same store, and the World is sealed. Each root is a fresh key
+ *  space in it.
+ *  Restored after ONE run: this module is imported by journey-walk.test.ts, and a store or clock left active
+ *  would leak into whichever suite the sweep runs next. */
+export declare function inMemoryWorld(label: string): {
+    root: () => string;
+    restore: () => void;
+};
+export type Failure = {
+    step: string;
+    beat: string;
+    detail: string;
+};
+/** What a caller that scores a walk observes around each step: the step, its resolved path and body,
+ *  and (after) the answer and the failures the step produced. */
+export type StepHooks = {
+    before?: (step: JourneyStep | LineStep | GitStep | RespStep, path: string, body: unknown) => void;
+    after?: (step: JourneyStep | LineStep | GitStep | RespStep, path: string, answer: {
+        status: number;
+        body: unknown;
+        headers?: Record<string, string>;
+    }, failures: Failure[]) => void;
+};
+/** A pack served for a walk the way a World runs it (its server.ts on a port, the World's root and scenario its options):
+ *  the walk's requests go to it over HTTP, the vendor's host in their Host header, instead of to the fetch in process;
+ *  its sockets are WebSockets to that port, and a line connection (`stream`) is a TCP connection to its protocol port. */
+export type ServedTwin = (root: string, options: {
+    scenarioPath?: string;
+}) => Promise<{
+    fetch: (request: Request) => Promise<Response>;
+    stop: () => void;
+    socket?: (url: string, headers: Record<string, string>) => WebSocket;
+    stream?: TwinStream;
+}>;
+export declare function walk(journey: Journey, root: string, collect: Failure[], opts: {
+    beats: boolean;
+    verbose?: boolean;
+    hooks?: StepHooks;
+    captured?: Captured;
+    served?: ServedTwin;
+}): Promise<Captured>;
+export declare function withPinnedWorldDraws<T>(fn: () => Promise<T>): Promise<T>;