@volter/twin-standard 1.0.148 → 1.0.149

package/dist/src/assessment.d.ts

@@ -14,6 +14,7 @@ export declare function assessPack(packDir: string, options?: AssessmentOptions)
     gates: {
         unit: string;
         failures: string[];
+        cacheable?: boolean;
     }[];
     quick: {
         scope: string;

package/dist/src/conformance.d.ts

@@ -11,8 +11,6 @@ export type ConformanceResult = {
 export declare const UNIT_FILES: readonly ["src/manifest.ts", "spec/SOURCE.md", "journeys/customer-life.json", "journeys/decisions.json"];
 /** The published package must carry every conformance input its units hold, including lanes. */
 export declare function unpublishedUnitFiles(unit: string): string[];
-/** Each of UNIT_FILES a unit lacks where conformance reads it: the manifest of every unit, the life at its vendor's root
- *  (lifeServed), the spec's record and the decision table of a unit with a spec (decided()). */
 export declare function unitFilesMissing(unit: string): string[];
 type Owners = Record<string, string>;
 type Decision = {

package/dist/src/conformance.js

@@ -56,6 +56,41 @@ export function unpublishedUnitFiles(unit) {
 }
 /** Each of UNIT_FILES a unit lacks where conformance reads it: the manifest of every unit, the life at its vendor's root
  *  (lifeServed), the spec's record and the decision table of a unit with a spec (decided()). */
+const trackedJourneySources = new Map();
+/** Table ownership follows one index snapshot per checkout/run. */
+function hasJourneySource(unit) {
+    const dir = join(unit, 'journeys');
+    let checkout = resolve(unit);
+    while (!existsSync(join(checkout, '.git'))) {
+        const parent = dirname(checkout);
+        if (parent === checkout) {
+            // An unpacked published package has no Git index; its delivered files
+            // are its source. Markers and empty directories are not table inputs.
+            if (!existsSync(dir))
+                return false;
+            const holdsFile = (at) => readdirSync(at, { withFileTypes: true }).some(entry => entry.name !== '.metadata_never_index'
+                && (entry.isFile() || (entry.isDirectory() && holdsFile(join(at, entry.name)))));
+            return holdsFile(dir);
+        }
+        checkout = parent;
+    }
+    const env = { ...process.env };
+    for (const key of ['GIT_DIR', 'GIT_COMMON_DIR', 'GIT_WORK_TREE', 'GIT_PREFIX', 'GIT_INDEX_FILE'])
+        delete env[key];
+    if (process.env.VOLTER_PACK_HOOK_INDEX)
+        env.GIT_INDEX_FILE = process.env.VOLTER_PACK_HOOK_INDEX;
+    const key = `${checkout}\0${env.GIT_INDEX_FILE ?? ''}`;
+    let source = trackedJourneySources.get(key);
+    if (!source) {
+        const files = spawnSync('git', ['-C', checkout, 'ls-files', '-z', '--cached', '--', ':(glob)**/journeys/**'], { env, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], maxBuffer: 16 * 1024 * 1024 });
+        if (files.status !== 0 || files.error)
+            throw new Error(`cannot read tracked journey source: ${String(files.stderr || files.error?.message)}`);
+        source = files.stdout.split('\0').filter(path => path && !path.split('/').includes('.metadata_never_index'));
+        trackedJourneySources.set(key, source);
+    }
+    const prefix = relative(checkout, dir).replaceAll('\\', '/') + '/';
+    return source.some(path => path.startsWith(prefix));
+}
 export function unitFilesMissing(unit) {
     const vendor = existsSync(join(unit, 'package.json')) ? unit : dirname(unit);
     const spec = hasOwnSurface(unit);
@@ -63,7 +98,7 @@ export function unitFilesMissing(unit) {
         'src/manifest.ts': unit,
         'spec/SOURCE.md': spec ? unit : undefined,
         'journeys/customer-life.json': vendor,
-        'journeys/decisions.json': spec ? (existsSync(join(unit, 'journeys')) ? unit : vendor) : undefined,
+        'journeys/decisions.json': spec ? (hasJourneySource(unit) ? unit : vendor) : undefined,
     };
     return UNIT_FILES.filter((f) => at[f] !== undefined && !existsSync(join(at[f], f))).map((f) => `${relative(unit, join(at[f], f))} is missing (conformance reads it)`);
 }
@@ -119,7 +154,7 @@ async function decided(pack) {
     for (const unit of unitsIn(pack).filter(hasOwnSurface)) {
         const name = nameOf(pack, unit);
         const key = unit === pack ? '' : basename(unit);
-        const journeys = existsSync(join(unit, 'journeys')) ? join(unit, 'journeys') : join(unit, '..', 'journeys');
+        const journeys = hasJourneySource(unit) ? join(unit, 'journeys') : join(unit, '..', 'journeys');
         const owners = byUnit ? byUnit[key] ?? {} : (await makeOf(unit))?.().owners?.();
         if (!owners) {
             out.push(`${name}: its fetch (${fetchName(unit)}) names no owners() to check the decision table against`);

package/dist/src/create-pack.js

@@ -617,7 +617,13 @@ export async function createPack(args) {
             // a unit whose spec is a proto (derive-pack generated its schema) is served over gRPC: its serve seam in that form,
             // the one form a unit takes after --init (a server.ts of a wire of the pack's own, SMTP's, is never written over)
             if (!lanesOnly && existsSync(join(dir, 'src', 'generated', 'proto.gen.json'))) {
-                writeFileSync(join(dir, 'src', 'server.ts'), serverFile(vendor, true, existsSync(join(dir, 'src', 'stream.ts'))));
+                const wire = existsSync(join(dir, 'src', 'stream.ts'));
+                // a raw-tcp pack exporting one create<Name>TwinStream is taken to serve that stream on its main port, and is admitted
+                // by its TCP answer alone (world-runtime host.ts servesByteStream); this one serves gRPC there, its stream on a side port
+                if (wire && manifest?.descriptor?.transport === 'raw-tcp') {
+                    throw new Error(`create-pack: ${vendor} serves gRPC on its main port and its own wire (./stream.ts) on a side port, so its descriptor's transport is not raw-tcp: raw-tcp with a stream export says the main port is that stream (world-runtime host.ts servesByteStream).`);
+                }
+                writeFileSync(join(dir, 'src', 'server.ts'), serverFile(vendor, true, wire));
                 console.log(`create-pack: wrote ${join(dir, 'src', 'server.ts')}`);
             }
             else if (manifest?.live?.length) {

package/dist/src/derive.js

@@ -21,7 +21,7 @@ import { gunzipSync } from 'node:zlib';
 import { CRUD_CLASSES, fromOpenAPI, fromSmithy, fromSwagger2, slug } from "./spec-ir.js";
 import { fromCommandReplies } from "./spec-ir-lines.js";
 import { fromProto, protoSchema, readProtoFiles } from "./spec-ir-proto.js";
-import { fromRedisCommands } from "./spec-ir-commands.js";
+import { fromDriverCommandBuilders, fromRedisCommands } from "./spec-ir-commands.js";
 import { fromClientCalls } from "./spec-ir-client.js";
 import { discoveryMethods, fromDiscovery, isDiscovery } from "./spec-ir-discovery.js";
 import { handlerCitations, quotedPage, sourceHeld, urlsIn } from "./check-sources.js";
@@ -34,22 +34,28 @@ if (!vendor) {
     console.error('usage: twin-standard derive <pack dir> [--out <dir>]');
     process.exit(1);
 }
+// A source-declared refusal is deterministic over the pinned bytes. Unexpected
+// loader, filesystem and process failures keep status 1 and must be retried.
+const SOURCE_REFUSAL = 2;
 const PKG = unitAt(vendor).dir;
 // an OpenAPI document, an AWS Smithy JSON model (smithy.json), the RFC a line protocol is (rfcNNNN.txt), or the
 // Protocol Buffers files an RPC service is published as (spec/proto/, every file the service imports), or the calls a
 // vendor's own client makes where the vendor publishes no spec (client-ops.json, spec-ir-client.ts), or one API's several
 // OpenAPI documents (spec/openapi/, read as their union: spec-documents.ts), or a Google API Discovery document
-// (discovery.json, spec-ir-discovery.ts)
+// (discovery.json, spec-ir-discovery.ts), or the command documents a vendor's own client builds where the vendor
+// publishes no table a pack may derive from (command-builders.json, spec-ir-commands.ts)
 const rfc = existsSync(join(PKG, 'spec')) ? readdirSync(join(PKG, 'spec')).find((f) => /^rfc\d+\.txt$/.test(f)) : undefined;
-const specPath = ['openapi.json.gz', 'openapi.json', 'openapi.yaml.gz', 'openapi.yaml', 'smithy.json.gz', 'smithy.json', 'discovery.json.gz', 'discovery.json', ...(rfc ? [rfc] : []), 'openapi', 'proto', 'commands', 'client-ops.json'].map((f) => join(PKG, 'spec', f)).find((p) => existsSync(p));
+const specPath = ['openapi.json.gz', 'openapi.json', 'openapi.yaml.gz', 'openapi.yaml', 'smithy.json.gz', 'smithy.json', 'discovery.json.gz', 'discovery.json', ...(rfc ? [rfc] : []), 'openapi', 'proto', 'commands', 'command-builders.json', 'client-ops.json'].map((f) => join(PKG, 'spec', f)).find((p) => existsSync(p));
 if (!specPath) {
-    console.error(`derive-pack: no spec at ${join(PKG, 'spec')}/openapi.{json,yaml}[.gz], smithy.json[.gz], rfcNNNN.txt, proto/, commands/ or client-ops.json`);
-    process.exit(1);
+    console.error(`derive-pack: no spec at ${join(PKG, 'spec')}/openapi.{json,yaml}[.gz], smithy.json[.gz], rfcNNNN.txt, proto/, commands/, command-builders.json or client-ops.json`);
+    process.exit(SOURCE_REFUSAL);
 }
 const rpcService = basename(specPath) === 'proto';
 const severalDocuments = basename(specPath) === 'openapi';
 // a command language's table, one vendored file per command (Redis's src/commands/*.json), with its version in SOURCE.md
 const commandTable = basename(specPath) === 'commands';
+// a language whose commands are documents: the table a pack's extractor read from the vendor's client
+const commandBuilders = basename(specPath) === 'command-builders.json';
 const protoTree = (dir, at = '') => Object.fromEntries(readdirSync(join(dir, at), { withFileTypes: true }).flatMap((e) => (e.isDirectory() ? Object.entries(protoTree(dir, join(at, e.name))) : e.name.endsWith('.proto') ? [[join(at, e.name), readFileSync(join(dir, at, e.name), 'utf8')]] : [])));
 const bytes = rpcService || commandTable || severalDocuments ? Buffer.from('') : readFileSync(specPath);
 const text = (specPath.endsWith('.gz') ? gunzipSync(bytes) : bytes).toString('utf8');
@@ -164,7 +170,7 @@ if (existsSync(patchPath)) {
     for (const p of parseExactJson(readFileSync(patchPath, 'utf8')).patches) {
         if (!p.why?.trim()) {
             console.error(`${vendor}: spec patch ${p.op} ${p.path} gives no why`);
-            process.exit(1);
+            process.exit(SOURCE_REFUSAL);
         }
         {
             const s = p.source;
@@ -183,7 +189,7 @@ if (severalDocuments) {
     const { doc: merged, contradictions } = mergeDocuments(doc);
     if (contradictions.length) {
         console.error(`${vendor}: the documents contradict each other; a patch (citing what shows which holds) rules each:\n  ${contradictions.join('\n  ')}`);
-        process.exit(1);
+        process.exit(SOURCE_REFUSAL);
     }
     doc = merged;
 }
@@ -193,7 +199,9 @@ const out = outAt >= 0 && process.argv[outAt + 1] ? process.argv[outAt + 1] : jo
 mkdirSync(out, { recursive: true });
 // A line protocol's surface is its commands and the replies each may answer; its manifest's transitions
 // name commands and cite the RFC.
-if (lineProtocol || commandTable) {
+if (commandBuilders)
+    doc = fromDriverCommandBuilders(doc);
+if (lineProtocol || commandTable || commandBuilders) {
     const spec = doc;
     writeFileSync(join(out, 'surface.gen.json'), `${JSON.stringify({ generatedBy: 'scripts/derive-pack.ts', spec: basename(specPath), ...spec })}\n`);
     const manifestPath = join(PKG, 'src', 'manifest.ts');
@@ -213,7 +221,7 @@ if (lineProtocol || commandTable) {
     }
     if (evidence.length) {
         console.error(`${vendor}: ${evidence.length} citation(s) do not hold:\n  ${[...new Set(evidence)].join('\n  ')}`);
-        process.exit(1);
+        process.exit(SOURCE_REFUSAL);
     }
     console.log(`${vendor}: spec ${spec.version}, ${spec.commands.length} commands${'anyCommand' in spec ? `; any command may answer ${spec.anyCommand.join(', ')}` : ''}`);
     process.exit(0);
@@ -322,7 +330,7 @@ if (existsSync(manifestPath)) {
     }
     if (evidence.length) {
         console.error(`${vendor}: ${evidence.length} citation(s) do not hold:\n  ${[...new Set(evidence)].join('\n  ')}`);
-        process.exit(1);
+        process.exit(SOURCE_REFUSAL);
     }
     // every state candidate of a resource the pack models is ruled on: a state field, or named not one
     const unruled = ir.resources.flatMap((r) => {
@@ -331,7 +339,7 @@ if (existsSync(manifestPath)) {
     });
     if (unruled.length) {
         console.error(`${vendor}: the manifest does not rule on ${unruled.length} state candidate(s): ${unruled.join(', ')} (declare each a state field or list it in notState)`);
-        process.exit(1);
+        process.exit(SOURCE_REFUSAL);
     }
     // a resource's refresh scope ("The real-system adapters", What a pack declares) names the list that enumerates it or
     // its retrieve, or says why the vendor offers no read-back; whether every stored resource declares one is
@@ -421,14 +429,14 @@ if (existsSync(manifestPath)) {
     });
     if (scopes.length) {
         console.error(`${vendor}: ${scopes.length} refresh scope(s) do not hold:\n  ${scopes.join('\n  ')}`);
-        process.exit(1);
+        process.exit(SOURCE_REFUSAL);
     }
     // the architecture's mechanical rules over the pack's own code (./p3-rules.ts): a line breaking one records why, or
     // the build stops
     const hits = p3RuleHits(PKG);
     if (hits.length) {
         console.error(`${vendor}: ${hits.length} line(s) break a Protocol 3 rule (fix it, or record why on the line: // p3: <reason>):\n  ${hits.map((h) => `${h.file}:${h.line}: ${h.rule}\n      ${h.text}`).join('\n  ')}`);
-        process.exit(1);
+        process.exit(SOURCE_REFUSAL);
     }
 }
 const counts = new Map();

package/dist/src/gate.d.ts

@@ -7,4 +7,5 @@ export declare function laneRootFailures(dir: string): string[];
 export declare function p3Gate(units: string[], opts?: Pick<GradeOptions, 'onCriterion'>): Promise<Array<{
     unit: string;
     failures: string[];
+    cacheable?: boolean;
 }>>;

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,8 +307,11 @@ 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`);
         },
     },
@@ -641,7 +647,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 +660,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/types.d.ts

@@ -53,6 +53,8 @@ export interface ScoreReport {
 }
 export interface CriterionResult {
     pass: boolean;
+    /** An interrupted check is not a verdict about unchanged source. */
+    cacheable?: boolean;
     /** why it failed, or what it measured when it passed */
     reason: string;
 }