@volter/world-core 3.0.38 → 3.0.39

package/src/derived.ts

@@ -1,3 +1,4 @@
+import { parseExactJson } from './exact-json.ts';
 // THE DERIVED DISPATCH — the generated wire's router (docs/contributing/architecture.md, "The derived
 // pack"). A derived pack's surface (`src/generated/surface.gen.json`, written by scripts/derive-pack.ts)
 // names every operation the vendor publishes. This matches a request to one of them and hands it to its
@@ -38,11 +39,11 @@ export type DerivedOperation = {
   scopes?: ReadonlyArray<string>;
   credentials?: ReadonlyArray<string>;
   /** the body's declared fields: name, type, and the numeric bounds the spec states (a strict body, `ctx.fields`) */
-  body?: ReadonlyArray<{ name: string; type: string; required?: boolean; minimum?: number; maximum?: number }>;
+  body?: ReadonlyArray<{ name: string; type: string; required?: boolean; 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 = { version: string; basePath?: string; spanning?: ReadonlyArray<string>; operations: ReadonlyArray<DerivedOperation> };
+export type DerivedSurface = { graphql?: { sdl: string }; format?: string; commands?: ReadonlyArray<{ id: string }>; version: string; basePath?: string; spanning?: ReadonlyArray<string>; operations: ReadonlyArray<DerivedOperation> };
 
 /** What a semantics handler receives: the request, the operation it matched, and its path parameters. */
 export type DerivedCall = { request: Request; operation: DerivedOperation; params: Record<string, string> };
@@ -77,7 +78,7 @@ export async function checkJsonBody(request: Request): Promise<boolean> {
   // a body labelled otherwise and not shaped as JSON is the form it is labelled (an OAuth token request), not bad JSON
   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 as Tagged)[BODY_TEXT] !== undefined ? BODY_PARSE_KEY.get(request) : undefined;
     if (tag) BODY_PARSED.set(tag, { value });
     return true;
@@ -185,6 +186,19 @@ export function matchOperation(routes: Map<string, Route[]>, method: string, pat
   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: Map<string, Route[]>, pathname: string): Record<string, string> {
+  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: Record<string, string> = {};
+  try { route.names.forEach((name, i) => { params[name] = decodeURIComponent(m[i + 1]!); }); } catch { return {}; }
+  return params;
+}
+
 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). */
@@ -194,8 +208,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`). */
@@ -256,7 +275,7 @@ export function createDerivedFetch(options: DerivedFetchOptions): DerivedFetch {
     if (request.method !== 'GET' && request.method !== 'HEAD' && request.body && !(request.headers.get('content-type') ?? '').includes('multipart')) 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: DerivedCall = { request, operation: matched.operation, params: prefixed ? { ...(JSON.parse(prefixed) as Record<string, string>), ...matched.params } : matched.params };
+    const call: DerivedCall = { request, operation: matched.operation, params: prefixed ? { ...(parseExactJson(prefixed) as Record<string, string>), ...matched.params } : matched.params };
     const around = options.around ?? ((_c: DerivedCall, next: () => Promise<Response>) => next());
     const handler = handlers[matched.operation.id];
     if (handler) return around(call, () => handler(call));

package/src/events.ts

@@ -8,27 +8,32 @@
 // delivery is made, never when a browser client imports the kernel.
 import { createHash, createHmac } from 'node:crypto';
 import { applyTwinWrite, twinResources } from './serve.ts';
-import { equalSecrets as same } from './signing.ts';
+import { equalSecrets as same, ksuidFrom } from './signing.ts';
 import { deliveryTraceHeaders } from './trace-context.ts';
 
 /** 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. */
-  | { kind: 'timestamp-v1'; header: string }
+   *  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
    *  and `{body}` the body (Slack's `v0:{t}:{body}`), and `algorithm` the hash (SHA-256 unless named: GitHub's older
    *  `X-Hub-Signature` is SHA-1). */
-  | { kind: 'hmac'; header: string; encoding: 'hex' | 'base64'; prefix?: string; timestampHeader?: string; signed?: string; algorithm?: 'sha1' | 'sha256'; secretKey?: 'base64' | 'utf8' }
+  | { kind: 'hmac'; header: string; encoding: 'hex' | 'base64'; prefix?: string; timestampHeader?: string; signed?: string; algorithm?: 'sha1' | 'sha256' }
   /** 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}` */
-  | { kind: 'hash'; header: string; signed: string; encoding: 'hex' | 'base64'; algorithm?: 'sha256' };
+   *  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' | '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
  *  stored type and the fields holding the URL, the signing secret, the event types an endpoint takes (all when absent,
@@ -56,26 +61,8 @@ 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 };
-
 /** 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: Record<string, unknown>, match: EndpointsDecl['match'], filled: Record<string, unknown>): boolean {
@@ -114,10 +101,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
@@ -151,24 +134,27 @@ const webhookKey = (scheme: { secretPrefix?: string; secretKey?: 'base64' | 'utf
  *  made before this one, so a receiver that deduplicates by id drops neither. */
 export function signEvent(scheme: EventScheme, secret: string, body: string, seconds: number, url: string, seq = 0): Record<string, string> {
   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: { signed: string; encoding: 'hex' | 'base64'; algorithm?: 'sha256' }, secret: string, body: string): string =>
-  createHash(scheme.algorithm ?? 'sha256').update(scheme.signed.replaceAll('{secret}', secret).replaceAll('{body}', body), 'utf8').digest(scheme.encoding);
+const hashOf = (scheme: { signed: string; encoding: 'hex' | 'base64' | 'base64-unpadded'; algorithm?: 'sha256' }, secret: string, body: string): string => {
+  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: { timestampHeader?: string; signed?: string }, seconds: number, body: string): string =>
@@ -199,8 +185,9 @@ export function verifyEvent(scheme: EventScheme, secret: string, body: string, h
     const seconds = Number(parts.find(([k]) => k === 't')?.[1]);
     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()]; return given !== undefined && same(given, hashOf(scheme, secret, body)); }
   const seconds = scheme.timestampHeader ? Number(h[scheme.timestampHeader.toLowerCase()]) : undefined;
   if (seconds !== undefined && (!Number.isFinite(seconds) || !fresh(seconds))) return false;
@@ -243,11 +230,7 @@ function at(row: Record<string, unknown>, path: string): unknown {
 function headersFor(templates: Record<string, string>, values: Record<string, unknown>, endpoint: Record<string, unknown>): Record<string, string> {
   const out: Record<string, string> = {};
   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);
   }
   return out;
@@ -298,38 +281,35 @@ function requestValues(request: Request | undefined): Record<string, string> {
 const worldTransport: EventTransport = async (url, body, headers) => {
   const [{ appDestination, appFetch }, { worldEgressRefusal }] = await Promise.all([
     import('../app-route.cjs') as Promise<{ appDestination: (value: string) => unknown; appFetch: (url: string, init: RequestInit) => Promise<unknown> }>,
-    import('../network-policy.cjs') as Promise<{ worldEgressRefusal: (value: string) => unknown }>,
+    import('../network-policy.cjs') as Promise<{ worldEgressRefusal: (value: string, env?: NodeJS.ProcessEnv, method?: string) => unknown }>,
   ]);
-  if (!appDestination(url) && worldEgressRefusal(url) !== null) return 0;
+  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 })) as { status: number }).status; } catch { 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: string, init: RequestInit): Promise<number> {
-  const [{ appDestination, appFetch }, { worldEgressRefusal }] = await Promise.all([
-    import('../app-route.cjs') as Promise<{ appDestination: (value: string) => unknown; appFetch: (url: string, init: RequestInit) => Promise<{ status: number }> }>,
-    import('../network-policy.cjs') as Promise<{ worldEgressRefusal: (value: string) => unknown }>,
-  ]);
-  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; }
+/** 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;
+let deliveryObserver: DeliveryObserver | undefined;
+export function setDeliveryObserver(observer: DeliveryObserver | undefined): DeliveryObserver | undefined {
+  const previous = deliveryObserver;
+  deliveryObserver = observer;
+  return previous;
 }
 
-/** 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`). */
-export type ApplicationAnswer = { status: number; body: string; missed?: 'timeout' | 'unreachable' };
+/** 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' };
 
 /** Who answers what the vendor asks the application (`ctx.ask`) 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. */
-export type ApplicationStandIn = (url: string, init: RequestInit) => Promise<{ status: number; body: string } | 'unreachable' | undefined>;
+ *  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
@@ -339,22 +319,23 @@ export async function askApplication(url: string, init: RequestInit, within: num
     let timer: ReturnType<typeof setTimeout> | undefined;
     const late = new Promise<'late'>((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' };
-    if (stood === 'unreachable') return { status: 0, body: '', missed: 'unreachable' };
-    if (stood !== undefined) return stood;
+    if (stood === 'late') return { status: 0, headers: {}, body: '', missed: 'timeout' };
+    if (stood === '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 { 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') as Promise<{ appDestination: (value: string) => unknown; appFetch: (url: string, init: RequestInit) => Promise<{ status: number; text(): Promise<string> }> }>,
-    import('../network-policy.cjs') as Promise<{ worldEgressRefusal: (value: string) => unknown }>,
+    import('../app-route.cjs') as Promise<{ appDestination: (value: string) => unknown; appFetch: (url: string, init: RequestInit) => Promise<{ status: number; headers: Headers; text(): Promise<string> }> }>,
+    import('../network-policy.cjs') as Promise<{ worldEgressRefusal: (value: string, env?: NodeJS.ProcessEnv, method?: string) => unknown }>,
   ]);
-  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' };
   }
 }
 
@@ -367,11 +348,10 @@ export async function deliverEvents(
   data: (type: string) => Promise<Record<string, unknown>>,
   transport: EventTransport = worldTransport,
   values?: (type: string) => Promise<Record<string, unknown>>,
-  onAnswer?: (answer: DeliveryAnswer) => Promise<void>,
 ): Promise<EventDelivery[]> {
   if (write.storedType === decl.store) return [];
   const sent: EventDelivery[] = [];
-  for (const type of eventTypesOf(decl, write.operation)) sent.push(...(await deliverEventType(service, decl, write, data, transport, values, type, onAnswer)));
+  for (const type of eventTypesOf(decl, write.operation)) sent.push(...(await deliverEventType(service, decl, write, data, transport, values, type)));
   return sent;
 }
 
@@ -384,7 +364,6 @@ async function deliverEventType(
   transport: EventTransport,
   values: ((type: string) => Promise<Record<string, unknown>>) | undefined,
   type: string,
-  onAnswer?: (answer: DeliveryAnswer) => Promise<void>,
 ): Promise<EventDelivery[]> {
   const all = twinResources(service, write.root) as unknown as Array<Record<string, unknown>>;
   const kinds = Array.isArray(decl.endpoints) ? decl.endpoints : [decl.endpoints as EndpointsDecl];
@@ -411,7 +390,7 @@ async function deliverEventType(
   const kept = decl.store !== undefined ? all.filter((r) => r.type === decl.store).length : 0;
   const filled: Record<string, unknown> = {
     $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,
@@ -428,7 +407,6 @@ async function deliverEventType(
   const shared = JSON.stringify(envelope);
   const each = perEndpoint(decl.envelope);
   const sent: EventDelivery[] = [];
-  const to: Array<{ kind: EndpointsDecl; row: Record<string, unknown> }> = [];
   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;
@@ -437,7 +415,6 @@ async function deliverEventType(
     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, {
@@ -450,17 +427,9 @@ async function deliverEventType(
   // 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: string): number | undefined => {
-    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()) 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(() => {});
+  for (const d of sent) deliveryObserver?.({ ...d, service });
+  for (const { url, body: payload, headers } of sent) setTimeout(() => {
+    void transport(url, payload, { ...headers, ...trace }).catch(() => {});
   }, 0);
   return sent;
 }

package/src/exact-json.ts

@@ -0,0 +1,71 @@
+/** 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: string): number | string {
+  const n = BigInt(digits);
+  return n >= -9007199254740991n && n <= 9007199254740991n ? Number(n) : n.toString();
+}
+
+export function parseExactJson(text: string, integer: (digits: string) => number | string | bigint = exactInteger): any {
+  let at = 0;
+  const number = /-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?/y;
+  const space = (): void => { while (/[\x20\t\r\n]/.test(text[at] ?? '') && at < text.length) at++; };
+  const invalid = (): never => { throw new SyntaxError(`Invalid JSON at position ${at}`); };
+  const quoted = (): string => {
+    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 = (): any => {
+    space();
+    if (text[at] === '"') return quoted();
+    if (text[at] === '[' || text[at] === '{') {
+      const array = text[at++] === '[';
+      const out: any = array ? [] : {};
+      const end = array ? ']' : '}';
+      space(); if (text[at] === end) { at++; return out; }
+      for (;;) {
+        space();
+        let key: string | undefined;
+        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]] as const) {
+      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: unknown, b: unknown): number {
+  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: unknown): boolean {
+  return Number.isInteger(value) || typeof value === 'string' && /^-?\d+$/.test(value) && !Number.isSafeInteger(Number(value));
+}

package/src/executor.ts

@@ -24,8 +24,12 @@ export type TwinAuthStrategy =
   /** A vendor of lanes whose lanes authenticate apart (Cloudflare's API by bearer, its R2 by SigV4): a lane named takes
    *  its own strategy, every other call the sealed headers; the request names its lane (`RemoteExecuteRequest.lane`). */
   | { 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. */
@@ -76,6 +80,29 @@ export type TwinAuthStrategy =
     rotate?: { answer: string; credential: string };
   };
 
+async function oauth1SignedHeader(credential: CredentialPayload, method: string, target: URL, headers: Headers, body?: string | Uint8Array): Promise<string> {
+  const field = (name: string): string => {
+    const value = credential[name];
+    if (typeof value !== 'string' || !value) throw new Error(`remote execute: oauth1-hmac-sha1 needs sealed ${name}`);
+    return value;
+  };
+  const consumerKey = field('consumerKey'), consumerSecret = field('consumerSecret');
+  const token = field('token'), tokenSecret = field('tokenSecret');
+  const encode = (value: string): string => encodeURIComponent(value).replace(/[!\x27()*]/g, c => `%${c.charCodeAt(0).toString(16).toUpperCase()}`);
+  const protocol: Array<[string, string]> = [
+    ['oauth_consumer_key', consumerKey], ['oauth_token', token], ['oauth_signature_method', 'HMAC-SHA1'],
+    ['oauth_timestamp', String(Math.floor(Date.now() / 1000))], ['oauth_nonce', crypto.randomUUID()], ['oauth_version', '1.0'],
+  ];
+  const form = typeof body === 'string' && /^application\/x-www-form-urlencoded/i.test(headers.get('content-type') ?? '') ? [...new URLSearchParams(body)] : [];
+  const pairs = [...protocol, ...target.searchParams, ...form].filter(([name]) => name !== 'oauth_signature').map(([name, value]) => [encode(name), encode(value)]);
+  pairs.sort(([a, av], [b, bv]) => a < b ? -1 : a > b ? 1 : av < bv ? -1 : av > bv ? 1 : 0);
+  const base = `${method.toUpperCase()}&${encode(`${target.protocol}//${target.host.toLowerCase()}${target.pathname}`)}&${encode(pairs.map(([name, value]) => `${name}=${value}`).join('&'))}`;
+  const key = await crypto.subtle.importKey('raw', new TextEncoder().encode(`${encode(consumerSecret)}&${encode(tokenSecret)}`), { name: 'HMAC', hash: 'SHA-1' }, false, ['sign']);
+  const bytes = new Uint8Array(await crypto.subtle.sign('HMAC', key, new TextEncoder().encode(base)));
+  const signature = btoa(Array.from(bytes, byte => String.fromCharCode(byte)).join(''));
+  return `OAuth ${[...protocol, ['oauth_signature', signature]].map(([name, value]) => `${encode(name)}="${encode(value)}"`).join(', ')}`;
+}
+
 const MAX_ORIGIN_LENGTH = 2048;
 
 function isLoopbackHost(hostname: string): boolean {
@@ -224,7 +251,9 @@ async function awsSigV4Headers(input: {
 export type CredentialCustody = { key: string; open: () => Promise<CredentialPayload>; seal: (credential: CredentialPayload) => Promise<void> | void };
 /** `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). */
-export type RemoteExecuteOptions = { custody?: CredentialCustody; vendor?: string };
+/** `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 function buildRemoteExecute(origin: URL, credential: CredentialPayload, auth?: TwinAuthStrategy, vendorHosts?: readonly HostRule[], options: RemoteExecuteOptions = {}): RemoteExecute {
   if (auth?.in === 'lanes') {
     // each lane's strategy over the same origin and credential, the budget charged once, around them all
@@ -234,7 +263,12 @@ export function buildRemoteExecute(origin: URL, credential: CredentialPayload, a
     const execute: RemoteExecute = (request) => (byLane.get(request.lane ?? '') ?? headers)(request);
     return options.vendor === undefined ? execute : budgeted(options.vendor, execute, options.custody?.key ?? JSON.stringify(credential.headers));
   }
-  const execute = auth?.in === 'exchange' ? exchangeExecute(origin, credential, auth, vendorHosts, options.custody) : direct(origin, credential, auth, vendorHosts);
+  if (auth?.in === 'choice') {
+    const picked = auth.choices.find(c => typeof credential[c.credential] === 'string' && credential[c.credential] !== '');
+    if (!picked) throw new Error('remote execute: no credential matches the declared strategy choices');
+    return buildRemoteExecute(origin, credential, picked.strategy, vendorHosts, options);
+  }
+  const execute = auth?.in === 'exchange' ? exchangeExecute(origin, credential, auth, vendorHosts, options.custody) : direct(origin, credential, auth, vendorHosts, options.now);
   return options.vendor === undefined ? execute : budgeted(options.vendor, execute, options.custody?.key ?? JSON.stringify(credential.headers));
 }
 
@@ -253,7 +287,7 @@ function budgeted(vendor: string, execute: RemoteExecute, token: string): Remote
 }
 
 /** The call made as the root's credential is applied by the strategy (header replacement when none). */
-function direct(origin: URL, credential: CredentialPayload, auth?: Exclude<TwinAuthStrategy, { in: 'exchange' | 'lanes' }>, vendorHosts?: readonly HostRule[]): RemoteExecute {
+function direct(origin: URL, credential: CredentialPayload, auth?: Exclude<TwinAuthStrategy, { in: 'exchange' | 'choice' | 'lanes' }>, vendorHosts?: readonly HostRule[], now: () => Date = () => new Date()): RemoteExecute {
   return async ({ method, path, headers, body, responseType, presigned, issued }) => {
     // A PRESIGNED UPLOAD URL the vendor returned: its own signature is its authorization, so the
     // sealed credential never goes with it, whatever host it names. A host other than the root's
@@ -284,13 +318,23 @@ function direct(origin: URL, credential: CredentialPayload, auth?: Exclude<TwinA
     // the origin into USERINFO and ships the credential to evil.com. A path is a path:
     // it starts with '/', and the parse must land on the validated origin, asserted.
     let target: URL;
+    // the vendor's own URL, where a loopback root stands in for it: what a signature is made over
+    let vendorUrl: URL | undefined;
     if (/^https:\/\//i.test(path) && vendorHosts?.length) {
       // a second host the pack declares for this vendor, on a path its rule names: validated as the root is
       target = new URL(path);
       if (target.username || target.password) throw new Error('remote execute: a vendor URL carries no userinfo');
       validateRemoteOrigin(target.origin);
-      const declared = vendorHosts.some((r) => 'host' in r && !r.exclude && r.host === target.hostname && (r.pathPattern === undefined || new RegExp(r.pathPattern).test(target.pathname)));
+      const named = (r: HostRule): boolean => ('host' in r ? r.host === target.hostname : 'suffix' in r ? target.hostname.endsWith(r.suffix) : new RegExp(r.hostPattern).test(target.hostname))
+        && (r.pathPattern === undefined || new RegExp(r.pathPattern).test(target.pathname));
+      const declared = vendorHosts.some((r) => !r.exclude && named(r)) && !vendorHosts.some((r) => r.exclude && named(r));
       if (!declared) throw new Error(`remote execute: ${target.host}${target.pathname.slice(0, 64)} is not a host this vendor's pack declares for this path`);
+      // A loopback root is the vendor substitute. Preserve the vendor Host while retaining
+      // the already-validated root's mounted path; an absolute URL never escapes that root.
+      if (isLoopbackHost(origin.hostname)) {
+        vendorUrl = target;
+        target = new URL(origin.href.replace(/\/+$/, '') + target.pathname + target.search);
+      }
     } else {
       if (!path.startsWith('/')) throw new Error(`remote execute: path must start with '/' (got ${JSON.stringify(path.slice(0, 64))})`);
       // the base keeps its path: a served world's twin lives under /<org>/<world>/<vendor>, github.com under /
@@ -302,6 +346,8 @@ function direct(origin: URL, credential: CredentialPayload, auth?: Exclude<TwinA
     // a credential the vendor issued in this perform is the request's authorization; the sealed one stays home
     if (issued !== undefined) outbound.set('authorization', issued);
     else for (const [name, value] of Object.entries(credential.headers)) outbound.set(name, value);
+    // the vendor's host, kept over any the credential carries (a loopback twin routes by it, as the World's proxy's)
+    if (vendorUrl) { outbound.set('host', vendorUrl.host); outbound.set('x-volter-twin-original-host', vendorUrl.host); }
 
     // ── THE STRATEGIES BEYOND HEADER REPLACEMENT ──────────────────────────────────────────────
     // Applied AFTER the anchoring check above, so nothing here can move the request off the
@@ -310,30 +356,43 @@ function direct(origin: URL, credential: CredentialPayload, auth?: Exclude<TwinA
     // FAIL CLOSED. A strategy with no secret must never send a request that merely LOOKS
     // authenticated — that silence is the whole defect this exists to remove. The refusals name the
     // strategy and the parameter, never the secret.
-    if (auth !== undefined && issued === undefined) {
-      const secret = credential.secret;
-      if (typeof secret !== 'string' || secret === '') {
-        throw new Error(`remote execute: the ${auth.in} credential strategy needs \`secret\` on the sealed credential, and it is absent`);
-      }
-      if (auth.in === 'query') {
-        // `set`, not `append`: it REPLACES whatever placeholder the pack put in its own path,
-        // exactly as `outbound.set` replaces a placeholder authorization header.
-        target.searchParams.set(auth.name, secret);
-      } else if (auth.algorithm === 'aws-sigv4') {
-        const keyId = credential.keyId;
-        if (typeof keyId !== 'string' || keyId === '') {
-          throw new Error('remote execute: the aws-sigv4 credential strategy needs `keyId` on the sealed credential, and it is absent');
+    // an issued credential is the authorization: nothing of the sealed one signs the request
+    if (issued === undefined) {
+      if (auth?.in === 'signature' && auth.algorithm === 'oauth1-hmac-sha1') {
+        outbound.set('authorization', await oauth1SignedHeader(credential, method, target, outbound, body));
+      } else if (auth !== undefined) {
+        const secret = credential.secret;
+        if (typeof secret !== 'string' || secret === '') {
+          throw new Error(`remote execute: the ${auth.in} credential strategy needs \`secret\` on the sealed credential, and it is absent`);
+        }
+        if (auth.in === 'query') {
+          // `set`, not `append`: it REPLACES whatever placeholder the pack put in its own path,
+          // exactly as `outbound.set` replaces a placeholder authorization header.
+          target.searchParams.set(auth.name, secret);
+        } else if (auth.in === 'path') {
+          // the key's place in the path, filled after the origin is validated; a secret that could end the segment or
+          // the path (a slash, a query, a fragment, an escape) is refused, so the request cannot leave the validated root
+          if (/[/?#%\\]/.test(secret)) throw new Error('remote execute: the path credential strategy refuses a secret that is not one path segment');
+          const place = new RegExp(auth.pattern, 'd').exec(target.pathname)?.indices?.[1];
+          if (!place) throw new Error(`remote execute: the path credential strategy's pattern does not name the key's place in ${target.pathname.slice(0, 64)}`);
+          target.pathname = target.pathname.slice(0, place[0]) + secret + target.pathname.slice(place[1]);
+        } else if (auth.algorithm === 'aws-sigv4') {
+          const keyId = credential.keyId;
+          if (typeof keyId !== 'string' || keyId === '') {
+            throw new Error('remote execute: the aws-sigv4 credential strategy needs `keyId` on the sealed credential, and it is absent');
+          }
+          // the HOST goes with it: an AWS endpoint names its own region, and only the pack knows how
+          const signedUrl = vendorUrl ?? target;
+          const { region, service } = typeof auth.scope === 'function' ? auth.scope({ method, path, host: signedUrl.host, headers: Object.fromEntries(outbound.entries()), ...(body === undefined ? {} : { body }) }) : auth.scope;
+          const signed = await awsSigV4Headers({ method, url: signedUrl, ...(body === undefined ? {} : { body }), keyId, secret, region, service, headers: outbound, at: now() });
+          for (const [name, value] of Object.entries(signed)) outbound.set(name, value);
+        } else {
+          // `null` is the vendor's own exemption, declared by the pack — not an error, and not a
+          // reason to send an unsigned header.
+          if (body instanceof Uint8Array) throw new Error('remote execute: this signature canonicalizer accepts text bodies only');
+          const payload = auth.canonical({ method, path, ...(body === undefined ? {} : { body }) });
+          if (payload !== null) outbound.set(auth.header, await hmacSha256(secret, payload, auth.encoding));
         }
-        // the HOST goes with it: an AWS endpoint names its own region, and only the pack knows how
-        const { region, service } = typeof auth.scope === 'function' ? auth.scope({ method, path, host: target.host, headers: Object.fromEntries(outbound.entries()), ...(body === undefined ? {} : { body }) }) : auth.scope;
-        const signed = await awsSigV4Headers({ method, url: target, ...(body === undefined ? {} : { body }), keyId, secret, region, service, headers: outbound, at: new Date() });
-        for (const [name, value] of Object.entries(signed)) outbound.set(name, value);
-      } else {
-        // `null` is the vendor's own exemption, declared by the pack — not an error, and not a
-        // reason to send an unsigned header.
-        if (body instanceof Uint8Array) throw new Error('remote execute: this signature canonicalizer accepts text bodies only');
-        const payload = auth.canonical({ method, path, ...(body === undefined ? {} : { body }) });
-        if (payload !== null) outbound.set(auth.header, await hmacSha256(secret, payload, auth.encoding));
       }
     }