@volter/world-core 3.0.166 → 3.0.167

package/dist/src/pack-fetch.js

@@ -13,11 +13,16 @@ import { ORIGINAL_PATH_HEADER } from "./sigv4.js";
 import { placedCookies, TWIN_PREFIX_HEADER } from "./twin-fetch.js";
 import { PREFIX_PARAMS_HEADER } from "./derived.js";
 import { withHeaders } from "./with-headers.js";
-import { authRefusal, bindSemantics, contextFor, LANE_HEADER, SCENARIO_DECISION_HEADER, scenarioDecisionHeader, storedType, coreFor, crossCutting, derivedRequestScopes, vendorError } from "./derived-core.js";
+import { authRefusal, bindSemantics, contextFor, scenarioLedgerOf, scenarioRecords, LANE_HEADER, SCENARIO_DECISION_HEADER, scenarioDecisionHeader, storedType, coreFor, crossCutting, derivedRequestScopes, vendorError } from "./derived-core.js";
 import { compileSurface, createDerivedFetch, matchOperation, pathParams } from "./derived.js";
 import { isReadOnlyRequest, READ_ONLY_REQUEST_HEADER, runAsVendorMove } from "./request-scope.js";
-import { parseScenarioDocument, ScenarioEngine, ScenarioError, statefulTwinManifest, twinManifest } from "./scenario.js";
-import { getActiveWorldStore } from "./world-store.js";
+import { ScenarioError, statefulTwinManifest, twinManifest } from "./scenario.js";
+import { placedOn } from "./scenario-timeline.js";
+import { rateLimited, recordFault, requestFaults } from "./scenario-consume.js";
+import { faultAnswer, kernelFault, serveTurn } from "./scenario-serve.js";
+import { onHeldDelivery, releaseHeldDeliveries } from "./events.js";
+import { getActiveWorldStore, withWorldStore } from "./world-store.js";
+import { noteCompleteness } from "./completeness.js";
 import { runWithCorrelationId } from "./actions.js";
 import { deferPerform, deployableEntries, performRequestGroup, RefusedWriteError, VendorWriteError } from "./head.js";
 import { FLUSH, ZERO_SHA, pktLine, readPktLines } from "./git/smart-http.js";
@@ -30,7 +35,7 @@ import { expireSocketWaits, socketUpgrade } from "./sockets.js";
 import { liveIngest } from "./live/ingest.js";
 import { readResourceBlob, removeResourceBlob, writeResourceBlob } from "./resource-blob.js";
 import { gitRepositoryOf, resourcesOfType } from "./derived-core.js";
-import { worldNow } from "./world-clock.js";
+import { worldClockRunning, worldNow } from "./world-clock.js";
 import { MACHINE_POOL, POOL_KINDS, resetFakePool } from "./machines.js";
 import { applyTwinWrite } from "./serve.js";
 import { graphqlEndpoint } from "./graphql-wire.js";
@@ -260,6 +265,8 @@ export function createPackFetch(parts, options = {}) {
             const refused = m.auth?.beforeRouting ? authRefusal(m, request, options.root) : undefined;
             if (refused)
                 return refused;
+            // an operation this twin does not implement is what the World is missing at this vendor (ADR 0036 §9)
+            noteCompleteness(process.env, { kind: 'unimplemented', vendor: m.vendor, method: request.method, path: new URL(request.url).pathname, ...(operation ? { operation: operation.id } : {}) });
             if (parts.gap) {
                 const url = new URL(request.url);
                 const matched = operation ? matchOperation(routes, request.method, url.pathname, url.searchParams, request.headers) : undefined;
@@ -284,25 +291,39 @@ export function createPackFetch(parts, options = {}) {
             return graphql(request);
         return rest(request);
     }, { owners: rest.owners });
-    // the World's scenario, read from the World's store at every turn, HTTP or socket alike: a file the World rewrites takes
-    // effect at the next turn, with no reboot; the engine (its handlers' counts) is kept while the file is unchanged
-    let engine;
-    let engineRaw;
-    const engineOf = () => {
-        if (!parts.scenario || options.scenarioPath === undefined)
-            return undefined;
-        const raw = getActiveWorldStore().read(options.scenarioPath);
-        if (raw === null)
-            throw new ScenarioError(`${m.vendor} scenario: no file at ${options.scenarioPath}`);
-        if (!engine || raw !== engineRaw) {
-            engine = new ScenarioEngine(parts.scenario.adapter, parseScenarioDocument(parseExactJson(raw), parts.scenario.adapter));
-            engineRaw = raw;
+    // the World's scenario (scenario-timeline.ts), read through the World's store at every request as the clock is: a
+    // model vendor's turns, and the faults placed on this vendor's requests, consumed and recorded in its own log
+    const placesThis = () => placedOn(m.vendor).length > 0;
+    // the work the World's time makes due (ADR 0036 §4): done when the clock's mover asks (`POST /twin/due`) and waits, and
+    // under a running clock by one timer set for the instant the next work falls due
+    let dueTimer;
+    const due = async () => {
+        if (!m.events)
+            return null;
+        const next = await releaseHeldDeliveries(m.service, options.root, m.events.record);
+        if (dueTimer !== undefined) {
+            clearTimeout(dueTimer);
+            dueTimer = undefined;
+        }
+        const store = getActiveWorldStore();
+        if (next !== null && worldClockRunning()) {
+            dueTimer = setTimeout(() => { dueTimer = undefined; void withWorldStore(store, due).catch(() => undefined); }, Math.max(0, Date.parse(next) - Date.parse(worldNow())));
+            dueTimer.unref?.();
         }
-        return engine;
+        return next;
     };
-    /** The API, a turn the scenario decides handed its decision (ctx.scenario), or answered as the fault it names. */
+    // a packet held under a running clock sets the timer for when it falls due; so does a twin that starts with held work
+    // in its store (what time crossed while it was down is sent at once)
+    const arm = () => { if (worldClockRunning())
+        void due().catch(() => undefined); };
+    if (m.events) {
+        onHeldDelivery(m.service, options.root, arm);
+        const store = getActiveWorldStore();
+        queueMicrotask(() => { void withWorldStore(store, async () => arm()); });
+    }
+    /** The API, a turn handed its decision (ctx.scenario), or answered as the fault the World's scenario placed on it. */
     const decided = async (arrived) => {
-        if (!parts.scenario)
+        if (!parts.scenario && !placesThis())
             return api(arrived);
         // the body is read once and the request made again from its bytes, so the turn's context and the API each read their
         // own. Merge served with --scenario once answered no turn in 8 s (t_c0279b69), and this change came with the cure;
@@ -313,32 +334,69 @@ export function createPackFetch(parts, options = {}) {
         const request = new Request(arrived.url, { method: arrived.method, headers: arrived.headers, signal: arrived.signal, ...(bytes ? { body: bytes } : {}) });
         const url = new URL(request.url);
         const matched = matchOperation(routes, request.method, url.pathname, url.searchParams, request.headers);
-        if (!matched || !parts.scenario.operations.includes(matched.operation.id))
+        if (!matched)
             return api(request);
-        // the credential is the vendor's first question: a request it refuses takes no scripted turn
-        if (!m.auth?.exempt?.includes(matched.operation.id)) {
-            const refused = authRefusal(m, request, options.root);
-            if (refused)
-                return refused;
-        }
-        let decision;
+        const turn = parts.scenario?.operations.includes(matched.operation.id) === true;
+        if (!turn && !placesThis())
+            return api(request);
+        const ctx = await contextFor(m, { request: request.clone(), operation: matched.operation, params: matched.params }, scope);
+        const ledger = scenarioLedgerOf(ctx);
+        const asked = turn ? parts.scenario.request(ctx) : undefined;
+        /** A fault's answer in the vendor's own envelope: the model wire's, where the pack renders a turn's, else the manifest's
+         *  error; null when it holds the request (`slow`) and the answer follows. */
+        const answerFault = async (fault) => {
+            const placed = kernelFault(fault);
+            const adapter = parts.scenario?.adapter;
+            if (placed.kind !== 'status' || (asked !== undefined && adapter?.renderFault))
+                return faultAnswer(fault, asked !== undefined && adapter?.renderFault ? () => adapter.renderFault(placed, asked) : undefined, request.signal);
+            const refused = vendorError(m, { status: placed.status, code: placed.errorType ?? 'twin_fault', message: placed.message });
+            if (placed.retryAfterSeconds !== undefined)
+                refused.headers.set('retry-after', String(placed.retryAfterSeconds));
+            return refused;
+        };
         try {
-            const turns = engineOf();
-            if (!turns)
-                return api(request);
-            const asked = parts.scenario.request(await contextFor(m, { request: request.clone(), operation: matched.operation, params: matched.params }, scope));
-            if (asked === undefined)
-                return api(request);
-            decision = await turns.serve(asked);
+            // a rejection at the vendor's edge comes before its credential is read; a rate limit counts every request
+            const fault = requestFaults(ledger).find((f) => f.on === undefined && f.point === undefined && (f.operation === undefined || f.operation === matched.operation.id));
+            if (fault?.kind === 'rejected') {
+                await recordFault(ledger, fault, { operation: matched.operation.id });
+                return (await answerFault(fault));
+            }
+            const limited = await rateLimited(ledger, matched.operation.id);
+            if (limited)
+                return (await answerFault(limited));
+            // the credential is the vendor's first question: a request it refuses takes no turn and meets no other fault
+            if ((turn || fault) && !m.auth?.exempt?.includes(matched.operation.id)) {
+                const refused = authRefusal(m, request, options.root);
+                if (refused)
+                    return refused;
+            }
+            if (fault) {
+                await recordFault(ledger, fault, { operation: matched.operation.id });
+                // committed, and its answer lost: the write lands, and the app is told it failed
+                if (fault.kind === 'lost') {
+                    await (await answer(request, asked, ledger)).arrayBuffer();
+                    return (await answerFault({ ...fault, kind: 'failed' }));
+                }
+                const answered = await answerFault(fault);
+                if (answered)
+                    return answered;
+            }
+            return await answer(request, asked, ledger);
         }
         catch (error) {
             if (!(error instanceof ScenarioError))
                 throw error;
             return vendorError(m, { status: 500, code: 'scenario_error', message: `the World's scenario: ${error.message}` });
         }
-        if (decision.kind === 'fault')
-            return Response.json(decision.result.body, { status: decision.result.status, headers: decision.result.headers ?? {} });
-        return api(withHeaders(request, new Headers([...request.headers, [SCENARIO_DECISION_HEADER, scenarioDecisionHeader(decision)]])));
+    };
+    /** The request answered by the API, a turn first decided by the World's scenario. */
+    const answer = async (request, asked, ledger) => {
+        if (asked === undefined)
+            return api(request);
+        const served = await serveTurn(asked, ledger, parts.scenario.adapter, request.signal);
+        if (served.kind === 'fault')
+            return Response.json(served.result.body, { status: served.result.status, headers: served.result.headers ?? {} });
+        return api(withHeaders(request, new Headers([...request.headers, [SCENARIO_DECISION_HEADER, scenarioDecisionHeader(served)]])));
     };
     for (const d of m.doors ?? [])
         if (!parts.doors?.[d.id])
@@ -513,18 +571,20 @@ export function createPackFetch(parts, options = {}) {
                 const body = twinManifest({
                     vendor: m.vendor, twinOf: d.twinOf,
                     stateSentence: `Stateful: it stores ${d.stores}. Create state through the vendor's OWN API with the real SDK or plain fetch pointed here${discoveryDoors.length ? "; what the vendor does on its own pages (not its API) is a door of the World, listed under doors" : ''}.`,
-                    behaviorSentence: d.behavior, exampleHandler: d.exampleHandler ?? null, ...(engineOf() ? { engine: engineOf() } : {}),
+                    behaviorSentence: d.behavior, exampleHandler: d.exampleHandler ?? null,
                 });
                 const declared = Object.fromEntries(discoveryDoors.map((door) => [`${door.method} ${doorPath(door.path)}`, door.note ?? 'a door of the World']));
                 return Response.json({ ...shown, ...body, program: { ...body.program, ...(identity ? { identity } : {}) }, doors: { ...body.doors, ...declared } });
             }
             return Response.json({ ...statefulTwinManifest({ vendor: m.vendor, twinOf: d.twinOf, stores: d.stores, ...(identity ? { identity } : {}), ...(d.behavior ? { behavior: d.behavior } : {}), ...(d.notes ? { notes: d.notes } : {}), ...(discoveryDoors.length ? { doors: discoveryDoors.map((door) => ({ ...door, path: doorPath(door.path) })) } : {}) }), ...shown });
         }
-        // the scenario's handlers with their match counts, and the recent misses
+        // the World's clock has moved: do what it made due, and answer once it is done (ADR 0036 §4)
+        if (request.method === 'POST' && path === '/twin/due')
+            return Response.json({ next: await due() });
+        // what the World's scenario placed on this vendor, and what the twin consumed of it (its `_decision` and `_fault` records)
         if (request.method === 'GET' && path === '/twin/scenario') {
             const lanes = await laneDoor(request, '/twin/scenario');
-            if (parts.scenario || Object.keys(lanes).length)
-                return Response.json({ ...(engineOf()?.status() ?? { vendor: m.vendor, handlers: [], misses: 0, recentMisses: [] }), ...(Object.keys(lanes).length ? { lanes } : {}) });
+            return Response.json({ ...scenarioRecords(m, options.root), ...(Object.keys(lanes).length ? { lanes } : {}) });
         }
         // the vendor's own moves, not the caller's: its context carries none of the request's headers (a Stripe-Account
         // header would make a payout time makes the caller's), but a tenant's, when the vendor keeps tenants apart
@@ -732,7 +792,7 @@ export function createPackFetch(parts, options = {}) {
             throw new Error(`${m.vendor}: the manifest declares the socket ${d.id}, and semantics/sockets.ts exports no ${d.id}`);
     const ownUpgrade = m.sockets?.length ? socketUpgrade(m.service, options.root, m.sockets, parts.sockets, (request, d, params) => open(request, `socket:${d.id}`, 'GET', d.path, params), hostOf, (request) => new URL(routed(request).url).pathname, 
     // a turn a session speaks (a voice agent's reply) is the World's scenario's, as a turn over HTTP is
-    async (asked) => engineOf()?.serve(asked)) : undefined;
+    async (asked, context) => (parts.scenario ? serveTurn(asked, scenarioLedgerOf(await context()), parts.scenario.adapter) : undefined)) : undefined;
     const rawUpgrade = laneUpgrades(parts.lanes ?? {}, ownUpgrade);
     const opening = new WeakMap();
     const upgrade = rawUpgrade && m.tenant?.storage === 'namespaced' && parts.tenant ? {

package/dist/src/runtime.d.ts

@@ -1,6 +1,9 @@
 export { clearRegistry, getPack, hasPack, listPacks, packOf, registerPack, pullPosture, assertContinuousPullAllowed, pullOnSchedule, resolvePullVendor, DEFAULT_PULL_POSTURE, DEFAULT_PULL_TRIGGER, PROTOCOL_VERSION, PROTOCOL_MAJOR, PACK_ARCHETYPES, protocolStanding } from './packRegistry.js';
 export type { PackTransport, PullPosture, PullTrigger, PullVendor, RoundTripWrite, TwinPack } from './packRegistry.js';
-export { parseScenarioDocument, scenarioFaultResult, ScenarioEngine, ScenarioError, statefulTwinManifest, twinManifest } from './scenario.js';
+export { scenarioFaultResult, ScenarioError, statefulTwinManifest, twinManifest } from './scenario.js';
+export { durationMs, MACHINE_LAYERS, parseScenario, resolveScenario, ScenarioTimelineError } from './scenario-timeline.js';
+export type { ResolvedScenario, ScenarioAction, ScenarioCall, ScenarioFaultInput } from './scenario-timeline.js';
+export { completenessMark, completenessSince, noteCompleteness, type Completeness } from './completeness.js';
 export { WORLD_CLOCK_ENV, worldNow } from './world-clock.js';
 export { WORLD_ENV_NAMES_ENV, worldEnvValue } from './world-env.js';
 export { ORIGINAL_PATH_HEADER } from './sigv4.js';
@@ -19,7 +22,7 @@ export type { EventDelivery, EventRender, EventScheme, EventsDecl, EventTranspor
 export type { Actor, CoreScope, DerivedManifest, ErrorSpec, FieldRule, Handler, HandlerContext, ResourceDecl, WriteHookContext, ScreenDecl, Semantics, SemanticsContext, StateField, Transition, TransitionObserver, SeedCall } from './derived-core.js';
 export type { RemoteExecute, RemoteExecuteRequest, RemoteExecuteResponse } from './remote-execute.js';
 export type { TwinFetchAdapterConfig, TwinFetchHandlerRequest, TwinFetchHandlerResult, TwinStream, TwinStreamConnection, TwinStreamSink } from './twin-fetch.js';
-export type { PackScenarioAdapter, ScenarioDecision, ScenarioDocument, ScenarioExtractorSpec, ScenarioFault, ScenarioFaultResult, ScenarioFeatures, ScenarioHandler, ScenarioMatcher, ScenarioMissRecord, ScenarioStatus } from './scenario.js';
+export type { PackScenarioAdapter, ScenarioDecision, ScenarioFault, ScenarioFaultResult, ScenarioFeatures, ScenarioHandler, ScenarioMatcher, ScenarioMissRecord } from './scenario.js';
 export { emitTwinEvent, eventSubscriptionMatches, listEmittable, runEmitCli } from './emit.js';
 export type { EmitDeliveryResult, EmitEndpoint, EmitReport, EmittableEvent, SynthesizedDelivery, TwinEmitter } from './emit.js';
 export { DEFAULT_RATE_BUDGET, MAX_RATE_BUDGET_CEILING, MAX_RATE_BUDGET_WINDOW_MS, MIN_RATE_BUDGET_WEIGHT, MIN_RATE_BUDGET_WINDOW_MS, RateBudget, RateBudgetError, declareRateBudget, hasRateBudgetDeclaration, listRateBudgets, priceCall, rateBudgetPath, rateBudgetPolicy, rateBudgetWeight, resetToSeconds, assertBudgetGuardIntact, } from './rateBudget.js';

package/dist/src/runtime.js

@@ -8,7 +8,9 @@
 export { clearRegistry, getPack, hasPack, listPacks, packOf, registerPack, pullPosture, assertContinuousPullAllowed, pullOnSchedule, resolvePullVendor, DEFAULT_PULL_POSTURE, DEFAULT_PULL_TRIGGER, PROTOCOL_VERSION, PROTOCOL_MAJOR, PACK_ARCHETYPES, protocolStanding } from "./packRegistry.js";
 // The DELIVER verb (`emit`) — vendor-agnostic engine + CLI glue; packs declare a TwinEmitter
 // (their event catalog, endpoints-from-state, and signed synthesis) on `TwinPack.emitter`.
-export { parseScenarioDocument, scenarioFaultResult, ScenarioEngine, ScenarioError, statefulTwinManifest, twinManifest } from "./scenario.js";
+export { scenarioFaultResult, ScenarioError, statefulTwinManifest, twinManifest } from "./scenario.js";
+export { durationMs, MACHINE_LAYERS, parseScenario, resolveScenario, ScenarioTimelineError } from "./scenario-timeline.js";
+export { completenessMark, completenessSince, noteCompleteness } from "./completeness.js";
 export { WORLD_CLOCK_ENV, worldNow } from "./world-clock.js";
 export { WORLD_ENV_NAMES_ENV, worldEnvValue } from "./world-env.js";
 export { ORIGINAL_PATH_HEADER } from "./sigv4.js";

package/dist/src/scenario-consume.d.ts

@@ -0,0 +1,43 @@
+import { type PlacedDecision, type PlacedFault } from './scenario-timeline.js';
+/** What a consumption reads and writes: the twin's own bookkeeping rows, at the request's World time. `recording` is
+ *  false for a read-only request, which consumes nothing. */
+export type ScenarioLedger = {
+    vendor: string;
+    service: string;
+    root?: string;
+    at: string;
+    recording: boolean;
+    rows(type: '_decision' | '_fault' | '_fact' | '_rate'): Array<Record<string, unknown>>;
+    record(type: '_decision' | '_fault' | '_fact' | '_rate', fields: Record<string, unknown>, id?: string): Promise<unknown>;
+};
+/** The vendor's judgement at `point` for `subject`: the first decision the timeline placed for it, else `byDefault`;
+ *  recorded either way. */
+export declare function decide<T>(ledger: ScenarioLedger, point: string, subject: string, byDefault: T): Promise<T>;
+/** The model turns the timeline placed for this vendor and not yet used up, in order: what the kernel matches a turn
+ *  against with the pack's matchers. */
+export declare function turnDecisions(ledger: ScenarioLedger): PlacedDecision[];
+/** Record a turn's decision: the placed one that answered it, or the labelled default. */
+export declare function recordTurn(ledger: ScenarioLedger, chosen: PlacedDecision | undefined, outcome: unknown): Promise<void>;
+/** The request faults placed on this vendor that are not used up, in order. */
+export declare function requestFaults(ledger: ScenarioLedger): PlacedFault[];
+/** Record a fault that landed. */
+export declare function recordFault(ledger: ScenarioLedger, fault: PlacedFault, where: Record<string, unknown>): Promise<void>;
+/** A fault the timeline placed at a point of the pack's own (one item of a batch), for `subject`; recorded when it lands. */
+export declare function faultAt(ledger: ScenarioLedger, point: string, subject: string): Promise<PlacedFault | undefined>;
+/** A ledger over a twin's store alone, for the kernel's own paths that open no context (an event's delivery, a list the
+ *  core answers). */
+export declare function serviceLedger(input: {
+    vendor: string;
+    service: string;
+    root?: string;
+    at: string;
+    recording: boolean;
+}): ScenarioLedger;
+/** The first webhook fault placed on this vendor for an event type, not used up. */
+export declare function webhookFault(ledger: ScenarioLedger, type: string): PlacedFault | undefined;
+/** The `lag` the timeline placed on this vendor's lists (an `operation` names one list), if any. */
+export declare function listLag(ledger: ScenarioLedger, operation: string): PlacedFault | undefined;
+/** A rate limit the timeline placed, counted: this request's count in its window, and whether it is past the limit. */
+export declare function rateLimited(ledger: ScenarioLedger, operation: string): Promise<PlacedFault | undefined>;
+/** A World fact the twin answers with, recorded as answered (undefined when the World holds none). */
+export declare function fact(ledger: ScenarioLedger, kind: string, key: string): Promise<unknown>;

package/dist/src/scenario-consume.js

@@ -0,0 +1,111 @@
+// How a twin consumes its World's scenario (architecture, "Scenarios"; ADR 0036 §2-4, §10): a decision where its vendor
+// decides, a fault where it lands, a World fact where the vendor answers with one. Every consumption is recorded in the
+// twin's own log as bookkeeping (`_decision`, `_fault`, `_fact`), so the state a run reaches holds what was decided and
+// what failed, a `once` decision or a counted fault is used up by the log rather than by a process's memory, and a branch
+// or a replay agrees. A twin whose head is real consults no scenario: its vendor decides and fails on its own.
+import { headOf } from "./head.js";
+import { applyTwinWriteAtomic, twinResources } from "./serve.js";
+import { durationMs, placedDecisions, placedFaults, worldJsonFile } from "./scenario-timeline.js";
+const WORLD_FACTS_ENV = 'TWIN_WORLD_FACTS_FILE';
+const simulated = (ledger) => headOf(ledger.service, ledger.root).kind !== 'real';
+const usedTimes = (ledger, type, index) => ledger.rows(type).filter((r) => r.entry === index).length;
+const available = (ledger, type, index, limit) => limit === undefined || usedTimes(ledger, type, index) < limit;
+const decisionLeft = (ledger, d) => available(ledger, '_decision', d.index, d.once ? 1 : undefined);
+const faultLeft = (ledger, f) => available(ledger, '_fault', f.index, f.times);
+/** The vendor's judgement at `point` for `subject`: the first decision the timeline placed for it, else `byDefault`;
+ *  recorded either way. */
+export async function decide(ledger, point, subject, byDefault) {
+    if (!simulated(ledger))
+        return byDefault;
+    const chosen = placedDecisions(ledger.vendor, point, ledger.at).find((d) => d.on === undefined && (d.subject === undefined || d.subject === subject) && decisionLeft(ledger, d));
+    const outcome = (chosen ? chosen.outcome : byDefault);
+    if (ledger.recording)
+        await ledger.record('_decision', { point, subject, outcome, entry: chosen?.index ?? 'default', decidedAt: ledger.at });
+    return outcome;
+}
+/** The model turns the timeline placed for this vendor and not yet used up, in order: what the kernel matches a turn
+ *  against with the pack's matchers. */
+export function turnDecisions(ledger) {
+    if (!simulated(ledger))
+        return [];
+    return placedDecisions(ledger.vendor, 'turn', ledger.at).filter((d) => decisionLeft(ledger, d));
+}
+/** Record a turn's decision: the placed one that answered it, or the labelled default. */
+export async function recordTurn(ledger, chosen, outcome) {
+    if (ledger.recording)
+        await ledger.record('_decision', { point: 'turn', outcome, entry: chosen?.index ?? 'default', decidedAt: ledger.at });
+}
+/** The request faults placed on this vendor that are not used up, in order. */
+export function requestFaults(ledger) {
+    if (!simulated(ledger))
+        return [];
+    return placedFaults(ledger.vendor, 'request', ledger.at).filter((f) => faultLeft(ledger, f));
+}
+/** Record a fault that landed. */
+export async function recordFault(ledger, fault, where) {
+    if (ledger.recording)
+        await ledger.record('_fault', { ...where, layer: fault.layer, kind: fault.kind, entry: fault.index, landedAt: ledger.at });
+}
+/** A fault the timeline placed at a point of the pack's own (one item of a batch), for `subject`; recorded when it lands. */
+export async function faultAt(ledger, point, subject) {
+    const fault = requestFaults(ledger).find((f) => f.point === point && (f.subject === undefined || f.subject === subject));
+    if (fault)
+        await recordFault(ledger, fault, { point, subject });
+    return fault;
+}
+/** A ledger over a twin's store alone, for the kernel's own paths that open no context (an event's delivery, a list the
+ *  core answers). */
+export function serviceLedger(input) {
+    const rows = (type) => twinResources(input.service, input.root).filter((r) => r.type === type && r.deleted !== true);
+    return {
+        ...input,
+        rows,
+        record: async (type, fields, id) => {
+            await applyTwinWriteAtomic(input.service, (resources) => {
+                const prefix = `${type.slice(1)}_`;
+                const next = id ?? `${prefix}${1 + Math.max(0, ...resources.filter((r) => r.type === type && r.id.startsWith(prefix)).map((r) => Number(r.id.slice(prefix.length)) || 0))}`;
+                return { kind: 'write', value: next, write: { operation: `${type.slice(1)}.record`, subjectType: type, subjectId: next, fields, occurredAt: input.at, actor: { kind: 'system' } } };
+            }, input.root);
+        },
+    };
+}
+/** The first webhook fault placed on this vendor for an event type, not used up. */
+export function webhookFault(ledger, type) {
+    return overTimeFaults(ledger).find((f) => f.kind.startsWith('webhook-') && (f.event === undefined || f.event === type) && faultLeft(ledger, f));
+}
+/** The `lag` the timeline placed on this vendor's lists (an `operation` names one list), if any. */
+export function listLag(ledger, operation) {
+    return overTimeFaults(ledger).find((f) => f.kind === 'lag' && (f.operation === undefined || f.operation === operation));
+}
+/** The over-time faults placed on this vendor, in order. */
+function overTimeFaults(ledger) {
+    if (headOf(ledger.service, ledger.root).kind === 'real')
+        return [];
+    return placedFaults(ledger.vendor, 'over-time', ledger.at);
+}
+/** A rate limit the timeline placed, counted: this request's count in its window, and whether it is past the limit. */
+export async function rateLimited(ledger, operation) {
+    if (!ledger.recording)
+        return undefined;
+    for (const fault of overTimeFaults(ledger)) {
+        if (fault.kind !== 'rate-limit' || (fault.operation !== undefined && fault.operation !== operation))
+            continue;
+        const per = durationMs(fault.per);
+        const window = Math.floor((Date.parse(ledger.at) - Date.parse(fault.at)) / per);
+        const id = `rate_${fault.index}_${window}`;
+        const count = Number(ledger.rows('_rate').find((r) => r.id === id)?.count ?? 0) + 1;
+        await ledger.record('_rate', { count, entry: fault.index, window }, id);
+        if (count > fault.limit) {
+            await recordFault(ledger, fault, { operation, count });
+            return fault;
+        }
+    }
+    return undefined;
+}
+/** A World fact the twin answers with, recorded as answered (undefined when the World holds none). */
+export async function fact(ledger, kind, key) {
+    const value = worldJsonFile(WORLD_FACTS_ENV)?.[kind]?.[key];
+    if (ledger.recording)
+        await ledger.record('_fact', { kind, key, value: value ?? null, answeredAt: ledger.at });
+    return value;
+}

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

@@ -0,0 +1,16 @@
+import { type PackScenarioAdapter, type ScenarioFault } from './scenario.js';
+import { type ScenarioLedger } from './scenario-consume.js';
+import type { PlacedFault } from './scenario-timeline.js';
+import type { ScenarioServed } from './sockets.js';
+/** 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 declare function kernelFault(fault: PlacedFault): ScenarioFault;
+/** 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 declare function serveTurn<Req>(asked: Req, ledger: ScenarioLedger, adapter: PackScenarioAdapter<Req>, signal?: AbortSignal): Promise<ScenarioServed>;
+/** What a request fault answers in place of the vendor's answer: the vendor's own envelope where the pack renders one. */
+export declare function faultAnswer(fault: PlacedFault, render: (() => {
+    body: unknown;
+    headers?: Record<string, string>;
+} | undefined) | undefined, signal?: AbortSignal): Promise<Response | null>;

package/dist/src/scenario-serve.js

@@ -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 } from "./scenario.js";
+import { recordFault, recordTurn, requestFaults, turnDecisions } from "./scenario-consume.js";
+/** 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) {
+    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(asked, ledger, adapter, signal) {
+    const engineOf = (handlers) => 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, 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, render, signal) {
+    const result = await scenarioFaultResult(kernelFault(fault), render, signal);
+    return result === null ? null : Response.json(result.body, { status: result.status, headers: result.headers });
+}

package/dist/src/scenario-timeline.d.ts

@@ -0,0 +1,131 @@
+export declare 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;
+};
+declare const FAULT_KINDS: {
+    readonly request: readonly ["rejected", "failed", "lost", "slow", "drop", "generation"];
+    readonly 'over-time': readonly ["webhook-delay", "webhook-duplicate", "webhook-drop", "lag", "rate-limit"];
+    readonly network: readonly ["reset", "dns", "tls", "latency", "loss", "partition"];
+    readonly infrastructure: readonly ["oom", "disk-full", "crash", "restart"];
+    readonly time: readonly ["jump"];
+};
+type FaultLayer = keyof typeof FAULT_KINDS;
+/** The layers asked of the machine the app runs on, through its fault door (ADR 0036 §4). */
+export declare const MACHINE_LAYERS: ReadonlyArray<FaultLayer>;
+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 declare class ScenarioTimelineError extends Error {
+}
+/** `90s`, `5m`, `12h`, `30d` in milliseconds. */
+export declare function durationMs(by: string): number;
+/** Strict parse of a scenario document: every refusal names where it is and the vocabulary it expected. */
+export declare function parseScenario(raw: unknown): Scenario;
+/** 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 declare function resolveScenario(name: string, doc: Scenario): ResolvedScenario;
+/** 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 declare function worldJsonFile<T>(env: string): T | null;
+/** The decisions and vendor faults the World's scenario places on one vendor, in timeline order. */
+export declare function placedOn(vendor: string): ResolvedScenario['timeline'];
+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 declare function placedDecisions(vendor: string, point: string, now?: string): PlacedDecision[];
+/** The vendor faults placed on a vendor at or before the World's now and not past their `until`, in timeline order. */
+export declare function placedFaults(vendor: string, layer: 'request' | 'over-time', now?: string): PlacedFault[];
+export {};