@volter/world-core 3.0.165 → 3.0.167

package/src/derived-core.ts

@@ -45,6 +45,8 @@ import { inVendorMove, isReadOnlyRequest, runAsVendorMove, writesRefused } from
 import type { DerivedCall, DerivedCoreOutcome, DerivedHandler, DerivedOperation } from './derived.ts';
 import { getPack, type PackDescriptor } from './packRegistry.ts';
 import type { ScenarioDecision, ScenarioHandler } from './scenario.ts';
+import { decide, fact, faultAt, listLag, recordFault, serviceLedger, type ScenarioLedger } from './scenario-consume.ts';
+import { durationMs, placedOn } from './scenario-timeline.ts';
 import { bodyTextOf, checkJsonBody, takeParsedBody } from './derived.ts';
 
 // ── the manifest ─────────────────────────────────────────────────────────────────────────────
@@ -1510,7 +1512,7 @@ async function finishWrite(m: DerivedManifest, call: DerivedCall, resource: stri
     const endpoint = (kind: import('./events.ts').EndpointsDecl): import('./events.ts').EndpointsDecl => ({ ...kind, storedAs: storedType(m, kind.storedAs), ...(kind.joins ? { joins: Object.fromEntries(Object.entries(kind.joins).map(([name, join]) => [name, { ...join, storedAs: storedType(m, join.storedAs) }])) } : {}) });
     const events = { ...m.events, ...(m.events.store ? { store: storedType(m, m.events.store) } : {}), endpoints: 'storedAs' in m.events.endpoints ? endpoint(m.events.endpoints) : m.events.endpoints.map(endpoint) };
     const write = { operation, storedType: m.resources[resource]?.storedAs ?? resource, body, ...(root !== undefined ? { root } : {}), occurredAt, request: request.clone() };
-    await deliverEvents(m.service, events, write, async (type) => (events.render ? events.render(await context(), write, type) : body), undefined, events.values ? async (type) => events.values!(await context(), write, type) : undefined, scopeOfCall.get(call)?.application);
+    await deliverEvents(m.service, events, write, async (type) => (events.render ? events.render(await context(), write, type) : body), undefined, events.values ? async (type) => events.values!(await context(), write, type) : undefined, scopeOfCall.get(call)?.application, m.vendor);
   }
   if (m.sockets?.length) socketWrite(m.service, root, { operation, storedType: m.resources[resource]?.storedAs ?? resource, body, ...(root !== undefined ? { root } : {}), occurredAt, request: request.clone() });
   // a read held until the World writes (held-reads.ts) hears it
@@ -1930,7 +1932,14 @@ export async function serveCore(m: DerivedManifest, call: DerivedCall, scope: Co
     }
     case 'list': {
       if (!m.list) return { unmodeled: 'no manifest list configuration' };
-      const rows = stored(m, resource, root).filter(underParent).map((r) => view(m, resource, r));
+      // a `lag` the World's scenario placed: a write younger than it is missing from lists, as an eventually consistent
+      // index misses it (architecture, "Scenarios"); recorded when it withholds one
+      const ledger = serviceLedger({ vendor: m.vendor, service: m.service, root, at, recording: !(scope.readOnly === true || isReadOnlyRequest(call.request)) });
+      const lag = listLag(ledger, op.id);
+      const settled = (r: TwinResource): boolean => !lag || Date.parse(r.updatedAt) <= Date.parse(at) - durationMs(lag.by!);
+      const listed = stored(m, resource, root).filter(underParent);
+      if (lag && listed.some((r) => !settled(r))) await recordFault(ledger, lag, { operation: op.id, withheld: listed.filter((r) => !settled(r)).map((r) => r.id) });
+      const rows = listed.filter(settled).map((r) => view(m, resource, r));
       const arranged = arrangeRows(m, resource, params, rows);
       if (!Array.isArray(arranged)) return { served: vendorError(m, arranged) };
       return { served: pageRows(m, op, call, params, arranged, resource, root, paths) };
@@ -2030,6 +2039,16 @@ export type SemanticsContext = {
   /** What the World's scenario decided for this turn (a model vendor's answer: the handler matched, or the miss), on an
    *  operation the pack's `semantics/scenario.ts` names; undefined elsewhere, or when the World carries no scenario. */
   scenario: ScenarioDecision | undefined;
+  /** The vendor's judgement at one of its decision points (a fraud score, an identity check, deliverability), for the
+   *  subject it is keyed to: what the World's scenario decided, else `byDefault`, the vendor's normal outcome; recorded in
+   *  the twin's log either way (architecture, "Scenarios"). The handler follows it with what the vendor does next. */
+  decide<T>(point: string, subject: string, byDefault: T): Promise<T>;
+  /** A fault the World's scenario placed at a point of the pack's own (one item of a batch) for `subject`, recorded as
+   *  landed; undefined when none is placed. */
+  fault(point: string, subject: string): Promise<{ kind: string; status?: number; message?: string; errorType?: string } | undefined>;
+  /** A World fact (an exchange rate, a holiday, a place) the twin answers with in its own shape, recorded as answered;
+   *  undefined when the World holds none. */
+  fact(kind: string, key: string): Promise<unknown>;
   /** A message the vendor sends the application's server and decides by its answer, waited on for at most `within`
    *  milliseconds (a real-time authorization request): its status and body, or why there was none. */
   ask(url: string, init: RequestInit, within: number): Promise<ApplicationAnswer>;
@@ -2245,6 +2264,21 @@ const coreReadsBody = (type: string | null): boolean => {
   const media = (type ?? '').split(';')[0]!.trim().toLowerCase();
   return media === '' || media === 'application/json' || media.endsWith('+json') || media === 'application/x-www-form-urlencoded' || media.startsWith('multipart/') || media.startsWith('text/');
 };
+const ledgers = new WeakMap<object, () => ScenarioLedger>();
+/** What a context consumes the World's scenario through (scenario-consume.ts): its twin's bookkeeping, at its time. */
+export function scenarioLedgerOf(ctx: object): ScenarioLedger {
+  const ledger = ledgers.get(ctx);
+  if (!ledger) throw new Error('a scenario ledger is a context the kernel opened');
+  return ledger();
+}
+
+/** `GET /twin/scenario`: what the World's scenario placed on this vendor, and what the twin consumed of it. */
+export function scenarioRecords(m: DerivedManifest, root?: string): { vendor: string; placed: unknown[]; consumed: { decisions: unknown[]; faults: unknown[] } } {
+  const placed = placedOn(m.vendor);
+  const kept = (type: string) => resourcesOfType(m.service, storedType(m, type), root).map((r) => ownFields(r));
+  return { vendor: m.vendor, placed, consumed: { decisions: kept('_decision'), faults: kept('_fault') } };
+}
+
 export async function contextFor(m: DerivedManifest, call: DerivedCall, scope: CoreScope): Promise<SemanticsContext> {
   const root = scope.root;
   const asAsked = call;
@@ -2301,6 +2335,7 @@ export async function contextFor(m: DerivedManifest, call: DerivedCall, scope: C
     const row = context.row(link.resource, link.id);
     return row && row.deleted !== true ? row : undefined;
   };
+  const ledger = (): ScenarioLedger => ({ vendor: m.vendor, service: m.service, root, at, recording: !(scope.readOnly === true || isReadOnlyRequest(call.request)), rows: (type) => context.rowsRaw(type), record: (type, fields, id) => context.record(type, fields, id) });
   const context: SemanticsContext = {
     call,
     params,
@@ -2310,6 +2345,9 @@ export async function contextFor(m: DerivedManifest, call: DerivedCall, scope: C
     root,
     publicBase: twinPublicBase(call.request),
     scenario: scenarioDecisionOf(call.request),
+    decide: (point, subject, byDefault) => decide(ledger(), point, subject, byDefault),
+    fault: (point, subject) => faultAt(ledger(), point, subject),
+    fact: (kind, key) => fact(ledger(), kind, key),
     ask: (url, init, within) => askApplication(url, init, within, scope.application),
     worldEnv: (name) => worldEnvValue(name),
     asVendor: (fn) => runAsVendorMove(fn),
@@ -2570,6 +2608,7 @@ export async function contextFor(m: DerivedManifest, call: DerivedCall, scope: C
     batch: (fn) => fn(),
   };
   if (batchable(m, root)) bindBatch(m, call, context, params, root, at, rawRow);
+  ledgers.set(context, ledger);
   return context;
 }
 

package/src/events.ts

@@ -14,6 +14,9 @@ import { deliveryTraceHeaders } from './trace-context.ts';
 import { sendRecordedEvent } from './event-delivery.ts';
 import { getActiveWorldStore, withWorldStore, type WorldStore } from './world-store.ts';
 import { worldPaths } from './storage.ts';
+import { worldNow } from './world-clock.ts';
+import { recordFault, serviceLedger, webhookFault } from './scenario-consume.ts';
+import { durationMs } from './scenario-timeline.ts';
 
 /** How the vendor signs a delivery. */
 export type EventScheme =
@@ -390,6 +393,7 @@ export async function deliverEvents(
   transport: EventTransport = worldTransport,
   values?: (type: string) => Promise<Record<string, unknown>>,
   application?: ApplicationStandIn,
+  vendor?: string,
 ): Promise<EventDelivery[]> {
   if (write.storedType === decl.store) return [];
   const dispatch: EventTransport = application ? async (url, body, headers) => {
@@ -397,7 +401,7 @@ export async function deliverEvents(
     return answer === undefined ? transport(url, body, headers) : answer === 'unreachable' ? 0 : answer.status;
   } : transport;
   const sent: EventDelivery[] = [];
-  for (const type of eventTypesOf(decl, write.operation)) sent.push(...(await deliverEventType(service, decl, write, data, dispatch, values, type)));
+  for (const type of eventTypesOf(decl, write.operation)) sent.push(...(await deliverEventType(service, decl, write, data, dispatch, values, type, vendor)));
   return sent;
 }
 
@@ -410,6 +414,7 @@ async function deliverEventType(
   transport: EventTransport,
   values: ((type: string) => Promise<Record<string, unknown>>) | undefined,
   type: string,
+  vendor: string | undefined,
 ): Promise<EventDelivery[]> {
   const all = twinResources(service, write.root) as unknown as Array<Record<string, unknown>>;
   const kinds = Array.isArray(decl.endpoints) ? decl.endpoints : [decl.endpoints as EndpointsDecl];
@@ -474,16 +479,33 @@ async function deliverEventType(
     // kept with the write, by an id of the delivery itself (two made at once never take the same one)
     const record = decl.record ?? '_world_event_delivery';
     const id = `${record.slice(1)}_v1_${seq}`;
-    await applyTwinWrite(service, {
-      operation: `${record.slice(1)}.record`, subjectType: record, subjectId: id,
-      fields: { url, body, headers, event_type: type, sent_at: millis,
-        delivery_protocol: 1, event_id: String(filled.$id),
-        endpoint_type: kind.storedAs, endpoint_id: String(row.id),
-        delivery_state: 'queued', attempt_count: 0, current_attempt: null,
-        transport_status: null, finished_at: null, accepted_at: null,
-      }, occurredAt: write.occurredAt, actor: { kind: 'system' },
-    }, write.root);
+    const packet = { url, body, headers, event_type: type, sent_at: millis,
+      delivery_protocol: 1, event_id: String(filled.$id),
+      endpoint_type: kind.storedAs, endpoint_id: String(row.id),
+      delivery_state: 'queued', attempt_count: 0, current_attempt: null,
+      transport_status: null, finished_at: null, accepted_at: null,
+    };
+    await applyTwinWrite(service, { operation: `${record.slice(1)}.record`, subjectType: record, subjectId: id, fields: packet, occurredAt: write.occurredAt, actor: { kind: 'system' } }, write.root);
+    // a webhook fault the World's scenario placed (architecture, "Scenarios"): dropped, held until the World's clock
+    // reaches its delay (sent when the clock's mover reaches it, or by a running clock's timer: releaseHeldDeliveries),
+    // or sent twice, recorded as landed
+    const ledger = vendor ? serviceLedger({ vendor, service, root: write.root, at: write.occurredAt, recording: true }) : undefined;
+    const fault = ledger ? webhookFault(ledger, type) : undefined;
+    if (ledger && fault) await recordFault(ledger, fault, { event: type, delivery: id });
+    if (fault?.kind === 'webhook-drop' || fault?.kind === 'webhook-delay') {
+      const held = fault.kind === 'webhook-delay' ? { delivery_state: 'held', due_at: millis + durationMs(fault.by!) } : { delivery_state: 'dropped' };
+      await applyTwinWrite(service, { operation: `${record.slice(1)}.record`, subjectType: record, subjectId: id, fields: held, occurredAt: write.occurredAt, actor: { kind: 'system' } }, write.root);
+      sent.pop();
+      if (fault.kind === 'webhook-delay') heldListeners.get(worldPaths(service, write.root).root)?.();
+      continue;
+    }
     recorded.push({ type: record, id });
+    if (fault?.kind === 'webhook-duplicate') {
+      const twin = `${id}_duplicate`;
+      await applyTwinWrite(service, { operation: `${record.slice(1)}.record`, subjectType: record, subjectId: twin, fields: packet, occurredAt: write.occurredAt, actor: { kind: 'system' } }, write.root);
+      sent.push(sent.at(-1)!);
+      recorded.push({ type: record, id: twin });
+    }
   }
   // sent after the write's answer, as a vendor sends it: the caller never waits on its receiver, and a receiver that is
   // slow or down fails no request
@@ -493,6 +515,12 @@ async function deliverEventType(
   // active before it runs. Transport completion writes to the same retained state.
   const store = getActiveWorldStore(), deliveryRoot = worldPaths(service, write.root).root;
   for (const d of sent) deliveryObserver?.({ ...d, service });
+  dispatchRecorded(service, store, deliveryRoot, recorded, transport, trace);
+  return sent;
+}
+
+/** Each recorded packet sent after the write's answer, keeping its request's store and root. */
+function dispatchRecorded(service: string, store: WorldStore, deliveryRoot: string, recorded: ReadonlyArray<{ type: string; id: string }>, transport: EventTransport, trace: Record<string, string>): void {
   const roots = pendingDeliveries.get(store) ?? new Map<string, Set<Promise<void>>>();
   pendingDeliveries.set(store, roots);
   const pending = roots.get(deliveryRoot) ?? new Set<Promise<void>>();
@@ -516,5 +544,24 @@ async function deliverEventType(
       }
     }, 0);
   }
-  return sent;
+}
+
+const heldListeners = new Map<string, () => void>();
+/** Who hears that a twin held a packet for later (its pack's fetch, which sets the timer a running clock needs). */
+export function onHeldDelivery(service: string, root: string | undefined, listener: () => void): void {
+  heldListeners.set(worldPaths(service, root).root, listener);
+}
+
+/** Send what a `webhook-delay` held that the World's clock has reached, in the order it fell due, and wait until it is
+ *  sent; answer the instant the next held packet falls due, if any (ADR 0036 §4: the mover of the clock waits on it). */
+export async function releaseHeldDeliveries(service: string, root: string | undefined, record = '_world_event_delivery', transport: EventTransport = worldTransport): Promise<string | null> {
+  const now = Date.parse(worldNow());
+  const held = twinResources(service, root).filter((r) => r.type === record && r.deleted !== true && r.delivery_state === 'held').sort((a, b) => Number(a.due_at) - Number(b.due_at));
+  const due = held.filter((r) => Number(r.due_at) <= now);
+  for (const r of due) await applyTwinWrite(service, { operation: `${record.slice(1)}.release`, subjectType: record, subjectId: r.id, fields: { delivery_state: 'queued' }, occurredAt: worldNow(), actor: { kind: 'system' } }, root);
+  const deliveryRoot = worldPaths(service, root).root;
+  dispatchRecorded(service, getActiveWorldStore(), deliveryRoot, due.map((r) => ({ type: record, id: r.id })), transport, {});
+  await settleEventDeliveries(deliveryRoot);
+  const next = held.find((r) => Number(r.due_at) > now);
+  return next ? new Date(Number(next.due_at)).toISOString() : null;
 }

package/src/index.ts

@@ -100,9 +100,11 @@ export * as live from './live/index.ts';
 export * as mongodb from './mongodb/index.ts';
 export * as git from './git/index.ts';
 
-// ── the scenario grammar (architecture, "Behaviour") ───────────────────────────────────────────
-export { parseScenarioDocument, scenarioFaultResult, ScenarioEngine, ScenarioError } from './scenario.ts';
-export type { PackScenarioAdapter, ScenarioDecision, ScenarioDocument, ScenarioExtractorSpec, ScenarioFault, ScenarioFaultResult, ScenarioFeatures, ScenarioHandler, ScenarioMatcher, ScenarioMissRecord, ScenarioStatus } from './scenario.ts';
+// ── the scenario grammar (architecture, "Scenarios") ───────────────────────────────────────────
+export { scenarioFaultResult, ScenarioError } from './scenario.ts';
+export { parseScenario, resolveScenario, WORLD_SCENARIO_ENV } from './scenario-timeline.ts';
+export type { ResolvedScenario, Scenario } from './scenario-timeline.ts';
+export type { PackScenarioAdapter, ScenarioDecision, ScenarioFault, ScenarioFaultResult, ScenarioFeatures, ScenarioHandler, ScenarioMatcher, ScenarioMissRecord } from './scenario.ts';
 
 export { verifyAttestationBundle } from './attestation.ts';
 

package/src/openai-wire.ts

@@ -350,7 +350,6 @@ export function scenario(vendor: string, operations: string[], faultBody: (statu
       toolResultFor: (r, c) => nonEmpty(c) && r.results.includes(c),
       hasTool: (r, c) => nonEmpty(c) && r.tools.includes(c),
     },
-    text: (r) => r.text,
     // source: https://platform.openai.com/docs/api-reference/chat/create "none means the model will not call any tool and instead generates a message"
     admits: (r, respond) => !(r.toolsForbidden && obj(respond).toolCalls !== undefined),
     validateOn: (on) => {

package/src/pack-fetch.ts

@@ -13,11 +13,16 @@ import { ORIGINAL_PATH_HEADER } from './sigv4.ts';
 import { placedCookies, TWIN_PREFIX_HEADER } from './twin-fetch.ts';
 import { PREFIX_PARAMS_HEADER } from './derived.ts';
 import { withHeaders } from './with-headers.ts';
-import { authRefusal, bindSemantics, contextFor, LANE_HEADER, SCENARIO_DECISION_HEADER, scenarioDecisionHeader, storedType, coreFor, crossCutting, derivedRequestScopes, vendorError, type CoreScope, type DerivedManifest, type ErrorSpec, type Handler, type HandlerContext, type LanesDecl, type ScreenDecl, type VendorManifest } from './derived-core.ts';
+import { authRefusal, bindSemantics, contextFor, scenarioLedgerOf, scenarioRecords, LANE_HEADER, SCENARIO_DECISION_HEADER, scenarioDecisionHeader, storedType, coreFor, crossCutting, derivedRequestScopes, vendorError, type CoreScope, type DerivedManifest, type ErrorSpec, type Handler, type HandlerContext, type LanesDecl, type ScreenDecl, type VendorManifest } from './derived-core.ts';
 import { compileSurface, createDerivedFetch, matchOperation, pathParams, type DerivedFetch, type DerivedOperation, type DerivedOwner, type DerivedSurface, type Workspace, type BoardFrame } from './derived.ts';
 import { isReadOnlyRequest, READ_ONLY_REQUEST_HEADER, runAsVendorMove } from './request-scope.ts';
-import { parseScenarioDocument, ScenarioEngine, ScenarioError, statefulTwinManifest, twinManifest, type PackScenarioAdapter } from './scenario.ts';
-import { getActiveWorldStore } from './world-store.ts';
+import { ScenarioError, statefulTwinManifest, twinManifest, type PackScenarioAdapter, type ScenarioStatusFault } from './scenario.ts';
+import { placedOn, type PlacedFault } from './scenario-timeline.ts';
+import { rateLimited, recordFault, requestFaults, type ScenarioLedger } from './scenario-consume.ts';
+import { faultAnswer, kernelFault, serveTurn } from './scenario-serve.ts';
+import { onHeldDelivery, releaseHeldDeliveries } from './events.ts';
+import { getActiveWorldStore, withWorldStore } from './world-store.ts';
+import { noteCompleteness } from './completeness.ts';
 import { runWithCorrelationId } from './actions.ts';
 import { deferPerform, deployableEntries, performRequestGroup, RefusedWriteError, VendorWriteError } from './head.ts';
 import { FLUSH, ZERO_SHA, pktLine, readPktLines } from './git/smart-http.ts';
@@ -35,7 +40,7 @@ import { liveIngest } from './live/ingest.ts';
 import type { LiveEngine } from './live/types.ts';
 import { readResourceBlob, removeResourceBlob, writeResourceBlob } from './resource-blob.ts';
 import { gitRepositoryOf, resourcesOfType } from './derived-core.ts';
-import { worldNow } from './world-clock.ts';
+import { worldClockRunning, worldNow } from './world-clock.ts';
 import type { WebSocketUpgrade, WebSocketPeer } from './serve-http.ts';
 import { MACHINE_POOL, POOL_KINDS, resetFakePool } from './machines.ts';
 import { applyTwinWrite } from './serve.ts';
@@ -103,10 +108,9 @@ export type LanePart = {
 };
 
 /** Where a pack serves: its World's root, whether it was started read-only, the World instant when a caller pins it, the
- *  World's managed Postgres the runtime binds a pack declaring `managedDatabase` to (a handler's `ctx.engine`), and the
- *  World's scenario file for a model vendor's turns (`scenarioPath`, the runtime's `--scenario`). */
+ *  and the World's managed Postgres the runtime binds a pack declaring `managedDatabase` to (a handler's `ctx.engine`). */
 export type PackFetchOptions = {
-  root?: string; readOnly?: boolean; clock?: () => string; database?: string; scenarioPath?: string;
+  root?: string; readOnly?: boolean; clock?: () => string; database?: string;
   /** the application a walk stands in for: this fetch's requests and declared events are answered by it */
   application?: ApplicationStandIn;
 };
@@ -320,6 +324,8 @@ export function createPackFetch(parts: PackParts, options: PackFetchOptions = {}
     gap: async (request, operation) => {
       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;
@@ -343,23 +349,30 @@ export function createPackFetch(parts: PackParts, options: PackFetchOptions = {}
     if (graphql && gql && request.method === 'POST' && gql.paths.includes(new URL(request.url).pathname.replace(/\/+$/, ''))) 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: ScenarioEngine<unknown> | undefined;
-  let engineRaw: string | undefined;
-  const engineOf = (): ScenarioEngine<unknown> | undefined => {
-    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 = (): boolean => 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: ReturnType<typeof setTimeout> | undefined;
+  const due = async (): Promise<string | null> => {
+    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 as { unref?: () => void }).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 = (): void => { 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: Request): Promise<Response> => {
-    if (!parts.scenario) return api(arrived);
+    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;
     // putting the earlier read back (the served request cloned for the context, then forwarded) does not reproduce the
@@ -369,25 +382,52 @@ export function createPackFetch(parts: PackParts, options: PackFetchOptions = {}
     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)) 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;
+    if (!matched) return api(request);
+    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: PlacedFault): Promise<Response | null> => {
+      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 as ScenarioStatusFault, 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: Request, asked: unknown, ledger: ScenarioLedger): Promise<Response> => {
+    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]) throw new Error(`${m.vendor}: the manifest declares the door ${d.id}, and semantics/doors.ts exports no ${d.id}`);
   const door = worldDoorMatcher(m.doors ?? []);
@@ -540,17 +580,19 @@ export function createPackFetch(parts: PackParts, options: PackFetchOptions = {}
         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() as never } : {}),
+          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 as Record<string, unknown>), ...(identity ? { identity } : {}) }, doors: { ...(body.doors as Record<string, string>), ...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
@@ -723,7 +765,7 @@ export function createPackFetch(parts: PackParts, options: PackFetchOptions = {}
   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<WebSocketPeer, Promise<void>>();
   const upgrade: WebSocketUpgrade | undefined = rawUpgrade && m.tenant?.storage === 'namespaced' && parts.tenant ? {

package/src/runtime.ts

@@ -9,7 +9,10 @@ export { clearRegistry, getPack, hasPack, listPacks, packOf, registerPack, pullP
 export type { PackTransport, PullPosture, PullTrigger, PullVendor, RoundTripWrite, TwinPack } from './packRegistry.ts';
 // 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.ts';
+export { scenarioFaultResult, ScenarioError, statefulTwinManifest, twinManifest } from './scenario.ts';
+export { durationMs, MACHINE_LAYERS, parseScenario, resolveScenario, ScenarioTimelineError } from './scenario-timeline.ts';
+export type { ResolvedScenario, ScenarioAction, ScenarioCall, ScenarioFaultInput } from './scenario-timeline.ts';
+export { completenessMark, completenessSince, noteCompleteness, type Completeness } from './completeness.ts';
 export { WORLD_CLOCK_ENV, worldNow } from './world-clock.ts';
 export { WORLD_ENV_NAMES_ENV, worldEnvValue } from './world-env.ts';
 export { ORIGINAL_PATH_HEADER } from './sigv4.ts';
@@ -28,7 +31,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.ts';
 export type { RemoteExecute, RemoteExecuteRequest, RemoteExecuteResponse } from './remote-execute.ts';
 export type { TwinFetchAdapterConfig, TwinFetchHandlerRequest, TwinFetchHandlerResult, TwinStream, TwinStreamConnection, TwinStreamSink } from './twin-fetch.ts';
-export type { PackScenarioAdapter, ScenarioDecision, ScenarioDocument, ScenarioExtractorSpec, ScenarioFault, ScenarioFaultResult, ScenarioFeatures, ScenarioHandler, ScenarioMatcher, ScenarioMissRecord, ScenarioStatus } from './scenario.ts';
+export type { PackScenarioAdapter, ScenarioDecision, ScenarioFault, ScenarioFaultResult, ScenarioFeatures, ScenarioHandler, ScenarioMatcher, ScenarioMissRecord } from './scenario.ts';
 export { emitTwinEvent, eventSubscriptionMatches, listEmittable, runEmitCli } from './emit.ts';
 export type { EmitDeliveryResult, EmitEndpoint, EmitReport, EmittableEvent, SynthesizedDelivery, TwinEmitter } from './emit.ts';
 // The vendor-agnostic CLIENT-SIDE RATE BUDGET — the fail-closed backstop a pack's guarded client

package/src/scenario-consume.ts

@@ -0,0 +1,123 @@
+// 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.ts';
+import { applyTwinWriteAtomic, twinResources } from './serve.ts';
+import { durationMs, placedDecisions, placedFaults, worldJsonFile, type PlacedDecision, type PlacedFault } from './scenario-timeline.ts';
+
+const WORLD_FACTS_ENV = 'TWIN_WORLD_FACTS_FILE';
+
+/** 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>;
+};
+
+const simulated = (ledger: ScenarioLedger): boolean => headOf(ledger.service, ledger.root).kind !== 'real';
+const usedTimes = (ledger: ScenarioLedger, type: '_decision' | '_fault', index: number): number => ledger.rows(type).filter((r) => r.entry === index).length;
+const available = (ledger: ScenarioLedger, type: '_decision' | '_fault', index: number, limit: number | undefined): boolean => limit === undefined || usedTimes(ledger, type, index) < limit;
+const decisionLeft = (ledger: ScenarioLedger, d: PlacedDecision): boolean => available(ledger, '_decision', d.index, d.once ? 1 : undefined);
+const faultLeft = (ledger: ScenarioLedger, f: PlacedFault): boolean => 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<T>(ledger: ScenarioLedger, point: string, subject: string, byDefault: T): Promise<T> {
+  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) as T;
+  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: ScenarioLedger): PlacedDecision[] {
+  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: ScenarioLedger, chosen: PlacedDecision | undefined, outcome: unknown): Promise<void> {
+  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: ScenarioLedger): PlacedFault[] {
+  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: ScenarioLedger, fault: PlacedFault, where: Record<string, unknown>): Promise<void> {
+  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: ScenarioLedger, point: string, subject: string): Promise<PlacedFault | undefined> {
+  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: { vendor: string; service: string; root?: string; at: string; recording: boolean }): ScenarioLedger {
+  const rows = (type: string) => twinResources(input.service, input.root).filter((r) => r.type === type && r.deleted !== true) as Array<Record<string, unknown>>;
+  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: ScenarioLedger, type: string): PlacedFault | undefined {
+  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: ScenarioLedger, operation: string): PlacedFault | undefined {
+  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: Pick<ScenarioLedger, 'vendor' | 'service' | 'root' | 'at'>): PlacedFault[] {
+  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: ScenarioLedger, operation: string): Promise<PlacedFault | undefined> {
+  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: ScenarioLedger, kind: string, key: string): Promise<unknown> {
+  const value = worldJsonFile<Record<string, Record<string, unknown>>>(WORLD_FACTS_ENV)?.[kind]?.[key];
+  if (ledger.recording) await ledger.record('_fact', { kind, key, value: value ?? null, answeredAt: ledger.at });
+  return value;
+}