@volter/world-core 2.0.36 → 3.0.0

package/src/machines.ts

@@ -0,0 +1,151 @@
+// The World's machine pool (architecture, "Other wires: … machines"): what runs a vendor's customer's image when the
+// vendor is one that runs images (Fly's Machines). It is a platform provider enrolled through the kernel's door
+// `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.
+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 }> };
+/** 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 MachinePool = {
+  readonly kind: 'docker' | 'none' | 'fake';
+  /** 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>;
+  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 }>;
+};
+export const MACHINE_POOL = '_machine_pool';
+export const POOL_KINDS = ['docker', 'none', 'fake'] as const;
+
+/** 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. */
+const containerName = (world: string, name: string): string => `volter-world-machine-${world}-${name.replace(/[^A-Za-z0-9_.-]/g, '-')}`;
+
+// an image's pull is the slow step: a run may take two minutes before the pool gives up; anything else, thirty seconds
+const RUN_TIMEOUT_MS = 120_000;
+const STEP_TIMEOUT_MS = 30_000;
+
+function dockerPool(world: string): MachinePool {
+  // asynchronous, so a pull never holds the World's other requests (or a socket's heartbeats) behind it
+  const docker = (args: string[], timeout = STEP_TIMEOUT_MS): Promise<string> => new Promise((resolve, reject) => {
+    const { execFile } = nodeBuiltin<typeof import('node:child_process')>('node:child_process');
+    execFile('docker', args, { encoding: 'utf8', timeout }, (error, stdout, stderr) => (error ? reject(new Error(String(stderr || error.message).trim())) : resolve(String(stdout).trim())));
+  });
+  return {
+    kind: 'docker',
+    async run(spec) {
+      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}`]);
+      const ports = (spec.ports ?? []).flatMap((p) => ['-p', `127.0.0.1::${p}`]);
+      await docker(['run', '-d', '--name', name, ...env, ...ports, spec.image, ...(spec.command ?? [])], RUN_TIMEOUT_MS);
+      const published: MachineRun['ports'] = [];
+      for (const internal of spec.ports ?? []) {
+        const line = (await docker(['port', name, String(internal)])).split('\n')[0] ?? '';
+        published.push({ internal, host: Number(line.split(':').at(-1)) });
+      }
+      return { ports: published };
+    },
+    async exec(name, spec) {
+      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
+      const child = spawn('docker', ['exec', '-i', ...env, ...(spec.cwd ? ['-w', spec.cwd] : []), containerName(world, name), 'sh', '-c', 'echo "@pid $$"; exec "$@"', 'sh', ...spec.args], { stdio: ['ignore', 'pipe', 'pipe'] });
+      const queue: Array<{ stdout?: string } | { stderr?: string } | { exit: number }> = [];
+      let wake: (() => void) | undefined;
+      let done = false;
+      let pid: number | undefined;
+      let head = '';
+      let stderr = '';
+      let settle: { resolve: (n: number) => void; reject: (e: Error) => void } | undefined;
+      const pidKnown = new Promise<number>((resolve, reject) => { settle = { resolve, reject }; child.on('error', reject); });
+      const push = (e: (typeof queue)[number]): void => { queue.push(e); wake?.(); };
+      child.stdout!.setEncoding('utf8').on('data', (chunk: string) => {
+        if (pid === undefined) {
+          // the pid line may arrive split across chunks: nothing is output until its newline is read
+          head += chunk;
+          const nl = head.indexOf('\n');
+          if (nl < 0) return;
+          const m = /^@pid (\d+)$/.exec(head.slice(0, nl));
+          if (!m) { push({ stdout: head }); head = ''; return; }
+          pid = Number(m[1]);
+          settle?.resolve(pid);
+          chunk = head.slice(nl + 1);
+          head = '';
+        }
+        if (chunk) push({ stdout: chunk });
+      });
+      child.stderr!.setEncoding('utf8').on('data', (chunk: string) => { if (pid === undefined) stderr += chunk; push({ stderr: chunk }); });
+      child.on('close', (code, signal) => {
+        // a machine the pool does not run (docker exec fails before the shell starts) rejects, with docker's words
+        if (pid === undefined) settle?.reject(new Error(stderr.trim() || `the process did not start (exit ${code ?? signal})`));
+        // a process ended by a signal exits as a shell reports it: 128 and the signal's number
+        const signals: Record<string, number> = { SIGHUP: 1, SIGINT: 2, SIGQUIT: 3, SIGKILL: 9, SIGTERM: 15 };
+        push({ exit: code ?? (signal ? 128 + (signals[signal] ?? 0) : 0) });
+        done = true; wake?.();
+      });
+      const events: MachineProcess['events'] = {
+        async *[Symbol.asyncIterator]() {
+          for (;;) {
+            while (queue.length) { const e = queue.shift()!; yield e; if ('exit' in e) return; }
+            if (done) return;
+            await new Promise<void>((r) => { wake = r; });
+          }
+        },
+      };
+      let timer: ReturnType<typeof setTimeout> | undefined;
+      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 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 {
+  if (kind === 'docker') return dockerPool(world);
+  if (kind === 'fake') {
+    const asked: NonNullable<MachinePool['asked']> = [];
+    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 exec(name, spec) {
+        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 }); },
+    };
+  }
+  return {
+    kind: 'none', async run() { return { ports: [] }; },
+    async exec() { throw new Error('no machine runs in this World: its machine pool is none'); },
+    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}`;
+  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'));
+    pools.set(key, pool);
+  }
+  return pool;
+}

package/src/managed-database.ts

@@ -0,0 +1,299 @@
+// THE WORLD'S MANAGED DATABASE, as a pack reaches it (architecture.md, "The engine slot" and managed infrastructure): a
+// vendor whose data plane is a server in front of Postgres (Supabase's PostgREST, Storage and Auth; a Neon or a
+// PlanetScale) serves it over the World's own Postgres, whose URL the runtime hands the pack (the descriptor's
+// `managedDatabase`: `serve --database <url>`, or the colocated host's `database` option). A protocol-3 handler reaches
+// it as `ctx.engine`; a pack's own server in front of it (a PostgREST) through `managedDatabase(url)`. Its terms:
+//
+// - Nothing here reads the environment, and the tree references none of the rows it writes.
+// - Each batch is ONE transaction sent as ONE extended-protocol pipeline ending in ONE Sync: `BEGIN`, the role
+//   (`SET LOCAL ROLE`), the transaction-local settings (`set_config(…, true)`), the statements and `COMMIT`, every value a
+//   bind parameter. The PGlite host runs a connection's messages up to its Sync under one lock and lets another
+//   connection's read into a session idle inside a transaction; a batch that never sits idle inside its transaction lets
+//   nobody in, so its role and settings reach no other connection.
+// - The role, which Postgres takes only as SQL text, is quoted as an identifier; which roles a caller may take is the
+//   pack's rule (Supabase's three API roles), checked before a batch is made.
+// - A batch that fails leaves its transaction aborted (the backend skips to the Sync); it is ended with `ROLLBACK` before
+//   the connection is released, and a connection that cannot be rolled back is destroyed, never reused.
+//
+// The Postgres driver is node-postgres (`pg`), loaded the first time a database is bound and installed by the package that
+// declares a managed database (its package.json): the kernel's dependencies are zod and ws alone (architecture B1), and a
+// browser bundle imports the kernel without a database. A host may register another (`useDatabaseDriver`).
+
+/** One statement of a batch; `values` travel as bind parameters (text, or null), never in the SQL text. */
+export type Statement = { text: string; values?: ReadonlyArray<string | null> };
+
+/** What one statement answered: its columns and rows in Postgres's text format, and its command tag. */
+export type StatementResult = { fields: string[]; rows: Array<Array<string | null>>; command: string };
+
+/** A Postgres error as the backend reported it (SQLSTATE and its fields), what a vendor's server passes through. */
+export class EngineDatabaseError extends Error {
+  readonly code: string;
+  readonly detail: string | null;
+  readonly hint: string | null;
+  constructor(message: string, fields: { code?: string; detail?: string; hint?: string }) {
+    super(message);
+    this.name = 'EngineDatabaseError';
+    this.code = fields.code ?? 'XX000';
+    this.detail = fields.detail ?? null;
+    this.hint = fields.hint ?? null;
+  }
+}
+
+/** The World's database cannot be reached: none is bound, or it does not answer. */
+export class EngineUnavailableError extends Error {
+  constructor(message: string) { super(message); this.name = 'EngineUnavailableError'; }
+}
+
+/** One transaction: as `role` (none: the twin's own login role, the vendor's servers' own work), with transaction-local
+ *  `settings` (`request.jwt.claims`, `search_path`), READ ONLY when `readOnly` (a write is refused by Postgres itself,
+ *  25006), ended with ROLLBACK when `rollback` (a permission probe asked of Postgres and undone). */
+export type Batch = { role?: string; settings?: Record<string, string>; readOnly?: boolean; rollback?: boolean; statements: Statement[] };
+
+export interface ManagedDatabase {
+  /** Whether the World binds a database at all (a World with none refuses every batch). */
+  readonly bound: boolean;
+  /** 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, '""')}"`;
+}
+
+type BackendMessage = { fields?: unknown; text?: string };
+type PgConnection = {
+  parse(query: { text: string; types: number[] }): void;
+  bind(config: { values: ReadonlyArray<string | null> }): void;
+  describe(message: { type: 'P' }): void;
+  execute(config: { rows: number }): void;
+  sync(): void;
+  sendCopyFail(message: string): void;
+};
+
+/** pg's Submittable (the extension point pg-cursor and pg-query-stream use): the client hands it the connection once
+ *  it is its turn, it writes every statement's Parse/Bind/Describe/Execute and ONE Sync, and the client hands it each
+ *  backend message until ReadyForQuery. */
+class Pipeline {
+  private readonly results: StatementResult[] = [];
+  private current: { fields: string[]; rows: Array<Array<string | null>> } | null = null;
+  private error: Error | null = null;
+  private settled = false;
+  constructor(private readonly statements: Statement[], private readonly done: (error: Error | null, results: StatementResult[]) => void) {}
+  submit(connection: PgConnection): void {
+    for (const statement of this.statements) {
+      connection.parse({ text: statement.text, types: [] });
+      connection.bind({ values: statement.values ?? [] });
+      connection.describe({ type: 'P' });
+      connection.execute({ rows: 0 });
+    }
+    connection.sync();
+  }
+  handleRowDescription(message: { fields: Array<{ name: string }> }): void {
+    this.current = { fields: message.fields.map((field) => field.name), rows: [] };
+  }
+  handleDataRow(message: { fields: Array<string | null> }): void {
+    (this.current ??= { fields: [], rows: [] }).rows.push(message.fields);
+  }
+  handleCommandComplete(message: BackendMessage): void {
+    this.results.push({ ...(this.current ?? { fields: [], rows: [] }), command: String(message.text ?? '') });
+    this.current = null;
+  }
+  handleEmptyQuery(): void {
+    this.results.push({ fields: [], rows: [], command: '' });
+  }
+  handlePortalSuspended(): void { /* every Execute asks for all rows */ }
+  handleCopyInResponse(connection: PgConnection): void { connection.sendCopyFail('COPY FROM STDIN is not served by a managed database batch'); }
+  handleCopyData(): void { /* no COPY is ever sent */ }
+  handleError(error: Error): void {
+    // An ErrorResponse (the backend's, with a SQLSTATE) or a failed connection. pg ends the submittable's turn here:
+    // it drops it as the active query, so the ReadyForQuery the backend sends after skipping to the Sync goes to no
+    // one, and the next query this client is given (the ROLLBACK) is sent once that ReadyForQuery arrives.
+    this.error ??= error;
+    this.finish();
+  }
+  handleReadyForQuery(): void { this.finish(); }
+  private finish(): void {
+    if (this.settled) return;
+    this.settled = true;
+    this.done(this.error, this.results);
+  }
+}
+
+function asDatabaseError(error: Error): Error {
+  const fields = error as { code?: string; detail?: string; hint?: string; severity?: string };
+  if (fields.severity === undefined) return new EngineUnavailableError(`the World's Postgres failed: ${error.message}`);
+  return new EngineDatabaseError(error.message, fields);
+}
+
+/** The part of a Postgres driver the kernel uses: node-postgres's (`pg`) Pool and its clients. */
+type PgClient = { query(query: unknown): unknown; release(error?: Error): void };
+type PgPool = { connect(): Promise<PgClient>; end(): Promise<void>; on(event: 'error', listener: (error: Error) => void): unknown };
+export type DatabaseDriver = { Pool: new (config: { connectionString: string; max: number; idleTimeoutMillis: number; connectionTimeoutMillis: number }) => PgPool };
+
+let driver: DatabaseDriver | undefined;
+
+/** A Postgres driver a host registers in place of node-postgres. */
+export function useDatabaseDriver(given: DatabaseDriver): void {
+  driver = given;
+}
+
+/** The driver: the registered one, else node-postgres, loaded on first use (a name the bundler does not resolve). */
+async function loadDriver(): Promise<DatabaseDriver> {
+  if (driver !== undefined) return driver;
+  const name = 'pg';
+  try {
+    const mod = (await import(name)) as { default?: DatabaseDriver } & DatabaseDriver;
+    driver = mod.default ?? mod;
+  } catch (error) {
+    throw new EngineUnavailableError(`no Postgres driver: node-postgres (pg) is not installed beside the pack that declares a managed database (${(error as Error).message})`);
+  }
+  return driver;
+}
+
+const pools = new Map<string, PgPool>(); // cache: one pool per bound database URL — the connections this process holds to the World's Postgres, never state
+
+async function poolFor(url: string): Promise<PgPool> {
+  let pool = pools.get(url);
+  if (pool === undefined) {
+    const { Pool } = await loadDriver();
+    // another request may have made it while the driver loaded
+    const made = pools.get(url);
+    if (made !== undefined) return made;
+    // a few connections: the PGlite host serializes them anyway, and a container Postgres needs no more for a twin
+    pool = new Pool({ connectionString: url, max: 4, idleTimeoutMillis: 10_000, connectionTimeoutMillis: 10_000 });
+    // an idle connection that the database ends (a World's Postgres restarting) is dropped from the pool, not thrown
+    pool.on('error', () => {});
+    pools.set(url, pool);
+  }
+  return pool;
+}
+
+async function checkout(url: string): Promise<PgClient> {
+  const pool = await poolFor(url);
+  try {
+    return await pool.connect();
+  } catch (error) {
+    throw new EngineUnavailableError(`the World's Postgres is not answering: ${(error as Error).message}`);
+  }
+}
+
+function pipeline(client: PgClient, statements: Statement[]): Promise<{ error: Error | null; results: StatementResult[] }> {
+  return new Promise((resolve) => {
+    (client as unknown as { query: (submittable: Pipeline) => void }).query(new Pipeline(statements, (error, results) => resolve({ error, results })));
+  });
+}
+
+/** Run one transaction as one pipeline with one Sync; on failure, ROLLBACK before the connection goes back. */
+async function transaction(url: string, statements: Statement[], lead: number): Promise<StatementResult[]> {
+  const client = await checkout(url);
+  let broken: Error | undefined;
+  try {
+    const { error, results } = await pipeline(client, statements);
+    if (error !== null) {
+      if ((error as { severity?: unknown }).severity !== undefined) {
+        try { await (client.query('ROLLBACK') as Promise<unknown>); } catch (rollback) { broken = rollback as Error; }
+      } else broken = error;
+      throw asDatabaseError(error);
+    }
+    // the answer is the batch's own statements: not BEGIN, the role, the settings, or its end
+    return results.slice(lead, statements.length - 1);
+  } finally {
+    client.release(broken);
+  }
+}
+
+function settingsStatement(settings: Record<string, string>): Statement | null {
+  const names = Object.keys(settings);
+  if (names.length === 0) return null;
+  const values: string[] = [];
+  const calls = names.map((name) => {
+    values.push(name, settings[name]!);
+    return `set_config($${values.length - 1}, $${values.length}, true)`;
+  });
+  return { text: `SELECT ${calls.join(', ')}`, values };
+}
+
+/** 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 {
+  return {
+    bound: true,
+    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 head: Statement[] = [
+        { text: batch.readOnly || options.readOnly ? 'BEGIN READ ONLY' : 'BEGIN' },
+        ...(batch.role === undefined ? [] : [{ text: `SET LOCAL ROLE ${quoteIdent(batch.role)}` }]),
+        ...(set === null ? [] : [set]),
+      ];
+      return transaction(url, [...head, ...batch.statements, { text: batch.rollback ? 'ROLLBACK' : 'COMMIT' }], head.length);
+    },
+    async script(text) {
+      const client = await checkout(url);
+      let broken: Error | undefined;
+      try {
+        await (client.query(text) as Promise<unknown>);
+      } catch (error) {
+        if ((error as { severity?: unknown }).severity === undefined) broken = error as Error;
+        else { try { await (client.query('ROLLBACK') as Promise<unknown>); } catch (rollback) { broken = rollback as Error; } }
+        throw asDatabaseError(error as Error);
+      } finally {
+        client.release(broken);
+      }
+    },
+  };
+}
+
+/** 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 => {
+    throw new EngineUnavailableError(`This World binds no managed Postgres to the ${service} twin, so what it serves over one is refused, not served: add a postgres service to the World's managed infrastructure (architecture: managed infrastructure)`);
+  };
+  return { bound: false, batch: async () => refuse(), script: async () => refuse() };
+}
+
+/** Close every connection this process holds (a test's teardown; a served twin's connections end with it). */
+export async function closeManagedDatabases(): Promise<void> {
+  const held = [...pools.values()];
+  pools.clear();
+  await Promise.all(held.map((pool) => pool.end().catch(() => {})));
+}

package/src/multipart.ts

@@ -0,0 +1,51 @@
+// 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).
+
+/** 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 };
+
+/** The boundary a `multipart/form-data` content type names, or null (not multipart, or no boundary). */
+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);
+  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;
+  }
+  return -1;
+}
+
+/** 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();
+  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({
+      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),
+    });
+    at = next;
+  }
+  return parts;
+}

package/src/observe.ts

@@ -7,24 +7,27 @@
 // unchanged resource appends nothing; a listing the adapter declares complete tombstones what it
 // no longer holds. A refresh runs inside a scope that collects the adapter's observations and folds
 // them as one batch; an ingest observes directly, one resource at a time.
-import { withAncestryLock } from './ancestry.ts';
+import { withHistoryLock } from './ancestry.ts';
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { appendParentEntry, readParentTreeMap, type Entry, type Tree } from './log.ts';
 import { hashFieldValue, type SubjectFields } from './hash.ts';
 import { worldNow } from './world-clock.ts';
+import { worldPaths } from './storage.ts';
 
-export type ObservedResource = { type: string; id: string; fields: SubjectFields; deleted?: boolean };
+/** `adopts`: the local id of a subject a deploy settled with no vendor id, which this observation is (refresh's
+ *  adoption, architecture "Refresh"): the observation lands as that subject's alias, and the local one stands. */
+export type ObservedResource = { type: string; id: string; fields: SubjectFields; deleted?: boolean; adopts?: string };
 export type ObserveReport = { observed: number; appended: number; unchanged: number; removed: number };
 
 export type Observation = { service: string; root?: string } & (
   | { resource: ObservedResource }
-  | { resources: ObservedResource[]; complete?: string[] }
+  | { resources: ObservedResource[]; complete?: Completed[] }
 );
 // ONE sink per process, whichever copy of the kernel a pack resolved: a pack installed beside a
 // world carries its own `@volter/world-core`, and its observations must reach the scope the runtime
 // opened. A module-level instance would be one per copy; a process-global symbol is one per process.
 const SINK = Symbol.for('volter.observe.sink');
-// created on first use, never at import: a mirror's CLIENT bundle (target browser) carries this module
+// created on first use, never at import: a browser bundle carrying the kernel carries this module
 // through the pack's shared helpers, and a browser has no AsyncLocalStorage — constructing one at load
 // would kill the whole client ("not a constructor") for a scope the browser never opens
 const sink = (): AsyncLocalStorage<Observation[]> => ((globalThis as Record<symbol, unknown>)[SINK] ??= new AsyncLocalStorage<Observation[]>()) as AsyncLocalStorage<Observation[]>;
@@ -37,10 +40,14 @@ export async function collectObservations<T>(fn: () => Promise<T>): Promise<{ va
   return { value, observations };
 }
 
+/** 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[] };
+
 /** Fold a collected batch: one `observeResources` per service, `complete` applied to each. */
-export function foldObservations(observations: Observation[], opts: { root?: string; at?: string; complete?: string[]; batch?: string } = {}): ObserveReport {
+export function foldObservations(observations: Observation[], opts: { root?: string; at?: string; complete?: Completed[]; batch?: string } = {}): ObserveReport {
   const total: ObserveReport = { observed: 0, appended: 0, unchanged: 0, removed: 0 };
-  const groups = new Map<string, { service: string; root?: string; resources: ObservedResource[]; complete: Set<string> }>();
+  const groups = new Map<string, { service: string; root?: string; resources: ObservedResource[]; complete: Set<Completed> }>();
   for (const o of observations) {
     const root = opts.root ?? o.root;
     const key = JSON.stringify([o.service, root]);
@@ -72,9 +79,9 @@ function stable(value: unknown): string {
 }
 
 /** The fold: diff each resource against upstream state, append what changed to the root's log. `complete`
- *  names the types this batch listed in full — a subject of such a type the batch does not hold is
- *  tombstoned. Entry ids are content-addressed, so the same observation folds once. */
-export function observeResources(service: string, resources: ObservedResource[], opts: { root?: string; at?: string; complete?: string[]; batch?: string } = {}): ObserveReport {
+ *  names the types this batch listed in full (or in full under the parents it names) — a subject of such a type the
+ *  batch does not hold is tombstoned. Entry ids are content-addressed, so the same observation folds once. */
+export function observeResources(service: string, resources: ObservedResource[], opts: { root?: string; at?: string; complete?: Completed[]; batch?: string } = {}): ObserveReport {
   const collecting = typeof AsyncLocalStorage === 'function' ? sink().getStore() : undefined;
   if (collecting) {
     collecting.push({ service, resources, ...(opts.root !== undefined ? { root: opts.root } : {}), ...(opts.complete ? { complete: opts.complete } : {}) });
@@ -83,18 +90,18 @@ export function observeResources(service: string, resources: ObservedResource[],
   return foldResources(service, resources, opts);
 }
 
-function foldResources(service: string, resources: ObservedResource[], opts: { root?: string; at?: string; complete?: string[]; batch?: string }): ObserveReport {
-  return withAncestryLock(() => {
+function foldResources(service: string, resources: ObservedResource[], opts: { root?: string; at?: string; complete?: Completed[]; batch?: string }): ObserveReport {
+  return withHistoryLock(worldPaths(service, opts.root).dir, () => {
   const at = opts.at ?? worldNow();
   // one look is one batch: every entry it appends carries the same id, and no position may split it
   const batch = opts.batch ?? `obs:${service}:${at}`;
   const tree: Tree = readParentTreeMap(service, opts.root);
   const report: ObserveReport = { observed: resources.length, appended: 0, unchanged: 0, removed: 0 };
   const seen = new Set<string>();
-  const append = (subject: { type: string; id: string }, fields: SubjectFields): boolean => {
+  const append = (subject: { type: string; id: string }, fields: SubjectFields, aliasOf?: string): boolean => {
     const entry: Entry = {
-      id: `observed:${service}:${subject.type}:${subject.id}:${hashFieldValue({ subject, fields, at })}`,
-      service, op: 'set', operation: 'observed', subject, occurredAt: at, actor: { kind: 'system', id: 'vendor' }, fields, batch,
+      id: `observed:${service}:${subject.type}:${subject.id}:${hashFieldValue({ subject, fields, at, ...(aliasOf ? { aliasOf } : {}) })}`,
+      service, op: 'set', operation: 'observed', subject, occurredAt: at, actor: { kind: 'system', id: 'vendor' }, fields, batch, ...(aliasOf ? { aliasOf } : {}),
     };
     const { appended } = appendParentEntry(entry, opts.root);
     const key = `${subject.type}:${subject.id}`;
@@ -107,6 +114,12 @@ function foldResources(service: string, resources: ObservedResource[], opts: { r
   for (const r of resources) {
     const key = `${r.type}:${r.id}`;
     seen.add(key);
+    // an adoption: the vendor's subject is the local one a deploy made with no id, aliased to it
+    if (r.adopts !== undefined && !tree.has(key)) {
+      seen.add(`${r.type}:${r.adopts}`);
+      if (append({ type: r.type, id: r.id }, r.fields, r.adopts)) report.appended += 1; else report.unchanged += 1;
+      continue;
+    }
     const existing = tree.get(key);
     if (r.deleted) {
       if (existing && existing.fields.deleted !== true) { if (append({ type: r.type, id: r.id }, { deleted: true })) report.removed += 1; }
@@ -119,9 +132,12 @@ function foldResources(service: string, resources: ObservedResource[], opts: { r
     if (existing?.fields.deleted === true && Object.keys(changed).length === 0) Object.assign(changed, r.fields); // resurrected as it stands
     if (append({ type: r.type, id: r.id }, changed)) report.appended += 1; else report.unchanged += 1;
   }
-  for (const type of opts.complete ?? []) {
+  for (const c of opts.complete ?? []) {
+    const type = typeof c === 'string' ? c : c.type;
+    const within = typeof c === 'string' ? undefined : new Set(c.within);
     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 (append({ type: s.type, id: s.id }, { deleted: true })) report.removed += 1;
     }
   }