@volter/world-core 2.0.0

package/dist/src/scenario.js

@@ -0,0 +1,425 @@
+// 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.
+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(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 };
+}
+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, ... }`);
+    const h = raw;
+    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)) {
+        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", ... }`);
+        const kinds = ["slow", "status", "drop"];
+        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"], 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" && !(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 === "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`);
+    }
+    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")
+        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);
+}
+const MISS_KEEP = 20;
+/** The engine: pure state machine over registered handlers. One instance per twin server. */
+export class ScenarioEngine {
+    adapter;
+    extractors;
+    baseline = [];
+    overrides = [];
+    scopes = new Map();
+    missCount = 0;
+    recentMisses = [];
+    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)); };
+    }
+    /** Decide one request. Mutates scope state (calls, once, phase) exactly like serving. */
+    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))
+                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.$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 = 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 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) {
+    signal?.throwIfAborted();
+}
+function waitForScenarioFault(ms, signal) {
+    throwIfScenarioAborted(signal);
+    return new Promise((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, render, signal) {
+    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 = { ...(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) {
+    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) {
+    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 } : {}),
+    };
+}

package/dist/src/schemas.d.ts

@@ -0,0 +1,78 @@
+import { z } from 'zod';
+export declare const WorldActorSchema: z.ZodObject<{
+    id: z.ZodOptional<z.ZodString>;
+    name: z.ZodOptional<z.ZodString>;
+    kind: z.ZodEnum<{
+        human: "human";
+        agent: "agent";
+        bot: "bot";
+        system: "system";
+    }>;
+}, z.core.$strip>;
+export declare const WorldSubjectSchema: z.ZodObject<{
+    type: z.ZodString;
+    id: z.ZodString;
+}, z.core.$strip>;
+export declare const WorldExternalRefSchema: z.ZodObject<{
+    provider: z.ZodString;
+    id: z.ZodOptional<z.ZodString>;
+    url: z.ZodOptional<z.ZodString>;
+    cursor: z.ZodOptional<z.ZodString>;
+    rawRef: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const WorldServiceEventSchema: z.ZodObject<{
+    id: z.ZodString;
+    service: z.ZodString;
+    type: z.ZodString;
+    schemaVersion: z.ZodNumber;
+    idempotencyKey: z.ZodString;
+    occurredAt: z.ZodString;
+    observedAt: z.ZodString;
+    origin: z.ZodEnum<{
+        agent: "agent";
+        virtual: "virtual";
+        external: "external";
+        connector: "connector";
+        replay: "replay";
+        migration: "migration";
+    }>;
+    actor: z.ZodOptional<z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
+        name: z.ZodOptional<z.ZodString>;
+        kind: z.ZodEnum<{
+            human: "human";
+            agent: "agent";
+            bot: "bot";
+            system: "system";
+        }>;
+    }, z.core.$strip>>;
+    subject: z.ZodObject<{
+        type: z.ZodString;
+        id: z.ZodString;
+    }, z.core.$strip>;
+    causationId: z.ZodOptional<z.ZodString>;
+    correlationId: z.ZodOptional<z.ZodString>;
+    external: z.ZodOptional<z.ZodObject<{
+        provider: z.ZodString;
+        id: z.ZodOptional<z.ZodString>;
+        url: z.ZodOptional<z.ZodString>;
+        cursor: z.ZodOptional<z.ZodString>;
+        rawRef: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    data: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    raw: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+export declare const GenericWorldStateSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    service: z.ZodString;
+    rebuiltAt: z.ZodString;
+    eventCount: z.ZodNumber;
+    latestEventId: z.ZodOptional<z.ZodString>;
+    subjects: z.ZodRecord<z.ZodString, z.ZodObject<{
+        type: z.ZodString;
+        id: z.ZodString;
+        latestEventId: z.ZodString;
+        latestType: z.ZodString;
+        updatedAt: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;

package/dist/src/schemas.js

@@ -0,0 +1,50 @@
+import { z } from 'zod';
+export const WorldActorSchema = z.object({
+    id: z.string().min(1).optional(),
+    name: z.string().min(1).optional(),
+    kind: z.enum(['human', 'agent', 'bot', 'system']),
+});
+export const WorldSubjectSchema = z.object({
+    type: z.string().min(1),
+    id: z.string().min(1),
+});
+export const WorldExternalRefSchema = z.object({
+    provider: z.string().min(1),
+    id: z.string().min(1).optional(),
+    url: z.string().min(1).optional(),
+    cursor: z.string().min(1).optional(),
+    rawRef: z.string().min(1).optional(),
+});
+export const WorldServiceEventSchema = z.object({
+    id: z.string().min(1),
+    service: z.string().min(1),
+    type: z.string().min(1),
+    schemaVersion: z.number().int().positive(),
+    idempotencyKey: z.string().min(1),
+    occurredAt: z.string().min(1),
+    observedAt: z.string().min(1),
+    origin: z.enum(['virtual', 'external', 'agent', 'connector', 'replay', 'migration']),
+    actor: WorldActorSchema.optional(),
+    subject: WorldSubjectSchema,
+    causationId: z.string().min(1).optional(),
+    correlationId: z.string().min(1).optional(),
+    external: WorldExternalRefSchema.optional(),
+    data: z.record(z.string(), z.unknown()),
+    raw: z.record(z.string(), z.unknown()).optional(),
+});
+// NOTE: WorldAnnotationSchema moved to @volter/tracker/world-annotations — annotating
+// world events as sources/noise is a tracker (verification) concern, not the twin's.
+export const GenericWorldStateSchema = z.object({
+    version: z.literal(1),
+    service: z.string().min(1),
+    rebuiltAt: z.string().min(1),
+    eventCount: z.number().int().nonnegative(),
+    latestEventId: z.string().min(1).optional(),
+    subjects: z.record(z.string(), z.object({
+        type: z.string().min(1),
+        id: z.string().min(1),
+        latestEventId: z.string().min(1),
+        latestType: z.string().min(1),
+        updatedAt: z.string().min(1),
+    })),
+});

package/dist/src/serve-http.d.ts

@@ -0,0 +1,48 @@
+export type HttpHandler = (request: Request) => Response | Promise<Response>;
+export type WebSocketPeer = {
+    send: (data: string | Uint8Array) => unknown;
+    close: (code?: number, reason?: string) => unknown;
+};
+export type WebSocketUpgrade = {
+    accepts: (request: Request) => boolean;
+    open: (peer: WebSocketPeer, request: Request) => void;
+    message: (peer: WebSocketPeer, data: string | Uint8Array) => void | Promise<void>;
+    close: (peer: WebSocketPeer) => void;
+};
+export type ServeHttpOptions = {
+    /** Multiplexing infrastructure fronts leave vendor journaling to the downstream twins. */
+    twinRequestJournal?: boolean;
+    /** Optional persistent transport, with the same callbacks on Node and Bun. */
+    upgrade?: WebSocketUpgrade;
+    tls?: {
+        key: string | Uint8Array;
+        cert: string | Uint8Array;
+    };
+    /** the interface to listen on: loopback unless a caller names another. A twin is reached by its
+     *  World over loopback; a front that is meant to be reached (a served world, a host) names its own. */
+    hostname?: string;
+    port?: number;
+    fetch: HttpHandler;
+    /** seconds a connection may idle (Bun honors it; Node's keep-alive timeout is set from it) */
+    idleTimeout?: number;
+    /** the largest request body accepted, in bytes (Bun's default is 128 MB; Node sets none) */
+    maxRequestBodySize?: number;
+    /** what a thrown handler answers with; absent, a 500 carrying the error (as Bun.serve) */
+    error?: (error: Error) => Response | Promise<Response>;
+};
+export type HttpServer = {
+    hostname: string;
+    port: number;
+    /** as Bun's: a URL, whose string form ends in `/` — packs build `${server.url}path` on that */
+    url: URL;
+    /** stop listening; `closeActive` (default true) drops in-flight connections as well */
+    stop: (closeActive?: boolean) => Promise<void>;
+};
+export declare function setServeDecorator(fn: ((options: ServeHttpOptions) => HttpHandler) | undefined): void;
+/** The path a World asks a service it booted, when that service's port answers, which boot it belongs to. */
+export declare const WORLD_BOOT_PATH = "/__volter/world-boot";
+export declare function serveHttp(options: ServeHttpOptions): Promise<HttpServer>;
+/** A Node builtin without a static import — `process.getBuiltinModule` (Node 22.3+, Bun): what a
+ *  module that also rides into a browser bundle reaches `node:crypto` with. A bare `require()`
+ *  is Bun's alone; Node's ESM has none (found 2026-09-07 by the pages running under node). */
+export declare function nodeBuiltin<T = unknown>(name: string): T;