@volter/world-core 3.0.38 → 3.0.39

package/dist/src/derived.d.ts

@@ -41,13 +41,20 @@ export type DerivedOperation = {
         name: string;
         type: string;
         required?: boolean;
-        minimum?: number;
-        maximum?: number;
+        minimum?: number | string;
+        maximum?: number | string;
     }>;
 };
 /** `basePath` is what the vendor's server URL puts before every operation path; `spanning` names the
  *  path parameters whose values may hold slashes (a git ref, a file path), which no spec says. */
 export type DerivedSurface = {
+    graphql?: {
+        sdl: string;
+    };
+    format?: string;
+    commands?: ReadonlyArray<{
+        id: string;
+    }>;
     version: string;
     basePath?: string;
     spanning?: ReadonlyArray<string>;
@@ -102,6 +109,10 @@ export declare function matchOperation(routes: Map<string, Route[]>, method: str
     operation: DerivedOperation;
     params: Record<string, string>;
 } | undefined;
+/** The path's template parameters for a request no operation matches (a CORS preflight, a method the path is not
+ *  served by): read from the most literal route of any method whose path the request's path fits, discriminators
+ *  aside, so `around` and `gap` know the resource the URL names without parsing it (S3's OPTIONS on `/{Bucket}/{Key+}`). */
+export declare function pathParams(routes: Map<string, Route[]>, pathname: string): Record<string, string>;
 export type DerivedOwner = 'handler' | 'core' | 'gap';
 /** The header the kernel carries a path prefix's named groups in, from routing to the call (never a client's). */
 export declare const PREFIX_PARAMS_HEADER = "x-volter-path-prefix-params";
@@ -109,8 +120,13 @@ export type DerivedFetch = ((request: Request) => Promise<Response>) & {
     /** Per operationId, who serves it: a semantics handler, the derived core, the pack's existing
      *  fetch while it moves, or nothing (the vendor's gap). */
     owners(): Record<string, DerivedOwner>;
+    /** A vendor's owners by unit: its own API's under `''`, each lane's under the lane's name, each keyed by the unit's own
+     *  operation ids (an id two units share is two operations, each served or the gap on its own). `owners()` is this map
+     *  flat, a lane's ids written `<lane>:<id>`. A fetch with no lanes may leave it out: its one unit is `owners()`. */
+    ownersByUnit?(): Record<string, Record<string, DerivedOwner>>;
     /** The vendor's sockets (sockets.ts), for the serve seam to upgrade to, when its manifest declares any. */
     upgrade?: WebSocketUpgrade;
+    maxRequestBodySize?: number;
     /** The workspace screens it draws, its lanes' too (`GET /twin`'s `screens`). */
     workspaces?(): Workspace[];
     /** Whether it lays out frames of the World's board (`semantics/board.ts`). */

package/dist/src/derived.js

@@ -1,3 +1,4 @@
+import { parseExactJson } from "./exact-json.js";
 import { runWithRequestTrace } from "./trace-context.js";
 /**
  * A request's body as text, read once per request: the dispatch reads it and tags the request with it, and every clone
@@ -29,7 +30,7 @@ export async function checkJsonBody(request) {
     if (!(request.headers.get('content-type') ?? '').includes('json') && !/^\s*[[{]/.test(text))
         return true;
     try {
-        const value = JSON.parse(text);
+        const value = parseExactJson(text);
         const tag = request[BODY_TEXT] !== undefined ? BODY_PARSE_KEY.get(request) : undefined;
         if (tag)
             BODY_PARSED.set(tag, { value });
@@ -123,6 +124,24 @@ export function matchOperation(routes, method, pathname, query, headers) {
     }
     return undefined;
 }
+/** The path's template parameters for a request no operation matches (a CORS preflight, a method the path is not
+ *  served by): read from the most literal route of any method whose path the request's path fits, discriminators
+ *  aside, so `around` and `gap` know the resource the URL names without parsing it (S3's OPTIONS on `/{Bucket}/{Key+}`). */
+export function pathParams(routes, pathname) {
+    const fits = [...routes.values()].flat().filter((r) => r.pattern.test(pathname)).sort((a, b) => b.literals - a.literals || b.names.length - a.names.length);
+    const route = fits[0];
+    const m = route?.pattern.exec(pathname);
+    if (!route || !m)
+        return {};
+    const params = {};
+    try {
+        route.names.forEach((name, i) => { params[name] = decodeURIComponent(m[i + 1]); });
+    }
+    catch {
+        return {};
+    }
+    return params;
+}
 /** The header the kernel carries a path prefix's named groups in, from routing to the call (never a client's). */
 export const PREFIX_PARAMS_HEADER = 'x-volter-path-prefix-params';
 export function createDerivedFetch(options) {
@@ -147,7 +166,7 @@ export function createDerivedFetch(options) {
             tagBody(request, await request.clone().text());
         // the path prefix's named groups (pack-fetch.ts, `pathPrefix`) are the call's parameters too
         const prefixed = request.headers.get(PREFIX_PARAMS_HEADER);
-        const call = { request, operation: matched.operation, params: prefixed ? { ...JSON.parse(prefixed), ...matched.params } : matched.params };
+        const call = { request, operation: matched.operation, params: prefixed ? { ...parseExactJson(prefixed), ...matched.params } : matched.params };
         const around = options.around ?? ((_c, next) => next());
         const handler = handlers[matched.operation.id];
         if (handler)

package/dist/src/events.d.ts

@@ -1,20 +1,28 @@
 /** How the vendor signs a delivery. */
 export type EventScheme = 
+/** One header carrying the destination's secret as it is, no signature over the body (Cloudflare Notifications'
+ *  `cf-webhook-auth`, the secret a webhook destination was made with). */
+{
+    kind: 'secret';
+    header: string;
+}
 /** A message id, a timestamp and a signature header (the Standard Webhooks shape): `<prefix>-id`,
  *  `<prefix>-timestamp` (seconds) and `<prefix>-signature: v1,<base64 HMAC-SHA256>` over `${id}.${timestamp}.${body}`,
  *  keyed by the base64 part of the secret after `secretPrefix`, or by the secret's own UTF-8 bytes (`secretKey: 'utf8'`:
  *  Polar's, whose SDK base64-encodes the secret as it is before verifying). */
-{
+ | {
     kind: 'webhook-id';
     prefix: string;
     secretPrefix?: string;
     secretKey?: 'base64' | 'utf8';
 }
 /** One header of a timestamp and its signatures: `<header>: t=<seconds>,v1=<hex HMAC-SHA256>` over `${t}.${body}`,
- *  keyed by the secret as it is. */
+ *  keyed by the secret as it is; `version` names the signature's key when the vendor's is not `v1` (ElevenLabs'
+ *  `ElevenLabs-Signature: t=…,v0=…`). */
  | {
     kind: 'timestamp-v1';
     header: string;
+    version?: string;
 }
 /** One HMAC header over the body (`X-Hub-Signature-256: sha256=<hex>`, GitHub's), or over `${timestamp}.${body}` when
  *  the vendor sends its timestamp in `timestampHeader`; `signed` names what is signed otherwise, `{t}` the timestamp
@@ -28,15 +36,15 @@ export type EventScheme =
     timestampHeader?: string;
     signed?: string;
     algorithm?: 'sha1' | 'sha256';
-    secretKey?: 'base64' | 'utf8';
 }
 /** One header of a plain hash (not an HMAC) of the secret and the body (HubSpot's v1 `X-HubSpot-Signature`: the SHA-256
- *  of the app's client secret followed by the request body); `signed` names the input, `{secret}` and `{body}` */
+ *  of the app's client secret followed by the request body); `signed` names the input, `{secret}` and `{body}`;
+ *  `base64-unpadded` is base64 with its trailing `=` removed (E2B's `e2b-signature`) */
  | {
     kind: 'hash';
     header: string;
     signed: string;
-    encoding: 'hex' | 'base64';
+    encoding: 'hex' | 'base64' | 'base64-unpadded';
     algorithm?: 'sha256';
 };
 /** Where the World's endpoints of one kind are kept (a door the vendor's dashboard stands in for writes them): their
@@ -79,34 +87,6 @@ export type EndpointsDecl = {
      *  when a message mentions it, and every `message` its subscription names). */
     types?: ReadonlyArray<string>;
     skip?: ReadonlyArray<string>;
-    /** What each delivery's answer writes on the endpoint, when the vendor keeps score (Daily's webhook): a success (2xx)
-     *  resets `failures` and writes `success` (templates: `$time.iso`, `$time.s`), a failure adds one to `failures`, and
-     *  `after` failures in a row make `move`, the vendor's transition of a state field, asked of the endpoint's machine,
-     *  on every endpoint but one matching `unless` (Daily's `exponential` retry never breaks). */
-    outcome?: EndpointOutcome;
-};
-/** An endpoint kind's delivery outcome (EndpointsDecl.outcome). */
-export type EndpointOutcome = {
-    failures: string;
-    success?: Record<string, string>;
-    after?: number;
-    move?: {
-        field: string;
-        to: string;
-        operation: string;
-    };
-    unless?: {
-        field: string;
-        equals: unknown;
-    };
-};
-/** A delivery's answer as the kernel reads it: the endpoint kind and row it went to, and the receiver's status (0 when
- *  the World refused it or nothing answered). */
-export type DeliveryAnswer = {
-    kind: EndpointsDecl;
-    row: Record<string, unknown>;
-    status: number;
-    occurredAt: string;
 };
 /** The events a pack's writes send. */
 export type EventsDecl = {
@@ -132,10 +112,6 @@ export type EventsDecl = {
     endpoints: EndpointsDecl | ReadonlyArray<EndpointsDecl>;
     /** The bookkeeping type each delivery is kept as (`_webhook_message`): what a World reads to see what was sent. */
     record?: string;
-    /** The bookkeeping type a World states its receivers' answers in (`{url, status}`, Daily's `_receiver`), for receivers
-     *  it runs no server for: a delivery whose URL starts with a stated `url` (the longest) is answered that status, and
-     *  nothing is sent. */
-    receivers?: string;
 };
 /** An event's further envelope values (`$`-named) the pack computes for a write, from the vendor's own state (the
  *  connected account it is about, the API version it is rendered in): the pack's `semantics/events.ts` `values`. A
@@ -187,14 +163,18 @@ 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;
-/** A message a vendor sends the application's own server that is no declared event (Google Calendar's push notification:
- *  a bodiless POST with its X-Goog headers), over the same transport: the receiver's status, or 0 when the World lets
- *  no request out to it or it cannot be reached. The vendor waits on it, as the sender of such a message does. */
-export declare function deliverToApplication(url: string, init: RequestInit): Promise<number>;
-/** What the application's server answered a message the vendor waits on, or why it did not answer: `missed` when the
- *  World let no request out to it or it could not be reached (`unreachable`), or it did not answer in time (`timeout`). */
+/** Who watches what the World sends (a walk reading each delivery as its receiver would): told of every delivery as it
+ *  is made, before its transport. Set and restored by the walk, as its World store is; unset, nothing watches. */
+export type DeliveryObserver = (delivery: EventDelivery & {
+    service: string;
+}) => void;
+export declare function setDeliveryObserver(observer: DeliveryObserver | undefined): DeliveryObserver | undefined;
+/** What the application's server answered a message the vendor waits on (its status, its headers by lower-cased name,
+ *  its body), or why it did not answer: `missed` when the World let no request out to it or it could not be reached
+ *  (`unreachable`), or it did not answer in time (`timeout`). */
 export type ApplicationAnswer = {
     status: number;
+    headers: Record<string, string>;
     body: string;
     missed?: 'timeout' | 'unreachable';
 };
@@ -203,10 +183,13 @@ export type ApplicationAnswer = {
  *  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. */
+ *  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. */
 export type ApplicationStandIn = (url: string, init: RequestInit) => Promise<{
     status: number;
+    headers?: Record<string, string>;
     body: string;
+    bodyError?: string;
 } | 'unreachable' | undefined>;
 /** A message the vendor sends the application's server and decides by its answer (Stripe's real-time authorization
  *  request, answered within its window): over the same transport, waited on for at most `within` milliseconds, the
@@ -214,4 +197,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>>, onAnswer?: (answer: DeliveryAnswer) => Promise<void>): 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>>): Promise<EventDelivery[]>;

package/dist/src/events.js

@@ -8,7 +8,7 @@
 // delivery is made, never when a browser client imports the kernel.
 import { createHash, createHmac } from 'node:crypto';
 import { applyTwinWrite, twinResources } from "./serve.js";
-import { equalSecrets as same } from "./signing.js";
+import { equalSecrets as same, ksuidFrom } from "./signing.js";
 import { deliveryTraceHeaders } from "./trace-context.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. */
@@ -33,23 +33,28 @@ const webhookKey = (scheme, secret) => scheme.secretKey === 'utf8' ? Buffer.from
  *  made before this one, so a receiver that deduplicates by id drops neither. */
 export function signEvent(scheme, secret, body, seconds, url, seq = 0) {
     if (scheme.kind === 'webhook-id') {
-        const id = `msg_twin_${digest(`${url}|${seconds}|${seq}|${body}`).slice(0, 24)}`;
+        // Svix's `msg_` and a KSUID (its ids' form), derived from the delivery itself
+        const id = `msg_${ksuidFrom(seconds, seq, `${url}|${seconds}|${seq}|${body}`)}`;
         const p = scheme.prefix.toLowerCase();
         const signature = createHmac('sha256', webhookKey(scheme, secret)).update(`${id}.${seconds}.${body}`, 'utf8').digest('base64');
         return { [`${p}-id`]: id, [`${p}-timestamp`]: String(seconds), [`${p}-signature`]: `v1,${signature}` };
     }
     if (scheme.kind === 'timestamp-v1') {
         const signature = createHmac('sha256', secret).update(`${seconds}.${body}`, 'utf8').digest('hex');
-        return { [scheme.header.toLowerCase()]: `t=${seconds},v1=${signature}` };
+        return { [scheme.header.toLowerCase()]: `t=${seconds},${scheme.version ?? 'v1'}=${signature}` };
     }
+    if (scheme.kind === 'secret')
+        return { [scheme.header.toLowerCase()]: secret };
     if (scheme.kind === 'hash')
         return { [scheme.header.toLowerCase()]: hashOf(scheme, secret, body) };
-    // the key is the secret as it is, or its base64 decoded (`secretKey: 'base64'`, Daily's)
-    const mac = createHmac(scheme.algorithm ?? 'sha256', scheme.secretKey === 'base64' ? Buffer.from(secret, 'base64') : secret).update(hmacBase(scheme, seconds, body), 'utf8').digest(scheme.encoding);
+    const mac = createHmac(scheme.algorithm ?? 'sha256', secret).update(hmacBase(scheme, seconds, body), 'utf8').digest(scheme.encoding);
     return { [scheme.header.toLowerCase()]: `${scheme.prefix ?? ''}${mac}`, ...(scheme.timestampHeader ? { [scheme.timestampHeader.toLowerCase()]: String(seconds) } : {}) };
 }
 /** A `hash` scheme's value: the digest of its `signed` template with the secret and the body put in. */
-const hashOf = (scheme, secret, body) => createHash(scheme.algorithm ?? 'sha256').update(scheme.signed.replaceAll('{secret}', secret).replaceAll('{body}', body), 'utf8').digest(scheme.encoding);
+const hashOf = (scheme, secret, body) => {
+    const digest = createHash(scheme.algorithm ?? 'sha256').update(scheme.signed.replaceAll('{secret}', secret).replaceAll('{body}', body), 'utf8');
+    return scheme.encoding === 'base64-unpadded' ? digest.digest('base64').replace(/=+$/, '') : digest.digest(scheme.encoding);
+};
 /** What an `hmac` scheme signs: its `signed` template, else `${t}.${body}` with a timestamp header, else the body. */
 const hmacBase = (scheme, seconds, body) => scheme.signed !== undefined ? scheme.signed.replaceAll('{t}', String(seconds)).replaceAll('{body}', body) : scheme.timestampHeader ? `${seconds}.${body}` : body;
 /** Every scheme's headers for one delivery, merged. */
@@ -81,7 +86,11 @@ export function verifyEvent(scheme, secret, body, headers, opts = {}) {
         if (!Number.isFinite(seconds) || !fresh(seconds))
             return false;
         const expected = createHmac('sha256', secret).update(`${seconds}.${body}`, 'utf8').digest('hex');
-        return parts.some(([k, v]) => k === 'v1' && v !== undefined && same(v, expected));
+        return parts.some(([k, v]) => k === (scheme.version ?? 'v1') && v !== undefined && same(v, expected));
+    }
+    if (scheme.kind === 'secret') {
+        const given = h[scheme.header.toLowerCase()];
+        return given !== undefined && same(given, secret);
     }
     if (scheme.kind === 'hash') {
         const given = h[scheme.header.toLowerCase()];
@@ -133,11 +142,7 @@ function at(row, path) {
 function headersFor(templates, values, endpoint) {
     const out = {};
     for (const [name, template] of Object.entries(templates)) {
-        // a literal may stand before an endpoint's field (`Basic $endpoint.basicAuth`); the header is dropped when it is empty
-        const prefixed = /^(.+?)\$endpoint\.([\w.]+)$/.exec(template);
-        const field = prefixed ? at(endpoint, prefixed[2]) : undefined;
-        const value = prefixed ? (field === undefined || field === null || field === '' ? undefined : `${prefixed[1]}${String(field)}`)
-            : template.startsWith('$endpoint.') ? at(endpoint, template.slice('$endpoint.'.length)) : template.startsWith('$') ? values[template] : template;
+        const value = template.startsWith('$endpoint.') ? at(endpoint, template.slice('$endpoint.'.length)) : template.startsWith('$') ? values[template] : template;
         if (value !== undefined && value !== null)
             out[name.toLowerCase()] = String(value);
     }
@@ -191,7 +196,7 @@ const worldTransport = async (url, body, headers) => {
         import('../app-route.cjs'),
         import('../network-policy.cjs'),
     ]);
-    if (!appDestination(url) && worldEgressRefusal(url) !== null)
+    if (!appDestination(url) && worldEgressRefusal(url, process.env, 'POST') !== null)
         return 0;
     try {
         return (await appFetch(url, { method: 'POST', headers: { 'content-type': 'application/json', ...headers }, body })).status;
@@ -200,27 +205,11 @@ const worldTransport = async (url, body, headers) => {
         return 0;
     }
 };
-/** A message a vendor sends the application's own server that is no declared event (Google Calendar's push notification:
- *  a bodiless POST with its X-Goog headers), over the same transport: the receiver's status, or 0 when the World lets
- *  no request out to it or it cannot be reached. The vendor waits on it, as the sender of such a message does. */
-export async function deliverToApplication(url, init) {
-    const [{ appDestination, appFetch }, { worldEgressRefusal }] = await Promise.all([
-        import('../app-route.cjs'),
-        import('../network-policy.cjs'),
-    ]);
-    if (!appDestination(url) && worldEgressRefusal(url) !== null)
-        return 0;
-    // the request that caused the message is its trace's parent (trace-context.ts)
-    const headers = new Headers(init.headers);
-    for (const [k, v] of Object.entries(deliveryTraceHeaders()))
-        if (!headers.has(k))
-            headers.set(k, v);
-    try {
-        return (await appFetch(url, { ...init, headers })).status;
-    }
-    catch {
-        return 0;
-    }
+let deliveryObserver;
+export function setDeliveryObserver(observer) {
+    const previous = deliveryObserver;
+    deliveryObserver = observer;
+    return previous;
 }
 /** A message the vendor sends the application's server and decides by its answer (Stripe's real-time authorization
  *  request, answered within its window): over the same transport, waited on for at most `within` milliseconds, the
@@ -231,42 +220,44 @@ export async function askApplication(url, init, within, standIn) {
         const late = new Promise((done) => { timer = setTimeout(() => done('late'), within); });
         const stood = await Promise.race([standIn(url, init), late]).finally(() => clearTimeout(timer));
         if (stood === 'late')
-            return { status: 0, body: '', missed: 'timeout' };
+            return { status: 0, headers: {}, body: '', missed: 'timeout' };
         if (stood === 'unreachable')
-            return { status: 0, body: '', missed: 'unreachable' };
+            return { status: 0, headers: {}, body: '', missed: 'unreachable' };
+        if (stood !== undefined && stood.bodyError !== undefined)
+            return { status: 0, headers: {}, body: '', missed: 'unreachable' };
         if (stood !== undefined)
-            return stood;
+            return { status: stood.status, headers: Object.fromEntries(Object.entries(stood.headers ?? {}).map(([k, v]) => [k.toLowerCase(), v])), body: stood.body };
     }
     const [{ appDestination, appFetch }, { worldEgressRefusal }] = await Promise.all([
         import('../app-route.cjs'),
         import('../network-policy.cjs'),
     ]);
-    if (!appDestination(url) && worldEgressRefusal(url) !== null)
-        return { status: 0, body: '', missed: 'unreachable' };
+    if (!appDestination(url) && worldEgressRefusal(url, process.env, init.method ?? 'GET') !== null)
+        return { status: 0, headers: {}, body: '', missed: 'unreachable' };
     const headers = new Headers(init.headers);
     for (const [k, v] of Object.entries(deliveryTraceHeaders()))
         if (!headers.has(k))
             headers.set(k, v);
     try {
         const res = await appFetch(url, { ...init, headers, signal: AbortSignal.timeout(within) });
-        return { status: res.status, body: await res.text() };
+        return { status: res.status, headers: Object.fromEntries(res.headers), body: await res.text() };
     }
     catch (e) {
-        return { status: 0, body: '', missed: e instanceof Error && (e.name === 'TimeoutError' || e.name === 'AbortError') ? 'timeout' : 'unreachable' };
+        return { status: 0, headers: {}, body: '', missed: e instanceof Error && (e.name === 'TimeoutError' || e.name === 'AbortError') ? 'timeout' : 'unreachable' };
     }
 }
 /** 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, onAnswer) {
+export async function deliverEvents(service, decl, write, data, transport = worldTransport, values) {
     if (write.storedType === decl.store)
         return [];
     const sent = [];
     for (const type of eventTypesOf(decl, write.operation))
-        sent.push(...(await deliverEventType(service, decl, write, data, transport, values, type, onAnswer)));
+        sent.push(...(await deliverEventType(service, decl, write, data, transport, values, type)));
     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, onAnswer) {
+async function deliverEventType(service, decl, write, data, transport, values, type) {
     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)
@@ -295,7 +286,7 @@ async function deliverEventType(service, decl, write, data, transport, values, t
     const kept = decl.store !== undefined ? all.filter((r) => r.type === decl.store).length : 0;
     const filled = {
         $type: type, $data: eventData,
-        $id: `evt_twin_${digest(`${type}|${write.occurredAt}|${kept}|${JSON.stringify(eventData)}`).slice(0, 24)}`,
+        $id: `evt_${ksuidFrom(seconds, kept, `${type}|${write.occurredAt}|${kept}|${JSON.stringify(eventData)}`)}`,
         '$time.ms': millis, '$time.s': seconds, '$time.iso': write.occurredAt,
         ...requestValues(write.request),
         ...extra,
@@ -314,7 +305,6 @@ async function deliverEventType(service, decl, write, data, transport, values, t
     const shared = JSON.stringify(envelope);
     const each = perEndpoint(decl.envelope);
     const sent = [];
-    const to = [];
     const before = decl.record !== undefined ? all.filter((r) => r.type === decl.record).length : 0;
     for (const [i, { row, kind }] of endpoints.entries()) {
         const body = each ? JSON.stringify(fillEnvelope(decl.envelope, filled, row)) : shared;
@@ -323,7 +313,6 @@ async function deliverEventType(service, decl, write, data, transport, values, t
         const extraHeaders = decl.headers ? headersFor(decl.headers, filled, row) : {};
         const headers = { ...extraHeaders, ...signEventAll(decl.scheme, String(at(row, kind.secret)), body, seconds, url, seq) };
         sent.push({ url, body, headers });
-        to.push({ kind, row });
         // kept with the write, by an id of the delivery itself (two made at once never take the same one)
         if (decl.record !== undefined) {
             await applyTwinWrite(service, {
@@ -336,18 +325,11 @@ async function deliverEventType(service, decl, write, data, transport, values, t
     // slow or down fails no request
     // the write's trace is read now, inside its request, and carried on each delivery (W3C trace continuation)
     const trace = deliveryTraceHeaders();
-    // each answer is read as the vendor reads it, when the endpoint kind keeps score (its `outcome`)
-    const stated = (url) => {
-        const r = decl.receivers === undefined ? undefined : all.filter((x) => x.type === decl.receivers && x.deleted !== true && url.startsWith(String(x.url)))
-            .sort((x, y) => String(y.url).length - String(x.url).length)[0];
-        return r === undefined ? undefined : Number(r.status);
-    };
-    for (const [i, { url, body: payload, headers }] of sent.entries())
+    for (const d of sent)
+        deliveryObserver?.({ ...d, service });
+    for (const { url, body: payload, headers } of sent)
         setTimeout(() => {
-            const answered = stated(url);
-            (answered !== undefined ? Promise.resolve(answered) : transport(url, payload, { ...headers, ...trace }))
-                .then((status) => (onAnswer && to[i].kind.outcome ? onAnswer({ ...to[i], status: typeof status === 'number' ? status : 0, occurredAt: write.occurredAt }) : undefined))
-                .catch(() => { });
+            void transport(url, payload, { ...headers, ...trace }).catch(() => { });
         }, 0);
     return sent;
 }

package/dist/src/exact-json.d.ts

@@ -0,0 +1,10 @@
+/** JSON and wire integers outside JavaScript's safe range retain their decimal digits.
+ * Safe integers stay numbers; floating-point tokens keep their wire's double semantics.
+ * Quoted strings are consumed whole, so their contents are never rewritten.
+ */
+export declare function exactInteger(digits: string): number | string;
+export declare function parseExactJson(text: string, integer?: (digits: string) => number | string | bigint): any;
+/** Ordering integer versions and stored fields must not round adjacent int64 values. */
+export declare function compareExactNumbers(a: unknown, b: unknown): number;
+/** Unsafe integer tokens use decimal strings at kernel interfaces; schema checks retain that meaning. */
+export declare function isExactIntegerValue(value: unknown): boolean;

package/dist/src/exact-json.js

@@ -0,0 +1,98 @@
+/** JSON and wire integers outside JavaScript's safe range retain their decimal digits.
+ * Safe integers stay numbers; floating-point tokens keep their wire's double semantics.
+ * Quoted strings are consumed whole, so their contents are never rewritten.
+ */
+export function exactInteger(digits) {
+    const n = BigInt(digits);
+    return n >= -9007199254740991n && n <= 9007199254740991n ? Number(n) : n.toString();
+}
+export function parseExactJson(text, integer = exactInteger) {
+    let at = 0;
+    const number = /-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?/y;
+    const space = () => { while (/[\x20\t\r\n]/.test(text[at] ?? '') && at < text.length)
+        at++; };
+    const invalid = () => { throw new SyntaxError(`Invalid JSON at position ${at}`); };
+    const quoted = () => {
+        const begin = at++;
+        for (; at < text.length; at++) {
+            if (text[at] === '\\') {
+                at++;
+                continue;
+            }
+            if (text[at] === '"') {
+                const token = text.slice(begin, ++at);
+                // JSON.parse reads only a quoted string, never an integer token.
+                return JSON.parse(token);
+            }
+        }
+        return invalid();
+    };
+    const value = () => {
+        space();
+        if (text[at] === '"')
+            return quoted();
+        if (text[at] === '[' || text[at] === '{') {
+            const array = text[at++] === '[';
+            const out = array ? [] : {};
+            const end = array ? ']' : '}';
+            space();
+            if (text[at] === end) {
+                at++;
+                return out;
+            }
+            for (;;) {
+                space();
+                let key;
+                if (!array) {
+                    if (text[at] !== '"')
+                        return invalid();
+                    key = quoted();
+                    space();
+                    if (text[at++] !== ':')
+                        return invalid();
+                }
+                const item = value();
+                if (array)
+                    out.push(item);
+                else
+                    Object.defineProperty(out, key, { value: item, enumerable: true, writable: true, configurable: true });
+                space();
+                if (text[at] === end) {
+                    at++;
+                    return out;
+                }
+                if (text[at++] !== ',')
+                    return invalid();
+            }
+        }
+        for (const [literal, decoded] of [['true', true], ['false', false], ['null', null]]) {
+            if (text.startsWith(literal, at)) {
+                at += literal.length;
+                return decoded;
+            }
+        }
+        number.lastIndex = at;
+        const token = number.exec(text)?.[0];
+        if (token === undefined)
+            return invalid();
+        at += token.length;
+        return /^-?\d+$/.test(token) && !Number.isSafeInteger(Number(token)) ? integer(token) : Number(token);
+    };
+    const out = value();
+    space();
+    if (at !== text.length)
+        return invalid();
+    return out;
+}
+/** Ordering integer versions and stored fields must not round adjacent int64 values. */
+export function compareExactNumbers(a, b) {
+    if (/^-?\d+$/.test(String(a)) && /^-?\d+$/.test(String(b))) {
+        const x = BigInt(String(a)), y = BigInt(String(b));
+        return x < y ? -1 : x > y ? 1 : 0;
+    }
+    return Number(a) - Number(b);
+}
+/** Unsafe integer tokens use decimal strings at kernel interfaces; schema checks retain that meaning. */
+export function isExactIntegerValue(value) {
+    return Number.isInteger(value) || typeof value === 'string' && /^-?\d+$/.test(value) && !Number.isSafeInteger(Number(value));
+}

package/dist/src/executor.d.ts

@@ -17,12 +17,26 @@ export type TwinAuthStrategy =
 {
     in: 'lanes';
     lanes: Record<string, TwinAuthStrategy>;
+} | {
+    in: 'choice';
+    choices: Array<{
+        credential: string;
+        strategy: TwinAuthStrategy;
+    }>;
+} | {
+    in: 'signature';
+    algorithm: 'oauth1-hmac-sha1';
 }
 /** the key rides in the query string (`?key=…`, `?appid=…`) — no header will do */
  | {
     in: 'query';
     name: string;
 }
+/** the key rides in the path (Telegram's `/bot<token>/METHOD_NAME`): `pattern`'s first group is its place */
+ | {
+    in: 'path';
+    pattern: string;
+}
 /** AWS Signature Version 4 — a signature computed per request over the whole canonical request.
  *  `scope` answers which region and service THIS request is for, because a pack may route several
  *  services over one executor (aws routes six); it is pure and is handed no secret. */
@@ -125,8 +139,11 @@ export type CredentialCustody = {
 };
 /** `vendor`: the vendor whose rate budget every call is charged to (D8): the call is priced and reserved before it is
  *  made, refused when the budget is spent, and settled with the vendor's answer (its back-off honoured). */
+/** `now`: the instant a signature is made at (the wall clock unless given: an acceptance whose vendor is a fixture World
+ *  signs at that World's clock, which its twin checks a signature's date against). */
 export type RemoteExecuteOptions = {
     custody?: CredentialCustody;
     vendor?: string;
+    now?: () => Date;
 };
 export declare function buildRemoteExecute(origin: URL, credential: CredentialPayload, auth?: TwinAuthStrategy, vendorHosts?: readonly HostRule[], options?: RemoteExecuteOptions): RemoteExecute;