@volter/world-core 3.0.165 → 3.0.167

package/src/scenario-serve.ts

@@ -0,0 +1,47 @@
+// A model vendor's turn and a request's fault, as the World's scenario places them (architecture, "Scenarios"). The
+// placed turns are matched with the pack's own matchers (its `semantics/scenario.ts` adapter, through the kernel's
+// grammar in scenario.ts), in timeline order; what answered, the labelled default or the fault that landed is recorded
+// in the twin's log (scenario-consume.ts).
+import { parseScenarioDocument, ScenarioEngine, scenarioFaultResult, type PackScenarioAdapter, type ScenarioFault, type ScenarioHandler, type ScenarioStatusFault } from './scenario.ts';
+import { recordFault, recordTurn, requestFaults, turnDecisions, type ScenarioLedger } from './scenario-consume.ts';
+import type { PlacedFault } from './scenario-timeline.ts';
+import type { ScenarioServed } from './sockets.ts';
+
+/** A request fault as the kernel's fault grammar answers it: `rejected` at the edge (503 unless named), `failed` and
+ *  `lost` as the vendor's server failure (500 unless named). */
+export function kernelFault(fault: PlacedFault): ScenarioFault {
+  if (fault.kind === 'slow') return { kind: 'slow', ms: fault.ms ?? 0 };
+  if (fault.kind === 'drop') return { kind: 'drop', ...(fault.ms !== undefined ? { holdMs: fault.ms } : {}) };
+  if (fault.kind === 'generation') return { kind: 'generation', status: fault.status!, message: fault.message!, errorType: fault.errorType!, ...(fault.metadata ? { metadata: fault.metadata } : {}), ...(fault.partialText !== undefined ? { partialText: fault.partialText } : {}), ...(fault.event !== undefined ? { event: fault.event } : {}) };
+  const status = fault.status ?? (fault.kind === 'rejected' ? 503 : fault.kind === 'rate-limit' ? 429 : 500);
+  return { kind: 'status', status, ...(fault.retryAfterSeconds !== undefined ? { retryAfterSeconds: fault.retryAfterSeconds } : {}), message: fault.message ?? `${fault.kind}: the World's scenario placed this fault (entry ${fault.index})`, ...(fault.errorType ? { errorType: fault.errorType } : {}), ...(fault.metadata ? { metadata: fault.metadata } : {}) };
+}
+
+/** A model vendor's turn: a placed fault whose `on` the request satisfies lands first (a `slow` one holds the turn, then
+ *  it is decided); then the first placed turn decision whose `on` it satisfies and whose answer it admits, else the
+ *  miss, the pack's labelled stub. What landed and what decided are recorded either way. */
+export async function serveTurn<Req>(asked: Req, ledger: ScenarioLedger, adapter: PackScenarioAdapter<Req>, signal?: AbortSignal): Promise<ScenarioServed> {
+  const engineOf = (handlers: ScenarioHandler[]) => new ScenarioEngine(adapter, parseScenarioDocument({ handlers }, adapter));
+  const faults = requestFaults(ledger).filter((f) => f.on !== undefined);
+  if (faults.length) {
+    const hit = engineOf(faults.map((f) => ({ id: `entry-${f.index}`, on: f.on!, fault: kernelFault(f) }))).next(asked);
+    if (hit.kind === 'handler') {
+      const fault = faults.find((f) => `entry-${f.index}` === hit.ruleId)!;
+      await recordFault(ledger, fault, { point: 'turn' });
+      // a generation failure is admitted, then fails: the pack's handler answers it in its SDK's error wire
+      if (fault.kind === 'generation') return hit;
+      const result = await scenarioFaultResult(hit.fault!, () => adapter.renderFault?.(hit.fault as ScenarioStatusFault, asked), signal);
+      if (result !== null) return { kind: 'fault', result, ruleId: hit.ruleId };
+    }
+  }
+  const decisions = turnDecisions(ledger);
+  const decided = engineOf(decisions.map((d) => ({ id: `entry-${d.index}`, on: d.on ?? {}, respond: d.outcome }))).next(asked);
+  await recordTurn(ledger, decided.kind === 'handler' ? decisions.find((d) => `entry-${d.index}` === decided.ruleId) : undefined, decided.kind === 'handler' ? decided.respond : null);
+  return decided;
+}
+
+/** What a request fault answers in place of the vendor's answer: the vendor's own envelope where the pack renders one. */
+export async function faultAnswer(fault: PlacedFault, render: (() => { body: unknown; headers?: Record<string, string> } | undefined) | undefined, signal?: AbortSignal): Promise<Response | null> {
+  const result = await scenarioFaultResult(kernelFault(fault), render, signal);
+  return result === null ? null : Response.json(result.body, { status: result.status, headers: result.headers });
+}

package/src/scenario-timeline.ts

@@ -0,0 +1,269 @@
+// 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.ts';
+import { worldNow } from './world-clock.ts';
+import { parseExactJson } from './exact-json.ts';
+
+export const WORLD_SCENARIO_ENV = 'TWIN_WORLD_SCENARIO_FILE';
+
+/** A call to a vendor's API at its own URL, routed to its twin as the application's calls are; `${NAME}` in a header is
+ *  the value the World sets for its application, and `as` names the person whose World browser carries its cookies. */
+export type ScenarioCall = { method: string; url: string; headers?: Record<string, string>; body?: unknown; as?: string };
+export type ScenarioAction = { person: string; browser?: string; run: string };
+/** The outcome of a vendor's judgement at one of its decision points, for the subject it is keyed to (absent: every
+ *  subject); a model vendor's turn is the point `turn`, keyed by `on`, the pack's scenario matchers. */
+type ScenarioDecisionInput = { vendor: string; point: string; subject?: string; on?: Record<string, unknown>; outcome: unknown; once?: boolean };
+
+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'],
+} as const;
+type FaultLayer = keyof typeof FAULT_KINDS;
+/** The layers asked of the machine the app runs on, through its fault door (ADR 0036 §4). */
+export const MACHINE_LAYERS: ReadonlyArray<FaultLayer> = ['network', 'infrastructure'];
+
+export type ScenarioFaultInput = {
+  layer: FaultLayer;
+  kind: string;
+  /** the twin a vendor-layer fault lands in */
+  vendor?: string;
+  /** a request fault's operation (the spec's operationId), or a model turn's `on`; neither: every request */
+  operation?: string;
+  on?: Record<string, unknown>;
+  /** a point of the pack's own (`ctx.fault(point, subject)`: one item of a batch) */
+  point?: string;
+  subject?: string;
+  status?: number;
+  message?: string;
+  errorType?: string;
+  metadata?: Record<string, unknown>;
+  partialText?: string;
+  event?: string;
+  retryAfterSeconds?: number;
+  ms?: number;
+  /** a delay, a lag or a window: `90s`, `5m`, `12h`, `30d` */
+  by?: string;
+  per?: string;
+  limit?: number;
+  /** a machine fault's part of the app, as the machine knows it; a reset's or a TLS failure's destination; a full disk's
+   *  volume */
+  target?: string;
+  to?: string;
+  volume?: string;
+  between?: [string, string];
+  rate?: number;
+  /** how many times it lands (default: every time, until `until`) */
+  times?: number;
+  until?: string;
+};
+
+type ScenarioClock = { advance: string } | { set: string };
+
+type TimelineEntry = { at: string } & (
+  | { call: ScenarioCall }
+  | { action: ScenarioAction }
+  | { decision: ScenarioDecisionInput }
+  | { fault: ScenarioFaultInput }
+  | { clock: ScenarioClock }
+);
+
+export type Scenario = { start: string; random?: string; timeline: TimelineEntry[]; properties?: string };
+
+/** A scenario as a World plays it: every `at` an instant, each entry its place in the timeline (what a twin's record of a
+ *  consumption names). */
+export type ResolvedScenario = { name: string; start: string; random: string; timeline: Array<TimelineEntry & { index: number }>; properties?: string };
+
+export class ScenarioTimelineError extends Error {}
+
+const fail = (where: string, message: string): never => { throw new ScenarioTimelineError(`scenario: ${where}: ${message}`); };
+const isObject = (v: unknown): v is Record<string, unknown> => typeof v === 'object' && v !== null && !Array.isArray(v);
+const onlyKeys = (value: Record<string, unknown>, keys: readonly string[], where: string): void => {
+  for (const key of Object.keys(value)) if (key !== '$comment' && !keys.includes(key)) fail(where, `unknown key "${key}" (valid: ${keys.join(', ')})`);
+};
+const text = (value: unknown, where: string, name: string): string => (typeof value === 'string' && value.length > 0 ? value : fail(where, `${name} is a non-empty string`));
+const instant = (value: unknown, where: string, name: string): string => {
+  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: string): number {
+  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] as 's' | 'm' | 'h' | 'd'];
+}
+const duration = (value: unknown, where: string, name: string): string => {
+  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: unknown, where: string, name: string): number => (Number.isInteger(value) && (value as number) > 0 ? value as number : fail(where, `${name} is a positive integer`));
+
+function parseCall(raw: unknown, where: string): ScenarioCall {
+  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 as Record<string, string> } : {}), ...('body' in raw ? { body: raw.body } : {}), ...(raw.as !== undefined ? { as: text(raw.as, where, 'call.as') } : {}) };
+}
+
+function parseAction(raw: unknown, where: string): ScenarioAction {
+  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: unknown, where: string): ScenarioDecisionInput {
+  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 as Record<string, unknown> } : {}), outcome: raw.outcome, ...(raw.once !== undefined ? { once: raw.once as boolean } : {}) };
+}
+
+const FAULT_KEYS: Record<string, readonly string[]> = {
+  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: unknown, where: string): ScenarioFaultInput {
+  if (!isObject(raw)) return fail(where, 'fault is an object { layer, kind, ... }');
+  const layer = raw.layer as FaultLayer;
+  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] as readonly string[];
+  if (!kinds.includes(raw.kind as string)) fail(where, `a ${layer} fault's kind is one of ${kinds.join(', ')}, got ${JSON.stringify(raw.kind)}`);
+  const kind = raw.kind as string;
+  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 as number) >= 400 && (raw.status as number) <= 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'] as const) 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 as number) >= 0 && (raw.ms as number) <= 600_000)) fail(where, 'fault.ms is an integer 0..600000 (milliseconds)');
+  if (raw.retryAfterSeconds !== undefined && !(Number.isInteger(raw.retryAfterSeconds) && (raw.retryAfterSeconds as number) >= 0)) fail(where, 'fault.retryAfterSeconds is a non-negative integer');
+  for (const name of ['by', 'per'] as const) 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 as ScenarioFaultInput;
+}
+
+function parseClock(raw: unknown, where: string): ScenarioClock {
+  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'] as const;
+
+/** Strict parse of a scenario document: every refusal names where it is and the vocabulary it expected. */
+export function parseScenario(raw: unknown): Scenario {
+  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 as unknown[]).map((entry, i): TimelineEntry => {
+    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 } as TimelineEntry;
+  });
+  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: string, doc: Scenario): ResolvedScenario {
+  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<string, { raw: string; value: unknown }>();
+
+/** 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<T>(env: string): T | null {
+  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 as T;
+  const value = parseExactJson(raw);
+  kept.set(env, { raw, value });
+  return value as T;
+}
+
+/** The scenario this World is playing (the instance's resolved document), or null when it plays none. */
+function activeScenario(): ResolvedScenario | null {
+  return worldJsonFile<ResolvedScenario>(WORLD_SCENARIO_ENV);
+}
+
+/** The decisions and vendor faults the World's scenario places on one vendor, in timeline order. */
+export function placedOn(vendor: string): ResolvedScenario['timeline'] {
+  return (activeScenario()?.timeline ?? []).filter((e) => ('decision' in e && e.decision.vendor === vendor) || ('fault' in e && e.fault.vendor === vendor));
+}
+
+export type PlacedDecision = ScenarioDecisionInput & { index: number; at: string };
+export type PlacedFault = ScenarioFaultInput & { index: number; at: string };
+
+/** The decisions placed for a vendor's point at or before the World's now, in timeline order. */
+export function placedDecisions(vendor: string, point: string, now: string = worldNow()): PlacedDecision[] {
+  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: string, layer: 'request' | 'over-time', now: string = worldNow()): PlacedFault[] {
+  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 }] : []));
+}