@volter/world-core 3.0.162 → 3.0.164

package/dist/src/browser-session.d.ts

@@ -1,7 +1,13 @@
 import type { HandlerContext } from './derived-core.js';
+import { type Person } from './people.js';
 type Writer = Pick<HandlerContext, 'record' | 'secret' | 'occurredAt'>;
-/** The named cookie, without interpreting any other vendor's cookie. */
+/** The value of the cookie `name` the request carries, as a browser sends it back. */
+export declare function cookieOf(request: Request, name: string): string | undefined;
+/** The named session cookie; malformed encodings do not name a session. */
 export declare function browserSessionToken(request: Request, name: string): string | undefined;
+/** The person the request's session cookie names, or undefined when nobody is signed in; with `scope`, only a session
+ *  begun in it (a vendor's sandbox dashboard and its production one sign a person in apart). */
+export declare function signedIn(ctx: HandlerContext, cookie: string, scope?: string): Person | undefined;
 /** A new, independent sign-in, returning the cookie the vendor places on its response. */
 export declare function startBrowserSession(ctx: Writer, email: string, cookie: string, scope?: string): Promise<string>;
 /** End the session the request holds, then clear its cookie. Unknown cookies create no rows. */

package/dist/src/browser-session.js

@@ -1,18 +1,29 @@
-/** The named cookie, without interpreting any other vendor's cookie. */
-export function browserSessionToken(request, name) {
+import { personOf } from "./people.js";
+/** The value of the cookie `name` the request carries, as a browser sends it back. */
+export function cookieOf(request, name) {
     for (const part of (request.headers.get('cookie') ?? '').split(';')) {
         const at = part.indexOf('=');
-        if (at > 0 && part.slice(0, at).trim() === name) {
-            try {
-                return decodeURIComponent(part.slice(at + 1).trim());
-            }
-            catch {
-                return undefined;
-            }
-        }
+        if (at > 0 && part.slice(0, at).trim() === name)
+            return decodeURIComponent(part.slice(at + 1).trim());
     }
     return undefined;
 }
+/** The named session cookie; malformed encodings do not name a session. */
+export function browserSessionToken(request, name) {
+    try {
+        return cookieOf(request, name);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The person the request's session cookie names, or undefined when nobody is signed in; with `scope`, only a session
+ *  begun in it (a vendor's sandbox dashboard and its production one sign a person in apart). */
+export function signedIn(ctx, cookie, scope) {
+    const token = cookieOf(ctx.call.request, cookie);
+    const session = token ? ctx.rowsRaw('_web_session').find((s) => s.token === token && (scope === undefined || s.scope === scope)) : undefined;
+    return session ? personOf(ctx, String(session.email)) : undefined;
+}
 /** A new, independent sign-in, returning the cookie the vendor places on its response. */
 export async function startBrowserSession(ctx, email, cookie, scope) {
     const issued = await ctx.record('_web_session_issue', { email, ...(scope !== undefined ? { scope } : {}) });

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

@@ -15,7 +15,7 @@ import { type MultipartPart } from './multipart.js';
 import type { CorsDecl } from './cors.js';
 import { type TwinAction } from './actions.js';
 import type { DerivedCall, DerivedCoreOutcome, DerivedHandler, DerivedOperation } from './derived.js';
-import type { PackDescriptor } from './packRegistry.js';
+import { type PackDescriptor } from './packRegistry.js';
 import type { ScenarioDecision, ScenarioHandler } from './scenario.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. */
@@ -914,13 +914,25 @@ export type CoreScope = {
     readOnly?: boolean;
     /** `semantics/tenant.ts`: the tenant the caller acts in (the manifest's `tenant`), or undefined for none */
     tenant?: (ctx: HandlerContext) => string | undefined | Promise<string | undefined>;
-    /** the application a walk stands in for: what the vendor asks it (`ctx.ask`) is answered by it (events.ts) */
+    /** the application a walk stands in for: vendor requests and declared events are answered by it (events.ts) */
     application?: ApplicationStandIn;
 };
 /** World-owned generated values use the same private seed and log as pack secrets. */
 export declare function worldSecret(service: string, root: string, label: string, at?: string): Promise<string>;
 /** The same retained account primitive for pack doors and private native twin fronts. */
 export declare function worldAccount(service: string, root: string | undefined, id?: unknown, at?: string, provisioning?: boolean): Promise<string>;
+type WorldOrganization = {
+    id: string;
+    label: string;
+    members: string[];
+};
+type VendorNameRule = {
+    max: number;
+    lower?: boolean;
+    allowed: RegExp;
+    separator?: string;
+    first?: RegExp;
+};
 /** The lane a vendor's router sent a request to (pack-fetch's laneRouter sets it). */
 export declare const LANE_HEADER = "x-volter-lane";
 /** What a coverage measurement sees of a pack's declared state logic: each move a request made and each refusal a
@@ -1018,6 +1030,27 @@ export type SemanticsContext = {
     secret(label: string): Promise<string>;
     /** Select an account at a pack's credential door. Packs retain their own vendor account/key semantics. */
     account(field?: string): Promise<string>;
+    /** The selected organization's label and people from the World's organization registry. */
+    organization(): Promise<WorldOrganization>;
+    /** The selected deployment, or an empty string for the organization's own level. */
+    deployment(): string;
+    /** A vendor-safe label; retained links keep identity independent of names. */
+    vendorName(label: string, rule: VendorNameRule, options?: {
+        suffixed?: boolean;
+        identity?: string;
+    }): string;
+    /** Retain the native customer tenant for the selected organization. */
+    tenant(resource: string, make: (organization: WorldOrganization) => Promise<string>): Promise<Record<string, unknown>>;
+    /** Retain one native resource of this kind for the selected organization and deployment. */
+    deploymentObject(kind: string, resource: string, make: (deployment: string) => Promise<string>): Promise<Record<string, unknown>>;
+    /** Reconstruct a live native key, replacing its link when the vendor's reader refuses it. */
+    accountKey(purpose: string, resource: string, key: {
+        make: () => Promise<string>;
+        read: (row: Record<string, unknown>) => Promise<string | undefined>;
+    }): Promise<{
+        id: string;
+        secret: string;
+    }>;
     /** The World's machine pool (machines.ts), as the pack's `machine-pool` door enrolled it; `none` when none was. */
     machines: MachinePool;
     /** A signing key pair for `label` (an issuer's ID tokens, a provider's JWTs, a CA's or a log's key), PEM: RSA 2048
@@ -1219,7 +1252,7 @@ export type HandlerContext = Omit<SemanticsContext, 'now' | 'core' | 'atomically
 };
 /** What a write hook reads: the writing call's context without its ways to write, so a hook that renders an event
  *  cannot write again (and run itself again). */
-export type WriteHookContext = Omit<HandlerContext, 'write' | 'batch' | 'create' | 'createUnique' | 'change' | 'issue' | 'record' | 'accumulate' | 'at' | 'over'>;
+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>;
 export declare function contextFor(m: DerivedManifest, call: DerivedCall, scope: CoreScope): Promise<SemanticsContext>;

package/dist/src/derived-core.js

@@ -37,6 +37,7 @@ import { vendorFetch } from "./vendor-call.js";
 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 { 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. */
@@ -473,6 +474,57 @@ export async function worldAccount(service, root, id = 'default', at = worldNow(
     }, root);
     return id;
 }
+function nativeAccountLink(row, field) {
+    if (!row || row.deleted === true)
+        return undefined;
+    const fields = ownFields(row);
+    const value = field === undefined ? fields : fields[field];
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return undefined;
+    const link = value;
+    return typeof link.resource === 'string' && typeof link.id === 'string' ? { resource: link.resource, id: link.id } : undefined;
+}
+const sameAccountLink = (a, b) => a?.resource === b?.resource && a?.id === b?.id;
+/** Native creation and reconstruction run outside the action lock; only the retained link is compared and written. */
+async function retainNativeAccountLink(service, root, at, call, type, id, field, resource, make, read) {
+    for (;;) {
+        const before = nativeAccountLink(resourcesOfType(service, type, root).find((row) => row.id === id), field);
+        const held = before && await read(before);
+        if (held !== undefined)
+            return held;
+        const made = { resource, id: await make() };
+        if (await read(made) === undefined)
+            throw new Error(`Credential ${type}/${id}: native ${resource}/${made.id} is unavailable after creation`);
+        const { value } = await applyTwinWriteAtomic(service, (snapshot) => {
+            const current = nativeAccountLink(snapshot.find((row) => row.type === type && row.id === id), field);
+            if (!sameAccountLink(current, before))
+                return { kind: 'skip', value: current };
+            return {
+                kind: 'write', value: made,
+                write: {
+                    operation: `${type.slice(1)}.link`, subjectType: type, subjectId: id,
+                    fields: field === undefined ? made : { name: id, [field]: made },
+                    ...provisioningInput(call), occurredAt: at, actor: { kind: 'system' },
+                },
+            };
+        }, root);
+        const linked = value && await read(value);
+        if (linked !== undefined)
+            return linked;
+    }
+}
+function vendorName(label, rule, { suffixed = false, identity = label } = {}) {
+    const allowed = new RegExp(rule.allowed.source, rule.allowed.flags.replace(/[gy]/g, ''));
+    const separator = rule.separator ?? '-';
+    if ([...separator].length !== 1 || !allowed.test(separator))
+        throw new Error('Credential name separator must be one allowed character');
+    const first = rule.first && new RegExp(rule.first.source, rule.first.flags.replace(/[gy]/g, ''));
+    let name = [...(rule.lower ? label.toLowerCase() : label)].map((letter) => allowed.test(letter) ? letter : separator).join('');
+    name = name.replace(new RegExp(`${escapeRe(separator)}+`, 'g'), separator);
+    if (first && !first.test(name[0] ?? ''))
+        name = `w${separator}${name}`;
+    return name !== label || name.length > rule.max || suffixed ? `${name.slice(0, Math.max(0, rule.max - 9))}${separator}${sha256(identity).slice(0, 8)}` : name;
+}
 /** A World's signing key for a label (ctx.signingKey): made once from the platform's random source, then read; the
  *  making is one per service store and label in the process, as the seed's is. */
 const SIGNING_KEY = '_world_signing_key';
@@ -571,9 +623,9 @@ function mintId(m, resource, root, at, snapshot) {
  *  increment. One space over every snowflake resource of the vendor, as its one generator's: the instant's first, or one
  *  past the greatest the World holds when that is later (a frozen clock, or several ids in one millisecond), so ids
  *  rise with time and never repeat. */
-/** The last snowflake minted per vendor and World in this process: two mints before the first is written (a message
+/** The last snowflake minted per store, vendor and World: two mints before the first is written (a message
  *  and its attachment) must not meet. */
-const lastSnowflake = new Map();
+const lastSnowflake = new WeakMap();
 function mintSnowflake(m, epoch, root, at, snapshot) {
     const ms = BigInt(Date.parse(at) || 0);
     const base = ms > epoch ? (ms - epoch) << 22n : 0n;
@@ -588,11 +640,13 @@ function mintSnowflake(m, epoch, root, at, snapshot) {
                     max = v;
             }
     }
+    const store = getActiveWorldStore();
+    const reservations = lastSnowflake.get(store) ?? lastSnowflake.set(store, new Map()).get(store);
     const key = `${m.service}\0${root ?? ''}`;
-    const last = lastSnowflake.get(key) ?? -1n;
+    const last = reservations.get(key) ?? -1n;
     const floor = max > last ? max : last;
     const id = base > floor ? base : floor + 1n;
-    lastSnowflake.set(key, id);
+    reservations.set(key, id);
     return String(id);
 }
 /** The next KSUID for a resource (Clerk's and Svix's ids, `ksuidFrom`): the World's instant, then the type's mint
@@ -895,7 +949,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);
+        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);
     }
     if (m.sockets?.length)
         socketWrite(m.service, root, { operation, storedType: m.resources[resource]?.storedAs ?? resource, body, ...(root !== undefined ? { root } : {}), occurredAt, request: request.clone() });
@@ -1489,6 +1543,8 @@ export async function contextFor(m, call, scope) {
     });
     const paths = expandPaths(m, params);
     const stateChecks = new Map();
+    const credentialDoor = m.descriptor?.credentialDoor ?? getPack(m.vendor)?.credentialDoor;
+    const credentialFields = body && typeof body === 'object' && !Array.isArray(body) ? body : {};
     const rawResources = new WeakMap();
     const rawRow = (resource, row) => {
         const name = m.resources[resource] ? resource : Object.keys(m.resources).find((name) => storedType(m, name) === row.type);
@@ -1502,6 +1558,10 @@ export async function contextFor(m, call, scope) {
         rawResources.set(row, name ?? resource);
         return row;
     };
+    const liveNativeRow = (link) => {
+        const row = context.row(link.resource, link.id);
+        return row && row.deleted !== true ? row : undefined;
+    };
     const context = {
         call,
         params,
@@ -1558,9 +1618,38 @@ export async function contextFor(m, call, scope) {
         },
         occurredAt: at,
         secret: async (label) => hmac(await worldSeed(m.service, root, at), scopeLabel(m, label), 'base64url'),
-        account: async (field = 'account') => {
-            const fields = body && typeof body === 'object' && !Array.isArray(body) ? body : {};
-            return worldAccount(m.service, root, fields[field] ?? 'default', at, call.request.headers.get('x-volter-world-activity') === 'provisioning');
+        account: async (field = credentialDoor?.account?.field ?? 'account') => {
+            return worldAccount(m.service, root, credentialFields[field] ?? 'default', at, call.request.headers.get('x-volter-world-activity') === 'provisioning');
+        },
+        organization: async () => {
+            const id = await context.account();
+            const row = projectOwnerResources('_world', root, { type: '_world_organization', id }).find((row) => row.type === '_world_organization' && row.id === id && row.deleted !== true);
+            return row ? { id, label: row.label, members: [...row.members] } : { id, label: id, members: ['owner@world.test'] };
+        },
+        deployment: () => {
+            const id = credentialFields[credentialDoor?.deployment?.field ?? 'deployment'] ?? '';
+            if (id !== '' && !isWorldAccountName(id))
+                throw new Error('Credential deployment must be a name of at most 128 letters, digits, dots, underscores or hyphens');
+            return id;
+        },
+        vendorName,
+        tenant: async (resource, make) => {
+            const id = await context.account();
+            return retainNativeAccountLink(m.service, root, at, call, '_world_account', id, 'tenant', resource, async () => make(await context.organization()), async (link) => liveNativeRow(link));
+        },
+        deploymentObject: async (kind, resource, make) => {
+            const organization = await context.account(), deployment = context.deployment();
+            return retainNativeAccountLink(m.service, root, at, call, '_world_deployment_object', `${organization}/${deployment}/${kind}`, undefined, resource, () => make(deployment), async (link) => liveNativeRow(link));
+        },
+        accountKey: async (purpose, resource, key) => {
+            const organization = await context.account(), deployment = context.deployment();
+            return retainNativeAccountLink(m.service, root, at, call, '_world_account_key', `${organization}/${deployment}/${purpose}`, undefined, resource, () => key.make(), async (link) => {
+                const row = liveNativeRow(link);
+                if (!row)
+                    return undefined;
+                const secret = await key.read(row);
+                return secret === undefined ? undefined : { id: link.id, secret };
+            });
         },
         record: async (type, fields, id, operation) => {
             if (!type.startsWith('_'))
@@ -1621,7 +1710,12 @@ export async function contextFor(m, call, scope) {
             const row = await atomicWrite(m, call, resource, (snapshot) => {
                 const id = options?.id ?? mintId(m, resource, root, at, snapshot);
                 const selected = typeof fields === 'function' ? fields(id) : fields;
-                const hit = snapshot.find((r) => r.type === storedType(m, resource) && r.deleted !== true && rules.some((rule) => rule.fields.every((f) => selected[f] !== undefined && view(m, resource, r)[f] === selected[f])));
+                const hit = snapshot.find((r) => {
+                    if (r.type !== storedType(m, resource) || r.deleted === true)
+                        return false;
+                    const fields = { [m.resources[resource]?.idAs ?? 'id']: r.id, ...ownFields(r) };
+                    return rules.some((rule) => rule.fields.every((field) => selected[field] !== undefined && fields[field] === selected[field]));
+                });
                 if (hit) {
                     existing = view(m, resource, hit);
                     return undefined;
@@ -1661,7 +1755,7 @@ export async function contextFor(m, call, scope) {
         },
         writeDetailed: (resource, id, fields, operation) => writeDetailed(m, call, resource, id, fields, operation, params, root, at, stateChecks),
         resolve: (resource, id) => resolveSubjectId(m.service, storedType(m, resource), id, root),
-        storedType: (resource) => storedType(m, resource),
+        storedType: (resource) => m.resources[resource]?.storedAs ?? resource,
         ok: (fields) => Response.json({ ...(m.success ?? {}), ...fields }),
         row: (resource, id, opts) => { const row = stored(m, resource, root, opts).find((r) => r.id === id); return row ? rawRow(resource, row) : undefined; },
         rowsRaw: (resource, opts) => stored(m, resource, root, opts).map((row) => rawRow(resource, row)),
@@ -1782,10 +1876,12 @@ const BATCH_REFUSED_READS = ['get', 'rows', 'tree', 'history', 'find', 'list', '
 /** The members that write, or wait on writes, or answer as another context: each lands the staged writes first. */
 const BATCH_LANDING_MEMBERS = ['create', 'createUnique', 'change', 'accumulate', 'writeDetailed', 'record', 'atomically', 'remove', 'issue', 'at', 'over', 'core', 'awaitWrite', 'awaitCondition',
     // a World's seed and signing keys are written when first asked (worldSeed, worldSigningKey, as a vendor's move)
-    'secret', 'signingKey'];
+    'secret', 'signingKey', 'account', 'organization', 'tenant', 'deploymentObject', 'accountKey'];
 /** `ctx.batch` over a context whose writes may be grouped (see `batchable`). */
 function bindBatch(m, call, context, params, root, at, rawRow) {
     let staged;
+    // A callback's native object must land before the helper writes its retained link.
+    let nativeAccountWrites = 0;
     // each staged subject as it will stand, by `type:id`, in the order first written
     const subjects = new Map();
     const land = async () => {
@@ -1801,7 +1897,19 @@ function bindBatch(m, call, context, params, root, at, rawRow) {
         const plain = ctx[name];
         if (typeof plain !== 'function')
             continue;
-        ctx[name] = async (...args) => { await land(); return plain(...args); };
+        ctx[name] = async (...args) => {
+            await land();
+            const native = name === 'tenant' || name === 'deploymentObject' || name === 'accountKey';
+            if (native)
+                nativeAccountWrites++;
+            try {
+                return await plain(...args);
+            }
+            finally {
+                if (native)
+                    nativeAccountWrites--;
+            }
+        };
     }
     for (const name of BATCH_REFUSED_READS) {
         const plain = ctx[name];
@@ -1816,7 +1924,7 @@ function bindBatch(m, call, context, params, root, at, rawRow) {
     const plainWrite = context.write, plainRow = context.row, plainRowsRaw = context.rowsRaw;
     context.write = async (resource, id, fields, operation) => {
         // a vendor's own move (ctx.asVendor) is the clock's write, recorded as the system's: it lands alone, in its place
-        if (!staged || inVendorMove()) {
+        if (!staged || nativeAccountWrites > 0 || inVendorMove()) {
             await land();
             return plainWrite(resource, id, fields, operation);
         }

package/dist/src/derived-real.js

@@ -682,10 +682,10 @@ function refreshOf(units, service) {
                         const sent = asked.length ? `${target}${target.includes('?') ? '&' : '?'}${new URLSearchParams(asked)}` : target;
                         const answer = await execute({ method: op.method.toUpperCase(), path: sentTo(m, sent, subject), ...onLane, headers: fixedHeaders(op) });
                         // a door's subject the vendor does not show the root (another bot's private chat) stays as the World holds it
-                        if (!rooted.has(key) && answer.status >= 400 && answer.status !== 429)
-                            continue;
                         if (answer.status === 401)
                             throw new Error(`401: the vendor refused the root's credential (${op.method.toUpperCase()} ${path}); nothing folded`);
+                        if (!rooted.has(key) && answer.status >= 400 && answer.status !== 429)
+                            continue;
                         if (answer.status === 403) {
                             unread.push({ type, path, status: 403 });
                             refused = true;
@@ -700,7 +700,19 @@ function refreshOf(units, service) {
                             continue;
                         if (answer.status >= 400 || refusedIn(m, parse(answer)))
                             throw new Error(`${m.vendor}: ${resource} refresh ${op.id} (${op.method.toUpperCase()} ${op.path}): ${answer.status}: ${refusalWords(m, parse(answer))}`);
-                        const full = object(op.answers?.key ? at(parse(answer), op.answers.key) : parse(answer)) ?? {};
+                        const parsed = parse(answer);
+                        let full;
+                        if (op.answers?.list) {
+                            const items = itemsOf(op, parsed);
+                            const matching = items.find((item) => (scopeIdOf(scope, item) ?? storedIdOf(decl, item)) === vendorId);
+                            if (!matching && items.length)
+                                throw new Error(`${m.vendor}: ${resource} refresh ${op.id} omitted the requested subject; nothing folded`);
+                            if (!matching)
+                                continue;
+                            full = matching;
+                        }
+                        else
+                            full = object(op.answers?.key ? at(parsed, op.answers.key) : parsed) ?? {};
                         const local = m.worldFields?.[resource] ?? {};
                         const fields = Object.fromEntries(Object.entries(full).filter(([k]) => !(k in local)));
                         if (decl.parent) {

package/dist/src/events.d.ts

@@ -164,6 +164,8 @@ export declare function eventTypeOf(decl: Pick<EventsDecl, 'types' | 'known'>, o
 /** Whether an endpoint's list of event types takes a type: every type when the list is empty, `*` or `<family>.*`
  *  its patterns, else the type itself. */
 export declare function takesEvent(list: unknown, type: string): boolean;
+/** Await already-scheduled first dispatches and consume their retained persistence failures. */
+export declare function settleEventDeliveries(root: string): Promise<void>;
 /** Who watches signed packets before dispatch (a walk reading each as its receiver would). This is not evidence of
  *  transport or acceptance. Set and restored by the walk, as its World store is; unset, nothing watches. */
 export type DeliveryObserver = (delivery: EventDelivery & {
@@ -179,13 +181,14 @@ export type ApplicationAnswer = {
     body: string;
     missed?: 'timeout' | 'unreachable';
 };
-/** Who answers what the vendor asks the application (`ctx.ask`) before the World's application route does, given to a
+/** Who answers a vendor's requests to the application before the World's application route does, given to a
  *  pack's fetch (`PackFetchOptions.application`) and belonging to that fetch alone: an answer it gives is the
  *  application's; `'unreachable'` is a question nobody answers (a walk's life, a sealed World, takes no other); undefined
  *  is a question it does not take, which goes on as any other does: the application route, the World's egress rule, the
  *  network. A walk's stand-in answers every question (its life's answers, else unreachable); a hosted World's router
  *  answers only what it can answer truthfully (WorldDoors.askInWorld) and leaves the rest. `bodyError` models a
- *  disconnect after the response headers; a caller needing the complete body receives no complete answer. */
+ *  disconnect after the response headers; a caller needing the complete body receives no complete answer, while an
+ *  event dispatch acknowledges the response status without reading its body. */
 export type ApplicationStandIn = (url: string, init: RequestInit) => Promise<{
     status: number;
     headers?: Record<string, string>;
@@ -198,4 +201,4 @@ 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>>): 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): Promise<EventDelivery[]>;

package/dist/src/events.js

@@ -7,6 +7,7 @@
 // Imports stay free of side effects: the delivery's transport (Node's http, the World's egress policy) is loaded when a
 // delivery is made, never when a browser client imports the kernel.
 import { createHash, createHmac } from 'node:crypto';
+import { resolve } from 'node:path';
 import { applyTwinWrite, applyTwinWriteAtomic, twinResources } from "./serve.js";
 import { equalSecrets as same, ksuidFrom } from "./signing.js";
 import { deliveryTraceHeaders } from "./trace-context.js";
@@ -223,6 +224,28 @@ const worldTransport = async (url, body, headers) => {
         return 0;
     }
 };
+const pendingDeliveries = new WeakMap();
+function forgetDeliveries(store, root, deliveries) {
+    const roots = pendingDeliveries.get(store), pending = roots?.get(root);
+    if (!pending)
+        return;
+    for (const delivery of deliveries)
+        pending.delete(delivery);
+    if (!pending.size)
+        roots.delete(root);
+    if (!roots.size)
+        pendingDeliveries.delete(store);
+}
+/** Await already-scheduled first dispatches and consume their retained persistence failures. */
+export async function settleEventDeliveries(root) {
+    const store = getActiveWorldStore(), path = resolve(root);
+    const deliveries = [...(pendingDeliveries.get(store)?.get(path) ?? [])];
+    const outcomes = await Promise.allSettled(deliveries);
+    forgetDeliveries(store, path, deliveries);
+    const failures = outcomes.flatMap((outcome) => outcome.status === 'rejected' ? [outcome.reason] : []);
+    if (failures.length)
+        throw new AggregateError(failures, 'Declared-event dispatch failed');
+}
 let deliveryObserver;
 export function setDeliveryObserver(observer) {
     const previous = deliveryObserver;
@@ -266,12 +289,16 @@ 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) {
+export async function deliverEvents(service, decl, write, data, transport = worldTransport, values, application) {
     if (write.storedType === decl.store)
         return [];
+    const dispatch = application ? async (url, body, headers) => {
+        const answer = await application(url, { method: 'POST', headers: { 'content-type': 'application/json', ...headers }, body });
+        return answer === undefined ? transport(url, body, headers) : answer === 'unreachable' ? 0 : answer.status;
+    } : transport;
     const sent = [];
     for (const type of eventTypesOf(decl, write.operation))
-        sent.push(...(await deliverEventType(service, decl, write, data, transport, values, type)));
+        sent.push(...(await deliverEventType(service, decl, write, data, dispatch, values, type)));
     return sent;
 }
 /** One event type a write sends: to the live endpoints that take it, stored when the vendor keeps its events. */
@@ -364,11 +391,29 @@ 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 });
-    for (const packet of recorded)
-        setTimeout(() => {
-            // Persistence failure leaves a queued/sending claim for explicit recovery;
-            // it must not fail the already-committed vendor write or cause a blind resend.
-            void withWorldStore(store, () => sendRecordedEvent(service, packet.type, packet.id, deliveryRoot, transport, trace)).catch(() => { });
+    const roots = pendingDeliveries.get(store) ?? new Map();
+    pendingDeliveries.set(store, roots);
+    const pending = roots.get(deliveryRoot) ?? new Set();
+    roots.set(deliveryRoot, pending);
+    for (const packet of recorded) {
+        let finish;
+        let fail;
+        const dispatched = new Promise((done, reject) => { finish = done; fail = reject; });
+        // Live writes return before dispatch; an explicit settlement reports persistence failures.
+        void dispatched.catch(() => { });
+        pending.add(dispatched);
+        setTimeout(async () => {
+            try {
+                await withWorldStore(store, () => sendRecordedEvent(service, packet.type, packet.id, deliveryRoot, transport, trace));
+                finish();
+                forgetDeliveries(store, deliveryRoot, [dispatched]);
+            }
+            catch (error) {
+                // Keep the rejection until explicit settlement consumes it. The queued/sending claim remains for
+                // native recovery; this must not fail the already-committed vendor write or cause a blind resend.
+                fail(error);
+            }
         }, 0);
+    }
     return sent;
 }

package/dist/src/file-response.d.ts

@@ -5,6 +5,10 @@ export declare function fileResponse(path: string, init?: ResponseInit): Respons
  * Stored bytes as a response, honouring a single `Range: bytes=` as RFC 9110 §14 has it: every satisfiable range is a
  * 206 with its Content-Range, `bytes=0-` (the whole body) included; a range that does not parse, a first-byte-pos past
  * its last-byte-pos (`bytes=5-2`) included, is ignored and the whole body is a 200; a well-formed range that starts past
- * the end (any range of an empty body) is a 416. `nosniff` stops a browser second-guessing the content type the vendor gave.
+ * the end (any range of an empty body) is a 416. Lazy sources supply inclusive ranges and stream in bounded reads.
+ * `nosniff` stops a browser second-guessing the content type the vendor gave.
  */
-export declare function bytesResponse(request: Request, bytes: Uint8Array, contentType: string, cacheControl?: string): Response;
+export declare function bytesResponse(request: Request, bytes: Uint8Array | {
+    size: number;
+    range(start: number, end: number): Promise<Uint8Array | null>;
+}, contentType: string, cacheControl?: string): Response;

package/dist/src/file-response.js

@@ -24,10 +24,11 @@ export function fileResponse(path, init) {
  * Stored bytes as a response, honouring a single `Range: bytes=` as RFC 9110 §14 has it: every satisfiable range is a
  * 206 with its Content-Range, `bytes=0-` (the whole body) included; a range that does not parse, a first-byte-pos past
  * its last-byte-pos (`bytes=5-2`) included, is ignored and the whole body is a 200; a well-formed range that starts past
- * the end (any range of an empty body) is a 416. `nosniff` stops a browser second-guessing the content type the vendor gave.
+ * the end (any range of an empty body) is a 416. Lazy sources supply inclusive ranges and stream in bounded reads.
+ * `nosniff` stops a browser second-guessing the content type the vendor gave.
  */
 export function bytesResponse(request, bytes, contentType, cacheControl = 'public, max-age=604800, immutable') {
-    const total = bytes.length;
+    const total = bytes instanceof Uint8Array ? bytes.length : bytes.size;
     const base = { 'content-type': contentType, 'x-content-type-options': 'nosniff', 'accept-ranges': 'bytes', 'cache-control': cacheControl };
     const range = /^bytes=(\d*)-(\d*)$/.exec((request.headers.get('range') ?? '').trim());
     let start = 0;
@@ -47,9 +48,32 @@ export function bytesResponse(request, bytes, contentType, cacheControl = 'publi
     // every satisfiable range is answered as one, the whole body's `bytes=0-` included: a media player (Safari's) reads a
     // 206 with its Content-Range as the server taking ranges, and a 200 as one it cannot seek in
     const partial = valid;
-    const body = bytes.slice(start, end + 1);
-    return new Response(request.method === 'HEAD' ? null : new Blob([body]), {
+    let body = null;
+    if (request.method !== 'HEAD') {
+        if (bytes instanceof Uint8Array)
+            body = new Blob([bytes.slice(start, end + 1)]);
+        else {
+            let at = start;
+            body = new ReadableStream({
+                async pull(controller) {
+                    if (at > end) {
+                        controller.close();
+                        return;
+                    }
+                    const last = Math.min(at + 8 * 1024 * 1024 - 1, end);
+                    const chunk = await bytes.range(at, last);
+                    if (!chunk) {
+                        controller.error(new Error('stored bytes are gone'));
+                        return;
+                    }
+                    controller.enqueue(chunk);
+                    at = last + 1;
+                },
+            });
+        }
+    }
+    return new Response(body, {
         status: partial ? 206 : 200,
-        headers: { ...base, 'content-length': String(body.length), ...(partial ? { 'content-range': `bytes ${start}-${end}/${total}` } : {}) },
+        headers: { ...base, 'content-length': String(end + 1 - start), ...(partial ? { 'content-range': `bytes ${start}-${end}/${total}` } : {}) },
     });
 }

package/dist/src/index.d.ts

@@ -67,6 +67,7 @@ export * as protobuf from './protobuf.js';
 export * as grpc from './grpc-wire.js';
 export { acceptH2Connection, type H2Handler, type Http1Handler } from './h2.js';
 export { placeholderPng } from './placeholder-image.js';
+export { imageDimensions, readImageHeader, readMp4Header } from './media-header.js';
 export { presignSigV4, signSigV4, verifySigV4, type SigV4Verdict } from './sigv4.js';
 export * as redis from './redis/index.js';
 export * as mysql from './mysql/index.js';
@@ -76,7 +77,7 @@ 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 { verifyAttestationBundle } from './attestation.js';
-export { browserSessionToken, startBrowserSession, endBrowserSession } from './browser-session.js';
+export { cookieOf, signedIn, browserSessionToken, startBrowserSession, endBrowserSession } from './browser-session.js';
 export { readHostPort } from './host-port.js';
 export { assertBrowserName, browserOrigin, validateBrowserState, validateBrowserStorageState, validateBrowserContext, browserAcceptLanguage, cookieMatchesHost, type BrowserCookie, type BrowserState, type BrowserStorageState, type BrowserContext, type BrowserIndexedDB } from './browser-state.js';
 export * as managedOriginalInputs from './managed-original-inputs.js';

package/dist/src/index.js

@@ -59,6 +59,7 @@ export * as protobuf from "./protobuf.js";
 export * as grpc from "./grpc-wire.js";
 export { acceptH2Connection } from "./h2.js";
 export { placeholderPng } from "./placeholder-image.js";
+export { imageDimensions, readImageHeader, readMp4Header } from "./media-header.js";
 export { presignSigV4, signSigV4, verifySigV4 } from "./sigv4.js";
 export * as redis from "./redis/index.js";
 export * as mysql from "./mysql/index.js";
@@ -68,7 +69,7 @@ export * as git from "./git/index.js";
 // ── the scenario grammar (architecture, "Behaviour") ───────────────────────────────────────────
 export { parseScenarioDocument, scenarioFaultResult, ScenarioEngine, ScenarioError } from "./scenario.js";
 export { verifyAttestationBundle } from "./attestation.js";
-export { browserSessionToken, startBrowserSession, endBrowserSession } from "./browser-session.js";
+export { cookieOf, signedIn, browserSessionToken, startBrowserSession, endBrowserSession } from "./browser-session.js";
 export { readHostPort } from "./host-port.js";
 export { assertBrowserName, browserOrigin, validateBrowserState, validateBrowserStorageState, validateBrowserContext, browserAcceptLanguage, cookieMatchesHost } from "./browser-state.js";
 export * as managedOriginalInputs from "./managed-original-inputs.js";