@volter/twin-standard 1.0.91 → 1.0.92

package/src/consumer.ts

@@ -0,0 +1,168 @@
+// The installed customer entry into a pack's life. The CLI owns World lifetime; these are caller steps.
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, statSync, writeFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { basename, dirname, isAbsolute, join, resolve } from 'node:path';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { standardPackageFile } from './package-file.ts';
+
+export type ConsumerRecipe = {
+  schemaVersion: 1;
+  source: string;
+  about: string;
+  files: Record<string, string>;
+  clock?: { at: string; advanceAfterRun?: string };
+  run: string[];
+  retention: { readback: string[] } | { none: string };
+};
+export type ConsumerOptions = { appDir: string; cli: string; artifactIntegrity: string };
+
+/** 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]> = [];
+  const cache = new Set(['journeys/score.json', 'journeys/coverage.json']);
+  const scan = (path: string): void => {
+    if (cache.has(path)) return;
+    const at = join(pack, path);
+    if (statSync(at).isDirectory()) {
+      for (const name of readdirSync(at).sort()) if (name !== 'node_modules') scan(`${path}/${name}`);
+    } else entries.push([path, createHash('sha256').update(readFileSync(at)).digest('hex')]);
+  };
+  for (const name of readdirSync(pack).sort()) {
+    const at = join(pack, name);
+    if (['src', 'spec', 'journeys', 'vendor', 'assets', 'static'].includes(name) || statSync(at).isDirectory() && existsSync(join(at, 'src/manifest.ts'))) scan(name);
+  }
+  return createHash('sha256').update(JSON.stringify(entries)).digest('hex');
+}
+
+/** A pack supplies its own entry journey; older immutable releases use a versioned standard fixture. */
+export function consumerRecipe(vendor: string, packDir?: string): ConsumerRecipe {
+  if (!/^[a-z][a-z0-9-]*$/.test(vendor)) throw new Error('Invalid consumer vendor identity');
+  const root = dirname(fileURLToPath(standardPackageFile('package.json')));
+  const supplied = packDir ? join(packDir, 'journeys/first-use.json') : undefined;
+  const path = supplied && existsSync(supplied) ? supplied : join(root, 'src/clients', `${vendor}.first-use.json`);
+  if (!existsSync(path)) throw new Error(`${vendor} has no installed customer workflow in this standard`);
+  const recipe = JSON.parse(readFileSync(path, 'utf8')) as ConsumerRecipe;
+  const command = (value: unknown): value is string[] => Array.isArray(value) && value.length > 0 && value.every((part) => typeof part === 'string' && part.length > 0);
+  if (recipe.schemaVersion !== 1 || typeof recipe.source !== 'string' || !recipe.source || typeof recipe.about !== 'string' || !recipe.about || !recipe.files || typeof recipe.files !== 'object' || Array.isArray(recipe.files) || !recipe.files['package.json'] || typeof recipe.files['.env.example'] !== 'string' || !command(recipe.run)) throw new Error('Incomplete installed customer workflow');
+  if (!recipe.retention || ('none' in recipe.retention) === ('readback' in recipe.retention) || ('none' in recipe.retention ? typeof recipe.retention.none !== 'string' || !recipe.retention.none.trim() : !command(recipe.retention.readback))) throw new Error('Workflow needs retained-state readback or a stateless explanation');
+  if (recipe.clock && (!Number.isFinite(Date.parse(recipe.clock.at)) || recipe.clock.advanceAfterRun !== undefined && (!/^\d+(?:\.\d+)?[smhd]$/.test(recipe.clock.advanceAfterRun) || !('readback' in recipe.retention)))) throw new Error('Consumer clock needs an instant and, for a stored result, an optional advance before inspection');
+  return recipe;
+}
+
+/** Materialize only a new caller-owned app. Normal dependency installation happens before offline assessment. */
+export function prepareConsumerApp(packDir: string, appDir: string): { recipeSha256: string; dependencies: Record<string, string> } {
+  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 preparation requires one artifact vendor identity');
+  const recipe = consumerRecipe(vendor, packDir);
+  if (existsSync(appDir)) throw new Error('Consumer app must be a new directory');
+  const app = JSON.parse(recipe.files['package.json']!);
+  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 files = Object.entries(recipe.files).map(([path, content]) => {
+    if (isAbsolute(path) || path.includes('\\') || path.split('/').some((part) => !part || part === '.' || part === '..') || 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');
+    return [path, content] as const;
+  });
+  mkdirSync(appDir, { recursive: true });
+  for (const [path, content] of files) {
+    mkdirSync(dirname(join(appDir, path)), { recursive: true });
+    writeFileSync(join(appDir, path), content);
+  }
+  return { recipeSha256: createHash('sha256').update(JSON.stringify(recipe)).digest('hex'), dependencies: app.dependencies ?? {} };
+}
+
+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 packageVersion = (entry: string, name: string): string => {
+    let directory = dirname(entry);
+    while (true) {
+      const file = join(directory, 'package.json');
+      if (existsSync(file)) { const pkg = JSON.parse(readFileSync(file, 'utf8')); if (pkg.name === name) return pkg.version; }
+      const parent = dirname(directory);
+      if (parent === directory) throw new Error(`${name} has no installed package identity`);
+      directory = parent;
+    }
+  };
+  const cliEntry = realpathSync(options.cli);
+  const cliRequire = createRequire(cliEntry);
+  const tools = {
+    '@volter/world': packageVersion(cliEntry, '@volter/world'),
+    '@volter/world-core': packageVersion(cliRequire.resolve('@volter/world-core/runtime'), '@volter/world-core'),
+    '@volter/world-runtime': packageVersion(cliRequire.resolve('@volter/world-runtime'), '@volter/world-runtime'),
+  };
+  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);
+  const commands: Array<{ label: string; argv: string[]; exitCode: number | null; stdout: string; stderr: string }> = [];
+  const failures: string[] = [];
+  const run = async (label: string, args: string[]) => {
+    const result = await new Promise<{ exitCode: number | null; stdout: string; stderr: string }>((done) => {
+      const child = spawn(options.cli, ['world', ...args], { 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 }));
+    });
+    commands.push({ label, argv: [options.cli, 'world', ...args], ...result });
+    if (result.exitCode !== 0) throw new Error(`${label} exited ${result.exitCode}: ${result.stderr.trim().split('\n')[0] ?? ''}`);
+    return result.stdout;
+  };
+  let upAttempted = false;
+  let retainedReadback = false;
+  let teardownVerified = false;
+  try {
+    await run('init', ['init', '--twins', vendor]);
+    const config = JSON.parse(readFileSync(join(options.appDir, '.volter/world.json'), 'utf8'));
+    if (!config.services?.some((service: { source?: { package?: string; version?: string } }) => service.source?.package === metadata.name && service.source?.version === metadata.version)) throw new Error('World init did not select the installed candidate package and exact version');
+    upAttempted = true;
+    await run('up', ['up']);
+    if (recipe.clock) await run('clock-set', ['clock', 'set', recipe.clock.at]);
+    await run('sdk', ['run', '--', ...recipe.run]);
+    if ('readback' in recipe.retention) {
+      if (recipe.clock?.advanceAfterRun) {
+        await run('clock-advance', ['clock', 'advance', recipe.clock.advanceAfterRun]);
+        await run('inspect-timed-result', ['run', '--', ...recipe.retention.readback]);
+      }
+      const before = JSON.parse(await run('log-before-stop', ['log', '--json']));
+      await run('stop', ['down']);
+      await run('resume', ['up']);
+      const resumed = JSON.parse(await run('log-after-resume', ['log', '--json']));
+      if (JSON.stringify(before) !== JSON.stringify(resumed)) throw new Error('Resume changed recorded application state before readback');
+      await run('retained-readback', ['run', '--', ...recipe.retention.readback]);
+      const after = JSON.parse(await run('log-after-readback', ['log', '--json']));
+      if (JSON.stringify(before) !== JSON.stringify(after)) throw new Error('Retained readback added mutations; it must only inspect existing state');
+      retainedReadback = true;
+    }
+  } catch (error) { failures.push((error as Error).message); }
+  finally {
+    if (upAttempted) {
+      try {
+        await run('final-stop', ['down']);
+        const status = JSON.parse(await run('final-status', ['status', '--json']));
+        if (status.running || Object.values(status.services ?? {}).some((service) => (service as { running?: boolean }).running)) throw new Error('Consumer World still reports running compute');
+        teardownVerified = true;
+      } catch (error) { failures.push((error as Error).message); }
+    }
+  }
+  return {
+    measured: true, 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,
+    sourceInputsSha256: consumerSourceDigest(packDir), recipeSha256: createHash('sha256').update(JSON.stringify(recipe)).digest('hex'),
+    fixture: existsSync(join(packDir, 'journeys/first-use.json')) ? 'journeys/first-use.json' : `standard/clients/${vendor}.first-use.json`, appDir: resolve(options.appDir), appName: basename(options.appDir),
+    commands, failures, teardownVerified, retainedReadback,
+    clock: recipe.clock ?? { mode: 'wall' },
+    ...('none' in recipe.retention ? { retentionNotApplicable: recipe.retention.none } : {}),
+    node: process.versions.node, at: new Date().toISOString(),
+  };
+}

package/src/index.ts

@@ -18,3 +18,4 @@ export { assessPack, type AssessmentOptions } from './assessment.ts';
 
 export { createPack } from './create-pack.ts';
 export { verifyBrowserTransport } from './browser-verification.ts';
+export { consumerRecipe, prepareConsumerApp, runConsumerWorkflow, consumerSourceDigest, type ConsumerRecipe, type ConsumerOptions } from './consumer.ts';

package/src/protocol-3.ts

@@ -127,7 +127,7 @@ function srcFileInForm(unit: GradeUnit, name: string): boolean {
 const SEMANTICS_FIXED = new Set(['answer-views.ts', 'states.ts', 'index.ts', 'shared.ts', 'doors.ts', 'seed.ts', 'around.ts', 'events.ts', 'clock.ts', 'tenant.ts', 'scenario.ts', 'gap.ts', 'graphql.ts', 'sockets.ts', 'board.ts']);
 /** journeys/'s closed set. */
 const JOURNEY_FILES = new Set(['customer-life.outline.md', 'customer-life.outline.verdict.json', 'customer-life.json', 'customer-life.verdict.json', 'decisions.json',
-  'vendor-examples.json', 'vendor-examples.verdict.json', 'demand.json', 'unreachable.json', 'score.json', 'coverage.json',
+  'vendor-examples.json', 'vendor-examples.verdict.json', 'demand.json', 'unreachable.json', 'score.json', 'coverage.json', 'first-use.json',
   // a generative pack's life names the World's scenario it walks under (architecture, "Writing a life")
   'scenario.json']);
 /** Only scenario basenames the two walks explicitly declare extend the closed layout. */