@ultimat3/realtime 4.1.0 → 5.0.1

package/CLAUDE.md

@@ -680,7 +680,7 @@ Tier 3 package. Channels, live queries, local-first sync. One protocol for all t
 | `live-contract.ts` | what a live query IS: `LiveQueryDefinition`, `SnapshotResult`, `LiveSubscription`. Four modules need the shape and none of them needs the registry that runs it. The **id** is not here and not anywhere in this package — it is `@ultimat3/query`'s `queryHash` |
 | `json.ts` | the wire's value types and `fnv1a` (drift), the one hash still owned here. The canonical form and the sharing-key hash are `@ultimat3/core`'s (`canonicalJson`, `fingerprint`) — `json.test.ts` pins that `fnv1a` is never mistakable for one |
 | `live-definition.ts` | the only bridge from a declared `query({ live: true })` to a registrable definition — and `policy-gate.ts`'s only caller |
-| `matcher-bridge.ts` | the only `@ultimat3/query` matcher seam |
+| `matcher-bridge.ts` | the only `@ultimat3/query` matcher seam — and where a patch row is narrowed to the columns the query returned |
 
 ## Commands
 
@@ -698,3 +698,21 @@ the same whitelist drops an old client's copy, and a new client's omission decod
 field always held. Bumping for either refuses every in-flight client on a rolling deploy and buys
 nothing — the version guards incompatibility, not novelty. Removing a field something *does* read
 is the opposite case and bumps.
+
+**A patch carries the result set's columns, never the table's** — `narrowRow` in
+`matcher-bridge.ts`, `As of 2026-08-20`. A `ChangeEvent` carries the whole TABLE row (that is what
+logical replication emits, and what `@ultimat3/entity`'s `setRowObserver` emits), while a live
+query's result set is whatever its `sql` returned. Every patch used to forward the change row
+unnarrowed, so a column a projection exists to withhold went out on the socket the moment it
+CHANGED — `examples/dummy`'s feed projects ten columns and one publish delivered `updatedAt` to
+every subscriber (#230). The per-subscriber gate cannot help: it decides whether a ROW is delivered,
+never which of its columns.
+
+`id` always survives the narrowing — it is the row's identity on the wire, and `applyToWindow` and
+every client store key by it. An **unknown** projection narrows nothing, because "nothing has been
+read yet" is not "the result set has no columns".
+
+The projection is **learned from the query's own reads**, in `live-definition.ts`: a projection
+lives inside the `sql` provider's closure and there is nothing static to read it from. Learned and
+kept rather than re-derived per fanout, because the case the window's own rows cannot answer is an
+EMPTY window — the first row to arrive would otherwise go out whole.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/realtime",
-  "version": "4.1.0",
+  "version": "5.0.1",
   "description": "Three-tier realtime: channels, live queries, local-first sync — one protocol, one mutator shape",
   "license": "MIT",
   "type": "module",
@@ -32,8 +32,8 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "4.1.0",
-    "@ultimat3/query": "4.1.0",
+    "@ultimat3/core": "5.0.1",
+    "@ultimat3/query": "5.0.1",
     "nats": "2.29.3"
   }
 }

package/src/live-definition.ts

@@ -13,7 +13,7 @@ import { type AnyQuery, queryHash, queryName } from '@ultimat3/query';
 import { LiveRowUnidentifiedError } from './errors';
 import { isRow, type JsonValue, type Row } from './json';
 import type { LiveQueryDefinition, SnapshotResult } from './live-contract';
-import { type IncrementalMatcher, matcherFor } from './matcher-bridge';
+import { type IncrementalMatcher, matcherFor, type Projection } from './matcher-bridge';
 import { authorizeWithPolicy, visibleWithPolicy } from './policy-gate';
 
 export interface LiveDefinitionOptions {
@@ -49,6 +49,25 @@ interface SharedWindow {
   read(): Promise<readonly Row[]>;
 }
 
+/**
+ * The columns this query's result set carries, learned from the rows it returns rather than
+ * declared — a projection lives inside the `sql` provider's closure and there is nothing static to
+ * read it from. Learned once and kept, because the case the window's own rows cannot answer is an
+ * EMPTY window: the first row to arrive would otherwise be sent as the whole table row.
+ */
+const learnProjection = (): { read: () => Projection; teach: (rows: readonly Row[]) => void } => {
+  let projection: Projection;
+  return {
+    read: () => projection,
+    // Never unlearned: a window that empties still describes the same result set, and forgetting
+    // would put the leak back on the first row to return.
+    teach: (rows) => {
+      if (projection === undefined && rows[0] !== undefined)
+        projection = new Set(Object.keys(rows[0]));
+    },
+  };
+};
+
 /**
  * A matcher for an input nothing has resolved yet. It refuses to decide rather than reporting "no
  * change": a subscriber told nothing happened diverges silently, and `refill` is the one answer
@@ -88,12 +107,17 @@ export function liveQueryDefinition(
     // that patches them describe the same `(query, input)` by construction. Asking `sourceFor` for
     // a second subject-less copy — which is what this did — paid for the parse and the `sql()`
     // twice per query id and left two descriptions of one read that agreed only by luck.
+    const projection = learnProjection();
     const built: SharedWindow = {
-      matcher: matcherFor(live),
+      matcher: matcherFor(live, projection.read),
       // `assertMatchable` already refused a shape without one, so this is the entity the matcher
       // patches rows of — the same name `ChangeEvent.entity` and `tx.<table>` use.
       rowEntity: live.shape.entity,
-      read: async () => rowsOf(name, await live.execute()),
+      read: async () => {
+        const rows = rowsOf(name, await live.execute());
+        projection.teach(rows);
+        return rows;
+      },
     };
     windows.set(qid, built);
     evictOldest(windows, options.maxWindows ?? 256);

package/src/matcher-bridge.ts

@@ -77,7 +77,7 @@ export function patchFromChange(change: ChangeEvent): RowPatch | null {
  * swapping the matcher — or adopting an external protocol's, per the risk register — touches this
  * function only.
  */
-export function matcherFor(live: LiveQuery): IncrementalMatcher {
+export function matcherFor(live: LiveQuery, projection?: () => Projection): IncrementalMatcher {
   return {
     entities: live.reads,
     match: (change, rows) => {
@@ -89,13 +89,53 @@ export function matcherFor(live: LiveQuery): IncrementalMatcher {
         row,
         ...(change.before === null ? {} : { before: change.before }),
       });
-      return toBridgeResult(patches, change);
+      // The window's own rows are the fallback, so a matcher built without a `projection` reader
+      // still narrows once the window holds anything — `live-definition.ts` supplies one because
+      // an EMPTY window is the case rows cannot answer.
+      return toBridgeResult(patches, change, projection?.() ?? projectionOf(rows));
     },
   };
 }
 
+/**
+ * The columns a query's result set actually carries, learned from the rows it returned. `undefined`
+ * means nothing has been read yet, and then nothing is narrowed — the shape is unknown, and
+ * inventing one would drop columns a caller is owed.
+ */
+export type Projection = ReadonlySet<string> | undefined;
+
+/** The projection a window's own rows describe. Empty window, no answer. */
+export const projectionOf = (rows: readonly Row[]): Projection =>
+  rows[0] === undefined ? undefined : new Set(Object.keys(rows[0]));
+
+/**
+ * One row, restricted to the columns the result set carries.
+ *
+ * A `ChangeEvent` carries the whole TABLE row — that is what logical replication emits and what
+ * `setRowObserver` emits — while a live query's result set is whatever its `sql` returned. Sending
+ * the change row through unnarrowed put every column of the table on the socket, including the ones
+ * a projection exists to withhold: `examples/dummy`'s feed projects ten columns and a single publish
+ * delivered `body` to every subscriber. The per-subscriber gate cannot help — it decides whether a
+ * ROW is delivered, never which of its columns.
+ *
+ * `id` always survives: it is the row's identity on the wire, and `applyToWindow` and every client
+ * store key by it.
+ */
+export function narrowRow(row: JsonObject, projection: Projection): JsonObject {
+  if (projection === undefined) return row;
+  const out: JsonObject = {};
+  for (const key of Object.keys(row)) {
+    if (key === 'id' || projection.has(key)) out[key] = row[key] as JsonObject[string];
+  }
+  return out;
+}
+
 /** `Patch<Row>` (add/update/remove/refill, positional) -> the wire's `RowPatch`. */
-export function toBridgeResult(patches: readonly Patch<Row>[], change: ChangeEvent): BridgeResult {
+export function toBridgeResult(
+  patches: readonly Patch<Row>[],
+  change: ChangeEvent,
+  projection?: Projection,
+): BridgeResult {
   const out: RowPatch[] = [];
   let refill = false;
   for (const patch of patches) {
@@ -104,7 +144,7 @@ export function toBridgeResult(patches: readonly Patch<Row>[], change: ChangeEve
         out.push({
           op: 'insert',
           id: patch.row.id,
-          row: patch.row,
+          row: narrowRow(patch.row, projection),
           lsn: change.lsn,
           index: patch.position,
         });
@@ -113,7 +153,10 @@ export function toBridgeResult(patches: readonly Patch<Row>[], change: ChangeEve
         out.push({
           op: 'update',
           id: patch.row.id,
-          row: { id: patch.row.id, ...changedColumns(change.before, patch.row) },
+          row: narrowRow(
+            { id: patch.row.id, ...changedColumns(change.before, patch.row) },
+            projection,
+          ),
           lsn: change.lsn,
           index: patch.position,
         });

package/src/pg-wire.ts

@@ -170,13 +170,28 @@ export const describeFields = (fields: Readonly<Record<string, string>>): string
     .filter((part): part is string => part !== undefined && part !== '')
     .join(' — ');
 
-/** SQLSTATEs worth their own fix line, because the operator's next command differs for each. */
-const FIXES: Readonly<Record<string, string>> = {
+/**
+ * SQLSTATEs worth their own fix line, because the operator's next command differs for each.
+ *
+ * Exported for `pg-wire.test.ts` alone, which pins the publication name in `42704` to
+ * `DEFAULT_REPLICATION_PUBLICATION` — a test may import `changefeed-env.ts`, and this module may
+ * 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 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',
   '55006': 'another replicator holds the slot — exactly one replicator per database, by design',
-  '42704': 'x db replication init — the publication or the slot does not exist yet',
+  // 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
+  // read out of a TABLE was invisible to the gate — `fix: FIXES[code]` holds no literal — which is
+  // 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. " +
+    "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',
 };