@volter/twin-standard 1.0.148 → 1.0.149

package/dist/src/walk/behavior-journey.js

@@ -8,7 +8,8 @@ import { attributionName } from "../verdict.js";
 // score-pack walks the life through it twice, on two fresh roots, and compares what they answer.
 //
 // The caller names the pack repository first (usePacks).
-import { mysql, redis } from '@volter/world-core';
+import { mongodb, mysql, redis } from '@volter/world-core';
+import { createRequire } from 'node:module';
 import { gzipSync } from 'node:zlib';
 import { parse, visit } from 'graphql';
 import { existsSync, readdirSync, readFileSync } from 'node:fs';
@@ -16,7 +17,7 @@ import { join } from 'node:path';
 import { databaseSession, getActivePackAssets, getActiveWorldStore, LocalPackAssets, MemoryBlobStore, MemoryWorldStore, setActiveBlobStore, setActivePackAssets, setActiveWorldStore, setDeliveryObserver, setInProcessTwins } from '@volter/world-core/runtime';
 import { createHostTable } from '@volter/world-core/host-routing';
 import packFactsDocument from '@volter/world-core/generated/pack-facts.json' with { type: 'json' };
-import { isMysql, isResp, at, captureAt, echoFailures, expandFills, expectFailures, fill, fillJson, formBody, isGit, isLine, isSql, isSocket, isWait, jwtAuthorization, oauth1Authorization, presignedPath, sigv4Headers, waitMs } from "./journey-kit.js";
+import { isMongo, isMysql, isResp, at, captureAt, echoFailures, expandFills, expectFailures, fill, fillJson, formBody, isGit, isLine, isSql, isSocket, isWait, jwtAuthorization, oauth1Authorization, presignedPath, sigv4Headers, waitMs } from "./journey-kit.js";
 import { lanesOf, lineShape, shapeChecker } from "./shape.js";
 import { walkPackDirectory } from "./pack-directory.js";
 import { xmlMembers } from "./xml-view.js";
@@ -579,6 +580,99 @@ export async function walk(journey, root, collect, opts) {
             opts.hooks?.after?.(step, link, answered, collect.slice(before));
         }
     };
+    // A MongoDB step speaks the pack's MongoDB wire as an application's driver does (@volter/world-core/mongodb's client), on
+    // the same byte-stream adapter the owned TCP listener serves. The document codec is BSON, the library the pack
+    // installs: the walk loads it from the pack's own dependencies, so a step is encoded by the library the pack decodes with.
+    const mongoLinks = new Map();
+    let bson;
+    const bareNumber = (value, at = 'mongo') => {
+        if (typeof value === 'number')
+            return at;
+        if (Array.isArray(value)) {
+            for (const [i, item] of value.entries()) {
+                const found = bareNumber(item, `${at}[${i}]`);
+                if (found)
+                    return found;
+            }
+            return undefined;
+        }
+        if (value && typeof value === 'object')
+            for (const [key, item] of Object.entries(value)) {
+                const found = bareNumber(item, `${at}.${key}`);
+                if (found)
+                    return found;
+            }
+        return undefined;
+    };
+    const mongoStep = async (step) => {
+        const before = collect.length;
+        let answered = { status: 0, body: undefined };
+        const link = step.link ?? 'mongo';
+        opts.hooks?.before?.(step, link, step.mongo);
+        try {
+            if (!bson) {
+                const pack = walkPackDirectory(packsDir(), journey.vendor, dependenciesDir());
+                if (!pack)
+                    throw new Error(`no pack directory for ${journey.vendor} to load its BSON library from`);
+                bson = createRequire(join(pack, 'package.json'))('bson');
+            }
+            const codec = { serialize: (document) => bson.serialize(document), deserialize: (bytes) => bson.deserialize(bytes, { promoteValues: false, promoteLongs: false, bsonRegExp: true }) };
+            let held = mongoLinks.get(link);
+            if (!held) {
+                if (!served?.stream)
+                    streams ??= await vendorStream(packsDir(), journey.vendor, dependenciesDir());
+                const factory = served?.stream ?? streams?.(root, {});
+                if (!factory)
+                    throw new Error(`no create<Name>TwinStream adapter enrolled for ${journey.vendor}`);
+                let out = [];
+                const conn = factory({ write: (b) => { out.push(...b); }, end: () => { } }, '127.0.0.1');
+                const exchange = async (bytes) => { conn.data(bytes); await conn.settled(); const got = Uint8Array.from(out); out = []; return got; };
+                held = { client: mongodb.mongoClient(exchange, codec), database: 'test', close: () => conn.close() };
+                mongoLinks.set(link, held);
+            }
+            if (step.database)
+                held.database = fill(step.database, captured);
+            const written = fillJson(step.mongo, captured);
+            const bare = bareNumber(written);
+            if (bare)
+                throw new Error(`${bare} is a bare JSON number: write its kind ({ "$numberInt": "…" }, $numberLong or $numberDouble)`);
+            const reply = await held.client.command(held.database, bson.EJSON.deserialize(written, { relaxed: false }));
+            const body = bson.EJSON.serialize(reply, { relaxed: false });
+            const ok = body.ok, failed = !ok || Number(Object.values(ok)[0]) !== 1;
+            const code = failed ? Number(Object.values(body.code ?? { none: Number.NaN })[0]) : undefined;
+            answered = { status: code ?? 0, body };
+            if (opts.verbose)
+                console.log(`  ${String(code ?? 'OK').padEnd(5)} ${link.padEnd(6)} ${String(Object.keys(step.mongo)[0] ?? '').padEnd(20)} ${step.name}`);
+            if (step.refused !== undefined ? code !== step.refused : failed) {
+                collect.push({ step: step.name, beat: 'STATUS', detail: failed ? `MongoDB refused it: ${code} ${String(body.codeName ?? '')} ${String(body.errmsg ?? '')}${step.refused ? ` (wanted ${step.refused})` : ''}` : `MongoDB completed it, wanted ${step.refused}` });
+                return;
+            }
+            for (const [name, dot] of Object.entries(step.capture ?? {})) {
+                const value = captureAt(body, dot);
+                if (value === undefined || value === null)
+                    collect.push({ step: step.name, beat: 'CAPTURE', detail: `nothing at "${dot}" in the answer to capture as {${name}}` });
+                else
+                    remember(name, value);
+            }
+            try {
+                for (const detail of expectFailures(step.expect ?? [], body, captured))
+                    collect.push({ step: step.name, beat: 'EXPECT', detail });
+            }
+            catch (e) {
+                collect.push({ step: step.name, beat: 'CAPTURE', detail: e.message });
+            }
+            if (step.close) {
+                mongoLinks.get(link)?.close();
+                mongoLinks.delete(link);
+            }
+        }
+        catch (e) {
+            collect.push({ step: step.name, beat: 'MONGO', detail: e.message });
+        }
+        finally {
+            opts.hooks?.after?.(step, link, answered, collect.slice(before));
+        }
+    };
     // A git step is a git client's clone or push on the pack's smart-HTTP plane (packages/twin-standard/src/walk/git-client.ts); its answer is
     // checked as a request's is (status, captures, expectations).
     const gitStep = async (step) => {
@@ -931,6 +1025,10 @@ export async function walk(journey, root, collect, opts) {
     try {
         for (const step of journey.steps) {
             stepNow = step.name;
+            if (isMongo(step)) {
+                await mongoStep(step);
+                continue;
+            }
             if (isMysql(step)) {
                 await mysqlStep(step);
                 continue;

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

@@ -226,7 +226,7 @@ export type Journey = {
     }) => boolean;
     steps: Step[];
 };
-export type Step = JourneyStep | WaitStep | LineStep | GitStep | SocketStep | SqlStep | RespStep | MysqlStep;
+export type Step = JourneyStep | WaitStep | LineStep | GitStep | SocketStep | SqlStep | RespStep | MysqlStep | MongoStep;
 /** A step on a MySQL wire (the kernel's @volter/world-core/mysql, a pack's `create<Name>TwinStream`), spoken as an
  *  application's driver speaks it. `signIn` opens a named connection (`link`, `mysql` by default) with a user and
  *  password (mysql_native_password); `mysql` sends a statement on it: a text query, or a prepared statement when
@@ -249,6 +249,26 @@ export type MysqlStep = {
     expect?: JourneyStep['expect'];
 };
 export declare const isMysql: (step: Step) => step is MysqlStep;
+/** A step on a pack's MongoDB wire, sent as an application's driver sends it (`@volter/world-core/mongodb`'s client)
+ *  on a named `link`, opened by the first step that names it. `mongo` is ONE command document, written in
+ *  canonical extended JSON so that what a document holds is written as it is: an ObjectId as `{ "$oid": … }`, a date
+ *  as `{ "$date": … }`, and a number with its kind (`{ "$numberInt": "1" }`, `$numberLong`, `$numberDouble`); a bare
+ *  JSON number is refused, because JSON does not say which of three kinds it is. `database` is the database it is
+ *  sent to (the link's last one, else `test`). Its answer is the reply document in the same form. A reply whose
+ *  `ok` is 0 fails the step unless `refused` names its `code`. */
+export type MongoStep = {
+    name: string;
+    mongo: Record<string, unknown>;
+    database?: string;
+    link?: string;
+    close?: boolean;
+    refused?: number;
+    capture?: JourneyStep['capture'];
+    expect?: JourneyStep['expect'];
+    example?: string;
+    exampleDiffers?: Record<string, string>;
+};
+export declare const isMongo: (step: Step) => step is MongoStep;
 /** A typed request/reply stream step. `resp` is one command or a pipeline of commands, on a named connection.
  * Captures and expectations see `{ replies, last, error }`; binary arguments use `{ base64 }`.
  * `read` drains pushes or a blocking command's answer without sending bytes. */

package/dist/src/walk/journey-kit.js

@@ -198,6 +198,7 @@ export function expandFills(journey) {
     return steps.some((x, i) => x !== journey.steps[i]) ? { ...journey, steps } : journey;
 }
 export const isMysql = (step) => 'mysql' in step || 'signIn' in step;
+export const isMongo = (step) => 'mongo' in step;
 export const isResp = (step) => 'connection' in step;
 export const isLine = (step) => 'on' in step;
 export const isSocket = (step) => 'socket' in step;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/twin-standard",
-  "version": "1.0.148",
+  "version": "1.0.149",
   "description": "The Protocol 3 standard for Volter twin packs: the criteria a pack is graded by, the grader, the gate a pack repository and the twin catalog run on every change and submission, and the spec derivation the grade checks against. Pin a version: every place a pack is judged judges by that standard.",
   "keywords": [
     "twin",
@@ -75,7 +75,7 @@
     "yaml": "2.9.0"
   },
   "peerDependencies": {
-    "@volter/world-core": "3.0.155",
+    "@volter/world-core": "3.0.156",
     "@volter/world-runtime": "*",
     "playwright": "^1.63.0"
   },

package/src/conformance.ts

@@ -65,6 +65,38 @@ export 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()). */
+const trackedJourneySources = new Map<string, string[]>();
+/** Table ownership follows one index snapshot per checkout/run. */
+function hasJourneySource(unit: string): boolean {
+  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: string): boolean => 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: string): string[] {
   const vendor = existsSync(join(unit, 'package.json')) ? unit : dirname(unit);
   const spec = hasOwnSurface(unit);
@@ -72,7 +104,7 @@ export function unitFilesMissing(unit: string): string[] {
     '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)`);
 }
@@ -125,7 +157,7 @@ async function decided(pack: string): Promise<string[]> {
   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`); continue; }
     const table = readJson(join(journeys, 'decisions.json')) as { decisions?: Decision[] } | undefined;

package/src/create-pack.ts

@@ -567,7 +567,7 @@ export async function createPack(args: string[]): Promise<void> {
     console.log(`create-pack: wrote ${join(dir, 'src', 'fetch.ts')}`);
     // a pack's own index (a lane's is the vendor's to name): the descriptor with what the kernel derives from the surface
     if (existsSync(join(dir, 'package.json'))) {
-      const { manifest } = await import(join(dir, 'src', 'manifest.ts')) as { manifest?: { vendor?: string } };
+      const { manifest } = await import(join(dir, 'src', 'manifest.ts')) as { manifest?: { vendor?: string; descriptor?: { transport?: string } } };
       const vendor = manifest?.vendor;
       if (!vendor || !/^[a-z][a-z0-9-]*$/.test(vendor)) throw new Error('Pack manifest must declare its vendor identity independently of the npm package name');
       writeFileSync(join(dir, 'src', 'index.ts'), packIndexFile(dir, vendor));
@@ -577,7 +577,13 @@ export async function createPack(args: string[]): Promise<void> {
       // 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 as { live?: unknown[] } | undefined)?.live?.length) {
         // a unit that takes broadcasts over RTMP serves its ingest beside its HTTP host, and its bin takes the ingest's

package/src/derive.ts

@@ -14,7 +14,7 @@ import { gunzipSync } from 'node:zlib';
 import { CRUD_CLASSES, fromOpenAPI, fromSmithy, fromSwagger2, slug, type SpecIR } from './spec-ir.ts';
 import { fromCommandReplies, type LineSpec } from './spec-ir-lines.ts';
 import { fromProto, protoSchema, readProtoFiles } from './spec-ir-proto.ts';
-import { fromRedisCommands, type CommandTableSpec } from './spec-ir-commands.ts';
+import { fromDriverCommandBuilders, fromRedisCommands, type CommandTableSpec, type DocumentCommandTableSpec, type DriverCommandBuilders } from './spec-ir-commands.ts';
 import { fromClientCalls, type ClientOpsSpec } from './spec-ir-client.ts';
 import { discoveryMethods, fromDiscovery, isDiscovery } from './spec-ir-discovery.ts';
 import { handlerCitations, quotedPage, sourceHeld, type Patch, type SourceRecord, urlsIn } from './check-sources.ts';
@@ -28,22 +28,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: string, at = ''): Record<string, string> => 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');
@@ -139,7 +145,7 @@ for (const c of handlerCitations(PKG)) {
 const patchPath = join(PKG, 'spec', 'patches.json');
 if (existsSync(patchPath)) {
   for (const p of parseExactJson(readFileSync(patchPath, 'utf8')).patches as Array<{ op: string; path: string; from?: string; value?: unknown; why: string }>) {
-    if (!p.why?.trim()) { console.error(`${vendor}: spec patch ${p.op} ${p.path} gives no why`); process.exit(1); }
+    if (!p.why?.trim()) { console.error(`${vendor}: spec patch ${p.op} ${p.path} gives no why`); process.exit(SOURCE_REFUSAL); }
     {
       const s = (p as Patch).source;
       const held = s?.recording !== undefined ? unheldRecording(s.recording, s.quote)
@@ -156,7 +162,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;
 }
@@ -166,8 +172,9 @@ const out = outAt >= 0 && process.argv[outAt + 1] ? process.argv[outAt + 1]! : j
 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) {
-  const spec = doc as LineSpec | CommandTableSpec;
+if (commandBuilders) doc = fromDriverCommandBuilders(doc as DriverCommandBuilders);
+if (lineProtocol || commandTable || commandBuilders) {
+  const spec = doc as LineSpec | CommandTableSpec | DocumentCommandTableSpec;
   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');
   if (existsSync(manifestPath)) {
@@ -184,7 +191,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);
@@ -288,7 +295,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) => {
@@ -297,7 +304,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
@@ -368,14 +375,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);
   }
 }
 

package/src/gate.ts

@@ -42,6 +42,39 @@ export function unitsOf(repo: string): string[] {
  *  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: string): string[] {
+  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: ts.Expression): boolean => {
+    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: string, names: string[]): Set<string> {
   if (!names.length) return new Set();
@@ -55,15 +88,16 @@ export function laneRootFailures(dir: string): string[] {
   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: string): string => (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'))) failures.push('layout: src/fetch.ts builds no createVendorFetch: the kernel routes a vendor\'s lanes from its manifest, nothing by hand');
   // the root's own files hold to the pack contract as a unit's do (the grade's kernel-contract)
@@ -85,9 +119,9 @@ export function laneRootFailures(dir: string): string[] {
 }
 
 /** Each unit's blocking form failures (empty when it may be in the repository). */
-export async function p3Gate(units: string[], opts: Pick<GradeOptions, 'onCriterion'> = {}): Promise<Array<{ unit: string; failures: string[] }>> {
+export async function p3Gate(units: string[], opts: Pick<GradeOptions, 'onCriterion'> = {}): Promise<Array<{ unit: string; failures: string[]; cacheable?: boolean }>> {
   return withCheckoutFiles(async () => {
-    const out: Array<{ unit: string; failures: string[] }> = [];
+    const out: Array<{ unit: string; failures: string[]; cacheable?: boolean }> = [];
     for (const unit of units) {
       // a vendor whose every API is a lane has no spec of its own: its lanes are graded, and its root is only the vendor's
       // front (architecture, "Pack layout", "Other wires: lanes")
@@ -95,7 +129,7 @@ export async function p3Gate(units: string[], opts: Pick<GradeOptions, 'onCriter
       if (lanesOnly || !existsSync(join(unit, 'src', 'manifest.ts'))) { out.push({ unit, failures: laneRootFailures(unit) }); continue; }
       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/src/grade.ts

@@ -10,7 +10,7 @@ import { unitAt } from './unit.ts';
 /** The latest version of each standard. A new protocol, or a revision, replaces or joins this list. */
 export const STANDARDS: Standard[] = [protocol3];
 
-export interface CriterionGrade { id: string; section: string; asks: string; pass: boolean; reason: string }
+export interface CriterionGrade { id: string; section: string; asks: string; pass: boolean; reason: string; cacheable?: boolean }
 export interface StandardGrade { grade: number; met: number; total: number; criteria: CriterionGrade[]; planned: string[] }
 
 export type GradeOptions = {
@@ -40,7 +40,7 @@ export async function grade(dir: string, opts: GradeOptions = {}): Promise<Recor
       if (opts.sections && !opts.sections.includes(c.section)) continue;
       opts.onCriterion?.(name, c.id);
       let result;
-      try { result = await c.check(unit); } catch (e) { result = { pass: false, reason: `the check threw: ${(e as Error).message.slice(0, 160)}` }; }
+      try { result = await c.check(unit); } catch (e) { result = { pass: false, cacheable: false, reason: `the check threw: ${(e as Error).message.slice(0, 160)}` }; }
       opts.onCriterion?.(name, c.id, result);
       criteria.push({ id: c.id, section: c.section, asks: c.asks, ...result });
     }

package/src/pack-facts.ts

@@ -37,7 +37,7 @@ export type PackFacts = {
   /** The Prisma driver adapter this database twin is reached through (see TwinPack.prismaAdapter). */
   prismaAdapter?: { adapter: string; export: string; urlEnv: string };
   /** The managed-infrastructure kind this pack is the World's backing for (architecture.md, "The descriptor"). */
-  managedService?: { kind: 'redis' | 'mongodb'; scheme: string; note: string };
+  managedService?: { 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?: { kind: 'postgres'; arg: string; note: string };
   /** Listeners the twin opens beside its main port (see TwinPack.sidePorts). */
@@ -191,10 +191,17 @@ export async function compilePackFacts(dirs: Array<{ vendor: string; dir: string
       facts.managedDatabase = pack.managedDatabase;
     }
     if (pack.managedService !== undefined) {
-      const ms = pack.managedService as { kind?: unknown; scheme?: unknown; note?: unknown };
-      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`);
+      const ms = pack.managedService as { kind?: unknown; scheme?: unknown; note?: unknown; configurationArg?: unknown; originalInputs?: unknown };
+      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 as { version?: unknown; manifestArg?: unknown; rootArg?: unknown; digestArg?: unknown; paths?: unknown };
+        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);
       if (other) throw new Error(`pack-facts: ${vendor} and ${other[0]} both declare managedService.kind "${ms.kind}"; one pack backs a kind`);

package/src/pack-files.ts

@@ -1,4 +1,5 @@
 /** Release outputs and runtime state, relative to the pack directory being listed. */
 export function isPackArtifact(path: string): boolean {
-  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/src/protocol-3.ts

@@ -88,7 +88,7 @@ function filesUnder(dir: string, base = dir): string[] {
     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);
@@ -100,6 +100,8 @@ function allFilesUnder(dir: string, base = dir, excludeArtifacts = false): strin
   if (!existsSync(dir)) return [];
   const out: string[] = [];
   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;
     if (statSync(path).isDirectory()) out.push(...allFilesUnder(path, base, excludeArtifacts));
@@ -275,7 +277,9 @@ const criteria: Criterion[] = [
       }
       // 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 !== 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)}`);
+      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)}`), 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`);
     },
   },
@@ -552,13 +556,13 @@ const criteria: Criterion[] = [
       const manifestPath = join(unit.dir, 'src', 'manifest.ts');
       const statesPath = join(unit.dir, 'src', 'semantics', 'states.ts');
       let manifest: { resources?: Record<string, { state?: unknown; notState?: unknown }> } | undefined;
-      try { manifest = ((await import(manifestPath)) as { manifest?: typeof manifest }).manifest; } catch (e) { return fail(`manifest.ts does not load: ${(e as Error).message.slice(0, 120)}`); }
+      try { manifest = ((await import(manifestPath)) as { manifest?: typeof manifest }).manifest; } catch (e) { return { ...fail(`manifest.ts does not load: ${(e as Error).message.slice(0, 120)}`), cacheable: false }; }
       const resources = Object.entries(manifest?.resources ?? {});
       const ruled = resources.filter(([, r]) => (r.state && Object.keys(r.state as object).length) || (Array.isArray(r.notState) && r.notState.length));
       if (!ruled.length) return pass('the pack declares no state machine and rules no candidate');
       if (!existsSync(statesPath)) return fail(`${ruled.length} resources carry states or rulings, and there is no semantics/states.ts`);
       let states: Record<string, { state?: unknown; notState?: unknown }> | undefined;
-      try { states = ((await import(statesPath)) as { states?: typeof states }).states; } catch (e) { return fail(`semantics/states.ts does not load: ${(e as Error).message.slice(0, 120)}`); }
+      try { states = ((await import(statesPath)) as { states?: typeof states }).states; } catch (e) { return { ...fail(`semantics/states.ts does not load: ${(e as Error).message.slice(0, 120)}`), cacheable: false }; }
       if (!states) return fail('semantics/states.ts exports no `states`');
       const off = ruled.filter(([name, r]) => (r.state !== undefined && r.state !== states![name]?.state) || (r.notState !== undefined && r.notState !== states![name]?.notState)).map(([name]) => name);
       return off.length ? fail(`resources whose states or rulings are not states.ts's own: ${off.join(', ')}`) : pass(`${ruled.length} resources, their states and rulings from states.ts`);

package/src/spec-ir-client.ts

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