@volter/world-core 3.0.166 → 3.0.167

package/dist/src/scenario-timeline.js

@@ -0,0 +1,242 @@
+// A SCENARIO is a timeline of inputs (ADR 0036; architecture, "Scenarios"): calls, people's actions, decisions, faults
+// and the clock, played at World times after the World's seed, its prefix. Nothing in it answers in a twin's place: a
+// twin consumes a decision where its vendor decides and a fault where it lands, and records both in its own log.
+//
+// This module is the grammar (a strict parse that names the vocabulary on every refusal), the resolution of a
+// document's times, and the twins' read of the scenario a World is playing: the instance's resolved document, read
+// through the World's store at every request as the clock is (TWIN_WORLD_SCENARIO_FILE), so a decision or a fault holds
+// from its `at` with no reboot.
+import { getActiveWorldStore } from "./world-store.js";
+import { worldNow } from "./world-clock.js";
+import { parseExactJson } from "./exact-json.js";
+export const WORLD_SCENARIO_ENV = 'TWIN_WORLD_SCENARIO_FILE';
+const FAULT_KINDS = {
+    request: ['rejected', 'failed', 'lost', 'slow', 'drop', 'generation'],
+    'over-time': ['webhook-delay', 'webhook-duplicate', 'webhook-drop', 'lag', 'rate-limit'],
+    network: ['reset', 'dns', 'tls', 'latency', 'loss', 'partition'],
+    infrastructure: ['oom', 'disk-full', 'crash', 'restart'],
+    time: ['jump'],
+};
+/** The layers asked of the machine the app runs on, through its fault door (ADR 0036 §4). */
+export const MACHINE_LAYERS = ['network', 'infrastructure'];
+export class ScenarioTimelineError extends Error {
+}
+const fail = (where, message) => { throw new ScenarioTimelineError(`scenario: ${where}: ${message}`); };
+const isObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+const onlyKeys = (value, keys, where) => {
+    for (const key of Object.keys(value))
+        if (key !== '$comment' && !keys.includes(key))
+            fail(where, `unknown key "${key}" (valid: ${keys.join(', ')})`);
+};
+const text = (value, where, name) => (typeof value === 'string' && value.length > 0 ? value : fail(where, `${name} is a non-empty string`));
+const instant = (value, where, name) => {
+    const at = text(value, where, name);
+    return Number.isNaN(Date.parse(at)) || !/^\d{4}-\d{2}-\d{2}T/.test(at) ? fail(where, `${name} is an ISO-8601 instant, got ${JSON.stringify(at)}`) : new Date(Date.parse(at)).toISOString();
+};
+/** `90s`, `5m`, `12h`, `30d` in milliseconds. */
+export function durationMs(by) {
+    const m = /^(\d+(?:\.\d+)?)(s|m|h|d)$/.exec(by.trim());
+    if (!m)
+        throw new ScenarioTimelineError(`${JSON.stringify(by)} is not <N>(s|m|h|d)`);
+    return Number(m[1]) * { s: 1_000, m: 60_000, h: 3_600_000, d: 86_400_000 }[m[2]];
+}
+const duration = (value, where, name) => {
+    const by = text(value, where, name);
+    try {
+        durationMs(by);
+    }
+    catch {
+        fail(where, `${name} is a duration (90s, 5m, 12h, 30d), got ${JSON.stringify(by)}`);
+    }
+    return by;
+};
+const positive = (value, where, name) => (Number.isInteger(value) && value > 0 ? value : fail(where, `${name} is a positive integer`));
+function parseCall(raw, where) {
+    if (!isObject(raw))
+        return fail(where, 'call is an object { method, url, headers?, body?, as? }');
+    onlyKeys(raw, ['method', 'url', 'headers', 'body', 'as'], `${where} call`);
+    const method = text(raw.method, where, 'call.method').toUpperCase();
+    const url = text(raw.url, where, 'call.url');
+    if (!/^https?:\/\//.test(url))
+        fail(where, 'call.url is the vendor\'s own absolute URL (https://...)');
+    if (raw.headers !== undefined && (!isObject(raw.headers) || Object.values(raw.headers).some((x) => typeof x !== 'string')))
+        fail(where, 'call.headers is an object of strings');
+    return { method, url, ...(raw.headers ? { headers: raw.headers } : {}), ...('body' in raw ? { body: raw.body } : {}), ...(raw.as !== undefined ? { as: text(raw.as, where, 'call.as') } : {}) };
+}
+function parseAction(raw, where) {
+    if (!isObject(raw))
+        return fail(where, 'action is an object { person, browser?, run }');
+    onlyKeys(raw, ['person', 'browser', 'run'], `${where} action`);
+    return { person: text(raw.person, where, 'action.person'), ...(raw.browser !== undefined ? { browser: text(raw.browser, where, 'action.browser') } : {}), run: text(raw.run, where, 'action.run') };
+}
+function parseDecision(raw, where) {
+    if (!isObject(raw))
+        return fail(where, 'decision is an object { vendor, point, subject?, on?, outcome, once? }');
+    onlyKeys(raw, ['vendor', 'point', 'subject', 'on', 'outcome', 'once'], `${where} decision`);
+    if (!('outcome' in raw))
+        fail(where, 'decision.outcome is required: what the vendor decided');
+    if (raw.on !== undefined && !isObject(raw.on))
+        fail(where, 'decision.on is an object of the pack\'s turn matchers');
+    if (raw.once !== undefined && typeof raw.once !== 'boolean')
+        fail(where, 'decision.once is boolean');
+    return { vendor: text(raw.vendor, where, 'decision.vendor'), point: text(raw.point, where, 'decision.point'), ...(raw.subject !== undefined ? { subject: text(raw.subject, where, 'decision.subject') } : {}), ...(raw.on !== undefined ? { on: raw.on } : {}), outcome: raw.outcome, ...(raw.once !== undefined ? { once: raw.once } : {}) };
+}
+const FAULT_KEYS = {
+    rejected: ['status', 'message', 'errorType', 'metadata', 'retryAfterSeconds'],
+    failed: ['status', 'message', 'errorType', 'metadata', 'retryAfterSeconds'],
+    lost: ['status', 'message', 'errorType'],
+    slow: ['ms'],
+    drop: ['ms'],
+    generation: ['status', 'message', 'errorType', 'metadata', 'partialText', 'event'],
+    'webhook-delay': ['event', 'by'],
+    'webhook-duplicate': ['event'],
+    'webhook-drop': ['event'],
+    lag: ['by'],
+    'rate-limit': ['limit', 'per', 'retryAfterSeconds', 'message'],
+    reset: ['target', 'to'], dns: ['target'], tls: ['target', 'to'], latency: ['target', 'ms'], loss: ['target', 'rate'], partition: ['between'],
+    oom: ['target'], 'disk-full': ['target', 'volume'], crash: ['target'], restart: ['target'],
+    jump: ['by'],
+};
+function parseFault(raw, where) {
+    if (!isObject(raw))
+        return fail(where, 'fault is an object { layer, kind, ... }');
+    const layer = raw.layer;
+    if (!(layer in FAULT_KINDS))
+        fail(where, `fault.layer is one of ${Object.keys(FAULT_KINDS).join(', ')}, got ${JSON.stringify(raw.layer)}`);
+    const kinds = FAULT_KINDS[layer];
+    if (!kinds.includes(raw.kind))
+        fail(where, `a ${layer} fault's kind is one of ${kinds.join(', ')}, got ${JSON.stringify(raw.kind)}`);
+    const kind = raw.kind;
+    const vendorLayer = layer === 'request' || layer === 'over-time';
+    const placement = vendorLayer ? ['vendor', 'times', 'until', ...(layer === 'request' ? ['operation', 'on', 'point', 'subject'] : ['operation'])] : ['times', 'until'];
+    onlyKeys(raw, ['layer', 'kind', ...placement, ...FAULT_KEYS[kind]], `${where} fault (${layer} ${kind})`);
+    if (vendorLayer)
+        text(raw.vendor, where, 'fault.vendor');
+    if (raw.operation !== undefined)
+        text(raw.operation, where, 'fault.operation');
+    if (raw.on !== undefined && !isObject(raw.on))
+        fail(where, 'fault.on is an object of the pack\'s turn matchers');
+    if ([raw.operation, raw.on, raw.point].filter((v) => v !== undefined).length > 1)
+        fail(where, 'a fault lands on one of operation, on (a model turn) or point');
+    if (raw.subject !== undefined && raw.point === undefined)
+        fail(where, 'fault.subject keys a fault at a pack\'s point; name the point');
+    if (raw.status !== undefined && !(Number.isInteger(raw.status) && raw.status >= 400 && raw.status <= 599))
+        fail(where, 'fault.status is an integer 400..599: a fault is a refusal or a failure, never a success');
+    if (kind === 'generation' && raw.on === undefined)
+        fail(where, 'a generation failure is a model turn\'s: name its `on`');
+    if (kind === 'lost' && raw.on !== undefined)
+        fail(where, 'a lost answer lands on an operation: name its `operation`');
+    if (kind === 'generation' && (typeof raw.message !== 'string' || typeof raw.errorType !== 'string' || !raw.errorType || raw.status === undefined))
+        fail(where, 'a generation fault names its status, message and nonempty errorType');
+    for (const name of ['message', 'errorType', 'partialText', 'event', 'target', 'to', 'volume'])
+        if (raw[name] !== undefined && typeof raw[name] !== 'string')
+            fail(where, `fault.${name} is a string`);
+    if (raw.metadata !== undefined && !isObject(raw.metadata))
+        fail(where, 'fault.metadata is an object');
+    if (raw.ms !== undefined && !(Number.isInteger(raw.ms) && raw.ms >= 0 && raw.ms <= 600_000))
+        fail(where, 'fault.ms is an integer 0..600000 (milliseconds)');
+    if (raw.retryAfterSeconds !== undefined && !(Number.isInteger(raw.retryAfterSeconds) && raw.retryAfterSeconds >= 0))
+        fail(where, 'fault.retryAfterSeconds is a non-negative integer');
+    for (const name of ['by', 'per'])
+        if (raw[name] !== undefined)
+            duration(raw[name], where, `fault.${name}`);
+    if (['webhook-delay', 'lag', 'jump'].includes(kind))
+        duration(raw.by, where, 'fault.by');
+    if (MACHINE_LAYERS.includes(layer) && kind !== 'partition' && raw.target === undefined)
+        fail(where, `a ${layer} fault names its target, the part of the app it lands on`);
+    if (kind === 'rate-limit') {
+        positive(raw.limit, where, 'fault.limit');
+        duration(raw.per, where, 'fault.per');
+    }
+    if (raw.rate !== undefined && !(typeof raw.rate === 'number' && raw.rate > 0 && raw.rate <= 1))
+        fail(where, 'fault.rate is a fraction in (0, 1]');
+    if (kind === 'partition' && !(Array.isArray(raw.between) && raw.between.length === 2 && raw.between.every((s) => typeof s === 'string' && s)))
+        fail(where, 'a partition names its two sides: between [a, b]');
+    if (raw.times !== undefined)
+        positive(raw.times, where, 'fault.times');
+    if (raw.until !== undefined)
+        instant(raw.until, where, 'fault.until');
+    return raw;
+}
+function parseClock(raw, where) {
+    if (!isObject(raw))
+        return fail(where, 'clock is { advance: <duration> } or { set: <instant> }');
+    onlyKeys(raw, ['advance', 'set'], `${where} clock`);
+    if (('advance' in raw) === ('set' in raw))
+        fail(where, 'clock is one of { advance } or { set }');
+    return 'advance' in raw ? { advance: duration(raw.advance, where, 'clock.advance') } : { set: instant(raw.set, where, 'clock.set') };
+}
+const ENTRY_KINDS = ['call', 'action', 'decision', 'fault', 'clock'];
+/** Strict parse of a scenario document: every refusal names where it is and the vocabulary it expected. */
+export function parseScenario(raw) {
+    if (!isObject(raw))
+        return fail('document', 'a scenario is an object { start, random?, timeline, properties? }');
+    onlyKeys(raw, ['start', 'random', 'timeline', 'properties'], 'document');
+    const start = instant(raw.start, 'document', 'start');
+    if (!Array.isArray(raw.timeline))
+        fail('document', 'timeline is an array of entries');
+    const timeline = raw.timeline.map((entry, i) => {
+        const where = `entry ${i + 1}`;
+        if (!isObject(entry))
+            return fail(where, `an entry is { at, ${ENTRY_KINDS.join(' | ')} }`);
+        onlyKeys(entry, ['at', ...ENTRY_KINDS], where);
+        const kinds = ENTRY_KINDS.filter((k) => k in entry);
+        if (kinds.length !== 1)
+            fail(where, `an entry is exactly one of ${ENTRY_KINDS.join(', ')}`);
+        const at = text(entry.at, where, 'at');
+        if (Number.isNaN(Date.parse(at)))
+            duration(at, where, 'at');
+        const kind = kinds[0];
+        const parsed = kind === 'call' ? parseCall(entry.call, where) : kind === 'action' ? parseAction(entry.action, where) : kind === 'decision' ? parseDecision(entry.decision, where) : kind === 'fault' ? parseFault(entry.fault, where) : parseClock(entry.clock, where);
+        return { at, [kind]: parsed };
+    });
+    return { start, ...(raw.random !== undefined ? { random: text(raw.random, 'document', 'random') } : {}), timeline, ...(raw.properties !== undefined ? { properties: text(raw.properties, 'document', 'properties') } : {}) };
+}
+/** Every `at` an instant: an instant as written, a duration after `start`. An entry before the one ahead of it, or before
+ *  `start`, is refused: the clock moves only forward through a timeline. */
+export function resolveScenario(name, doc) {
+    const start = Date.parse(doc.start);
+    let last = start;
+    const timeline = doc.timeline.map((entry, i) => {
+        const at = Number.isNaN(Date.parse(entry.at)) || !/^\d{4}-/.test(entry.at) ? start + durationMs(entry.at) : Date.parse(entry.at);
+        if (at < last)
+            fail(`entry ${i + 1}`, `at ${new Date(at).toISOString()} is before the entry ahead of it (${new Date(last).toISOString()}); a timeline runs forward`);
+        last = at;
+        return { ...entry, at: new Date(at).toISOString(), index: i + 1 };
+    });
+    return { name, start: doc.start, random: doc.random ?? name, timeline, ...(doc.properties !== undefined ? { properties: doc.properties } : {}) };
+}
+const kept = new Map();
+/** A JSON file of the World named by an env variable (its scenario, its facts), read through the World's store at each
+ *  call as the clock is, and parsed again only when it changed; null where the variable or the file is absent. */
+export function worldJsonFile(env) {
+    const file = process.env[env];
+    if (!file)
+        return null;
+    const store = getActiveWorldStore();
+    const raw = store.readKept ? store.readKept(file) : store.read(file);
+    if (raw === null)
+        return null;
+    const held = kept.get(env);
+    if (held?.raw === raw)
+        return held.value;
+    const value = parseExactJson(raw);
+    kept.set(env, { raw, value });
+    return value;
+}
+/** The scenario this World is playing (the instance's resolved document), or null when it plays none. */
+function activeScenario() {
+    return worldJsonFile(WORLD_SCENARIO_ENV);
+}
+/** The decisions and vendor faults the World's scenario places on one vendor, in timeline order. */
+export function placedOn(vendor) {
+    return (activeScenario()?.timeline ?? []).filter((e) => ('decision' in e && e.decision.vendor === vendor) || ('fault' in e && e.fault.vendor === vendor));
+}
+/** The decisions placed for a vendor's point at or before the World's now, in timeline order. */
+export function placedDecisions(vendor, point, now = worldNow()) {
+    return placedOn(vendor).flatMap((e) => ('decision' in e && e.decision.point === point && e.at <= now ? [{ ...e.decision, index: e.index, at: e.at }] : []));
+}
+/** The vendor faults placed on a vendor at or before the World's now and not past their `until`, in timeline order. */
+export function placedFaults(vendor, layer, now = worldNow()) {
+    return placedOn(vendor).flatMap((e) => ('fault' in e && e.fault.layer === layer && e.at <= now && (e.fault.until === undefined || now < new Date(Date.parse(e.fault.until)).toISOString()) ? [{ ...e.fault, index: e.index, at: e.at }] : []));
+}

package/dist/src/scenario.d.ts

@@ -12,8 +12,8 @@ export type PackScenarioAdapter<Req> = {
     /** The legal `on` keys and their per-request semantics. Pure. */
     matchers: Record<string, ScenarioMatcher<Req>>;
     /** Validate `on` CONDITION VALUES at load (key membership is the kernel's; VALUE typing is
-     *  the pack's — "a string nthCall silently never matches" is exactly the misfire strict
-     *  loading exists to prevent). Return an error string to refuse. */
+     *  the pack's — a mistyped value silently never matching is the misfire strict loading exists
+     *  to prevent). Return an error string to refuse. */
     validateOn?: (on: Record<string, unknown>) => string | null;
     /** Validate a handler's `respond` payload at load; return an error string to refuse.
      *  This is ALSO where a pack refuses success-shaped handlers on stateful routes
@@ -22,22 +22,10 @@ export type PackScenarioAdapter<Req> = {
     /** Whether the request admits a handler's answer (OpenAI's `tool_choice: 'none'` admits no tool call): a handler whose
      *  answer it does not admit is passed over, and the next that matches answers, else the stub. Absent, every answer. */
     admits?: (req: Req, respond: unknown) => boolean;
-    /** The request's text corpus for `textPattern` extractors (packs with text requests). */
-    text?: (req: Req) => string;
-    /** Pack-defined extractor KINDS beyond the builtins (feature, textPattern). A pack kind with
-     *  a builtin's name OVERRIDES the builtin (e.g. a richer textPattern with flags/group).
-     *  validate returns an error string to refuse the spec at load; extract runs at serve time
-     *  and throws ScenarioError when the request cannot supply the value. */
-    extractorKinds?: Record<string, {
-        validate: (spec: Record<string, unknown>, name: string) => string | null;
-        extract: (spec: Record<string, unknown>, req: Req, name: string) => string | number;
-    }>;
-    /** The per-session scope discriminator; omitted → all requests share one "world" scope. */
-    scopeKey?: (req: Req) => string;
-    /** The VENDOR'S error envelope for a `status` fault — a 429 from this vendor looks like this
-     *  vendor's 429. Omitted → the kernel's envelope `{ error: { message, type: "twin_fault" } }`. */
     /** Opt-in scope check for post-admission model generation failures; absent rejects them. */
     validateGenerationFault?: (fault: ScenarioGenerationFault, handler: ScenarioHandler) => string | null;
+    /** The VENDOR'S error envelope for a `status` fault — a 429 from this vendor looks like this
+     *  vendor's 429. Omitted → the kernel's envelope `{ error: { message, type: "twin_fault" } }`. */
     renderFault?: (fault: ScenarioStatusFault, req: Req) => {
         body: unknown;
         headers?: Record<string, string>;
@@ -90,49 +78,21 @@ export type ScenarioFaultResult = {
     body: unknown;
 };
 export type ScenarioHandler = {
-    /** Stable id for status/telemetry; defaults to `handler-<1-based index>`. */
+    /** The rule's id: `entry-<n>`, the timeline entry it came from. */
     id?: string;
-    /** Conditions — ALL must hold. `{}` matches every request (an ordered catch-all). */
+    /** Conditions — ALL must hold. `{}` matches every request. */
     on: Record<string, unknown>;
-    /** Pack-realized response content (the pack's realizer builds the faithful envelope).
-     *  Optional only on a handler that carries a `fault` (a `slow` may still carry one; a
-     *  `status` or `drop` serves no content, so it must not). */
+    /** The turn's answer, which the pack realizes into the vendor's envelope; absent on a fault. */
     respond?: unknown;
-    /** A fault to inject when this handler fires (ScenarioFault). Same once/phase/scope
-     *  semantics as any handler — a mid-story outage is `{on, fault, once}` or `{phase}`. */
+    /** The fault that answers the turn instead (ScenarioFault). */
     fault?: ScenarioFault;
-    /** Fire at most once per scope. */
-    once?: boolean;
-    /** Reserved: "world" (default) | "session" — with "session", once/phase state is per
-     *  scopeKey instead of shared. */
-    scope?: "world" | "session";
-    /** Fires only while the scope's phase equals this. Handlers without `phase` fire in any. */
-    phase?: string;
-    /** On fire, move the scope's phase — the tiny sequencing primitive that replaces
-     *  linear scripts and nthCall arithmetic. */
-    advancePhase?: string;
 };
-/** Request-derived values a `respond` payload may reference as "{{name}}" placeholders —
- *  builtin kinds, or any kind the pack's adapter declares. Payload placeholders support the
- *  numeric transforms `{{name|min:N}}` / `{{name|max:N}}`; a whole-string placeholder yields
- *  the TYPED value (numbers stay numbers). */
-export type ScenarioExtractorSpec = {
-    kind: "feature";
-    feature: string;
-} | {
-    kind: "textPattern";
-    pattern: string;
-    as?: "string" | "number";
-} | ({
-    kind: string;
-} & Record<string, unknown>);
+/** The ordered rules of one turn. */
 export type ScenarioDocument = {
-    extractors?: Record<string, ScenarioExtractorSpec>;
     handlers: ScenarioHandler[];
 };
 export type ScenarioMissRecord = {
     features: ScenarioFeatures;
-    phase: string | undefined;
 };
 export type ScenarioDecision = {
     kind: "handler";
@@ -144,54 +104,17 @@ export type ScenarioDecision = {
     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 declare class ScenarioError extends Error {
 }
-/** 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 declare function parseScenarioDocument<Req>(raw: unknown, adapter: PackScenarioAdapter<Req>): ScenarioDocument;
-/** The engine: pure state machine over registered handlers. One instance per twin server. */
+/** Strict-loud parse of a turn's rules. Every refusal names the valid vocabulary. */
+export declare function parseScenarioDocument<Req>(raw: ScenarioDocument, adapter: PackScenarioAdapter<Req>): ScenarioDocument;
+/** The engine over one turn's rules: pure, the same rules and request giving the same decision. */
 export declare class ScenarioEngine<Req> {
     private readonly adapter;
-    private readonly extractors;
-    private baseline;
-    private overrides;
-    private scopes;
-    private missCount;
-    private recentMisses;
-    constructor(adapter: PackScenarioAdapter<Req>, document?: ScenarioDocument);
-    /** In-process test overrides: LIFO over the baseline; returns a remover. NOT a runtime
-     *  door — nothing outside this process can reach it, by design. */
-    use(...handlers: ScenarioHandler[]): () => void;
-    /** Decide one request. Mutates scope state (calls, once, phase) exactly like serving. */
+    private readonly document;
+    constructor(adapter: PackScenarioAdapter<Req>, document: ScenarioDocument);
+    /** Decide one request: the first rule that matches and whose answer the request admits, else the miss. */
     next(req: Req): ScenarioDecision;
-    /** 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. */
-    serve(req: Req, signal?: AbortSignal): Promise<ScenarioDecision | {
-        kind: "fault";
-        result: ScenarioFaultResult;
-        ruleId: string;
-    }>;
-    /** For GET /twin/scenario — active handlers with match counts, and the recent misses. */
-    status(): ScenarioStatus;
-    private scope;
-    private matches;
-    private extractValue;
-    private substitute;
 }
 export declare function scenarioFaultResult(fault: ScenarioFault, render?: () => {
     body: unknown;
@@ -218,5 +141,4 @@ export declare function twinManifest(input: {
     stateSentence: string;
     behaviorSentence: string;
     exampleHandler: ScenarioHandler | null;
-    engine?: ScenarioEngine<never>;
 }): Record<string, unknown>;