@volter/twin-standard 1.0.161 → 1.0.162

package/dist/src/clients/anthropic-messages.js

@@ -1,10 +1,10 @@
 const MESSAGES = 'https://platform.claude.com/docs/en/api/messages';
 const TOOLS = [{ name: 'lookup', input_schema: { type: 'object', properties: {} } }];
 export function messagesCases(v) {
-    const SCRIPT = { handlers: [
-            { id: 'calls', on: { hasTool: 'lookup' }, respond: v.toolTurn },
-            { id: 'words', on: { userTextIncludes: 'hello' }, respond: { text: 'scripted words' } },
-        ] };
+    const SCRIPT = [
+        { on: { hasTool: 'lookup' }, outcome: v.toolTurn },
+        { on: { userTextIncludes: 'hello' }, outcome: { text: 'scripted words' } },
+    ];
     const ask = async (c, extra = {}) => {
         const { default: Anthropic } = await import('@anthropic-ai/sdk');
         const client = new Anthropic({ apiKey: c.env[v.key] ?? '', baseURL: v.base(c.host), fetch: c.fetch, maxRetries: 0, timeout: 10_000 });
@@ -41,9 +41,9 @@ export function messagesCases(v) {
             asks: "the World's scenario rewritten between two turns decides the second (no reboot)",
             source: 'architecture "The scenario is read from the World\'s store at every turn"',
             async run(c) {
-                c.scenario({ handlers: [{ id: 'one', on: { userTextIncludes: 'hello' }, respond: { text: 'first script' } }] });
+                c.scenario([{ on: { userTextIncludes: 'hello' }, outcome: { text: 'first script' } }]);
                 const first = await ask(c).then(text, (e) => `error ${e.message}`);
-                c.scenario({ handlers: [{ id: 'two', on: { userTextIncludes: 'hello' }, respond: { text: 'second script' } }] });
+                c.scenario([{ on: { userTextIncludes: 'hello' }, outcome: { text: 'second script' } }]);
                 const second = await ask(c).then(text, (e) => `error ${e.message}`);
                 return first === 'first script' && second === 'second script' ? [] : [`the turns answered "${first}" then "${second}"`];
             },

package/dist/src/clients/gemini.js

@@ -22,7 +22,7 @@ export const cases = [
         source: `${REFERENCE} "a stream of GenerateContentResponse instances"`,
         async run(c) {
             return routed(c, async () => {
-                c.scenario({ handlers: [{ id: 'words', on: { userTextIncludes: 'workshop' }, respond: { text: 'A scripted workshop reply.' } }] });
+                c.scenario([{ on: { userTextIncludes: 'workshop' }, outcome: { text: 'A scripted workshop reply.' } }]);
                 const result = await (await chat(c)).generateContentStream('Plan the workshop.');
                 let text = '';
                 for await (const chunk of result.stream)
@@ -40,10 +40,10 @@ export const cases = [
         async run(c) {
             return routed(c, async () => {
                 const { SchemaType } = await import('@google/generative-ai');
-                c.scenario({ handlers: [
-                        { id: 'returned', on: { toolResultFor: 'lookup_company', lastMessageIsToolResult: true }, respond: { text: 'Tidewater renewal is in October.' } },
-                        { id: 'lookup', on: { hasTool: 'lookup_company' }, respond: { functionCalls: [{ name: 'lookup_company', args: { company: 'Tidewater' } }] } },
-                    ] });
+                c.scenario([
+                    { on: { toolResultFor: 'lookup_company', lastMessageIsToolResult: true }, outcome: { text: 'Tidewater renewal is in October.' } },
+                    { on: { hasTool: 'lookup_company' }, outcome: { functionCalls: [{ name: 'lookup_company', args: { company: 'Tidewater' } }] } },
+                ]);
                 const session = (await chat(c)).startChat({ tools: [{ functionDeclarations: [{ name: 'lookup_company', parameters: { type: SchemaType.OBJECT, properties: { company: { type: SchemaType.STRING } }, required: ['company'] } }] }] });
                 const first = await session.sendMessage('Find the company renewal.');
                 const call = first.response.functionCalls()?.[0];
@@ -78,9 +78,9 @@ export const cases = [
         async run(c) {
             return routed(c, async () => {
                 const { GoogleGenAI } = await import('@google/genai');
-                c.scenario({ handlers: [{ id: 'picture', on: { userTextIncludes: 'square illustration' }, respond: {
-                                text: 'A synthetic square illustration.', parts: [{ inlineData: { mimeType: 'image/png', data: PNG } }],
-                            } }] });
+                c.scenario([{ on: { userTextIncludes: 'square illustration' }, outcome: {
+                            text: 'A synthetic square illustration.', parts: [{ inlineData: { mimeType: 'image/png', data: PNG } }],
+                        } }]);
                 const ai = new GoogleGenAI({ apiKey: c.env.GEMINI_API_KEY ?? '', httpOptions: { baseUrl: `https://${c.host}` } });
                 const response = await ai.models.generateContent({ model: 'gemini-3.1-flash-image', contents: 'Make a square illustration.', config: { responseModalities: ['TEXT', 'IMAGE'] } });
                 const image = response.candidates?.[0]?.content?.parts?.find((p) => p.inlineData)?.inlineData;

package/dist/src/clients/harness.d.ts

@@ -14,8 +14,16 @@ export type ClientContext = {
     /** an HTTPS agent as a World routes it, for a client that takes an agent (Slack's, Stripe's): its connections reach the
      *  served port, the client's URL and Host unchanged */
     agent: HttpsAgent;
-    /** writes the World's scenario file (read at the pack's next turn) */
-    scenario: (doc: unknown) => void;
+    /** plays the World's scenario (read at the pack's next request): the model vendor's turns, each a decision at its
+     *  `turn` point keyed by `on` (the pack's turn matchers) with `outcome` its answer, holding from the scenario's start;
+     *  playing another replaces it */
+    scenario: (turns: ScriptedTurn[]) => void;
+};
+/** A model vendor's scripted turn: a decision `{ point: 'turn', on, outcome, once? }` (ADR 0036) of the case's vendor. */
+export type ScriptedTurn = {
+    on: Record<string, unknown>;
+    outcome: unknown;
+    once?: boolean;
 };
 /** One expectation of the vendor's documented behaviour, driven through its client. */
 export type ClientCase = {
@@ -59,4 +67,7 @@ export declare function servedHttpFetch(port: number): typeof fetch;
 /** The context for a pack reached at `port` of this machine (the World's proxy in front of it). */
 /** `raw`: a raw protocol's served port (SMTP's listener), which a connection reaches directly, as a World passes a raw TCP
  *  connection through untouched; the proxy speaks HTTP only. */
-export declare function clientContext(port: number, host: string, env: Record<string, string>, scenarioPath: string, raw?: number): ClientContext;
+export declare function clientContext(port: number, host: string, env: Record<string, string>, scenario: {
+    vendor: string;
+    file: string;
+}, raw?: number): ClientContext;

package/dist/src/clients/harness.js

@@ -8,6 +8,8 @@ import { createServer, request as httpRequest } from 'node:http';
 import { Agent as HttpsAgent } from 'node:https';
 import { connect } from 'node:net';
 import { writeFileSync } from 'node:fs';
+/** Where a case's scenario starts, every entry with it: long before any clock the served pack keeps, so each holds at once. */
+const HELD_FROM = '2000-01-01T00:00:00.000Z';
 /** The World's proxy in front of a pack served on `served`: it ends the caller's TLS (here, none was begun) and forwards
  *  each request and socket upgrade to the pack with `x-forwarded-proto: https`, the vendor's Host unchanged, as a World's
  *  proxy forwards a caller of the vendor's https host (twin-fetch.ts, twinPublicBase: the links and socket URLs the pack
@@ -249,13 +251,18 @@ export function servedHttpFetch(port) {
 /** The context for a pack reached at `port` of this machine (the World's proxy in front of it). */
 /** `raw`: a raw protocol's served port (SMTP's listener), which a connection reaches directly, as a World passes a raw TCP
  *  connection through untouched; the proxy speaks HTTP only. */
-export function clientContext(port, host, env, scenarioPath, raw) {
+export function clientContext(port, host, env, scenario, raw) {
     const agent = new (class extends HttpsAgent {
         createConnection() { return connect(port, '127.0.0.1'); }
     })({ keepAlive: false });
     return {
         host, env, fetch: servedHttpFetch(port), agent,
         connect: () => connect(raw ?? port, '127.0.0.1'),
-        scenario: (doc) => writeFileSync(scenarioPath, JSON.stringify(doc)),
+        // written as a World resolves a document whose every entry is at `0s`: the cases run in Node, whose type stripping
+        // does not load the kernel's source entry (its parameter properties), so they write the resolved form it reads
+        scenario: (turns) => writeFileSync(scenario.file, JSON.stringify({
+            name: 'client-case', start: HELD_FROM, random: 'client-case',
+            timeline: turns.map((t, i) => ({ at: HELD_FROM, decision: { vendor: scenario.vendor, point: 'turn', on: t.on, outcome: t.outcome, ...(t.once === undefined ? {} : { once: t.once }) }, index: i + 1 })),
+        })),
     };
 }

package/dist/src/clients/openai-compatible.js

@@ -1,9 +1,9 @@
 const CHAT = 'https://developers.openai.com/api/reference/resources/chat/subresources/completions/methods/create';
 const TOOLS = [{ type: 'function', function: { name: 'lookup', parameters: { type: 'object', properties: {} } } }];
-const SCRIPT = { handlers: [
-        { id: 'calls', on: { hasTool: 'lookup' }, respond: { toolCalls: [{ name: 'lookup', arguments: {} }] } },
-        { id: 'words', on: { userTextIncludes: 'hello' }, respond: { text: 'scripted words' } },
-    ] };
+const SCRIPT = [
+    { on: { hasTool: 'lookup' }, outcome: { toolCalls: [{ name: 'lookup', arguments: {} }] } },
+    { on: { userTextIncludes: 'hello' }, outcome: { text: 'scripted words' } },
+];
 export async function openaiClient(c, v) {
     const { default: OpenAI } = await import('openai');
     return new OpenAI({ apiKey: c.env[v.key] ?? '', baseURL: v.base(c.host), fetch: c.fetch, maxRetries: 0, timeout: 10_000 });
@@ -40,9 +40,9 @@ export function chatCases(v) {
             asks: "the World's scenario rewritten between two turns decides the second (no reboot)",
             source: 'architecture "The scenario is read from the World\'s store at every turn"',
             async run(c) {
-                c.scenario({ handlers: [{ id: 'one', on: { userTextIncludes: 'hello' }, respond: { text: 'first script' } }] });
+                c.scenario([{ on: { userTextIncludes: 'hello' }, outcome: { text: 'first script' } }]);
                 const first = await ask(c).then((a) => a.choices?.[0]?.message?.content, (e) => `error ${e.message}`);
-                c.scenario({ handlers: [{ id: 'two', on: { userTextIncludes: 'hello' }, respond: { text: 'second script' } }] });
+                c.scenario([{ on: { userTextIncludes: 'hello' }, outcome: { text: 'second script' } }]);
                 const second = await ask(c).then((a) => a.choices?.[0]?.message?.content, (e) => `error ${e.message}`);
                 return first === 'first script' && second === 'second script' ? [] : [`the turns answered "${first}" then "${second}"`];
             },

package/dist/src/clients/openai.js

@@ -8,10 +8,10 @@ async function client(c) {
 }
 const TOOLS = [{ type: 'function', function: { name: 'lookup', parameters: { type: 'object', properties: {} } } }];
 // a turn that calls the tool wherever one is offered, and one that answers in words
-const SCRIPT = { handlers: [
-        { id: 'calls', on: { hasTool: 'lookup' }, respond: { toolCalls: [{ name: 'lookup', arguments: {} }] } },
-        { id: 'words', on: { userTextIncludes: 'hello' }, respond: { text: 'scripted words' } },
-    ] };
+const SCRIPT = [
+    { on: { hasTool: 'lookup' }, outcome: { toolCalls: [{ name: 'lookup', arguments: {} }] } },
+    { on: { userTextIncludes: 'hello' }, outcome: { text: 'scripted words' } },
+];
 /** A Realtime session through the client (openai-node's server-side Realtime client, on the ws library, as a Node
  *  application opens it), until its response is done: its first event and the output items' types, or what went wrong. */
 async function realtimeTurn(c, toolChoice) {

package/dist/src/clients/run.js

@@ -7,7 +7,7 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
     return path;
 };
 // The vendor's client cases, run in Node as an application runs its SDK: `node run.ts <job.json>`. The job names the
-// vendor, the served port, the host, the issued credentials and the scenario file; each case's failures are printed as
+// vendor, the served port, the host, the issued credentials and the World's scenario file; each case's failures are printed as
 // one JSON line, `{ id, asks, failures }`.
 import { readFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
@@ -28,7 +28,7 @@ try {
     const facts = JSON.parse(readFileSync(job.packFacts, 'utf8')).packs[job.vendor];
     const keys = [...new Set((facts.hosts ?? []).map((rule) => rule.key ?? job.vendor))];
     require('@volter/world-core/inject').install(Object.fromEntries(keys.map((key) => [key, `http://127.0.0.1:${proxy.port}`])));
-    const context = clientContext(proxy.port, job.host, job.env, job.scenarioPath, job.raw ? job.port : undefined);
+    const context = clientContext(proxy.port, job.host, job.env, { vendor: job.vendor, file: job.scenarioFile }, job.raw ? job.port : undefined);
     for (const c of cases) {
         const failures = await Promise.race([
             c.run(context).catch((e) => [`the case threw: ${e.message}`]),

package/dist/src/clients/xai.js

@@ -7,7 +7,7 @@ export const cases = [
         asks: "a reasoning turn streamed through the SDK's Responses stream completes with its reasoning item and its message",
         source: 'https://developers.openai.com/api/reference/resources/responses/streaming-events "response.reasoning_summary_part.added"',
         async run(c) {
-            c.scenario({ handlers: [{ id: 'reasons', on: { userTextIncludes: 'hello' }, respond: { text: 'scripted words', reasoning: 'thinking it through' } }] });
+            c.scenario([{ on: { userTextIncludes: 'hello' }, outcome: { text: 'scripted words', reasoning: 'thinking it through' } }]);
             const client = await openaiClient(c, XAI);
             try {
                 const stream = client.responses.stream({ model: XAI.model, input: 'hello', reasoning: { summary: 'auto' } });

package/dist/src/conformance.js

@@ -34,6 +34,7 @@ import { fileURLToPath } from 'node:url';
 import { parseEnv } from 'node:util';
 import { openWebSocket, readHttpResponse, servedHttpFetch, worldProxy } from "./clients/harness.js";
 import { servePack as serve } from "./walk/serve-pack.js";
+import { playScenario, resolvedScenario } from "./walk/world-scenario.js";
 import { walkPackDirectory } from "./walk/pack-directory.js";
 import { formBody, sigv4Headers } from "./walk/journey-kit.js";
 import { consumerClientProof, consumerRecipe, runConsumerCommand } from "./consumer.js";
@@ -479,7 +480,7 @@ async function consumerAuthorization(pack, scratch, root, server, descriptor, ou
     }
 }
 /** Every operation the pack serves, called over HTTP as an application calls it, against its server.ts served as a World
- *  runs it: once plainly and once with a scenario loaded (an empty one, as a World that scripts nothing loads it). Each
+ *  runs it: once plainly and once with a scenario played (an empty one, as a World that places nothing plays it). Each
  *  answers within 10 s, never with a 500 the spec does not declare, never with a field of the twin's own (`_`
  *  bookkeeping, the kernel's `updatedAt`) and, answered successfully, in the shape the spec gives the operation; and every
  *  refresh list a fresh account can read (one with no parameter in its path) succeeds or remains unread under the
@@ -521,11 +522,12 @@ async function surfaceSwept(pack, scratch, runtime, consumer) {
         return { failures: out, note: 'no unit serves an operation on a path of its own' };
     const tally = { calls: 0, ok: 0, refused: 0, unread: 0, removed: 0 };
     const replayedHeaders = new Set();
-    const scenarioPath = join(scratch, 'surface-scenario.json');
-    writeFileSync(scenarioPath, '{"handlers":[]}');
+    // the scenario mode plays an empty timeline as the World's, as a World that places nothing on the vendor plays it
+    const empty = resolvedScenario('surface', { start: '2000-01-01T00:00:00.000Z', timeline: [] });
     for (const mode of ['plain', 'scenario']) {
         const root = join(scratch, `surface-${mode}`);
-        const server = await serve(pack, { root, ...(mode === 'scenario' ? { scenarioPath } : {}) });
+        const restoreScenario = playScenario(join(scratch, 'surface-scenario.json'), mode === 'scenario' ? empty : undefined);
+        const server = await serve(pack, { root }).catch((error) => { restoreScenario(); throw error; });
         const http = servedHttpFetch(server.inspectPort ?? server.port);
         const send = async (request) => {
             await server.managedDatabaseUrl?.();
@@ -768,7 +770,12 @@ async function surfaceSwept(pack, scratch, runtime, consumer) {
                     }
         }
         finally {
-            await server.stop();
+            try {
+                await server.stop();
+            }
+            finally {
+                restoreScenario();
+            }
         }
     }
     // one defect repeated over a surface reads as one: the first 40 findings, and how many more
@@ -805,7 +812,7 @@ function lineConnection(port) {
     };
 }
 /** The life walked as an application calls the pack: its server.ts served as a World runs it (boot id set, the World's
- *  root and the life's scenario its options), every step over HTTP with the vendor's host, every check of the walk held
+ *  root its option, the life's scenario played as the World's), every step over HTTP with the vendor's host, every check of the walk held
  *  (status, expectations, captures, SHAPE, LEAK over answers, events and frames). Slack's events once carried the
  *  kernel's updatedAt; a request the served pack does not answer in 10 s fails its step. */
 async function lifeServed(pack) {
@@ -814,8 +821,8 @@ async function lifeServed(pack) {
         return ['journeys/customer-life.json is missing'];
     const { inMemoryWorld, usePacks, walk } = await import("./walk/behavior-journey.js");
     usePacks(dirname(pack), { dependenciesFrom: pack });
-    const served = async (root, options) => {
-        const server = await serve(pack, { root, ...options });
+    const served = async (root) => {
+        const server = await serve(pack, { root });
         const port = server.inspectPort ?? server.port;
         const http = servedHttpFetch(port);
         return {
@@ -868,9 +875,11 @@ async function clientCases(pack, scratch, consumer) {
     const host = descriptor?.hosts?.flatMap((h) => 'host' in h && h.exclude !== true ? [h.host] : [])[0] ?? (descriptor?.hostsNone ? 'relay.world.test' : undefined);
     if (!host)
         return { failures: ['the descriptor names no host for its client to address'] };
-    const scenarioPath = join(scratch, 'client-scenario.json');
-    writeFileSync(scenarioPath, '{"handlers":[]}');
-    const server = await serve(pack, { root: join(scratch, 'client-world'), scenarioPath });
+    // the World's scenario, empty until a case plays the turns it scripts (the harness writes the file this process's pack
+    // reads at each request)
+    const scenarioFile = join(scratch, 'client-scenario.json');
+    const restoreScenario = playScenario(scenarioFile, resolvedScenario('client-case', { start: '2000-01-01T00:00:00.000Z', timeline: [] }));
+    const server = await serve(pack, { root: join(scratch, 'client-world') }).catch((error) => { restoreScenario(); throw error; });
     try {
         // the World's credentials: what the pack's credential door issues, by the variable a World sets each in
         const issued = {};
@@ -890,7 +899,7 @@ async function clientCases(pack, scratch, consumer) {
             packFacts = join(scratch, 'pack-facts.json');
             writeFileSync(packFacts, renderPackFacts(compiled));
         }
-        writeFileSync(job, JSON.stringify({ vendor, port: server.port, host, env: issued, scenarioPath, packFacts, ...(descriptor?.hostsNone ? { raw: true } : {}) }));
+        writeFileSync(job, JSON.stringify({ vendor, port: server.port, host, env: issued, scenarioFile, packFacts, ...(descriptor?.hostsNone ? { raw: true } : {}) }));
         // Node, as an application runs its SDK (asynchronous: this process serves the pack meanwhile)
         const out = await new Promise((resolve) => {
             const child = spawn('node', ['--experimental-strip-types', '--no-warnings', join(clients, `run${extension}`), job], { stdio: ['ignore', 'pipe', 'pipe'] });
@@ -907,7 +916,12 @@ async function clientCases(pack, scratch, consumer) {
         return { failures: results.flatMap((r) => r.failures.map((f) => `${r.id} (${r.asks}): ${f}`)), note: `${results.length} case(s) through the vendor's client` };
     }
     finally {
-        await server.stop();
+        try {
+            await server.stop();
+        }
+        finally {
+            restoreScenario();
+        }
     }
 }
 /** The gate over every unit of the pack: the form section of the grade, which holds the rules an author's code keeps

package/dist/src/create-pack.js

@@ -372,7 +372,7 @@ export function cliFile(vendor, live = false) {
     const Name = pascal(vendor);
     const ingest = live ? `// the RTMP ingest's side port, which the World allocates (the manifest's sidePorts)\nconst ingestPort = Number(optionValue(rest, '--ingest-port', '0')) || undefined;\n` : '';
     const served = live ? `  process.stdout.write(s.ingestPort ? \`${vendor} twin ingest at rtmp://127.0.0.1:\${s.ingestPort}\\n\` : '${vendor} twin: no RTMP ingest\\n');\n` : '';
-    return `#!/usr/bin/env node\n// world-${vendor}: serve the ${vendor} twin.\nimport { hasFlag, optionValue } from '@volter/world-core/args';\nimport { keepProcessAlive } from '@volter/world-core/lifecycle';\nimport { create${Name}TwinServer } from './server.ts';\n\nconst [cmd, ...rest] = process.argv.slice(2);\nconst port = Number(optionValue(rest, '--port', '0')) || undefined;\nconst root = optionValue(rest, '--root') || undefined;\nconst readOnly = hasFlag(rest, '--read-only');\n// the selected twin's private Postgres, which the runtime binds a pack declaring managedDatabase to\nconst database = optionValue(rest, '--database') || undefined;\n// the World's scenario file, for a model vendor's turns\nconst scenarioPath = optionValue(rest, '--scenario') || undefined;\n${ingest}\nif (cmd === 'serve' || cmd === undefined) {\n  const s = await create${Name}TwinServer({ readOnly, ...(root ? { root } : {}), ...(port ? { port } : {}), ...(database ? { database } : {}), ...(scenarioPath ? { scenarioPath } : {})${live ? ', ...(ingestPort ? { ingestPort } : {})' : ''} });\n  process.stdout.write(\`${vendor} twin\${readOnly ? ' [read-only]' : ''} at http://127.0.0.1:\${s.port}\\n\`);\n${served}  await keepProcessAlive();\n} else {\n  process.stdout.write('Usage: world-${vendor} serve [--port N] [--root DIR] [--read-only] [--database URL] [--scenario FILE]${live ? ' [--ingest-port N]' : ''}\\n');\n}\n`;
+    return `#!/usr/bin/env node\n// world-${vendor}: serve the ${vendor} twin.\nimport { hasFlag, optionValue } from '@volter/world-core/args';\nimport { keepProcessAlive } from '@volter/world-core/lifecycle';\nimport { create${Name}TwinServer } from './server.ts';\n\nconst [cmd, ...rest] = process.argv.slice(2);\nconst port = Number(optionValue(rest, '--port', '0')) || undefined;\nconst root = optionValue(rest, '--root') || undefined;\nconst readOnly = hasFlag(rest, '--read-only');\n// the selected twin's private Postgres, which the runtime binds a pack declaring managedDatabase to\nconst database = optionValue(rest, '--database') || undefined;\n${ingest}\nif (cmd === 'serve' || cmd === undefined) {\n  const s = await create${Name}TwinServer({ readOnly, ...(root ? { root } : {}), ...(port ? { port } : {}), ...(database ? { database } : {})${live ? ', ...(ingestPort ? { ingestPort } : {})' : ''} });\n  process.stdout.write(\`${vendor} twin\${readOnly ? ' [read-only]' : ''} at http://127.0.0.1:\${s.port}\\n\`);\n${served}  await keepProcessAlive();\n} else {\n  process.stdout.write('Usage: world-${vendor} serve [--port N] [--root DIR] [--read-only] [--database URL]${live ? ' [--ingest-port N]' : ''}\\n');\n}\n`;
 }
 /** A vendor id as a name in code: `npm-registry` is `NpmRegistry`. */
 const pascal = (vendor) => vendor.split(/[^A-Za-z0-9]+/).filter(Boolean).map((w) => w[0].toUpperCase() + w.slice(1)).join('');

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

@@ -42,11 +42,11 @@ export type StepHooks = {
     before?: (step: JourneyStep | LineStep | GitStep | RespStep, path: string, body: unknown) => void;
     after?: (step: JourneyStep | LineStep | GitStep | RespStep, path: string, answer: StepAnswer, failures: Failure[]) => void;
 };
-/** A pack served for a walk the way a World runs it (its server.ts on a port, the World's root and scenario its options):
+/** A pack served for a walk the way a World runs it (its server.ts on a port, the World's root its option, its scenario
+ *  the World's file):
  *  the walk's requests go to it over HTTP, the vendor's host in their Host header, instead of to the fetch in process;
  *  its sockets are WebSockets to that port, and a line connection (`stream`) is a TCP connection to its protocol port. */
 export type ServedTwin = (root: string, options: {
-    scenarioPath?: string;
     application?: import('@volter/world-core').PackFetchOptions['application'];
 }) => Promise<{
     scheme?: 'http' | 'https';

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

@@ -123,6 +123,7 @@ export function inMemoryWorld(label) {
     };
 }
 import { vendorAnswerViews, vendorFetch as vendorFetchFrom, vendorStream } from "./vendor-fetch.js";
+import { playScenario, resolvedScenario } from "./world-scenario.js";
 import { gitClone, gitPush } from "./git-client.js";
 /** The type a step's body goes with when it names none, as fetch labels it: JSON for a value or a JSON text, plain text
  *  for any other string (an upload's bytes). */
@@ -287,14 +288,21 @@ export async function walk(journey, root, collect, opts) {
     const ownKeys = routingKeys(journey.vendor);
     /** The companion that serves a step's URL: one whose host rules claim it where the life's own vendor's do not. */
     const companionOf = (url) => (claims(ownKeys, url) ? undefined : companions.find((c) => claims(c.keys, url)));
-    // the life's scenario is the World's: written into the walk's World store, which the pack reads it from as a World's
-    // handlers/<vendor>.json is read
-    const scenarioPath = journey.scenario ? join(directoryFor(journey.vendor), 'journeys', journey.scenario) : undefined;
-    if (scenarioPath)
-        getActiveWorldStore().write(scenarioPath, readFileSync(scenarioPath, 'utf8'));
+    // the life's scenario is the World's: resolved here, and played (written beside the walk's root in its World store and
+    // named by TWIN_WORLD_SCENARIO_FILE, which every pack of the walk reads at each request as a World's twins do) from its
+    // first step to its end; a life naming none plays none, whatever World the walk itself runs in
+    let scenario;
+    try {
+        if (journey.scenario)
+            scenario = resolvedScenario(journey.scenario, parseExactJson(readFileSync(join(directoryFor(journey.vendor), 'journeys', journey.scenario), 'utf8')));
+    }
+    catch (error) {
+        collect.push({ step: '(setup)', beat: 'SCENARIO', detail: `journeys/${journey.scenario}: ${error.message}` });
+        return {};
+    }
     const shape = await shapeOf(journey.vendor);
-    const served = opts.served ? await opts.served(root, { ...(scenarioPath ? { scenarioPath } : {}), application }) : undefined;
-    const twin = served ? served.fetch : factory(root, { ...(scenarioPath ? { scenarioPath } : {}), application });
+    const served = opts.served ? await opts.served(root, { application }) : undefined;
+    const twin = served ? served.fetch : factory(root, { application });
     const host = journey.host ?? 'twin.local';
     const origin = `${served?.scheme ?? 'http'}://${host}`;
     // a capture's JSON value where it is not text (a number, a boolean, an object such as database-js's `session`)
@@ -1046,6 +1054,7 @@ export async function walk(journey, root, collect, opts) {
         ...ownKeys.map((key) => [key, twin]),
     ]));
     const previousMailServers = setInProcessMailServers(mailServers);
+    const restoreScenario = playScenario(`${root}.scenario.json`, scenario);
     try {
         for (const step of journey.steps) {
             await settleEventDeliveries(root);
@@ -1380,6 +1389,7 @@ export async function walk(journey, root, collect, opts) {
                         finally {
                             if (clockFile && startedAt !== undefined)
                                 store.write(clockFile, startedAt);
+                            restoreScenario();
                         }
                     }
                 }

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

@@ -193,8 +193,9 @@ export type Journey = {
     /** The instant the story begins, where it is before the World's day one (2026-01-01): an account whose story starts
      *  while an API it used still made what it no longer makes. Its waits move the clock on from there. */
     startsAt?: string;
-    /** The World's scenario for a generative pack's turns (a file beside the life, `journeys/<name>.json`, as a World
-     *  loads `handlers/<vendor>.json`): the walk loads it, so the scripted turns and the pack's scenario code are walked. */
+    /** The World's scenario the life is walked under (a scenario document beside it, `journeys/<name>.json`: ADR 0036,
+     *  `{ start, timeline }`): the walk plays it as the World's, so the decisions and faults it places, and the pack's code
+     *  that consumes them, are walked. */
     scenario?: string;
     /** The packs of the same catalog, by vendor, that the vendor calls as its own behaviour (`ctx.vendorFetch`: a sign-in
      *  trading a code at its provider): the walk loads each over the walk's own World and root, the vendor's calls reach

package/dist/src/walk/serve-pack.d.ts

@@ -7,5 +7,4 @@ export type ServedPack = {
 } & Omit<ManagedDatabaseWalk, 'stopDatabase'>;
 export declare function servePack(pack: string, options: {
     root?: string;
-    scenarioPath?: string;
 }): Promise<ServedPack>;

package/dist/src/walk/vendor-fetch.d.ts

@@ -2,10 +2,9 @@ import { type ManagedDatabaseWalk } from './walk-database.js';
 import { type TwinStream } from '@volter/world-core/runtime';
 import type { PackFetchOptions } from '@volter/world-core';
 type ApplicationStandIn = NonNullable<PackFetchOptions['application']>;
-/** A pack's fetch over a World's root; a walk whose life names a scenario loads it as the World's (`scenarioPath`), and a
+/** A pack's fetch over a World's root (the World's scenario it reads itself, TWIN_WORLD_SCENARIO_FILE), and a
  *  life's application answers stand in for the application the vendor asks (`application`, this fetch's alone). */
 export type VendorFetchFactory = ((root: string, options?: {
-    scenarioPath?: string;
     application?: ApplicationStandIn;
 }) => ((request: Request) => Response | Promise<Response>) & ManagedDatabaseWalk) & {
     managedDatabaseDoor?: string;

package/dist/src/walk/world-scenario.d.ts

@@ -0,0 +1,8 @@
+import { type ResolvedScenario } from '@volter/world-core';
+export type { ResolvedScenario };
+/** A scenario document as a World plays it; one the grammar refuses throws its ScenarioTimelineError, which names the
+ *  entry and the vocabulary it expected. */
+export declare function resolvedScenario(name: string, document: unknown): ResolvedScenario;
+/** Play `scenario` as the World's at `file` until the returned restore, which puts the variable back as it was. Playing
+ *  none clears the variable, so what the standard serves inside a World plays nothing of that World's. */
+export declare function playScenario(file: string, scenario: ResolvedScenario | undefined): () => void;

package/dist/src/walk/world-scenario.js

@@ -0,0 +1,26 @@
+// The World's scenario as the standard plays it for a walk or a served pack (ADR 0036; architecture, "Scenarios"): the
+// document parsed and resolved as a World resolves it, written through the active World store, and named by
+// TWIN_WORLD_SCENARIO_FILE, where every twin in this process reads it at each request as it reads the clock. A pack takes
+// no scenario option: what it plays is the World's one scenario, so the standard sets the World's.
+import { parseScenario, resolveScenario, WORLD_SCENARIO_ENV } from '@volter/world-core';
+import { getActiveWorldStore } from '@volter/world-core/runtime';
+/** A scenario document as a World plays it; one the grammar refuses throws its ScenarioTimelineError, which names the
+ *  entry and the vocabulary it expected. */
+export function resolvedScenario(name, document) {
+    return resolveScenario(name, parseScenario(document));
+}
+/** Play `scenario` as the World's at `file` until the returned restore, which puts the variable back as it was. Playing
+ *  none clears the variable, so what the standard serves inside a World plays nothing of that World's. */
+export function playScenario(file, scenario) {
+    if (scenario)
+        getActiveWorldStore().write(file, JSON.stringify(scenario));
+    const previous = process.env[WORLD_SCENARIO_ENV];
+    if (scenario)
+        process.env[WORLD_SCENARIO_ENV] = file;
+    else
+        delete process.env[WORLD_SCENARIO_ENV];
+    return () => { if (previous === undefined)
+        delete process.env[WORLD_SCENARIO_ENV];
+    else
+        process.env[WORLD_SCENARIO_ENV] = previous; };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/twin-standard",
-  "version": "1.0.161",
+  "version": "1.0.162",
   "description": "The Protocol 3 standard for Volter twin packs: the criteria a pack is graded by, the grader, the gate a pack repository and the twin catalog run on every change and submission, and the spec derivation the grade checks against. Pin a version: every place a pack is judged judges by that standard.",
   "keywords": [
     "twin",
@@ -77,8 +77,8 @@
     "yaml": "2.9.0"
   },
   "peerDependencies": {
-    "@volter/world-core": "3.0.166",
-    "@volter/world-runtime": "^3.0.191",
+    "@volter/world-core": "3.0.167",
+    "@volter/world-runtime": "^3.0.192",
     "playwright": "^1.63.0"
   },
   "peerDependenciesMeta": {

package/src/clients/anthropic-messages.ts

@@ -11,10 +11,10 @@ const TOOLS = [{ name: 'lookup', input_schema: { type: 'object' as const, proper
 export type MessagesVendor = { key: string; base: (host: string) => string; model: string; toolTurn: Record<string, unknown> };
 
 export function messagesCases(v: MessagesVendor): ClientCase[] {
-  const SCRIPT = { handlers: [
-    { id: 'calls', on: { hasTool: 'lookup' }, respond: v.toolTurn },
-    { id: 'words', on: { userTextIncludes: 'hello' }, respond: { text: 'scripted words' } },
-  ] };
+  const SCRIPT = [
+    { on: { hasTool: 'lookup' }, outcome: v.toolTurn },
+    { on: { userTextIncludes: 'hello' }, outcome: { text: 'scripted words' } },
+  ];
   const ask = async (c: ClientContext, extra: Record<string, unknown> = {}) => {
     const { default: Anthropic } = await import('@anthropic-ai/sdk');
     const client = new Anthropic({ apiKey: c.env[v.key] ?? '', baseURL: v.base(c.host), fetch: c.fetch, maxRetries: 0, timeout: 10_000 });
@@ -49,9 +49,9 @@ export function messagesCases(v: MessagesVendor): ClientCase[] {
       asks: "the World's scenario rewritten between two turns decides the second (no reboot)",
       source: 'architecture "The scenario is read from the World\'s store at every turn"',
       async run(c) {
-        c.scenario({ handlers: [{ id: 'one', on: { userTextIncludes: 'hello' }, respond: { text: 'first script' } }] });
+        c.scenario([{ on: { userTextIncludes: 'hello' }, outcome: { text: 'first script' } }]);
         const first = await ask(c).then(text, (e: Error) => `error ${e.message}`);
-        c.scenario({ handlers: [{ id: 'two', on: { userTextIncludes: 'hello' }, respond: { text: 'second script' } }] });
+        c.scenario([{ on: { userTextIncludes: 'hello' }, outcome: { text: 'second script' } }]);
         const second = await ask(c).then(text, (e: Error) => `error ${e.message}`);
         return first === 'first script' && second === 'second script' ? [] : [`the turns answered "${first}" then "${second}"`];
       },

package/src/clients/gemini.ts

@@ -25,7 +25,7 @@ export const cases: ClientCase[] = [
     source: `${REFERENCE} "a stream of GenerateContentResponse instances"`,
     async run(c) {
       return routed(c, async () => {
-        c.scenario({ handlers: [{ id: 'words', on: { userTextIncludes: 'workshop' }, respond: { text: 'A scripted workshop reply.' } }] });
+        c.scenario([{ on: { userTextIncludes: 'workshop' }, outcome: { text: 'A scripted workshop reply.' } }]);
         const result = await (await chat(c)).generateContentStream('Plan the workshop.');
         let text = '';
         for await (const chunk of result.stream) text += chunk.text();
@@ -42,10 +42,10 @@ export const cases: ClientCase[] = [
     async run(c) {
       return routed(c, async () => {
         const { SchemaType } = await import('@google/generative-ai');
-        c.scenario({ handlers: [
-          { id: 'returned', on: { toolResultFor: 'lookup_company', lastMessageIsToolResult: true }, respond: { text: 'Tidewater renewal is in October.' } },
-          { id: 'lookup', on: { hasTool: 'lookup_company' }, respond: { functionCalls: [{ name: 'lookup_company', args: { company: 'Tidewater' } }] } },
-        ] });
+        c.scenario([
+          { on: { toolResultFor: 'lookup_company', lastMessageIsToolResult: true }, outcome: { text: 'Tidewater renewal is in October.' } },
+          { on: { hasTool: 'lookup_company' }, outcome: { functionCalls: [{ name: 'lookup_company', args: { company: 'Tidewater' } }] } },
+        ]);
         const session = (await chat(c)).startChat({ tools: [{ functionDeclarations: [{ name: 'lookup_company', parameters: { type: SchemaType.OBJECT, properties: { company: { type: SchemaType.STRING } }, required: ['company'] } }] }] });
         const first = await session.sendMessage('Find the company renewal.');
         const call = first.response.functionCalls()?.[0];
@@ -75,9 +75,9 @@ export const cases: ClientCase[] = [
     async run(c) {
       return routed(c, async () => {
         const { GoogleGenAI } = await import('@google/genai');
-        c.scenario({ handlers: [{ id: 'picture', on: { userTextIncludes: 'square illustration' }, respond: {
+        c.scenario([{ on: { userTextIncludes: 'square illustration' }, outcome: {
           text: 'A synthetic square illustration.', parts: [{ inlineData: { mimeType: 'image/png', data: PNG } }],
-        } }] });
+        } }]);
         const ai = new GoogleGenAI({ apiKey: c.env.GEMINI_API_KEY ?? '', httpOptions: { baseUrl: `https://${c.host}` } });
         const response = await ai.models.generateContent({ model: 'gemini-3.1-flash-image', contents: 'Make a square illustration.', config: { responseModalities: ['TEXT', 'IMAGE'] } });
         const image = response.candidates?.[0]?.content?.parts?.find((p) => p.inlineData)?.inlineData;

package/src/clients/harness.ts

@@ -8,6 +8,7 @@ import { createServer, request as httpRequest, type ClientRequest } from 'node:h
 import { Agent as HttpsAgent } from 'node:https';
 import { connect, type AddressInfo, type Socket } from 'node:net';
 import { writeFileSync } from 'node:fs';
+import type { ResolvedScenario } from '@volter/world-core';
 
 /** What a case is given. */
 export type ClientContext = {
@@ -23,10 +24,18 @@ export type ClientContext = {
   /** an HTTPS agent as a World routes it, for a client that takes an agent (Slack's, Stripe's): its connections reach the
    *  served port, the client's URL and Host unchanged */
   agent: HttpsAgent;
-  /** writes the World's scenario file (read at the pack's next turn) */
-  scenario: (doc: unknown) => void;
+  /** plays the World's scenario (read at the pack's next request): the model vendor's turns, each a decision at its
+   *  `turn` point keyed by `on` (the pack's turn matchers) with `outcome` its answer, holding from the scenario's start;
+   *  playing another replaces it */
+  scenario: (turns: ScriptedTurn[]) => void;
 };
 
+/** A model vendor's scripted turn: a decision `{ point: 'turn', on, outcome, once? }` (ADR 0036) of the case's vendor. */
+export type ScriptedTurn = { on: Record<string, unknown>; outcome: unknown; once?: boolean };
+
+/** Where a case's scenario starts, every entry with it: long before any clock the served pack keeps, so each holds at once. */
+const HELD_FROM = '2000-01-01T00:00:00.000Z';
+
 /** One expectation of the vendor's documented behaviour, driven through its client. */
 export type ClientCase = {
   id: string;
@@ -231,13 +240,18 @@ export function servedHttpFetch(port: number): typeof fetch {
 /** The context for a pack reached at `port` of this machine (the World's proxy in front of it). */
 /** `raw`: a raw protocol's served port (SMTP's listener), which a connection reaches directly, as a World passes a raw TCP
  *  connection through untouched; the proxy speaks HTTP only. */
-export function clientContext(port: number, host: string, env: Record<string, string>, scenarioPath: string, raw?: number): ClientContext {
+export function clientContext(port: number, host: string, env: Record<string, string>, scenario: { vendor: string; file: string }, raw?: number): ClientContext {
   const agent = new (class extends HttpsAgent {
     createConnection(): Socket { return connect(port, '127.0.0.1'); }
   })({ keepAlive: false });
   return {
     host, env, fetch: servedHttpFetch(port), agent,
     connect: () => connect(raw ?? port, '127.0.0.1'),
-    scenario: (doc) => writeFileSync(scenarioPath, JSON.stringify(doc)),
+    // written as a World resolves a document whose every entry is at `0s`: the cases run in Node, whose type stripping
+    // does not load the kernel's source entry (its parameter properties), so they write the resolved form it reads
+    scenario: (turns) => writeFileSync(scenario.file, JSON.stringify({
+      name: 'client-case', start: HELD_FROM, random: 'client-case',
+      timeline: turns.map((t, i) => ({ at: HELD_FROM, decision: { vendor: scenario.vendor, point: 'turn', on: t.on, outcome: t.outcome, ...(t.once === undefined ? {} : { once: t.once }) }, index: i + 1 })),
+    } satisfies ResolvedScenario)),
   };
 }

package/src/clients/openai-compatible.ts

@@ -5,10 +5,10 @@ import type { ClientCase, ClientContext } from './harness.ts';
 
 const CHAT = 'https://developers.openai.com/api/reference/resources/chat/subresources/completions/methods/create';
 const TOOLS = [{ type: 'function' as const, function: { name: 'lookup', parameters: { type: 'object', properties: {} } } }];
-const SCRIPT = { handlers: [
-  { id: 'calls', on: { hasTool: 'lookup' }, respond: { toolCalls: [{ name: 'lookup', arguments: {} }] } },
-  { id: 'words', on: { userTextIncludes: 'hello' }, respond: { text: 'scripted words' } },
-] };
+const SCRIPT = [
+  { on: { hasTool: 'lookup' }, outcome: { toolCalls: [{ name: 'lookup', arguments: {} }] } },
+  { on: { userTextIncludes: 'hello' }, outcome: { text: 'scripted words' } },
+];
 
 /** A vendor's chat as openai-node reaches it: the variable its key is issued in, the base URL on its host, a model it serves. */
 export type Compatible = { key: string; base: (host: string) => string; model: string };
@@ -48,9 +48,9 @@ export function chatCases(v: Compatible): ClientCase[] {
       asks: "the World's scenario rewritten between two turns decides the second (no reboot)",
       source: 'architecture "The scenario is read from the World\'s store at every turn"',
       async run(c) {
-        c.scenario({ handlers: [{ id: 'one', on: { userTextIncludes: 'hello' }, respond: { text: 'first script' } }] });
+        c.scenario([{ on: { userTextIncludes: 'hello' }, outcome: { text: 'first script' } }]);
         const first = await ask(c).then((a) => a.choices?.[0]?.message?.content, (e: Error) => `error ${e.message}`);
-        c.scenario({ handlers: [{ id: 'two', on: { userTextIncludes: 'hello' }, respond: { text: 'second script' } }] });
+        c.scenario([{ on: { userTextIncludes: 'hello' }, outcome: { text: 'second script' } }]);
         const second = await ask(c).then((a) => a.choices?.[0]?.message?.content, (e: Error) => `error ${e.message}`);
         return first === 'first script' && second === 'second script' ? [] : [`the turns answered "${first}" then "${second}"`];
       },

package/src/clients/openai.ts

@@ -13,10 +13,10 @@ async function client(c: ClientContext) {
 }
 const TOOLS = [{ type: 'function' as const, function: { name: 'lookup', parameters: { type: 'object', properties: {} } } }];
 // a turn that calls the tool wherever one is offered, and one that answers in words
-const SCRIPT = { handlers: [
-  { id: 'calls', on: { hasTool: 'lookup' }, respond: { toolCalls: [{ name: 'lookup', arguments: {} }] } },
-  { id: 'words', on: { userTextIncludes: 'hello' }, respond: { text: 'scripted words' } },
-] };
+const SCRIPT = [
+  { on: { hasTool: 'lookup' }, outcome: { toolCalls: [{ name: 'lookup', arguments: {} }] } },
+  { on: { userTextIncludes: 'hello' }, outcome: { text: 'scripted words' } },
+];
 
 /** A Realtime session through the client (openai-node's server-side Realtime client, on the ws library, as a Node
  *  application opens it), until its response is done: its first event and the output items' types, or what went wrong. */

package/src/clients/run.ts

@@ -1,5 +1,5 @@
 // The vendor's client cases, run in Node as an application runs its SDK: `node run.ts <job.json>`. The job names the
-// vendor, the served port, the host, the issued credentials and the scenario file; each case's failures are printed as
+// vendor, the served port, the host, the issued credentials and the World's scenario file; each case's failures are printed as
 // one JSON line, `{ id, asks, failures }`.
 import { readFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
@@ -7,7 +7,7 @@ import { extname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { clientContext, worldProxy, type ClientCase } from './harness.ts';
 
-const job = JSON.parse(readFileSync(process.argv[2]!, 'utf8')) as { vendor: string; port: number; host: string; env: Record<string, string>; scenarioPath: string; packFacts: string; raw?: boolean };
+const job = JSON.parse(readFileSync(process.argv[2]!, 'utf8')) as { vendor: string; port: number; host: string; env: Record<string, string>; scenarioFile: string; packFacts: string; raw?: boolean };
 const { cases } = (await import(`./${job.vendor}${extname(fileURLToPath(import.meta.url))}`)) as { cases: ClientCase[] };
 if (!Array.isArray(cases) || cases.length === 0) throw new Error(`${job.vendor} client module declares no cases; there is no SDK execution evidence`);
 // every connection a case makes goes through the World's proxy, as an application's does in a World
@@ -20,7 +20,7 @@ try {
   const facts = JSON.parse(readFileSync(job.packFacts, 'utf8')).packs[job.vendor];
   const keys: string[] = [...new Set<string>((facts.hosts ?? []).map((rule: { key?: string }) => rule.key ?? job.vendor))];
   require('@volter/world-core/inject').install(Object.fromEntries(keys.map((key) => [key, `http://127.0.0.1:${proxy.port}`])));
-  const context = clientContext(proxy.port, job.host, job.env, job.scenarioPath, job.raw ? job.port : undefined);
+  const context = clientContext(proxy.port, job.host, job.env, { vendor: job.vendor, file: job.scenarioFile }, job.raw ? job.port : undefined);
   for (const c of cases) {
     const failures = await Promise.race([
       c.run(context).catch((e: Error) => [`the case threw: ${e.message}`]),

package/src/clients/xai.ts

@@ -12,7 +12,7 @@ export const cases: ClientCase[] = [
     asks: "a reasoning turn streamed through the SDK's Responses stream completes with its reasoning item and its message",
     source: 'https://developers.openai.com/api/reference/resources/responses/streaming-events "response.reasoning_summary_part.added"',
     async run(c) {
-      c.scenario({ handlers: [{ id: 'reasons', on: { userTextIncludes: 'hello' }, respond: { text: 'scripted words', reasoning: 'thinking it through' } }] });
+      c.scenario([{ on: { userTextIncludes: 'hello' }, outcome: { text: 'scripted words', reasoning: 'thinking it through' } }]);
       const client = await openaiClient(c, XAI);
       try {
         const stream = client.responses.stream({ model: XAI.model, input: 'hello', reasoning: { summary: 'auto' } } as never);

package/src/conformance.ts

@@ -28,6 +28,7 @@ import { fileURLToPath } from 'node:url';
 import { parseEnv } from 'node:util';
 import { openWebSocket, readHttpResponse, servedHttpFetch, worldProxy } from './clients/harness.ts';
 import { servePack as serve, type ServedPack as Served } from './walk/serve-pack.ts';
+import { playScenario, resolvedScenario } from './walk/world-scenario.ts';
 import { walkPackDirectory } from './walk/pack-directory.ts';
 import { formBody, sigv4Headers } from './walk/journey-kit.ts';
 import { consumerClientProof, consumerRecipe, runConsumerCommand, type ConsumerResult } from './consumer.ts';
@@ -420,7 +421,7 @@ async function consumerAuthorization(pack: string, scratch: string, root: string
 }
 
 /** Every operation the pack serves, called over HTTP as an application calls it, against its server.ts served as a World
- *  runs it: once plainly and once with a scenario loaded (an empty one, as a World that scripts nothing loads it). Each
+ *  runs it: once plainly and once with a scenario played (an empty one, as a World that places nothing plays it). Each
  *  answers within 10 s, never with a 500 the spec does not declare, never with a field of the twin's own (`_`
  *  bookkeeping, the kernel's `updatedAt`) and, answered successfully, in the shape the spec gives the operation; and every
  *  refresh list a fresh account can read (one with no parameter in its path) succeeds or remains unread under the
@@ -458,11 +459,12 @@ async function surfaceSwept(pack: string, scratch: string, runtime: Runtime, con
   if (!units.length) return { failures: out, note: 'no unit serves an operation on a path of its own' };
   const tally = { calls: 0, ok: 0, refused: 0, unread: 0, removed: 0 };
   const replayedHeaders = new Set<string>();
-  const scenarioPath = join(scratch, 'surface-scenario.json');
-  writeFileSync(scenarioPath, '{"handlers":[]}');
+  // the scenario mode plays an empty timeline as the World's, as a World that places nothing on the vendor plays it
+  const empty = resolvedScenario('surface', { start: '2000-01-01T00:00:00.000Z', timeline: [] });
   for (const mode of ['plain', 'scenario'] as const) {
     const root = join(scratch, `surface-${mode}`);
-    const server = await serve(pack, { root, ...(mode === 'scenario' ? { scenarioPath } : {}) });
+    const restoreScenario = playScenario(join(scratch, 'surface-scenario.json'), mode === 'scenario' ? empty : undefined);
+    const server = await serve(pack, { root }).catch((error: unknown) => { restoreScenario(); throw error; });
     const http = servedHttpFetch(server.inspectPort ?? server.port);
     const send = async (request: Request): Promise<Awaited<ReturnType<typeof readHttpResponse>> | Error> => {
       await server.managedDatabaseUrl?.();
@@ -626,7 +628,7 @@ async function surfaceSwept(pack: string, scratch: string, runtime: Runtime, con
         if (status === 403 && readSomething) { tally.unread++; continue; }
         if (status !== undefined && (status < 200 || status >= 300)) out.push(`${u.name}: ${r.resource}'s refresh lists by ${r.id}, which answered a fresh account ${status}: a World rooted at this twin reads nothing back`);
       }
-    } finally { await server.stop(); }
+    } finally { try { await server.stop(); } finally { restoreScenario(); } }
   }
   // one defect repeated over a surface reads as one: the first 40 findings, and how many more
   return { failures: out.length > 40 ? [...out.slice(0, 40), `… ${out.length - 40} more`] : out, note: `${tally.calls} served operations called, twice each: ${tally.ok} answered successfully, ${tally.refused} refused, unscripted; ${tally.unread} refresh resources unread (403), ${tally.removed} match declared native removals${replayedHeaders.size ? `; replayed application headers (values redacted): ${[...replayedHeaders].sort().join(', ')}` : ''}` };
@@ -661,7 +663,7 @@ function lineConnection(port: number): TwinStream {
 }
 
 /** The life walked as an application calls the pack: its server.ts served as a World runs it (boot id set, the World's
- *  root and the life's scenario its options), every step over HTTP with the vendor's host, every check of the walk held
+ *  root its option, the life's scenario played as the World's), every step over HTTP with the vendor's host, every check of the walk held
  *  (status, expectations, captures, SHAPE, LEAK over answers, events and frames). Slack's events once carried the
  *  kernel's updatedAt; a request the served pack does not answer in 10 s fails its step. */
 async function lifeServed(pack: string): Promise<string[]> {
@@ -669,8 +671,8 @@ async function lifeServed(pack: string): Promise<string[]> {
   if (!existsSync(lifePath)) return ['journeys/customer-life.json is missing'];
   const { inMemoryWorld, usePacks, walk } = await import('./walk/behavior-journey.ts');
   usePacks(dirname(pack), { dependenciesFrom: pack });
-  const served = async (root: string, options: { scenarioPath?: string }) => {
-    const server = await serve(pack, { root, ...options });
+  const served = async (root: string) => {
+    const server = await serve(pack, { root });
     const port = server.inspectPort ?? server.port;
     const http = servedHttpFetch(port);
     return {
@@ -718,9 +720,11 @@ async function clientCases(pack: string, scratch: string, consumer?: ConsumerRes
   // connection alone; its client names a stand-in host the connection never resolves
   const host = descriptor?.hosts?.flatMap((h) => 'host' in h && h.exclude !== true ? [h.host] : [])[0] ?? (descriptor?.hostsNone ? 'relay.world.test' : undefined);
   if (!host) return { failures: ['the descriptor names no host for its client to address'] };
-  const scenarioPath = join(scratch, 'client-scenario.json');
-  writeFileSync(scenarioPath, '{"handlers":[]}');
-  const server = await serve(pack, { root: join(scratch, 'client-world'), scenarioPath });
+  // the World's scenario, empty until a case plays the turns it scripts (the harness writes the file this process's pack
+  // reads at each request)
+  const scenarioFile = join(scratch, 'client-scenario.json');
+  const restoreScenario = playScenario(scenarioFile, resolvedScenario('client-case', { start: '2000-01-01T00:00:00.000Z', timeline: [] }));
+  const server = await serve(pack, { root: join(scratch, 'client-world') }).catch((error: unknown) => { restoreScenario(); throw error; });
   try {
     // the World's credentials: what the pack's credential door issues, by the variable a World sets each in
     const issued: Record<string, string> = {};
@@ -739,7 +743,7 @@ async function clientCases(pack: string, scratch: string, consumer?: ConsumerRes
       packFacts = join(scratch, 'pack-facts.json');
       writeFileSync(packFacts, renderPackFacts(compiled));
     }
-    writeFileSync(job, JSON.stringify({ vendor, port: server.port, host, env: issued, scenarioPath, packFacts, ...(descriptor?.hostsNone ? { raw: true } : {}) }));
+    writeFileSync(job, JSON.stringify({ vendor, port: server.port, host, env: issued, scenarioFile, packFacts, ...(descriptor?.hostsNone ? { raw: true } : {}) }));
     // Node, as an application runs its SDK (asynchronous: this process serves the pack meanwhile)
     const out = await new Promise<string>((resolve) => {
       const child = spawn('node', ['--experimental-strip-types', '--no-warnings', join(clients, `run${extension}`), job], { stdio: ['ignore', 'pipe', 'pipe'] });
@@ -753,7 +757,7 @@ async function clientCases(pack: string, scratch: string, consumer?: ConsumerRes
     const results = out.split('\n').filter((l) => l.startsWith('{')).map((l) => JSON.parse(l) as { id: string; asks: string; failures: string[] });
     if (results.length === 0) return { failures: [`${vendor} client runner returned no case results; there is no SDK execution evidence`] };
     return { failures: results.flatMap((r) => r.failures.map((f) => `${r.id} (${r.asks}): ${f}`)), note: `${results.length} case(s) through the vendor's client` };
-  } finally { await server.stop(); }
+  } finally { try { await server.stop(); } finally { restoreScenario(); } }
 }
 
 /** The gate over every unit of the pack: the form section of the grade, which holds the rules an author's code keeps

package/src/create-pack.ts

@@ -361,7 +361,7 @@ export function cliFile(vendor: string, live = false): string {
   const Name = pascal(vendor);
   const ingest = live ? `// the RTMP ingest's side port, which the World allocates (the manifest's sidePorts)\nconst ingestPort = Number(optionValue(rest, '--ingest-port', '0')) || undefined;\n` : '';
   const served = live ? `  process.stdout.write(s.ingestPort ? \`${vendor} twin ingest at rtmp://127.0.0.1:\${s.ingestPort}\\n\` : '${vendor} twin: no RTMP ingest\\n');\n` : '';
-  return `#!/usr/bin/env node\n// world-${vendor}: serve the ${vendor} twin.\nimport { hasFlag, optionValue } from '@volter/world-core/args';\nimport { keepProcessAlive } from '@volter/world-core/lifecycle';\nimport { create${Name}TwinServer } from './server.ts';\n\nconst [cmd, ...rest] = process.argv.slice(2);\nconst port = Number(optionValue(rest, '--port', '0')) || undefined;\nconst root = optionValue(rest, '--root') || undefined;\nconst readOnly = hasFlag(rest, '--read-only');\n// the selected twin's private Postgres, which the runtime binds a pack declaring managedDatabase to\nconst database = optionValue(rest, '--database') || undefined;\n// the World's scenario file, for a model vendor's turns\nconst scenarioPath = optionValue(rest, '--scenario') || undefined;\n${ingest}\nif (cmd === 'serve' || cmd === undefined) {\n  const s = await create${Name}TwinServer({ readOnly, ...(root ? { root } : {}), ...(port ? { port } : {}), ...(database ? { database } : {}), ...(scenarioPath ? { scenarioPath } : {})${live ? ', ...(ingestPort ? { ingestPort } : {})' : ''} });\n  process.stdout.write(\`${vendor} twin\${readOnly ? ' [read-only]' : ''} at http://127.0.0.1:\${s.port}\\n\`);\n${served}  await keepProcessAlive();\n} else {\n  process.stdout.write('Usage: world-${vendor} serve [--port N] [--root DIR] [--read-only] [--database URL] [--scenario FILE]${live ? ' [--ingest-port N]' : ''}\\n');\n}\n`;
+  return `#!/usr/bin/env node\n// world-${vendor}: serve the ${vendor} twin.\nimport { hasFlag, optionValue } from '@volter/world-core/args';\nimport { keepProcessAlive } from '@volter/world-core/lifecycle';\nimport { create${Name}TwinServer } from './server.ts';\n\nconst [cmd, ...rest] = process.argv.slice(2);\nconst port = Number(optionValue(rest, '--port', '0')) || undefined;\nconst root = optionValue(rest, '--root') || undefined;\nconst readOnly = hasFlag(rest, '--read-only');\n// the selected twin's private Postgres, which the runtime binds a pack declaring managedDatabase to\nconst database = optionValue(rest, '--database') || undefined;\n${ingest}\nif (cmd === 'serve' || cmd === undefined) {\n  const s = await create${Name}TwinServer({ readOnly, ...(root ? { root } : {}), ...(port ? { port } : {}), ...(database ? { database } : {})${live ? ', ...(ingestPort ? { ingestPort } : {})' : ''} });\n  process.stdout.write(\`${vendor} twin\${readOnly ? ' [read-only]' : ''} at http://127.0.0.1:\${s.port}\\n\`);\n${served}  await keepProcessAlive();\n} else {\n  process.stdout.write('Usage: world-${vendor} serve [--port N] [--root DIR] [--read-only] [--database URL]${live ? ' [--ingest-port N]' : ''}\\n');\n}\n`;
 }
 
 /** A vendor id as a name in code: `npm-registry` is `NpmRegistry`. */

package/src/walk/behavior-journey.ts

@@ -110,6 +110,7 @@ export function inMemoryWorld(label: string): { root: () => string; restore: ()
 }
 
 import { vendorAnswerViews, vendorFetch as vendorFetchFrom, vendorStream, type VendorStreamFactory } from './vendor-fetch.ts';
+import { playScenario, resolvedScenario, type ResolvedScenario } from './world-scenario.ts';
 import { gitClone, gitPush } from './git-client.ts';
 
 /** The type a step's body goes with when it names none, as fetch labels it: JSON for a value or a JSON text, plain text
@@ -188,10 +189,11 @@ function takeReplies(c: Connection): LineReply[] {
   return out;
 }
 
-/** A pack served for a walk the way a World runs it (its server.ts on a port, the World's root and scenario its options):
+/** A pack served for a walk the way a World runs it (its server.ts on a port, the World's root its option, its scenario
+ *  the World's file):
  *  the walk's requests go to it over HTTP, the vendor's host in their Host header, instead of to the fetch in process;
  *  its sockets are WebSockets to that port, and a line connection (`stream`) is a TCP connection to its protocol port. */
-export type ServedTwin = (root: string, options: { scenarioPath?: string; application?: import('@volter/world-core').PackFetchOptions['application'] }) => Promise<{ scheme?: 'http' | 'https'; fetch: ((request: Request, options?: { credentials?: RequestCredentials }) => Promise<Response>) & ManagedDatabaseWalk; stop: () => void | Promise<void>; socket?: (url: string, headers: Record<string, string>) => WebSocket; stream?: TwinStream }>;
+export type ServedTwin = (root: string, options: { application?: import('@volter/world-core').PackFetchOptions['application'] }) => Promise<{ scheme?: 'http' | 'https'; fetch: ((request: Request, options?: { credentials?: RequestCredentials }) => Promise<Response>) & ManagedDatabaseWalk; stop: () => void | Promise<void>; socket?: (url: string, headers: Record<string, string>) => WebSocket; stream?: TwinStream }>;
 
 export async function walk(journey: Journey, root: string, collect: Failure[], opts: { beats: boolean; verbose?: boolean; hooks?: StepHooks; captured?: Captured; served?: ServedTwin }): Promise<Captured> {
   attributionName(journey.author);
@@ -263,13 +265,16 @@ export async function walk(journey: Journey, root: string, collect: Failure[], o
   const ownKeys = routingKeys(journey.vendor);
   /** The companion that serves a step's URL: one whose host rules claim it where the life's own vendor's do not. */
   const companionOf = (url: string) => (claims(ownKeys, url) ? undefined : companions.find((c) => claims(c.keys, url)));
-  // the life's scenario is the World's: written into the walk's World store, which the pack reads it from as a World's
-  // handlers/<vendor>.json is read
-  const scenarioPath = journey.scenario ? join(directoryFor(journey.vendor), 'journeys', journey.scenario) : undefined;
-  if (scenarioPath) getActiveWorldStore().write(scenarioPath, readFileSync(scenarioPath, 'utf8'));
+  // the life's scenario is the World's: resolved here, and played (written beside the walk's root in its World store and
+  // named by TWIN_WORLD_SCENARIO_FILE, which every pack of the walk reads at each request as a World's twins do) from its
+  // first step to its end; a life naming none plays none, whatever World the walk itself runs in
+  let scenario: ResolvedScenario | undefined;
+  try {
+    if (journey.scenario) scenario = resolvedScenario(journey.scenario, parseExactJson(readFileSync(join(directoryFor(journey.vendor), 'journeys', journey.scenario), 'utf8')));
+  } catch (error) { collect.push({ step: '(setup)', beat: 'SCENARIO', detail: `journeys/${journey.scenario}: ${(error as Error).message}` }); return {}; }
   const shape = await shapeOf(journey.vendor);
-  const served = opts.served ? await opts.served(root, { ...(scenarioPath ? { scenarioPath } : {}), application }) : undefined;
-  const twin = served ? served.fetch : factory(root, { ...(scenarioPath ? { scenarioPath } : {}), application });
+  const served = opts.served ? await opts.served(root, { application }) : undefined;
+  const twin = served ? served.fetch : factory(root, { application });
   const host = journey.host ?? 'twin.local';
   const origin = `${served?.scheme ?? 'http'}://${host}`;
   // a capture's JSON value where it is not text (a number, a boolean, an object such as database-js's `session`)
@@ -747,6 +752,7 @@ export async function walk(journey: Journey, root: string, collect: Failure[], o
     ...ownKeys.map((key) => [key, twin] as const),
   ]));
   const previousMailServers = setInProcessMailServers(mailServers);
+  const restoreScenario = playScenario(`${root}.scenario.json`, scenario);
   try {
   for (const step of journey.steps) {
     await settleEventDeliveries(root);
@@ -965,6 +971,7 @@ export async function walk(journey: Journey, root: string, collect: Failure[], o
               if (failures.length) throw new AggregateError(failures, 'Walk native database retirement failed');
             } finally {
               if (clockFile && startedAt !== undefined) store.write(clockFile, startedAt);
+              restoreScenario();
             }
           }
         }

package/src/walk/journey-kit.ts

@@ -305,8 +305,9 @@ export type Journey = {
   /** The instant the story begins, where it is before the World's day one (2026-01-01): an account whose story starts
    *  while an API it used still made what it no longer makes. Its waits move the clock on from there. */
   startsAt?: string;
-  /** The World's scenario for a generative pack's turns (a file beside the life, `journeys/<name>.json`, as a World
-   *  loads `handlers/<vendor>.json`): the walk loads it, so the scripted turns and the pack's scenario code are walked. */
+  /** The World's scenario the life is walked under (a scenario document beside it, `journeys/<name>.json`: ADR 0036,
+   *  `{ start, timeline }`): the walk plays it as the World's, so the decisions and faults it places, and the pack's code
+   *  that consumes them, are walked. */
   scenario?: string;
   /** The packs of the same catalog, by vendor, that the vendor calls as its own behaviour (`ctx.vendorFetch`: a sign-in
    *  trading a code at its provider): the walk loads each over the walk's own World and root, the vendor's calls reach

package/src/walk/serve-pack.ts

@@ -10,7 +10,7 @@ export type ServedPack = {
   stop: () => void | Promise<void>;
 } & Omit<ManagedDatabaseWalk, 'stopDatabase'>;
 
-export async function servePack(pack: string, options: { root?: string; scenarioPath?: string }): Promise<ServedPack> {
+export async function servePack(pack: string, options: { root?: string }): Promise<ServedPack> {
   const previousBoot = process.env.VOLTER_WORLD_BOOT_ID;
   process.env.VOLTER_WORLD_BOOT_ID = 'conformance';
   try { return await serve(pack, options); }
@@ -20,7 +20,7 @@ export async function servePack(pack: string, options: { root?: string; scenario
   }
 }
 
-async function serve(pack: string, options: { root?: string; scenarioPath?: string }): Promise<ServedPack> {
+async function serve(pack: string, options: { root?: string }): Promise<ServedPack> {
   const mod = await import(join(pack, 'src', 'server.ts')) as Record<string, unknown>;
   const create = Object.entries(mod).find(([name, value]) => /^create\w+TwinServer$/.test(name) && typeof value === 'function')?.[1] as ((options: Record<string, unknown>) => Promise<ServedPack>) | undefined;
   if (!create) throw new Error('src/server.ts exports no create<Vendor>TwinServer');

package/src/walk/vendor-fetch.ts

@@ -9,9 +9,9 @@ import { walkPackDirectory } from './pack-directory.ts';
 
 type ApplicationStandIn = NonNullable<PackFetchOptions['application']>;
 
-/** A pack's fetch over a World's root; a walk whose life names a scenario loads it as the World's (`scenarioPath`), and a
+/** A pack's fetch over a World's root (the World's scenario it reads itself, TWIN_WORLD_SCENARIO_FILE), and a
  *  life's application answers stand in for the application the vendor asks (`application`, this fetch's alone). */
-export type VendorFetchFactory = ((root: string, options?: { scenarioPath?: string; application?: ApplicationStandIn }) => ((request: Request) => Response | Promise<Response>) & ManagedDatabaseWalk) & { managedDatabaseDoor?: string };
+export type VendorFetchFactory = ((root: string, options?: { application?: ApplicationStandIn }) => ((request: Request) => Response | Promise<Response>) & ManagedDatabaseWalk) & { managedDatabaseDoor?: string };
 
 export async function vendorFetch(twinDir: string, vendor: string, dependenciesFrom = twinDir): Promise<VendorFetchFactory | undefined> {
   const directory = walkPackDirectory(twinDir, vendor, dependenciesFrom);
@@ -26,7 +26,7 @@ export async function packFetch(directory: string): Promise<VendorFetchFactory |
   // a pack exports create<Name>Fetch (its generated fetch.ts)
   const name = Object.keys(mod).find((k) => /^create\w+?Fetch$/.test(k) && !/TwinFetch$/.test(k) && typeof mod[k] === 'function');
   if (!name) return undefined;
-  const factory = mod[name] as (options: { root: string; database?: string; scenarioPath?: string; application?: ApplicationStandIn }) => ((request: Request) => Response | Promise<Response>) & Record<string, unknown>;
+  const factory = mod[name] as (options: { root: string; database?: string; application?: ApplicationStandIn }) => ((request: Request) => Response | Promise<Response>) & Record<string, unknown>;
   const descriptor = mod.pack as TwinPack | undefined;
   if (!descriptor?.managedDatabase) return (root: string, options = {}) => factory({ root, ...options });
   const managedDatabaseClock = descriptor.managedDatabase.clock;

package/src/walk/world-scenario.ts

@@ -0,0 +1,23 @@
+// The World's scenario as the standard plays it for a walk or a served pack (ADR 0036; architecture, "Scenarios"): the
+// document parsed and resolved as a World resolves it, written through the active World store, and named by
+// TWIN_WORLD_SCENARIO_FILE, where every twin in this process reads it at each request as it reads the clock. A pack takes
+// no scenario option: what it plays is the World's one scenario, so the standard sets the World's.
+import { parseScenario, resolveScenario, WORLD_SCENARIO_ENV, type ResolvedScenario } from '@volter/world-core';
+import { getActiveWorldStore } from '@volter/world-core/runtime';
+
+export type { ResolvedScenario };
+
+/** A scenario document as a World plays it; one the grammar refuses throws its ScenarioTimelineError, which names the
+ *  entry and the vocabulary it expected. */
+export function resolvedScenario(name: string, document: unknown): ResolvedScenario {
+  return resolveScenario(name, parseScenario(document));
+}
+
+/** Play `scenario` as the World's at `file` until the returned restore, which puts the variable back as it was. Playing
+ *  none clears the variable, so what the standard serves inside a World plays nothing of that World's. */
+export function playScenario(file: string, scenario: ResolvedScenario | undefined): () => void {
+  if (scenario) getActiveWorldStore().write(file, JSON.stringify(scenario));
+  const previous = process.env[WORLD_SCENARIO_ENV];
+  if (scenario) process.env[WORLD_SCENARIO_ENV] = file; else delete process.env[WORLD_SCENARIO_ENV];
+  return () => { if (previous === undefined) delete process.env[WORLD_SCENARIO_ENV]; else process.env[WORLD_SCENARIO_ENV] = previous; };
+}