@volter/twin-standard 1.0.148 → 1.0.150

package/dist/src/gate.js

@@ -42,6 +42,48 @@ export function unitsOf(repo) {
  *  routes by hand: only the fetch reaches a lane. A directory with no manifest and no lane is no Protocol 3 pack. */
 const ROOT_ENTRIES = new Set(['README.md', 'package.json', 'LICENSE', 'CHANGELOG.md', 'tsconfig.json', 'tsconfig.build.json', 'gate.ts', 'census.json', 'vendor', 'journeys', 'spec', 'generated', 'src', 'node_modules']);
 const ROOT_SRC = new Set(['manifest.ts', 'fetch.ts', 'index.ts', 'cli.ts', 'server.ts']);
+/** The copied root seed is data, never an alternate executable seed runner. */
+function rootSeedFailures(dir) {
+    const path = join(dir, 'src', 'semantics', 'seed.ts');
+    if (!existsSync(path))
+        return [];
+    const text = readFileSync(path, 'utf8');
+    if (ts.transpileModule(text, { fileName: path, reportDiagnostics: true }).diagnostics?.some(diagnostic => diagnostic.category === ts.DiagnosticCategory.Error))
+        return ['handler-contract: root seed has invalid TypeScript syntax'];
+    const source = ts.createSourceFile(path, text, ts.ScriptTarget.Latest, true);
+    const literal = (node) => {
+        if (ts.isStringLiteral(node) || ts.isNumericLiteral(node) || [ts.SyntaxKind.TrueKeyword, ts.SyntaxKind.FalseKeyword, ts.SyntaxKind.NullKeyword].includes(node.kind))
+            return true;
+        if (ts.isPrefixUnaryExpression(node))
+            return node.operator === ts.SyntaxKind.MinusToken && ts.isNumericLiteral(node.operand);
+        if (ts.isArrayLiteralExpression(node))
+            return node.elements.every(element => !ts.isSpreadElement(element) && !ts.isOmittedExpression(element) && literal(element));
+        return ts.isObjectLiteralExpression(node) && node.properties.every(property => ts.isPropertyAssignment(property)
+            && !ts.isComputedPropertyName(property.name) && literal(property.initializer));
+    };
+    let imports = 0, seeds = 0;
+    for (const statement of source.statements) {
+        if (ts.isImportDeclaration(statement)) {
+            const clause = statement.importClause, bindings = clause?.namedBindings;
+            if (!clause?.isTypeOnly || clause.name || !bindings || !ts.isNamedImports(bindings)
+                || bindings.elements.length !== 1 || bindings.elements[0].name.text !== 'SeedCall' || bindings.elements[0].propertyName
+                || !ts.isStringLiteral(statement.moduleSpecifier) || statement.moduleSpecifier.text !== '@volter/world-core')
+                return ['handler-contract: root seed imports only the SeedCall type from world-core'];
+            imports++;
+            continue;
+        }
+        if (!ts.isVariableStatement(statement) || !statement.modifiers?.some(modifier => modifier.kind === ts.SyntaxKind.ExportKeyword)
+            || !(statement.declarationList.flags & ts.NodeFlags.Const) || statement.declarationList.declarations.length !== 1)
+            return ['handler-contract: root seed exports only const seed: SeedCall[] literal data'];
+        const declaration = statement.declarationList.declarations[0];
+        if (!ts.isIdentifier(declaration.name) || declaration.name.text !== 'seed' || !declaration.type || !ts.isArrayTypeNode(declaration.type)
+            || !ts.isTypeReferenceNode(declaration.type.elementType) || declaration.type.elementType.typeName.getText(source) !== 'SeedCall' || declaration.type.elementType.typeArguments?.length
+            || !declaration.initializer || !ts.isArrayLiteralExpression(declaration.initializer) || !literal(declaration.initializer))
+            return ['handler-contract: root seed must be literal SeedCall[] data'];
+        seeds++;
+    }
+    return imports === 1 && seeds === 1 ? [] : ['handler-contract: root seed requires one SeedCall type import and one seed export'];
+}
 /** What the repository ignores (a build's dist/, a World's state) is no file of the pack, as protocol-3's layout reads it. */
 function ignored(dir, names) {
     if (!names.length)
@@ -57,15 +99,16 @@ export function laneRootFailures(dir) {
     const skip = ignored(dir, stray);
     const outside = [
         ...stray.filter((n) => !skip.has(n)),
-        ...(existsSync(join(dir, 'spec')) ? readdirSync(join(dir, 'spec')).filter((n) => !['sources.json', 'SOURCE.md', 'README.md'].includes(n)).map((n) => `spec/${n}`) : []),
-        ...(existsSync(join(dir, 'src')) ? readdirSync(join(dir, 'src')).filter((n) => !ROOT_SRC.has(n) && !n.endsWith('.d.ts') && n !== 'semantics').map((n) => `src/${n}`) : []),
+        ...(existsSync(join(dir, 'spec')) ? readdirSync(join(dir, 'spec')).filter((n) => !isPackArtifact(n) && !['sources.json', 'SOURCE.md', 'README.md'].includes(n)).map((n) => `spec/${n}`) : []),
+        ...(existsSync(join(dir, 'src')) ? readdirSync(join(dir, 'src')).filter((n) => !isPackArtifact(n) && !ROOT_SRC.has(n) && !n.endsWith('.d.ts') && n !== 'semantics').map((n) => `src/${n}`) : []),
         // what the lanes share, and nothing else (architecture, "Pack layout": a vendor whose every API is a lane)
-        ...(existsSync(join(dir, 'src', 'semantics')) ? readdirSync(join(dir, 'src', 'semantics')).filter((n) => n !== 'shared.ts').map((n) => `src/semantics/${n}`) : []),
+        ...(existsSync(join(dir, 'src', 'semantics')) ? readdirSync(join(dir, 'src', 'semantics')).filter((n) => !isPackArtifact(n) && !['shared.ts', 'seed.ts'].includes(n)).map((n) => `src/semantics/${n}`) : []),
     ];
     const failures = outside.length ? [`layout: ${outside.length} outside the vendor's root (its lanes hold the rest): ${outside.slice(0, 8).join(', ')}${outside.length > 8 ? ` and ${outside.length - 8} more` : ''}`] : [];
     // the vendor's front is declared and the kernel serves it: a manifest, and a fetch that is createVendorFetch over it
     const src = (n) => (existsSync(join(dir, 'src', n)) ? readFileSync(join(dir, 'src', n), 'utf8') : '');
     failures.push(...unpublishedUnitFiles(dir).map((f) => `layout: ${f}`));
+    failures.push(...rootSeedFailures(dir));
     if (!src('manifest.ts'))
         failures.push("layout: no src/manifest.ts: a vendor of lanes declares its lanes' routes, discovery and descriptor");
     if (!/\bcreateVendorFetch\(/.test(src('fetch.ts')))
@@ -109,7 +152,7 @@ export async function p3Gate(units, opts = {}) {
             }
             const grades = await grade(unit, { static: true, sections: ['form'], ...opts });
             const form = Object.values(grades).flatMap((g) => g.criteria).filter((c) => !c.pass);
-            out.push({ unit, failures: form.map((c) => `${c.id}: ${c.reason}`) });
+            out.push({ unit, failures: form.map((c) => `${c.id}: ${c.reason}`), cacheable: Object.values(grades).every(g => g.criteria.every(c => c.cacheable !== false)) });
         }
         return out;
     });

package/dist/src/grade.d.ts

@@ -7,6 +7,7 @@ export interface CriterionGrade {
     asks: string;
     pass: boolean;
     reason: string;
+    cacheable?: boolean;
 }
 export interface StandardGrade {
     grade: number;

package/dist/src/grade.js

@@ -26,7 +26,7 @@ export async function grade(dir, opts = {}) {
                 result = await c.check(unit);
             }
             catch (e) {
-                result = { pass: false, reason: `the check threw: ${e.message.slice(0, 160)}` };
+                result = { pass: false, cacheable: false, reason: `the check threw: ${e.message.slice(0, 160)}` };
             }
             opts.onCriterion?.(name, c.id, result);
             criteria.push({ id: c.id, section: c.section, asks: c.asks, ...result });

package/dist/src/pack-facts.d.ts

@@ -76,9 +76,17 @@ export type PackFacts = {
     };
     /** The managed-infrastructure kind this pack is the World's backing for (architecture.md, "The descriptor"). */
     managedService?: {
-        kind: 'redis' | 'mongodb';
+        kind: 'redis' | 'mongodb' | 'clickhouse';
         scheme: string;
         note: string;
+        configurationArg?: '--configuration';
+        originalInputs?: {
+            version: 1;
+            manifestArg: '--original-inputs';
+            rootArg: '--original-root';
+            digestArg: '--original-inputs-sha256';
+            paths: string[];
+        };
     };
     /** The World's managed database the runtime binds the twin to (see TwinPack.managedDatabase). */
     managedDatabase?: {

package/dist/src/pack-facts.js

@@ -184,12 +184,21 @@ export async function compilePackFacts(dirs) {
         }
         if (pack.managedService !== undefined) {
             const ms = pack.managedService;
-            if (ms.kind !== 'redis' && ms.kind !== 'mongodb')
-                throw new Error(`pack-facts: ${vendor} declares managedService.kind "${String(ms.kind)}"; the managed-infrastructure kinds a twin backs are redis and mongodb`);
+            if (ms.kind !== 'redis' && ms.kind !== 'mongodb' && ms.kind !== 'clickhouse')
+                throw new Error(`pack-facts: ${vendor} declares managedService.kind "${String(ms.kind)}"; the managed-infrastructure kinds a twin backs are redis, mongodb and clickhouse`);
             if (typeof ms.scheme !== 'string' || !/^[a-z][a-z0-9+.-]*$/.test(ms.scheme))
                 throw new Error(`pack-facts: ${vendor} declares managedService.scheme "${String(ms.scheme)}"; it is the published URL's scheme`);
             if (typeof ms.note !== 'string' || ms.note.trim() === '')
                 throw new Error(`pack-facts: ${vendor} declares managedService with no note`);
+            if (ms.configurationArg !== undefined && ms.configurationArg !== '--configuration')
+                throw new Error(`pack-facts: ${vendor} has an unsupported managed operator-configuration flag`);
+            if (ms.originalInputs !== undefined) {
+                const input = ms.originalInputs;
+                if (!input || typeof input !== 'object' || Array.isArray(input) || input.version !== 1 || input.manifestArg !== '--original-inputs' || input.rootArg !== '--original-root' || input.digestArg !== '--original-inputs-sha256'
+                    || !Array.isArray(input.paths) || !input.paths.length || new Set(input.paths).size !== input.paths.length
+                    || input.paths.some(path => typeof path !== 'string' || !path.startsWith('/') || path === '/' || path.slice(1).split('/').some(part => !part || part === '.' || part === '..' || /[\\\0\r\n]/.test(part))))
+                    throw new Error(`pack-facts: ${vendor} has an invalid original-input consumer`);
+            }
             if (pack.bin === undefined)
                 throw new Error(`pack-facts: ${vendor} declares managedService with no bin; the managed infrastructure starts the pack by its bin`);
             const other = Object.entries(packs).find(([, f]) => f.managedService?.kind === ms.kind);

package/dist/src/pack-files.js

@@ -1,4 +1,5 @@
 /** Release outputs and runtime state, relative to the pack directory being listed. */
 export function isPackArtifact(path) {
-    return /^(dist|node_modules|\.volter)(\/|$)/.test(path) || path === 'generated/pack-facts.json';
+    return /^(dist|node_modules|\.volter)(\/|$)/.test(path) || path === 'generated/pack-facts.json'
+        || path.split('/').includes('.metadata_never_index');
 }

package/dist/src/protocol-3.js

@@ -101,7 +101,7 @@ function filesUnder(dir, base = dir) {
         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))];
+        files = [...new Set(String(run.stdout).split('\0').filter(f => f && !f.split('/').includes('.metadata_never_index')))];
         listing?.set(top, files);
     }
     const under = rel(top, dir);
@@ -114,6 +114,9 @@ function allFilesUnder(dir, base = dir, excludeArtifacts = false) {
         return [];
     const out = [];
     for (const name of readdirSync(dir)) {
+        // macOS directory bookkeeping is not a pack source or release output.
+        if (name === '.metadata_never_index')
+            continue;
         const path = join(dir, name);
         if (excludeArtifacts && isPackArtifact(rel(base, path)))
             continue;
@@ -304,11 +307,31 @@ const criteria = [
             }
             // the pack's own path and the scratch directory are this checkout's, not the pack's: the verdict names neither, so
             // a standing written from one checkout reads the same from any other
+            if (run.status === null || run.signal !== null || run.error)
+                return { pass: false, cacheable: false,
+                    reason: `derive-pack interrupted: status=${run.status} signal=${run.signal} error=${run.error?.message ?? ''}` };
             if (run.status !== 0)
-                return fail(`derive-pack refused: ${String(run.stderr || run.stdout).split(unit.dir).join('.').split(tmp).join('<out>').trim().split('\n').slice(-2).join(' ').slice(0, 200)}`);
+                return { ...fail(`derive-pack refused: ${String(run.stderr || run.stdout).split(unit.dir).join('.').split(tmp).join('<out>').trim().split('\n').slice(-2).join(' ').slice(0, 200)}`), cacheable: run.status === 2 };
             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",
@@ -534,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) => {
@@ -550,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);
@@ -641,7 +675,7 @@ const criteria = [
                 manifest = (await import(__rewriteRelativeImportExtension(manifestPath))).manifest;
             }
             catch (e) {
-                return fail(`manifest.ts does not load: ${e.message.slice(0, 120)}`);
+                return { ...fail(`manifest.ts does not load: ${e.message.slice(0, 120)}`), cacheable: false };
             }
             const resources = Object.entries(manifest?.resources ?? {});
             const ruled = resources.filter(([, r]) => (r.state && Object.keys(r.state).length) || (Array.isArray(r.notState) && r.notState.length));
@@ -654,7 +688,7 @@ const criteria = [
                 states = (await import(__rewriteRelativeImportExtension(statesPath))).states;
             }
             catch (e) {
-                return fail(`semantics/states.ts does not load: ${e.message.slice(0, 120)}`);
+                return { ...fail(`semantics/states.ts does not load: ${e.message.slice(0, 120)}`), cacheable: false };
             }
             if (!states)
                 return fail('semantics/states.ts exports no `states`');

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

@@ -1,8 +1,9 @@
 // A vendor that publishes no spec of its API but ships its own client: the API as that client calls it. Tinybird
 // publishes no OpenAPI of its platform API (its reference pages omit endpoints its own CLI calls: /v0/tags,
 // /v0/sql_tables), and its Python client (`tinybird/client.py`, class TinyB, in tinybird-cli on PyPI) makes every
-// request through `_req(url, method=..., data=...)`. Each such call, read from the client's syntax tree (the pack's
-// `spec/extract-client-ops.py`), is vendored as data in `spec/client-ops.json`: its method, its URL as the client
+// request through `_req(url, method=..., data=...)`. Each such call, read from the client's syntax tree, is vendored as
+// data in `spec/client-ops.json` (the program that read it is not in the pack: a pack keeps no converter in its
+// `spec/`, Creating a pack, step 2): its method, its URL as the client
 // builds it (a label is the Python expression the client interpolates), the query keys it sends (literal, or the keys
 // of the dict it urlencodes) and its body's keys, each typed by the client's own annotation of the value (`null`
 // where the client does not say). A spec patch corrects the table as it corrects a JSON spec (derive-pack): what the

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

@@ -35,4 +35,77 @@ type RedisCommandFile = Record<string, {
 }>;
 /** The command table of the vendored files (file name → its parsed JSON), in command order. */
 export declare function fromRedisCommands(files: Record<string, RedisCommandFile>, version: string): CommandTableSpec;
+export type FieldCondition = {
+    form: 'always' | 'given' | 'wire-version' | 'other';
+    text?: string;
+};
+/** A field of a command document: where the client sets it and under what condition. `by` names a helper that sets
+ *  it; `from` the builder it was read in, where that is not the command's own (a base class, a subclass). */
+export type CommandField = {
+    name: string;
+    type: string;
+    optional?: boolean;
+    sentWhen: FieldCondition;
+    source: {
+        file: string;
+        line: number;
+    };
+    by?: string;
+    from?: string;
+};
+/** A command that is a document. `statements`: for a field that is a list of statements, the fields of one. */
+export type DocumentCommandDef = {
+    id: string;
+    fields: CommandField[];
+    statements?: Record<string, CommandField[]>;
+};
+export type DocumentCommandTableSpec = {
+    format: 'command-table';
+    language: 'document';
+    version: string;
+    source: {
+        package: string;
+        commit: string;
+        licence: string;
+    };
+    commands: DocumentCommandDef[];
+    envelope: CommandField[];
+};
+type BuilderField = CommandField & {
+    typeFrom?: string;
+    value?: string;
+    also?: unknown[];
+    spreadUnder?: string;
+};
+type Builder = {
+    builder: string;
+    kind: 'command' | 'statement';
+    file: string;
+    line: number;
+    command: string | null;
+    class?: string;
+    extends?: string;
+    addsTo?: string;
+    fields: BuilderField[];
+};
+export type DriverCommandBuilders = {
+    format: 'driver-command-builders';
+    driver: {
+        package: string;
+        version: string;
+        commit: string;
+        licence: string;
+    };
+    builders: Builder[];
+    envelope: Array<{
+        layer: string;
+        file: string;
+        line: number;
+        fields: BuilderField[];
+    }>;
+};
+/** The command table of a client's command builders: each command with its own fields, the fields its subclasses
+ *  add, the fields a base class adds to the commands that descend from it, and the fields of its statements. A builder this cannot place is
+ *  an error naming it; a table with a silent hole is never returned. */
+export declare function fromDriverCommandBuilders(doc: DriverCommandBuilders): DocumentCommandTableSpec;
 export {};

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

@@ -36,3 +36,66 @@ export function fromRedisCommands(files, version) {
     commands.sort((a, b) => a.id.localeCompare(b.id));
     return { format: 'command-table', version, commands };
 }
+const fieldOf = (f, from) => ({
+    name: f.name, type: f.type, ...(f.optional ? { optional: true } : {}), sentWhen: f.sentWhen, source: f.source,
+    ...(f.by ? { by: f.by } : {}), ...(from ? { from } : {}),
+});
+/** The command table of a client's command builders: each command with its own fields, the fields its subclasses
+ *  add, the fields a base class adds to the commands that descend from it, and the fields of its statements. A builder this cannot place is
+ *  an error naming it; a table with a silent hole is never returned. */
+export function fromDriverCommandBuilders(doc) {
+    const named = doc.builders.filter((b) => b.kind === 'command' && b.command !== null);
+    const classOf = new Map(named.filter((b) => b.class).map((b) => [b.class, b.command]));
+    const commands = new Map();
+    const add = (id, fields, from) => {
+        const held = commands.get(id) ?? { id, fields: [] };
+        for (const f of fields)
+            if (!held.fields.some((h) => h.name === f.name))
+                held.fields.push(fieldOf(f, from));
+        commands.set(id, held);
+    };
+    for (const b of named)
+        add(b.command, b.fields);
+    // what a subclass adds to its parent's document, and what the base of every command adds to all of them
+    const everyCommand = [];
+    for (const b of doc.builders.filter((b) => b.kind === 'command' && b.command === null)) {
+        if (b.addsTo === undefined)
+            throw new Error(`command-builders: ${b.builder} (${b.file}:${b.line}) names no command and adds to none`);
+        const parent = classOf.get(b.addsTo);
+        if (parent !== undefined)
+            add(parent, b.fields, b.builder);
+        else if (b.class === b.addsTo)
+            everyCommand.push(b);
+        else
+            throw new Error(`command-builders: ${b.builder} (${b.file}:${b.line}) adds to ${b.addsTo}, which builds no named command`);
+    }
+    // the base's fields go to the commands whose class descends from it, and to no other (a getMore is not one)
+    const parentOf = new Map(doc.builders.filter((b) => b.class && b.extends).map((b) => [b.class, b.extends]));
+    const descends = (cls, base) => { for (let at = cls, hops = 0; at !== undefined && hops < 16; at = parentOf.get(at), hops += 1)
+        if (at === base)
+            return true; return false; };
+    for (const b of everyCommand)
+        for (const n of named)
+            if (descends(n.extends, b.class))
+                add(n.command, b.fields, b.builder);
+    // a statement builder's fields belong to the command of its file that carries the statement list
+    for (const b of doc.builders.filter((b) => b.kind === 'statement')) {
+        const owner = named.find((n) => n.file === b.file && n.fields.some((f) => f.value === 'this.statements'));
+        const list = owner?.fields.find((f) => f.value === 'this.statements');
+        if (!owner || !list)
+            throw new Error(`command-builders: ${b.builder} (${b.file}:${b.line}) builds a statement and no command of its file carries a statement list`);
+        (commands.get(owner.command).statements ??= {})[list.name] = b.fields.map((f) => fieldOf(f));
+    }
+    const envelope = [];
+    for (const layer of doc.envelope)
+        for (const f of layer.fields)
+            if (!envelope.some((h) => h.name === f.name))
+                envelope.push(fieldOf(f, layer.layer));
+    if (commands.size === 0)
+        throw new Error('command-builders: no command was read');
+    return {
+        format: 'command-table', language: 'document', version: doc.driver.version,
+        source: { package: doc.driver.package, commit: doc.driver.commit, licence: doc.driver.licence },
+        commands: [...commands.values()].sort((a, b) => a.id.localeCompare(b.id)), envelope,
+    };
+}

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>;