@ultimat3/realtime 21.0.0 → 22.1.0

package/src/pg-socket.ts

@@ -2,15 +2,23 @@
 // and the SSLRequest handshake that has to happen before the first protocol byte. Bun pushes bytes
 // at handlers while the connection pulls messages, so a queue sits between them.
 
-import { ReplicationFailedError, ReplicationProtocolError } from './errors';
+import { renderThrowable } from '@ultimat3/core';
+import { ReplicationFailedError, ReplicationProtocolError, ReplicationTlsError } from './errors';
+import { judgeHandshake, parseSsl, rootCertificate, type SslMode } from './pg-tls';
 import { type PgStream, sslRequest } from './pg-wire';
 
+export type { SslMode } from './pg-tls';
+
 /** Structural view of Bun's socket, declared here so the contract does not need bun-types. */
 export interface SocketLike {
   write(data: Uint8Array): number;
   end(): void;
   upgradeTLS(options: {
-    readonly tls: { readonly serverName: string; readonly rejectUnauthorized?: boolean };
+    readonly tls: {
+      readonly serverName: string;
+      readonly rejectUnauthorized: boolean;
+      readonly ca?: string;
+    };
     readonly socket: SocketHandlers;
   }): readonly SocketLike[];
 }
@@ -21,6 +29,8 @@ export interface SocketHandlers {
   end(): void;
   drain(): void;
   error(socket: SocketLike, error: Error): void;
+  /** TLS sockets only: Bun reports the verification it did instead of acting on it. */
+  handshake?(socket: SocketLike, success: boolean, authorizationError: Error | null): void;
 }
 
 export interface BunConnect {
@@ -31,9 +41,6 @@ export interface BunConnect {
   }): Promise<SocketLike>;
 }
 
-/** `disable` never offers TLS, `prefer` accepts a refusal, `require` treats one as a failure. */
-export type SslMode = 'disable' | 'prefer' | 'require';
-
 export interface PgTarget {
   readonly host: string;
   readonly port: number;
@@ -41,10 +48,10 @@ export interface PgTarget {
   readonly user: string;
   readonly password: string | undefined;
   readonly ssl: SslMode;
+  /** `sslrootcert`: a PEM path, `'system'`, or absent for the runtime's trust store. */
+  readonly rootCert?: string | undefined;
 }
 
-const SSL_MODES = new Set<string>(['disable', 'prefer', 'require']);
-
 /** `postgres://user:pass@host:5432/db?sslmode=require`. The one place a connection URL is read. */
 export function parsePgUrl(url: string): PgTarget {
   let parsed: URL;
@@ -67,14 +74,7 @@ export function parsePgUrl(url: string): PgTarget {
       fix: 'set DATABASE_URL to postgres://user:password@host:5432/database',
     });
   }
-  const mode = parsed.searchParams.get('sslmode') ?? 'prefer';
-  if (!SSL_MODES.has(mode)) {
-    throw new ReplicationFailedError({
-      stage: 'connect',
-      detail: `sslmode=${mode} is not one of disable, prefer, require`,
-      fix: 'use ?sslmode=require for a managed database, ?sslmode=disable for a local one',
-    });
-  }
+  const { ssl, rootCert } = parseSsl(parsed.searchParams);
   const database = decodeURIComponent(parsed.pathname.replace(/^\//, ''));
   return {
     host: parsed.hostname,
@@ -82,7 +82,8 @@ export function parsePgUrl(url: string): PgTarget {
     database: database === '' ? 'postgres' : database,
     user: decodeURIComponent(parsed.username) || 'postgres',
     password: parsed.password === '' ? undefined : decodeURIComponent(parsed.password),
-    ssl: mode as SslMode,
+    ssl,
+    rootCert,
   };
 }
 
@@ -156,8 +157,24 @@ export const bunPgStream = (target: PgTarget): Promise<PgStream> =>
  * happen here rather than in the message layer.
  */
 export async function pgStreamOver(runtime: BunConnect, target: PgTarget): Promise<PgStream> {
+  // Before any socket exists: a trust anchor that cannot be read is a setting, not a connection,
+  // and refused after the connect it left the raw socket open — one descriptor per retry.
+  const ca = target.ssl === 'disable' ? undefined : await rootCertificate(target.rootCert);
   const queue = new ChunkQueue();
   let draining: (() => void) | undefined;
+  /**
+   * Set the moment the socket is upgraded. Bun keeps calling the RAW socket's handlers after
+   * `upgradeTLS` — with the ciphertext — so those handlers go deaf here, or the reader receives
+   * TLS records as protocol bytes: a read that never completes, or "closed with 2007 bytes of a
+   * partial message".
+   */
+  let upgraded = false;
+
+  const resume = (): void => {
+    const parked = draining;
+    draining = undefined;
+    parked?.();
+  };
 
   /**
    * A write parked for `drain` can never get one from a socket that is gone, so it is released
@@ -165,31 +182,35 @@ export async function pgStreamOver(runtime: BunConnect, target: PgTarget): Promi
    * side ends cleanly because an EOF that matters is already an error one layer up.
    */
   const died = (): void => {
-    const resume = draining;
-    draining = undefined;
-    resume?.();
+    resume();
     queue.end();
   };
 
+  const connectFailure = (error: Error): ReplicationFailedError =>
+    new ReplicationFailedError({
+      stage: 'connect',
+      detail: error.message,
+      fix: `open the route to ${target.host}:${target.port}, then: x doctor db`,
+    });
+
   const handlers: SocketHandlers = {
     // Copied, not retained: Bun promises nothing about the chunk's contents — or that it is even
     // the same buffer — once the handler returns, and this one outlives it in the queue.
-    data: (_socket, data) => queue.push(data.slice()),
-    close: died,
-    end: died,
+    data: (_socket, data) => {
+      if (!upgraded) queue.push(data.slice());
+    },
+    close: () => {
+      if (!upgraded) died();
+    },
+    end: () => {
+      if (!upgraded) died();
+    },
     drain: () => {
-      const resume = draining;
-      draining = undefined;
-      resume?.();
+      if (!upgraded) resume();
+    },
+    error: (_socket, error) => {
+      if (!upgraded) queue.fail(connectFailure(error));
     },
-    error: (_socket, error) =>
-      queue.fail(
-        new ReplicationFailedError({
-          stage: 'connect',
-          detail: error.message,
-          fix: `open the route to ${target.host}:${target.port}, then: x doctor db`,
-        }),
-      ),
   };
 
   let socket = await runtime.connect({
@@ -219,7 +240,86 @@ export async function pgStreamOver(runtime: BunConnect, target: PgTarget): Promi
     }
   };
 
-  if (target.ssl !== 'disable') {
+  /**
+   * The upgrade, awaited to its HANDSHAKE rather than assumed: the runtime is told never to
+   * reject (`rejectUnauthorized: false`), because libpq's `prefer` and `require` verify nothing,
+   * and `judgeHandshake` decides what its report means under the mode that was asked for. A
+   * failure is `X_REPLICATION_TLS` here, never a refused write one step later.
+   */
+  const upgrade = async (): Promise<SocketLike> => {
+    let settle: ((failure: ReplicationTlsError | undefined) => void) | undefined;
+    const handshake = new Promise<ReplicationTlsError | undefined>((resolve) => {
+      settle = resolve;
+    });
+    const decide = (failure: ReplicationTlsError | undefined): void => {
+      const once = settle;
+      settle = undefined;
+      once?.(failure);
+    };
+    const lost = (detail: string): ReplicationTlsError =>
+      new ReplicationTlsError({
+        detail,
+        fix: `confirm ${target.host}:${target.port} is postgres with ssl=on, or use ?sslmode=disable if it does not speak TLS`,
+      });
+    const tlsHandlers: SocketHandlers = {
+      data: (_socket, data) => queue.push(data.slice()),
+      close: () => {
+        decide(lost('the server closed the connection during the TLS handshake'));
+        died();
+      },
+      end: () => {
+        decide(lost('the server ended the connection during the TLS handshake'));
+        died();
+      },
+      drain: resume,
+      error: (_socket, error) => {
+        decide(lost(`the TLS handshake failed: ${renderThrowable(error)}`));
+        queue.fail(connectFailure(error));
+      },
+      handshake: (_socket, _success, authorizationError) =>
+        decide(judgeHandshake(target, authorizationError)),
+    };
+    upgraded = true;
+    // Bun hands back `[raw, tls]`; every later read and write goes through the second one.
+    const tls = socket.upgradeTLS({
+      tls: {
+        serverName: target.host,
+        rejectUnauthorized: false,
+        ...(ca === undefined ? {} : { ca }),
+      },
+      socket: tlsHandlers,
+    })[1];
+    if (tls === undefined) {
+      throw new ReplicationFailedError({
+        stage: 'ssl',
+        detail: 'the runtime returned no TLS socket for the upgrade',
+        fix: 'bun upgrade   # in-band TLS needs bun >= 1.3',
+      });
+    }
+    const failure = await handshake;
+    if (failure !== undefined) {
+      tls.end();
+      throw failure;
+    }
+    return tls;
+  };
+
+  // Every refusal below owns the socket it opened: the caller never receives a stream to close.
+  try {
+    await negotiate();
+  } catch (failure) {
+    socket.end();
+    throw failure;
+  }
+
+  return {
+    read: () => queue.read(),
+    write: flush,
+    close: () => socket.end(),
+  };
+
+  async function negotiate(): Promise<void> {
+    if (target.ssl === 'disable') return;
     await flush(sslRequest());
     const answer = (await queue.read()) ?? new Uint8Array(0);
     const verdict = answer[0];
@@ -240,29 +340,15 @@ export async function pgStreamOver(runtime: BunConnect, target: PgTarget): Promi
           fix: 'point the replication URL at postgres itself — a proxy answers like this',
         });
       }
-      // Bun hands back `[raw, tls]`; every later read and write goes through the second one, and
-      // the handlers are re-registered because the upgraded socket is a different object.
-      const upgraded = socket.upgradeTLS({ tls: { serverName: target.host }, socket: handlers })[1];
-      if (upgraded === undefined) {
-        throw new ReplicationFailedError({
-          stage: 'ssl',
-          detail: 'the runtime returned no TLS socket for the upgrade',
-          fix: 'bun upgrade   # in-band TLS needs bun >= 1.3',
-        });
-      }
-      socket = upgraded;
-    } else if (target.ssl === 'require') {
+      socket = await upgrade();
+    } else if (target.ssl !== 'allow' && target.ssl !== 'prefer') {
+      // `X_REPLICATION_FAILED`, as it always was: a server that says no is a connection outcome,
+      // and moving it to the TLS code would break whoever already matches on it.
       throw new ReplicationFailedError({
         stage: 'ssl',
-        detail: 'the server refused TLS but sslmode=require was asked for',
+        detail: `the server refused TLS but sslmode=${target.ssl} was asked for`,
         fix: `enable ssl on ${target.host}, or use ?sslmode=prefer to accept a cleartext session`,
       });
     }
   }
-
-  return {
-    read: () => queue.read(),
-    write: flush,
-    close: () => socket.end(),
-  };
 }

package/src/pg-tls.ts

@@ -0,0 +1,124 @@
+// Single responsibility: libpq's `sslmode` / `sslrootcert` semantics for the replicator's own wire
+// client — which modes exist, which of them VERIFY, what a handshake's authorization error means
+// under each, and where the trust anchor comes from. The socket mechanics are `pg-socket.ts`'s.
+
+import { renderFixShellArg, renderThrowable, stringField } from '@ultimat3/core';
+import { ReplicationFailedError, ReplicationTlsError } from './errors';
+
+/**
+ * libpq's six. `disable` never offers TLS; `allow`, `prefer` and `require` encrypt and verify
+ * NOTHING; `verify-ca` checks the chain; `verify-full` checks the chain and the host name.
+ */
+export type SslMode = 'disable' | 'allow' | 'prefer' | 'require' | 'verify-ca' | 'verify-full';
+
+const SSL_MODES: readonly SslMode[] = [
+  'disable',
+  'allow',
+  'prefer',
+  'require',
+  'verify-ca',
+  'verify-full',
+];
+
+const isSslMode = (value: string): value is SslMode =>
+  (SSL_MODES as readonly string[]).includes(value);
+
+/** A path to a PEM file, `'system'` for the runtime's store, or `undefined` for its default. */
+export interface SslSettings {
+  readonly ssl: SslMode;
+  readonly rootCert: string | undefined;
+}
+
+/**
+ * The connection URL's TLS half, with libpq's two couplings: `require` with a root certificate
+ * FILE behaves as `verify-ca` (a CA the operator named is one they meant to be checked against),
+ * and `sslrootcert=system` defaults to `verify-full` and refuses anything weaker — the system
+ * store trusts every public CA, so only the host name makes it mean anything.
+ */
+export function parseSsl(params: URLSearchParams): SslSettings {
+  const given = params.get('sslmode');
+  const rootCert = params.get('sslrootcert') ?? undefined;
+  const mode = given ?? (rootCert === 'system' ? 'verify-full' : 'prefer');
+  if (!isSslMode(mode)) {
+    throw new ReplicationFailedError({
+      stage: 'connect',
+      detail: `sslmode=${mode} is not one of ${SSL_MODES.join(', ')}`,
+      fix: 'use ?sslmode=verify-full for a managed database, ?sslmode=disable for a local one',
+    });
+  }
+  if (rootCert === 'system' && mode !== 'verify-full') {
+    throw new ReplicationFailedError({
+      stage: 'connect',
+      detail: `sslrootcert=system trusts every public CA, so sslmode=${mode} would prove nothing`,
+      fix: 'use ?sslrootcert=system&sslmode=verify-full, or name your CA: ?sslrootcert=/path/ca.crt',
+    });
+  }
+  if (mode === 'require' && rootCert !== undefined && rootCert !== 'system') {
+    return { ssl: 'verify-ca', rootCert };
+  }
+  return { ssl: mode, rootCert };
+}
+
+/** Whether a mode asks the runtime for the verification at all. */
+export const verifies = (ssl: SslMode): boolean => ssl === 'verify-ca' || ssl === 'verify-full';
+
+/** OpenSSL's code for a certificate whose chain verified but whose names do not include the host. */
+const HOST_MISMATCH = 'ERR_TLS_CERT_ALTNAME_INVALID';
+
+/**
+ * The verdict on a completed handshake. The runtime is always asked NOT to reject
+ * (`rejectUnauthorized: false`) and reports what it found instead, chain errors ahead of the host
+ * name; this decides what that report means under `ssl`. `undefined` is "carry on".
+ */
+export function judgeHandshake(
+  target: { readonly ssl: SslMode; readonly host: string; readonly port: number },
+  authorizationError: unknown,
+): ReplicationTlsError | undefined {
+  if (!verifies(target.ssl)) return undefined;
+  if (authorizationError === null || authorizationError === undefined) return undefined;
+  const code =
+    stringField(authorizationError, 'code') ??
+    (typeof authorizationError === 'string'
+      ? authorizationError
+      : renderThrowable(authorizationError));
+  if (code === HOST_MISMATCH) {
+    if (target.ssl === 'verify-ca') return undefined;
+    return new ReplicationTlsError({
+      detail: `the server certificate does not name ${target.host} (${code}) and sslmode=verify-full checks it`,
+      // The target's own host and port, so the pasted command reaches this server; a host a shell
+      // would misread becomes the libpq env pair instead, which a shell expands rather than runs.
+      fix: `openssl s_client -starttls postgres -connect ${renderFixShellArg(`${target.host}:${target.port}`, '"$PGHOST:$PGPORT"')} </dev/null | openssl x509 -noout -ext subjectAltName   # connect with a name it lists, or use ?sslmode=verify-ca to check the chain alone`,
+    });
+  }
+  return new ReplicationTlsError({
+    detail: `the server certificate did not verify (${code}) and sslmode=${target.ssl} checks it`,
+    fix: 'pass the server CA with ?sslrootcert=/path/to/ca.crt, or use ?sslmode=require to encrypt without verifying',
+  });
+}
+
+/**
+ * The trust anchor `upgradeTLS` gets as `ca`: a named file REPLACES the runtime store, as libpq's
+ * `root.crt` does; `system` and absent both leave the runtime's store (which honours
+ * `NODE_EXTRA_CA_CERTS`). libpq reads `~/.postgresql/root.crt` when nothing is named — a container
+ * has no such home, so this build never looks there.
+ */
+export async function rootCertificate(rootCert: string | undefined): Promise<string | undefined> {
+  if (rootCert === undefined || rootCert === 'system') return undefined;
+  const file = Bun.file(rootCert);
+  if (!(await file.exists())) {
+    throw new ReplicationTlsError({
+      detail: 'sslrootcert names a file that does not exist',
+      fix: 'mount the server CA and point ?sslrootcert= at it, or use ?sslrootcert=system for a public CA',
+    });
+  }
+  // `exists()` is not readability: a secret mounted 0600 for another user exists and still refuses
+  // the read, which escaped as a raw runtime error with no code.
+  try {
+    return await file.text();
+  } catch (error) {
+    throw new ReplicationTlsError({
+      detail: `sslrootcert names a file this process cannot read: ${renderThrowable(error)}`,
+      fix: 'id -u   # the replicator runs as this user: mount the CA readable by it, or use ?sslrootcert=system for a public CA',
+    });
+  }
+}

package/src/pg-wire.ts

@@ -36,7 +36,17 @@ const MAX_MESSAGE_BYTES = 64 * 1024 * 1024;
  */
 export class MessageReader {
   readonly #stream: PgStream;
+  /** Bytes of messages whose length is not yet known, or complete ones not yet taken. */
   #buffer: Uint8Array = new Uint8Array(0);
+  /**
+   * One message whose length IS known and whose bytes are still arriving: allocated once at its
+   * full size and filled in place. Joining every chunk onto what was held re-copied the whole
+   * message per chunk — quadratic, measured at 5.2 s of blocked event loop for one 32 MB CopyData
+   * on the replication connection every live window depends on.
+   */
+  #pending: { readonly bytes: Uint8Array; filled: number } | null = null;
+  /** Messages completed out of `#pending`, in arrival order, ahead of anything in `#buffer`. */
+  readonly #ready: Uint8Array[] = [];
 
   constructor(stream: PgStream) {
     this.#stream = stream;
@@ -44,7 +54,8 @@ export class MessageReader {
 
   /** Bytes already read but not yet consumed — what a reconnect would have to replay. */
   get buffered(): number {
-    return this.#buffer.length;
+    const ready = this.#ready.reduce((sum, bytes) => sum + bytes.length, 0);
+    return this.#buffer.length + (this.#pending?.filled ?? 0) + ready;
   }
 
   /** The next complete message, or `undefined` at a clean EOF. */
@@ -54,10 +65,11 @@ export class MessageReader {
       if (framed !== undefined) return framed;
       const chunk = await this.#stream.read();
       if (chunk === undefined) {
-        if (this.#buffer.length === 0) return undefined;
+        const held = this.buffered;
+        if (held === 0) return undefined;
         throw new ReplicationProtocolError({
           stage: 'read',
-          detail: `the connection closed with ${this.#buffer.length} bytes of a partial message`,
+          detail: `the connection closed with ${held} bytes of a partial message`,
           fix: 'x doctor db — the backend was terminated mid-message; the server log names the reason',
         });
       }
@@ -66,18 +78,33 @@ export class MessageReader {
   }
 
   #append(chunk: Uint8Array): void {
+    let rest = chunk;
+    const pending = this.#pending;
+    if (pending !== null) {
+      const take = Math.min(pending.bytes.length - pending.filled, rest.length);
+      pending.bytes.set(rest.subarray(0, take), pending.filled);
+      pending.filled += take;
+      rest = rest.subarray(take);
+      if (pending.filled < pending.bytes.length) return;
+      this.#ready.push(pending.bytes);
+      this.#pending = null;
+    }
+    if (rest.length === 0) return;
     if (this.#buffer.length === 0) {
-      this.#buffer = chunk;
+      this.#buffer = rest;
       return;
     }
-    const joined = new Uint8Array(this.#buffer.length + chunk.length);
+    // Only ever a few bytes are held here: a message whose length is known moves to `#pending`.
+    const joined = new Uint8Array(this.#buffer.length + rest.length);
     joined.set(this.#buffer, 0);
-    joined.set(chunk, this.#buffer.length);
+    joined.set(rest, this.#buffer.length);
     this.#buffer = joined;
   }
 
   /** A message is `tag` + Int32 length that counts itself but not the tag. */
   #take(): PgMessage | undefined {
+    const done = this.#ready.shift();
+    if (done !== undefined) return messageOf(done);
     const buffer = this.#buffer;
     if (buffer.length < 5) return undefined;
     const length = new DataView(buffer.buffer, buffer.byteOffset, buffer.byteLength).getInt32(
@@ -92,16 +119,24 @@ export class MessageReader {
       });
     }
     const total = length + 1;
-    if (buffer.length < total) return undefined;
-    const message: PgMessage = {
-      tag: String.fromCharCode(buffer[0] ?? 0),
-      body: buffer.subarray(5, total),
-    };
+    if (buffer.length < total) {
+      // The length is known, so the message gets its one allocation now and fills in place.
+      const bytes = new Uint8Array(total);
+      bytes.set(buffer, 0);
+      this.#pending = { bytes, filled: buffer.length };
+      this.#buffer = new Uint8Array(0);
+      return undefined;
+    }
     this.#buffer = buffer.subarray(total);
-    return message;
+    return messageOf(buffer.subarray(0, total));
   }
 }
 
+const messageOf = (whole: Uint8Array): PgMessage => ({
+  tag: String.fromCharCode(whole[0] ?? 0),
+  body: whole.subarray(5),
+});
+
 /** `tag` + Int32 length + body — the shape of every frontend message except the startup packet. */
 export const frame = (tag: string, body: Uint8Array): Uint8Array =>
   new ByteWriter(body.length + 5)
@@ -178,10 +213,23 @@ export const describeFields = (fields: Readonly<Record<string, string>>): string
  * not: `changefeed-env -> changefeed -> pg-replication -> pg-wire` is already a chain, so reading
  * the constant here would close it into a cycle. Not re-exported from `index.ts`.
  */
+export const REPLICATION_EXPOSURE_DOC =
+  'https://github.com/developerz-ai/ultimate/blob/main/docs/ops/01-kubernetes.md#replication-is-a-cluster-wide-grant';
+
+/**
+ * What granting `REPLICATION` costs, said wherever a fix hands the grant over. The attribute is
+ * CLUSTER-wide: a `replication=database` session may run `BASE_BACKUP` or `START_REPLICATION
+ * PHYSICAL` with no database check, so on a shared cluster the app role could copy every database,
+ * `pg_authid` included, drop other slots and exhaust the walsenders.
+ */
+export const REPLICATION_GRANT_WARNING =
+  `only on a Postgres cluster dedicated to this app — on a shared cluster REPLICATION lets this ` +
+  `role copy every database (${REPLICATION_EXPOSURE_DOC})`;
+
 export const FIXES: Readonly<Record<string, string>> = {
   '28P01': 'correct the password in the replication URL — the server refused the credentials',
   '28000': 'add a `host replication <user> <cidr> scram-sha-256` line to pg_hba.conf and reload',
-  '42501': 'grant the role REPLICATION: ALTER ROLE <user> WITH REPLICATION',
+  '42501': `ALTER ROLE <user> WITH REPLICATION; -- ${REPLICATION_GRANT_WARNING}`,
   '55006': 'another replicator holds the slot — exactly one replicator per database, by design',
   // NOT `x db replication init`, which this line said until 2026-08-20 and which is not a command:
   // `x db` takes gen, migrate, reset, seed, studio, branch and backfill. It shipped because a fix
@@ -189,10 +237,11 @@ export const FIXES: Readonly<Record<string, string>> = {
   // the half of #97 that outlived the three log-injection holes. The publication is the operator's
   // to create; the slot the replicator creates for itself on its next start.
   '42704':
-    'psql "$REPLICATION_URL" -c "CREATE PUBLICATION x_changes FOR ALL TABLES"' +
-    "   # x_changes is the default name; use REPLICATION_PUBLICATION's value where it is set. " +
+    'psql "$REPLICATION_URL" -c "CREATE PUBLICATION x_changes FOR TABLE <every entity table>"' +
+    "   # x_changes is the default name; use REPLICATION_PUBLICATION's value where it is set, and FOR TABLE because FOR ALL TABLES needs a superuser. " +
     "The slot is the replicator's own and it creates one on its next start",
-  '0A000': 'set wal_level = logical in postgresql.conf and restart the server',
+  '0A000':
+    "set wal_level=logical in the server configuration (postgresql.conf, or your managed provider's database flags) and restart the server",
 };
 
 /** What a SQLSTATE this table has no entry for is answered with. */

package/src/policy-fake.ts

@@ -0,0 +1,14 @@
+// A policy that admits every caller, for the tests that declare a channel whose authz is not
+// their subject. Structural, never built with `@ultimat3/policy`: realtime reaches that package
+// only through `@ultimat3/query`'s `guard`, and a direct import would be a second authz path.
+// An app says the same thing with `allow('public')`, which is what this stands in for.
+
+import type { QueryPolicy } from '@ultimat3/query';
+
+export const OPEN_POLICY: QueryPolicy = Object.freeze({
+  kind: 'allow',
+  label: 'public',
+  permissions: [],
+  children: [],
+  run: () => ({ allowed: true as const }),
+});

package/src/query-window.ts

@@ -125,29 +125,43 @@ export function createEntry(
 export async function fillWindow(
   entry: QueryEntry,
 ): Promise<{ rows: readonly Row[]; lsn: string }> {
-  // Read before `startRead` clears it: a second caller arriving during the read joins it and is
-  // not the one that forced it, which is what keeps one forced read from becoming N.
-  const forced = entry.stale;
-  const pending = forced || entry.reading === null ? startRead(entry) : entry.reading;
-  const result = await pending.result;
-  return await entry.lock.run(async () => {
-    // Two rules, and neither can stand in for the other. Against another READ it is identity —
-    // the same check `startRead` makes on `entry.reading` one function down, and the one
-    // `packages/cache/src/single-flight.ts` makes for the same reason — because an lsn cannot
-    // order two reads at all: a definition with no lsn provider answers `''` for both, and
-    // `'' >= ''` let the older one overwrite the gap repair the newer one had just landed, with
-    // `stale` already cleared by its issue and therefore nothing left to re-read. Against a
-    // CHANGE it is still the lsn, because a fanout moved `entry.lsn` forwards while this read was
-    // in flight and rewinding to what the read saw hands that subscriber rows the fanout has
-    // moved past — except for a forced read, which was issued *because* what is under it is
-    // wrong.
-    if (isNewestRead(entry, pending) && (forced || result.lsn >= entry.lsn)) {
-      applyRead(entry, pending, result);
-    }
-    return { rows: entry.rows, lsn: entry.lsn };
-  });
+  for (let attempt = 0; ; attempt += 1) {
+    // Read before `startRead` clears it: a second caller arriving during the read joins it and is
+    // not the one that forced it, which is what keeps one forced read from becoming N.
+    const forced = entry.stale;
+    const pending = forced || entry.reading === null ? startRead(entry) : entry.reading;
+    const result = await pending.result;
+    const again = await entry.lock.run(async () => {
+      // Two rules, and neither can stand in for the other. Against another READ it is identity —
+      // the same check `startRead` makes on `entry.reading` one function down, and the one
+      // `packages/cache/src/single-flight.ts` makes for the same reason — because an lsn cannot
+      // order two reads at all: a definition with no lsn provider answers `''` for both, and
+      // `'' >= ''` let the older one overwrite the gap repair the newer one had just landed, with
+      // `stale` already cleared by its issue and therefore nothing left to re-read. Against a
+      // CHANGE it is still the lsn, because a fanout moved `entry.lsn` forwards while this read was
+      // in flight and rewinding to what the read saw hands that subscriber rows the fanout has
+      // moved past — except for a forced read, which was issued *because* what is under it is
+      // wrong, and for the FIRST read, which has no window under it to rewind: a fanout never
+      // patches a window no read has landed in (`live-fanout.ts`), it marks it stale instead.
+      const first = entry.applied === 0;
+      if (isNewestRead(entry, pending) && (forced || first || result.lsn >= entry.lsn)) {
+        applyRead(entry, pending, result);
+      }
+      // A change reached this window while its first read was in flight and could not be folded,
+      // so what just landed may predate it: read once more before serving anyone a partial window.
+      return first && entry.stale && attempt < COLD_REREADS;
+    });
+    if (!again) return { rows: entry.rows, lsn: entry.lsn };
+  }
 }
 
+/**
+ * How many times a cold window re-reads because writes kept landing during its read. Bounded: a
+ * table written faster than it can be read would otherwise never serve a subscriber, and after the
+ * bound the window stays `stale`, so the next change re-reads it anyway.
+ */
+const COLD_REREADS = 3;
+
 /**
  * The same replacement, for a caller that is already holding the lane. A fanout cannot call
  * `fillWindow` — that takes the entry's own lane, and a lane is not reentrant — so the one path