@volter/world-core 3.0.165 → 3.0.167

package/dist/src/scenario.js

@@ -1,355 +1,68 @@
-import { exactInteger, compareExactNumbers, isExactIntegerValue } from "./exact-json.js";
+// 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.
+//
+// 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.
 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. */
+const HANDLER_KEYS = new Set(["id", "on", "respond", "fault"]);
+/** Strict-loud parse of a turn's rules. Every refusal names the valid vocabulary. */
 export function parseScenarioDocument(raw, adapter) {
-    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;
-    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 = {};
-    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)) {
-            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.map((h, i) => parseHandler(h, i, adapter, extractors));
-    return { ...(doc.extractors !== undefined ? { extractors } : {}), handlers };
+    return { handlers: raw.handlers.map((h, i) => parseHandler(h, i, adapter)) };
 }
-function parseExtractor(name, raw, adapter) {
-    if (typeof raw !== "object" || raw === null)
-        throw new ScenarioError(`${adapter.vendor} scenario: extractor "${name}" is an object`);
-    const spec = raw;
-    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;
-    }
-    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 } : {}) };
-    }
-    throw new ScenarioError(`${adapter.vendor} scenario: extractor "${name}": kind is one of ${[...new Set(["feature", "textPattern", ...Object.keys(adapter.extractorKinds ?? {})])].join(", ")}`);
-}
-function parseHandler(raw, index, adapter, extractors) {
-    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(raw, index, adapter) {
     const h = raw;
+    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)) {
+    const validOn = Object.keys(adapter.matchers);
+    for (const key of Object.keys(h.on)) {
         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 < 1))
-            throw new ScenarioError(`${adapter.vendor} scenario: ${at}: nthCall is a positive integer`);
     }
     const onRefusal = adapter.validateOn?.(h.on);
     if (onRefusal)
         throw new ScenarioError(`${adapter.vendor} scenario: ${at}: ${onRefusal}`);
-    if (h.fault !== undefined) {
-        const f = h.fault;
-        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))
-            throw new ScenarioError(`${adapter.vendor} scenario: ${at}: fault.kind is one of ${kinds.join(", ")}, got ${JSON.stringify(f.kind)}`);
-        const keysFor = { 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].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].join(", ")})`);
-        if (f.kind === "slow" && !(Number.isInteger(f.ms) && f.ms >= 0 && f.ms <= 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 >= 400 && f.status <= 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 >= 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, h);
-            if (refusal)
-                throw new ScenarioError(`${adapter.vendor} scenario: ${at}: ${refusal}`);
-        }
-        if (f.kind === "drop" && f.holdMs !== undefined && !(Number.isInteger(f.holdMs) && f.holdMs >= 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"]) {
-        if (h[key] !== undefined && (typeof h[key] !== "string" || h[key].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.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, h);
+        if (refusal)
+            throw new ScenarioError(`${adapter.vendor} scenario: ${at}: ${refusal}`);
     }
     const refusal = "respond" in h ? adapter.validateRespond?.(h.respond, h) : null;
     if (refusal)
         throw new ScenarioError(`${adapter.vendor} scenario: ${at}: ${refusal}`);
     return h;
 }
-const PLACEHOLDER_SRC = "\\{\\{([a-zA-Z0-9_.-]+)(\\|(?:min|max):-?[\\d.]+)?\\}\\}";
-function placeholderNames(value, out = new Set()) {
-    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(adapter, kind) {
-    return adapter.extractorKinds?.[kind];
-}
-/** `{{name|min:N}}` / `{{name|max:N}}` — numeric clamps on an extracted value. */
-function applyTransform(value, transform, vendor, where) {
-    if (!transform)
-        return value;
-    const [op, rawN] = transform.slice(1).split(":");
-    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);
-}
-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 {
     adapter;
-    extractors;
-    baseline = [];
-    overrides = [];
-    scopes = new Map();
-    missCount = 0;
-    recentMisses = [];
+    document;
     constructor(adapter, document) {
         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) {
-        const parsed = handlers.map((h, i) => parseHandler(h, i, this.adapter, this.extractors));
-        const 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)); };
+        this.document = document;
     }
-    /** 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) {
-        const scopeOf = (h) => (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))
+        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 (!this.matches(r.handler, req, scope))
+            if ("respond" in handler && this.adapter.admits && !this.adapter.admits(req, handler.respond))
                 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.$comment === "string" ? `: ${String(r.handler.$comment).slice(0, 80)}` : ""}]`);
-                throw e;
-            }
-        }
-        const miss = { 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, signal) {
-        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, 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() {
-        const row = (r) => ({ 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] };
-    }
-    scope(key) {
-        let s = this.scopes.get(key);
-        if (!s) {
-            s = { calls: 0, phase: undefined, onceFired: new Set() };
-            this.scopes.set(key, s);
-        }
-        return s;
-    }
-    matches(handler, req, scope) {
-        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;
-    }
-    extractValue(name, req, cache) {
-        const cached = cache.get(name);
-        if (cached !== undefined)
-            return cached;
-        const spec = this.extractors[name];
-        const packKind = adapterKind(this.adapter, spec.kind);
-        let value;
-        if (packKind !== undefined) {
-            value = packKind.extract(spec, req, name);
-        }
-        else if (spec.kind === "feature") {
-            const v = this.adapter.features(req)[spec.feature];
-            if (v === undefined)
-                throw new ScenarioError(`${this.adapter.vendor} scenario: placeholder "{{${name}}}": the request has no feature "${spec.feature}"`);
-            value = typeof v === "number" || typeof v === "string" ? v : String(v);
-        }
-        else {
-            const text = this.adapter.text(req);
-            const tp = spec;
-            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;
-    }
-    substitute(value, req, cache = new Map()) {
-        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, transform) => 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 { 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. */
@@ -414,7 +127,6 @@ export function statefulTwinManifest(input) {
 /** 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) {
-    const status = input.engine?.status();
     return {
         twin: true,
         vendor: input.vendor,
@@ -422,10 +134,9 @@ export function twinManifest(input) {
         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/dist/src/sockets.d.ts

@@ -1,5 +1,5 @@
 import type { EventWrite } from './events.js';
-import type { ScenarioEngine } from './scenario.js';
+import type { ScenarioDecision, ScenarioFaultResult } from './scenario.js';
 import type { WebSocketUpgrade } from './serve-http.js';
 /** A socket the vendor serves: its path (and host, when the vendor serves it on a host of its own), as the manifest
  *  declares it. */
@@ -30,8 +30,12 @@ export type SocketSession = {
      *  scenario or the World carries none. A fault decision is the engine's to answer in its own frames. */
     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> = {
     open?(session: SocketSession, ctx: C): void | Promise<void>;
@@ -51,4 +55,4 @@ export declare function expireSocketWaits(service: string, root: string | undefi
  *  awaited: the write may be one a session's own frame made, which that session finishes before it is told. */
 export declare function socketWrite(service: string, root: string | undefined, write: EventWrite): void;
 /** The upgrade the serve seam takes: a request to a declared socket's path (and host) opens a session of its engine. */
-export declare function socketUpgrade<C>(service: string, root: string | undefined, decls: ReadonlyArray<SocketDecl>, engines: Record<string, SocketEngine<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>): WebSocketUpgrade;
+export declare function socketUpgrade<C>(service: string, root: string | undefined, decls: ReadonlyArray<SocketDecl>, engines: Record<string, SocketEngine<C>>, context: (request: Request, decl: SocketDecl, params: Record<string, string>) => Promise<C>, hostOf: (request: Request) => string, pathOf: (request: Request) => string, decide: (asked: unknown, context: () => Promise<C>) => Promise<ScenarioServed | undefined>): WebSocketUpgrade;

package/dist/src/sockets.js

@@ -114,7 +114,7 @@ export function socketUpgrade(service, root, decls, engines, context, hostOf, pa
                     p.resolve(value);
                     return true;
                 },
-                decide,
+                decide: (asked) => decide(asked, () => o.context()),
             };
             const tenant = storageTenant(service), run = (fn) => runWithStorageTenant(service, tenant, fn);
             const o = { tenant, run, session, engine, context: () => context(request.clone(), decl, params), queue: Promise.resolve(), pending };

package/dist/src/world-clock.d.ts

@@ -2,3 +2,6 @@ export declare const WORLD_CLOCK_ENV = "TWIN_WORLD_CLOCK_FILE";
 /** 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 declare function worldNow(): string;
+/** 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 declare function worldClockRunning(): boolean;

package/dist/src/world-clock.js

@@ -22,16 +22,21 @@ const machineNow = () => {
 /** 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() {
+    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() {
     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() {
+    return heldClock()?.kind !== 'frozen';
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/world-core",
-  "version": "3.0.165",
+  "version": "3.0.167",
   "description": "The kernel of Volter World: one log per twin, branches as pointers, checkpoints, the fold that keeps a twin current, the head that performs a write against the vendor, references, and the git plane. A twin package builds on it; the runtime serves it.",
   "keywords": [
     "twin",
@@ -88,6 +88,10 @@
       "types": "./dist/src/exact-json.d.ts",
       "default": "./dist/src/exact-json.js"
     },
+    "./checkout": {
+      "types": "./dist/src/checkout.d.ts",
+      "default": "./dist/src/checkout.js"
+    },
     "./inject": "./inject.cjs",
     "./attach": "./attach.cjs",
     "./stream-bridge": "./stream-bridge.cjs",

package/src/changeset.ts

@@ -1,7 +1,7 @@
 import { parseExactJson } from './exact-json.ts';
 import { resolveReferences } from './references.ts';
 import { withHistoryLocks } from './ancestry.ts';
-import { captureParentHistory, historyChanges, historyEntries, historyPrefix, readHistoryView, type HistoryReference } from './history.ts';
+import { captureHistory, captureParentHistory, historyChanges, historyEntries, historyPrefix, readHistoryView, type HistoryReference } from './history.ts';
 import { worldPaths } from './storage.ts';
 // The changeset primitive — "commit" for operational reality (docs/concepts/the-model.md, v0).
 //
@@ -88,6 +88,9 @@ export type LedgerPosition = {
   stateService: string;
   count: number;
   lastActionId: string | null;
+  /** the twin's history view and its position in it: what a branch at this mark starts from (ADR 0036 §5) */
+  view?: string;
+  position?: number;
 };
 
 export const MARKER_KIND = 'volter.world.marker.v1';
@@ -102,6 +105,10 @@ export type WorldMarker = {
   /** Every ledger that existed at capture time. A ledger absent here is treated as position 0
    *  (a twin that recorded its first action AFTER the mark contributes its whole ledger). */
   ledgers: LedgerPosition[];
+  /** the World clock's instant at the mark, or null when it ran on the machine's time (a run's position, ADR 0036 §5) */
+  clock?: string | null;
+  /** whether the machine's fault door took the app's disk with the mark */
+  disk?: boolean;
 };
 
 /** The id reserved for the synthetic "everything this world has ever recorded" base. */
@@ -253,17 +260,20 @@ export function worldBootMarker(world: string, createdAt: string): WorldMarker {
 }
 
 /** Capture the current position of every ledger — the cross-service base marker. */
-export function captureMarker(opts: { id: string; world: string; ledgers: LedgerRef[]; createdAt?: string }): WorldMarker {
+export function captureMarker(opts: { id: string; world: string; ledgers: LedgerRef[]; createdAt?: string; clock?: string | null; disk?: boolean }): WorldMarker {
   const ledgers = opts.ledgers.map((ledger) => {
     const rows = listActions(ledger.stateService, ledger.controlRoot);
+    const { view, position } = captureHistory(ledger.stateService, ledger.controlRoot);
     return {
       service: ledger.service,
       stateService: ledger.stateService,
       count: rows.length,
       lastActionId: rows.length ? rows[rows.length - 1]!.id : null,
+      view,
+      position,
     } satisfies LedgerPosition;
   });
-  return { kind: MARKER_KIND, id: opts.id, world: opts.world, createdAt: opts.createdAt ?? new Date().toISOString(), ledgers };
+  return { kind: MARKER_KIND, id: opts.id, world: opts.world, createdAt: opts.createdAt ?? new Date().toISOString(), ledgers, ...(opts.clock !== undefined ? { clock: opts.clock } : {}), ...(opts.disk ? { disk: true } : {}) };
 }
 
 function positionKey(service: string, stateService: string): string {

package/src/checkout.ts

@@ -0,0 +1,12 @@
+import { existsSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+
+/** The checkout a directory is in: the nearest ancestor of the path as given that holds `.git` (a directory, or a
+ *  worktree's file), or undefined outside every checkout. It walks the spelling it is handed; a caller whose base may
+ *  be a symlink passes its physical path. What a checkout tracks, and what a failed Git query means, is each caller's. */
+export function checkoutOf(dir: string): string | undefined {
+  for (let d = resolve(dir); ; d = dirname(d)) {
+    if (existsSync(join(d, '.git'))) return d;
+    if (dirname(d) === d) return undefined;
+  }
+}

package/src/completeness.ts

@@ -0,0 +1,57 @@
+// A run's completeness (ADR 0036 §9; architecture, "Scenarios"): the World is the application's internet closure, so
+// what reached past it is what the World is missing. The relay notes every destination no twin serves (refused, or
+// passed to the real internet where the World lets it), a twin every request to an operation it does not implement
+// (answered as the vendor answers an unknown request), and a run every machine fault no fault door carried. All are
+// appended, at World time, to the instance's completeness file (TWIN_WORLD_COMPLETENESS_FILE), and a run counts them.
+import { getActiveWorldStore } from './world-store.ts';
+import clockForm from '../world-clock.cjs';
+
+const WORLD_COMPLETENESS_ENV = 'TWIN_WORLD_COMPLETENESS_FILE';
+
+/** What a relay or a twin notes; the World's time is added as it is appended. */
+type CompletenessNote =
+  | { kind: 'egress'; destination: string; outcome: 'refused' | 'passed'; rule?: string }
+  | { kind: 'unimplemented'; vendor: string; method: string; path: string; operation?: string }
+  | { kind: 'machine'; layer: string; fault: string; target?: string };
+type CompletenessRecord = CompletenessNote & { at: string };
+
+/** The World's time in `env` (its clock file's, else the machine's). */
+function worldTimeIn(env: Record<string, string | undefined>): string {
+  const file = env.TWIN_WORLD_CLOCK_FILE;
+  const held = file ? getActiveWorldStore().read(file) : null;
+  return new Date(held ? clockForm.clockNowMs(clockForm.parseClock(held), Date.now()) : Date.now()).toISOString();
+}
+
+/** Append one record to the World's completeness file named in `env`; a process outside a World notes nothing. */
+export function noteCompleteness(env: Record<string, string | undefined>, record: CompletenessNote): void {
+  const file = env[WORLD_COMPLETENESS_ENV];
+  if (!file) return;
+  try { getActiveWorldStore().append(file, `${JSON.stringify({ at: worldTimeIn(env), ...record })}\n`); } catch { /* the answer still goes out */ }
+}
+
+export type Completeness = {
+  /** zero when the World was the whole internet the run reached */
+  total: number;
+  egress: Record<string, { refused: number; passed: number }>;
+  unimplemented: Record<string, Record<string, number>>;
+  /** machine faults the run placed and no fault door carried, by layer and kind (ADR 0036 §4) */
+  machine: Record<string, number>;
+};
+
+/** How many records the completeness file holds: where a run starts counting. */
+export function completenessMark(file: string): number {
+  return (getActiveWorldStore().read(file) ?? '').split('\n').filter((line) => line.trim()).length;
+}
+
+/** What reached past the World after the file's `mark`, counted per destination and per vendor's operation. */
+export function completenessSince(file: string, mark: number): Completeness {
+  const out: Completeness = { total: 0, egress: {}, unimplemented: {}, machine: {} };
+  for (const line of (getActiveWorldStore().read(file) ?? '').split('\n').filter((l) => l.trim()).slice(mark)) {
+    const r = JSON.parse(line) as CompletenessRecord;
+    out.total += 1;
+    if (r.kind === 'egress') (out.egress[r.destination] ??= { refused: 0, passed: 0 })[r.outcome] += 1;
+    else if (r.kind === 'machine') out.machine[`${r.layer} ${r.fault}`] = (out.machine[`${r.layer} ${r.fault}`] ?? 0) + 1;
+    else { const ops = out.unimplemented[r.vendor] ??= {}; const key = r.operation ?? `${r.method} ${r.path}`; ops[key] = (ops[key] ?? 0) + 1; }
+  }
+  return out;
+}