@volter/twin-standard 1.0.158 → 1.0.160

package/dist/src/consumer.d.ts

@@ -23,6 +23,7 @@ type ConsumerInstallation = {
     cli: string;
     artifact?: string;
 };
+export type ConsumerResult = Awaited<ReturnType<typeof runConsumerWorkflow>>;
 /** Bind behavior inputs on both source and packed layouts; compiled outputs and score caches are not inputs. */
 export declare function consumerSourceDigest(pack: string): string;
 /** A pack supplies its own entry journey; older immutable releases use a versioned standard fixture. */
@@ -32,6 +33,12 @@ export declare function prepareConsumerApp(packDir: string, appDir: string, inst
     recipeSha256: string;
     dependencies: Record<string, string>;
 };
+/** Run the unchanged customer command, with the environment supplied by its World. */
+export declare function runConsumerCommand(argv: string[], appDir: string, env: NodeJS.ProcessEnv, signal?: AbortSignal): Promise<{
+    exitCode: number | null;
+    stdout: string;
+    stderr: string;
+}>;
 export declare function runConsumerWorkflow(packDir: string, options: ConsumerOptions): Promise<{
     node: string | null;
     evaluatorRuntime: {
@@ -40,7 +47,7 @@ export declare function runConsumerWorkflow(packDir: string, options: ConsumerOp
     };
     at: string;
     retentionNotApplicable?: string | undefined;
-    measured: boolean;
+    measured: true;
     passed: boolean;
     scope: string;
     package: any;
@@ -61,6 +68,15 @@ export declare function runConsumerWorkflow(packDir: string, options: ConsumerOp
             package: string;
             version: string;
         };
+        peers: {
+            package: string;
+            version: string;
+        }[];
+        sdks: {
+            package: string;
+            version: string;
+            entry: string;
+        }[];
         dependencyLockSha256: string;
         appLocal: boolean;
     };
@@ -90,4 +106,9 @@ export declare function runConsumerWorkflow(packDir: string, options: ConsumerOp
         mode: string;
     };
 }>;
+/** The same installed execution can prove a declared SDK when the standard has no built-in client module. */
+export declare function consumerClientProof(packDir: string, vendor: string, sdks: string[], result?: ConsumerResult): {
+    failures: string[];
+    note?: string;
+};
 export {};

package/dist/src/consumer.js

@@ -7,16 +7,27 @@ import { spawn, spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { standardPackageFile } from "./package-file.js";
 import { dependencyLock } from "./dependency-lock.js";
+function recipeDependencies(recipe) {
+    const app = JSON.parse(recipe.files['package.json']);
+    const dependencies = { ...app.dependencies, ...app.devDependencies, ...app.optionalDependencies };
+    for (const [name, version] of Object.entries(dependencies)) {
+        if (typeof version !== 'string' || !/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(version))
+            throw new Error(`${name}: customer SDK dependencies require exact registry versions`);
+    }
+    return dependencies;
+}
 function packageIdentity(entry, name) {
     let directory = dirname(realpathSync(entry));
     while (true) {
-        const file = join(directory, 'package.json');
-        if (existsSync(file)) {
-            const pkg = JSON.parse(readFileSync(file, 'utf8'));
-            if (pkg.name === name)
-                return { directory, version: pkg.version };
-        }
         const parent = dirname(directory);
+        // The installed node_modules slot owns the entry; nested distribution manifests do not identify the package.
+        const boundary = basename(parent) === 'node_modules' || (basename(parent).startsWith('@') && basename(dirname(parent)) === 'node_modules');
+        if (boundary) {
+            const pkg = JSON.parse(readFileSync(join(directory, 'package.json'), 'utf8'));
+            if (pkg.name !== name)
+                throw new Error(`${name}: installed package boundary belongs to ${String(pkg.name)}`);
+            return { directory, version: pkg.version };
+        }
         if (parent === directory)
             throw new Error(`${name} has no installed package identity`);
         directory = parent;
@@ -30,6 +41,21 @@ function consumerTools(cli) {
         '@volter/world-runtime': packageIdentity(require.resolve('@volter/world-runtime'), '@volter/world-runtime').version,
     };
 }
+function consumerEntries(directory, names) {
+    if (!names.length)
+        return new Map();
+    const result = spawnSync('node', ['--input-type=module', '--eval', 'process.stdout.write(JSON.stringify(process.argv.slice(1).map(name => import.meta.resolve(name))))', ...names], { cwd: directory, encoding: 'utf8' });
+    if (result.error || result.status !== 0)
+        throw new Error(`Consumer ESM dependency resolution failed: ${result.error?.message ?? result.stderr.trim()}`);
+    const entries = JSON.parse(result.stdout);
+    return new Map(names.map((name, index) => [name, fileURLToPath(entries[index])]));
+}
+function consumerPeerVersions(metadata, cli, sdkDependencies) {
+    const names = Object.keys(metadata.peerDependencies ?? {})
+        .filter((name) => name !== '@volter/world-core' && !metadata.peerDependenciesMeta?.[name]?.optional && !metadata.dependencies?.[name] && !metadata.optionalDependencies?.[name] && !sdkDependencies[name]);
+    const entries = consumerEntries(dirname(realpathSync(cli)), names);
+    return Object.fromEntries(names.map((name) => [name, packageIdentity(entries.get(name), name).version]));
+}
 /** Bind behavior inputs on both source and packed layouts; compiled outputs and score caches are not inputs. */
 export function consumerSourceDigest(pack) {
     const entries = [];
@@ -86,10 +112,7 @@ export function prepareConsumerApp(packDir, appDir, installation) {
     app.devEngines = { packageManager: { name: 'pnpm', version: '12.15.0', onFail: 'error' } };
     if (app.scripts || app.workspaces)
         throw new Error('Consumer fixture supplies direct SDK commands, not install scripts or workspace links');
-    for (const [name, version] of Object.entries({ ...app.dependencies, ...app.devDependencies, ...app.optionalDependencies })) {
-        if (typeof version !== 'string' || !/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(version))
-            throw new Error(`${name}: customer SDK dependencies require exact registry versions`);
-    }
+    const sdkDependencies = recipeDependencies(recipe);
     const files = Object.entries(recipe.files).map(([path, content]) => {
         if (isAbsolute(path) || path.includes('\\') || path.split('/').some((part) => !part || part === '.' || part === '..' || part === '.git') || path.split('/').includes('node_modules') || ['.env', '.npmrc', '.volter/world.json'].includes(path))
             throw new Error(`Invalid consumer file: ${path}`);
@@ -104,7 +127,7 @@ export function prepareConsumerApp(packDir, appDir, installation) {
             throw new Error('Consumer candidate must be an absolute prepared archive path');
         if (Object.hasOwn(app.dependencies ?? {}, metadata.name))
             throw new Error('Consumer SDK dependencies must not substitute the candidate package');
-        app.devDependencies = { ...app.devDependencies, '@volter/world-core': tools['@volter/world-core'], [metadata.name]: installation.artifact ? `file:${installation.artifact}` : metadata.version };
+        app.devDependencies = { ...app.devDependencies, ...consumerPeerVersions(metadata, installation.cli, sdkDependencies), '@volter/world-core': tools['@volter/world-core'], [metadata.name]: installation.artifact ? `file:${installation.artifact}` : metadata.version };
     }
     files.find(([path]) => path === 'package.json')[1] = JSON.stringify(app, null, 2) + '\n';
     files.push(['pnpm-workspace.yaml', 'packages:\n  - .\npackageImportMethod: hardlink\nnodeLinker: hoisted\nautoInstallPeers: false\nstrictPeerDependencies: false\n']);
@@ -126,6 +149,17 @@ export function prepareConsumerApp(packDir, appDir, installation) {
     }
     return { recipeSha256: createHash('sha256').update(JSON.stringify(recipe)).digest('hex'), dependencies: app.dependencies ?? {} };
 }
+/** Run the unchanged customer command, with the environment supplied by its World. */
+export function runConsumerCommand(argv, appDir, env, signal) {
+    return new Promise((done) => {
+        const child = spawn(argv[0], argv.slice(1), { cwd: appDir, env, signal, stdio: ['ignore', 'pipe', 'pipe'] });
+        let stdout = '', stderr = '';
+        child.stdout.on('data', (chunk) => { stdout += chunk; });
+        child.stderr.on('data', (chunk) => { stderr += chunk; });
+        child.on('error', (error) => { stderr += `\n${error.message}`; });
+        child.on('close', (exitCode) => done({ exitCode, stdout, stderr }));
+    });
+}
 export async function runConsumerWorkflow(packDir, options) {
     if (!isAbsolute(options.appDir) || !isAbsolute(options.cli) || !/^sha512-[A-Za-z0-9+/]{86}==$/.test(options.artifactIntegrity))
         throw new Error('Consumer requires absolute prepared paths and candidate SHA-512 integrity');
@@ -134,10 +168,18 @@ export async function runConsumerWorkflow(packDir, options) {
     const cliEntry = realpathSync(options.cli);
     const tools = consumerTools(cliEntry);
     const metadata = JSON.parse(readFileSync(join(packDir, 'package.json'), 'utf8'));
+    const facts = JSON.parse(readFileSync(join(packDir, 'generated/pack-facts.json'), 'utf8'));
+    const vendor = Object.keys(facts.packs ?? {})[0];
+    if (!vendor || Object.keys(facts.packs).length !== 1)
+        throw new Error('Consumer workflow requires one selected artifact identity');
+    const recipe = consumerRecipe(vendor, packDir), sdkDependencies = recipeDependencies(recipe);
     const appRoot = realpathSync(options.appDir), appRequire = createRequire(join(appRoot, 'package.json'));
     const candidate = packageIdentity(appRequire.resolve(metadata.name), metadata.name);
     const kernel = packageIdentity(appRequire.resolve('@volter/world-core/runtime'), '@volter/world-core');
-    for (const [name, identity] of [[metadata.name, candidate], ['@volter/world-core', kernel]]) {
+    const peerVersions = consumerPeerVersions(metadata, cliEntry, sdkDependencies);
+    const entries = consumerEntries(appRoot, [...Object.keys(peerVersions), ...Object.keys(sdkDependencies)]);
+    const peers = Object.keys(peerVersions).map((name) => [name, packageIdentity(entries.get(name), name)]);
+    for (const [name, identity] of [[metadata.name, candidate], ['@volter/world-core', kernel], ...peers]) {
         const location = relative(join(appRoot, 'node_modules'), identity.directory);
         if (location.startsWith('..') || isAbsolute(location))
             throw new Error(`${name}: consumer resolves an evaluator or ancestor dependency; install it in the app`);
@@ -147,25 +189,25 @@ export async function runConsumerWorkflow(packDir, options) {
         throw new Error('Consumer app candidate does not match the exact assessed artifact');
     if (kernel.version !== tools['@volter/world-core'] || appLock.entry('@volter/world-core')?.version !== kernel.version)
         throw new Error('Consumer app kernel does not match the CLI kernel pin');
-    const application = { candidate: { package: metadata.name, version: candidate.version, integrity: options.artifactIntegrity }, kernel: { package: '@volter/world-core', version: kernel.version }, dependencyLockSha256: createHash('sha256').update(appLockBytes).digest('hex'), appLocal: true };
-    const facts = JSON.parse(readFileSync(join(packDir, 'generated/pack-facts.json'), 'utf8'));
-    const vendor = Object.keys(facts.packs ?? {})[0];
-    if (!vendor || Object.keys(facts.packs).length !== 1)
-        throw new Error('Consumer workflow requires one selected artifact identity');
-    const recipe = consumerRecipe(vendor, packDir);
+    for (const [name, identity] of peers)
+        if (identity.version !== peerVersions[name] || appLock.entry(name)?.version !== identity.version)
+            throw new Error(`${name}: consumer peer does not match the installed CLI closure and exact application lock version ${peerVersions[name]}`);
+    const sdks = Object.entries(sdkDependencies).map(([name, version]) => {
+        const entry = realpathSync(entries.get(name)), identity = packageIdentity(entry, name);
+        const location = relative(join(appRoot, 'node_modules'), identity.directory);
+        if (location.startsWith('..') || isAbsolute(location))
+            throw new Error(`${name}: customer SDK resolves outside the application installation`);
+        if (identity.version !== version || appLock.entry(name)?.version !== version)
+            throw new Error(`${name}: customer SDK does not match its exact recipe and application lock version ${version}`);
+        return { package: name, version, entry: relative(appRoot, entry).split('\\').join('/') };
+    });
+    const application = { candidate: { package: metadata.name, version: candidate.version, integrity: options.artifactIntegrity }, kernel: { package: '@volter/world-core', version: kernel.version }, peers: peers.map(([name, identity]) => ({ package: name, version: identity.version })), sdks, dependencyLockSha256: createHash('sha256').update(appLockBytes).digest('hex'), appLocal: true };
     const commands = [];
     const failures = [];
     const compiledCli = /\.[cm]?js$/.test(cliEntry);
     let nodeVersion = null;
     const execute = async (label, executable, argv) => {
-        const result = await new Promise((done) => {
-            const child = spawn(executable, argv, { cwd: options.appDir, env: process.env, stdio: ['ignore', 'pipe', 'pipe'] });
-            let stdout = '', stderr = '';
-            child.stdout.on('data', (chunk) => { stdout += chunk; });
-            child.stderr.on('data', (chunk) => { stderr += chunk; });
-            child.on('error', (error) => done({ exitCode: 1, stdout, stderr: `${stderr}\n${error.message}` }));
-            child.on('close', (exitCode) => done({ exitCode, stdout, stderr }));
-        });
+        const result = await runConsumerCommand([executable, ...argv], options.appDir, process.env);
         commands.push({ label, argv: [executable, ...argv], ...result });
         if (result.exitCode !== 0)
             throw new Error(`${label} exited ${result.exitCode}: ${result.stderr.trim().split('\n')[0] ?? ''}`);
@@ -256,3 +298,26 @@ export async function runConsumerWorkflow(packDir, options) {
         at: new Date().toISOString(),
     };
 }
+/** The same installed execution can prove a declared SDK when the standard has no built-in client module. */
+export function consumerClientProof(packDir, vendor, sdks, result) {
+    if (!existsSync(join(packDir, 'journeys/first-use.json')))
+        return { failures: ['the pack supplies no journeys/first-use.json installed SDK workflow'] };
+    const recipe = consumerRecipe(vendor, packDir);
+    const dependencies = Object.entries(recipeDependencies(recipe)).filter(([name]) => sdks.includes(name));
+    if (!dependencies.length)
+        return { failures: ['the installed workflow has no exact direct dependency named by adoption.sdks'] };
+    if (!result?.measured || !result.passed || result.failures.length || !result.teardownVerified)
+        return { failures: ['the installed SDK workflow has no passing execution with verified teardown'] };
+    const metadata = JSON.parse(readFileSync(join(packDir, 'package.json'), 'utf8'));
+    const candidate = result.application.candidate;
+    if (result.package !== metadata.name || result.version !== metadata.version || candidate.package !== metadata.name || candidate.version !== metadata.version || !/^sha512-[A-Za-z0-9+/]{86}==$/.test(result.integrity) || candidate.integrity !== result.integrity || result.application.appLocal !== true)
+        return { failures: ['the installed SDK result does not identify this exact app-local candidate artifact'] };
+    if (result.fixture !== 'journeys/first-use.json' || result.sourceInputsSha256 !== consumerSourceDigest(packDir) || result.recipeSha256 !== createHash('sha256').update(JSON.stringify(recipe)).digest('hex'))
+        return { failures: ['the installed SDK result does not describe the current behavior inputs and authored recipe'] };
+    for (const [name, version] of dependencies) {
+        const sdk = result.application.sdks.find((entry) => entry.package === name);
+        if (sdk?.version !== version || !sdk.entry.startsWith('node_modules/') || sdk.entry.split('/').includes('..'))
+            return { failures: [`${name}: the installed SDK result has no exact app-local ${version} resolution`] };
+    }
+    return { failures: [], note: `installed customer workflow through ${dependencies.map(([name, version]) => `${name}@${version}`).join(', ')}; exact artifact and current recipe` };
+}

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

@@ -25,7 +25,7 @@ export declare function brief(unit: string): Promise<string>;
 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
+ *  itself: "Other wires"), or, for a unit whose spec is a proto, the gRPC seam over the schema the derivation 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, wire?: boolean, live?: boolean): string;

package/dist/src/create-pack.js

@@ -10,8 +10,9 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 // 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
+//   twin-standard create <dir> --init <vendor> --package <@scope/name>
+//                                                        write every fixed file of a new pack that does not exist yet
+//   twin-standard create <dir> --init <vendor> --package <@scope/name> --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
@@ -20,11 +21,11 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 //                                                          index}.ts, src/semantics/{states,shared,doors}.ts,
 //                                                          journeys/{demand,first-use}.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
+//   twin-standard create <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> --index --building the same during construction; unfinished operations stay gaps,
+//   twin-standard create <unit> --index --building   the same during construction; unfinished operations stay gaps,
 //                                                          and implemented operations must match their decisions
-//   bun scripts/create-pack.ts <unit> --brief [--out f]  the author's brief: every operation the derived core does not
+//   twin-standard create <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
@@ -75,7 +76,7 @@ export function handlerIndex(dir) {
     // 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`);
+        throw new Error(`${dir}: no src/generated/surface.gen.json yet; derive the unit (twin-standard derive) 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));
@@ -278,7 +279,7 @@ export async function brief(unit) {
             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)
+            // quoting the spec's own words (the derivation 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)
@@ -343,7 +344,7 @@ export function packIndexFile(dir, vendor) {
 }
 /** 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
+ *  itself: "Other wires"), or, for a unit whose spec is a proto, the gRPC seam over the schema the derivation 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, wire = false, live = false) {
@@ -443,7 +444,7 @@ export function initFiles(vendor) {
         '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/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 twin-standard derive). 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': cliFile(vendor),
         '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`,
@@ -522,7 +523,7 @@ export async function fixedFiles(dir) {
         throw new Error('Pack manifest must declare its vendor identity independently of the npm package name');
     files['src/index.ts'] = packIndexFile(dir, vendor);
     if (!existsSync(join(dir, 'src', 'stream.ts'))) {
-        // a unit whose spec is a proto (derive-pack generated its schema) is served over gRPC: its serve seam in that form
+        // a unit whose spec is a proto (the derivation generated its schema) is served over gRPC: its serve seam in that form
         const lanesOnly = !hasOwnSurface(dir) && readdirSync(dir).some((n) => existsSync(join(dir, n, 'src', 'manifest.ts')));
         const grpc = !lanesOnly && existsSync(join(dir, 'src', 'generated', 'proto.gen.json'));
         // a unit that takes broadcasts over RTMP (its manifest's `live`) has the live forms --index writes, so they reproduce
@@ -535,7 +536,7 @@ export async function fixedFiles(dir) {
 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 [--building] | --brief [--out <file>]');
+        console.error('usage: twin-standard create <dir> --init <vendor> --package <@scope/name> | <unit> --index [--building] | --brief [--out <file>]');
         process.exit(2);
     }
     if (rest.includes('--building') && (!rest.includes('--index') || rest.includes('--init') || rest.includes('--brief'))) {
@@ -642,7 +643,7 @@ export async function createPack(args) {
                 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,
+            // a unit whose spec is a proto (the derivation 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'))) {
                 const wire = existsSync(join(dir, 'src', 'stream.ts'));

package/dist/src/credential-issuer-import.d.ts

@@ -0,0 +1,3 @@
+/** The declared credential issuer's public subpaths, pinned as a direct runtime dependency. Reading the manifest as
+ *  data keeps the source/tarball gate independent of dependency installation; typechecking verifies exported paths. */
+export declare function credentialIssuerImports(unitDir: string, packageDir: string): (specifier: string) => boolean;

package/dist/src/credential-issuer-import.js

@@ -0,0 +1,42 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import ts from 'typescript';
+/** A literal property's effective value; a later spread or computed key cannot establish an import permission. */
+function property(expression, name) {
+    while (expression && (ts.isParenthesizedExpression(expression) || ts.isAsExpression(expression) || ts.isSatisfiesExpression(expression)))
+        expression = expression.expression;
+    if (!expression || !ts.isObjectLiteralExpression(expression))
+        return undefined;
+    for (const member of [...expression.properties].reverse()) {
+        if (!ts.isPropertyAssignment(member) || ts.isComputedPropertyName(member.name))
+            return undefined;
+        if (member.name.text === name)
+            return member.initializer;
+    }
+    return undefined;
+}
+/** The declared credential issuer's public subpaths, pinned as a direct runtime dependency. Reading the manifest as
+ *  data keeps the source/tarball gate independent of dependency installation; typechecking verifies exported paths. */
+export function credentialIssuerImports(unitDir, packageDir) {
+    const path = join(unitDir, 'src', 'manifest.ts');
+    const packagePath = join(packageDir, 'package.json');
+    if (!existsSync(path) || !existsSync(packagePath))
+        return () => false;
+    const source = ts.createSourceFile(path, readFileSync(path, 'utf8'), ts.ScriptTarget.Latest, true);
+    const manifests = source.statements.flatMap(statement => ts.isVariableStatement(statement)
+        && statement.modifiers?.some(modifier => modifier.kind === ts.SyntaxKind.ExportKeyword)
+        ? statement.declarationList.declarations.filter(declaration => ts.isIdentifier(declaration.name) && declaration.name.text === 'manifest') : []);
+    const issuer = manifests.length === 1 ? property(property(manifests[0].initializer, 'descriptor'), 'credentialIssuer') : undefined;
+    if (!issuer || !ts.isStringLiteral(issuer) || !/^[a-z]/.test(issuer.text) || /[^a-z0-9-]/.test(issuer.text))
+        return () => false;
+    const packageName = `@volter/twin-${issuer.text}`;
+    const pkg = JSON.parse(readFileSync(packagePath, 'utf8'));
+    const version = pkg.dependencies?.[packageName];
+    const number = '(?:0|[1-9][0-9]*)';
+    const prerelease = '(?:0|[1-9][0-9]*|[0-9]*[A-Za-z-][0-9A-Za-z-]*)';
+    const exactVersion = new RegExp(`^${number}\\.${number}\\.${number}(?:-${prerelease}(?:\\.${prerelease})*)?(?:\\+[0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*)?$`);
+    if (pkg.name === packageName || typeof version !== 'string' || exactVersion.exec(version)?.[0] !== version)
+        return () => false;
+    const prefix = `${packageName}/`;
+    return specifier => specifier.startsWith(prefix) && specifier.slice(prefix.length).split('/').every(segment => segment !== '' && segment !== '.' && segment !== '..' && !/[^A-Za-z0-9._-]/.test(segment) && segment.toLowerCase() !== 'node_modules');
+}

package/dist/src/derive.js

@@ -13,7 +13,7 @@ import { parseExactJson, exactInteger } from '@volter/world-core/exact-json';
 // vendored spec (`<pack>/spec/openapi.json[.gz]`), builds the spec IR (./spec-ir.ts) and writes the pack's
 // `src/generated/`. Deterministic: a second run over the same spec writes the same bytes. Never hand-edit what it writes.
 //
-// Usage: twin-standard derive <pack dir> [--out <dir>]   (twin-world: bun scripts/derive-pack.ts <vendor>)
+// Usage: twin-standard derive <pack dir> [--out <dir>]
 import { parse as parseYaml } from 'yaml';
 import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { basename, join } from 'node:path';
@@ -47,7 +47,7 @@ const PKG = unitAt(vendor).dir;
 const rfc = existsSync(join(PKG, 'spec')) ? readdirSync(join(PKG, 'spec')).find((f) => /^rfc\d+\.txt$/.test(f)) : undefined;
 const specPath = ['openapi.json.gz', 'openapi.json', 'openapi.yaml.gz', 'openapi.yaml', 'smithy.json.gz', 'smithy.json', 'discovery.json.gz', 'discovery.json', ...(rfc ? [rfc] : []), 'openapi', 'proto', 'commands', 'command-builders.json', 'client-ops.json'].map((f) => join(PKG, 'spec', f)).find((p) => existsSync(p));
 if (!specPath) {
-    console.error(`derive-pack: no spec at ${join(PKG, 'spec')}/openapi.{json,yaml}[.gz], smithy.json[.gz], rfcNNNN.txt, proto/, commands/, command-builders.json or client-ops.json`);
+    console.error(`derive: no spec at ${join(PKG, 'spec')}/openapi.{json,yaml}[.gz], smithy.json[.gz], rfcNNNN.txt, proto/, commands/, command-builders.json or client-ops.json`);
     process.exit(SOURCE_REFUSAL);
 }
 const rpcService = basename(specPath) === 'proto';
@@ -343,7 +343,7 @@ if (existsSync(manifestPath)) {
     }
     // a resource's refresh scope ("The real-system adapters", What a pack declares) names the list that enumerates it or
     // its retrieve, or says why the vendor offers no read-back; whether every stored resource declares one is
-    // pack-standing's report, not this build's
+    // not this build's to decide
     // (a resource the spec names is read by its own list or retrieve; one the manifest names apart from the spec's, an RPC
     // vendor's, by the list or read the scope names, with `items` where the answer holds them when the spec does not say)
     const specNamed = new Set(ir.resources.map((r) => r.name));
@@ -415,6 +415,9 @@ if (existsSync(manifestPath)) {
             const o = op(r.get);
             if (o?.class === 'retrieve' && ours(o))
                 return [];
+            // A known subject may be addressed by an id query whose native answer is a list envelope.
+            if (r.known && o?.class === 'list' && o.answers?.list && ours(o) && o.method.toUpperCase() === 'GET')
+                return [];
             // a resource the spec does not name (a client-derived spec classes every request an action) is read by the GET
             // the scope names, the answer itself the subject
             if (o && !specNamed.has(name) && !o.resource && String(o.method).toUpperCase() === 'GET')

package/dist/src/gate.js

@@ -19,6 +19,7 @@ import ts from 'typescript';
 import { grade } from "./grade.js";
 import { withCheckoutFiles } from "./protocol-3.js";
 import { isPackArtifact } from "./pack-files.js";
+import { credentialIssuerImports } from "./credential-issuer-import.js";
 /** Every unit of a pack repository: each pack (a directory with a package.json) and each lane in it (a directory with
  *  its own src/manifest.ts and no package.json). */
 export function unitsOf(repo) {
@@ -115,6 +116,7 @@ export function laneRootFailures(dir) {
         failures.push('layout: src/fetch.ts builds no createVendorFetch: the kernel routes a vendor\'s lanes from its manifest, nothing by hand');
     // the root's own files hold to the pack contract as a unit's do (the grade's kernel-contract)
     const beyond = [];
+    const issuerImport = credentialIssuerImports(dir, dir);
     for (const n of existsSync(join(dir, 'src')) ? readdirSync(join(dir, 'src')).filter((x) => /\.tsx?$/.test(x) && !x.endsWith('.d.ts')) : []) {
         // the file's imports as TypeScript reads them, as the grade's kernel-contract does
         for (const from of ts.preProcessFile(readFileSync(join(dir, 'src', n), 'utf8'), true, true).importedFiles.map((i) => i.fileName)) {
@@ -131,6 +133,8 @@ export function laneRootFailures(dir) {
             }
             if (from.startsWith('.') || from === '@volter/world-core' || from === '@volter/world-ui')
                 continue;
+            if (issuerImport(from))
+                continue;
             if (n === 'cli.ts' && (from === '@volter/world-core/args' || from === '@volter/world-core/lifecycle'))
                 continue;
             beyond.push(`src/${n} imports ${from}`);

package/dist/src/index.d.ts

@@ -1,5 +1,5 @@
 export { grade, STANDARDS, type CriterionGrade, type GradeOptions, type StandardGrade } from './grade.js';
-export { conformance, decisionTableProblems, type ConformanceResult, UNIT_FILES, unitFilesMissing } from './conformance.js';
+export { conformance, decisionTableProblems, type ConformanceResult, UNIT_FILES } from './conformance.js';
 export { laneRootFailures, p3Gate, unitsOf } from './gate.js';
 export { conformPublished, gatePublished, vendorOfPackage, type PublishedGate } from './published.js';
 export { handlerName, protocol3, PLANNED, withCheckoutFiles } from './protocol-3.js';

package/dist/src/index.js

@@ -4,7 +4,7 @@
 // of a submission — judges by the same standard at the version it pins. Changing a 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.
 export { grade, STANDARDS } from "./grade.js";
-export { conformance, decisionTableProblems, UNIT_FILES, unitFilesMissing } from "./conformance.js";
+export { conformance, decisionTableProblems, UNIT_FILES } from "./conformance.js";
 export { laneRootFailures, p3Gate, unitsOf } from "./gate.js";
 export { conformPublished, gatePublished, vendorOfPackage } from "./published.js";
 export { handlerName, protocol3, PLANNED, withCheckoutFiles } from "./protocol-3.js";

package/dist/src/lanes.d.ts

@@ -1,3 +1,5 @@
+/** The pack and its manifest-bearing lanes, without crossing another package's boundary. */
+export declare function unitsIn(pack: string): string[];
 /** Metadata such as sources.json is not a derivable API of a vendor whose APIs all belong to its lanes. */
 export declare function hasOwnSurface(pkg: string): boolean;
 /** The lanes over a vendor's state in the vendor's directory `pkg`, wherever its repository is. */

package/dist/src/lanes.js

@@ -3,6 +3,13 @@
 // walked, measured and graded through the vendor's life; every other lane keeps its own.
 import { existsSync, readdirSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
+/** The pack and its manifest-bearing lanes, without crossing another package's boundary. */
+export function unitsIn(pack) {
+    if (!existsSync(pack))
+        return [];
+    return [pack, ...readdirSync(pack).sort().map((name) => join(pack, name))
+            .filter((directory) => !existsSync(join(directory, 'package.json')) && existsSync(join(directory, 'src', 'manifest.ts')))];
+}
 /** Metadata such as sources.json is not a derivable API of a vendor whose APIs all belong to its lanes. */
 export function hasOwnSurface(pkg) {
     if (existsSync(join(pkg, 'src', 'generated', 'surface.gen.json')))

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

@@ -29,6 +29,7 @@ export type PackFacts = {
         demandPathPattern?: string | false;
         key?: string;
         exclude?: true;
+        basic?: string;
     }>;
     hostsNone?: string;
     hostsClaimed?: {
@@ -104,6 +105,8 @@ export type PackFacts = {
         scheme?: string;
         note: string;
     }>;
+    /** The vendor's own requests a World's generated seed makes (see TwinPack.seed). */
+    seed?: TwinPack['seed'];
     /** 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

package/dist/src/pack-facts.js

@@ -42,6 +42,8 @@ function validateHostRules(vendor, rules, vendors, claimedKeys, worldIds) {
         }
         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`);
+        if (rule.basic !== undefined && (typeof rule.basic !== 'string' || !/^[^:\s]+$/.test(rule.basic) || rule.exclude))
+            throw new Error(`pack-facts: ${vendor} host rule ${JSON.stringify(rule)} — basic names a user (no colon, no space) on an included host`);
         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
@@ -230,6 +232,39 @@ export async function compilePackFacts(dirs) {
             }
             facts.sidePorts = pack.sidePorts;
         }
+        if (pack.seed !== undefined) {
+            // ADR 0033 §3: one door per kind of fact, each the vendor's own request at its own host; only a domain's DNS record
+            // is a `/_twin/` stand-in
+            const seed = pack.seed;
+            const door = (value, what, standIn = false) => {
+                let url;
+                try {
+                    url = new URL(String(value));
+                }
+                catch {
+                    throw new Error(`pack-facts: ${vendor} seed ${what} "${String(value)}" is not a URL`);
+                }
+                if (url.protocol !== 'https:')
+                    throw new Error(`pack-facts: ${vendor} seed ${what} is the vendor's own https request`);
+                if (!standIn && url.pathname.startsWith('/_twin/'))
+                    throw new Error(`pack-facts: ${vendor} seed ${what} is the vendor's own request, never a /_twin/ door`);
+            };
+            if (!seed || typeof seed !== 'object' || Array.isArray(seed) || Object.keys(seed).some((k) => k !== 'signUp' && k !== 'domain'))
+                throw new Error(`pack-facts: ${vendor} seed is { signUp?, domain? }`);
+            if (seed.signUp !== undefined)
+                door(seed.signUp, 'signUp');
+            if (seed.domain !== undefined) {
+                const domain = seed.domain;
+                if (!domain || typeof domain !== 'object' || Array.isArray(domain) || Object.keys(domain).sort().join() !== 'add,record,settles,verify')
+                    throw new Error(`pack-facts: ${vendor} seed.domain is { add, record, verify, settles }`);
+                door(domain.add, 'domain.add');
+                door(domain.verify, 'domain.verify');
+                door(domain.record, 'domain.record', true);
+                if (typeof domain.settles !== 'string' || !/^\d+[smhd]$/.test(domain.settles))
+                    throw new Error(`pack-facts: ${vendor} seed.domain.settles is a World-clock time (10m)`);
+            }
+            facts.seed = pack.seed;
+        }
         // 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).
@@ -250,7 +285,7 @@ export async function compilePackFacts(dirs) {
             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.',
+        '//': 'GENERATED by twin-standard facts from the pack descriptor; no prior-artifact entries are retained.',
         packs: sortObject(packs),
         undeclared,
     };