@volter/twin-standard 1.0.32 → 1.0.34

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

@@ -0,0 +1,117 @@
+export type PackFacts = {
+    /** Explicit vendor-server backing; this entry declares no pack protocol or factory. */
+    serverBacking?: {
+        command: string;
+    };
+    maxRequestBodySize?: number;
+    adoption?: {
+        sdks?: string[];
+        pypi?: string[];
+        scopes?: string[];
+        envStems?: string[];
+        worldIds?: string[];
+        tools?: Array<{
+            package: string;
+            usage: 'build' | 'deployment';
+        }>;
+        configFiles?: Array<{
+            file: string;
+            usage: 'application' | 'build' | 'deployment';
+            when?: string;
+        }>;
+    };
+    hosts?: Array<{
+        host?: string;
+        suffix?: string;
+        hostPattern?: string;
+        pathPattern?: string;
+        demandPathPattern?: string | false;
+        key?: string;
+        exclude?: true;
+    }>;
+    hostsNone?: string;
+    hostsClaimed?: {
+        door: string;
+        note: string;
+    };
+    /** The subject types the twin projects (packRegistry `resources`) — invariant R2 at the resource
+     *  level checks a replay creates every one of them. */
+    resources?: string[];
+    /** The wire transport class (packRegistry PackTransport) — the invariant matrix keys
+     *  variants off it too (a raw-tcp twin has no workerd fetch path, so R12b is n/a). */
+    transport?: string;
+    /** Optional native frontend of the same state owner, selected explicitly on the pack CLI. */
+    /** The serve-family (packRegistry PackArchetype) — the axis the invariant matrix keys
+     *  strictness off. Closed enum, REQUIRED: every pack declares one (the catalog was
+     *  fully classified 2026-09-02; the scaffolder's A1 TODO makes a new pack's
+     *  ratification unskippable because an undeclared archetype is RED here). */
+    archetype?: string;
+    /** R16: the protocol major the package targets and its standing against this kernel. */
+    protocol?: {
+        declared?: string;
+        major: number;
+        standing: 'current' | 'deprecated' | 'refused' | 'assumed';
+    };
+    /** R20: pack-shipped asset paths (relative to the pack dir) the serve path reads through the seam. */
+    assets?: string[];
+    /** R2: declared types no replay can create, each with its reason (adopted debt, legible). */
+    resourcesUnreachable?: Record<string, string>;
+    endpointEnv?: {
+        name: string;
+        templates?: Record<string, string>;
+    };
+    endpointEnvNone?: string;
+    /** The door that issues the application a credential the twin accepts (see TwinPack.credentialDoor). */
+    credentialDoor?: {
+        path: string;
+        body: Record<string, unknown>;
+        fill: Record<string, string>;
+    };
+    credentialIssuer?: string;
+    /** 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;
+    };
+    /** 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). */
+    sidePorts?: Array<{
+        name: string;
+        option: string;
+        flag: string;
+        path?: string;
+        note: string;
+    }>;
+    /** DERIVED, never declared: the pack's `create<Name>TwinServer` factory export — the
+     *  `({port,root,readOnly}) => {port,stop}` contract the colocated host mounts
+     *  (world-runtime/src/host.ts). Read off the module's own exports because the name is not
+     *  mechanically derivable from the vendor string (createUpstashRedisTwinServer,
+     *  createGoogleOAuthTwinServer); the export itself is the single source of truth. Consumed
+     *  by `volter-world init` to emit `colocate:` service entries (runtime contract R2a). */
+    serveExport?: string;
+};
+export type PackFactsFile = {
+    '//': string;
+    /** Vendor → facts from its current descriptor or explicit vendor-server backing. */
+    packs: Record<string, PackFacts>;
+    /** vendor packs whose index.ts exports no `pack` descriptor yet — the migration worklist. */
+    undeclared: string[];
+};
+/** Compile descriptors at explicit package directories; no repository layout or publisher namespace is assumed. */
+export declare function compilePackFacts(dirs: Array<{
+    vendor: string;
+    dir: string;
+}>): Promise<PackFactsFile>;
+export declare function renderPackFacts(file: PackFactsFile): string;

package/dist/src/pack-facts.js

@@ -0,0 +1,242 @@
+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 descriptor compiler. Pack locations are explicit; imports happen only when called by a publisher.
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { PACK_ARCHETYPES, PROTOCOL_VERSION, protocolStanding } from '@volter/world-core/runtime';
+const sortObject = (o) => Object.fromEntries(Object.entries(o).sort(([a], [b]) => a.localeCompare(b)));
+/** Host rules are DATA with a closed grammar (packRegistry HostRule): exactly one selector, regex
+ *  sources that compile, keys that are one pack's alone (and never another pack's vendor id),
+ *  and an exclude only where the same key has something to exclude from. */
+function validateHostRules(vendor, rules, vendors, claimedKeys, worldIds) {
+    const keys = new Set();
+    for (const rule of rules) {
+        const selectors = ['host', 'suffix', 'hostPattern'].filter((k) => rule[k] !== undefined);
+        if (selectors.length !== 1)
+            throw new Error(`pack-facts: ${vendor} host rule ${JSON.stringify(rule)} — exactly one of host | suffix | hostPattern`);
+        for (const k of ['hostPattern', 'pathPattern']) {
+            if (rule[k] !== undefined) {
+                try {
+                    new RegExp(rule[k]);
+                }
+                catch (e) {
+                    throw new Error(`pack-facts: ${vendor} host rule ${k} ${JSON.stringify(rule[k])} does not compile: ${e.message}`);
+                }
+            }
+        }
+        if (rule.demandPathPattern !== undefined && rule.demandPathPattern !== false) {
+            if (typeof rule.demandPathPattern !== 'string')
+                throw new Error(`pack-facts: ${vendor} demandPathPattern must be a regex source or false`);
+            try {
+                new RegExp(rule.demandPathPattern);
+            }
+            catch (e) {
+                throw new Error(`pack-facts: ${vendor} demandPathPattern does not compile: ${e.message}`);
+            }
+        }
+        if (rule.exclude !== undefined && rule.exclude !== true)
+            throw new Error(`pack-facts: ${vendor} host rule ${JSON.stringify(rule)} — exclude is \`true\` or absent, never a falsy flag`);
+        const key = rule.key ?? vendor;
+        // A foreign key is a WORLD identity too: `volter-world init` emits <KEY>_TWIN_URL only for the
+        // ids in adoption.worldIds (covers.ts injectorVendorKeysFor), so a key not listed there would
+        // route in the injector and never be wired by the world — and a pack claiming ONLY foreign
+        // keys would leave its own <VENDOR>_TWIN_URL inert while looking covered.
+        if (key !== vendor && !worldIds.includes(key))
+            throw new Error(`pack-facts: ${vendor} claims key "${key}" but does not list it in adoption.worldIds — the routing identity must also be a world identity`);
+        if (!/^[a-z0-9-]+$/.test(key))
+            throw new Error(`pack-facts: ${vendor} host rule key ${JSON.stringify(key)} — keys are [a-z0-9-]+ (the <KEY>_TWIN_URL stem)`);
+        if (key !== vendor && vendors.includes(key))
+            throw new Error(`pack-facts: ${vendor} claims key "${key}", which is another pack's vendor id — a pack's hosts are its own`);
+        const owner = claimedKeys.get(key);
+        if (owner !== undefined && owner !== vendor)
+            throw new Error(`pack-facts: key "${key}" is claimed by both ${owner} and ${vendor} — a key belongs to one pack`);
+        claimedKeys.set(key, vendor);
+        keys.add(key);
+    }
+    for (const key of keys) {
+        if (rules.filter((r) => (r.key ?? vendor) === key).every((r) => r.exclude === true))
+            throw new Error(`pack-facts: ${vendor} key "${key}" has only exclude rules — nothing to exclude from`);
+    }
+    // A pack may answer ONLY under foreign keys (aws: the consolidated twin has no `aws` host and
+    // AWS_TWIN_URL is null by design) — the worldIds rule above is what makes that explicit.
+}
+/** Compile descriptors at explicit package directories; no repository layout or publisher namespace is assumed. */
+export async function compilePackFacts(dirs) {
+    const claimedKeys = new Map();
+    const claimedTools = new Map();
+    const packDirs = new Map(dirs.map((e) => [e.vendor, e.dir]));
+    const vendors = [...packDirs.keys()].sort();
+    const packs = {};
+    const undeclared = [];
+    for (const vendor of vendors) {
+        const entry = join(packDirs.get(vendor), 'src', 'index.ts');
+        if (!existsSync(entry)) {
+            undeclared.push(vendor);
+            continue;
+        }
+        const mod = await import(__rewriteRelativeImportExtension(entry));
+        const pack = mod.pack;
+        if (pack === undefined || typeof pack.vendor !== 'string') {
+            undeclared.push(vendor);
+            continue;
+        }
+        if (pack.vendor !== vendor) {
+            throw new Error(`pack-facts: ${entry} declares vendor "${pack.vendor}" but lives in ${vendor}/ of the pack repository — the directory IS the identity; rename one.`);
+        }
+        if (pack.hosts !== undefined && pack.hostsNone !== undefined) {
+            throw new Error(`pack-facts: ${vendor} declares BOTH hosts and hostsNone — a ruling is one or the other.`);
+        }
+        if (pack.hosts !== undefined)
+            validateHostRules(vendor, pack.hosts, vendors, claimedKeys, pack.adoption?.worldIds ?? []);
+        for (const tool of pack.adoption?.tools ?? []) {
+            if (!tool || typeof tool.package !== 'string' || tool.package === '' || (tool.usage !== 'build' && tool.usage !== 'deployment')) {
+                throw new Error(`pack-facts: ${vendor} adoption tool must be { package, usage: "build" | "deployment" }`);
+            }
+            const owner = claimedTools.get(tool.package);
+            if (owner !== undefined && owner !== vendor)
+                throw new Error(`pack-facts: tool package "${tool.package}" is claimed by both ${owner} and ${vendor}`);
+            claimedTools.set(tool.package, vendor);
+        }
+        // the World reads its name and templates (init.ts, served-world.ts): a bare string sets nothing, silently
+        const ee = pack.endpointEnv;
+        if (ee !== undefined && (typeof ee !== 'object' || ee === null || typeof ee.name !== 'string' || typeof ee.note !== 'string')) {
+            throw new Error(`pack-facts: ${vendor}'s endpointEnv is ${JSON.stringify(ee)}; it is { name, templates?, note } (the variable the vendor's SDK reads, and why)`);
+        }
+        if (pack.endpointEnv !== undefined && pack.endpointEnvNone !== undefined) {
+            throw new Error(`pack-facts: ${vendor} declares BOTH endpointEnv and endpointEnvNone — a ruling is one or the other.`);
+        }
+        if (pack.archetype === undefined) {
+            throw new Error(`pack-facts: ${vendor} declares no archetype — every pack ratifies its serve-family (closed enum: ${PACK_ARCHETYPES.join(' | ')}; see packRegistry PackArchetype)`);
+        }
+        if (!PACK_ARCHETYPES.includes(pack.archetype)) {
+            throw new Error(`pack-facts: ${vendor} declares unknown archetype "${String(pack.archetype)}" (closed enum: ${PACK_ARCHETYPES.join(' | ')})`);
+        }
+        // raw-tcp consistency: the one raw-protocol pack today serves CRUD state over its wire.
+        if (pack.archetype === 'proxy' && pack.transport === 'raw-tcp') {
+            throw new Error(`pack-facts: ${vendor} — proxy archetype over raw-tcp transport is undeclared territory; rule it in the contract first.`);
+        }
+        const facts = {};
+        if (pack.adoption !== undefined)
+            facts.adoption = pack.adoption;
+        if (pack.hosts !== undefined)
+            facts.hosts = pack.hosts;
+        if (pack.hostsNone !== undefined)
+            facts.hostsNone = pack.hostsNone;
+        if (pack.hostsClaimed !== undefined) {
+            if (!pack.hostsClaimed.door.startsWith('/') || !pack.hostsClaimed.note.trim())
+                throw new Error(`pack-facts: ${vendor} hostsClaimed needs a door path and a note`);
+            if (pack.hosts === undefined)
+                throw new Error(`pack-facts: ${vendor} claims hosts at runtime but declares none of its own: its door is reached on its own host`);
+            facts.hostsClaimed = pack.hostsClaimed;
+        }
+        facts.archetype = pack.archetype;
+        // R16 — the protocol the package targets, and where it stands against this kernel: the kernel serves its own
+        // major and no other, so any other declaration, or none, is refused here.
+        {
+            const standing = protocolStanding(pack.protocol);
+            if (standing.standing === 'refused')
+                throw new Error(`pack-facts: ${vendor} declares protocol ${JSON.stringify(pack.protocol)} — this kernel serves ${PROTOCOL_VERSION} and no other major (runtime contract R16)`);
+            facts.protocol = { ...(pack.protocol !== undefined ? { declared: pack.protocol } : {}), major: standing.major, standing: standing.standing };
+        }
+        facts.transport = pack.transport;
+        if (pack.maxRequestBodySize !== undefined) {
+            if (!Number.isSafeInteger(pack.maxRequestBodySize) || pack.maxRequestBodySize <= 0)
+                throw new Error(`pack-facts: ${vendor} maxRequestBodySize must be positive integer bytes`);
+            facts.maxRequestBodySize = pack.maxRequestBodySize;
+        }
+        if (pack.assets !== undefined)
+            facts.assets = pack.assets; // R20 — what the deploy step places behind the assets binding
+        if (pack.resourcesUnreachable !== undefined)
+            facts.resourcesUnreachable = pack.resourcesUnreachable; // R2 adopted-as-debt, by name and reason
+        facts.resources = pack.resources; // the declared subject types — R2's resource-level claim
+        if (pack.endpointEnv !== undefined)
+            facts.endpointEnv = pack.endpointEnv;
+        if (pack.endpointEnvNone !== undefined)
+            facts.endpointEnvNone = pack.endpointEnvNone;
+        if (pack.credentialDoor !== undefined)
+            facts.credentialDoor = pack.credentialDoor;
+        if (pack.credentialIssuer !== undefined) {
+            if (!/^[a-z][a-z0-9-]*$/.test(pack.credentialIssuer) || pack.credentialIssuer === vendor)
+                throw new Error(`pack-facts: ${vendor} credentialIssuer must name another pack`);
+            facts.credentialIssuer = pack.credentialIssuer;
+        }
+        if (pack.prismaAdapter !== undefined) {
+            if (pack.endpointEnv?.templates?.[pack.prismaAdapter.urlEnv] === undefined && pack.credentialDoor?.fill[pack.prismaAdapter.urlEnv] === undefined) {
+                throw new Error(`pack-facts: ${vendor} declares prismaAdapter.urlEnv "${pack.prismaAdapter.urlEnv}" but neither its endpointEnv templates nor its credentialDoor fill such a variable — the adapter's URL is one of theirs.`);
+            }
+            facts.prismaAdapter = pack.prismaAdapter;
+        }
+        if (pack.managedDatabase !== undefined) {
+            const md = pack.managedDatabase;
+            if (md.kind !== 'postgres')
+                throw new Error(`pack-facts: ${vendor} declares managedDatabase.kind "${String(md.kind)}"; the runtime binds only the World's managed postgres`);
+            if (typeof md.arg !== 'string' || !/^--[a-z][a-z-]*$/.test(md.arg))
+                throw new Error(`pack-facts: ${vendor} declares managedDatabase.arg "${String(md.arg)}"; it is the serve flag the URL follows (--name)`);
+            if (typeof md.note !== 'string' || md.note.trim() === '')
+                throw new Error(`pack-facts: ${vendor} declares managedDatabase with no note`);
+            facts.managedDatabase = pack.managedDatabase;
+        }
+        if (pack.managedService !== undefined) {
+            const ms = pack.managedService;
+            if (ms.kind !== 'redis' && ms.kind !== 'mongodb')
+                throw new Error(`pack-facts: ${vendor} declares managedService.kind "${String(ms.kind)}"; the managed-infrastructure kinds a twin backs are redis and mongodb`);
+            if (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 (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`);
+            facts.managedService = pack.managedService;
+        }
+        if (pack.sidePorts !== undefined) {
+            for (const side of pack.sidePorts) {
+                if (typeof side.name !== 'string' || !/^[a-z][a-z0-9-]*$/.test(side.name))
+                    throw new Error(`pack-facts: ${vendor} declares a side port named "${String(side.name)}"; a name is lowercase (inspect)`);
+                if (typeof side.option !== 'string' || !/^[a-z][A-Za-z0-9]*$/.test(side.option))
+                    throw new Error(`pack-facts: ${vendor} side port ${side.name}: option "${String(side.option)}" is the factory's camelCase option`);
+                if (typeof side.flag !== 'string' || !/^--[a-z][a-z-]*$/.test(side.flag))
+                    throw new Error(`pack-facts: ${vendor} side port ${side.name}: flag "${String(side.flag)}" is the serve flag (--name)`);
+                if (side.path !== undefined && (typeof side.path !== 'string' || !side.path.startsWith('/')))
+                    throw new Error(`pack-facts: ${vendor} side port ${side.name}: path "${String(side.path)}" starts with /`);
+                if (typeof side.note !== 'string' || side.note.trim() === '')
+                    throw new Error(`pack-facts: ${vendor} side port ${side.name} has no note`);
+            }
+            facts.sidePorts = pack.sidePorts;
+        }
+        // The serve factory is DERIVED from the module's exports (see PackFacts.serveExport);
+        // a pack exporting SEVERAL factories must declare which one `cli.ts serve` boots — the
+        // exports alone cannot reveal that judgment (linear defaults to its DERIVED server).
+        const serveExports = Object.keys(mod).filter((k) => /^create\w*TwinServer$/.test(k) && typeof mod[k] === 'function');
+        if (pack.serveExport !== undefined) {
+            if (!serveExports.includes(pack.serveExport)) {
+                throw new Error(`pack-facts: ${vendor} declares serveExport "${pack.serveExport}" but its index exports no such create*TwinServer factory (found: ${serveExports.join(', ') || 'none'}).`);
+            }
+            facts.serveExport = pack.serveExport;
+        }
+        else if (serveExports.length > 1) {
+            throw new Error(`pack-facts: ${vendor} exports ${serveExports.length} create*TwinServer factories (${serveExports.join(', ')}) — declare \`serveExport\` on its descriptor naming the one cli.ts serve boots.`);
+        }
+        else if (serveExports.length === 1) {
+            facts.serveExport = serveExports[0];
+        }
+        if (Object.keys(facts).length > 0)
+            packs[vendor] = facts;
+    }
+    return {
+        '//': 'GENERATED by scripts/pack-facts.ts — current pack descriptors and explicit world-runtime server backings; no prior-artifact entries are retained.',
+        packs: sortObject(packs),
+        undeclared,
+    };
+}
+export function renderPackFacts(file) {
+    return JSON.stringify(file, null, 2) + '\n';
+}

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

@@ -31,6 +31,7 @@ export type StepHooks = {
  *  its sockets are WebSockets to that port, and a line connection (`stream`) is a TCP connection to its protocol port. */
 export type ServedTwin = (root: string, options: {
     scenarioPath?: string;
+    application?: import('@volter/world-core').PackFetchOptions['application'];
 }) => Promise<{
     fetch: (request: Request) => Promise<Response>;
     stop: () => void;

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

@@ -11,10 +11,10 @@ import { attributionName } from "../verdict.js";
 import { redis } from '@volter/world-core';
 import { gzipSync } from 'node:zlib';
 import { parse, visit } from 'graphql';
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { databaseSession, getActiveWorldStore, MemoryBlobStore, MemoryWorldStore, setActiveBlobStore, setActiveWorldStore, setDeliveryObserver, setInProcessTwins } from '@volter/world-core/runtime';
-import { VENDOR_HOSTS } from '@volter/world-core/vendor-hosts';
+import { createHostTable } from '@volter/world-core/host-routing';
 import packFactsDocument from '@volter/world-core/generated/pack-facts.json' with { type: 'json' };
 import { isResp, at, captureAt, echoFailures, expandFills, expectFailures, fill, fillJson, formBody, isGit, isLine, isSql, isSocket, isWait, jwtAuthorization, oauth1Authorization, presignedPath, sigv4Headers, waitMs } from "./journey-kit.js";
 import { lanesOf, lineShape, shapeChecker } from "./shape.js";
@@ -28,7 +28,22 @@ function socketAt(open, host) {
     const u = new URL(open);
     return { host: u.host, path: `${u.pathname}${u.search}` };
 }
-export function usePacks(dir) { packsRoot = dir; }
+const baselineFacts = packFactsDocument.packs;
+let walkFacts = baselineFacts;
+let walkHosts = createHostTable(walkFacts).hosts;
+export function usePacks(dir) {
+    packsRoot = dir;
+    const installed = {};
+    for (const name of readdirSync(dir)) {
+        const file = join(dir, name, 'generated/pack-facts.json');
+        if (existsSync(file))
+            Object.assign(installed, JSON.parse(readFileSync(file, 'utf8')).packs);
+    }
+    walkFacts = { ...baselineFacts, ...installed };
+    walkHosts = createHostTable(walkFacts, Object.keys(installed)).hosts;
+    shapes.clear();
+    fieldsByVendor.clear();
+}
 const packsDir = () => { if (packsRoot === undefined)
     throw new Error('usePacks(<packs dir>) first'); return packsRoot; };
 /** The walk's World: the twin's own code on its in-memory World and blob stores (the backends a serverless
@@ -87,15 +102,15 @@ const shapeOf = (vendor) => { if (!shapes.has(vendor))
  *  name, as vendor-hosts.cjs compiles them. */
 function routingKeys(vendor) {
     const name = vendor.split('/')[0];
-    const hosts = (packFactsDocument.packs[name]?.hosts) ?? [];
-    return [...new Set(hosts.map((rule) => rule.key ?? name))].filter((key) => VENDOR_HOSTS[key] !== undefined);
+    const hosts = walkFacts[name]?.hosts ?? [];
+    return [...new Set(hosts.map((rule) => rule.key ?? name))].filter((key) => walkHosts[key] !== undefined);
 }
 /** Whether one of `keys`' host rules claims `url` (an absolute URL; a path is the life's own host). */
 const claims = (keys, url) => {
     if (!/^https?:\/\//.test(url) || !URL.canParse(url))
         return false;
     const u = new URL(url);
-    return keys.some((key) => VENDOR_HOSTS[key](u.hostname, u.pathname));
+    return keys.some((key) => walkHosts[key](u.hostname, u.pathname));
 };
 /** What a stored row keeps for the twin that no schema of the vendor's spec names, by path, in anything the World shows a
  *  client: the pack's `_`-prefixed bookkeeping (GitHub's `_links` is the vendor's), and, in what no answer's SHAPE
@@ -220,7 +235,7 @@ export async function walk(journey, root, collect, opts) {
         }
         return { status: a.status, ...(a.headers ? { headers: a.headers } : {}), ...(a.bodyError === undefined ? {} : { bodyError: a.bodyError }), body: typeof a.body === 'string' ? a.body : a.body === undefined ? '' : JSON.stringify(a.body) };
     };
-    const served = opts.served ? await opts.served(root, scenarioPath ? { scenarioPath } : {}) : undefined;
+    const served = opts.served ? await opts.served(root, { ...(scenarioPath ? { scenarioPath } : {}), application }) : undefined;
     const twin = served ? served.fetch : factory(root, { ...(scenarioPath ? { scenarioPath } : {}), application });
     const shape = await shapeOf(journey.vendor);
     const host = journey.host ?? 'twin.local';

package/dist/src/walk/vendor-fetch.js

@@ -10,7 +10,6 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 // index. What the catalog's walkers drive (behavior journeys, the spec census probe, the invariants)
 // since the worker render left with the v1 host.
 import { join } from 'node:path';
-import packFacts from '@volter/world-core/generated/pack-facts.json' with { type: 'json' };
 import { startPgliteHost } from "./walk-database.js";
 import { worldNow } from '@volter/world-core/runtime';
 export async function vendorFetch(twinDir, vendor) {
@@ -26,7 +25,7 @@ export async function vendorFetch(twinDir, vendor) {
     if (!name)
         return undefined;
     const factory = mod[name];
-    if (!declaresManagedDatabase(vendor))
+    if (!mod.pack?.managedDatabase)
         return (root, options = {}) => factory({ root, ...options });
     // A pack whose data plane is the World's managed Postgres is walked over one, as a World binds it: each World (each
     // root) its own fresh database, started on its first request and stopped when the walk's process ends, its clock the
@@ -52,11 +51,6 @@ process.once('exit', () => { for (const host of hosts) {
     }
     catch { /* ended */ }
 } });
-/** Whether a pack declares the World's managed database (its descriptor's `managedDatabase`, in the pack facts: this
- *  checkout's kernel's, as the walk's other readers of them import them). */
-function declaresManagedDatabase(vendor) {
-    return packFacts.packs[vendor.split('/')[0]]?.managedDatabase !== undefined;
-}
 const jwtView = (field) => (body) => {
     const token = body?.[field];
     if (typeof token !== 'string')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/twin-standard",
-  "version": "1.0.32",
+  "version": "1.0.34",
   "description": "The Protocol 3 standard for Volter twin packs: the criteria a pack is graded by, the grader, the gate a pack repository and the twin catalog run on every change and submission, and the spec derivation the grade checks against. Pin a version: every place a pack is judged judges by that standard.",
   "keywords": [
     "twin",
@@ -70,12 +70,16 @@
     "yaml": "2.9.0"
   },
   "peerDependencies": {
-    "@volter/world-core": "*",
-    "@volter/world-runtime": "*"
+    "@volter/world-core": "3.0.42",
+    "@volter/world-runtime": "*",
+    "playwright": "^1.63.0"
   },
   "peerDependenciesMeta": {
     "@volter/world-runtime": {
       "optional": true
+    },
+    "playwright": {
+      "optional": true
     }
   },
   "devDependencies": {

package/src/assessment.ts

@@ -0,0 +1,93 @@
+// 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, type DerivedOwner } from '@volter/world-core/runtime';
+import { p3Gate } from './gate.ts';
+import { conformance } from './conformance.ts';
+import { inMemoryWorld, walk, withPinnedWorldDraws, usePacks, type ServedTwin } from './walk/behavior-journey.ts';
+import { compilePackFacts } from './pack-facts.ts';
+import { expandFills, type Journey } from './walk/journey-kit.ts';
+
+const canonical = (value: unknown): unknown => 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: unknown) => JSON.stringify(canonical(value));
+const hash = (value: unknown) => createHash('sha256').update(json(value)).digest('hex');
+const read = (file: string) => JSON.parse(readFileSync(file, 'utf8'));
+export type AssessmentOptions = { browser?: boolean; conformance?: boolean };
+
+/** Surface coverage counts actual kernel dispatch, and retains every declared gap in the denominator. */
+export async function assessPack(packDir: string, options: AssessmentOptions = {}) {
+  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'))) as Journey;
+  if (!Array.isArray(life.steps) || !life.steps.length) throw new Error('Assessment needs a nonempty customer journey');
+  const surfaceRows: Array<{ unit: string; signature: string; ids: string[] }> = [];
+  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: { id: string }) => operation.id) });
+  }
+  const declaredHttp = [...new Set(surfaceRows.flatMap((row) => row.ids.map((id) => `${row.unit}:${id}`)))].sort();
+  const mod = await import(join(packDir, 'src/index.ts')) as Record<string, unknown>;
+  const factory = Object.entries(mod).find(([name, value]) => /^create\w+Fetch$/.test(name) && !/TwinFetch$/.test(name) && typeof value === 'function')?.[1] as ((options: { root: string }) => { ownersByUnit?: () => Record<string, Record<string, DerivedOwner>>; owners?: () => Record<string, DerivedOwner> }) | undefined;
+  const surfaceWorld = inMemoryWorld('catalog-surface');
+  let owners: Record<string, DerivedOwner> | null = 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: { exercised: string[]; ambiguous: boolean }) => !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?: ServedTwin) {
+    const world = inMemoryWorld('catalog-replay');
+    const failures: Array<{ step: string; beat: string; detail: string }> = [], trace: unknown[] = [];
+    const exercised = new Set<string>();
+    const signatures = new WeakMap<object, string>();
+    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: Record<string, unknown> = { 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.ts');
+    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 as unknown[]).length === 0 && (browser.replay as { equal: boolean }).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/src/browser-assessment.ts

@@ -0,0 +1,47 @@
+// Browser transport for the existing journey engine. A container supplies network isolation in catalog execution.
+import { join } from 'node:path';
+import type { ServedTwin } from './walk/behavior-journey.ts';
+export async function chromiumServed(packDir: string, host: string) {
+  const { chromium } = await import('playwright');
+  const browser = await chromium.launch({ args: ['--no-sandbox'] });
+  const mod = await import(join(packDir, 'src/index.ts')) as Record<string, unknown>;
+  const factory = Object.entries(mod).find(([name, value]) => /^create\w+Fetch$/.test(name) && !/TwinFetch$/.test(name) && typeof value === 'function')?.[1] as ((options: import('@volter/world-core').PackFetchOptions) => (request: Request) => Promise<Response>) | undefined;
+  if (!factory) { await browser.close(); throw new Error('Browser assessment needs the pack HTTP fetch factory'); }
+  const served: ServedTwin = 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: await request.allHeaders(), ...(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: 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() };
+}