@volter/world-core 3.0.156 → 3.0.158

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

@@ -30,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 */
@@ -48,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

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/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/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. */

package/src/index.ts

@@ -108,3 +108,4 @@ 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';

package/src/live/ingest.ts

@@ -57,7 +57,6 @@ export function liveIngest<C>(options: LiveIngestOptions<C>): TwinStream {
     let priorInit: number | undefined;
     let started = false;
     let metadata: Record<string, unknown> | undefined;
-    let refusedCodec: string | undefined;
 
     const recording = (): LiveRecording => {
       const row = store.rows(LIVE).find((r) => r.id === stream)!;
@@ -135,7 +134,12 @@ export function liveIngest<C>(options: LiveIngestOptions<C>): TwinStream {
             app: ask!.app, key: ask!.key, state: 'publishing', startedAt: typeof prior?.startedAt === 'string' ? prior.startedAt : now, endedAt: null,
             publishes: Number(prior?.publishes ?? 0) + 1, window: ruling.window ?? 6, segmentSeconds: ruling.segmentSeconds ?? 2, ...(ruling.retain !== undefined ? { retain: ruling.retain } : {}),
           }, 'live.publish'));
+          // Every admitted publish has its own encoder and hook state. Continuation comes from the recording above,
+          // including on a connection reused after FCUnpublish, never from the prior publish's in-memory state.
+          initIndex = -1;
           priorInit = last?.init;
+          started = false;
+          metadata = undefined;
           segmenter = new Segmenter({ targetMs: Math.max(0.5, ruling.segmentSeconds ?? 2) * 1000, offsetMs, firstSequence: last ? last.seq + 1 : 0 });
           stream = named;
           admitted = ruling;
@@ -154,7 +158,7 @@ export function liveIngest<C>(options: LiveIngestOptions<C>): TwinStream {
       async video(timestamp, payload) {
         if (!segmenter) return;
         const tag = readVideoTag(payload);
-        if (tag.kind === 'unsupported') { if (refusedCodec !== tag.codec) log(`${stream}: ${tag.codec} video is not recorded (H.264 is)`); refusedCodec = tag.codec; return; }
+        if (tag.kind === 'unsupported') throw new RtmpRefusal('NetStream.Failed', `${tag.codec} video is not supported; publish H.264.`);
         const s = segmenter;
         if (tag.kind === 'config') await keepAll(s.videoConfig(tag.config));
         else if (tag.kind === 'frame') await keepAll(overrun(() => s.videoFrame(timestamp, tag.key, tag.cts, tag.data)));
@@ -162,7 +166,7 @@ export function liveIngest<C>(options: LiveIngestOptions<C>): TwinStream {
       async audio(timestamp, payload) {
         if (!segmenter) return;
         const tag = readAudioTag(payload);
-        if (tag.kind === 'unsupported') { if (refusedCodec !== tag.codec) log(`${stream}: ${tag.codec} audio is not recorded (AAC is)`); refusedCodec = tag.codec; return; }
+        if (tag.kind === 'unsupported') throw new RtmpRefusal('NetStream.Failed', `${tag.codec} audio is not supported; publish AAC.`);
         const s = segmenter;
         if (tag.kind === 'config') await keepAll(s.audioConfig(tag.config));
         else await keepAll(overrun(() => s.audioFrame(timestamp, tag.data)));

package/src/live/rtmp.ts

@@ -124,6 +124,9 @@ export function rtmpSession(sink: TwinStreamSink, publisher: RtmpPublisher, log:
     chunks.clear();
     current = undefined;
     held = 0;
+    // A refused/ended transport owns the publish's cleanup too. An admission already awaiting the dialect settles
+    // first; messages queued behind the refusal cannot admit a new publish on the closed connection.
+    chain = chain.then(() => stop()).catch((error) => log(`the publish's end failed: ${String((error as Error)?.message ?? error)}`));
     try { sink.end(); } catch { /* the peer is gone */ }
   };
   /** A connection past a ceiling: said once, and closed. */
@@ -175,6 +178,7 @@ export function rtmpSession(sink: TwinStreamSink, publisher: RtmpPublisher, log:
         try { refusal = await publisher.publish({ app, name: named, ...(type !== undefined ? { type } : {}), ...(tcUrl !== undefined ? { tcUrl } : {}), ...(flashVer !== undefined ? { flashVer } : {}) }); }
         catch (error) { log(`publish failed: ${String((error as Error)?.message ?? error)}`); refusal = { code: 'NetStream.Publish.Denied', description: 'The server could not take the stream.' }; }
         if (refusal) { status(stream, 'error', refusal.code, refusal.description, named); close(); return; }
+        ended = false;
         publishing = true;
         publishStream = stream;
         // user control StreamBegin (event 0) for the publish's stream, then its start
@@ -257,7 +261,7 @@ export function rtmpSession(sink: TwinStreamSink, publisher: RtmpPublisher, log:
     const message: Message = { type: st.type, streamId: st.streamId, timestamp: st.timestamp, payload };
     queued += payload.length;
     if (queued > MAX_QUEUED) { overrun(`more than ${MAX_QUEUED} bytes of messages wait to be recorded`); return; }
-    chain = chain.then(() => (phase === 'closed' && message.type !== 20 ? undefined : onMessage(message))).catch((error) => {
+    chain = chain.then(() => (phase === 'closed' ? undefined : onMessage(message))).catch((error) => {
       log(`a message failed: ${String((error as Error)?.message ?? error)}`);
       close();
     }).finally(() => { queued -= payload.length; });
@@ -366,10 +370,8 @@ export function rtmpSession(sink: TwinStreamSink, publisher: RtmpPublisher, log:
     // message's bytes are not in it: only more bytes finish it, and what it may hold is bounded (MAX_HELD)
     backlog: () => queued + pending.length,
     close() {
-      clearTimeout(deadline);
-      // the connection ended: a publish still open ends with it, after every message already read
-      chain = chain.then(() => stop()).catch((error) => log(`the publish's end failed: ${String((error as Error)?.message ?? error)}`));
-      phase = 'closed';
+      // Peer close and server refusal share one end, after any admission or write already under way settles.
+      close();
     },
   };
 }

package/src/live/segmenter.ts

@@ -64,14 +64,20 @@ export class Segmenter {
     this.avc = config;
     this.freshInit = true;
     this.keyed = false;
+    this.unkeyedSince = undefined;
     return out;
   }
 
   audioConfig(config: AacConfig): Cut[] {
     if (this.aac && same(this.aac.asc, config.asc)) return [];
-    const out = this.aac ? this.flush() : [];
+    const out = this.flush();
     this.aac = config;
     this.freshInit = true;
+    // A configuration boundary has no running video segment. Its first frame must be a new keyframe, and the
+    // audio sample clock belongs to the new configuration (which may have a different sample rate).
+    this.keyed = false;
+    this.unkeyedSince = undefined;
+    this.audioNext = undefined;
     return out;
   }
 

package/src/machines.ts

@@ -6,6 +6,7 @@
 // is reached only when a compute pool is asked to act. The light pool delegates to the host's Substrate adapter.
 import { refuseReadOnlyWrite } from './request-scope.ts';
 import { nodeBuiltin } from './serve-http.ts';
+import { refuseRequiredMachineTransport } from '../required-credential-transport.cjs';
 
 export type MachineSpec = { name: string; image: string; env?: Record<string, string>; ports?: number[]; command?: string[]; checks?: Array<{ port: number; type: 'http' | 'tcp'; path?: string }>; resetOnStop?: boolean; mounts?: Array<{ name: string; path: string }>; signal?: AbortSignal; startTimeoutMs?: number };
 export type GuestImage = { context: string; dockerfile?: string; runtime?: 'node' | 'bun' | 'python' | 'deno'; command?: string[]; cwd?: string; env?: Record<string, string>; prepared?: boolean };
@@ -94,6 +95,7 @@ function dockerPool(world: string): MachinePool {
   });
   return {
     kind: 'docker',
+    async admitRun() { refuseRequiredMachineTransport(process.env, 'Docker machine application transport'); },
     async status(name) {
       const state = JSON.parse(await docker(['inspect', '--format', '{{json .State}}', containerName(world, name)]));
       return state.Running ? { state: 'started' } : { state: 'exited', exitCode: state.ExitCode, ...(state.Error ? { reason: state.Error } : {}) };
@@ -101,6 +103,7 @@ function dockerPool(world: string): MachinePool {
     async ports() { throw new Error('port discovery requires the light guest backing'); },
     async files() { throw new Error('file access requires the light guest backing'); },
     async run(spec) {
+      refuseRequiredMachineTransport(process.env, 'Docker machine application transport');
       const name = containerName(world, spec.name);
       await docker(['rm', '-f', name]).catch(() => undefined);
       const env = Object.entries(spec.env ?? {}).flatMap(([k, v]) => ['-e', `${k}=${v}`]);
@@ -114,6 +117,7 @@ function dockerPool(world: string): MachinePool {
       return { ports: published };
     },
     async exec(name, spec) {
+      refuseRequiredMachineTransport(process.env, 'Docker machine exec transport');
       const { spawn } = nodeBuiltin<typeof import('node:child_process')>('node:child_process');
       const env = Object.entries(spec.env ?? {}).flatMap(([k, v]) => ['-e', `${k}=${v}`]);
       // the shell names its own pid first, then becomes the process: its pid is the process's
@@ -176,7 +180,7 @@ function dockerPool(world: string): MachinePool {
       return fetch(`http://127.0.0.1:${host}${source.pathname}${source.search}`, { method: request.method, headers, body, redirect: 'manual', signal: request.signal });
     },
     async pause(name) { await docker(['pause', containerName(world, name)]); },
-    async resume(name) { await docker(['unpause', containerName(world, name)]); },
+    async resume(name) { refuseRequiredMachineTransport(process.env, 'Docker machine resume transport'); await docker(['unpause', containerName(world, name)]); },
     async stop(name) { await docker(['stop', containerName(world, name)]).catch(() => undefined); },
     async remove(name) { await docker(['rm', '-f', containerName(world, name)]).catch(() => undefined); },
   };