@volter/world-core 3.0.166 → 3.0.167

package/src/scenario.ts

@@ -1,24 +1,12 @@
-import { exactInteger, compareExactNumbers, isExactIntegerValue } from './exact-json.ts';
-// THE scenario engine — System 2 of the twin programming model (one grammar, per-pack
-// vocabulary). See company-repo BRIEFS/TWIN-PROGRAMMING-MODEL.md (LOCKED, 2026-08-27).
+// A model vendor's turn, matched with the pack's own vocabulary (architecture, "Scenarios"; ADR 0036). The World's
+// scenario places turn decisions and faults on a timeline (scenario-timeline.ts); scenario-serve.ts hands the ones not
+// used up to this engine as ordered rules `{ on, respond | fault }`, and the first whose `on` conditions ALL hold, and
+// whose answer the request admits, decides the turn. No match is the miss: the pack's labelled deterministic stub.
 //
-// A HANDLER is an MSW-shaped data rule: { on, respond, once?, scope?, phase?, advancePhase? }.
-// Handlers are evaluated IN ORDER; the FIRST handler whose `on` conditions ALL hold fires.
-// No match → the caller serves its labeled deterministic stub and records the MISS (with the
-// request's extracted features — the authoring signal). The handler FILE in the world dir is
-// the only write surface; `engine.use(...)` exists for in-process tests only (LIFO over the
-// baseline, removable). There are NO runtime write doors — a running world is never mutated.
-//
-// The GRAMMAR (structure, ordering, once/scope/phase, strict validation, extractors,
-// placeholders, miss records) is this module's and identical for every vendor. The
-// VOCABULARY (which `on` keys exist and how each matches; what `respond` may contain; which
-// routes are stateful and therefore refuse success-shaped handlers) is the pack's, declared
-// through a PackScenarioAdapter. Determinism: the engine is a pure state machine — same
-// handler list + same request sequence → same decisions, byte for byte.
-//
-// STRICT EVERYWHERE (the gemini discipline): unknown top-level keys, unknown `on` keys,
-// unknown placeholder names, malformed extractors — all THROW with the valid vocabulary in
-// the message. A typo must fail loudly at load, never silently mis-match at serve.
+// The GRAMMAR (strict validation, ordering, the fault vocabulary) is this module's and the same for every vendor; the
+// VOCABULARY (which `on` keys exist and how each matches, what `respond` may contain, which routes are stateful and so
+// refuse success-shaped answers) is the pack's, declared through a PackScenarioAdapter. A typo fails loudly at load,
+// naming the valid vocabulary, never silently mis-matches at serve.
 
 /** A vendor-agnostic bag of facts about one request, produced by the pack's adapter. Powers
  *  matching context, miss records (the authoring signal), and the self-teaching stub text. */
@@ -36,8 +24,8 @@ export type PackScenarioAdapter<Req> = {
   /** The legal `on` keys and their per-request semantics. Pure. */
   matchers: Record<string, ScenarioMatcher<Req>>;
   /** Validate `on` CONDITION VALUES at load (key membership is the kernel's; VALUE typing is
-   *  the pack's — "a string nthCall silently never matches" is exactly the misfire strict
-   *  loading exists to prevent). Return an error string to refuse. */
+   *  the pack's — a mistyped value silently never matching is the misfire strict loading exists
+   *  to prevent). Return an error string to refuse. */
   validateOn?: (on: Record<string, unknown>) => string | null;
   /** Validate a handler's `respond` payload at load; return an error string to refuse.
    *  This is ALSO where a pack refuses success-shaped handlers on stateful routes
@@ -46,22 +34,10 @@ export type PackScenarioAdapter<Req> = {
   /** Whether the request admits a handler's answer (OpenAI's `tool_choice: 'none'` admits no tool call): a handler whose
    *  answer it does not admit is passed over, and the next that matches answers, else the stub. Absent, every answer. */
   admits?: (req: Req, respond: unknown) => boolean;
-  /** The request's text corpus for `textPattern` extractors (packs with text requests). */
-  text?: (req: Req) => string;
-  /** Pack-defined extractor KINDS beyond the builtins (feature, textPattern). A pack kind with
-   *  a builtin's name OVERRIDES the builtin (e.g. a richer textPattern with flags/group).
-   *  validate returns an error string to refuse the spec at load; extract runs at serve time
-   *  and throws ScenarioError when the request cannot supply the value. */
-  extractorKinds?: Record<string, {
-    validate: (spec: Record<string, unknown>, name: string) => string | null;
-    extract: (spec: Record<string, unknown>, req: Req, name: string) => string | number;
-  }>;
-  /** The per-session scope discriminator; omitted → all requests share one "world" scope. */
-  scopeKey?: (req: Req) => string;
-  /** The VENDOR'S error envelope for a `status` fault — a 429 from this vendor looks like this
-   *  vendor's 429. Omitted → the kernel's envelope `{ error: { message, type: "twin_fault" } }`. */
   /** Opt-in scope check for post-admission model generation failures; absent rejects them. */
   validateGenerationFault?: (fault: ScenarioGenerationFault, handler: ScenarioHandler) => string | null;
+  /** The VENDOR'S error envelope for a `status` fault — a 429 from this vendor looks like this
+   *  vendor's 429. Omitted → the kernel's envelope `{ error: { message, type: "twin_fault" } }`. */
   renderFault?: (fault: ScenarioStatusFault, req: Req) => { body: unknown; headers?: Record<string, string> };
 };
 
@@ -88,344 +64,72 @@ export type ScenarioStatusFault = Extract<ScenarioFault, { kind: "status" }>;
 export type ScenarioFaultResult = { status: number; headers: Record<string, string>; body: unknown };
 
 export type ScenarioHandler = {
-  /** Stable id for status/telemetry; defaults to `handler-<1-based index>`. */
+  /** The rule's id: `entry-<n>`, the timeline entry it came from. */
   id?: string;
-  /** Conditions — ALL must hold. `{}` matches every request (an ordered catch-all). */
+  /** Conditions — ALL must hold. `{}` matches every request. */
   on: Record<string, unknown>;
-  /** Pack-realized response content (the pack's realizer builds the faithful envelope).
-   *  Optional only on a handler that carries a `fault` (a `slow` may still carry one; a
-   *  `status` or `drop` serves no content, so it must not). */
+  /** The turn's answer, which the pack realizes into the vendor's envelope; absent on a fault. */
   respond?: unknown;
-  /** A fault to inject when this handler fires (ScenarioFault). Same once/phase/scope
-   *  semantics as any handler — a mid-story outage is `{on, fault, once}` or `{phase}`. */
+  /** The fault that answers the turn instead (ScenarioFault). */
   fault?: ScenarioFault;
-  /** Fire at most once per scope. */
-  once?: boolean;
-  /** Reserved: "world" (default) | "session" — with "session", once/phase state is per
-   *  scopeKey instead of shared. */
-  scope?: "world" | "session";
-  /** Fires only while the scope's phase equals this. Handlers without `phase` fire in any. */
-  phase?: string;
-  /** On fire, move the scope's phase — the tiny sequencing primitive that replaces
-   *  linear scripts and nthCall arithmetic. */
-  advancePhase?: string;
 };
 
-/** Request-derived values a `respond` payload may reference as "{{name}}" placeholders —
- *  builtin kinds, or any kind the pack's adapter declares. Payload placeholders support the
- *  numeric transforms `{{name|min:N}}` / `{{name|max:N}}`; a whole-string placeholder yields
- *  the TYPED value (numbers stay numbers). */
-export type ScenarioExtractorSpec =
-  | { kind: "feature"; feature: string }
-  | { kind: "textPattern"; pattern: string; as?: "string" | "number" }
-  | ({ kind: string } & Record<string, unknown>);
-
-export type ScenarioDocument = {
-  extractors?: Record<string, ScenarioExtractorSpec>;
-  handlers: ScenarioHandler[];
-};
+/** The ordered rules of one turn. */
+export type ScenarioDocument = { handlers: ScenarioHandler[] };
 
-export type ScenarioMissRecord = { features: ScenarioFeatures; phase: string | undefined };
+export type ScenarioMissRecord = { features: ScenarioFeatures };
 
 export type ScenarioDecision =
   | { kind: "handler"; handler: ScenarioHandler; respond: unknown; ruleId: string; fault?: ScenarioFault }
   | { kind: "miss"; miss: ScenarioMissRecord };
 
-export type ScenarioStatus = {
-  vendor: string;
-  handlers: Array<{ id: string; phase?: string; once?: boolean; scope?: string; matches: number; source: "file" | "use" }>;
-  misses: number;
-  recentMisses: ScenarioMissRecord[];
-};
-
 export class ScenarioError extends Error {}
 
-// `$comment` is allowed (and ignored) at document and handler level — JSON has no comments
-// and scenario files are hand-authored story documents.
-const HANDLER_KEYS = new Set(["id", "on", "respond", "fault", "once", "scope", "phase", "advancePhase", "$comment"]);
-const DOCUMENT_KEYS = new Set(["extractors", "handlers", "$comment"]);
+const HANDLER_KEYS = new Set(["id", "on", "respond", "fault"]);
 
-/** Strict-loud parse of a scenario DOCUMENT (the per-vendor handlers/<vendor>.json content).
- *  The caller does file IO; this validates. Every refusal names the valid vocabulary. */
-export function parseScenarioDocument<Req>(raw: unknown, adapter: PackScenarioAdapter<Req>): ScenarioDocument {
-  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) throw new ScenarioError(`${adapter.vendor} scenario: the document is an object { extractors?, handlers }`);
-  const doc = raw as Record<string, unknown>;
-  for (const key of Object.keys(doc)) {
-    if (!DOCUMENT_KEYS.has(key)) throw new ScenarioError(`${adapter.vendor} scenario: unknown key "${key}" (valid: ${[...DOCUMENT_KEYS].join(", ")})`);
-  }
-  const extractors: Record<string, ScenarioExtractorSpec> = {};
-  if (doc.extractors !== undefined) {
-    if (typeof doc.extractors !== "object" || doc.extractors === null || Array.isArray(doc.extractors)) throw new ScenarioError(`${adapter.vendor} scenario: extractors is an object of named specs`);
-    for (const [name, spec] of Object.entries(doc.extractors as Record<string, unknown>)) {
-      extractors[name] = parseExtractor(name, spec, adapter);
-    }
-  }
-  if (!Array.isArray(doc.handlers)) throw new ScenarioError(`${adapter.vendor} scenario: handlers is an array`);
-  const handlers = (doc.handlers as unknown[]).map((h, i) => parseHandler(h, i, adapter, extractors));
-  return { ...(doc.extractors !== undefined ? { extractors } : {}), handlers };
+/** Strict-loud parse of a turn's rules. Every refusal names the valid vocabulary. */
+export function parseScenarioDocument<Req>(raw: ScenarioDocument, adapter: PackScenarioAdapter<Req>): ScenarioDocument {
+  return { handlers: raw.handlers.map((h, i) => parseHandler(h, i, adapter)) };
 }
 
-function parseExtractor<Req>(name: string, raw: unknown, adapter: PackScenarioAdapter<Req>): ScenarioExtractorSpec {
-  if (typeof raw !== "object" || raw === null) throw new ScenarioError(`${adapter.vendor} scenario: extractor "${name}" is an object`);
-  const spec = raw as Record<string, unknown>;
-  const packKind = typeof spec.kind === "string" ? adapter.extractorKinds?.[spec.kind] : undefined;
-  if (packKind !== undefined) {
-    const refusal = packKind.validate(spec, name);
-    if (refusal) throw new ScenarioError(`${adapter.vendor} scenario: extractor "${name}": ${refusal}`);
-    return spec as ScenarioExtractorSpec;
-  }
-  if (spec.kind === "feature") {
-    if (typeof spec.feature !== "string" || spec.feature.length === 0) throw new ScenarioError(`${adapter.vendor} scenario: extractor "${name}" (feature) needs a feature name`);
-    for (const key of Object.keys(spec)) if (key !== "kind" && key !== "feature") throw new ScenarioError(`${adapter.vendor} scenario: extractor "${name}": unknown key "${key}"`);
-    return { kind: "feature", feature: spec.feature };
-  }
-  if (spec.kind === "textPattern") {
-    if (adapter.text === undefined) throw new ScenarioError(`${adapter.vendor} scenario: extractor "${name}" uses textPattern but this pack exposes no request text`);
-    if (typeof spec.pattern !== "string") throw new ScenarioError(`${adapter.vendor} scenario: extractor "${name}" (textPattern) needs a pattern`);
-    try { new RegExp(spec.pattern); } catch (e) { throw new ScenarioError(`${adapter.vendor} scenario: extractor "${name}": invalid pattern: ${e instanceof Error ? e.message : String(e)}`); }
-    if (spec.as !== undefined && spec.as !== "string" && spec.as !== "number") throw new ScenarioError(`${adapter.vendor} scenario: extractor "${name}": as is "string" or "number"`);
-    for (const key of Object.keys(spec)) if (!["kind", "pattern", "as"].includes(key)) throw new ScenarioError(`${adapter.vendor} scenario: extractor "${name}": unknown key "${key}"`);
-    return { kind: "textPattern", pattern: spec.pattern, ...(spec.as !== undefined ? { as: spec.as as "string" | "number" } : {}) };
-  }
-  throw new ScenarioError(`${adapter.vendor} scenario: extractor "${name}": kind is one of ${[...new Set(["feature", "textPattern", ...Object.keys(adapter.extractorKinds ?? {})])].join(", ")}`);
-}
-
-function parseHandler<Req>(raw: unknown, index: number, adapter: PackScenarioAdapter<Req>, extractors: Record<string, ScenarioExtractorSpec>): ScenarioHandler {
-  const at = `handler ${index + 1}`;
-  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) throw new ScenarioError(`${adapter.vendor} scenario: ${at} is an object { on, respond, ... }`);
+function parseHandler<Req>(raw: unknown, index: number, adapter: PackScenarioAdapter<Req>): ScenarioHandler {
   const h = raw as Record<string, unknown>;
+  const at = typeof h.id === "string" ? h.id : `rule ${index + 1}`;
   for (const key of Object.keys(h)) {
     if (!HANDLER_KEYS.has(key)) throw new ScenarioError(`${adapter.vendor} scenario: ${at}: unknown key "${key}" (valid: ${[...HANDLER_KEYS].join(", ")})`);
   }
   if (typeof h.on !== "object" || h.on === null || Array.isArray(h.on)) throw new ScenarioError(`${adapter.vendor} scenario: ${at}: \`on\` is an object of conditions ({} matches all)`);
-  // `nthCall` is the one kernel-builtin condition (1-based per-scope call index); every other
-  // `on` key is the pack's declared vocabulary.
-  const validOn = ["nthCall", ...Object.keys(adapter.matchers)];
-  for (const [key, value] of Object.entries(h.on as Record<string, unknown>)) {
+  const validOn = Object.keys(adapter.matchers);
+  for (const key of Object.keys(h.on as Record<string, unknown>)) {
     if (!validOn.includes(key)) throw new ScenarioError(`${adapter.vendor} scenario: ${at}: unknown \`on\` key "${key}" (valid here: ${validOn.join(", ")})`);
-    if (key === "nthCall" && (!Number.isInteger(value) || (value as number) < 1)) throw new ScenarioError(`${adapter.vendor} scenario: ${at}: nthCall is a positive integer`);
   }
   const onRefusal = adapter.validateOn?.(h.on as Record<string, unknown>);
   if (onRefusal) throw new ScenarioError(`${adapter.vendor} scenario: ${at}: ${onRefusal}`);
-  if (h.fault !== undefined) {
-    const f = h.fault as Record<string, unknown>;
-    if (typeof f !== "object" || f === null || Array.isArray(f)) throw new ScenarioError(`${adapter.vendor} scenario: ${at}: fault is an object { kind: "slow" | "status" | "drop" | "generation", ... }`);
-    const kinds = ["slow", "status", "drop", "generation"];
-    if (!kinds.includes(f.kind as string)) throw new ScenarioError(`${adapter.vendor} scenario: ${at}: fault.kind is one of ${kinds.join(", ")}, got ${JSON.stringify(f.kind)}`);
-    const keysFor: Record<string, string[]> = { slow: ["kind", "ms"], status: ["kind", "status", "retryAfterSeconds", "message", "metadata", "errorType"], generation: ["kind", "status", "message", "errorType", "metadata", "partialText", "event"], drop: ["kind", "holdMs"] };
-    for (const key of Object.keys(f)) if (!keysFor[f.kind as string]!.includes(key)) throw new ScenarioError(`${adapter.vendor} scenario: ${at}: fault.${key} is not a key of a ${String(f.kind)} fault (valid: ${keysFor[f.kind as string]!.join(", ")})`);
-    if (f.kind === "slow" && !(Number.isInteger(f.ms) && (f.ms as number) >= 0 && (f.ms as number) <= 600_000)) throw new ScenarioError(`${adapter.vendor} scenario: ${at}: fault.ms is an integer 0..600000 (milliseconds)`);
-    if ((f.kind === "status" || f.kind === "generation") && !(Number.isInteger(f.status) && (f.status as number) >= 400 && (f.status as number) <= 599)) throw new ScenarioError(`${adapter.vendor} scenario: ${at}: fault.status is an integer 400..599 — a fault is a refusal or a failure, never a success`);
-    if (f.kind === "status" && f.retryAfterSeconds !== undefined && !(Number.isInteger(f.retryAfterSeconds) && (f.retryAfterSeconds as number) >= 0)) throw new ScenarioError(`${adapter.vendor} scenario: ${at}: fault.retryAfterSeconds is a non-negative integer`);
-    if (f.kind === "status" && f.message !== undefined && typeof f.message !== "string") throw new ScenarioError(`${adapter.vendor} scenario: ${at}: fault.message is a string`);
-    if ((f.kind === "status" || f.kind === "generation") && f.metadata !== undefined && (typeof f.metadata !== "object" || f.metadata === null || Array.isArray(f.metadata))) throw new ScenarioError(`${adapter.vendor} scenario: ${at}: fault.metadata is an object`);
-    if (f.kind === "status" && f.errorType !== undefined && typeof f.errorType !== "string") throw new ScenarioError(`${adapter.vendor} scenario: ${at}: fault.errorType is a string`);
-    if (f.kind === "generation") {
-      if (typeof f.message !== "string" || typeof f.errorType !== "string" || !f.errorType) throw new ScenarioError(`${adapter.vendor} scenario: ${at}: generation fault requires message and nonempty errorType`);
-      for (const key of ["partialText", "event"]) if (f[key] !== undefined && typeof f[key] !== "string") throw new ScenarioError(`${adapter.vendor} scenario: ${at}: fault.${key} is a string`);
-      if (!adapter.validateGenerationFault) throw new ScenarioError(`${adapter.vendor} scenario: ${at}: generation faults require a compute-only adapter`);
-      const refusal = adapter.validateGenerationFault(f as ScenarioGenerationFault, h as unknown as ScenarioHandler);
-      if (refusal) throw new ScenarioError(`${adapter.vendor} scenario: ${at}: ${refusal}`);
-    }
-    if (f.kind === "drop" && f.holdMs !== undefined && !(Number.isInteger(f.holdMs) && (f.holdMs as number) >= 0)) throw new ScenarioError(`${adapter.vendor} scenario: ${at}: fault.holdMs is a non-negative integer`);
-    if (f.kind !== "slow" && "respond" in h) throw new ScenarioError(`${adapter.vendor} scenario: ${at}: a ${String(f.kind)} fault serves no content — drop \`respond\` (only a slow fault may carry one)`);
-  }
-  if (!("respond" in h) && h.fault === undefined) throw new ScenarioError(`${adapter.vendor} scenario: ${at}: \`respond\` is required (or a \`fault\`)`);
-  if (h.id !== undefined && (typeof h.id !== "string" || h.id.length === 0)) throw new ScenarioError(`${adapter.vendor} scenario: ${at}: id is a non-empty string`);
-  if (h.once !== undefined && typeof h.once !== "boolean") throw new ScenarioError(`${adapter.vendor} scenario: ${at}: once is boolean`);
-  if (h.scope !== undefined && h.scope !== "world" && h.scope !== "session") throw new ScenarioError(`${adapter.vendor} scenario: ${at}: scope is "world" or "session"`);
-  if (h.scope === "session" && adapter.scopeKey === undefined) throw new ScenarioError(`${adapter.vendor} scenario: ${at}: scope "session" but this pack derives no session key`);
-  for (const key of ["phase", "advancePhase"] as const) {
-    if (h[key] !== undefined && (typeof h[key] !== "string" || (h[key] as string).length === 0)) throw new ScenarioError(`${adapter.vendor} scenario: ${at}: ${key} is a non-empty string`);
-  }
-  for (const name of "respond" in h ? placeholderNames(h.respond) : []) {
-    if (extractors[name] === undefined) throw new ScenarioError(`${adapter.vendor} scenario: ${at}: respond references "{{${name}}}" but no extractor "${name}" is declared`);
+  if (h.fault !== undefined && (h.fault as ScenarioFault).kind === "generation") {
+    if (!adapter.validateGenerationFault) throw new ScenarioError(`${adapter.vendor} scenario: ${at}: generation faults require a compute-only adapter`);
+    const refusal = adapter.validateGenerationFault(h.fault as ScenarioGenerationFault, h as unknown as ScenarioHandler);
+    if (refusal) throw new ScenarioError(`${adapter.vendor} scenario: ${at}: ${refusal}`);
   }
   const refusal = "respond" in h ? adapter.validateRespond?.(h.respond, h as ScenarioHandler) : null;
   if (refusal) throw new ScenarioError(`${adapter.vendor} scenario: ${at}: ${refusal}`);
   return h as ScenarioHandler;
 }
 
-const PLACEHOLDER_SRC = "\\{\\{([a-zA-Z0-9_.-]+)(\\|(?:min|max):-?[\\d.]+)?\\}\\}";
-
-function placeholderNames(value: unknown, out: Set<string> = new Set()): Set<string> {
-  if (typeof value === "string") {
-    for (const m of value.matchAll(new RegExp(PLACEHOLDER_SRC, "g"))) out.add(m[1]!);
-    // A lone unparseable {{...}} is almost certainly a typo'd placeholder — fail loudly.
-    const braces = /\{\{[^}]*\}\}/g.exec(value);
-    if (braces && !new RegExp(`^${PLACEHOLDER_SRC}$`).test(braces[0])) {
-      throw new ScenarioError(`malformed placeholder ${JSON.stringify(braces[0])} (expected {{name}} or {{name|min:N}}/{{name|max:N}})`);
-    }
-  } else if (Array.isArray(value)) {
-    for (const v of value) placeholderNames(v, out);
-  } else if (typeof value === "object" && value !== null) {
-    for (const v of Object.values(value)) placeholderNames(v, out);
-  }
-  return out;
-}
-
-function adapterKind<Req>(adapter: PackScenarioAdapter<Req>, kind: string): { validate: (spec: Record<string, unknown>, name: string) => string | null; extract: (spec: Record<string, unknown>, req: Req, name: string) => string | number } | undefined {
-  return adapter.extractorKinds?.[kind];
-}
-
-/** `{{name|min:N}}` / `{{name|max:N}}` — numeric clamps on an extracted value. */
-function applyTransform(value: string | number, transform: string | undefined, vendor: string, where: string): string | number {
-  if (!transform) return value;
-  const [op, rawN] = transform.slice(1).split(":") as [string, string];
-  if (typeof value !== "number" && !(typeof value === "string" && isExactIntegerValue(value))) throw new ScenarioError(`${vendor} scenario: ${where} applies |${op}:${rawN} to a non-numeric extractor value ${JSON.stringify(value)}`);
-  const n = /^-?\d+$/.test(rawN) ? exactInteger(rawN) : Number(rawN);
-  const cmp = compareExactNumbers(value, n);
-  return op === "min" ? (cmp <= 0 ? value : n) : (cmp >= 0 ? value : n);
-}
-
-type ScopeState = { calls: number; phase: string | undefined; onceFired: Set<string> };
-type Registered = { handler: ScenarioHandler; id: string; source: "file" | "use"; matches: number };
-
-const MISS_KEEP = 20;
-
-/** The engine: pure state machine over registered handlers. One instance per twin server. */
+/** The engine over one turn's rules: pure, the same rules and request giving the same decision. */
 export class ScenarioEngine<Req> {
-  private readonly adapter: PackScenarioAdapter<Req>;
-  private readonly extractors: Record<string, ScenarioExtractorSpec>;
-  private baseline: Registered[] = [];
-  private overrides: Registered[] = [];
-  private scopes = new Map<string, ScopeState>();
-  private missCount = 0;
-  private recentMisses: ScenarioMissRecord[] = [];
-
-  constructor(adapter: PackScenarioAdapter<Req>, document?: ScenarioDocument) {
-    this.adapter = adapter;
-    this.extractors = document?.extractors ?? {};
-    if (document) {
-      this.baseline = document.handlers.map((handler, i) => ({ handler, id: handler.id ?? `handler-${i + 1}`, source: "file", matches: 0 }));
-    }
-  }
+  constructor(private readonly adapter: PackScenarioAdapter<Req>, private readonly document: ScenarioDocument) {}
 
-  /** In-process test overrides: LIFO over the baseline; returns a remover. NOT a runtime
-   *  door — nothing outside this process can reach it, by design. */
-  use(...handlers: ScenarioHandler[]): () => void {
-    const parsed = handlers.map((h, i) => parseHandler(h, i, this.adapter, this.extractors));
-    const registered: Registered[] = parsed.map((handler, i) => ({ handler, id: handler.id ?? `use-${this.overrides.length + i + 1}`, source: "use", matches: 0 }));
-    this.overrides = [...registered, ...this.overrides]; // LIFO: newest first
-    return () => { this.overrides = this.overrides.filter((r) => !registered.includes(r)); };
-  }
-
-  /** Decide one request. Mutates scope state (calls, once, phase) exactly like serving. */
+  /** Decide one request: the first rule that matches and whose answer the request admits, else the miss. */
   next(req: Req): ScenarioDecision {
-    const scopeOf = (h: ScenarioHandler): string => (h.scope === "session" ? `session:${this.adapter.scopeKey!(req)}` : "world");
-    // The call counter ticks once per request on the WORLD scope (and the session scope when
-    // one exists) — before matching, so nthCall-style matchers see 1-based "this call".
-    this.scope("world").calls += 1;
-    if (this.adapter.scopeKey) this.scope(`session:${this.adapter.scopeKey(req)}`).calls += 1;
-    for (const r of [...this.overrides, ...this.baseline]) {
-      const scope = this.scope(scopeOf(r.handler));
-      if (r.handler.phase !== undefined && scope.phase !== r.handler.phase) continue;
-      if (r.handler.once && scope.onceFired.has(r.id)) continue;
-      if (!this.matches(r.handler, req, scope)) continue;
-      if ("respond" in r.handler && this.adapter.admits && !this.adapter.admits(req, r.handler.respond)) continue;
-      if (r.handler.once) scope.onceFired.add(r.id);
-      if (r.handler.advancePhase !== undefined) scope.phase = r.handler.advancePhase;
-      r.matches += 1;
-      // `ruleId` is the row's STABLE id — the authored `id` or the parser's `handler-<n>`
-      // default — the same name the status door reports, so a pack stamping the fired rule
-      // (deepgram's `scenario_rule`) and the operator reading /twin/scenario see one vocabulary.
-      try {
-        return { kind: "handler", handler: r.handler, respond: "respond" in r.handler ? this.substitute(r.handler.respond, req) : undefined, ruleId: r.id, ...(r.handler.fault !== undefined ? { fault: r.handler.fault } : {}) };
-      } catch (e) {
-        // The handler that demanded the value is named: an authoring fault is fixed by finding it.
-        if (e instanceof ScenarioError) throw new ScenarioError(`${e.message} [${r.id}${typeof (r.handler as { $comment?: unknown }).$comment === "string" ? `: ${String((r.handler as { $comment?: string }).$comment).slice(0, 80)}` : ""}]`);
-        throw e;
-      }
-    }
-    const miss: ScenarioMissRecord = { features: this.adapter.features(req), phase: this.scope("world").phase };
-    this.missCount += 1;
-    this.recentMisses = [...this.recentMisses.slice(-(MISS_KEEP - 1)), miss];
-    return { kind: "miss", miss };
-  }
-
-  /** Decide one request AND honor its fault: a `slow` is awaited here and the decision is
-   *  returned for the pack to serve; a `status` returns the rendered refusal to serve as-is; a
-   *  `drop` never resolves within its hold. The one call a realizer makes so every vendor's
-   *  outage reads the same. */
-  async serve(req: Req, signal?: AbortSignal): Promise<ScenarioDecision | { kind: "fault"; result: ScenarioFaultResult; ruleId: string }> {
-    throwIfScenarioAborted(signal);
-    const decision = this.next(req);
-    throwIfScenarioAborted(signal);
-    if (decision.kind !== "handler" || decision.fault === undefined) return decision;
-    const result = await scenarioFaultResult(decision.fault, () => this.adapter.renderFault?.(decision.fault as ScenarioStatusFault, req), signal);
-    throwIfScenarioAborted(signal);
-    return result === null ? decision : { kind: "fault", result, ruleId: decision.ruleId };
-  }
-
-  /** For GET /twin/scenario — active handlers with match counts, and the recent misses. */
-  status(): ScenarioStatus {
-    const row = (r: Registered) => ({ id: r.id, ...(r.handler.phase !== undefined ? { phase: r.handler.phase } : {}), ...(r.handler.once !== undefined ? { once: r.handler.once } : {}), ...(r.handler.scope !== undefined ? { scope: r.handler.scope } : {}), matches: r.matches, source: r.source });
-    return { vendor: this.adapter.vendor, handlers: [...this.overrides, ...this.baseline].map(row), misses: this.missCount, recentMisses: [...this.recentMisses] };
-  }
-
-  private scope(key: string): ScopeState {
-    let s = this.scopes.get(key);
-    if (!s) { s = { calls: 0, phase: undefined, onceFired: new Set() }; this.scopes.set(key, s); }
-    return s;
-  }
-
-  private matches(handler: ScenarioHandler, req: Req, scope: ScopeState): boolean {
-    for (const [key, condition] of Object.entries(handler.on)) {
-      if (key === "nthCall") { if (scope.calls !== condition) return false; continue; }
-      const matcher = this.adapter.matchers[key];
-      if (!matcher) return false; // unreachable post-parse; belt over braces
-      if (!matcher(req, condition)) return false;
-    }
-    return true;
-  }
-
-  private extractValue(name: string, req: Req, cache: Map<string, string | number>): string | number {
-    const cached = cache.get(name);
-    if (cached !== undefined) return cached;
-    const spec = this.extractors[name]!;
-    const packKind = adapterKind(this.adapter, spec.kind);
-    let value: string | number;
-    if (packKind !== undefined) {
-      value = packKind.extract(spec as Record<string, unknown>, req, name);
-    } else if (spec.kind === "feature") {
-      const v = this.adapter.features(req)[(spec as { feature: string }).feature];
-      if (v === undefined) throw new ScenarioError(`${this.adapter.vendor} scenario: placeholder "{{${name}}}": the request has no feature "${(spec as { feature: string }).feature}"`);
-      value = typeof v === "number" || typeof v === "string" ? v : String(v);
-    } else {
-      const text = this.adapter.text!(req);
-      const tp = spec as { pattern: string; as?: string };
-      const m = new RegExp(tp.pattern).exec(text);
-      if (!m) throw new ScenarioError(`${this.adapter.vendor} scenario: placeholder "{{${name}}}": pattern did not match the request (the handler demanded a value the request never stated)`);
-      const captured = m[1] ?? m[0]!;
-      if (tp.as === "number") {
-        const n = /^-?\d+$/.test(captured) ? exactInteger(captured) : Number(captured);
-        if (Number.isNaN(n)) throw new ScenarioError(`${this.adapter.vendor} scenario: placeholder "{{${name}}}": captured "${captured}" is not a number`);
-        value = n;
-      } else value = captured;
-    }
-    cache.set(name, value);
-    return value;
-  }
-
-  private substitute(value: unknown, req: Req, cache: Map<string, string | number> = new Map()): unknown {
-    if (typeof value === "string") {
-      // A WHOLE-string placeholder yields the typed value (numbers stay numbers).
-      const whole = new RegExp(`^${PLACEHOLDER_SRC}$`).exec(value);
-      if (whole) return applyTransform(this.extractValue(whole[1]!, req, cache), whole[2], this.adapter.vendor, value);
-      return value.replace(new RegExp(PLACEHOLDER_SRC, "g"), (all, name: string, transform: string | undefined) =>
-        String(applyTransform(this.extractValue(name, req, cache), transform, this.adapter.vendor, all)));
-    }
-    if (Array.isArray(value)) return value.map((v) => this.substitute(v, req, cache));
-    if (typeof value === "object" && value !== null) {
-      return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, this.substitute(v, req, cache)]));
+    for (const [i, handler] of this.document.handlers.entries()) {
+      if (!Object.entries(handler.on).every(([key, condition]) => this.adapter.matchers[key]!(req, condition))) continue;
+      if ("respond" in handler && this.adapter.admits && !this.adapter.admits(req, handler.respond)) continue;
+      return { kind: "handler", handler, respond: handler.respond, ruleId: handler.id ?? `rule-${i + 1}`, ...(handler.fault !== undefined ? { fault: handler.fault } : {}) };
     }
-    return value;
+    return { kind: "miss", miss: { features: this.adapter.features(req) } };
   }
 }
 
-/** The GET /twin manifest for a STATEFUL twin (no scenario engine): what it stores, how
- *  state and identity work, where behavior scripting actually lives. Education ships
- *  INSIDE the twin — in-world agents have no repos or skills, only HTTP. */
 /** Honor a fault outside the engine (hand-written serve paths): `slow` waits and returns null
  *  (serve normally now); `status` returns what to serve; `drop` holds the request for `holdMs`
  *  (default 300 000) and then throws, so the socket is released and nothing is ever answered. */
@@ -486,8 +190,7 @@ export function statefulTwinManifest(input: { vendor: string; twinOf: string; st
 
 /** The GET /twin manifest — the discovery door's body. Education ships INSIDE the twin:
  *  in-world agents have no repos or skills, only HTTP. */
-export function twinManifest(input: { vendor: string; twinOf: string; stateSentence: string; behaviorSentence: string; exampleHandler: ScenarioHandler | null; engine?: ScenarioEngine<never> }): Record<string, unknown> {
-  const status = input.engine?.status();
+export function twinManifest(input: { vendor: string; twinOf: string; stateSentence: string; behaviorSentence: string; exampleHandler: ScenarioHandler | null }): Record<string, unknown> {
   return {
     twin: true,
     vendor: input.vendor,
@@ -495,10 +198,9 @@ export function twinManifest(input: { vendor: string; twinOf: string; stateSente
     program: {
       state: input.stateSentence,
       behavior: input.behaviorSentence,
-      invariant: "A handler never fakes a SUCCESS on a route whose data this twin stores — seed that through the vendor's own API instead. Serving is deterministic.",
-      ...(input.exampleHandler ? { exampleHandler: input.exampleHandler } : {}),
+      invariant: "Nothing answers in place of this twin: a World's scenario places turn decisions (point \"turn\") on its timeline, and the twin answers and records them; stored data is seeded through the vendor's own API. Serving is deterministic.",
+      ...(input.exampleHandler ? { exampleDecision: { at: "0s", decision: { vendor: input.vendor, point: "turn", on: input.exampleHandler.on, outcome: input.exampleHandler.respond } } } : {}),
     },
-    doors: { manifest: "GET /twin", scenario: "GET /twin/scenario (read-only: active handlers + match/miss counts)" },
-    ...(status ? { activeHandlers: status.handlers.length, misses: status.misses } : {}),
+    doors: { manifest: "GET /twin", scenario: "GET /twin/scenario (read-only: what the World's scenario placed on this twin, and what it consumed)" },
   };
 }

package/src/sockets.ts

@@ -9,7 +9,7 @@ import { runWithStorageTenant, storageTenant } from './request-scope.ts';
 // Nothing here runs at module scope beyond the empty registry.
 import { worldNow } from './world-clock.ts';
 import type { EventWrite } from './events.ts';
-import type { ScenarioEngine } from './scenario.ts';
+import type { ScenarioDecision, ScenarioFaultResult } from './scenario.ts';
 import type { WebSocketPeer, WebSocketUpgrade } from './serve-http.ts';
 
 /** A socket the vendor serves: its path (and host, when the vendor serves it on a host of its own), as the manifest
@@ -36,8 +36,8 @@ export type SocketSession = {
   decide(asked: unknown): Promise<ScenarioServed | undefined>;
 };
 
-/** What the World's scenario serves a turn: a handler's decision, a miss, or a fault (scenario.ts `serve`). */
-export type ScenarioServed = Awaited<ReturnType<ScenarioEngine<unknown>['serve']>>;
+/** What the World's scenario serves a turn (scenario-serve.ts): its decision, the miss, or a fault's answer. */
+export type ScenarioServed = ScenarioDecision | { kind: 'fault'; result: ScenarioFaultResult; ruleId: string };
 
 /** A socket's protocol, over the handler contract's context (a read of the World as the request that opened it). */
 export type SocketEngine<C> = {
@@ -108,7 +108,7 @@ export function socketUpgrade<C>(
   context: (request: Request, decl: SocketDecl, params: Record<string, string>) => Promise<C>,
   hostOf: (request: Request) => string,
   pathOf: (request: Request) => string,
-  decide: (asked: unknown) => Promise<ScenarioServed | undefined>,
+  decide: (asked: unknown, context: () => Promise<C>) => Promise<ScenarioServed | undefined>,
 ): WebSocketUpgrade {
   const matchFor = (request: Request): { decl: SocketDecl; params: Record<string, string> } | undefined => {
     const path = pathOf(request).replace(/\/+$/, '') || '/';
@@ -149,7 +149,7 @@ export function socketUpgrade<C>(
           clearTimeout(p.timer); pending.delete(key); p.resolve(value);
           return true;
         },
-        decide,
+        decide: (asked) => decide(asked, () => o.context() as Promise<C>),
       };
       const tenant = storageTenant(service), run = <T>(fn: () => T): T => runWithStorageTenant(service, tenant, fn);
       const o: Open = { tenant, run, session, engine, context: () => context(request.clone(), decl, params), queue: Promise.resolve(), pending };

package/src/world-clock.ts

@@ -25,16 +25,23 @@ const machineNow = (): number => {
 /** The world's "now": the clock file's time when one is configured (its frozen instant, or a running clock's time
  *  now); real wall-clock time otherwise. */
 export function worldNow(): string {
+  const clock = heldClock();
+  return new Date(clock ? clockForm.clockNowMs(clock, machineNow()) : machineNow()).toISOString();
+}
+
+/** The World's clock as its file holds it, or null where it has none (the machine's time). One read answers both
+ *  whether the clock file is there and what it holds, kept while the file's own facts stand (world-store.ts readKept):
+ *  every operation asks the time. A configured-but-corrupt clock is a World defect: parseClock fails loudly, never
+ *  drifting back to the wall clock (two services disagreeing about now breaks the World). */
+function heldClock(): ReturnType<typeof clockForm.parseClock> | null {
   const file = process.env[WORLD_CLOCK_ENV];
-  // One read answers both whether the clock file is there and what it holds.
-  // Kept while the clock file's own facts stand (world-store.ts readKept): every operation asks the time.
   const store = getActiveWorldStore();
   const held = file ? (store.readKept ? store.readKept(file) : store.read(file)) : null;
-  if (held !== null) {
-    // A configured-but-corrupt clock is a WORLD defect — parseClock fails loudly, never silently drifting back to
-    // wall-clock (two services disagreeing about now breaks the world).
-    const clock = clockForm.parseClock(held);
-    return new Date(clockForm.clockNowMs(clock, machineNow())).toISOString();
-  }
-  return new Date(machineNow()).toISOString();
+  return held === null ? null : clockForm.parseClock(held);
+}
+
+/** Whether the World's time runs on by itself (a running clock, or no clock: the machine's), rather than standing frozen
+ *  until it is moved. */
+export function worldClockRunning(): boolean {
+  return heldClock()?.kind !== 'frozen';
 }