@volter/twin 0.1.0 → 0.1.1

package/src/refs.ts

@@ -4,9 +4,9 @@
 // ref records which remote ref a fork was based on, so a stale-base push can be
 // rejected before any provider call. Pure file I/O over the world dir; deterministic
 // (caller supplies observedAt).
-import { existsSync, mkdirSync, readdirSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { readJsonFile, worldPaths } from './storage.ts';
+import { getActiveWorldStore } from './world-store.ts';
 
 export type WorldRemoteRef = {
   service: string;
@@ -45,23 +45,23 @@ function safe(part: string): string {
 /** Record/advance a provider checkpoint (e.g. after a confirmed pull). */
 export function writeRemoteRef(ref: WorldRemoteRef, root?: string): WorldRemoteRef {
   const path = remoteRefPath(ref.service, safe(ref.provider), safe(ref.name), root);
-  mkdirSync(join(path, '..'), { recursive: true });
-  writeFileSync(path, `${JSON.stringify(ref, null, 2)}\n`);
+  getActiveWorldStore().write(path, `${JSON.stringify(ref, null, 2)}\n`);
   return ref;
 }
 
 export function readRemoteRef(service: string, provider: string, name = 'main', root?: string): WorldRemoteRef | null {
   const path = remoteRefPath(service, safe(provider), safe(name), root);
-  return existsSync(path) ? readJsonFile<WorldRemoteRef>(path) : null;
+  return getActiveWorldStore().exists(path) ? readJsonFile<WorldRemoteRef>(path) : null;
 }
 
 export function listRemoteRefs(service: string, root?: string): WorldRemoteRef[] {
+  const store = getActiveWorldStore();
   const base = join(refsDir(service, root), 'remote');
-  if (!existsSync(base)) return [];
+  if (!store.exists(base)) return [];
   const out: WorldRemoteRef[] = [];
-  for (const provider of readdirSync(base)) {
+  for (const provider of store.list(base)) {
     const providerDir = join(base, provider);
-    for (const file of readdirSync(providerDir)) {
+    for (const file of store.list(providerDir)) {
       if (file.endsWith('.json')) out.push(readJsonFile<WorldRemoteRef>(join(providerDir, file)));
     }
   }
@@ -70,14 +70,13 @@ export function listRemoteRefs(service: string, root?: string): WorldRemoteRef[]
 
 export function writeLocalRef(ref: WorldLocalRef, root?: string): WorldLocalRef {
   const path = localRefPath(ref.service, safe(ref.forkId), root);
-  mkdirSync(join(path, '..'), { recursive: true });
-  writeFileSync(path, `${JSON.stringify(ref, null, 2)}\n`);
+  getActiveWorldStore().write(path, `${JSON.stringify(ref, null, 2)}\n`);
   return ref;
 }
 
 export function readLocalRef(service: string, forkId: string, root?: string): WorldLocalRef | null {
   const path = localRefPath(service, safe(forkId), root);
-  return existsSync(path) ? readJsonFile<WorldLocalRef>(path) : null;
+  return getActiveWorldStore().exists(path) ? readJsonFile<WorldLocalRef>(path) : null;
 }
 
 /**

package/src/remote-execute.ts

@@ -0,0 +1,16 @@
+// 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>;
+  body?: string;
+};
+export type RemoteExecuteResponse = {
+  status: number;
+  headers: Record<string, string>;
+  body: string;
+};
+export type RemoteExecute = (request: RemoteExecuteRequest) => Promise<RemoteExecuteResponse>;

package/src/scenario.ts

@@ -0,0 +1,387 @@
+// 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;
+};
+
+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). */
+  respond: unknown;
+  /** 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 }
+  | { 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", "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 (!("respond" in h)) throw new ScenarioError(`${adapter.vendor} scenario: ${at}: \`respond\` is required`);
+  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 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 = adapter.validateRespond?.(h.respond, h as ScenarioHandler);
+  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: this.substitute(r.handler.respond, req), ruleId: r.id };
+      } 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 };
+  }
+
+  /** 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. */
+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 } : {}),
+  };
+}