@volter/world-core 3.0.166 → 3.0.167

package/dist/src/changeset.d.ts

@@ -21,6 +21,9 @@ export type LedgerPosition = {
     stateService: string;
     count: number;
     lastActionId: string | null;
+    /** the twin's history view and its position in it: what a branch at this mark starts from (ADR 0036 §5) */
+    view?: string;
+    position?: number;
 };
 export declare const MARKER_KIND = "volter.world.marker.v1";
 export declare const CHANGESET_KIND = "volter.world.changeset.v1";
@@ -33,6 +36,10 @@ export type WorldMarker = {
     /** Every ledger that existed at capture time. A ledger absent here is treated as position 0
      *  (a twin that recorded its first action AFTER the mark contributes its whole ledger). */
     ledgers: LedgerPosition[];
+    /** the World clock's instant at the mark, or null when it ran on the machine's time (a run's position, ADR 0036 §5) */
+    clock?: string | null;
+    /** whether the machine's fault door took the app's disk with the mark */
+    disk?: boolean;
 };
 /** The id reserved for the synthetic "everything this world has ever recorded" base. */
 export declare const WORLD_BOOT_MARKER_ID = "world-boot";
@@ -176,6 +183,8 @@ export declare function captureMarker(opts: {
     world: string;
     ledgers: LedgerRef[];
     createdAt?: string;
+    clock?: string | null;
+    disk?: boolean;
 }): WorldMarker;
 /** A marker taken in world A says nothing about world B's ledgers — comparing them would
  *  produce a confident, wrong delta. Refuse. */

package/dist/src/changeset.js

@@ -1,7 +1,7 @@
 import { parseExactJson } from "./exact-json.js";
 import { resolveReferences } from "./references.js";
 import { withHistoryLocks } from "./ancestry.js";
-import { captureParentHistory, historyChanges, historyEntries, historyPrefix, readHistoryView } from "./history.js";
+import { captureHistory, captureParentHistory, historyChanges, historyEntries, historyPrefix, readHistoryView } from "./history.js";
 import { worldPaths } from "./storage.js";
 // The changeset primitive — "commit" for operational reality (docs/concepts/the-model.md, v0).
 //
@@ -84,14 +84,17 @@ export function worldBootMarker(world, createdAt) {
 export function captureMarker(opts) {
     const ledgers = opts.ledgers.map((ledger) => {
         const rows = listActions(ledger.stateService, ledger.controlRoot);
+        const { view, position } = captureHistory(ledger.stateService, ledger.controlRoot);
         return {
             service: ledger.service,
             stateService: ledger.stateService,
             count: rows.length,
             lastActionId: rows.length ? rows[rows.length - 1].id : null,
+            view,
+            position,
         };
     });
-    return { kind: MARKER_KIND, id: opts.id, world: opts.world, createdAt: opts.createdAt ?? new Date().toISOString(), ledgers };
+    return { kind: MARKER_KIND, id: opts.id, world: opts.world, createdAt: opts.createdAt ?? new Date().toISOString(), ledgers, ...(opts.clock !== undefined ? { clock: opts.clock } : {}), ...(opts.disk ? { disk: true } : {}) };
 }
 function positionKey(service, stateService) {
     return `${service}\u0000${stateService}`;

package/dist/src/completeness.d.ts

@@ -0,0 +1,36 @@
+/** What a relay or a twin notes; the World's time is added as it is appended. */
+type CompletenessNote = {
+    kind: 'egress';
+    destination: string;
+    outcome: 'refused' | 'passed';
+    rule?: string;
+} | {
+    kind: 'unimplemented';
+    vendor: string;
+    method: string;
+    path: string;
+    operation?: string;
+} | {
+    kind: 'machine';
+    layer: string;
+    fault: string;
+    target?: string;
+};
+/** Append one record to the World's completeness file named in `env`; a process outside a World notes nothing. */
+export declare function noteCompleteness(env: Record<string, string | undefined>, record: CompletenessNote): void;
+export type Completeness = {
+    /** zero when the World was the whole internet the run reached */
+    total: number;
+    egress: Record<string, {
+        refused: number;
+        passed: number;
+    }>;
+    unimplemented: Record<string, Record<string, number>>;
+    /** machine faults the run placed and no fault door carried, by layer and kind (ADR 0036 §4) */
+    machine: Record<string, number>;
+};
+/** How many records the completeness file holds: where a run starts counting. */
+export declare function completenessMark(file: string): number;
+/** What reached past the World after the file's `mark`, counted per destination and per vendor's operation. */
+export declare function completenessSince(file: string, mark: number): Completeness;
+export {};

package/dist/src/completeness.js

@@ -0,0 +1,46 @@
+// A run's completeness (ADR 0036 §9; architecture, "Scenarios"): the World is the application's internet closure, so
+// what reached past it is what the World is missing. The relay notes every destination no twin serves (refused, or
+// passed to the real internet where the World lets it), a twin every request to an operation it does not implement
+// (answered as the vendor answers an unknown request), and a run every machine fault no fault door carried. All are
+// appended, at World time, to the instance's completeness file (TWIN_WORLD_COMPLETENESS_FILE), and a run counts them.
+import { getActiveWorldStore } from "./world-store.js";
+import clockForm from '../world-clock.cjs';
+const WORLD_COMPLETENESS_ENV = 'TWIN_WORLD_COMPLETENESS_FILE';
+/** The World's time in `env` (its clock file's, else the machine's). */
+function worldTimeIn(env) {
+    const file = env.TWIN_WORLD_CLOCK_FILE;
+    const held = file ? getActiveWorldStore().read(file) : null;
+    return new Date(held ? clockForm.clockNowMs(clockForm.parseClock(held), Date.now()) : Date.now()).toISOString();
+}
+/** Append one record to the World's completeness file named in `env`; a process outside a World notes nothing. */
+export function noteCompleteness(env, record) {
+    const file = env[WORLD_COMPLETENESS_ENV];
+    if (!file)
+        return;
+    try {
+        getActiveWorldStore().append(file, `${JSON.stringify({ at: worldTimeIn(env), ...record })}\n`);
+    }
+    catch { /* the answer still goes out */ }
+}
+/** How many records the completeness file holds: where a run starts counting. */
+export function completenessMark(file) {
+    return (getActiveWorldStore().read(file) ?? '').split('\n').filter((line) => line.trim()).length;
+}
+/** What reached past the World after the file's `mark`, counted per destination and per vendor's operation. */
+export function completenessSince(file, mark) {
+    const out = { total: 0, egress: {}, unimplemented: {}, machine: {} };
+    for (const line of (getActiveWorldStore().read(file) ?? '').split('\n').filter((l) => l.trim()).slice(mark)) {
+        const r = JSON.parse(line);
+        out.total += 1;
+        if (r.kind === 'egress')
+            (out.egress[r.destination] ??= { refused: 0, passed: 0 })[r.outcome] += 1;
+        else if (r.kind === 'machine')
+            out.machine[`${r.layer} ${r.fault}`] = (out.machine[`${r.layer} ${r.fault}`] ?? 0) + 1;
+        else {
+            const ops = out.unimplemented[r.vendor] ??= {};
+            const key = r.operation ?? `${r.method} ${r.path}`;
+            ops[key] = (ops[key] ?? 0) + 1;
+        }
+    }
+    return out;
+}

package/dist/src/derived-core.d.ts

@@ -17,6 +17,7 @@ import { type TwinAction } from './actions.js';
 import type { DerivedCall, DerivedCoreOutcome, DerivedHandler, DerivedOperation } from './derived.js';
 import { type PackDescriptor } from './packRegistry.js';
 import type { ScenarioDecision, ScenarioHandler } from './scenario.js';
+import { type ScenarioLedger } from './scenario-consume.js';
 /** How a stored field gets its value when the server assigns it. `now` is the world clock in the
  *  manifest's time format; `id` the subject's id; a `value` is stored as given. */
 /** A field the server assigns: the World clock's now, the subject's id, a fixed value, or a template over the stored
@@ -1018,6 +1019,21 @@ 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>;
@@ -1295,6 +1311,17 @@ export type HandlerContext = Omit<SemanticsContext, 'now' | 'core' | 'atomically
 export type WriteHookContext = Omit<HandlerContext, 'write' | 'batch' | 'create' | 'createUnique' | 'change' | 'issue' | 'record' | 'accumulate' | 'tenant' | 'deploymentObject' | 'accountKey' | 'at' | 'over'>;
 /** A derived pack's handler: one operation, by its operationId, over the contract's context. */
 export type Handler = (ctx: HandlerContext) => Promise<Response>;
+/** What a context consumes the World's scenario through (scenario-consume.ts): its twin's bookkeeping, at its time. */
+export declare function scenarioLedgerOf(ctx: object): ScenarioLedger;
+/** `GET /twin/scenario`: what the World's scenario placed on this vendor, and what the twin consumed of it. */
+export declare function scenarioRecords(m: DerivedManifest, root?: string): {
+    vendor: string;
+    placed: unknown[];
+    consumed: {
+        decisions: unknown[];
+        faults: unknown[];
+    };
+};
 export declare function contextFor(m: DerivedManifest, call: DerivedCall, scope: CoreScope): Promise<SemanticsContext>;
 /** A pack's semantics handlers as the dispatch's handlers. */
 export declare function bindSemantics(m: DerivedManifest, handlers: Record<string, Semantics>, scope?: CoreScope): Record<string, DerivedHandler>;

package/dist/src/derived-core.js

@@ -38,6 +38,8 @@ import { packReferences } from "./references.js";
 import { twinPublicBase, withRequestScopes } from "./twin-fetch.js";
 import { inVendorMove, isReadOnlyRequest, runAsVendorMove, writesRefused } from "./request-scope.js";
 import { getPack } from "./packRegistry.js";
+import { decide, fact, faultAt, listLag, recordFault, serviceLedger } from "./scenario-consume.js";
+import { durationMs, placedOn } from "./scenario-timeline.js";
 import { bodyTextOf, checkJsonBody, takeParsedBody } from "./derived.js";
 /** What a move to `to` stores in the field: a boolean field's value is a boolean, and a derived field's
  *  value is written by the move's effects (a state name is not a timestamp), so it stores nothing itself. */
@@ -998,7 +1000,7 @@ async function finishWrite(m, call, resource, row, result, operation, params, ro
         const endpoint = (kind) => ({ ...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() });
@@ -1439,7 +1441,15 @@ export async function serveCore(m, call, scope = {}) {
         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) => !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) };
@@ -1542,6 +1552,20 @@ const coreReadsBody = (type) => {
     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();
+/** What a context consumes the World's scenario through (scenario-consume.ts): its twin's bookkeeping, at its time. */
+export function scenarioLedgerOf(ctx) {
+    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, root) {
+    const placed = placedOn(m.vendor);
+    const kept = (type) => 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, call, scope) {
     const root = scope.root;
     const asAsked = call;
@@ -1611,6 +1635,7 @@ export async function contextFor(m, call, scope) {
         const row = context.row(link.resource, link.id);
         return row && row.deleted !== true ? row : undefined;
     };
+    const ledger = () => ({ 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 = {
         call,
         params,
@@ -1620,6 +1645,9 @@ export async function contextFor(m, call, scope) {
         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),
@@ -1903,6 +1931,7 @@ export async function contextFor(m, call, scope) {
     };
     if (batchable(m, root))
         bindBatch(m, call, context, params, root, at, rawRow);
+    ledgers.set(context, ledger);
     return context;
 }
 /**

package/dist/src/events.d.ts

@@ -201,4 +201,9 @@ export type ApplicationStandIn = (url: string, init: RequestInit) => Promise<{
 export declare function askApplication(url: string, init: RequestInit, within: number, standIn?: ApplicationStandIn): Promise<ApplicationAnswer>;
 /** Every event a write sends, rendered, stored when the vendor keeps its events, signed, delivered to each endpoint
  *  that takes it, and recorded. */
-export declare function deliverEvents(service: string, decl: EventsDecl, write: EventWrite, data: (type: string) => Promise<Record<string, unknown>>, transport?: EventTransport, values?: (type: string) => Promise<Record<string, unknown>>, application?: ApplicationStandIn): Promise<EventDelivery[]>;
+export declare function deliverEvents(service: string, decl: EventsDecl, write: EventWrite, data: (type: string) => Promise<Record<string, unknown>>, transport?: EventTransport, values?: (type: string) => Promise<Record<string, unknown>>, application?: ApplicationStandIn, vendor?: string): Promise<EventDelivery[]>;
+/** Who hears that a twin held a packet for later (its pack's fetch, which sets the timer a running clock needs). */
+export declare function onHeldDelivery(service: string, root: string | undefined, listener: () => void): void;
+/** 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 declare function releaseHeldDeliveries(service: string, root: string | undefined, record?: string, transport?: EventTransport): Promise<string | null>;

package/dist/src/events.js

@@ -14,6 +14,9 @@ import { deliveryTraceHeaders } from "./trace-context.js";
 import { sendRecordedEvent } from "./event-delivery.js";
 import { getActiveWorldStore, withWorldStore } from "./world-store.js";
 import { worldPaths } from "./storage.js";
+import { worldNow } from "./world-clock.js";
+import { recordFault, serviceLedger, webhookFault } from "./scenario-consume.js";
+import { durationMs } from "./scenario-timeline.js";
 /** Whether an endpoint takes an event by its `match`: every field of one match (any, when several) equal to the event's
  *  value, or, a list, holding it. */
 function matches(row, match, filled) {
@@ -289,7 +292,7 @@ export async function askApplication(url, init, within, standIn) {
 }
 /** Every event a write sends, rendered, stored when the vendor keeps its events, signed, delivered to each endpoint
  *  that takes it, and recorded. */
-export async function deliverEvents(service, decl, write, data, transport = worldTransport, values, application) {
+export async function deliverEvents(service, decl, write, data, transport = worldTransport, values, application, vendor) {
     if (write.storedType === decl.store)
         return [];
     const dispatch = application ? async (url, body, headers) => {
@@ -298,11 +301,11 @@ export async function deliverEvents(service, decl, write, data, transport = worl
     } : transport;
     const sent = [];
     for (const type of eventTypesOf(decl, write.operation))
-        sent.push(...(await deliverEventType(service, decl, write, data, dispatch, values, type)));
+        sent.push(...(await deliverEventType(service, decl, write, data, dispatch, values, type, vendor)));
     return sent;
 }
 /** One event type a write sends: to the live endpoints that take it, stored when the vendor keeps its events. */
-async function deliverEventType(service, decl, write, data, transport, values, type) {
+async function deliverEventType(service, decl, write, data, transport, values, type, vendor) {
     const all = twinResources(service, write.root);
     const kinds = Array.isArray(decl.endpoints) ? decl.endpoints : [decl.endpoints];
     // an endpoint's row with its joined rows under their names (`app.hook_url` reads the installation's App)
@@ -371,16 +374,35 @@ async function deliverEventType(service, decl, write, data, transport, values, t
         // 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
@@ -391,6 +413,11 @@ async function deliverEventType(service, decl, write, data, transport, values, t
     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, store, deliveryRoot, recorded, transport, trace) {
     const roots = pendingDeliveries.get(store) ?? new Map();
     pendingDeliveries.set(store, roots);
     const pending = roots.get(deliveryRoot) ?? new Set();
@@ -415,5 +442,23 @@ async function deliverEventType(service, decl, write, data, transport, values, t
             }
         }, 0);
     }
-    return sent;
+}
+const heldListeners = new Map();
+/** 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, root, listener) {
+    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, root, record = '_world_event_delivery', transport = worldTransport) {
+    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/dist/src/index.d.ts

@@ -76,8 +76,10 @@ export * as mysql from './mysql/index.js';
 export * as live from './live/index.js';
 export * as mongodb from './mongodb/index.js';
 export * as git from './git/index.js';
-export { parseScenarioDocument, scenarioFaultResult, ScenarioEngine, ScenarioError } from './scenario.js';
-export type { PackScenarioAdapter, ScenarioDecision, ScenarioDocument, ScenarioExtractorSpec, ScenarioFault, ScenarioFaultResult, ScenarioFeatures, ScenarioHandler, ScenarioMatcher, ScenarioMissRecord, ScenarioStatus } from './scenario.js';
+export { scenarioFaultResult, ScenarioError } from './scenario.js';
+export { parseScenario, resolveScenario, WORLD_SCENARIO_ENV } from './scenario-timeline.js';
+export type { ResolvedScenario, Scenario } from './scenario-timeline.js';
+export type { PackScenarioAdapter, ScenarioDecision, ScenarioFault, ScenarioFaultResult, ScenarioFeatures, ScenarioHandler, ScenarioMatcher, ScenarioMissRecord } from './scenario.js';
 export { verifyAttestationBundle } from './attestation.js';
 export { cookieOf, signedIn, browserSessionToken, startBrowserSession, endBrowserSession } from './browser-session.js';
 export { readHostPort } from './host-port.js';

package/dist/src/index.js

@@ -69,8 +69,9 @@ export * as mysql from "./mysql/index.js";
 export * as live from "./live/index.js";
 export * as mongodb from "./mongodb/index.js";
 export * as git from "./git/index.js";
-// ── the scenario grammar (architecture, "Behaviour") ───────────────────────────────────────────
-export { parseScenarioDocument, scenarioFaultResult, ScenarioEngine, ScenarioError } from "./scenario.js";
+// ── the scenario grammar (architecture, "Scenarios") ───────────────────────────────────────────
+export { scenarioFaultResult, ScenarioError } from "./scenario.js";
+export { parseScenario, resolveScenario, WORLD_SCENARIO_ENV } from "./scenario-timeline.js";
 export { verifyAttestationBundle } from "./attestation.js";
 export { cookieOf, signedIn, browserSessionToken, startBrowserSession, endBrowserSession } from "./browser-session.js";
 export { readHostPort } from "./host-port.js";

package/dist/src/openai-wire.js

@@ -303,7 +303,6 @@ export function scenario(vendor, operations, faultBody, readers = {}) {
             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/dist/src/pack-fetch.d.ts

@@ -75,14 +75,12 @@ 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;
     /** the application a walk stands in for: this fetch's requests and declared events are answered by it */
     application?: ApplicationStandIn;
 };