@volter/twin-standard 1.0.148 → 1.0.150

package/src/create-pack.ts

@@ -150,6 +150,9 @@ export function packFetchFile(dir: string, name: string): string {
   const hasLive = existsSync(join(semantics, 'live.ts'));
   // a GraphQL API beside the REST one: its resolvers and the vendor's schema (graphql-wire.ts)
   const hasGraphql = existsSync(join(semantics, 'graphql.ts')) && existsSync(join(dir, 'src', 'generated', 'graphql-sdl.gen.json'));
+  // a stream whose documents are BSON (the MongoDB wire): the pack's own bson library, resolved from the pack as graphql's is
+  const packageJson = existsSync(join(dir, 'package.json')) ? (parseExactJson(readFileSync(join(dir, 'package.json'), 'utf8')) as { dependencies?: Record<string, string> }) : {};
+  const hasBson = existsSync(join(dir, 'src', 'stream.ts')) && packageJson.dependencies?.bson !== undefined;
   const screensDir = join(dir, 'src', 'screens');
   const screens = existsSync(screensDir) ? readdirSync(screensDir).filter((n) => /\.tsx?$/.test(n) && !/\.(test|uitest)\.tsx?$/.test(n) && !/^shared\.tsx?$/.test(n)).sort() : [];
   const id = (file: string): string => file.replace(/\.tsx?$/, '');
@@ -195,6 +198,7 @@ export function packFetchFile(dir: string, name: string): string {
     ...screens.map((f) => `import { screen as ${identifier(`screen_${id(f)}`)} } from './screens/${f}';`),
     ...laneImports,
     '',
+    ...(hasBson ? ["/** The pack's BSON library, resolved from the pack as graphql's loader is (architecture, the MongoDB wire). */", "export const loadBson = (): Promise<unknown> => import('bson');", ''] : []),
     `export function ${name}(options: PackFetchOptions = {}): DerivedFetch {`,
     '  return createPackFetch({',
     '    manifest,',
@@ -502,6 +506,26 @@ export function laneInitFiles(vendor: string, lanes: string[]): Record<string, s
   return files;
 }
 
+/** A unit's fixed files as the manifest and the spec make them now (architecture, "Creating a pack"): a lane's fetch, and
+ *  a pack's fetch, index, server and cli. A pack with a wire of its own (`src/stream.ts`, SMTP's and Redis's byte-stream
+ *  door) writes its server and cli itself: they carry its listener beside the fetch, so they are not fixed. `--index`
+ *  writes these and the grade's `fixed-reproducible` compares them byte for byte. */
+export async function fixedFiles(dir: string): Promise<Record<string, string>> {
+  const files: Record<string, string> = { 'src/fetch.ts': packFetchFile(dir, fetchName(dir)) };
+  if (!existsSync(join(dir, 'package.json'))) return files;
+  const { manifest } = await import(join(dir, 'src', 'manifest.ts')) as { manifest?: { vendor?: 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');
+  files['src/index.ts'] = packIndexFile(dir, vendor);
+  if (!existsSync(join(dir, 'src', 'stream.ts'))) {
+    // a unit whose spec is a proto (derive-pack generated its schema) is served over gRPC: its serve seam in that form
+    const lanesOnly = !hasOwnSurface(dir) && readdirSync(dir).some((n) => existsSync(join(dir, n, 'src', 'manifest.ts')));
+    files['src/server.ts'] = serverFile(vendor, !lanesOnly && existsSync(join(dir, 'src', 'generated', 'proto.gen.json')));
+    files['src/cli.ts'] = cliFile(vendor);
+  }
+  return files;
+}
+
 export async function createPack(args: string[]): Promise<void> {
   const [unit, ...rest] = args;
   if (!unit || (!rest.includes('--index') && !rest.includes('--brief') && !rest.includes('--init'))) {
@@ -562,12 +586,12 @@ export async function createPack(args: string[]): Promise<void> {
     }
     const path = join(dir, 'src', 'semantics', 'index.ts');
     if (!lanesOnly) { writeFileSync(path, handlerIndex(dir)); console.log(`create-pack: wrote ${path}`); }
-    // the fetch, again: a door file, the clock or a screen may have been added since
-    writeFileSync(join(dir, 'src', 'fetch.ts'), packFetchFile(dir, fetchName(dir)));
-    console.log(`create-pack: wrote ${join(dir, 'src', 'fetch.ts')}`);
+    // the fixed files, again: a door file, the clock, a screen, a lane or a proto may have been added since, and a pack
+    // made by an earlier create-pack takes the current form
+    for (const [rel, text] of Object.entries(await fixedFiles(dir))) { writeFileSync(join(dir, rel), text); console.log(`create-pack: wrote ${join(dir, rel)}`); }
     // a pack's own index (a lane's is the vendor's to name): the descriptor with what the kernel derives from the surface
     if (existsSync(join(dir, 'package.json'))) {
-      const { manifest } = await import(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 +601,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,10 +277,24 @@ 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`);
     },
   },
+  {
+    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.ts');
+      let want: Record<string, string>;
+      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",
@@ -462,8 +478,8 @@ const criteria: Criterion[] = [
         // 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: Array<{ start: number; end: number }> = [];
           const visit = (node: ts.Node): void => {
@@ -477,6 +493,16 @@ const criteria: Criterion[] = [
                 factory && ts.isCallExpression(factory) && ts.isIdentifier(factory.expression) && factory.expression.text === 'createPackFetch' &&
                 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);
@@ -552,13 +578,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

package/src/spec-ir-commands.ts

@@ -48,3 +48,84 @@ export function fromRedisCommands(files: Record<string, RedisCommandFile>, versi
   commands.sort((a, b) => a.id.localeCompare(b.id));
   return { format: 'command-table', version, commands };
 }
+
+// ── A command language whose commands are DOCUMENTS ─────────────────────────────────────────────────────────────
+// A command of MongoDB's wire protocol is not words with an arity: it is a document whose first key names the
+// command and whose other keys are named fields, some of them lists of statements (an update's `updates`) with
+// fields of their own, and every command also carries the fields the layers under it add (the session's, the
+// connection's). The vendor publishes no table of these that a pack may derive from (its reference and its driver
+// specifications are licensed NonCommercial); its own client is Apache-2.0 and builds every one of them. So the
+// table is the client's statement: the client's syntax tree is read by a program (as Tinybird's Python client's is,
+// spec-ir-client.ts) and what it read is the pack's vendored document, `spec/command-builders.json`; this reads that
+// data into the command table. The program is kept beside that document in the pack's `spec/`, as the table's
+// provenance, and is never a kernel script (Creating a pack, step 2).
+//
+// What the table says and does not: which commands a client can send and, for each, every field, its declared
+// type, and the condition the client sends it under. It says nothing of what a server does with them. A field's
+// condition is recorded, never evaluated: `always`; `given` (the condition tests only the option itself);
+// `wire-version` (it depends on what the server's hello says); `other`, kept as the client wrote it.
+
+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[] }>;
+};
+
+const fieldOf = (f: BuilderField, from?: string): CommandField => ({
+  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: DriverCommandBuilders): DocumentCommandTableSpec {
+  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<string, DocumentCommandDef>();
+  const add = (id: string, fields: BuilderField[], from?: string): void => {
+    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: Builder[] = [];
+  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: string | undefined, base: string): boolean => { 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: CommandField[] = [];
+  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/src/spec-ir.ts

@@ -49,6 +49,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[]>;
@@ -350,6 +352,33 @@ function formScalarsOf(doc: Json, op: Json, pathItem: Json, encoding: IrOperatio
   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: Json, op: Json, pathItem: Json, encoding: IrOperation['bodyEncoding']): Record<string, string[]> | undefined {
+  if (encoding !== 'form') return undefined;
+  const out: Record<string, string[]> = {};
+  const visit = (schema: Json, at: string[], depth: number): void => {
+    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: Json) => deref(doc, a));
+    if (alts.length) {
+      const free = alts.some((a: Json) => (a?.type === 'string' && !Array.isArray(a.enum)) || a?.type === 'integer' || a?.type === 'number' || a?.type === 'boolean');
+      const listed = alts.filter((a: Json) => a?.type === 'string' && Array.isArray(a.enum)).flatMap((a: Json) => 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: Json) => 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
@@ -477,6 +506,7 @@ export function fromOpenAPI(spec: Json): SpecIR {
       const credentials = [...new Set(security.flatMap((req: Json) => { 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 as Json).servers)?.[0]?.url ?? '');
       const ownBase = /^https?:\/\//.test(ownServer) ? new URL(ownServer).pathname.replace(/\/+$/, '') : undefined;
       raw.push({
@@ -488,6 +518,7 @@ export function fromOpenAPI(spec: Json): SpecIR {
         ...(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 as const } : {}),