@volter/twin-standard 1.0.32 → 1.0.33

package/README.md

@@ -6,11 +6,15 @@ workflow, a release, and the twin catalog's check of a submitted version all run
 place a pack is judged judges it by the same standard.
 
 ```bash
+twin-standard create <dir> --init <vendor> --package <@scope/name>  # fixed files, in your repository
+twin-standard create <unit> --index                         # fixed handler map and fetch after derivation
 twin-standard gate <pack repository> [<pack or lane dir>…]   # every unit passes the form section, or exit 1
 twin-standard gate-published <name>@<version>… [--registry <url>]  # a published version, as the catalog grades a submission
 twin-standard grade <pack or lane dir>… [--static] [--form]  # each criterion's result
 twin-standard derive <pack or lane dir> [--out <dir>]        # write src/generated/ from the vendored spec
 twin-standard check-sources <pack or lane dir> [--recheck]   # fetch and record the sources the unit cites
+twin-standard facts <pack dir> [--out <file>]               # package-local facts from its descriptor
+twin-standard assess <pack dir> [--browser] [--out <file>]   # inside a World
 twin-standard --version                                      # this package's version and each standard's
 ```
 
@@ -18,3 +22,8 @@ What each criterion asks, and the rules for changing one, are twin-world's
 [architecture, "The grade"](https://github.com/volter-ai/twin-world/blob/main/docs/contributing/architecture.md#the-grade).
 A changed criterion is a release of this package: a criterion's id never changes meaning; a changed criterion takes a
 new id and a new standard version, and a tightened check names what newly fails.
+
+The public `assessPack(packDir, { browser: true })` API runs inside a World, reports actual operation coverage from
+kernel dispatch and replays journeys through Chromium when their wire is HTTP. Install Playwright and Chromium for
+that target. Its report distinguishes API support, operations exercised, journey failures and replay, and does not
+claim DOM interaction coverage. Catalog controllers own provenance, admission and publication.

package/dist/src/assessment.d.ts

@@ -0,0 +1,49 @@
+export type AssessmentOptions = {
+    browser?: boolean;
+    conformance?: boolean;
+};
+/** Surface coverage counts actual kernel dispatch, and retains every declared gap in the denominator. */
+export declare function assessPack(packDir: string, options?: AssessmentOptions): Promise<{
+    schemaVersion: number;
+    vendor: string;
+    package: any;
+    version: any;
+    ready: boolean;
+    gates: {
+        unit: string;
+        failures: string[];
+    }[];
+    quick: {
+        scope: string;
+        steps: number;
+        answered: number;
+        failures: {
+            step: string;
+            beat: string;
+            detail: string;
+        }[];
+        replay: {
+            equal: boolean;
+            runs: number;
+            firstSha256: string;
+            secondSha256: string;
+        };
+        operationCoverage: {
+            total: number;
+            exercised: number;
+            percent: number;
+            operations: string[];
+            missing: string[];
+        } | null;
+        servedOperations: string[];
+        surface: {
+            total: number;
+            served: number;
+            gap: number;
+        } | null;
+        codeCoverage: null;
+        stateTransitionCoverage: null;
+    };
+    browser: Record<string, unknown>;
+    conformance: import("./conformance.js").ConformanceResult[] | null;
+}>;

package/dist/src/assessment.js

@@ -0,0 +1,124 @@
+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;
+};
+// Published assessment API. The standard owns journeys and checks; catalog controllers own admission authority.
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { createHash } from 'node:crypto';
+import { observeDerivedDispatch } from '@volter/world-core/runtime';
+import { p3Gate } from "./gate.js";
+import { conformance } from "./conformance.js";
+import { inMemoryWorld, walk, withPinnedWorldDraws, usePacks } from "./walk/behavior-journey.js";
+import { compilePackFacts } from "./pack-facts.js";
+import { expandFills } from "./walk/journey-kit.js";
+const canonical = (value) => value && typeof value === 'object' ? Array.isArray(value) ? value.map(canonical) : Object.fromEntries(Object.entries(value).sort(([a], [b]) => a.localeCompare(b)).map(([key, item]) => [key, canonical(item)])) : value;
+const json = (value) => JSON.stringify(canonical(value));
+const hash = (value) => createHash('sha256').update(json(value)).digest('hex');
+const read = (file) => JSON.parse(readFileSync(file, 'utf8'));
+/** Surface coverage counts actual kernel dispatch, and retains every declared gap in the denominator. */
+export async function assessPack(packDir, options = {}) {
+    if (!process.env.VOLTER_WORLD)
+        throw new Error('Assessment must run inside a World');
+    const facts = read(join(packDir, 'generated/pack-facts.json'));
+    const vendor = Object.keys(facts.packs ?? {})[0];
+    if (!vendor || Object.keys(facts.packs).length !== 1)
+        throw new Error('Assessment needs one published vendor identity');
+    const manifest = read(join(packDir, 'package.json'));
+    const compiled = await compilePackFacts([{ vendor, dir: packDir }]);
+    if (json(compiled.packs) !== json(facts.packs) || compiled.undeclared.length)
+        throw new Error('Published facts differ from the pack descriptor');
+    const lanes = readdirSync(packDir).filter((name) => existsSync(join(packDir, name, 'src/manifest.ts')) && !existsSync(join(packDir, name, 'package.json')));
+    const units = [packDir, ...lanes.map((name) => join(packDir, name))];
+    if (packDir.split(/[\\/]/).at(-1) !== vendor)
+        throw new Error('Place the artifact in a directory named for its vendor before assessment');
+    usePacks(join(packDir, '..'));
+    const gates = await p3Gate(units);
+    const life = expandFills(read(join(packDir, 'journeys/customer-life.json')));
+    if (!Array.isArray(life.steps) || !life.steps.length)
+        throw new Error('Assessment needs a nonempty customer journey');
+    const surfaceRows = [];
+    for (const unit of units) {
+        const file = join(unit, 'src/generated/surface.gen.json');
+        if (!existsSync(file))
+            continue;
+        const surface = read(file);
+        if (!Array.isArray(surface.operations) || !surface.operations.length)
+            continue;
+        surfaceRows.push({ unit: unit === packDir ? vendor : `${vendor}/${unit.slice(packDir.length + 1)}`, signature: hash(surface.operations), ids: surface.operations.map((operation) => operation.id) });
+    }
+    const declaredHttp = [...new Set(surfaceRows.flatMap((row) => row.ids.map((id) => `${row.unit}:${id}`)))].sort();
+    const mod = await import(__rewriteRelativeImportExtension(join(packDir, 'src/index.ts')));
+    const factory = Object.entries(mod).find(([name, value]) => /^create\w+Fetch$/.test(name) && !/TwinFetch$/.test(name) && typeof value === 'function')?.[1];
+    const surfaceWorld = inMemoryWorld('catalog-surface');
+    let owners = null;
+    try {
+        const wire = factory?.({ root: surfaceWorld.root() });
+        if (wire?.ownersByUnit)
+            owners = Object.fromEntries(Object.entries(wire.ownersByUnit()).flatMap(([unit, operations]) => Object.entries(operations).map(([id, owner]) => [`${vendor}${unit ? `/${unit}` : ''}:${id}`, owner])));
+        else if (wire?.owners)
+            owners = Object.fromEntries(Object.entries(wire.owners()).map(([id, owner]) => [`${vendor}:${id}`, owner]));
+    }
+    finally {
+        surfaceWorld.restore();
+    }
+    const declared = owners ? Object.keys(owners).sort() : [];
+    const servedOperations = owners ? declared.filter((id) => owners[id] !== 'gap') : [];
+    const instrumented = declared.length > 0 && json(declared) === json(declaredHttp);
+    const coverageOf = (result) => !instrumented || result.ambiguous ? null : { total: declared.length, exercised: result.exercised.length, percent: 100 * result.exercised.length / declared.length, operations: result.exercised, missing: declared.filter((id) => !result.exercised.includes(id)) };
+    async function replay(served) {
+        const world = inMemoryWorld('catalog-replay');
+        const failures = [], trace = [];
+        const exercised = new Set();
+        const signatures = new WeakMap();
+        let ambiguous = false;
+        const stop = observeDerivedDispatch(({ surface, operation }) => {
+            let signature = signatures.get(surface.operations);
+            if (!signature) {
+                signature = hash(surface.operations);
+                signatures.set(surface.operations, signature);
+            }
+            const candidates = surfaceRows.filter((row) => row.signature === signature);
+            if (!candidates.length)
+                return; // Companion dispatch is outside this pack's denominator.
+            if (candidates.length !== 1) {
+                ambiguous = true;
+                return;
+            }
+            const id = `${candidates[0].unit}:${operation.id}`;
+            exercised.add(id);
+        });
+        try {
+            await withPinnedWorldDraws(() => walk(structuredClone(life), world.root(), failures, { beats: true, ...(served ? { served } : {}), hooks: { after: (step, path, answer) => trace.push({ name: step.name ?? '', path, status: answer.status, body: answer.body }) } }));
+            return { failures, trace, exercised: [...exercised].sort(), ambiguous };
+        }
+        finally {
+            stop();
+            world.restore();
+        }
+    }
+    const first = await replay(), second = await replay();
+    const replayEqual = first.trace.length > 0 && json(first.trace) === json(second.trace);
+    const coverage = coverageOf(first);
+    const quick = { scope: 'packaged-customer-journey; in-process', steps: life.steps.length, answered: first.trace.length, failures: [...first.failures, ...second.failures], replay: { equal: replayEqual, runs: 2, firstSha256: hash(first.trace), secondSha256: hash(second.trace) }, operationCoverage: coverage, servedOperations, surface: owners ? { total: declared.length, served: servedOperations.length, gap: declared.length - servedOperations.length } : null, codeCoverage: null, stateTransitionCoverage: null };
+    let browser = { measured: false, reason: options.browser ? 'Journey has a wire Chromium fetch cannot exercise' : 'Browser target not requested' };
+    const httpOnly = life.steps.every((step) => 'method' in step || 'wait' in step);
+    if (options.browser && httpOnly) {
+        const { chromiumServed } = await import("./browser-assessment.js");
+        const transport = await chromiumServed(packDir, life.host ?? 'twin.local');
+        try {
+            const a = await replay(transport.served), b = await replay(transport.served);
+            browser = { measured: true, target: 'Chromium fetch, cookie jar and HTTP response behavior; no DOM interaction coverage', version: transport.version, answered: a.trace.length, failures: [...a.failures, ...b.failures], replay: { equal: a.trace.length > 0 && json(a.trace) === json(b.trace), firstSha256: hash(a.trace), secondSha256: hash(b.trace), runs: 2 }, operationCoverage: coverageOf(a), domCoverage: null, clock: 'World and page JavaScript clocks frozen; native cookie expiration uses Chromium wall time' };
+        }
+        finally {
+            await transport.stop();
+        }
+    }
+    const conform = options.conformance === false ? null : await conformance(packDir);
+    const ready = gates.length > 0 && gates.every((gate) => !gate.failures.length) && !quick.failures.length && replayEqual && conform !== null && conform.length > 0 && conform.every((result) => !result.failures.length) && (!options.browser || !httpOnly || browser.measured === true && browser.failures.length === 0 && browser.replay.equal);
+    return { schemaVersion: 1, vendor, package: manifest.name, version: manifest.version, ready, gates: gates.map((gate) => ({ ...gate, unit: gate.unit === packDir ? vendor : `${vendor}/${gate.unit.slice(packDir.length + 1)}` })), quick, browser, conformance: conform };
+}

package/dist/src/browser-assessment.d.ts

@@ -0,0 +1,6 @@
+import type { ServedTwin } from './walk/behavior-journey.js';
+export declare function chromiumServed(packDir: string, host: string): Promise<{
+    served: ServedTwin;
+    version: string;
+    stop: () => Promise<void>;
+}>;

package/dist/src/browser-assessment.js

@@ -0,0 +1,69 @@
+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;
+};
+// Browser transport for the existing journey engine. A container supplies network isolation in catalog execution.
+import { join } from 'node:path';
+export async function chromiumServed(packDir, host) {
+    const { chromium } = await import('playwright');
+    const browser = await chromium.launch({ args: ['--no-sandbox'] });
+    const mod = await import(__rewriteRelativeImportExtension(join(packDir, 'src/index.ts')));
+    const factory = Object.entries(mod).find(([name, value]) => /^create\w+Fetch$/.test(name) && !/TwinFetch$/.test(name) && typeof value === 'function')?.[1];
+    if (!factory) {
+        await browser.close();
+        throw new Error('Browser assessment needs the pack HTTP fetch factory');
+    }
+    const served = async (root, options) => {
+        const fetchPack = factory({ root, ...options });
+        const context = await browser.newContext({ serviceWorkers: 'block', locale: 'en-US', timezoneId: 'UTC' });
+        const page = await context.newPage();
+        const harness = `https://${host}/__catalog_assessment__`;
+        await context.route('**/*', async (route) => {
+            const request = route.request();
+            if (request.url() === harness) {
+                await route.fulfill({ status: 200, contentType: 'text/html', body: '<!doctype html><title>Catalog assessment</title>' });
+                return;
+            }
+            if (!['xhr', 'fetch'].includes(request.resourceType())) {
+                await route.abort('blockedbyclient');
+                return;
+            }
+            try {
+                const response = await fetchPack(new Request(request.url(), { method: request.method(), headers: request.headers(), ...(request.postDataBuffer() ? { body: new Uint8Array(request.postDataBuffer()).buffer } : {}) }));
+                const headers = Object.fromEntries(response.headers);
+                const cookies = response.headers.getSetCookie();
+                if (cookies.length)
+                    headers['set-cookie'] = cookies.join('\n');
+                await route.fulfill({ status: response.status, headers, body: Buffer.from(await response.arrayBuffer()) });
+            }
+            catch {
+                await route.abort('failed');
+            }
+        });
+        await page.goto(harness);
+        await page.clock.setFixedTime(new Date('2026-01-01T00:00:00.000Z'));
+        return {
+            fetch: async (request) => {
+                const body = request.body ? Buffer.from(await request.arrayBuffer()).toString('base64') : null;
+                const result = await page.evaluate(async ({ url, method, headers, body }) => {
+                    const bytes = body === null ? undefined : Uint8Array.from(atob(body), (char) => char.charCodeAt(0));
+                    const response = await fetch(url, { method, headers, body: bytes, redirect: 'manual', credentials: 'include' });
+                    const data = new Uint8Array(await response.arrayBuffer());
+                    let text = '';
+                    for (let i = 0; i < data.length; i += 32768)
+                        text += String.fromCharCode(...data.subarray(i, i + 32768));
+                    return { status: response.status, headers: [...response.headers], body: btoa(text) };
+                }, { url: request.url, method: request.method, headers: Object.fromEntries(request.headers), body });
+                if (!result.status)
+                    throw new Error('Chromium returned an opaque response; this journey needs browser-specific navigation assertions');
+                return new Response([101, 204, 205, 304].includes(result.status) || request.method === 'HEAD' ? null : Buffer.from(result.body, 'base64'), { status: result.status, headers: result.headers });
+            },
+            stop: () => { void context.close(); },
+        };
+    };
+    return { served, version: browser.version(), stop: () => browser.close() };
+}

package/dist/src/cli.js

@@ -1,4 +1,12 @@
 #!/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;
+};
 // twin-standard — the Protocol 3 standard's commands, the same wherever they run (a pack repository's hook and workflow,
 // a release, the catalog's check of a submission, an author's machine):
 //
@@ -22,7 +30,7 @@ import { withCheckoutFiles } from "./protocol-3.js";
 import { gatePublished } from "./published.js";
 const [command, ...args] = process.argv.slice(2);
 const usage = () => {
-    console.error('usage: twin-standard gate <repo> [units…] | gate-published <name>@<version>… [--registry <url>] | grade <unit>… [--static] [--form] | derive <unit> [--out <dir>] | read-page <url> [--raw] | check-sources <unit> [--recheck] | conform <pack dir> | <name>@<version> [--registry <url>] | --version');
+    console.error('usage: twin-standard gate <repo> [units…] | gate-published <name>@<version>… [--registry <url>] | grade <unit>… [--static] [--form] | derive <unit> [--out <dir>] | read-page <url> [--raw] | check-sources <unit> [--recheck] | conform <pack dir> | <name>@<version> [--registry <url>] | create <dir> --init <vendor> --package <@scope/name> | create <unit> --index | facts <pack dir> [--out <file>] | assess <pack dir> [--browser] [--out <file>] | --version');
     process.exit(2);
 };
 if (command === '--version') {
@@ -95,6 +103,46 @@ else if (command === 'grade') {
         }
     });
 }
+else if (command === 'create') {
+    if (args.includes('--init') && !args.includes('--package'))
+        throw new Error('Name your scoped package with --package');
+    await (await import("./create-pack.js")).createPack(args);
+}
+else if (command === 'assess') {
+    if (!args[0])
+        usage();
+    const { assessPack } = await import("./assessment.js");
+    const report = await assessPack(resolve(args[0]), { browser: args.includes('--browser') });
+    const at = args.indexOf('--out');
+    if (at >= 0) {
+        if (!args[at + 1])
+            usage();
+        const { writeFileSync } = await import('node:fs');
+        writeFileSync(resolve(args[at + 1]), `${JSON.stringify(report, null, 2)}\n`);
+    }
+    else
+        console.log(JSON.stringify(report, null, 2));
+    process.exit(report.ready ? 0 : 1);
+}
+else if (command === 'facts') {
+    if (!args[0])
+        usage();
+    const { compilePackFacts, renderPackFacts } = await import("./pack-facts.js");
+    const { mkdirSync, writeFileSync } = await import('node:fs');
+    const { join, dirname } = await import('node:path');
+    const dir = resolve(args[0]);
+    const vendor = String((await import(__rewriteRelativeImportExtension(join(dir, 'src/index.ts')))).pack?.vendor ?? '');
+    const at = args.indexOf('--out');
+    if (at >= 0 && !args[at + 1])
+        usage();
+    const out = at >= 0 ? resolve(args[at + 1]) : join(dir, 'generated/pack-facts.json');
+    const facts = await compilePackFacts([{ vendor, dir }]);
+    if (facts.undeclared.length)
+        throw new Error('Pack descriptor is missing');
+    mkdirSync(dirname(out), { recursive: true });
+    writeFileSync(out, renderPackFacts(facts));
+    console.log(out);
+}
 else if (command === 'derive') {
     if (!args[0])
         usage();

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

@@ -0,0 +1,38 @@
+#!/usr/bin/env bun
+/** 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 declare function handlerIndex(dir: string): string;
+/** 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 declare function decisionProblems(dir: string): Promise<string[]>;
+/** 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 declare const fetchName: (dir: string) => string;
+export declare function packFetchFile(dir: string, name: string): string;
+/** The author's brief: the operations left to write, by family, each with the spec's words. */
+export declare function brief(unit: string): Promise<string>;
+/** 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 declare function packIndexFile(dir: string, vendor: string): string;
+/** 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 declare function serverFile(vendor: string, grpc: boolean): string;
+/** A pack's tsconfig.json, a fixed file: what the grade's typecheck (soundness) compiles, the pack and its lanes. */
+export declare const TSCONFIG: string;
+/** The fixed files of a new pack, by path, for a vendor: what nobody should write by hand. */
+export declare function initFiles(vendor: string): Record<string, string>;
+/** 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 declare function laneInitFiles(vendor: string, lanes: string[]): Record<string, string>;
+export declare function createPack(args: string[]): Promise<void>;