@volter/twin-standard 1.0.32 → 1.0.34

package/dist/src/create-pack.js

@@ -0,0 +1,576 @@
+#!/usr/bin/env bun
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+// create-pack — the files of a Protocol 3 pack that nobody should write (the board's `create-pack` card;
+// docs/contributing/architecture.md, "Creating a pack"), and the brief an author writes the rest from.
+//
+//   bun scripts/create-pack.ts <dir> --init <vendor>     write every fixed file of a new pack that does not exist yet
+//   bun scripts/create-pack.ts <dir> --init <vendor> --lanes a,b
+//                                                        the same for a pack of lanes, one per API of the vendor, each
+//                                                        derived from its own spec (<dir>/<lane>/spec): each lane's
+//                                                        manifest, fetch, index and semantics, and the pack's server
+//                                                        sending each lane's host to it
+//                                                          (package.json, README.md, LICENSE, src/{manifest,fetch,server,cli,
+//                                                          index}.ts, src/semantics/{states,shared,doors}.ts,
+//                                                          journeys/demand.json): the author fills the manifest's
+//                                                          vendor facts, the descriptor's hosts and the families
+//   bun scripts/create-pack.ts <unit> --index            write src/semantics/index.ts, the handler map, and src/fetch.ts from the
+//                                                          families' files (every exported function, by its name)
+//   bun scripts/create-pack.ts <unit> --brief [--out f]  the author's brief: every operation the derived core does not
+//                                                          serve and no handler answers yet, by family, with what the
+//                                                          vendored spec says of it (summary, description, parameters,
+//                                                          the answers it documents and their examples), so a handler
+//                                                          is written from the vendor's words, never from memory
+//
+// <unit> is a pack (`clerk`) or a lane (`clerk/fapi`). A brief is a work aid, printed (or written to --out); it is not
+// part of the pack.
+import { parseExactJson, exactInteger } from '@volter/world-core/exact-json';
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join, relative, resolve } from 'node:path';
+import { gunzipSync } from 'node:zlib';
+import { parse as parseYaml } from 'yaml';
+import { coreFor } from '@volter/world-core';
+import { decisionTableProblems } from "./conformance.js";
+import { handlerName } from "./protocol-3.js";
+import { hasOwnSurface } from "./lanes.js";
+const FIXED = new Set(['answer-views.ts', 'states.ts', 'index.ts', 'shared.ts', 'doors.ts', 'seed.ts', 'around.ts', 'events.ts', 'clock.ts', 'tenant.ts', 'scenario.ts', 'gap.ts', 'graphql.ts', 'sockets.ts', 'board.ts']);
+/** A family file's name as a JavaScript identifier (`well-known` is `well_known`). */
+/** A family's name in code: as a handler's (a name JavaScript reserves, the family `default`, takes a trailing `_`). */
+const identifier = (family) => handlerName(family);
+/** The families' files of a unit's semantics, with the handlers each exports. */
+function families(dir) {
+    const semantics = join(dir, 'src', 'semantics');
+    if (!existsSync(semantics))
+        return [];
+    return readdirSync(semantics)
+        // events.ts is the webhook renderer's; a vendor with an `events` family keeps that family's handlers there too
+        .filter((f) => f.endsWith('.ts') && !f.endsWith('.test.ts') && (!FIXED.has(f) || f === 'events.ts'))
+        .sort()
+        .map((f) => ({
+        family: f.replace(/\.ts$/, ''),
+        handlers: [...readFileSync(join(semantics, f), 'utf8').matchAll(/^export\s+async\s+function\s+([A-Za-z0-9_$]+)/gm)].map((m) => m[1]),
+    }));
+}
+/** src/semantics/index.ts: the handler map by operationId, keeping the name the unit's fetch imports it by. Each
+ *  operation of the generated surface whose handler (named as `handlerName` names it) a family's file exports is an
+ *  entry: an id no JavaScript name can hold (`storage.object.get`, `pulls/create`) is keyed as it is. */
+export function handlerIndex(dir) {
+    const path = join(dir, 'src', 'semantics', 'index.ts');
+    const vendor = basename(dir);
+    const fallback = `${vendor.split(/[^A-Za-z0-9]+/).filter(Boolean).map((w, i) => (i === 0 ? w : w[0].toUpperCase() + w.slice(1))).join('')}Semantics`;
+    const name = existsSync(path) ? /export\s+const\s+([A-Za-z0-9_$]+)\s*:/.exec(readFileSync(path, 'utf8'))?.[1] ?? fallback : fallback;
+    const fams = families(dir).filter((f) => f.handlers.length > 0);
+    const surfacePath = join(dir, 'src', 'generated', 'surface.gen.json');
+    // a command table's surface (Redis's) names no HTTP operation: its wire is the pack's front, so no handler is mapped
+    const ids = existsSync(surfacePath) ? (parseExactJson(readFileSync(surfacePath, 'utf8')).operations ?? []).map((o) => o.id) : [];
+    // an index written before the derive has no operations to map, and every served call would fall to the gap (404): refuse
+    // it rather than write an empty map (2026-09-30: six packs committed so)
+    if (!existsSync(surfacePath) && fams.length)
+        throw new Error(`${dir}: no src/generated/surface.gen.json yet; derive the unit (scripts/derive-pack.ts) before --index`);
+    const where = new Map(fams.flatMap((f) => f.handlers.map((h) => [h, f.family])));
+    const named = new Set([...new Set(ids)].map(handlerName));
+    const stray = [...where.keys()].filter((h) => !named.has(h));
+    // a stray export breaks the handler contract (each export an operation of its family): the index is written, and the
+    // command fails, so a caller reads it from the exit code
+    if (stray.length) {
+        console.error(`create-pack: ${basename(dir)}: ${stray.join(', ')} name${stray.length === 1 ? 's' : ''} no operation of the surface: not in the handler map`);
+        process.exitCode = 1;
+    }
+    const entries = [...new Set(ids)].filter((id) => where.has(handlerName(id))).sort().map((id) => `  ${/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(id) ? id : JSON.stringify(id)}: ${identifier(where.get(handlerName(id)))}.${handlerName(id)},`);
+    return [
+        '// GENERATED by scripts/create-pack.ts --index: the handler map, by operationId, from the families\' files (each',
+        '// handler named as its operation). Do not edit; add a handler to its family\'s file and generate again.',
+        "import type { Handler } from '@volter/world-core';",
+        ...fams.map((f) => `import * as ${identifier(f.family)} from './${f.family}.ts';`),
+        '',
+        `export const ${name}: Record<string, Handler> = {`,
+        ...entries,
+        '};',
+        '',
+    ].join('\n');
+}
+/** What a unit serves, checked against its decision table and its demand (the P3 procedure: demand, then the decision
+ *  table, then the code). `journeys/decisions.json` (the vendor's, beside its lanes) names, for each operation the unit
+ *  serves, the demand it answers and the mechanism that serves it (`handler` or `core`); an operation it does not serve
+ *  is `unmodeled` in the manifest. The unit's owners are the vendor's dispatch's for that unit. A problem stops the index:
+ *  six packs once shipped answering 404 to everything, and scope once grew past demand, both unseen by the tools. */
+export async function decisionProblems(dir) {
+    const out = [];
+    const journeys = existsSync(join(dir, 'journeys')) ? join(dir, 'journeys') : join(dir, '..', 'journeys');
+    const tablePath = join(journeys, 'decisions.json');
+    // the table is the vendor's, so a unit is read from the vendor's dispatch, each unit against its own operations
+    // (decisionTableProblems): an id the root and a lane share is two operations, and a lane's gap stays its gap
+    const vendorDir = journeys === join(dir, 'journeys') || !existsSync(join(dir, '..', 'src', 'fetch.ts')) ? dir : join(dir, '..');
+    const unit = vendorDir === dir ? '' : basename(dir);
+    const mod = await import(__rewriteRelativeImportExtension(resolve(vendorDir, 'src', 'fetch.ts')));
+    const make = mod[fetchName(vendorDir)];
+    const dispatch = make?.();
+    // a unit with a spec serves operations: a dispatch that names no owners cannot be checked, and passes nothing
+    if (hasOwnSurface(dir) && typeof dispatch?.owners !== 'function')
+        return [`${relative(process.cwd(), dir)}/src/fetch.ts: its dispatch names no owners() to check against the decision table`];
+    const byUnit = dispatch?.ownersByUnit?.() ?? { '': dispatch?.owners?.() ?? {} };
+    const owners = byUnit[unit] ?? {};
+    // an operation no demand names answers the vendor's gap (coverage counts it `todo`, architecture "Doors, screens and the
+    // gap"); a demanded one served by nothing is refused, and one the manifest keeps from the core is `unmodeled`
+    if (!existsSync(tablePath))
+        return [...out, `${relative(dir, tablePath)} is missing: the decision table names each served operation, its demand and its mechanism`];
+    const table = parseExactJson(readFileSync(tablePath, 'utf8'));
+    const demandPath = join(journeys, 'demand.json');
+    const demanded = existsSync(demandPath)
+        ? (parseExactJson(readFileSync(demandPath, 'utf8')).applications ?? []).flatMap((a) => a.backend ?? []).flatMap((b) => String(b.operation ?? '').split(/;\s*/))
+        : [];
+    // a refresh reads the vendor's list or retrieve, and a World rooted at a second World's twin of the pack reads it from
+    // that twin (pack-done's (g)): an operation a refresh scope names is one the pack serves
+    const { manifest } = await import(__rewriteRelativeImportExtension(resolve(dir, 'src', 'manifest.ts')));
+    out.push(...decisionTableProblems(unit, byUnit, table.decisions ?? [], demanded, manifest?.doors?.map((d) => d.id) ?? []));
+    for (const [name, decl] of Object.entries(manifest?.resources ?? {})) {
+        for (const id of [decl.refresh?.list ?? decl.refresh?.get, decl.refresh?.detail])
+            if (id && id in owners && owners[id] === 'gap')
+                out.push(`${id}: ${name}'s refresh reads it, and nothing serves it (serve it, or declare refresh none with why)`);
+    }
+    return out;
+}
+/** A unit's fetch.ts, a fixed file: `createPackFetch` over its parts as they stand (the manifest, the surface, the handler
+ *  map, and its doors, clock and screens where it has them). `--init` writes it, and `--index` again when a door file,
+ *  the clock or a screen is added. `name` is the fetch's export (`createClerkFetch`, a lane's `createFapiLaneFetch`). */
+/** A unit's fetch export: a pack's `create<Vendor>Fetch`, a lane's (a unit with no package.json of its own) `create<Lane>LaneFetch`. */
+export const fetchName = (dir) => (existsSync(join(dir, 'package.json')) ? `create${pascal(basename(dir))}Fetch` : `create${pascal(basename(dir))}LaneFetch`);
+export function packFetchFile(dir, name) {
+    const semantics = join(dir, 'src', 'semantics');
+    const index = join(semantics, 'index.ts');
+    const map = existsSync(index) ? /export\s+const\s+([A-Za-z0-9_$]+)\s*:/.exec(readFileSync(index, 'utf8'))?.[1] : undefined;
+    const hasDoors = existsSync(join(semantics, 'doors.ts'));
+    const hasClock = existsSync(join(semantics, 'clock.ts'));
+    const hasAround = existsSync(join(semantics, 'around.ts'));
+    const hasBoard = existsSync(join(semantics, 'board.ts'));
+    const hasTenant = existsSync(join(semantics, 'tenant.ts'));
+    const hasScenario = existsSync(join(semantics, 'scenario.ts'));
+    const hasGap = existsSync(join(semantics, 'gap.ts'));
+    const hasSockets = existsSync(join(dir, 'src', 'semantics', 'sockets.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'));
+    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) => file.replace(/\.tsx?$/, '');
+    // a vendor's own lanes (a pack's directories with a manifest of their own), which its manifest's `lanes` routes to
+    const lanes = existsSync(join(dir, 'package.json')) ? readdirSync(dir).filter((n) => existsSync(join(dir, n, 'src', 'manifest.ts'))).sort() : [];
+    const laneImports = lanes.map((l) => `import { ${fetchName(join(dir, l))}, manifest as ${identifier(`${l}_manifest`)} } from '../${l}/src/index.ts';`);
+    const laneParts = `{ ${lanes.map((l) => `${JSON.stringify(l)}: { fetch: ${fetchName(join(dir, l))}(options), manifest: ${identifier(`${l}_manifest`)} }`).join(', ')} }`;
+    // a vendor whose every API is a lane: no spec of its own, only its manifest's lanes (architecture, "Other wires: lanes")
+    if (lanes.length && !hasOwnSurface(dir)) {
+        return [
+            '// GENERATED by scripts/create-pack.ts (--init, --index): a fixed file. The kernel serves the vendor\'s discovery door and',
+            "// sends each request to the lane its manifest's routes name (architecture, \"Other wires: lanes\").",
+            "import { createVendorFetch, type DerivedFetch, type PackFetchOptions } from '@volter/world-core';",
+            "import { manifest } from './manifest.ts';",
+            ...laneImports,
+            '',
+            `export function ${name}(options: PackFetchOptions = {}): DerivedFetch {`,
+            `  return createVendorFetch(manifest, ${laneParts});`,
+            '}',
+            '',
+        ].join('\n');
+    }
+    const surfacePath = join(dir, 'src', 'generated', 'surface.gen.json');
+    // a command table's surface (Redis's commands, a line protocol's command-reply) is no HTTP surface: it is cast through unknown
+    const commandSurface = existsSync(surfacePath) && ['command-reply', 'command-table'].includes(parseExactJson(readFileSync(surfacePath, 'utf8')).format);
+    return [
+        '// GENERATED by scripts/create-pack.ts (--init, --index): a fixed file. The kernel serves the discovery door, the clock,',
+        "// the World's doors, the vendor's screens and the API from the pack's parts (architecture, \"The pack contract\").",
+        "import { createPackFetch, type DerivedFetch, type DerivedSurface, type PackFetchOptions } from '@volter/world-core';",
+        "import surface from './generated/surface.gen.json' with { type: 'json' };",
+        "import { manifest } from './manifest.ts';",
+        ...(hasAround ? ["import { around } from './semantics/around.ts';"] : []),
+        ...(hasBoard ? ["import { board } from './semantics/board.ts';"] : []),
+        ...(hasClock ? ["import { clock } from './semantics/clock.ts';"] : []),
+        ...(hasTenant ? ["import { tenant } from './semantics/tenant.ts';"] : []),
+        ...(hasScenario ? ["import { scenario } from './semantics/scenario.ts';"] : []),
+        ...(hasGap ? ["import { gap } from './semantics/gap.ts';"] : []),
+        ...(hasSockets ? ["import * as sockets from './semantics/sockets.ts';"] : []),
+        ...(hasGraphql ? ["import { graphql } from './semantics/graphql.ts';", "import schema from './generated/graphql-sdl.gen.json' with { type: 'json' };", "import graphqlSurface from './generated/graphql.gen.json' with { type: 'json' };"] : []),
+        ...(hasDoors ? ["import * as doors from './semantics/doors.ts';"] : []),
+        ...(map ? [`import { ${map} } from './semantics/index.ts';`] : []),
+        ...screens.map((f) => `import { screen as ${identifier(`screen_${id(f)}`)} } from './screens/${f}';`),
+        ...laneImports,
+        '',
+        `export function ${name}(options: PackFetchOptions = {}): DerivedFetch {`,
+        '  return createPackFetch({',
+        '    manifest,',
+        commandSurface ? '    surface: surface as unknown as DerivedSurface,' : '    surface: surface as DerivedSurface,',
+        ...(map ? [`    handlers: ${map},`] : []),
+        ...(hasDoors ? ['    doors,'] : []),
+        ...(hasAround ? ['    around,'] : []),
+        ...(hasBoard ? ['    board,'] : []),
+        ...(hasClock ? ['    clock,'] : []),
+        ...(hasTenant ? ['    tenant,'] : []),
+        ...(hasScenario ? ['    scenario,'] : []),
+        ...(hasGap ? ['    gap,'] : []),
+        ...(hasSockets ? ['    sockets,'] : []),
+        ...(hasGraphql ? ['    graphql: { ...graphql, operations: graphqlSurface.operations as NonNullable<typeof graphql.operations>, sdl: schema.sdl },'] : []),
+        ...(screens.length ? [`    screens: { ${screens.map((f) => `${JSON.stringify(id(f))}: ${identifier(`screen_${id(f)}`)}`).join(', ')} },`] : []),
+        ...(lanes.length ? [`    lanes: ${laneParts},`] : []),
+        '  }, options);',
+        '}',
+        '',
+    ].join('\n');
+}
+/** The vendored OpenAPI document's operations by operationId (other spec formats have no brief yet). */
+function specOperations(dir) {
+    const file = ['openapi.json.gz', 'openapi.json', 'openapi.yaml.gz', 'openapi.yaml'].map((f) => join(dir, 'spec', f)).find((p) => existsSync(p));
+    const out = new Map();
+    if (!file)
+        return out;
+    const bytes = readFileSync(file);
+    const text = (file.endsWith('.gz') ? gunzipSync(bytes) : bytes).toString('utf8');
+    const doc = (file.includes('.yaml') ? parseExactJson(JSON.stringify(parseYaml(text, { intAsBigInt: true }), (_, v) => typeof v === 'bigint' ? exactInteger(String(v)) : v)) : parseExactJson(text));
+    for (const [path, item] of Object.entries(doc.paths ?? {})) {
+        for (const [method, op] of Object.entries(item ?? {})) {
+            if (!op || typeof op !== 'object')
+                continue;
+            if (typeof op.operationId === 'string')
+                out.set(op.operationId, op);
+            // an operation without an operationId is derived as method_path; index it by that too
+            else
+                out.set(`${method.toLowerCase()}_${path.replace(/[^A-Za-z0-9]+/g, '_').replace(/^_|_$/g, '')}`, op);
+        }
+    }
+    out.components = doc.components;
+    return out;
+}
+const oneLine = (s) => String(s ?? '').replace(/\s+/g, ' ').trim();
+/** The author's brief: the operations left to write, by family, each with the spec's words. */
+export async function brief(unit) {
+    const dir = resolve(unit);
+    const surface = parseExactJson(readFileSync(join(dir, 'src', 'generated', 'surface.gen.json'), 'utf8'));
+    const { manifest } = (await import(__rewriteRelativeImportExtension(join(dir, 'src', 'manifest.ts'))));
+    const core = coreFor(manifest);
+    const written = new Set(families(dir).flatMap((f) => f.handlers));
+    const unmodeled = new Set(manifest.unmodeled ?? []);
+    const spec = specOperations(dir);
+    const components = spec.components;
+    const left = surface.operations.filter((o) => !core.owns(o) && !written.has(handlerName(o.id)));
+    const byFamily = new Map();
+    for (const o of left) {
+        const family = o.family ?? (o.path.split('/').filter((s) => s && !/^v\d/.test(s) && !s.startsWith('{'))[0] ?? 'operations').replace(/^\.well-known$/, 'well-known');
+        byFamily.set(family, [...(byFamily.get(family) ?? []), o]);
+    }
+    const lines = [`# ${unit}: the operations left to write`, '', `${left.length} of ${surface.operations.length} operations: the derived core does not serve them and no handler answers them yet${unmodeled.size ? ` (${[...unmodeled].filter((id) => left.some((o) => o.id === id)).length} of them named unmodeled)` : ''}. Each handler goes in \`src/semantics/<family>.ts\`, named as its operation, under the handler contract; every rule it writes cites the spec or a page beside it (\`// source:\`).`, ''];
+    for (const [family, ops] of [...byFamily].sort(([a], [b]) => a.localeCompare(b))) {
+        lines.push(`## ${family}`, '');
+        for (const o of ops) {
+            const s = spec.get(o.id);
+            lines.push(`### ${o.id}${unmodeled.has(o.id) ? ' (unmodeled)' : ''}`, '', `\`${o.method.toUpperCase()} ${o.path}\` — ${o.class}${s?.summary ? `: ${oneLine(s.summary)}` : ''}`);
+            // the citation a handler carries, ready to paste: by operationId where the spec names one, else by its JSON pointer,
+            // quoting the spec's own words (derive-pack refuses a quote the spec does not hold)
+            const words = oneLine(s?.summary ?? s?.description ?? '').split(/(?<=\.)\s/)[0].replace(/"/g, '\\"');
+            const cite = s && s.operationId === o.id ? `spec:${o.id}` : `spec:/paths/${o.path.replace(/~/g, '~0').replace(/\//g, '~1')}/${o.method.toLowerCase()}`;
+            if (words)
+                lines.push('', `Cite: \`// source: ${cite} "${words}"\``);
+            if (s?.description)
+                lines.push('', `> ${oneLine(s.description)}`);
+            const params = [...o.query ?? [], ...(o.body ?? [])];
+            if (params.length)
+                lines.push('', `Parameters: ${params.map((p) => `\`${p.name}\`${p.required ? ' (required)' : ''}`).join(', ')}`);
+            const answers = Object.entries(s?.responses ?? {}).map(([status, r]) => {
+                const ref = r.$ref;
+                const described = ref ? components?.responses?.[ref.split('/').at(-1)]?.description ?? ref.split('/').at(-1) : r.description;
+                return `\`${status}\` ${oneLine(described)}`;
+            });
+            if (answers.length)
+                lines.push('', `Documented answers: ${answers.join('; ')}`);
+            lines.push('');
+        }
+    }
+    return lines.join('\n');
+}
+/** A pack's `src/index.ts` (a fixed file): the descriptor registered with what the kernel derives from the pack's
+ *  generated surface (the real-system adapters), or, for a vendor whose every API is a lane, each lane's manifest and
+ *  surface. A lane's own index is not a pack's and is not written here. */
+export function packIndexFile(dir, vendor) {
+    const Name = pascal(vendor);
+    const lanes = readdirSync(dir).filter((n) => existsSync(join(dir, n, 'src', 'manifest.ts'))).sort();
+    const hasGraphql = existsSync(join(dir, 'src', 'generated', 'graphql-sdl.gen.json'));
+    const gqlLanes = new Set(lanes.filter((l) => existsSync(join(dir, l, 'src', 'generated', 'graphql-sdl.gen.json'))));
+    const laneSurface = (l) => gqlLanes.has(l) ? `{ ...${id(l)}Surface, graphql: { sdl: ${id(l)}Schema.sdl } }` : `${id(l)}Surface`;
+    const lanesOnly = lanes.length > 0 && !hasOwnSurface(dir);
+    const id = (l) => l.replace(/[^A-Za-z0-9]/g, '_');
+    // a unit with no generated surface (a gRPC one's is proto.gen.json) has nothing to derive the vendor-backed half from
+    if (!lanesOnly && !existsSync(join(dir, 'src', 'generated', 'surface.gen.json')))
+        return initFiles(vendor)['src/index.ts'];
+    if (lanes.some((l) => !existsSync(join(dir, l, 'src', 'generated', 'surface.gen.json'))))
+        return initFiles(vendor)['src/index.ts'];
+    return [
+        `// @volter/twin-${vendor} — the ${vendor} twin (Protocol 3). A fixed file (create-pack): the descriptor is the manifest's, and the`,
+        `// kernel derives the vendor-backed half from the generated surface, unless the manifest declares none (vendorBacked.none;`,
+        `// architecture, "The real-system adapters").`,
+        `import { packOf, registerPack, type DerivedSurface } from '@volter/world-core';`,
+        `import { manifest } from './manifest.ts';`,
+        ...lanes.flatMap((l) => [`import { manifest as ${id(l)}Manifest } from '../${l}/src/manifest.ts';`, `import ${id(l)}Surface from '../${l}/src/generated/surface.gen.json' with { type: 'json' };`, ...(gqlLanes.has(l) ? [`import ${id(l)}Schema from '../${l}/src/generated/graphql-sdl.gen.json' with { type: 'json' };`] : [])]),
+        ...(lanesOnly ? [] : [`import surface from './generated/surface.gen.json' with { type: 'json' };`]),
+        ...(hasGraphql ? [`import schema from './generated/graphql-sdl.gen.json' with { type: 'json' };`] : []),
+        '',
+        `export { create${Name}Fetch } from './fetch.ts';`,
+        `export { create${Name}TwinServer } from './server.ts';`,
+        ...(existsSync(join(dir, 'src', 'stream.ts')) ? [`export { create${Name}TwinStream } from './stream.ts';`] : []),
+        ...(existsSync(join(dir, 'src', 'semantics', 'answer-views.ts')) ? [`export { answerViews } from './semantics/answer-views.ts';`] : []),
+        'export { manifest };',
+        '',
+        lanesOnly
+            ? `export const pack = registerPack(packOf(manifest, { ${lanes.map((l) => `${JSON.stringify(l)}: { manifest: ${id(l)}Manifest, surface: ${laneSurface(l)} as unknown as DerivedSurface }`).join(', ')} }));`
+            : lanes.length
+                // an API of its own with lanes beside it (Clerk's Frontend API): one state system over all of them
+                ? `export const pack = registerPack(packOf(manifest, ${hasGraphql ? '{ ...surface, graphql: { sdl: schema.sdl } }' : 'surface'} as unknown as DerivedSurface, { ${lanes.map((l) => `${JSON.stringify(l)}: { manifest: ${id(l)}Manifest, surface: ${laneSurface(l)} as unknown as DerivedSurface }`).join(', ')} }));`
+                : `export const pack = registerPack(packOf(manifest, ${hasGraphql ? '{ ...surface, graphql: { sdl: schema.sdl } }' : 'surface'} as unknown as DerivedSurface));`,
+        '',
+    ].join('\n');
+}
+/** A pack's `src/server.ts` (a fixed file), the kernel's serve seam around its fetch, naming only what its unit has so
+ *  it typechecks and a bundler follows every import: the plain seam (serveHttp, which takes the sockets a fetch carries
+ *  itself: "Other wires"), or, for a unit whose spec is a proto, the gRPC seam over the schema derive-pack generated
+ *  (src/generated/proto.gen.json, imported by its literal path). `--init` writes the plain one, `--index` the gRPC one once
+ *  the unit's proto is derived. */
+export function serverFile(vendor, grpc) {
+    const Name = pascal(vendor);
+    const head = `// FETCH-FIRST (runtime contract R12b): a fixed file, the kernel's serve seam around the pack's fetch (./fetch.ts).\n`;
+    const signature = `export async function create${Name}TwinServer(options: PackFetchOptions & { port?: number } = {}): Promise<{ port: number; stop: () => void }> {\n`;
+    if (grpc) {
+        return `${head}import { grpc, type PackFetchOptions } from '@volter/world-core';\nimport schema from './generated/proto.gen.json' with { type: 'json' };\nimport { create${Name}Fetch } from './fetch.ts';\n\n${signature}  const fetch = create${Name}Fetch(options);\n  // the vendor speaks gRPC (its manifest's \`grpc\`): HTTP/2 and HTTP/1 on one port, each rpc through the fetch\n  return grpc.serveGrpc({ ...(options.port ? { port: options.port } : {}), fetch: async (r) => fetch(r), schema: schema as unknown as Parameters<typeof grpc.serveGrpc>[0]['schema'] });\n}\n`;
+    }
+    return `${head}import { serveHttp, type PackFetchOptions } from '@volter/world-core';\nimport { create${Name}Fetch } from './fetch.ts';\n\n${signature}  const server = await serveHttp({ port: options.port ?? 0, idleTimeout: 60, fetch: create${Name}Fetch(options) });\n  return { port: server.port ?? options.port ?? 0, stop: () => server.stop(true) };\n}\n`;
+}
+/** A vendor id as a name in code: `npm-registry` is `NpmRegistry`. */
+const pascal = (vendor) => vendor.split(/[^A-Za-z0-9]+/).filter(Boolean).map((w) => w[0].toUpperCase() + w.slice(1)).join('');
+/** A pack's tsconfig.json, a fixed file: what the grade's typecheck (soundness) compiles, the pack and its lanes. */
+export const TSCONFIG = `${JSON.stringify({
+    compilerOptions: { target: 'ES2022', module: 'ESNext', moduleResolution: 'bundler', allowImportingTsExtensions: true, resolveJsonModule: true, jsx: 'react-jsx', strict: true, skipLibCheck: true, types: ['node', 'bun'], noEmit: true },
+    include: ['**/src/**/*.ts', '**/src/**/*.tsx'],
+    exclude: ['node_modules'],
+}, null, 2)}\n`;
+/** The fixed files of a new pack, by path, for a vendor: what nobody should write by hand. */
+export function initFiles(vendor) {
+    const Name = pascal(vendor);
+    const semantics = `${Name[0].toLowerCase()}${Name.slice(1)}Semantics`;
+    return {
+        'package.json': `${JSON.stringify({
+            name: `@volter/twin-${vendor}`, version: '1.0.0', description: `The ${vendor} twin (Protocol 3).`, author: 'Volter (https://github.com/volter-ai)', license: 'Apache-2.0',
+            type: 'module', exports: { '.': './src/index.ts' }, bin: { [`world-${vendor}`]: 'src/cli.ts' }, files: ['src', 'journeys', 'spec', 'README.md', '!**/*.test.ts'],
+            peerDependencies: { '@volter/world-core': '*' }, engines: { node: '>=22.3' },
+        }, null, 2)}\n`,
+        'tsconfig.json': TSCONFIG,
+        'README.md': `# @volter/twin-${vendor}\n\nThe ${vendor} twin (Protocol 3). Its surface is derived from the vendor's spec (\`spec/\`, provenance in\n\`spec/SOURCE.md\`); what it serves and why is its manifest and semantics.\n\nRules, layout and tools: twin-world's architecture ("Protocol 3", "The catalog: where twins come from").\n`,
+        'journeys/demand.json': `${JSON.stringify({ measured: 'FILL: when and how the applications were read', applications: [] }, null, 1)}\n`,
+        'src/semantics/states.ts': `// ${vendor}'s state machines and state rulings, each transition cited (architecture, "State").\nexport const states = {};\n`,
+        'src/semantics/shared.ts': `// What every family of ${vendor} shares: its stored shapes, who is calling, and the vendor's answers.\nimport type { HandlerContext } from '@volter/world-core';\n\nexport type Row = Record<string, unknown>;\nexport type { HandlerContext };\n`,
+        'src/semantics/doors.ts': `// The World's doors (architecture, "Doors, screens and the gap"): what the vendor's own pages do that its API does\n// not, each declared in the manifest's \`doors\` (its id, method and path under \`/_twin/\`) and answered here by the\n// export its id names, over the contract's context.\nimport type { HandlerContext } from '@volter/world-core';\n\nexport type { HandlerContext };\n`,
+        'src/manifest.ts': `// ${vendor}'s manifest: the vendor facts its spec does not carry (architecture, "Protocol 3"). The surface is generated\n// (./generated/surface.gen.json, from ../spec by derive-pack). Every line marked FILL is a vendor fact to state from\n// the vendor's pages, cited.\nimport type { DerivedManifest } from '@volter/world-core';\n\nexport const manifest: DerivedManifest = {\n  vendor: '${vendor}',\n  service: '${vendor}',\n  body: { json: 'always' },\n  ids: { template: '{uuid}' }, // FILL: the vendor's id form\n  time: 'iso', // FILL: iso, unix or unix-ms\n  error: { error: { message: '{message}', code: '{code}' } }, // FILL: the vendor's error body\n  readOnly: { status: 403, message: 'This twin was started read-only; writes are refused.' }, // FILL: the vendor's refusal\n  notFound: { status: 404, message: 'Not found' }, // FILL: the vendor's not-found\n  list: { style: 'envelope', envelope: { data: '{data}' }, limit: { param: 'limit', default: 20, max: 100 } }, // FILL: its paging\n  deleted: {},\n  resources: {}, // FILL: the resources the core serves (plain create, read, update, delete, list)\n  discovery: { twinOf: 'FILL: what the twin is of', stores: 'FILL: what it keeps' },\n  // the descriptor, as data (twin-world's architecture, "The descriptor"): the pack registers packOf(manifest)\n  descriptor: {\n    protocol: '3',\n    transport: 'rest',\n    archetype: 'crud',\n    bin: 'world-${vendor}',\n    resources: [], // FILL: the stored types\n    specSource: 'FILL: the vendored spec (spec/SOURCE.md)',\n    description: 'FILL: one line',\n    adoption: { sdks: [], envStems: [] }, // FILL: its npm clients, and each credential variable's stem (TRIPO for TRIPO_API_KEY: the suffix removed)\n    hosts: [], // FILL: the vendor's hosts\n    endpointEnvNone: 'FILL: the SDK\\'s base-URL variable (endpointEnv) or why none',\n  },\n};\n`,
+        'src/server.ts': serverFile(vendor, false),
+        'src/cli.ts': `#!/usr/bin/env node\n// world-${vendor}: serve the ${vendor} twin.\nimport { hasFlag, optionValue } from '@volter/world-core/args';\nimport { keepProcessAlive } from '@volter/world-core/lifecycle';\nimport { create${Name}TwinServer } from './server.ts';\n\nconst [cmd, ...rest] = process.argv.slice(2);\nconst port = Number(optionValue(rest, '--port', '0')) || undefined;\nconst root = optionValue(rest, '--root') || undefined;\nconst readOnly = hasFlag(rest, '--read-only');\n// the World's managed Postgres, which the runtime binds a pack declaring managedDatabase to\nconst database = optionValue(rest, '--database') || undefined;\n// the World's scenario file, for a model vendor's turns\nconst scenarioPath = optionValue(rest, '--scenario') || undefined;\n\nif (cmd === 'serve' || cmd === undefined) {\n  const s = await create${Name}TwinServer({ readOnly, ...(root ? { root } : {}), ...(port ? { port } : {}), ...(database ? { database } : {}), ...(scenarioPath ? { scenarioPath } : {}) });\n  process.stdout.write(\`${vendor} twin\${readOnly ? ' [read-only]' : ''} at http://127.0.0.1:\${s.port}\\n\`);\n  await keepProcessAlive();\n} else {\n  process.stdout.write('Usage: world-${vendor} serve [--port N] [--root DIR] [--read-only] [--database URL] [--scenario FILE]\\n');\n}\n`,
+        'src/index.ts': `// @volter/twin-${vendor} — the ${vendor} twin (Protocol 3). A fixed file: the descriptor is the manifest's.\nimport { packOf, registerPack } from '@volter/world-core';\nimport { manifest } from './manifest.ts';\n\nexport { create${Name}Fetch } from './fetch.ts';\nexport { create${Name}TwinServer } from './server.ts';\nexport { manifest };\n\n// The descriptor: twin-world's architecture, "The descriptor"; declared in manifest.ts.\nexport const pack = registerPack(packOf(manifest));\n`,
+    };
+}
+/** The fixed files of a pack of lanes (Cloudflare's API and R2, Sigstore's Fulcio and Rekor): each lane a derived
+ *  surface of its own under `<lane>/src`, keeping the vendor's one store and sharing its `src/semantics/shared.ts`, and the
+ *  pack's server routing each lane's host to it. */
+export function laneInitFiles(vendor, lanes) {
+    const Name = pascal(vendor);
+    const camel = (s) => { const p = pascal(s); return `${p[0].toLowerCase()}${p.slice(1)}`; };
+    const single = initFiles(vendor);
+    const files = {
+        'package.json': single['package.json'].replace('"spec",', lanes.map((l) => `"${l}",`).join('\n    ')),
+        'README.md': `# @volter/twin-${vendor}\n\nThe ${vendor} twin (Protocol 3), one lane per API: ${lanes.map((l) => `\`${l}/\``).join(', ')}, each derived from its own spec\n(\`<lane>/spec/\`, provenance in its SOURCE.md). FILL: what each lane is of.\n`,
+        'journeys/demand.json': single['journeys/demand.json'],
+        'tsconfig.json': TSCONFIG,
+        // the vendor's front, as data: its lanes and how its gateway routes them, its discovery facts, its descriptor. The
+        // kernel serves it (createVendorFetch, from the generated fetch.ts); nothing routes by hand
+        'src/manifest.ts': [
+            `// ${vendor}'s manifest: a vendor whose every API is a lane (architecture, "Other wires: lanes"). The kernel sends a`,
+            `// request to the lane whose manifest declares its /_twin/ door, else to the first route whose conditions hold, else to`,
+            `// the default lane. Every line marked FILL is a vendor fact to state from the vendor's pages, cited.`,
+            `import type { VendorManifest } from '@volter/world-core';`,
+            ``,
+            `export const manifest: VendorManifest = {`,
+            `  vendor: '${vendor}',`,
+            `  discovery: { twinOf: 'FILL: what the twin is of', stores: 'FILL: what it keeps' },`,
+            `  lanes: {`,
+            `    // FILL: each lane's host (a regular expression), path prefix or header, as the vendor's clients reach it`,
+            `    routes: [${lanes.map((l) => `{ lane: ${JSON.stringify(l)}, host: 'FILL' }`).join(', ')}],`,
+            `  },`,
+            `  descriptor: {`,
+            `    protocol: '3',`,
+            `    transport: 'rest',`,
+            `    archetype: 'crud',`,
+            `    bin: 'world-${vendor}',`,
+            `    resources: [], // FILL: the stored types`,
+            `    specSource: 'FILL: each lane\\'s vendored spec (<lane>/spec/SOURCE.md)',`,
+            `    description: 'FILL: one line',`,
+            `    adoption: { sdks: [], envStems: [] }, // FILL`,
+            `    hosts: [], // FILL: every lane's hosts`,
+            `    endpointEnvNone: 'FILL: the SDK\\'s base-URL variable (endpointEnv) or why none',`,
+            `  },`,
+            `};`,
+            ``,
+        ].join('\n'),
+        'src/semantics/shared.ts': single['src/semantics/shared.ts'].replace(`What every family of ${vendor} shares`, `What every lane of ${vendor} shares`),
+        'src/server.ts': serverFile(vendor, false),
+        'src/cli.ts': single['src/cli.ts'],
+        'src/index.ts': single['src/index.ts'],
+    };
+    for (const lane of lanes) {
+        const L = pascal(lane);
+        const one = initFiles(lane);
+        // every lane keeps the vendor's one store (its manifest names the vendor's service); a lane that is an independent
+        // service of its own (Sigstore's Fulcio and Rekor) names `<vendor>-<lane>` instead, by the author's ruling
+        files[`${lane}/src/manifest.ts`] = one['src/manifest.ts'].replace(`// ${lane}'s manifest:`, `// The ${lane} lane's manifest:`).replace(`vendor: '${lane}'`, `vendor: '${vendor}'`).replace(`service: '${lane}'`, `service: '${vendor}'`);
+        files[`${lane}/src/semantics/states.ts`] = one['src/semantics/states.ts'];
+        // what the lanes share is the vendor's (src/semantics/shared.ts); each lane's shared.ts re-exports it
+        files[`${lane}/src/semantics/shared.ts`] = `// What the ${lane} lane shares: the vendor's (../../../src/semantics/shared.ts).\nexport * from '../../../src/semantics/shared.ts';\n`;
+        files[`${lane}/src/index.ts`] = `// The ${lane} lane of the ${vendor} pack: the vendor's manifest routes its requests here.\nexport { create${L}LaneFetch } from './fetch.ts';\nexport { manifest } from './manifest.ts';\n`;
+    }
+    return files;
+}
+export async function createPack(args) {
+    const [unit, ...rest] = args;
+    if (!unit || (!rest.includes('--index') && !rest.includes('--brief') && !rest.includes('--init'))) {
+        console.error('usage: bun scripts/create-pack.ts <dir> --init <vendor> | <unit> --index | --brief [--out <file>]');
+        process.exit(2);
+    }
+    const dir = resolve(unit);
+    if (rest.includes('--init')) {
+        const vendor = rest[rest.indexOf('--init') + 1];
+        if (!vendor || !/^[a-z0-9-]+$/.test(vendor)) {
+            console.error('create-pack --init: name the vendor id ([a-z0-9-]+)');
+            process.exit(2);
+        }
+        const lanesArg = rest.includes('--lanes') ? String(rest[rest.indexOf('--lanes') + 1] ?? '').split(',').filter(Boolean) : [];
+        if (lanesArg.some((l) => !/^[a-z0-9-]+$/.test(l))) {
+            console.error('create-pack --init --lanes: each lane an id ([a-z0-9-]+)');
+            process.exit(2);
+        }
+        for (const [rel, text] of Object.entries(lanesArg.length ? laneInitFiles(vendor, lanesArg) : initFiles(vendor))) {
+            const path = join(dir, rel);
+            if (existsSync(path)) {
+                console.log(`create-pack: kept ${rel}`);
+                continue;
+            }
+            mkdirSync(dirname(path), { recursive: true });
+            writeFileSync(path, text);
+            console.log(`create-pack: wrote ${rel}`);
+        }
+        if (rest.includes('--package')) {
+            const name = rest[rest.indexOf('--package') + 1];
+            if (!name || !/^@[a-z0-9][a-z0-9._-]*\/[a-z0-9][a-z0-9._-]*$/.test(name))
+                throw new Error('--package needs a scoped npm name');
+            const file = join(dir, 'package.json');
+            const pkg = JSON.parse(readFileSync(file, 'utf8'));
+            pkg.name = name;
+            delete pkg.author;
+            pkg.files = [...new Set([...pkg.files, 'generated', 'LICENSE'])];
+            writeFileSync(file, `${JSON.stringify(pkg, null, 2)}\n`);
+        }
+        // the package's licence, the platform's (Apache-2.0), as every published pack carries it
+        const licence = join(dir, 'LICENSE');
+        if (!existsSync(licence)) {
+            writeFileSync(licence, readFileSync(new URL('../LICENSE', import.meta.url)));
+            console.log('create-pack: wrote LICENSE');
+        }
+        // the handler map each fetch imports, empty until the families are written (--index again then)
+        for (const at of lanesArg.length ? [...lanesArg.map((l) => join(dir, l)), dir] : [dir]) {
+            if (at === dir && lanesArg.length) {
+                const f = join(dir, 'src', 'fetch.ts');
+                if (!existsSync(f)) {
+                    writeFileSync(f, packFetchFile(dir, fetchName(dir)));
+                    console.log('create-pack: wrote src/fetch.ts');
+                }
+                continue;
+            }
+            const index = join(at, 'src', 'semantics', 'index.ts');
+            if (!existsSync(index)) {
+                mkdirSync(dirname(index), { recursive: true });
+                writeFileSync(index, handlerIndex(at));
+                console.log(`create-pack: wrote ${relative(dir, index)}`);
+            }
+            const fetchPath = join(at, 'src', 'fetch.ts');
+            if (!existsSync(fetchPath)) {
+                writeFileSync(fetchPath, packFetchFile(at, fetchName(at)));
+                console.log(`create-pack: wrote ${relative(dir, fetchPath)}`);
+            }
+        }
+    }
+    if (rest.includes('--index')) {
+        // a vendor whose every API is a lane has no handlers of its own: only its fetch
+        const lanesOnly = !hasOwnSurface(dir) && readdirSync(dir).some((n) => existsSync(join(dir, n, 'src', 'manifest.ts')));
+        // the index maps the derived surface's operations: before the derive there is none, so say what comes first
+        if (!lanesOnly && !existsSync(join(dir, 'src', 'generated', 'surface.gen.json'))) {
+            console.error(`create-pack --index: ${relative(process.cwd(), dir) || dir} has no src/generated/surface.gen.json yet: derive it first (twin-standard derive ${relative(process.cwd(), dir) || dir}), then --index`);
+            process.exit(2);
+        }
+        // a lane is served through its vendor's server.ts, which speaks HTTP: a lane whose spec is a proto has no seam that
+        // serves it over gRPC, so it is refused before anything is written, rather than served as plain HTTP (a gRPC API is a pack of its own)
+        if (!existsSync(join(dir, 'package.json')) && existsSync(join(dir, 'src', 'generated', 'proto.gen.json'))) {
+            console.error(`create-pack --index: ${relative(process.cwd(), dir) || dir} is a lane whose spec is a proto; its vendor's server.ts serves lanes over HTTP alone, so a gRPC API is a pack of its own (architecture, "Pack layout")`);
+            process.exit(1);
+        }
+        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')}`);
+        // 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 vendor = parseExactJson(readFileSync(join(dir, 'package.json'), 'utf8')).name.replace(/^@volter\/twin-/, '');
+            writeFileSync(join(dir, 'src', 'index.ts'), packIndexFile(dir, vendor));
+            console.log(`create-pack: wrote ${join(dir, 'src', 'index.ts')}`);
+            // what the grade's typecheck compiles: a pack made before init wrote it gets it here
+            if (!existsSync(join(dir, 'tsconfig.json'))) {
+                writeFileSync(join(dir, 'tsconfig.json'), TSCONFIG);
+                console.log(`create-pack: wrote ${join(dir, 'tsconfig.json')}`);
+            }
+            // 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));
+                console.log(`create-pack: wrote ${join(dir, 'src', 'server.ts')}`);
+            }
+        }
+        // a handler is an exported async function, one per operation (the handler contract); anything else a family file
+        // exports is not in the map, said at once rather than found by the grade
+        const semantics = join(dir, 'src', 'semantics');
+        // a family file exports handlers only: a helper it shares belongs in semantics/shared.ts, so the index refuses one
+        let odd = 0;
+        for (const f of existsSync(semantics) ? readdirSync(semantics).filter((n) => n.endsWith('.ts') && !n.endsWith('.test.ts') && !FIXED.has(n)) : []) {
+            const names = [...readFileSync(join(semantics, f), 'utf8').matchAll(/^export\s+(?:const|let|var|class|function)\s+([A-Za-z0-9_$]+)/gm)].map((m) => m[1]);
+            if (names.length) {
+                odd += 1;
+                console.error(`create-pack: ${f} exports ${names.join(', ')} otherwise than as an async function: a handler is \`export async function <name>(ctx: HandlerContext)\`, and a shared helper belongs in semantics/shared.ts`);
+            }
+        }
+        if (odd)
+            process.exit(1);
+        if (!lanesOnly) {
+            const problems = await decisionProblems(dir);
+            if (problems.length) {
+                console.error(`create-pack: ${basename(dir)}: ${problems.length} problem(s) with what the unit serves:\n  ${problems.join('\n  ')}`);
+                process.exit(1);
+            }
+        }
+    }
+    if (rest.includes('--brief')) {
+        const text = await brief(unit);
+        const at = rest.indexOf('--out');
+        if (at >= 0 && rest[at + 1]) {
+            writeFileSync(rest[at + 1], text);
+            console.log(`create-pack: wrote ${rest[at + 1]}`);
+        }
+        else
+            console.log(text);
+    }
+}

package/dist/src/index.d.ts

@@ -7,3 +7,6 @@ export { notIndependent, type Verdict } from './verdict.js';
 export { sharingLanesIn, hasOwnSurface } from './lanes.js';
 export { unitAt } from './unit.js';
 export type { Criterion, CriterionResult, GradeUnit, ScoreReport, Standard } from './types.js';
+export { compilePackFacts, renderPackFacts, type PackFacts, type PackFactsFile } from './pack-facts.js';
+export { assessPack, type AssessmentOptions } from './assessment.js';
+export { createPack } from './create-pack.js';

package/dist/src/index.js

@@ -11,3 +11,6 @@ export { handlerName, protocol3, PLANNED, withCheckoutFiles } from "./protocol-3
 export { notIndependent } from "./verdict.js";
 export { sharingLanesIn, hasOwnSurface } from "./lanes.js";
 export { unitAt } from "./unit.js";
+export { compilePackFacts, renderPackFacts } from "./pack-facts.js";
+export { assessPack } from "./assessment.js";
+export { createPack } from "./create-pack.js";