@volter/world-core 2.0.0

package/src/references.ts

@@ -0,0 +1,46 @@
+// REFERENCES — docs/contributing/architecture.md#alias-aware-lookup-at-the-request-boundary: an id is adopted once and every declared
+// reference follows it. Adoption is an alias (`aliasOf` on the landed copy; the fold moves the
+// subject). A pack DECLARES which fields of which subject types hold another subject's id; the
+// kernel resolves those fields through the alias map — in the tree, whatever order the entries fold
+// in, and at the perform, so the vendor is asked about #7, never the local #3.
+//
+// One registry per process (a pack installed beside a world carries its own copy of the kernel).
+import type { SubjectFields } from './hash.ts';
+
+export type ReferenceDeclaration = {
+  /** the referencing subject type */
+  type: string;
+  /** the referenced subject type */
+  to: string;
+  /** the referenced subject's id, read from the referencing subject's fields (undefined: no reference) */
+  key: (fields: SubjectFields) => string | undefined;
+  /** the fields to overlay once the referenced subject's id is `vendorId` */
+  adopt: (fields: SubjectFields, vendorId: string) => SubjectFields;
+};
+
+/** The common case: one field holds the referenced subject's id as it is. */
+export function referenceField(type: string, field: string, to: string): ReferenceDeclaration {
+  return { type, to, key: (f) => (f[field] === undefined || f[field] === null ? undefined : String(f[field])), adopt: (_f, vendorId) => ({ [field]: vendorId }) };
+}
+
+const REGISTRY = Symbol.for('volter.references');
+const registry = (): Map<string, ReferenceDeclaration[]> => ((globalThis as Record<symbol, unknown>)[REGISTRY] ??= new Map<string, ReferenceDeclaration[]>()) as Map<string, ReferenceDeclaration[]>;
+
+export function registerReferences(vendor: string, references: ReferenceDeclaration[]): void { registry().set(vendor, references); }
+export function packReferences(vendor: string): ReferenceDeclaration[] { return registry().get(vendor) ?? []; }
+
+/** `fields` of a `type` subject with every declared reference resolved through `aliases`
+ *  (`${type}:${oldId}` → newId, as `aliasesFrom` builds it). The same object when nothing applies. */
+export function resolveReferences(vendor: string, type: string, fields: SubjectFields, aliases: Map<string, string>): SubjectFields {
+  if (aliases.size === 0) return fields;
+  let out = fields;
+  for (const ref of packReferences(vendor)) {
+    if (ref.type !== type) continue;
+    const key = ref.key(out);
+    if (key === undefined) continue;
+    const adopted = aliases.get(`${ref.to}:${key}`);
+    if (adopted === undefined || adopted === key) continue;
+    out = { ...out, ...ref.adopt(out, adopted) };
+  }
+  return out;
+}

package/src/remote-execute.ts

@@ -0,0 +1,26 @@
+// THE ONE PULL EXECUTOR SHAPE (runtime contract R14, scheduled pull): what every pack's
+// `sync<Name>FromRemote` adapter receives. TYPES ONLY — the kernel defines the seam so
+// packs can adapt their vendor-specific executors to it; BUILDING one (origin +
+// sealed-credential egress) is the twins service's job, never a pack's.
+export type RemoteExecuteRequest = {
+  method: string;
+  path: string;
+  headers?: Record<string, string>;
+  /** A JSON text, or raw bytes (a multipart upload) — the host hands either to fetch as is. */
+  body?: string | Uint8Array;
+  /** Opt into exact bytes for object/attachment downloads; JSON clients keep body text. */
+  responseType?: 'bytes';
+  /** A URL the vendor itself returned for an upload, already carrying its own authorization
+   *  (LinkedIn's video parts on www.linkedin.com/dms-uploads, Slack's upload_url, TikTok's
+   *  upload.<region>.tiktokapis.com): `path` is then that absolute URL, often on another host than
+   *  the API, and the request goes WITHOUT the sealed credential. An upload the vendor authorizes
+   *  with the API token (LinkedIn's images) is not presigned and cannot use this. */
+  presigned?: true;
+};
+export type RemoteExecuteResponse = {
+  status: number;
+  headers: Record<string, string>;
+  body: string;
+  bodyBytes?: Uint8Array;
+};
+export type RemoteExecute = (request: RemoteExecuteRequest) => Promise<RemoteExecuteResponse>;

package/src/resource-blob.ts

@@ -0,0 +1,57 @@
+import { isAbsolute, join } from 'node:path';
+import { getActiveBlobStore, readBlobRange } from './blob-store.ts';
+import { readBranchMeta } from './log.ts';
+import { worldPaths } from './storage.ts';
+
+/** Read a resource payload at this branch, then its retained ancestors. */
+export async function readResourceBlob(service: string, key: string, root?: string): Promise<Uint8Array | null> {
+  assertResourceKey(key);
+  for (const dir of resourceChain(service, root)) {
+    const bytes = await getActiveBlobStore().get(join(dir, key));
+    if (bytes !== null) return bytes;
+  }
+  return null;
+}
+
+/** A service's resources dir at this branch, then at each retained ancestor's: where a read resolves a payload, and
+ *  what a listing that mints ids covers, so a branch serves bytes its parent received and never re-mints a parent's id. */
+export function resourceChain(service: string, root?: string): string[] {
+  const out: string[] = [];
+  const seen = new Set<string>();
+  let current = worldPaths(service, root).root;
+  for (;;) {
+    if (seen.has(current)) throw new Error('Cyclic resource blob ancestry');
+    seen.add(current);
+    out.push(worldPaths(service, current).resources);
+    const parent = readBranchMeta(service, current)?.parent;
+    if (!parent) return out;
+    current = parent.at;
+  }
+}
+
+function assertResourceKey(key: string): void {
+  if (isAbsolute(key) || key.includes('\0') || key.split(/[\\/]/).includes('..')) throw new Error('Invalid relative resource blob key');
+}
+
+/** The key's full path at the first of this branch and its retained ancestors that holds it. */
+async function resolveResourceBlob(service: string, key: string, root?: string): Promise<string | null> {
+  assertResourceKey(key);
+  for (const dir of resourceChain(service, root)) {
+    const path = join(dir, key);
+    if (await getActiveBlobStore().exists(path)) return path;
+  }
+  return null;
+}
+
+/** Size of a resource payload at this branch or its ancestors, or null. */
+export async function resourceBlobSize(service: string, key: string, root?: string): Promise<number | null> {
+  const path = await resolveResourceBlob(service, key, root);
+  return path === null ? null : getActiveBlobStore().size(path);
+}
+
+/** A byte range of a resource payload at this branch or its ancestors (a ranged read where the
+ *  store has one), or null when absent. */
+export async function readResourceBlobRange(service: string, key: string, start: number, endInclusive: number, root?: string): Promise<Uint8Array | null> {
+  const path = await resolveResourceBlob(service, key, root);
+  return path === null ? null : readBlobRange(path, start, endInclusive);
+}

package/src/scenario.ts

@@ -0,0 +1,479 @@
+// 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 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.
+
+/** 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. */
+export type ScenarioFeatures = Record<string, string | number | boolean | readonly string[]>;
+
+/** One matcher: does THIS request satisfy `condition`? Pure — no state, no IO. */
+export type ScenarioMatcher<Req> = (req: Req, condition: unknown) => boolean;
+
+/** The pack's declaration of its vocabulary — the ONLY vendor-specific surface. */
+export type PackScenarioAdapter<Req> = {
+  /** Vendor key, e.g. "anthropic" — used in errors and the manifest. */
+  vendor: string;
+  /** Extract the feature bag for miss records / stub teaching. Pure. */
+  features: (req: Req) => ScenarioFeatures;
+  /** 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. */
+  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
+   *  ("seed that through the vendor's API instead"). */
+  validateRespond?: (respond: unknown, handler: ScenarioHandler) => string | null;
+  /** 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" } }`. */
+  renderFault?: (fault: ScenarioStatusFault, req: Req) => { body: unknown; headers?: Record<string, string> };
+};
+
+/** THE FAULT VOCABULARY (runtime contract R15 — outage rehearsal as a world-level value). One
+ *  grammar every pack's engine honors, so a 429 or a hung request is authored the same way for
+ *  every vendor instead of improvised per realizer:
+ *    slow   — hold the answer `ms` before serving it (the response is whatever the handler's
+ *             `respond` or the twin's own path produces; timing is not content, R9 holds);
+ *    status — answer this HTTP status instead of serving: a 4xx/5xx the vendor's own envelope
+ *             (the pack's adapter renders it; a kernel envelope when it declares none), with
+ *             `Retry-After` when `retryAfterSeconds` is set;
+ *    drop   — never answer: the request hangs until the client's own timeout ends it (what an
+ *             outage looks like from the client; a TCP reset is not something a fetch can do),
+ *             released after `holdMs` (default 300 000) so a socket is not held forever. */
+export type ScenarioFault =
+  | { kind: "slow"; ms: number }
+  | { kind: "status"; status: number; retryAfterSeconds?: number; message?: string }
+  | { kind: "drop"; holdMs?: number };
+export type ScenarioStatusFault = Extract<ScenarioFault, { kind: "status" }>;
+/** What a `status` fault serves: the pack's rendered envelope, or the kernel's. */
+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>`. */
+  id?: string;
+  /** Conditions — ALL must hold. `{}` matches every request (an ordered catch-all). */
+  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). */
+  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}`. */
+  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[];
+};
+
+export type ScenarioMissRecord = { features: ScenarioFeatures; phase: string | undefined };
+
+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"]);
+
+/** 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 };
+}
+
+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, ... }`);
+  const h = raw as Record<string, unknown>;
+  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>)) {
+    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", ... }`);
+    const kinds = ["slow", "status", "drop"];
+    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"], 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" && !(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 === "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`);
+  }
+  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") throw new ScenarioError(`${vendor} scenario: ${where} applies |${op}:${rawN} to a non-numeric extractor value ${JSON.stringify(value)}`);
+  const n = Number(rawN);
+  return op === "min" ? Math.min(value, n) : Math.max(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. */
+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 }));
+    }
+  }
+
+  /** 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. */
+  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 (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 = 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)]));
+    }
+    return value;
+  }
+}
+
+/** 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. */
+function throwIfScenarioAborted(signal?: AbortSignal): void {
+  signal?.throwIfAborted();
+}
+
+function waitForScenarioFault(ms: number, signal?: AbortSignal): Promise<void> {
+  throwIfScenarioAborted(signal);
+  return new Promise<void>((resolve, reject) => {
+    const cleanup = () => signal?.removeEventListener('abort', onAbort);
+    const onAbort = () => {
+      clearTimeout(timer);
+      cleanup();
+      reject(signal?.reason);
+    };
+    const timer = setTimeout(() => { cleanup(); resolve(); }, ms);
+    signal?.addEventListener('abort', onAbort, { once: true });
+    if (signal?.aborted) onAbort();
+  });
+}
+
+export async function scenarioFaultResult(fault: ScenarioFault, render?: () => { body: unknown; headers?: Record<string, string> } | undefined, signal?: AbortSignal): Promise<ScenarioFaultResult | null> {
+  throwIfScenarioAborted(signal);
+  if (fault.kind === "slow") { await waitForScenarioFault(fault.ms, signal); throwIfScenarioAborted(signal); return null; }
+  if (fault.kind === "drop") {
+    await waitForScenarioFault(fault.holdMs ?? 300_000, signal);
+    throwIfScenarioAborted(signal);
+    throw new ScenarioError("scenario drop: the request was held unanswered for its hold and is now released without a response");
+  }
+  const rendered = render?.();
+  throwIfScenarioAborted(signal);
+  const headers: Record<string, string> = { ...(rendered?.headers ?? {}) };
+  if (fault.retryAfterSeconds !== undefined) headers["retry-after"] = String(fault.retryAfterSeconds);
+  return { status: fault.status, headers, body: rendered?.body ?? { error: { message: fault.message ?? `twin fault: ${fault.status}`, type: "twin_fault" } } };
+}
+
+export function statefulTwinManifest(input: { vendor: string; twinOf: string; stores: string; identity?: string; notes?: string }): Record<string, unknown> {
+  return {
+    twin: true,
+    vendor: input.vendor,
+    twinOf: input.twinOf,
+    program: {
+      state: `Stateful: it stores ${input.stores}. Create state through the vendor's OWN API with the real SDK or plain fetch pointed here — there is no fixture language and no write door besides the vendor's.`,
+      identity: input.identity ?? 'Authenticate as the vendor does; the twin accepts any non-sentinel credential.',
+      time: 'Writes are stamped from the WORLD CLOCK (volter-world clock <world> set/advance) — deterministic history is clock-set, seed, clock-advance.',
+      behavior: 'This twin is state, not scripting — answers are functions of what you seeded. Judgment/fault scripting lives on the scripted vendor twins (their GET /twin explains).',
+      ...(input.notes ? { notes: input.notes } : {}),
+    },
+    doors: { manifest: 'GET /twin' },
+  };
+}
+
+/** 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();
+  return {
+    twin: true,
+    vendor: input.vendor,
+    twinOf: input.twinOf,
+    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 } : {}),
+    },
+    doors: { manifest: "GET /twin", scenario: "GET /twin/scenario (read-only: active handlers + match/miss counts)" },
+    ...(status ? { activeHandlers: status.handlers.length, misses: status.misses } : {}),
+  };
+}