@volter/twin-standard 1.0.158 → 1.0.159

package/src/consumer.ts

@@ -19,13 +19,28 @@ export type ConsumerRecipe = {
 };
 export type ConsumerOptions = { appDir: string; cli: string; artifactIntegrity: string };
 type ConsumerInstallation = { cli: string; artifact?: string };
+export type ConsumerResult = Awaited<ReturnType<typeof runConsumerWorkflow>>;
+
+function recipeDependencies(recipe: ConsumerRecipe): Record<string, string> {
+  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: string, name: string): { directory: string; version: string } {
   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;
   }
@@ -39,6 +54,21 @@ function consumerTools(cli: string) {
   };
 }
 
+function consumerEntries(directory: string, names: string[]): Map<string, string> {
+  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) as string[];
+  return new Map(names.map((name, index) => [name, fileURLToPath(entries[index]!)]));
+}
+
+function consumerPeerVersions(metadata: { dependencies?: Record<string, string>; optionalDependencies?: Record<string, string>; peerDependencies?: Record<string, string>; peerDependenciesMeta?: Record<string, { optional?: boolean }> }, cli: string, sdkDependencies: Record<string, string>): Record<string, string> {
+  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: string): string {
   const entries: Array<[string, string]> = [];
@@ -83,9 +113,7 @@ export function prepareConsumerApp(packDir: string, appDir: string, installation
   app.packageManager = 'pnpm@12.15.0';
   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}`);
     if (typeof content !== 'string') throw new Error('Consumer files must contain text');
@@ -96,7 +124,7 @@ export function prepareConsumerApp(packDir: string, appDir: string, installation
     const tools = consumerTools(installation.cli);
     if (installation.artifact && (!isAbsolute(installation.artifact) || !statSync(installation.artifact).isFile())) 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']);
@@ -118,40 +146,56 @@ export function prepareConsumerApp(packDir: string, appDir: string, 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: string[], appDir: string, env: NodeJS.ProcessEnv, signal?: AbortSignal): Promise<{ exitCode: number | null; stdout: string; stderr: string }> {
+  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: string, options: ConsumerOptions) {
   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');
   if (existsSync(join(options.appDir, '.volter/world.json'))) throw new Error('Consumer app already has a World; prepare a new app rather than reusing prior state');
   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]] as const) {
+  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)] as const);
+  for (const [name, identity] of [[metadata.name, candidate], ['@volter/world-core', kernel], ...peers] as const) {
     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`);
   }
   const appLock = dependencyLock(appRoot), appLockBytes = appLock.bytes;
   if (candidate.version !== metadata.version || appLock.entry(metadata.name)?.integrity !== options.artifactIntegrity) 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: Array<{ label: string; argv: string[]; exitCode: number | null; stdout: string; stderr: string }> = [];
   const failures: string[] = [];
   const compiledCli = /\.[cm]?js$/.test(cliEntry);
   let nodeVersion: string | null = null;
   const execute = async (label: string, executable: string, argv: string[]) => {
-    const result = await new Promise<{ exitCode: number | null; stdout: string; stderr: string }>((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] ?? ''}`);
     return result.stdout;
@@ -213,7 +257,7 @@ export async function runConsumerWorkflow(packDir: string, options: ConsumerOpti
     }
   }
   return {
-    measured: true, passed: failures.length === 0 && teardownVerified,
+    measured: true as const, passed: failures.length === 0 && teardownVerified,
     scope: 'Exact installed artifact; normal CLI initialization, unchanged SDK, result assertions and retained-state read-only resume where applicable',
     package: metadata.name, version: metadata.version, integrity: options.artifactIntegrity,
     tools, application,
@@ -227,3 +271,21 @@ export async function runConsumerWorkflow(packDir: string, options: ConsumerOpti
     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: string, vendor: string, sdks: string[], result?: ConsumerResult): { failures: string[]; note?: string } {
+  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/src/credential-issuer-import.ts

@@ -0,0 +1,38 @@
+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: ts.Expression | undefined, name: string): ts.Expression | undefined {
+  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: string, packageDir: string): (specifier: string) => boolean {
+  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')) as { name?: string; dependencies?: Record<string, string> };
+  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/src/derive.ts

@@ -312,7 +312,7 @@ if (existsSync(manifestPath)) {
   // (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));
-  const scopes = Object.entries(manifest.resources as Record<string, { storedAs?: string; refresh?: { list?: string; get?: string; none?: string; items?: string; detail?: string } }>).flatMap(([name, decl]) => {
+  const scopes = Object.entries(manifest.resources as Record<string, { storedAs?: string; refresh?: { list?: string; get?: string; known?: boolean; none?: string; items?: string; detail?: string } }>).flatMap(([name, decl]) => {
     const r = decl.refresh;
     if (!r) return [];
     if ('graphql' in r && r.graphql) {
@@ -363,6 +363,8 @@ if (existsSync(manifestPath)) {
     if (r.get !== undefined) {
       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') return [];

package/src/gate.ts

@@ -19,6 +19,7 @@ import ts from 'typescript';
 import { grade, type GradeOptions } from './grade.ts';
 import { withCheckoutFiles } from './protocol-3.ts';
 import { isPackArtifact } from './pack-files.ts';
+import { credentialIssuerImports } from './credential-issuer-import.ts';
 
 /** 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). */
@@ -102,6 +103,7 @@ export function laneRootFailures(dir: string): string[] {
   if (!/\bcreateVendorFetch\(/.test(src('fetch.ts'))) 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: string[] = [];
+  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)) {
@@ -111,6 +113,7 @@ export function laneRootFailures(dir: string): string[] {
       if (/^\.\.\/[^/]+\/src\//.test(from) && n !== 'fetch.ts' && !laneData) { beyond.push(`src/${n} imports ${from}: only src/fetch.ts reaches a lane`); continue; }
       if (n === 'manifest.ts' && from !== '@volter/world-core') { beyond.push(`src/manifest.ts imports ${from}: the manifest is data`); continue; }
       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/src/lanes.ts

@@ -4,6 +4,13 @@
 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: string): string[] {
+  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: string): boolean {
   if (existsSync(join(pkg, 'src', 'generated', 'surface.gen.json'))) return true;

package/src/protocol-3.ts

@@ -17,6 +17,7 @@ import ts from 'typescript';
 import { fileURLToPath } from 'node:url';
 import { sharingLanesIn } from './lanes.ts';
 import { isPackArtifact } from './pack-files.ts';
+import { credentialIssuerImports } from './credential-issuer-import.ts';
 import type { Criterion, GradeUnit, Standard } from './types.ts';
 
 // A path relative to another with '/' between its parts on every platform: git lists files that way, and every rule
@@ -340,13 +341,14 @@ const criteria: Criterion[] = [
   },
   {
     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)) return pass('no handlers');
       const ops = operationsOf(unit);
       const families = new Set(ops.values());
       const found: string[] = [];
+      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');
@@ -363,7 +365,7 @@ const criteria: Criterion[] = [
           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) found.push(`${f} imports ${from}`);
+          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
         if (f === 'index.ts' && !/:\s*Record<\s*string\s*,\s*Handler\s*>/.test(text)) found.push('index.ts does not type its handler map Record<string, Handler>');
@@ -468,11 +470,12 @@ const criteria: Criterion[] = [
   },
   {
     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: string[] = [];
+      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)
@@ -512,6 +515,7 @@ const criteria: Criterion[] = [
         for (const from of specifiers) {
           if (from.startsWith('.')) 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/src/spec-documents.ts

@@ -10,24 +10,113 @@ 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, type SpecPatch } from './spec-patches.ts';
+import { slug } from './spec-ir.ts';
 
 type Json = any;
 export type SpecDocuments = { documents: Record<string, Json> };
 
+function readDocument(file: string): Json {
+  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: string): SpecDocuments | undefined {
   const dir = join(specDir, 'openapi');
   if (!existsSync(dir)) return undefined;
   const documents: Record<string, Json> = {};
   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: string, filenames: string[]): Json | undefined {
+  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) as { patches: SpecPatch[] }).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: string): Map<string, Set<string>> {
+  const doc = readPatchedDocument(specDir, openapiFiles);
+  const statuses = new Map<string, Set<string>>();
+  if (doc === undefined) return statuses;
+  for (const [path, item] of Object.entries(doc.paths ?? {}) as Array<[string, Record<string, { operationId?: string; responses?: Record<string, unknown> }>]>) {
+    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: string): Set<string> {
+  const doc = readPatchedDocument(specDir, ['smithy.json.gz', 'smithy.json', ...openapiFiles, 'discovery.json.gz', 'discovery.json']);
+  const fields = new Set<string>();
+  if (doc === undefined) return fields;
+  for (const shape of Object.values(doc.shapes ?? {}) as Json[]) {
+    if (shape.type !== 'structure' && shape.type !== 'union') continue;
+    for (const [name, member] of Object.entries(shape.members ?? {}) as Array<[string, Json]>) {
+      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: Json): void => {
+    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 ?? {}) as Array<[string, Json]>) {
+      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: Json): void => {
+    schema(node?.schema);
+    for (const media of Object.values(node?.content ?? {}) as Json[]) 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 ?? {}) as Json[]) {
+      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): string => 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));

package/src/tools/life-coverage-walk.ts

@@ -6,9 +6,9 @@ import { parseExactJson } from '@volter/world-core/exact-json';
 // is its precondition, not what it measures. This module is no test file itself, so a published package holds it.
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { listActions, observeTransitions, stateOf, type Actor, type DerivedManifest, type Transition } from '@volter/world-core/runtime';
+import { listActions, observeTransitions, stateOf, type Actor, type DerivedManifest, type ErrorSpec, type Transition } from '@volter/world-core/runtime';
 import { inMemoryWorld, walk, type Failure, usePacks } from '../walk/behavior-journey.ts';
-import { lanesOf, shapeChecker } from '../walk/shape.ts';
+import { lanesOf, lineShape, shapeChecker } from '../walk/shape.ts';
 import { sharingLanesIn } from '../lanes.ts';
 
 /** Registers, in the `bun test` run that imports it, the walks of `vendor` in the pack repository at `PACKS`. */
@@ -30,9 +30,12 @@ for (const [n, w] of walks.entries()) test(`${vendor}: ${w.file} walks`, async (
   const { manifest } = (await import(join(PACKS, vendor, 'src', 'manifest.ts'))) as { manifest: DerivedManifest };
   // the lanes over the vendor's state its serve factory serves are walked by this life, their machines with the vendor's
   // ("Pack layout"); two manifests naming one resource's field would collide in the keys below, so that refuses
-  const laneManifests = await Promise.all(sharingLanes(vendor).map(async (l) => ((await import(join(PACKS, vendor, l, 'src', 'manifest.ts'))) as { manifest: DerivedManifest }).manifest));
+  const units = [{ dir: join(PACKS, vendor), manifest, lane: undefined }, ...await Promise.all(sharingLanes(vendor).map(async (l) => {
+    const dir = join(PACKS, vendor, l);
+    return { dir, lane: l, manifest: ((await import(join(dir, 'src', 'manifest.ts'))) as { manifest: DerivedManifest }).manifest };
+  }))];
   // a vendor of lanes' root (a VendorManifest) declares no resources of its own: its lanes do
-  const allResources = [manifest, ...laneManifests].flatMap((mf) => Object.entries(mf.resources ?? {}));
+  const allResources = units.flatMap(({ manifest: mf }) => Object.entries(mf.resources ?? {}));
   const machines = new Map<string, unknown>();
   for (const [resource, decl] of allResources) for (const [field, machine] of Object.entries(decl.state ?? {})) {
     const name = `${resource}.${field}`;
@@ -42,20 +45,25 @@ for (const [n, w] of walks.entries()) test(`${vendor}: ${w.file} walks`, async (
     machines.set(name, machine);
   }
   const where = new Map<Transition, Array<{ at: string; field: string; type: string; service: string }>>();
-  for (const mf of [manifest, ...laneManifests]) for (const [resource, decl] of Object.entries(mf.resources ?? {})) {
-    for (const [field, m] of Object.entries(decl.state ?? {})) m.transitions.forEach((t, i) => {
-      const place = { at: `${resource}.${field}#${i}`, field, type: decl.storedAs ?? resource, service: mf.service ?? mf.vendor };
-      const places = where.get(t) ?? [];
-      if (!places.some((p) => p.at === place.at && p.type === place.type && p.service === place.service)) where.set(t, [...places, place]);
-    });
+  const httpTransitions = new Set<Transition>();
+  for (const { dir, manifest: mf } of units) {
+    const http = !lineShape(dir);
+    for (const [resource, decl] of Object.entries(mf.resources ?? {})) {
+      for (const [field, m] of Object.entries(decl.state ?? {})) m.transitions.forEach((t, i) => {
+        if (http) httpTransitions.add(t);
+        const place = { at: `${resource}.${field}#${i}`, field, type: decl.storedAs ?? resource, service: mf.service ?? mf.vendor };
+        const places = where.get(t) ?? [];
+        if (!places.some((p) => p.at === place.at && p.type === place.type && p.service === place.service)) where.set(t, [...places, place]);
+      });
+    }
   }
   const moves = new Map<string, Array<{ transition: Transition; from: string; field: string; actor: Actor; subject: string }>>();
   const subjectKey = (service: string, type: string, id: string): string => JSON.stringify([service, type, id]);
   observeTransitions((_decl, t, outcome, from, entry) => {
     const places = where.get(t) ?? [];
     if (outcome === 'refused') {
-      // A failed check on an already committed write is no refusal the application received.
-      if (entry) return;
+      // HTTP refusals are credited from their received status and body; a line protocol owns its session's replies.
+      if (entry || httpTransitions.has(t)) return;
       const groups = new Set(places.map((p) => JSON.stringify([p.service, p.type, p.field])));
       if (groups.size === 1) for (const p of places) seen.add(`${p.at}|refused|${from}`);
       return;
@@ -79,12 +87,14 @@ for (const [n, w] of walks.entries()) test(`${vendor}: ${w.file} walks`, async (
   const root = world.root();
   // what each step was answered, by the spec operation it called: a refusal is seen at the wire, whichever code gave it
   const shape = await shapeChecker(join(PACKS, vendor));
-  const answered: Array<{ op: string; text: string; body: unknown }> = [];
+  const answered: Array<{ op: string; lane?: string; status: number; body: unknown }> = [];
   try {
-    await walk(life, root, failures, { beats: w.beats, hooks: { after: (step, path, answer) => {
+    await walk(life, root, failures, { beats: w.beats, hooks: { after: (_step, _path, answer) => {
       // a line step's refusals are the machine's own (observeTransitions); a request's are read off its answer
-      const op = 'method' in step ? shape?.operationOf(step.method, path, { ...(life.headers ?? {}), ...(step.headers ?? {}) })?.op.id : undefined;
-      if (op) answered.push({ op, text: JSON.stringify(answer.body ?? ''), body: answer.body });
+      const request = answer.request;
+      if (!request) return;
+      const hit = shape?.operationOf(request.method, request.url, request.headers);
+      if (hit) answered.push({ op: hit.op.id, lane: hit.lane, status: answer.status, body: answer.wireBody });
     } } });
     // a declared refusal is reached when a step on its operation was answered with it: its code, or its message
     // up to the first placeholder
@@ -92,13 +102,13 @@ for (const [n, w] of walks.entries()) test(`${vendor}: ${w.file} walks`, async (
     const holds = (value: unknown, code: string): boolean => (value !== null && typeof value === 'object'
       ? Object.values(value as Record<string, unknown>).some((v) => holds(v, code))
       : (typeof value === 'string' || typeof value === 'number') && String(value) === code);
-    const answers = (a: { text: string; body: unknown }, r: { code?: string | number; message: string }): boolean =>
-      r.code !== undefined ? holds(a.body, String(r.code)) : a.text.includes(r.message.split('{')[0]!.trim());
-    for (const [resource, decl] of allResources) {
+    const answers = (a: { status: number; body: unknown }, r: ErrorSpec): boolean =>
+      a.status === r.status && (r.code !== undefined ? holds(a.body, String(r.code)) : JSON.stringify(a.body)?.includes(r.message.split('{')[0]!.trim()) === true);
+    for (const { manifest: mf, lane } of units) for (const [resource, decl] of Object.entries(mf.resources ?? {})) {
       for (const [field, m] of Object.entries(decl.state ?? {})) {
         m.transitions.forEach((t, i) => {
           if (!t.operation) return;
-          const on = answered.filter((a) => a.op === t.operation);
+          const on = answered.filter((a) => a.op === t.operation && a.lane === lane);
           if (t.refusal && on.some((a) => answers(a, t.refusal!))) seen.add(`${resource}.${field}#${i}|refused|*`);
           for (const [from, r] of Object.entries(t.refusals ?? {})) if (on.some((a) => answers(a, r))) seen.add(`${resource}.${field}#${i}|refused|${from}`);
         });
@@ -108,13 +118,13 @@ for (const [n, w] of walks.entries()) test(`${vendor}: ${w.file} walks`, async (
     // transition that allows it (from its state to the next, by its operation when both name one); a change no
     // transition allows is an undeclared move
     const fieldsOf = new Map<string, Array<[string, string, (typeof manifest.resources)[string]['state'] extends infer S ? S extends Record<string, infer F> ? F : never : never]>>();
-    for (const mf of [manifest, ...laneManifests]) for (const [resource, decl] of Object.entries(mf.resources ?? {})) {
+    for (const { manifest: mf } of units) for (const [resource, decl] of Object.entries(mf.resources ?? {})) {
       const key = JSON.stringify([mf.service ?? mf.vendor, decl.storedAs ?? resource]);
       for (const [field, m] of Object.entries(decl.state ?? {})) fieldsOf.set(key, [...(fieldsOf.get(key) ?? []), [resource, field, m]]);
     }
     const current = new Map<string, Record<string, unknown>>();
     // the services the life wrote: the vendor's, or its lanes' (a vendor of lanes' root names none of its own)
-    const services = [...new Set([manifest, ...laneManifests].map((mf) => mf.service).filter((x): x is string => typeof x === 'string'))];
+    const services = [...new Set(units.map(({ manifest: mf }) => mf.service).filter((x): x is string => typeof x === 'string'))];
     if (!services.length) services.push(manifest.vendor);
     for (const a of services.flatMap((service) => listActions(service, root))) {
       if (a.op !== 'set' || !a.fields) continue;

package/src/tools/score-pack.ts

@@ -3,7 +3,7 @@
 // life per pack is walked through the pack's own fetch on the in-memory World, and the report says:
 //   - the life: whether a judge's plausible verdict names its current content (a verdict its author wrote is not one);
 //   - correctness: every check on every step (status, expectations, captures, SHAPE, the beats) and the life
-//     answering byte for byte the same on a second fresh World;
+//     answering the same on a second fresh World under its declared engine outputs;
 //   - coverage: the hand-written code the life and the vendor's published examples run and the declared state logic
 //     they reach (life-coverage.ts), with what they never reach;
 //   - the vendor's published examples: replayed and judged (vendor-examples.ts);
@@ -27,6 +27,7 @@ import { dirname, join, sep } from 'node:path';
 import { inMemoryWorld, walk, withPinnedWorldDraws, type Failure, usePacks } from '../walk/behavior-journey.ts';
 import { expandFills, waitMs, type Journey } from '../walk/journey-kit.ts';
 import { vendorFetch, vendorStream } from '../walk/vendor-fetch.ts';
+import { compareReplays, type ReplayStep } from '../walk/replay.ts';
 import { existenceProbe } from '../walk/journey-kit.ts';
 import { kernelCheckout, packsRoot, toolPath } from './packs-root.ts';
 const PACKS = packsRoot();
@@ -73,10 +74,10 @@ const judged = life.steps.length === 0 || !verdict ? 'unjudged' : dependent ? de
 const world = inMemoryWorld(`score-${vendor}`);
 const failures: Failure[] = [];
 await walk(life, world.root(), failures, { beats: true });
-const answers = async (): Promise<string[]> => {
-  const seen: string[] = [];
+const answers = async (): Promise<ReplayStep[]> => {
+  const seen: ReplayStep[] = [];
   // the World's own draws (its seed, its keys) are the same in both: two Worlds differ only by what is beyond them (R9)
-  await withPinnedWorldDraws(() => walk(life, world.root(), [], { beats: false, hooks: { after: (step, p, a) => seen.push(`${(step as { name?: string }).name ?? ''}\u0000${p} ${a.status} ${JSON.stringify(a.body)}`) } }));
+  await withPinnedWorldDraws(() => walk(life, world.root(), failures, { beats: false, hooks: { after: (step, path, answer) => seen.push({ name: step.name ?? '', path, status: answer.status, body: answer.body, ...(answer.sql ? { sql: answer.sql } : {}), ...(answer.connection ? { connection: answer.connection } : {}) }) } }));
   return seen;
 };
 const [first, second] = [await answers(), await answers()];
@@ -166,8 +167,8 @@ const flags: Flag[] = [];
     }
   }
 }
-const differs = first.findIndex((line, i) => line !== second[i]);
-if (differs >= 0 || first.length !== second.length) failures.push({ step: '(whole life)', beat: 'REPLAYABLE', detail: `a second fresh World answered differently at "${(first[differs] ?? second[differs] ?? first.at(-1) ?? '').split('\u0000')[0]}" (the ${differs + 1}th answered step; waits are not counted)` });
+const replayComparison = compareReplays(first, second);
+for (const detail of replayComparison.diagnostics) failures.push({ step: '(whole life)', beat: 'REPLAYABLE', detail });
 
 // ── breadth ──────────────────────────────────────────────────────────────────────────────────
 const factory = await vendorFetch(PACKS, vendor);