@volter/world-core 3.0.38 → 3.0.40

package/src/machines.ts

@@ -3,27 +3,80 @@
 // `POST /_twin/machine-pool`, recorded in the pack's own tree; a handler reaches it as `ctx.machines`. `docker` runs
 // each machine as a local container with its internal ports published on loopback; `none` runs nothing; `fake`
 // records what it was asked (capability verification). Nothing here runs at module scope, and `node:child_process`
-// is reached only when a docker pool is asked to act.
+// 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';
 
-export type MachineSpec = { name: string; image: string; env?: Record<string, string>; ports?: number[]; command?: string[] };
-export type MachineRun = { ports: Array<{ internal: number; host: number }> };
+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 };
+export type LightPoolOptions = { images?: Record<string, GuestImage> };
+export type MachineRun = { ports: Array<{ internal: number; host: number; url?: string }> };
+export type MachineStatus = { state: 'started' | 'paused' | 'stopped' | 'exited' | 'failed'; exitCode?: number; reason?: string };
+export type MachineFileStat = { type: 'file' | 'directory'; size: number; mode: number; mtime: string };
+export type MachineFiles = {
+  read(path: string): Promise<Uint8Array>;
+  write(path: string, bytes: Uint8Array): Promise<unknown>;
+  list(path: string): Promise<Array<{ name: string; type: 'file' | 'directory'; size: number }>>;
+  mkdir(path: string): Promise<unknown>;
+  remove(path: string): Promise<unknown>;
+  stat(path: string): Promise<MachineFileStat>;
+};
 /** A process started in a machine: its pid, and what it writes and how it ends, as they happen. */
 export type MachineProcess = { pid: number; events: AsyncIterable<{ stdout?: string } | { stderr?: string } | { exit: number }> };
 export type ExecSpec = { args: string[]; env?: Record<string, string>; cwd?: string };
+export type MachineHttpReply = { port: number; method: string; path: string; requestText?: string; status: number; headers?: Record<string, string>; body?: string };
 export type MachinePool = {
-  readonly kind: 'docker' | 'none' | 'fake';
+  readonly kind: 'docker' | 'none' | 'fake' | 'light';
+  /** Optional capability admission, before vendor resource creation; starts no process. */
+  admitRun?(spec: MachineSpec): Promise<void>;
   /** runs the image; a failure (no container runtime, an image that will not start) rejects with the runtime's message */
   run(spec: MachineSpec): Promise<MachineRun>;
   /** starts a process in a running machine; a machine the pool does not run rejects */
   exec(name: string, spec: ExecSpec): Promise<MachineProcess>;
+  request(name: string, port: number, request: Request): Promise<Response>;
+  /** Undefined means the metadata-only/fake backing has no process lifecycle to observe. */
+  status(name: string): Promise<MachineStatus | undefined>;
+  ports(name: string): Promise<number[]>;
+  files(name: string): Promise<MachineFiles>;
+  pause(name: string): Promise<void>;
+  resume(name: string): Promise<void>;
   stop(name: string): Promise<void>;
   remove(name: string): Promise<void>;
   /** the fake pool's record of what it was asked */
-  readonly asked?: Array<{ act: 'run' | 'exec' | 'stop' | 'remove'; name: string; spec?: MachineSpec; exec?: ExecSpec }>;
+  readonly asked?: Array<{ act: 'run' | 'exec' | 'request' | 'pause' | 'resume' | 'stop' | 'remove'; name: string; spec?: MachineSpec; exec?: ExecSpec; port?: number; path?: string; requestText?: string }>;
 };
+/** A declared compute capability gap, distinct from a failed admitted guest. */
+export function isMachineCapabilityGap(error: unknown): boolean {
+  return typeof error === 'object' && error !== null && 'code' in error && error.code === 'WORLD_MACHINE_CAPABILITY_GAP';
+}
 export const MACHINE_POOL = '_machine_pool';
-export const POOL_KINDS = ['docker', 'none', 'fake'] as const;
+export const POOL_KINDS = ['docker', 'none', 'fake', 'light'] as const;
+
+/** The host owns provider bootstrapping. Browser/kernel imports stay inert, and a missing
+ * host provider refuses rather than falling back to metadata-only success. */
+function lightPool(world: string, root: string | undefined, options: LightPoolOptions): MachinePool {
+  let ready: Promise<MachinePool> | undefined;
+  const load = (): Promise<MachinePool> => ready ??= (async () => {
+    const entry = typeof process === 'undefined' ? undefined : process.env.VOLTER_WORLD_GUEST_RUNNER;
+    if (!entry) throw new Error('light guest runner is unavailable: run this twin inside a World');
+    const provider = await import(entry);
+    return provider.createLightGuestPool({ world, root, ...options }) as MachinePool;
+  })();
+  return {
+    kind: 'light',
+    admitRun: async (spec) => { await (await load()).admitRun?.(spec); },
+    run: async (spec) => (await load()).run(spec),
+    exec: async (name, spec) => (await load()).exec(name, spec),
+    request: async (name, port, request) => (await load()).request(name, port, request),
+    status: async (name) => (await load()).status(name),
+    ports: async (name) => (await load()).ports(name),
+    files: async (name) => (await load()).files(name),
+    pause: async (name) => (await load()).pause(name),
+    resume: async (name) => (await load()).resume(name),
+    stop: async (name) => (await load()).stop(name),
+    remove: async (name) => (await load()).remove(name),
+  };
+}
 
 /** A container's name for a machine: the World's prefix, the World's own mark (a machine id repeats across Worlds and
  *  branches, which mint alike), then the vendor's machine name made safe for docker. */
@@ -41,6 +94,12 @@ function dockerPool(world: string): MachinePool {
   });
   return {
     kind: 'docker',
+    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 } : {}) };
+    },
+    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) {
       const name = containerName(world, spec.name);
       await docker(['rm', '-f', name]).catch(() => undefined);
@@ -105,47 +164,110 @@ function dockerPool(world: string): MachinePool {
       const timeout = new Promise<number>((_, reject) => { timer = setTimeout(() => reject(new Error('the process did not start')), STEP_TIMEOUT_MS); });
       try { return { pid: await Promise.race([pidKnown, timeout]), events }; } finally { clearTimeout(timer); }
     },
+    async request(name, port, request) {
+      if (!Number.isInteger(port) || port < 1 || port > 65535) throw new Error('invalid machine port');
+      const line = (await docker(['port', containerName(world, name), String(port)])).split('\n')[0] ?? '';
+      const host = Number(line.split(':').at(-1));
+      if (!Number.isInteger(host) || host < 1 || host > 65535 || !line.startsWith('127.0.0.1:')) throw new Error('the machine port is not published on loopback');
+      const source = new URL(request.url);
+      const headers = new Headers(request.headers);
+      for (const key of ['host', 'connection', 'content-length', 'transfer-encoding']) headers.delete(key);
+      const body = ['GET', 'HEAD'].includes(request.method) ? undefined : await request.clone().arrayBuffer();
+      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 stop(name) { await docker(['stop', containerName(world, name)]).catch(() => undefined); },
     async remove(name) { await docker(['rm', '-f', containerName(world, name)]).catch(() => undefined); },
   };
 }
 
 /** The pool of a kind, for a World (`world`: the mark its containers carry). */
-export function machinePool(kind: MachinePool['kind'], world = 'world'): MachinePool {
+export function machinePool(kind: MachinePool['kind'], world = 'world', httpReplies: readonly MachineHttpReply[] = [], light: LightPoolOptions = {}, root?: string): MachinePool {
+  if (kind === 'light') return lightPool(world, root, light);
   if (kind === 'docker') return dockerPool(world);
   if (kind === 'fake') {
     const asked: NonNullable<MachinePool['asked']> = [];
+    const running = new Map<string, { ports: number[]; paused: boolean }>();
     return {
       kind, asked,
-      async run(spec) { asked.push({ act: 'run', name: spec.name, spec }); return { ports: (spec.ports ?? []).map((internal) => ({ internal, host: 40_000 + internal })) }; },
+      async status() { return undefined; },
+      async ports(name) { return running.get(name)?.ports ?? []; },
+      async files() { throw new Error('the fake pool has no filesystem'); },
+      async run(spec) { running.set(spec.name, { ports: spec.ports ?? [], paused: false }); asked.push({ act: 'run', name: spec.name, spec }); return { ports: (spec.ports ?? []).map((internal) => ({ internal, host: 40_000 + internal })) }; },
       async exec(name, spec) {
+        if (!running.has(name) || running.get(name)!.paused) throw new Error('the fake machine is not running');
         asked.push({ act: 'exec', name, exec: spec });
         // a fake process: its pid the count of processes asked, and it ends at once
         const pid = asked.filter((a) => a.act === 'exec').length + 100;
         return { pid, events: (async function* () { yield { exit: 0 }; })() };
       },
-      async stop(name) { asked.push({ act: 'stop', name }); },
-      async remove(name) { asked.push({ act: 'remove', name }); },
+      async request(name, port, request) {
+        const machine = running.get(name);
+        if (!machine || machine.paused || !machine.ports.includes(port)) throw new Error('the fake machine port is not running');
+        const url = new URL(request.url), path = url.pathname + url.search;
+        const requestText = ['GET', 'HEAD'].includes(request.method) ? '' : await request.clone().text();
+        asked.push({ act: 'request', name, port, path, requestText });
+        const reply = httpReplies.find((r) => r.port === port && r.method === request.method && r.path === path && (r.requestText === undefined || r.requestText === requestText));
+        if (!reply) throw new Error('no fake HTTP reply matches');
+        return new Response(reply.body ?? null, { status: reply.status, headers: reply.headers });
+      },
+      async pause(name) { if (!running.has(name)) throw new Error('no fake machine'); running.get(name)!.paused = true; asked.push({ act: 'pause', name }); },
+      async resume(name) { if (!running.has(name)) throw new Error('no fake machine'); running.get(name)!.paused = false; asked.push({ act: 'resume', name }); },
+      async stop(name) { running.delete(name); asked.push({ act: 'stop', name }); },
+      async remove(name) { running.delete(name); asked.push({ act: 'remove', name }); },
     };
   }
   return {
     kind: 'none', async run() { return { ports: [] }; },
+    async status() { return undefined; },
+    async ports() { throw new Error('no guest ports'); },
+    async files() { throw new Error('no guest files'); },
     async exec() { throw new Error('no machine runs in this World: its machine pool is none'); },
+    async request() { throw new Error('no machine runs in this World: its machine pool is none'); },
+    async pause() {},
+    async resume() {},
     async stop() { /* nothing runs */ }, async remove() { /* nothing runs */ },
   };
 }
 
 /** A vendor's pool in a World, one per World and kind for the life of the process (a fake pool keeps what it was asked). */
 const pools = new Map<string, MachinePool>();
-export function poolFor(service: string, root: string | undefined, kind: MachinePool['kind']): MachinePool {
-  const key = `${service}\0${root ?? ''}\0${kind}`;
+export function poolFor(service: string, root: string | undefined, kind: MachinePool['kind'], httpReplies: readonly MachineHttpReply[] = [], light: LightPoolOptions = {}): MachinePool {
+  const key = `${service}\0${root ?? ''}\0${kind}${kind === 'light' ? JSON.stringify(light) : ''}`;
   let pool = pools.get(key);
   if (!pool) {
     // the World's mark: a short digest of the vendor and the World's tree, so two Worlds' machines never share a name
     let h = 0;
     for (const ch of `${service}:${root ?? ''}`) h = (Math.imul(h, 31) + ch.charCodeAt(0)) >>> 0;
-    pool = machinePool(kind, h.toString(16).padStart(8, '0'));
+    pool = machinePool(kind, h.toString(16).padStart(8, '0'), httpReplies, light, root);
     pools.set(key, pool);
   }
   return pool;
 }
+
+/** Re-enrolling a verification pool starts a fresh fake execution record. */
+export function resetFakePool(service: string, root: string | undefined): void { pools.delete(`${service}\0${root ?? ''}\0fake`); }
+
+/** Every machine mutation shares the tree's refusal seam. HTTP/RPC reads must be explicitly
+ * classified by the pack; a computed operation may execute arbitrary guest code. */
+export function guardedMachinePool(pool: MachinePool, service: string, safeRead: boolean): MachinePool {
+  const guard = (): void => refuseReadOnlyWrite(service);
+  return {
+    kind: pool.kind, asked: pool.asked,
+    ...(pool.admitRun ? { admitRun: (spec: MachineSpec) => { guard(); return pool.admitRun!(spec); } } : {}),
+    run: (spec) => { guard(); return pool.run(spec); },
+    exec: (name, spec) => { guard(); return pool.exec(name, spec); },
+    request: (name, port, request) => { if (!safeRead) guard(); return pool.request(name, port, request); },
+    status: (name) => pool.status(name),
+    ports: (name) => pool.ports(name),
+    files: async (name) => {
+      const files = await pool.files(name);
+      return { ...files, write: (path, bytes) => { guard(); return files.write(path, bytes); }, mkdir: (path) => { guard(); return files.mkdir(path); }, remove: (path) => { guard(); return files.remove(path); } };
+    },
+    pause: (name) => { guard(); return pool.pause(name); },
+    resume: (name) => { guard(); return pool.resume(name); },
+    stop: (name) => { guard(); return pool.stop(name); },
+    remove: (name) => { guard(); return pool.remove(name); },
+  };
+}

package/src/managed-database.ts

@@ -52,47 +52,15 @@ export type Batch = { role?: string; settings?: Record<string, string>; readOnly
 export interface ManagedDatabase {
   /** Whether the World binds a database at all (a World with none refuses every batch). */
   readonly bound: boolean;
+  /** The URL the World binds it at, what an application connects to (a credential door's database URL); none when
+   *  unbound. */
+  readonly url?: string;
   /** One transaction as one pipeline and one Sync; the answer is the batch's own statements', in order. */
   batch(batch: Batch): Promise<StatementResult[]>;
   /** A whole SQL script as one simple Query (a vendor's migrations, several statements to a file). */
   script(text: string): Promise<void>;
 }
 
-/** The transaction-local setting every batch a handler makes carries: the World clock at the call (ctx.occurredAt). */
-export const WORLD_CLOCK_SETTING = 'volter.world_clock';
-
-/** The World clock inside the database, for the schemas a vendor lays (its migrations stamp rows with Postgres's
- *  `now()`, which reads the wall clock): `volter.now()`, the World clock the batch set or the wall clock where none is
- *  set, and every column default in `schemas` that reads `now()` or `CURRENT_TIMESTAMP` (alone or inside an expression,
- *  GoTrue's `timezone('utc', now())`) rewritten to read it. Run after the schemas are laid; running it again changes
- *  nothing. A trigger or function that calls `now()` itself is the pack's to redefine. */
-export function worldClockSql(schemas: string[]): string {
-  const list = schemas.map((s) => `'${s.replace(/'/g, "''")}'`).join(', ');
-  return `CREATE SCHEMA IF NOT EXISTS volter;
-CREATE OR REPLACE FUNCTION volter.now() RETURNS timestamptz LANGUAGE sql STABLE AS $fn$
-  SELECT coalesce(nullif(current_setting('${WORLD_CLOCK_SETTING}', true), '')::timestamptz, pg_catalog.now())
-$fn$;
-GRANT USAGE ON SCHEMA volter TO PUBLIC;
-GRANT EXECUTE ON FUNCTION volter.now() TO PUBLIC;
-DO $do$
-DECLARE d record; rewritten text;
-BEGIN
-  FOR d IN
-    SELECT n.nspname AS schema, c.relname AS tbl, a.attname AS col, pg_get_expr(ad.adbin, ad.adrelid) AS expr
-    FROM pg_attrdef ad
-    JOIN pg_class c ON c.oid = ad.adrelid
-    JOIN pg_namespace n ON n.oid = c.relnamespace
-    JOIN pg_attribute a ON a.attrelid = ad.adrelid AND a.attnum = ad.adnum
-    WHERE n.nspname IN (${list}) AND c.relkind IN ('r', 'p')
-      AND pg_get_expr(ad.adbin, ad.adrelid) ~* '(^|[^.[:alnum:]_])(now\\(\\)|current_timestamp)'
-  LOOP
-    rewritten := regexp_replace(d.expr, '(^|[^.[:alnum:]_])(now\\(\\)|current_timestamp)', '\\1volter.now()', 'gi');
-    EXECUTE format('ALTER TABLE %I.%I ALTER COLUMN %I SET DEFAULT %s', d.schema, d.tbl, d.col, rewritten);
-  END LOOP;
-END
-$do$;`;
-}
-
 /** Quote an identifier the way Postgres's quote_ident does for a name that needs it. */
 export function quoteIdent(name: string): string {
   return `"${name.replace(/"/g, '""')}"`;
@@ -252,14 +220,13 @@ function settingsStatement(settings: Record<string, string>): Statement | null {
 }
 
 /** The World's Postgres at `url` (the runtime's binding, never the environment); with `readOnly`, every transaction is
- *  READ ONLY whatever the batch asks (a read-only twin or request: Postgres itself refuses a write, 25006); with `clock`,
- *  every batch carries the World clock as `volter.world_clock`. */
-export function managedDatabase(url: string, options: { readOnly?: boolean; clock?: string } = {}): ManagedDatabase {
+ *  READ ONLY whatever the batch asks (a read-only twin or request: Postgres itself refuses a write, 25006). */
+export function managedDatabase(url: string, options: { readOnly?: boolean } = {}): ManagedDatabase {
   return {
     bound: true,
+    url,
     async batch(batch) {
-      // the World clock at the call, which volter.now() and the defaults worldClockSql rewrote read
-      const set = settingsStatement({ ...(options.clock !== undefined ? { [WORLD_CLOCK_SETTING]: options.clock } : {}), ...(batch.settings ?? {}) });
+      const set = settingsStatement(batch.settings ?? {});
       const head: Statement[] = [
         { text: batch.readOnly || options.readOnly ? 'BEGIN READ ONLY' : 'BEGIN' },
         ...(batch.role === undefined ? [] : [{ text: `SET LOCAL ROLE ${quoteIdent(batch.role)}` }]),
@@ -283,6 +250,47 @@ export function managedDatabase(url: string, options: { readOnly?: boolean; cloc
   };
 }
 
+/** One connection of an application's own to the World's Postgres (a journey's SQL steps: twin-standard
+ *  walk/journey-kit.ts), its statements sent as its client sends them: a text alone as one simple Query (a migration
+ *  file, a `BEGIN`), a text with values as one extended-protocol statement, the values bind parameters. A transaction it
+ *  opens stays open across its statements until it ends it, as on the application's own connection. Each statement's
+ *  answer is its results in Postgres's text format, untyped. */
+export type DatabaseSession = { query(text: string, values?: ReadonlyArray<string | null>): Promise<StatementResult[]>; end(): Promise<void> };
+
+type PgResult = { command?: string | null; rowCount?: number | null; fields?: Array<{ name: string }>; rows?: Array<Array<string | null>> };
+
+/** The World's Postgres at `url` as one connection held until `end()`. */
+export async function databaseSession(url: string): Promise<DatabaseSession> {
+  const { Pool } = await loadDriver();
+  const pool = new Pool({ connectionString: url, max: 1, idleTimeoutMillis: 0, connectionTimeoutMillis: 10_000 });
+  pool.on('error', () => {});
+  let client: PgClient;
+  try { client = await pool.connect(); } catch (error) {
+    await pool.end().catch(() => {});
+    throw new EngineUnavailableError(`the World's Postgres is not answering: ${(error as Error).message}`);
+  }
+  // every value as the wire carries it: a row an array of texts, no type parsed
+  const raw = { getTypeParser: () => (value: string) => value };
+  return {
+    async query(text, values) {
+      try {
+        const answer = (await (client.query({ text, ...(values === undefined ? {} : { values }), rowMode: 'array', types: raw }) as Promise<PgResult | PgResult[]>));
+        return (Array.isArray(answer) ? answer : [answer]).map((r) => ({
+          fields: (r.fields ?? []).map((f) => f.name),
+          rows: r.rows ?? [],
+          command: [r.command ?? '', r.command === 'INSERT' ? '0' : '', r.rowCount ?? ''].filter((part) => part !== '').join(' '),
+        }));
+      } catch (error) {
+        throw asDatabaseError(error as Error);
+      }
+    },
+    async end() {
+      client.release();
+      await pool.end().catch(() => {});
+    },
+  };
+}
+
 /** A handler's database when the World binds none: every use is the refusal naming what to add. */
 export function unboundDatabase(service: string): ManagedDatabase {
   const refuse = (): never => {

package/src/multipart.ts

@@ -1,51 +1,126 @@
-// A multipart/form-data body's parts, read from its bytes (RFC 7578): the one reading every pack's uploads go through.
-// A runtime's own form parser is not used: Bun's drops a part whose field name is empty, which a browser's or
-// supabase-js's Blob upload sends. Dependency-free and side-effect free (a browser bundle imports it).
+// The one MIME multipart reader for requests and published examples. Dependency-free, side-effect-free and
+// byte-preserving: a browser bundle imports it, and empty field names and binary uploads must survive reading.
 
-/** One part: its field name (possibly empty), its filename when it is a file, its media type as sent, its bytes. */
 export type MultipartPart = { name: string; filename: string | null; type: string | null; body: Uint8Array };
+export type MultipartFramedPart = MultipartPart & {
+  headers: Uint8Array; leading: Uint8Array; separator: Uint8Array; trailing: Uint8Array;
+};
+export type MultipartEnvelope = {
+  complete: boolean; preamble: Uint8Array; epilogue: Uint8Array;
+  delimiters: Uint8Array[]; parts: MultipartFramedPart[];
+};
 
-/** The boundary a `multipart/form-data` content type names, or null (not multipart, or no boundary). */
+/** The boundary named by any multipart media type. */
 export function multipartBoundary(contentType: string | null | undefined): string | null {
-  if (!contentType || !/^multipart\/form-data/i.test(contentType)) return null;
-  const hit = /boundary=(?:"([^"]+)"|([^;\s]+))/i.exec(contentType);
+  if (!contentType || !/^multipart\//i.test(contentType)) return null;
+  const hit = /\bboundary\s*=\s*(?:"([^"]+)"|([^;\s]+))/i.exec(contentType);
   return hit ? (hit[1] ?? hit[2]!) : null;
 }
 
-function indexOf(haystack: Uint8Array, needle: Uint8Array, from: number): number {
-  outer: for (let i = from; i <= haystack.length - needle.length; i += 1) {
-    for (let j = 0; j < needle.length; j += 1) if (haystack[i + j] !== needle[j]) continue outer;
-    return i;
+type Line = { at: number; end: number; after: number };
+function byteLines(bytes: Uint8Array): Line[] {
+  const lines: Line[] = [];
+  for (let at = 0; at < bytes.length;) {
+    let end = at;
+    while (end < bytes.length && bytes[end] !== 13 && bytes[end] !== 10) end++;
+    const after = end === bytes.length ? end : end + (bytes[end] === 13 && bytes[end + 1] === 10 ? 2 : 1);
+    lines.push({ at, end, after });
+    at = after;
   }
-  return -1;
+  return lines;
 }
 
-/** The parts of a body delimited by `boundary`, in order; a malformed tail ends the reading. */
-export function multipartParts(bytes: Uint8Array, boundary: string): MultipartPart[] {
-  const encoder = new TextEncoder();
+/** Used both by the byte reader and by consumers guarding placeholder spans within a part. */
+export function multipartDelimiterPattern(boundary: string): string {
+  const literal = boundary.replace(/[.*+?^$(){}|[\]\\]/g, '\\$&');
+  // Include malformed whitespace-before-close lines in the guard: they cannot be hidden in a value either.
+  return '(?:^|(?<=[\\r\\n]))--' + literal + '(?:--|[ \\t]+--)?[ \\t]*(?=\\r\\n|\\n|\\r|$)';
+}
+
+/** Infer only a boundary with a corresponding closing line; Content-Type remains authoritative when supplied. */
+export function inferMultipartBoundary(bytes: Uint8Array): string | null {
+  const decoder = new TextDecoder();
+  const lines = byteLines(bytes).map(({ at, end }) => decoder.decode(bytes.subarray(at, end)));
+  for (const line of lines) {
+    if (!line.startsWith('--')) continue;
+    const boundary = line.slice(2).replace(/[ \t]+$/, '');
+    if (boundary && lines.some((closing) => closing.replace(/[ \t]+$/, '') === '--' + boundary + '--')) return boundary;
+  }
+  return null;
+}
+
+/** Read MIME fields once, unfolding continuations for interpretation while retaining raw bytes in the envelope. */
+function mimeHeaders(raw: Uint8Array): Map<string, string> | undefined {
+  const fields = new Map<string, string>();
+  let previous: string | undefined;
+  for (const line of new TextDecoder().decode(raw).split(/\r\n|\n|\r/)) {
+    if (!line) continue;
+    if (/^[ \t]/.test(line)) {
+      if (!previous) return undefined;
+      fields.set(previous, fields.get(previous)! + ' ' + line.trim());
+    } else {
+      const field = /^([^\s:]+):[ \t]*(.*)$/.exec(line);
+      if (!field) return undefined;
+      previous = field[1]!.toLowerCase();
+      fields.set(previous, field[2]!.trim());
+    }
+  }
+  return fields;
+}
+
+/** Raw MIME framing and interpreted parts. A malformed tail ends reading and leaves `complete` false. */
+export function multipartEnvelope(bytes: Uint8Array, boundary: string): MultipartEnvelope {
+  const empty = new Uint8Array();
+  const result: MultipartEnvelope = { complete: false, preamble: bytes.slice(), epilogue: empty, delimiters: [], parts: [] };
+  const lines = byteLines(bytes);
   const decoder = new TextDecoder();
-  const delimiter = encoder.encode(`--${boundary}`);
-  const blank = encoder.encode('\r\n\r\n');
-  const parts: MultipartPart[] = [];
-  let at = indexOf(bytes, delimiter, 0);
-  while (at >= 0) {
-    const start = at + delimiter.length;
-    // `--` after the delimiter closes the body
-    if (bytes[start] === 0x2d && bytes[start + 1] === 0x2d) break;
-    const headerEnd = indexOf(bytes, blank, start);
-    if (headerEnd < 0) break;
-    const next = indexOf(bytes, delimiter, headerEnd + 4);
-    if (next < 0) break;
-    const head = decoder.decode(bytes.subarray(start, headerEnd));
-    const disposition = /content-disposition:[^\r\n]*/i.exec(head)?.[0] ?? '';
-    parts.push({
+  const prefix = '--' + boundary;
+  const hits: Array<Line & { closing: boolean; valid: boolean }> = [];
+  for (const line of lines) {
+    const text = decoder.decode(bytes.subarray(line.at, line.end));
+    if (!text.startsWith(prefix)) continue;
+    const suffix = text.slice(prefix.length);
+    const closing = /^--[ \t]*$/.test(suffix);
+    const valid = closing || /^[ \t]*$/.test(suffix);
+    if (!valid && !/^[ \t]+--[ \t]*$/.test(suffix)) continue;
+    hits.push({ ...line, closing, valid });
+    if (closing || !valid) break;
+  }
+  if (!hits.length) return result;
+  result.preamble = bytes.slice(0, hits[0]!.at);
+  result.delimiters = hits.map(({ at, end }) => bytes.slice(at, end));
+  for (let i = 0; i < hits.length - 1; i++) {
+    const current = hits[i]!;
+    const next = hits[i + 1]!;
+    if (!current.valid || current.closing || current.after === current.end || !next.valid) return result;
+    const headerLines = lines.filter((line) => line.at >= current.after && line.at < next.at);
+    const blank = headerLines.find((line) => line.at === line.end);
+    if (!blank) return result;
+    const previous = headerLines.find((line) => line.after === blank.at);
+    const headersEnd = previous?.end ?? blank.at;
+    const headers = bytes.slice(current.after, headersEnd);
+    const fields = mimeHeaders(headers);
+    if (!fields) return result;
+    const beforeNext = lines.find((line) => line.after === next.at);
+    // The line break immediately before a delimiter belongs to framing, never to the uploaded bytes.
+    const bodyEnd = Math.max(blank.after, beforeNext?.end ?? next.at);
+    const disposition = fields.get('content-disposition') ?? '';
+    result.parts.push({
       name: /\bname="([^"]*)"/i.exec(disposition)?.[1] ?? '',
       filename: /\bfilename="([^"]*)"/i.exec(disposition)?.[1] ?? null,
-      type: /content-type:\s*([^\r\n]+)/i.exec(head)?.[1]?.trim() ?? null,
-      // the CRLF before the next delimiter is the delimiter's, not the part's
-      body: bytes.slice(headerEnd + 4, next - 2),
+      type: fields.get('content-type')?.trim() ?? null,
+      body: bytes.slice(blank.after, bodyEnd), headers,
+      leading: bytes.slice(current.end, current.after), separator: bytes.slice(headersEnd, blank.after),
+      trailing: bytes.slice(bodyEnd, next.at),
     });
-    at = next;
   }
-  return parts;
+  const last = hits.at(-1)!;
+  result.complete = last.valid && last.closing;
+  if (result.complete) result.epilogue = bytes.slice(last.end);
+  return result;
+}
+
+/** The request's parts, in order, using the same framing reader as wire comparison. */
+export function multipartParts(bytes: Uint8Array, boundary: string): MultipartPart[] {
+  return multipartEnvelope(bytes, boundary).parts.map(({ name, filename, type, body }) => ({ name, filename, type, body }));
 }

package/src/observe.ts

@@ -42,7 +42,7 @@ export async function collectObservations<T>(fn: () => Promise<T>): Promise<{ va
 
 /** A type a batch listed in full: all of it, or (a type under a parent) the subjects whose `field` names one of the
  *  parents listed `within`. */
-export type Completed = string | { type: string; field: string; within: string[] };
+export type Completed = string | { type: string; field: string; within: string[] } | { type: string; ids: string[] };
 
 /** Fold a collected batch: one `observeResources` per service, `complete` applied to each. */
 export function foldObservations(observations: Observation[], opts: { root?: string; at?: string; complete?: Completed[]; batch?: string } = {}): ObserveReport {
@@ -134,10 +134,13 @@ function foldResources(service: string, resources: ObservedResource[], opts: { r
   }
   for (const c of opts.complete ?? []) {
     const type = typeof c === 'string' ? c : c.type;
-    const within = typeof c === 'string' ? undefined : new Set(c.within);
+    const within = typeof c === 'string' || !('within' in c) ? undefined : new Set(c.within);
+    // subjects read one by one (a refresh of the known): only those read are whole, an unseen one is gone
+    const ids = typeof c !== 'string' && 'ids' in c ? new Set(c.ids) : undefined;
     for (const s of tree.values()) {
       if (s.type !== type || seen.has(`${s.type}:${s.id}`) || s.fields.deleted === true) continue;
-      if (within && typeof c !== 'string' && !within.has(String(s.fields[c.field]))) continue;
+      if (within && typeof c !== 'string' && 'field' in c && !within.has(String(s.fields[c.field]))) continue;
+      if (ids && !ids.has(s.id)) continue;
       if (append({ type: s.type, id: s.id }, { deleted: true })) report.removed += 1;
     }
   }