@volter/world-core 3.0.155 → 3.0.157

package/src/derived-real.ts

@@ -4,7 +4,7 @@ import { parseExactJson, exactInteger, compareExactNumbers } from './exact-json.
 // They run over the kernel executor (`RemoteExecute`), which applies the sealed credential; the credential never
 // reaches here, only its keyed fingerprint (`PerformContext.credential`, for the idempotency key).
 import type { TwinAction } from './actions.ts';
-import { aliasesFrom, parentEntries, readParentTreeMap, readTree } from './log.ts';
+import { aliasesFrom, parentEntries, readParentTreeMap, readTree, wholeLog } from './log.ts';
 import { storedType, type DerivedManifest, type IngestDecl, type ResourceDecl, type VendorManifest } from './derived-core.ts';
 import type { DerivedOperation, DerivedSurface } from './derived.ts';
 import { verifyEvent, type EventScheme } from './events.ts';
@@ -181,10 +181,20 @@ const fixedHeaders = (op: DerivedOperation): Record<string, string> => Object.fr
 
 /** The body as the operation's encoding sends it. */
 function encode(op: DerivedOperation, body: unknown): { body?: string; type?: string } {
-  if (body === undefined || op.bodyEncoding === 'none') return {};
+  // a body the request carried where the spec declares none (Tinybird's Events API, NDJSON its client sends as text):
+  // the body as recorded, as the vendor read it
+  if (body === undefined) return {};
   if (op.bodyEncoding === 'form') {
+    // a form's nested values in the bracket form a form-encoded API reads (`scope[type]=account`, `items[0][price]=…`),
+    // the form the kernel's own parseBracketForm reads back; never a value's JSON text
     const form = new URLSearchParams();
-    for (const [k, v] of Object.entries(object(body) ?? {})) if (v !== undefined && v !== null) form.set(k, typeof v === 'object' ? JSON.stringify(v) : String(v));
+    const put = (key: string, v: unknown): void => {
+      if (v === undefined || v === null) return;
+      if (Array.isArray(v)) { v.forEach((item, i) => put(`${key}[${i}]`, item)); return; }
+      if (typeof v === 'object') { for (const [k, x] of Object.entries(v as Record<string, unknown>)) put(`${key}[${k}]`, x); return; }
+      form.append(key, String(v));
+    };
+    for (const [k, v] of Object.entries(object(body) ?? {})) put(k, v);
     return { body: form.toString(), type: 'application/x-www-form-urlencoded' };
   }
   return { body: JSON.stringify(body), type: 'application/json' };
@@ -249,8 +259,14 @@ async function graphqlAnswers(m: DerivedManifest, surface: DerivedSurface, input
 /** The account a root is, before a perform sends a path naming the World's ("The account a root is"): the World's
  *  account its own doors made, unadopted, adopts the one account the root's credential lists. Read once per deploy (an
  *  adopted account is not asked again); a list the vendor refuses, or one naming several accounts, adopts none. */
+/** The accounts a root's list already named as the World's own (the World's id is the vendor's), by service and root:
+ *  nothing to adopt, so not asked again. */
+const accountsMatched = new Map<string, Set<string>>();
+
 async function adoptAccount(units: Unit[], execute: RemoteExecute, ctx: PerformContext): Promise<void> {
   if (ctx.service === undefined) return;
+  const matched = accountsMatched.get(`${ctx.service}\u0000${ctx.root ?? ''}`) ?? new Set<string>();
+  accountsMatched.set(`${ctx.service}\u0000${ctx.root ?? ''}`, matched);
   for (const u of units) {
     const m = u.manifest;
     const decl = m.account ? m.resources[m.account] : undefined;
@@ -259,11 +275,12 @@ async function adoptAccount(units: Unit[], execute: RemoteExecute, ctx: PerformC
     const local = (readTree(ctx.service, ctx.root) as Row[]).filter((r) => r.type === type && r.deleted !== true && ctx.resolve(type, String(r.id)) === String(r.id));
     const scope = decl.refresh;
     const op = scope && 'list' in scope ? u.surface.operations.find((o) => o.id === scope.list) : undefined;
-    if (!local.length || !op) continue;
+    if (!local.length || !op || local.every((l) => matched.has(`${type}:${String(l.id)}`))) continue;
     const answer = await execute({ method: op.method.toUpperCase(), path: sentTo(m, marked(op, `${op.basePath ?? u.surface.basePath ?? ''}${op.path}`), {}), ...(u.lane ? { lane: u.lane } : {}), headers: fixedHeaders(op) });
     if (answer.status >= 400) continue;
     const items = itemsOf(op, parse(answer));
     const id = items.length === 1 ? storedIdOf(decl, items[0]!) : undefined;
+    if (id !== undefined && local.some((l) => String(l.id) === id)) matched.add(`${type}:${id}`);
     if (id === undefined || local.some((l) => String(l.id) === id)) continue;
     observeResources(ctx.service, [{ type, id, fields: items[0] as ObservedResource['fields'], adopts: String(local[0]!.id) }], ctx.root !== undefined ? { root: ctx.root } : {});
   }
@@ -469,8 +486,25 @@ function scopeIdOf(scope: object, fields: Record<string, unknown>): string | und
   return value === undefined || value === null || value === '' ? undefined : String(value);
 }
 
+/** A refresh larger than one window of the vendor's rate budget paces itself: a call the budget refuses before making
+ *  it (RateBudgetError) waits the time the refusal names, at most two minutes a wait, and is made then. The budget is
+ *  never exceeded and no vendor answer is retried; without it a refresh needing more than one window never finishes
+ *  (Slack's, after a deploy spent the window: every rerun refused again from the start). */
+function paced(execute: RemoteExecute): RemoteExecute {
+  return async (request) => {
+    for (let waits = 0; ; waits++) {
+      try { return await execute(request); } catch (error) {
+        const wait = (error as { name?: string; retryAfterMs?: number }).name === 'RateBudgetError' ? (error as { retryAfterMs: number }).retryAfterMs : undefined;
+        if (wait === undefined || wait > 120_000 || waits >= 60) throw error;
+        await new Promise((done) => setTimeout(done, wait + 250));
+      }
+    }
+  };
+}
+
 function refreshOf(units: Unit[], service: string): NonNullable<StateSystemAdapters['refresh']> {
-  return async (execute, opts) => {
+  return async (unpaced, opts) => {
+    const execute = paced(unpaced);
     const observed: ObservedResource[] = [];
     const complete: Completed[] = [];
     // what the root's credential may not read (a token scoped to some of the account): left as the World holds it, said
@@ -478,6 +512,16 @@ function refreshOf(units: Unit[], service: string): NonNullable<StateSystemAdapt
     let answered = 0;
     for (const { manifest: m, surface, lane } of units) {
       const onLane = lane ? { lane } : {};
+      const tenantBinding: Record<string, unknown> = {};
+      if (m.refreshIdentity) {
+        const identity = surface.operations.find(operation => operation.id === m.refreshIdentity!.operation);
+        if (!m.tenant || !identity || identity.method !== 'get' || identity.path.includes('{')) throw new Error(`${m.vendor}: refresh identity needs a parameterless GET and declared tenant field`);
+        const answer = await execute({ method: 'GET', path: `${identity.basePath ?? surface.basePath ?? ''}${identity.path}`, ...onLane, headers: fixedHeaders(identity) });
+        if (answer.status >= 400 || refusedIn(m, parse(answer))) throw new Error(`${m.vendor}: root account identity refused; nothing folded`);
+        const tenant = at(parse(answer), m.refreshIdentity.field);
+        if (typeof tenant !== 'string' || !tenant) throw new Error(`${m.vendor}: root account identity is absent; nothing folded`);
+        tenantBinding[m.tenant.field] = tenant;
+      }
       // parents before children, however deep
       const scoped = Object.entries(m.resources).filter(([, d]) => d.refresh && !('none' in d.refresh));
       const depth = (r: string, seen = new Set<string>()): number => { const p = m.resources[r]?.parent?.resource; return p && !seen.has(p) ? 1 + depth(p, seen.add(r)) : 0; };
@@ -485,6 +529,7 @@ function refreshOf(units: Unit[], service: string): NonNullable<StateSystemAdapt
       for (const [resource, decl] of order) {
         const scope = decl.refresh!;
         if ('none' in scope) continue;
+        if (m.refreshIdentity && (!('list' in scope) || 'graphql' in scope)) throw new Error(`${m.vendor}: account-bound refresh requires REST list scopes`);
         if ('graphql' in scope && scope.graphql) {
           await refreshGraphql(m, resource, decl, scope, execute, opts.scope, observed, complete);
           answered += 1;
@@ -501,6 +546,16 @@ function refreshOf(units: Unit[], service: string): NonNullable<StateSystemAdapt
         if ('get' in scope && scope.known) {
           const aliases = aliasesFrom(parentEntries(service, opts.root));
           const held = [...readParentTreeMap(service, opts.root)].filter(([, r]) => r.type === type && r.fields.deleted !== true);
+          // and each a door made (a person's act on the vendor's site: a group they add the bot to), which the vendor holds
+          // as the World does though no deploy landed it
+          const rooted = new Set(held.map(([k]) => k));
+          const doorMade = new Set(wholeLog(service, opts.root).filter((e) => e.subject.type === type && (e.input as Row | undefined)?.door !== undefined).map((e) => String(e.subject.id)));
+          for (const r of readTree(service, opts.root) as Row[]) {
+            const key = `${type}:${String(r.id)}`;
+            if (r.type !== type || r.deleted === true || !doorMade.has(String(r.id)) || held.some(([k]) => k === key)) continue;
+            const { type: _t, id, ...fields } = r;
+            held.push([key, { type, id: String(id), fields } as (typeof held)[number][1]]);
+          }
           const read: string[] = [];
           // a 403 leaves the type as the World holds it, never complete
           let refused = false;
@@ -523,12 +578,15 @@ function refreshOf(units: Unit[], service: string): NonNullable<StateSystemAdapt
             const target = marked(op, path);
             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 (answer.status === 403) { unread.push({ type, path, status: 403 }); refused = true; break; }
             if (answer.status === 429) throw new Error(`429: rate limited${answer.headers['retry-after'] ? `, retry after ${answer.headers['retry-after']}s` : ''}`);
             read.push(String(subject.id));
             answered += 1;
-            if (answer.status === 404) continue;
+            // the vendor's answer for a subject it no longer has: a 404, or the scope's `gone` (Telegram's 400 `chat not found`)
+            if (answer.status === 404 || (scope.gone && answer.status === scope.gone.status && refusalWords(m, parse(answer)).includes(scope.gone.says))) 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 local = (m as { worldFields?: Record<string, Record<string, unknown>> }).worldFields?.[resource] ?? {};
@@ -577,9 +635,12 @@ function refreshOf(units: Unit[], service: string): NonNullable<StateSystemAdapt
               : decl.parent?.params?.length && under ? Object.fromEntries(Object.entries(under.params).filter(([n]) => !op.path.includes(`{${n}}`) && (op.query ?? []).some((x) => x.name === n))) : {};
             // a list asked by POST carries its parent in its body too, unless the operation reads it from its query
             const parentInQuery = !rpc || (op.query ?? []).some((x) => x.name === decl.parent?.param);
-            const q = new URLSearchParams(rpc ? (parentInQuery ? byQuery : {}) : { ...page, ...byQuery });
+            // a parameter the operation declares in its query, and not its body, goes in the query of a list asked by POST
+            // too (TikTok's video list: `fields` in the query, its cursor in the body)
+            const inQuery = (n: string): boolean => (op.query ?? []).some((x) => x.name === n) && !(op.body ?? []).some((b) => b.name === n);
+            const q = new URLSearchParams(rpc ? { ...Object.fromEntries(Object.entries(page).filter(([k]) => inQuery(k))), ...(parentInQuery ? byQuery : {}) } : { ...page, ...byQuery });
             // Fixed parameters and cursors take the operation's body types, not their manifest string encoding.
-            const typedPage = Object.fromEntries(Object.entries(page).map(([k, v]) => {
+            const typedPage = Object.fromEntries(Object.entries(page).filter(([k]) => !rpc || !inQuery(k)).map(([k, v]) => {
               const type = (op.body ?? []).find((b) => b.name === k)?.type;
               const value = type === 'integer' ? exactInteger(v) : type === 'number' ? Number(v)
                 : type === 'boolean' && (v === 'true' || v === 'false') ? v === 'true' : v;
@@ -631,9 +692,12 @@ function refreshOf(units: Unit[], service: string): NonNullable<StateSystemAdapt
               if ('list' in scope && scope.detail) {
                 const detail = surface.operations.find((o) => o.id === scope.detail);
                 if (!detail) throw new Error(`${m.vendor}: ${resource}'s refresh detail names ${scope.detail}, no operation of the surface`);
-                const id = mapId ?? storedIdOf(decl, item);
+                const id = mapId ?? storedIdOf(decl, { ...under?.params, ...item });
+                // the item's own id names it in the detail's path where its stored id is a composite key (a Cloudflare
+                // script stored `<account>/<name>` is read at `/scripts/{script_name}` by its name)
+                const own = item[decl.idAs ?? 'id'];
                 const path = `${detail.basePath ?? surface.basePath ?? ''}${detail.path}`.replace(/\{([^}]+)\}/g, (_, n: string) => {
-                  const value = under?.params[n] ?? item[n] ?? id;
+                  const value = under?.params[n] ?? item[n] ?? (decl.key && (typeof own === 'string' || typeof own === 'number') ? own : id);
                   if (value === undefined) throw new Error(`${m.vendor}: ${resource}'s refresh detail has no value for ${n}`);
                   return encodeURIComponent(String(value));
                 });
@@ -655,8 +719,10 @@ function refreshOf(units: Unit[], service: string): NonNullable<StateSystemAdapt
               // twin_local_ports) is the answering World's, never the vendor's, and is not folded in
               const local = (m as { worldFields?: Record<string, Record<string, unknown>> }).worldFields?.[resource] ?? {};
               const vendorShape = Object.fromEntries(Object.entries(full).filter(([k]) => !(k in local)));
-              const fields = { ...vendorShape, ...kept, ...(decl.parent && parent !== undefined ? { [decl.parent.field]: parent } : {}) };
-              const id = mapId ?? scopeIdOf(scope, fields) ?? storedIdOf(decl, fields);
+              const fields = { ...vendorShape, ...(!decl.shared ? tenantBinding : {}), ...kept, ...(decl.parent && parent !== undefined ? { [decl.parent.field]: parent } : {}) };
+              // a key part the item does not carry is the path parameter its parent was listed under (Cloudflare's secret,
+              // `{account_id}/{script_name}::{name}`, listed as its name and type alone)
+              const id = mapId ?? scopeIdOf(scope, fields) ?? storedIdOf(decl, { ...under?.params, ...fields });
               if (id === undefined) continue;
               observed.push({ type, id, fields: fields as ObservedResource['fields'] });
             }
@@ -717,7 +783,7 @@ function refreshOf(units: Unit[], service: string): NonNullable<StateSystemAdapt
         // a type under a parent is whole only for the parents observed: what it held under another parent stands. A root
         // scoped to one resource (`RootConfig.scope`, GitHub's `repos/o/r`) lists only what is under it, so a type with no
         // parent is never the account's whole list there
-        if (whole && !decl.parent && !opts.scope) complete.push(type);
+        if (whole && !decl.parent && !opts.scope) complete.push(m.refreshIdentity && m.tenant && !decl.shared ? { type, field: m.tenant.field, within: [String(tenantBinding[m.tenant.field])] } : type);
         else if (whole && parents.length && decl.parent) complete.push({ type, field: decl.parent.field, within: parents.map((p) => p!.value) });
       }
     }
@@ -814,7 +880,7 @@ async function refreshGraphql(m: DerivedManifest, resource: string, decl: Resour
       const items = listed(value).map(object).filter((x): x is Row => x !== undefined);
       for (const item of items) {
         const fields = { ...item, ...(decl.parent && under ? { [decl.parent.field]: under.value } : {}) };
-        const id = storedIdOf(decl, fields);
+        const id = storedIdOf(decl, { ...under?.params, ...fields });
         if (id !== undefined) observed.push({ type, id, fields: fields as ObservedResource['fields'] });
       }
       taken += items.length;

package/src/derived.ts

@@ -9,6 +9,7 @@ import { parseExactJson } from './exact-json.ts';
 import type { WebSocketUpgrade } from './serve-http.ts';
 import type { TwinStream } from './twin-fetch.ts';
 import { runWithRequestTrace } from './trace-context.ts';
+import { redisServiceTimes } from './redis/service-times.ts';
 
 /** The slice of a generated surface the dispatch reads. */
 export type DerivedOperation = {
@@ -29,6 +30,8 @@ export type DerivedOperation = {
   emptySuccess?: boolean;
   /** a form-encoded operation's number and boolean fields, by bracket path (`items.[].quantity`, `metadata.*`) */
   scalars?: Readonly<Record<string, string | undefined>>;
+  /** a form-encoded operation's string fields that take only listed values, by the same bracket path */
+  enums?: Readonly<Record<string, ReadonlyArray<string>>>;
   /** what the success answer is: a resource, a list of them, and the envelope key holding it */
   answers?: { resource: string; list: boolean; key?: string };
   /** the path its own server puts before it, where the operation names a server other than the surface's */
@@ -47,7 +50,10 @@ export type 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> };
+export type DerivedCall = { request: Request; operation: DerivedOperation; params: Record<string, string>;
+  /** a World screen's call, which no perform sends again: a body in a media type the core does not read (anything
+   *  but JSON, a form, multipart or text) is the handler's alone, left unread and unrecorded, so an upload streams */
+  streamed?: true };
 
 /**
  * A request's body as text, read once per request: the dispatch reads it and tags the request with it, and every clone
@@ -285,7 +291,9 @@ export function createDerivedFetch(options: DerivedFetchOptions): DerivedFetch {
     if (!matched) return fallback(request, undefined, 'no operation at this path');
     for (const observer of dispatchObservers ?? []) observer({ surface: options.surface, operation: matched.operation, owner: handlers[matched.operation.id] ? 'handler' : options.core?.owns(matched.operation) ? 'core' : 'gap' });
     // the body read once, as text, for everything the dispatch does with it (bodyTextOf)
+    redisServiceTimes.lap('6a around entered, guards and scenario passed, operation matched again');
     if (request.method !== 'GET' && request.method !== 'HEAD' && request.body && !(request.headers.get('content-type') ?? '').includes('multipart')) tagBody(request, await request.clone().text());
+    redisServiceTimes.lap('6b the dispatch read the body as 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 ? { ...(parseExactJson(prefixed) as Record<string, string>), ...matched.params } : matched.params };

package/src/executor.ts

@@ -78,6 +78,10 @@ export type TwinAuthStrategy =
      *  it replaces. The kernel keeps the new value for its next exchange and hands the updated credential to the
      *  root's custody to seal (`onRotate`), so the root outlives the first refresh token. */
     rotate?: { answer: string; credential: string };
+    /** The answer's field giving the token's lifetime in seconds (a dotted path; OAuth's `expires_in`): a token held past
+     *  it is exchanged again before the next call. For a vendor that answers an expired token with no `retryOn` status
+     *  (TikTok's API for Business answers HTTP 200 with a code), and so a long-lived process never sends a dead token. */
+    expiresIn?: string;
   };
 
 async function oauth1SignedHeader(credential: CredentialPayload, method: string, target: URL, headers: Headers, body?: string | Uint8Array): Promise<string> {
@@ -248,7 +252,9 @@ async function awsSigV4Headers(input: {
  *  refused, as before. */
 /** Where a credential is kept (the head's and refresh's root: head.ts rootCustody): `key` names the credential stably
  *  across rotations and anew when another is sealed in its place (the token cache is keyed by it, not by the secret's value), `open` reads it as sealed now, `seal` keeps a rotated one. */
-export type CredentialCustody = { key: string; open: () => Promise<CredentialPayload>; seal: (credential: CredentialPayload) => Promise<void> | void };
+/** `unsealed`: where a rotation the seal failed to keep is recorded durably (the field and the cause, never a value), since
+ *  the root cannot renew once the process holding the new secret ends; a later successful seal clears it. */
+export type CredentialCustody = { key: string; open: () => Promise<CredentialPayload>; seal: (credential: CredentialPayload) => Promise<void> | void; unsealed?: (field: string, cause: string) => 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). */
 /** `now`: the instant a signature is made at (the wall clock unless given: an acceptance whose vendor is a fixture World
@@ -418,7 +424,7 @@ function direct(origin: URL, credential: CredentialPayload, auth?: Exclude<TwinA
 /** Tokens the exchange strategy holds, per root and credential, for the life of the process: an executor
  *  is built per deploy and per refresh, so a token kept only inside one would cost a fresh exchange on every
  *  write (Bluesky allows 30 sessions in five minutes). In memory only; never written anywhere. */
-const exchangedTokens = new Map<string, { token: Promise<string> }>();
+const exchangedTokens = new Map<string, { token: Promise<string>; expiresAt?: number }>();
 /** A rotated credential a seal failed to keep, per custody key: the process spends it (never the spent one the file
  *  still holds) until a seal succeeds or the file moves past the value it replaced. In memory only. */
 const unsealedRotations = new Map<string, { replaced: string; credential: CredentialPayload }>();
@@ -442,6 +448,7 @@ function exchangeExecute(origin: URL, sealed: CredentialPayload, auth: Extract<T
     return held;
   };
   const key = custody ? `${origin.href}\n${custody.key}` : `${origin.href}\n${JSON.stringify(sealed)}`;
+  let expiresAt: number | undefined;
   const exchange = async (): Promise<string> => {
     // a rotating secret is read as kept NOW (another executor or process may have rotated it since this one was
     // built), or as this process holds it when its seal failed and the file still holds the spent value. Two
@@ -473,6 +480,11 @@ function exchangeExecute(origin: URL, sealed: CredentialPayload, auth: Extract<T
       const code = parsed && typeof parsed === 'object' ? (parsed as Record<string, unknown>).error : undefined;
       throw new Error(`remote execute: the token exchange answered no \`${auth.token}\`${typeof code === 'string' && code !== '' ? ` (${code.slice(0, 120)})` : ''}`);
     }
+    if (auth.expiresIn) {
+      const seconds = Number(auth.expiresIn.split('.').reduce<unknown>((at, k) => (at && typeof at === 'object' ? (at as Record<string, unknown>)[k] : undefined), parsed));
+      // a minute short of the stated lifetime, so a call in flight never carries a token that dies on the way
+      expiresAt = Number.isFinite(seconds) && seconds > 0 ? Date.now() + Math.max(0, seconds - 60) * 1000 : undefined;
+    }
     if (auth.rotate) {
       const next = auth.rotate.answer.split('.').reduce<unknown>((at, k) => (at && typeof at === 'object' ? (at as Record<string, unknown>)[k] : undefined), parsed);
       if (typeof next === 'string' && next !== '' && next !== credential[auth.rotate.credential]) {
@@ -483,6 +495,7 @@ function exchangeExecute(origin: URL, sealed: CredentialPayload, auth: Extract<T
         if (custody) {
           try { await custody.seal(credential); unsealedRotations.delete(key); } catch (error) {
             unsealedRotations.set(key, { replaced, credential });
+            try { custody.unsealed?.(auth.rotate.credential, error instanceof Error ? error.message : String(error)); } catch { /* the stderr line below still says it */ }
             console.error(`remote execute: the vendor rotated \`${auth.rotate.credential}\` and sealing the new one failed (${error instanceof Error ? error.message : String(error)}); this process holds it until a seal succeeds`);
           }
         }
@@ -492,12 +505,13 @@ function exchangeExecute(origin: URL, sealed: CredentialPayload, auth: Extract<T
   };
   const current = (): { token: Promise<string> } => {
     let held = exchangedTokens.get(key);
+    if (held?.expiresAt !== undefined && Date.now() >= held.expiresAt) { exchangedTokens.delete(key); held = undefined; }
     if (!held) {
       const token = exchange();
       held = { token };
       exchangedTokens.set(key, held);
       const entry = held;
-      token.catch(() => { if (exchangedTokens.get(key) === entry) exchangedTokens.delete(key); });
+      token.then(() => { entry.expiresAt = expiresAt; }, () => { if (exchangedTokens.get(key) === entry) exchangedTokens.delete(key); });
     }
     return held;
   };

package/src/fork.ts

@@ -76,7 +76,7 @@ export function forkTwin(opts: {
   };
   getActiveWorldStore().write(forkMetaPath(service, toRoot), `${JSON.stringify(meta, null, 2)}\n`);
   return meta;
-  });
+  }, { operation: 'pointer publication' });
 }
 
 export function readForkMeta(service: string, root: string): ForkMeta {

package/src/git/lfs.ts

@@ -9,7 +9,14 @@ import { exactInteger } from '../exact-json.ts';
 export const LFS_TYPE = 'application/vnd.git-lfs+json';
 export type LfsObject = { oid: string; size: number | string };
 /** Where a pack keeps its objects: by oid. */
-export type LfsStore = { get(oid: string): Promise<Uint8Array | null>; put(oid: string, bytes: Uint8Array): Promise<void> };
+/** Where a server keeps its LFS objects: an object's size when it holds one (the batch API answers from it, never
+ *  loading the object), and the store an upload's verified bytes go to. */
+export type LfsStore = {
+  size(oid: string): Promise<number | null>; put(oid: string, bytes: Uint8Array): Promise<void>;
+  /** an upload's body written as it arrives and kept only when `accept` holds for its size and SHA-256 (`ctx.blobs.putStream`):
+   *  a store with it never holds an object whole */
+  putStream?(oid: string, chunks: AsyncIterable<Uint8Array>, accept: (written: { size: number; sha256: string }) => boolean): Promise<boolean>;
+};
 
 const OID = /^[0-9a-f]{64}$/;
 const lfsJson = (status: number, body: unknown): Response => Response.json(body, { status, headers: { 'content-type': LFS_TYPE } });
@@ -48,21 +55,45 @@ export async function lfsBatch(body: unknown, opts: { store: LfsStore; href: (op
     const o = { oid: String(raw?.oid ?? ''), size: /^-?\d+$/.test(String(raw?.size)) ? exactInteger(String(raw?.size)) : Number(raw?.size) };
     // source: https://github.com/git-lfs/git-lfs/blob/main/docs/api/batch.md "The object is invalid (for example, an invalid oid or size)."
     if (!OID.test(o.oid) || !Number.isSafeInteger(o.size) || Number(o.size) < 0) { objects.push({ ...o, error: { code: 422, message: 'Invalid object' } }); continue; }
-    const held = await opts.store.get(o.oid);
+    const held = await opts.store.size(o.oid);
     if (operation === 'upload') {
-      objects.push(held ? { ...o, authenticated: true } : { ...o, authenticated: true, actions: { upload: { href: opts.href('upload', o), ...(opts.header ? { header: opts.header } : {}), expires_in: 3600 } } });
+      objects.push(held !== null ? { ...o, authenticated: true } : { ...o, authenticated: true, actions: { upload: { href: opts.href('upload', o), ...(opts.header ? { header: opts.header } : {}), expires_in: 3600 } } });
     } else {
       // source: https://github.com/git-lfs/git-lfs/blob/main/docs/api/batch.md "The object does not exist on the server."
-      objects.push(held ? { oid: o.oid, size: held.length, authenticated: true, actions: { download: { href: opts.href('download', o), ...(opts.header ? { header: opts.header } : {}), expires_in: 3600 } } } : { ...o, error: { code: 404, message: 'Object does not exist' } });
+      objects.push(held !== null ? { oid: o.oid, size: held, authenticated: true, actions: { download: { href: opts.href('download', o), ...(opts.header ? { header: opts.header } : {}), expires_in: 3600 } } } : { ...o, error: { code: 404, message: 'Object does not exist' } });
     }
   }
   return lfsJson(200, { transfer: 'basic', objects, hash_algo: 'sha256' });
 }
 
 /** A basic transfer's upload (`PUT` of the object's bytes): kept when they hash to the oid and have the declared size
- *  (the size is the request's Content-Length when the caller has no other), else refused and nothing kept. */
-export async function lfsUpload(bytes: Uint8Array, o: LfsObject, store: LfsStore): Promise<Response> {
-  if (bytes.length !== o.size || (await lfsOid(bytes)) !== o.oid) return lfsJson(422, { message: `the object's bytes do not match ${o.oid} (${o.size} bytes)` });
-  await store.put(o.oid, bytes);
-  return new Response(null, { status: 200 });
+ *  (the size is the request's Content-Length when the caller has no other), else refused and nothing kept. A body
+ *  stream goes to the store's `putStream` as it arrives, read no further than the declared size; bytes, or a store
+ *  without one, are checked whole. */
+export async function lfsUpload(body: Uint8Array | ReadableStream<Uint8Array> | null, o: LfsObject, store: LfsStore): Promise<Response> {
+  const refused = (): Response => lfsJson(422, { message: `the object's bytes do not match ${o.oid} (${o.size} bytes)` });
+  if (body instanceof Uint8Array || body === null || !store.putStream) {
+    const bytes = body instanceof Uint8Array ? body : new Uint8Array(body === null ? new ArrayBuffer(0) : await new Response(body).arrayBuffer());
+    if (bytes.length !== o.size || (await lfsOid(bytes)) !== o.oid) return refused();
+    await store.put(o.oid, bytes);
+    return new Response(null, { status: 200 });
+  }
+  const declared = Number(o.size);
+  let over = false;
+  async function* upTo(stream: ReadableStream<Uint8Array>): AsyncGenerator<Uint8Array> {
+    const reader = stream.getReader();
+    let read = 0;
+    try {
+      for (;;) {
+        const { done, value } = await reader.read();
+        if (done) return;
+        read += value.byteLength;
+        // a body longer than declared is refused without reading the rest of it
+        if (read > declared) { over = true; await reader.cancel(); return; }
+        yield value;
+      }
+    } finally { reader.releaseLock(); }
+  }
+  const kept = await store.putStream(o.oid, upTo(body), (w) => !over && w.size === declared && w.sha256 === o.oid);
+  return kept ? new Response(null, { status: 200 }) : refused();
 }

package/src/grpc-wire.ts

@@ -7,6 +7,7 @@ import { parseExactJson } from './exact-json.ts';
 // and what they answer is the pack's. Importing it does nothing.
 import { acceptH2Connection, type H2Handler } from './h2.ts';
 import { nodeBuiltin, WORLD_BOOT_PATH } from './serve-http.ts';
+import { worldBootAnswer } from './world-boot.ts';
 import { decodeMessage, encodeMessage, type ProtoSchema } from './protobuf.ts';
 
 /** gRPC's status codes (https://grpc.github.io/grpc/core/md_doc_statuscodes.html). */
@@ -151,7 +152,7 @@ export function grpcOverFetch(fetch: (request: Request) => Promise<Response>): G
 export async function serveGrpc(options: { port?: number; fetch: (request: Request) => Promise<Response>; schema: ProtoSchema }): Promise<{ port: number; stop: () => void }> {
   const net = nodeBuiltin<typeof import('node:net')>('node:net');
   const worldBoot = (globalThis as { process?: { env?: Record<string, string | undefined> } }).process?.env?.VOLTER_WORLD_BOOT_ID;
-  const fetch = worldBoot ? (request: Request) => (new URL(request.url).pathname === WORLD_BOOT_PATH ? Promise.resolve(Response.json({ boot: worldBoot })) : options.fetch(request)) : options.fetch;
+  const fetch = worldBoot ? (request: Request) => (new URL(request.url).pathname === WORLD_BOOT_PATH ? Promise.resolve(worldBootAnswer(worldBoot)) : options.fetch(request)) : options.fetch;
   const handler = grpcStreamHandler(options.schema, grpcOverFetch(fetch));
   const server = net.createServer((socket) => { acceptH2Connection(socket, handler, fetch); });
   await new Promise<void>((resolve, reject) => { server.once('error', reject); server.listen(options.port ?? 0, '127.0.0.1', () => resolve()); });

package/src/h2.ts

@@ -25,6 +25,36 @@ const MAX_CONCURRENT_STREAMS = 1000;
 /** a request body larger than this resets its stream: a memory bound, not Temporal's message limit (the
  *  SDKs' gRPC default is 4 MiB; this server does not enforce that one) */
 const MAX_REQUEST_BYTES = 64 * 1024 * 1024;
+
+/** A chunked body (RFC 9112 §7.1) from `from`: its bytes once the last chunk and the trailer section have arrived,
+ *  'incomplete' before, 'bad' for a malformed size line or one past MAX_REQUEST_BYTES. Extensions and trailers are
+ *  read past and not kept. */
+function chunkedBody(buffer: Buffer, from: number): Uint8Array | 'incomplete' | 'bad' {
+  const parts: Buffer[] = [];
+  let at = from, total = 0;
+  for (;;) {
+    const line = buffer.indexOf('\r\n', at);
+    if (line < 0) return buffer.length - at > 4096 ? 'bad' : 'incomplete';
+    const size = /^([0-9A-Fa-f]{1,8})[ \t]*(?:;.*)?$/su.exec(buffer.subarray(at, line).toString('latin1'));
+    if (!size) return 'bad';
+    const length = parseInt(size[1]!, 16);
+    at = line + 2;
+    if (length === 0) break;
+    total += length;
+    if (total > MAX_REQUEST_BYTES) return 'bad';
+    if (buffer.length < at + length + 2) return 'incomplete';
+    if (buffer[at + length] !== 0x0d || buffer[at + length + 1] !== 0x0a) return 'bad';
+    parts.push(buffer.subarray(at, at + length));
+    at += length + 2;
+  }
+  // The trailer section: field lines up to an empty line.
+  for (;;) {
+    const line = buffer.indexOf('\r\n', at);
+    if (line < 0) return buffer.length - at > 64 * 1024 ? 'bad' : 'incomplete';
+    if (line === at) return Buffer.concat(parts);
+    at = line + 2;
+  }
+}
 /** a header block (HEADERS + CONTINUATION) larger than this closes the connection */
 const MAX_HEADER_BLOCK = 256 * 1024;
 
@@ -293,11 +323,22 @@ class H2Connection {
       this.respondHttp1(new Response('bad header', { status: 400 }));
       return;
     }
-    if (headers.get('transfer-encoding')) { this.respondHttp1(new Response('chunked request bodies are not accepted', { status: 411 })); return; }
-    const length = Number(headers.get('content-length') ?? 0);
-    if (!Number.isFinite(length) || length < 0 || length > MAX_REQUEST_BYTES) { this.respondHttp1(new Response('bad content-length', { status: 400 })); return; }
-    if (this.buffer.length < end + 4 + length) return;
-    const body = this.buffer.subarray(end + 4, end + 4 + length);
+    // A request with a Transfer-Encoding has a body framed by it, and its Content-Length is not read (RFC 9112 §6.3):
+    // undici sends a streamed body (a World's fetch forwarding a request's own body, duplex 'half') chunked.
+    const coding = headers.get('transfer-encoding');
+    let body: Uint8Array;
+    if (coding !== null) {
+      if (coding.split(',').map((each) => each.trim().toLowerCase()).at(-1) !== 'chunked') { this.respondHttp1(new Response('a transfer coding other than chunked is not read', { status: 400 })); return; }
+      const read = chunkedBody(this.buffer, end + 4);
+      if (read === 'bad') { this.respondHttp1(new Response('bad chunked body', { status: 400 })); return; }
+      if (read === 'incomplete') return;
+      body = read;
+    } else {
+      const length = Number(headers.get('content-length') ?? 0);
+      if (!Number.isFinite(length) || length < 0 || length > MAX_REQUEST_BYTES) { this.respondHttp1(new Response('bad content-length', { status: 400 })); return; }
+      if (this.buffer.length < end + 4 + length) return;
+      body = this.buffer.subarray(end + 4, end + 4 + length);
+    }
     this.buffer = Buffer.alloc(0);
     this.socket.removeAllListeners('data');
     let request: Request;

package/src/head.ts

@@ -156,7 +156,10 @@ export async function resealRootCredential(root: BoundRoot, payload: CredentialP
   // read and write are synchronous: nothing comes between this check and the write
   if (store.read(root.credential) !== held) throw new Error(`the ${vendor} credential was set again while it rotated: the rotation is dropped`);
   store.write(root.credential, `${JSON.stringify({ ...sealed, ...(before ? { fingerprint: before.fingerprint } : {}), rotatedAt: now }, null, 2)}\n`, { secret: true });
+  store.remove(unsealedMarkerOf(root));
 }
+/** Beside a root's credential, the record of a rotation its seal failed to keep (`rootCustody`'s `unsealed`). */
+export function unsealedMarkerOf(root: BoundRoot): string { return root.credential.replace(/\.json$/, '.unsealed.json'); }
 /** The root's custody for an exchange that rotates: the credential as sealed now, and the seal of a rotated one, which
  *  lands only over the record that was opened. */
 export function rootCustody(root: BoundRoot, vendor: string = vendorOf(root)): CredentialCustody {
@@ -175,6 +178,9 @@ export function rootCustody(root: BoundRoot, vendor: string = vendorOf(root)): C
       return opened.payload;
     },
     seal: (credential) => resealRootCredential(root, credential, vendor, source),
+    // the vendor already spent the sealed secret: until a seal lands, the root renews only inside the process holding the
+    // new one, so the World keeps a record a person or `doctor` can read after that process ends
+    unsealed: (field, cause) => store.write(unsealedMarkerOf(root), `${JSON.stringify({ vendor, field, at: new Date().toISOString(), cause: cause.slice(0, 300) }, null, 2)}\n`),
   };
 }
 /** The vendor a root belongs to: its credential is sealed under the vendor's name. */
@@ -461,6 +467,15 @@ async function performNow(opts: Parameters<typeof performEntries>[0]): Promise<D
  * `auto` is performed now. Returns the vendor's id when it minted one, so the answer carries it.
  * Raises `RefusedWriteError` / `VendorWriteError` for the pack to answer in the vendor's shape.
  */
+/** Whether `performAtHead` would perform an entry now (a twin whose root says `auto`, outside a pack fetch's deferred
+ *  group): a caller appending several writes at once appends them one at a time then, each performed before the next. */
+export function performsAtHeadNow(service: string, root?: string): boolean {
+  const request = currentCorrelationId();
+  if (request !== undefined && deferred.has(request)) return false;
+  const head = headOf(service, root);
+  return head.kind === 'real' && head.deploy === 'auto';
+}
+
 export async function performAtHead(service: string, action: Pick<TwinAction, 'id'>, root?: string): Promise<{ performed: boolean; externalId?: string; data?: unknown }> {
   // a pack fetch performs its request's entries as one group after the handler (performRequestGroup)
   const request = currentCorrelationId();

package/src/history.ts

@@ -91,14 +91,14 @@ export function saveHistoryView(directory: string, view: HistoryView): string {
     getActiveWorldStore().writeAtomic(file, JSON.stringify({ ...view, dependencies }));
     for (const dependency of dependencies) commitParentPin(dependency.directory, file);
     return id;
-  });
+  }, { operation: 'view pin publication' });
 }
 /** What an inherited history's content stands on, as file facts: every segment file the view names
  *  (and the view document itself) and each named directory's ancestry record (its generation). A read cache keyed by this sees an
  *  ancestor's retained history truncated, replaced or its directory re-created, which the full read
  *  refuses (`historyEntries`), instead of serving a tree folded from the history it replaced. */
-export function inheritedHistoryKey(service: string, root?: string): string {
-  const parent = readBranchMeta(service, root)?.parent;
+export function inheritedHistoryKey(service: string, root?: string, meta?: string | null): string {
+  const parent = readBranchMeta(service, root, meta)?.parent;
   if (!parent?.view) return '';
   const store = getActiveWorldStore();
   const fact = (path: string): string => { const st = store.stat(path); return st ? `${st.size}:${st.mtimeMs}` : '-'; };
@@ -136,7 +136,7 @@ export function captureHistory(service: string, root?: string): { view: string;
       if (entries.length) descriptor.segments.push({ directory, generation, file, start: 0, count: entries.length, digest: historyDigest(entries) });
     }
     return { view: saveHistoryView(directory, descriptor), position: historyLength(descriptor.layout), descriptor };
-  });
+  }, { operation: 'capture' });
 }
 export function originHead(service: string, root?: string): { view: string; remoteView: string } | null {
   const raw = getActiveWorldStore().read(join(worldPaths(service, root).dir, 'origin-head.json'));
@@ -162,7 +162,7 @@ export function publishOriginHistory(service: string, root: string, remoteView:
     const view = saveHistoryView(directory, { version: 1, owner: { directory, generation }, layout, segments });
     store.writeAtomic(join(directory, 'origin-head.json'), JSON.stringify({ view, remoteView }));
     return { view, appended };
-  });
+  }, { operation: 'origin fetch' });
 }
 
 /** A changeset binds the complete inherited view, including this root's observations. */
@@ -171,7 +171,7 @@ export function captureParentHistory(service: string, root?: string): HistoryRef
     const head = captureHistory(service, root);
     const position = head.position - head.descriptor.layout.branch;
     return { view: saveHistoryView(worldPaths(service, root).dir, historyPrefix(head.descriptor, position)), position };
-  });
+  }, { operation: 'capture' });
 }
 /** Compare evaluated views, so removals, reordered rows and layout changes count as drift. */
 export function historyChanges(service: string, before: HistoryView, after: HistoryView): Entry[] {
@@ -222,7 +222,7 @@ export function historyAtInstant(service: string, instant: string, root?: string
     }
     const view = saveHistoryView(directory, { version: 1, owner: source.owner, layout, segments, ...(source.origin ? { origin: { ...source.origin, ...(keep.slice(0, source.origin.position).some(v => !v) ? { incomplete: true } : {}) } } : {}) });
     return { view, position: historyLength(layout) };
-  });
+  }, { operation: 'capture' });
 }
 
 /** Replace only the tracked origin layer; inherited local layers keep their exact projection order. */

package/src/index.ts

@@ -53,7 +53,7 @@ export { VendorUnreachableError } from './vendor-call.ts';
 export { isReadOnlyRequest, READ_ONLY_REQUEST_HEADER } from './request-scope.ts';
 
 // ── the serve factory ──────────────────────────────────────────────────────────────────────────
-export { serveHttp, serveStream, StreamListenerUnavailable, type HttpHandler, type HttpServer, type ServeHttpOptions } from './serve-http.ts';
+export { serveHttp, serveStream, nodeBuiltin, StreamListenerUnavailable, type HttpHandler, type HttpServer, type ServeHttpOptions } from './serve-http.ts';
 export type { TwinStream, TwinStreamConnection, TwinStreamSink } from './twin-fetch.ts';
 export { privateTransportKey } from './private-transport.ts';
 // where a page links a hostname its twin answers, inside the World that shows it
@@ -79,6 +79,8 @@ export type { Batch as EngineBatch, ManagedDatabase, Statement as EngineStatemen
 export type { Mail, SmtpRoute } from './smtp.ts';
 // S3's wire (contract "S3's wire is a kernel library too") and the git plane (contract "The git plane is a kernel library")
 export * as s3 from './s3/wire.ts';
+// Generic strict XML grammar; vendor interpretation remains in its consumer.
+export * as xml from './xml.ts';
 export * as clickhouse from './clickhouse/index.ts';
 export { sampleFromSchema } from './schema-sample.ts';
 export * as openaiWire from './openai-wire.ts';
@@ -91,6 +93,7 @@ export { presignSigV4, signSigV4, verifySigV4, type SigV4Verdict } from './sigv4
 export * as redis from './redis/index.ts';
 export * as mysql from './mysql/index.ts';
 export * as live from './live/index.ts';
+export * as mongodb from './mongodb/index.ts';
 export * as git from './git/index.ts';
 
 // ── the scenario grammar (architecture, "Behaviour") ───────────────────────────────────────────
@@ -103,3 +106,6 @@ export { browserSessionToken, startBrowserSession, endBrowserSession } from './b
 
 export { readHostPort } from './host-port.ts';
 export { assertBrowserName, browserOrigin, validateBrowserState, validateBrowserStorageState, validateBrowserContext, browserAcceptLanguage, cookieMatchesHost, type BrowserCookie, type BrowserState, type BrowserStorageState, type BrowserContext, type BrowserIndexedDB } from './browser-state.ts';
+
+export * as managedOriginalInputs from './managed-original-inputs.ts';
+export * as managedGoPrograms from './managed-go-programs.ts';