@volter/twin-standard 1.0.158 → 1.0.159

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/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

@@ -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/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/protocol-3.js

@@ -25,6 +25,7 @@ import ts from 'typescript';
 import { fileURLToPath } from 'node:url';
 import { sharingLanesIn } from "./lanes.js";
 import { isPackArtifact } from "./pack-files.js";
+import { credentialIssuerImports } from "./credential-issuer-import.js";
 // A path relative to another with '/' between its parts on every platform: git lists files that way, and every rule
 // here compares and splits on '/'; Windows' relative() joins with '\', which hid every lane's files and spec.
 const rel = (from, to) => relative(from, to).split(sep).join('/');
@@ -387,7 +388,7 @@ const criteria = [
     },
     {
         id: 'handler-contract', section: 'form',
-        asks: 'every file in semantics/ reaches no randomness, clock, environment, network or module but the kernel, the states and the shared helpers; each handler file is its family\'s and exports only its operations, named by the fixed rule',
+        asks: 'every file in semantics/ reaches no randomness, clock, environment, network or module but the kernel, the states, the shared helpers and a public subpath of its declared credential issuer pinned at an exact version as a direct runtime dependency; each handler file is its family\'s and exports only its operations, named by the fixed rule',
         check(unit) {
             const dir = join(unit.dir, 'src', 'semantics');
             if (!existsSync(dir))
@@ -395,6 +396,7 @@ const criteria = [
             const ops = operationsOf(unit);
             const families = new Set(ops.values());
             const found = [];
+            const issuerImport = credentialIssuerImports(unit.dir, packageOf(unit));
             for (const f of filesUnder(dir).filter((x) => /\.tsx?$/.test(x) && !TEST_FILE.test(x))) {
                 const text = stripComments(readFileSync(join(dir, f), 'utf8'));
                 const raw = readFileSync(join(dir, f), 'utf8');
@@ -413,7 +415,7 @@ const criteria = [
                     const engineModule = /^\.\.\/engine\/[A-Za-z0-9_-]+\.ts$/.test(from) || vendorPath(unit, from, 3, /^engine\/[A-Za-z0-9_-]+\.ts$/);
                     // a lane over its vendor's state takes the vendor's states and shared helpers ("Pack layout")
                     const vendorShared = vendorPath(unit, from, 3, /^(semantics\/(states|shared)|manifest)\.ts$/);
-                    if (from !== '@volter/world-core' && !/^\.\/(states|shared)\.ts$/.test(from) && !mapImport && !engineModule && !vendorShared)
+                    if (from !== '@volter/world-core' && !/^\.\/(states|shared)\.ts$/.test(from) && !mapImport && !engineModule && !vendorShared && !issuerImport(from))
                         found.push(`${f} imports ${from}`);
                 }
                 // the handler map is typed over the narrow context, so the compiler holds every handler it names to the contract
@@ -546,12 +548,13 @@ const criteria = [
     },
     {
         id: 'kernel-contract', section: 'form',
-        asks: "every file of src/ imports the kernel through its root, the pack contract, and nothing past it: no `@volter/world-core/runtime` or other entry (cli.ts alone takes args and lifecycle), no node builtin, no other package but @volter/world-ui and the generated GraphQL library loader",
+        asks: "every file of src/ imports the kernel through its root, the pack contract, and nothing past it: no `@volter/world-core/runtime` or other entry (cli.ts alone takes args and lifecycle), no node builtin, no other package but @volter/world-ui, a public subpath of its declared credential issuer pinned at an exact version as a direct runtime dependency, and the generated GraphQL library loader",
         check(unit) {
             const src = join(unit.dir, 'src');
             if (!existsSync(src))
                 return fail('src/ is missing');
             const found = [];
+            const issuerImport = credentialIssuerImports(unit.dir, packageOf(unit));
             for (const f of filesUnder(src).filter((x) => /\.tsx?$/.test(x) && !TEST_FILE.test(x) && !x.startsWith('generated/'))) {
                 // the file's imports, re-exports and dynamic imports as TypeScript reads them (a string that only reads like one,
                 // an error message's "from '<name>'", is none)
@@ -596,6 +599,8 @@ const criteria = [
                         continue;
                     if (from === '@volter/world-core' || from === '@volter/world-ui')
                         continue;
+                    if (issuerImport(from))
+                        continue;
                     if (f === 'cli.ts' && (from === '@volter/world-core/args' || from === '@volter/world-core/lifecycle'))
                         continue;
                     found.push(`${f} imports ${from}`);

package/dist/src/spec-documents.d.ts

@@ -4,6 +4,10 @@ export type SpecDocuments = {
 };
 /** The documents of `spec/openapi/`, by name, or undefined when the pack vendors one spec file. */
 export declare function readSpecDocuments(specDir: string): SpecDocuments | undefined;
+/** Response declarations as served, independent of their representation media or generated surface version. */
+export declare function declaredResponseStatuses(specDir: string): Map<string, Set<string>>;
+/** Declared schema fields, including nested objects that are not inferred as generated resources. */
+export declare function schemaFieldNames(specDir: string): Set<string>;
 /** The union of the documents as one OpenAPI document; each contradiction left unpatched is named, by pointer. */
 export declare function mergeDocuments(docs: SpecDocuments): {
     doc: Json;

package/dist/src/spec-documents.js

@@ -9,6 +9,13 @@ import { parse as parseYaml } from 'yaml';
 import { existsSync, readdirSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { gunzipSync } from 'node:zlib';
+import { applySpecPatch } from "./spec-patches.js";
+import { slug } from "./spec-ir.js";
+function readDocument(file) {
+    const bytes = readFileSync(file);
+    const text = (file.endsWith('.gz') ? gunzipSync(bytes) : bytes).toString('utf8');
+    return /\.ya?ml(\.gz)?$/.test(file) ? parseExactJson(JSON.stringify(parseYaml(text, { intAsBigInt: true }), (_, value) => typeof value === 'bigint' ? exactInteger(String(value)) : value)) : parseExactJson(text);
+}
 /** The documents of `spec/openapi/`, by name, or undefined when the pack vendors one spec file. */
 export function readSpecDocuments(specDir) {
     const dir = join(specDir, 'openapi');
@@ -16,14 +23,114 @@ export function readSpecDocuments(specDir) {
         return undefined;
     const documents = {};
     for (const f of readdirSync(dir).filter((f) => /\.(json|ya?ml)(\.gz)?$/.test(f)).sort()) {
-        const bytes = readFileSync(join(dir, f));
-        const text = (f.endsWith('.gz') ? gunzipSync(bytes) : bytes).toString('utf8');
-        documents[f.replace(/\.(json|ya?ml)(\.gz)?$/, '')] = /\.ya?ml(\.gz)?$/.test(f) ? parseExactJson(JSON.stringify(parseYaml(text, { intAsBigInt: true }), (_, v) => typeof v === 'bigint' ? exactInteger(String(v)) : v)) : parseExactJson(text);
+        documents[f.replace(/\.(json|ya?ml)(\.gz)?$/, '')] = readDocument(join(dir, f));
     }
     if (Object.keys(documents).length < 2)
         throw new Error(`${dir}: one API in several documents needs at least two; a single document is spec/openapi.{json,yaml}`);
     return { documents };
 }
+const openapiFiles = ['openapi.json.gz', 'openapi.json', 'openapi.yaml.gz', 'openapi.yaml'];
+function readPatchedDocument(specDir, filenames) {
+    const file = filenames.map((name) => join(specDir, name)).find(existsSync);
+    const documents = file === undefined ? readSpecDocuments(specDir) : undefined;
+    let doc = file === undefined ? documents : readDocument(file);
+    if (doc === undefined)
+        return undefined;
+    const patches = join(specDir, 'patches.json');
+    if (existsSync(patches))
+        for (const patch of readDocument(patches).patches)
+            applySpecPatch(doc, patch);
+    if (documents !== undefined) {
+        const merged = mergeDocuments(doc);
+        if (merged.contradictions.length)
+            throw new Error(`OpenAPI response declarations conflict: ${merged.contradictions.join('; ')}`);
+        doc = merged.doc;
+    }
+    return doc;
+}
+/** Response declarations as served, independent of their representation media or generated surface version. */
+export function declaredResponseStatuses(specDir) {
+    const doc = readPatchedDocument(specDir, openapiFiles);
+    const statuses = new Map();
+    if (doc === undefined)
+        return statuses;
+    for (const [path, item] of Object.entries(doc.paths ?? {})) {
+        for (const [method, operation] of Object.entries(item)) {
+            if (!operation || typeof operation !== 'object' || !operation.responses)
+                continue;
+            statuses.set(operation.operationId || slug(method, path), new Set(Object.keys(operation.responses)));
+        }
+    }
+    return statuses;
+}
+/** Declared schema fields, including nested objects that are not inferred as generated resources. */
+export function schemaFieldNames(specDir) {
+    const doc = readPatchedDocument(specDir, ['smithy.json.gz', 'smithy.json', ...openapiFiles, 'discovery.json.gz', 'discovery.json']);
+    const fields = new Set();
+    if (doc === undefined)
+        return fields;
+    for (const shape of Object.values(doc.shapes ?? {})) {
+        if (shape.type !== 'structure' && shape.type !== 'union')
+            continue;
+        for (const [name, member] of Object.entries(shape.members ?? {})) {
+            fields.add(name);
+            for (const trait of ['smithy.api#jsonName', 'smithy.api#xmlName']) {
+                const wireName = member.traits?.[trait];
+                if (typeof wireName === 'string')
+                    fields.add(wireName);
+            }
+        }
+    }
+    const schema = (node) => {
+        if (Array.isArray(node)) {
+            for (const item of node)
+                schema(item);
+            return;
+        }
+        if (!node || typeof node !== 'object')
+            return;
+        for (const [name, property] of Object.entries(node.properties ?? {})) {
+            fields.add(name);
+            if (typeof property?.xml?.name === 'string')
+                fields.add(property.xml.name);
+            schema(property);
+        }
+        for (const keyword of ['$defs', 'definitions', 'patternProperties', 'dependentSchemas']) {
+            for (const child of Object.values(node[keyword] ?? {}))
+                schema(child);
+        }
+        for (const keyword of ['items', 'additionalItems', 'additionalProperties', 'unevaluatedProperties', 'unevaluatedItems', 'not', 'contains', 'propertyNames', 'if', 'then', 'else', 'allOf', 'anyOf', 'oneOf', 'prefixItems'])
+            schema(node[keyword]);
+    };
+    for (const catalog of [doc.components?.schemas, doc.definitions, doc.schemas]) {
+        for (const node of Object.values(catalog ?? {}))
+            schema(node);
+    }
+    const body = (node) => {
+        schema(node?.schema);
+        for (const media of Object.values(node?.content ?? {}))
+            schema(media?.schema);
+    };
+    for (const catalog of [doc.components?.responses, doc.components?.requestBodies, doc.components?.parameters, doc.components?.headers, doc.responses, doc.parameters]) {
+        for (const node of Object.values(catalog ?? {}))
+            body(node);
+    }
+    for (const paths of [doc.paths, doc.webhooks, doc.components?.pathItems]) {
+        for (const item of Object.values(paths ?? {})) {
+            for (const parameter of item.parameters ?? [])
+                body(parameter);
+            for (const method of ['get', 'put', 'post', 'delete', 'patch', 'head', 'options', 'trace']) {
+                const operation = item[method];
+                for (const parameter of operation?.parameters ?? [])
+                    body(parameter);
+                body(operation?.requestBody);
+                for (const response of Object.values(operation?.responses ?? {}))
+                    body(response);
+            }
+        }
+    }
+    return fields;
+}
 /** A node without its words (description, summary, examples, and the tags a document files it under): what two
  *  documents must agree on. */
 const substance = (n) => JSON.stringify(n, (k, v) => (['description', 'summary', 'example', 'examples', 'x-mint', 'tags'].includes(k) ? undefined : v && typeof v === 'object' && !Array.isArray(v) ? Object.fromEntries(Object.entries(v).sort(([a], [b]) => a.localeCompare(b))) : v));