@ultimat3/entity 20.2.1 → 21.0.0

package/CLAUDE.md

@@ -1130,6 +1130,22 @@ Columns + invariants; the row type is derived from the columns. Tier 2.
   conflict. **`whyNot` asks three questions in one order** — unknown state, then terminal, then the
   legal list — because an unknown state has no outgoing moves either, and a check that skipped it
   reported a typo as "the row is terminal in `pendign`".
+- **An entity row on the client is a RECORD, and the record is derived — plan 101, `As of
+  2026-09-22`.** `$schema` is a full `t` schema (`row-schema.ts`) whose node carries the entity's
+  `RecordProjection` under the non-enumerable `ENTITY_BRAND` (`Symbol.for('ultimate.entity')`, so a
+  brand minted in one island bundle is read in another). Rules, none optional. **The brand lives on
+  the NODE**, because `t.array`/`t.object`/`t.record`/`t.union` keep only the child's node, by
+  reference; the five methods that COPY a node (`nullable`, `optional`, `default`, `describe`,
+  `refine`) are re-branded in `row-schema.ts`, since a spread drops a non-enumerable symbol — do not
+  "fix" that in `@ultimat3/schema` by making the brand enumerable, which would put it in every
+  spread and `toEqual` of the IR. **A partial row is never a record**: `$view` and any
+  `.pick/.omit/.extend` build unbranded nodes, and `rows-of.test.ts` pins it. **`rowsOf` answers type → record key → row**, both levels null-prototype: the key is what
+  travels, since a browser cannot compute one without importing the app's `entity()` declarations. **`persist` is an `EntityInit` key, default `false`**, read ONLY off the projection
+  (`recordProjection(e).persist`) — realtime's persister is its reader, so disk is a per-entity
+  declaration and never a store-wide switch. **The browser path is `@ultimat3/entity/record`** (`record.ts`), and the modules behind
+  it import `entity-error.ts`, never `errors.ts`: `errors.ts` imports `@ultimat3/db` for
+  `dbDrift`, and one such import put 16 `db` modules (pglite included) in the chunk.
+  `record-bundle.test.ts` lists the retained entity modules by name, so a new import there fails.
 - Never throw a bare `Error` — use `errors.ts`.
 - **Tests restore the process-global registry in `afterAll` (`clearRegistry()`), and the hook is at
   FILE scope — a build error since 2026-08-25, because the prose form was violated by 19 of the 19
@@ -1163,6 +1179,12 @@ Columns + invariants; the row type is derived from the columns. Tier 2.
 | `column-values.ts` | `got()` and `oneOf()`, so `enum-column.ts` needs no import of the file that imports it |
 | `feature-errors.ts` | the refusals search and the state machine raise at call time; the codes and titles stay in `errors.ts` |
 | `view.ts` | `$view(keys)` — the row projection an action names as its `output` |
+| `row-schema.ts` | `$schema` — the whole row as a `t` schema, branded, with the copying wrappers re-branded |
+| `record-projection.ts` / `record-key.ts` | `ENTITY_BRAND`, `RecordProjection`, `recordProjection()`; the record key and `X_RECORD_KEY_MISSING` |
+| `rows-of.ts` | `rowsOf`/`hasEntityRows` — the entity rows an output schema declares, read beside its value |
+| `record-table.ts` | `recordTypeForTable` — a changefeed's table back to the record type, memoised on the registry generation |
+| `record.ts` | the `@ultimat3/entity/record` subpath — the browser-safe entry for the four above |
+| `entity-error.ts` | the code registry, `EntityError`, `invariantViolated`, `entityDuplicate` — no `@ultimat3/db`, so the browser path can raise them; `errors.ts` re-exports all of it |
 | `query.ts` / `database.ts` | chainable read to a cursor page; `database()` + `Driver` |
 | `clock.ts` | `entityNow()` — the ONE clock read on the write path, `ctx.clock` else the system's |
 | `memory-match.ts` | what a `Predicate` means in the memory driver: compare/equal/LIKE, by the column's kind. The decimal comparison itself is `@ultimat3/core`'s `compareDecimalText` |
@@ -1178,7 +1200,8 @@ Columns + invariants; the row type is derived from the columns. Tier 2.
 | `jit-preload.ts` | a page's foreign key values → one `in` statement for the whole `for … of` loop |
 | `preload.ts` | the relation `preload()` names → one related-rows statement → attached to the page |
 | `pg-sql.ts` / `pg-row.ts` | plan → parameterised SQL; physical row ⇄ entity row (money is three columns) |
-| `row-observer.ts` | `setRowObserver` — committed row changes, above the driver, for a change feed that has no log to read |
+| `row-observer.ts` | `setRowObserver` — committed row changes, above the driver, for a change feed that has no log to read. A change made inside a keyed request carries `write` (`currentWriteOrigin()`) |
+| `write-tag.ts` | a keyed request's write names itself in the WAL: `pg_logical_emit_message(true, WRITE_ORIGIN_WAL_PREFIX, digest)` opens its transaction, once per transaction; a write outside one gets a transaction of its own; a role that may not execute it is probed once and its writes go out untagged; a pinned repository is never wrapped |
 | `registry.ts` | duplicate detection, `describeEntities()` for the manifest, `references()` per entry |
 | `relations.ts` | `relationMap()`/`relationsFor()`/`relationNamed()` — the FKs as a named `belongsTo`/`hasMany` map |
 | `n-plus-one.ts` | a repeated statement → the error whose `fix` is the preload or bulk call that ends it |

package/README.md

@@ -56,6 +56,51 @@ A view the columns cannot express — a joined `authorName`, a computed `excerpt
 `t.object({...})`. `t` is re-exported here, the same object `@ultimat3/schema` exports, so that file
 still imports one package: `import { entity, t } from '@ultimat3/entity'`.
 
+## A whole row is a record
+
+`posts.$schema` is the whole row as a `t` schema, and its node is branded
+(`Symbol.for('ultimate.entity')`, non-enumerable) with the entity's **record projection**. An
+action or query whose output names it — bare or wrapped — returns rows the client store adopts,
+with no `records:` option anywhere: the envelope is derived from the output schema.
+
+```ts
+import {
+  entity,
+  hasEntityRows,
+  recordProjection,
+  recordTypeForTable,
+  rowsOf,
+  t,
+  text,
+  uuid,
+} from '@ultimat3/entity';
+
+const posts = entity('posts', { columns: { id: uuid().primaryKey(), title: text() } });
+const Feed = t.object({ items: t.array(posts.$schema), featured: posts.$schema.nullable() });
+declare const answer: unknown; // what a handler returned
+
+hasEntityRows(Feed);         // true — static, memoised per node
+rowsOf(Feed, answer);        // { posts: { [recordKey]: row } } — null-prototype, same objects
+recordProjection(posts);     // { type: 'posts', table: 'posts', key, schema, persist: false }
+recordTypeForTable('posts'); // 'posts' — what a changefeed row belongs to
+```
+
+| Rule | Detail |
+|---|---|
+| Survives every wrapper | `t.array`, `t.object`, `t.record`, `t.union` keep the child node by reference; `.nullable()`, `.optional()`, `.default()`, `.describe()`, `.refine()` re-brand the copy they make |
+| A partial row is never a record | a `$view`, and any `t.object(...).pick/omit/extend`, carries no brand — it would overwrite a full record |
+| Wire shape | type → record key → row: the KEY travels, because a browser cannot compute one without importing the app's `entity()` declarations |
+| Union arms | a branded arm claims a value only when every column is an own key of it |
+| Record key | the primary key, in DECLARED order; a single key is the value itself (so it equals `$tagFor(id)`'s id), a composite one percent-encodes each part and joins on `:` |
+| Missing key | `X_RECORD_KEY_MISSING` — never keyed as `undefined`, because two keyless rows would be one record |
+| `persist` | `entity(name, { persist: true })` — default `false`; a browser keeps the records on disk (IndexedDB, per principal) only when declared. Realtime's persister reads `recordProjection(e).persist`, never the declaration |
+| `type` / `table` | the entity name (the store's key) and the physical relation (what a changefeed names); two entities over one table are `X_INVARIANT_VIOLATED` from `recordTypeForTable` |
+
+**In browser code import these from `@ultimat3/entity/record`**, never the barrel: the package
+declares no `sideEffects`, so the barrel retains ~1 MB of SQL rendering and `@ultimat3/db` a page
+never runs, while the subpath retains the projection, the key and the registry and nothing else —
+`record-bundle.test.ts` measures both.
+
 ## Blessed columns
 
 | Builder | Emits | Why it is the only way |
@@ -842,7 +887,8 @@ database from its boot code has decided to, and a library that overruled that wo
 `X_ENTITY_DUPLICATE` · `X_INVARIANT_VIOLATED` · `X_TENANCY_UNSCOPED` ·
 `X_TENANCY_ACTOR_MISMATCH` · `X_TENANCY_ACTOR_ORG_REQUIRED` · `X_TENANCY_CROSS_DENIED` ·
 `X_DB_DRIFT` · `X_NOT_FOUND` · `X_WRITE_UNFILTERED` · `X_PATCH_EMPTY` ·
-`X_PRELOAD_UNKNOWN_RELATION` · `X_N_PLUS_ONE_QUERY` · `X_N_PLUS_ONE_WRITE`
+`X_PRELOAD_UNKNOWN_RELATION` · `X_N_PLUS_ONE_QUERY` · `X_N_PLUS_ONE_WRITE` ·
+`X_RECORD_KEY_MISSING`
 
 ## Boundaries
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/entity",
-  "version": "20.2.1",
+  "version": "21.0.0",
   "description": "A table + its domain type + invariants the database also enforces",
   "license": "MIT",
   "type": "module",
@@ -14,7 +14,8 @@
     "provenance": true
   },
   "exports": {
-    ".": "./src/index.ts"
+    ".": "./src/index.ts",
+    "./record": "./src/record.ts"
   },
   "files": [
     "src",
@@ -31,9 +32,9 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "20.2.1",
-    "@ultimat3/db": "20.2.1",
-    "@ultimat3/schema": "20.2.1",
-    "@ultimat3/time": "20.2.1"
+    "@ultimat3/core": "21.0.0",
+    "@ultimat3/db": "21.0.0",
+    "@ultimat3/schema": "21.0.0",
+    "@ultimat3/time": "21.0.0"
   }
 }

package/src/entity-error.ts

@@ -0,0 +1,126 @@
+// The entity layer's code registry, its error class, and the two refusals the declaration path
+// raises — split from `errors.ts` so a module the BROWSER loads (the record key, the projection,
+// the registry) can raise one without importing `@ultimat3/db`, which `errors.ts` needs for
+// `dbDrift`'s shell-inert fix line.
+import { registerErrorCodes, UltimateError } from '@ultimat3/core';
+
+/** Codes this package declares and owns. */
+export const ENTITY_OWNED_ERROR_CODES = [
+  'X_ENTITY_DUPLICATE',
+  'X_INVARIANT_VIOLATED',
+  'X_TENANCY_UNSCOPED',
+  'X_TENANCY_ACTOR_MISMATCH',
+  'X_TENANCY_ACTOR_ORG_REQUIRED',
+  'X_TENANCY_CROSS_DENIED',
+  'X_NOT_FOUND',
+  'X_WRITE_UNFILTERED',
+  'X_PATCH_EMPTY',
+  'X_PRELOAD_UNKNOWN_RELATION',
+  'X_N_PLUS_ONE_QUERY',
+  'X_N_PLUS_ONE_WRITE',
+  'X_REPO_CLIENT_PINNED',
+  'X_AGGREGATE_UNSUPPORTED',
+  'X_AGGREGATE_MIXED_CURRENCY',
+  'X_APPROXIMATE_COUNT_FILTERED',
+  'X_SEARCH_UNDECLARED',
+  'X_SEARCH_IN_MEMORY',
+  'X_STATE_UNDECLARED',
+  'X_STATE_TRANSITION_ILLEGAL',
+  'X_STATE_CONFLICT',
+  'X_RECORD_KEY_MISSING',
+] as const;
+
+/**
+ * `X_DB_DRIFT` is `@ultimat3/db`'s — drift is a fact about migrations, and this package imports db
+ * rather than the other way round. `dbDrift()` below throws it; nothing here titles it, because a
+ * second copy of the title is what lets the two packages disagree about what the code means.
+ */
+export const ENTITY_BORROWED_ERROR_CODES = ['X_DB_DRIFT'] as const;
+
+/** Every code entity can throw: the ones it owns plus the one it borrows. */
+export const ENTITY_ERROR_CODES = [
+  ...ENTITY_OWNED_ERROR_CODES,
+  ...ENTITY_BORROWED_ERROR_CODES,
+] as const;
+
+export type EntityOwnedErrorCode = (typeof ENTITY_OWNED_ERROR_CODES)[number];
+export type EntityErrorCode = (typeof ENTITY_ERROR_CODES)[number];
+
+export const ENTITY_ERROR_TITLES: Readonly<Record<EntityOwnedErrorCode, string>> = {
+  X_ENTITY_DUPLICATE: 'two entities claim the same name',
+  X_INVARIANT_VIOLATED: 'a domain invariant rejected this row',
+  X_TENANCY_UNSCOPED: 'a tenant-scoped query has no org predicate',
+  // "call", not "query": the same code covers a predicate that names another tenant and a row or
+  // patch that writes one, because they are one mistake made in two places.
+  X_TENANCY_ACTOR_MISMATCH: "a call named a tenant other than the actor's",
+  X_TENANCY_ACTOR_ORG_REQUIRED: 'the acting actor carries no tenant',
+  X_TENANCY_CROSS_DENIED: 'a cross-tenant read was entered without the capability',
+  X_NOT_FOUND: 'no row for that id',
+  X_WRITE_UNFILTERED: 'a filtered write named no filter columns',
+  X_PATCH_EMPTY: 'a filtered update named no columns to write',
+  X_PRELOAD_UNKNOWN_RELATION: 'no relation of that name on this entity',
+  X_N_PLUS_ONE_QUERY: 'a read repeated once per row',
+  X_N_PLUS_ONE_WRITE: 'a write repeated once per row',
+  X_REPO_CLIENT_PINNED: 'a repository pinned to its own client cannot join the open transaction',
+  X_AGGREGATE_UNSUPPORTED: 'that column has no aggregate both drivers can answer alike',
+  X_AGGREGATE_MIXED_CURRENCY: 'an amount was aggregated across currencies',
+  X_APPROXIMATE_COUNT_FILTERED: 'an estimate was asked of a filtered chain',
+  X_SEARCH_UNDECLARED: 'this entity has no searchable column',
+  X_SEARCH_IN_MEMORY: 'the in-memory driver cannot answer a full-text match',
+  X_STATE_UNDECLARED: 'that column declares no state machine',
+  X_STATE_TRANSITION_ILLEGAL: 'the machine has no such transition',
+  X_STATE_CONFLICT: 'the row is no longer in the state this transition named',
+  X_RECORD_KEY_MISSING: 'a row reached its record key without a primary-key value',
+};
+
+// Registered at module load, unconditionally, in one call. Without this the registry humanises the
+// code and every surface renders a title this package never wrote; with a presence guard, a second
+// package claiming one of these codes would silently win instead of throwing X_ERROR_CODE_DUPLICATE.
+registerErrorCodes(
+  Object.fromEntries(Object.entries(ENTITY_ERROR_TITLES).map(([code, title]) => [code, { title }])),
+);
+
+/**
+ * Base for every error this package throws. No `docs:` — `UltimateError` fills it from
+ * `describeErrorCode(code).docs`, which is `@ultimat3/core`'s `ERROR_DOCS_URL`: one page for every
+ * code, never one per code, because `wiki/` is the framework's only public documentation surface
+ * and a code lives there in a TABLE ROW, which has no anchor. The
+ * `https://ultimate.dev/errors/<code>` links this class built until 9.x answered 404, host
+ * included, on every refusal it has ever raised.
+ */
+export class EntityError extends UltimateError {
+  override readonly name = 'EntityError';
+
+  constructor(init: { code: EntityErrorCode; cause: string; fix: string }) {
+    super({
+      code: init.code,
+      cause: init.cause,
+      fix: init.fix,
+    });
+  }
+}
+
+/**
+ * The entity name is a VALUE, never a literal — `entity.$name`, `table`, the `name` `entity()` was
+ * given. A literal is an entity that does not exist, and this fix then hands the reader
+ * `x entities describe column --json`, which answers `X_DECLARATION_UNKNOWN` (issue #290). A
+ * refusal raised before any entity exists belongs in `refuse.ts`, where the caller supplies the
+ * edit; `refuse.test.ts` fails on a literal here.
+ */
+export const invariantViolated = (
+  entityName: string,
+  invariantName: string,
+  message: string,
+): EntityError =>
+  new EntityError({
+    code: 'X_INVARIANT_VIOLATED',
+    cause: `${entityName}.${invariantName}: ${message}`,
+    fix: `x entities describe ${entityName} --json   # shows the invariant and its SQL CHECK`,
+  });
+
+export const entityDuplicate = (name: string, existingTable: string): EntityError =>
+  new EntityError({
+    code: 'X_ENTITY_DUPLICATE',
+    cause: `entity "${name}" is already registered for table "${existingTable}"`,
+    fix: `x entities list --json   # then rename one of the two entity({ name }) declarations`,
+  });

package/src/entity.ts

@@ -3,9 +3,8 @@
 // (the typed db handle, migrations, cache tags, the admin UI, the manifest) is projected from
 // this one call.
 
-import { renderThrowable } from '@ultimat3/core';
 import type { IndexMethod } from '@ultimat3/db';
-import { describeValue, type StandardSchemaV1 } from '@ultimat3/schema';
+import { describeValue, type Schema } from '@ultimat3/schema';
 import { entityNow } from './clock';
 import { assertColumnName, bindColumn, columnName, moneyColumns } from './column';
 import { newId } from './columns';
@@ -16,8 +15,10 @@ import { invariantColumns } from './expr';
 import { indexName } from './index-name';
 import type { Invariant, InvariantDef } from './invariants';
 import { assertInvariants, bindInvariant } from './invariants';
+import { recordProjection } from './record-projection';
 import type { EntityDescription, ReferenceDescription } from './registry';
 import { registerEntity } from './registry';
+import { rowSchema } from './row-schema';
 import type { SearchInit, SearchSource, SearchVector } from './search';
 import { searchVectorOf } from './search';
 import { resolveTenantColumn } from './tenancy';
@@ -84,6 +85,12 @@ export interface EntityInit<C extends ColumnMap> {
   readonly search?: SearchInit;
   /** Extra cache tags this entity participates in, beyond its own. */
   readonly tags?: readonly string[];
+  /**
+   * Whether a browser keeps this entity's records on disk (IndexedDB, keyed by principal) so they
+   * survive a reload and an offline start. Default `false`: a record is private data by default,
+   * and disk is a decision. Read off `recordProjection(entity).persist` by realtime's persister.
+   */
+  readonly persist?: boolean;
 }
 
 /**
@@ -111,8 +118,13 @@ export interface EntityCore<Row = unknown, C extends ColumnMap = ColumnMap> {
   readonly $search: SearchVector | null;
   /** Phantom: `type Post = typeof posts.$row`. Reading it at runtime throws. */
   readonly $row: Row;
-  /** The Standard Schema the columns already describe — forms and actions hand input to it. */
-  readonly $schema: StandardSchemaV1<unknown, Row>;
+  /**
+   * The whole row as a `t` schema — forms and actions hand input to it, and an output naming it
+   * (bare or wrapped: `t.array(posts.$schema)`) is a row the client store adopts, because its node
+   * carries the `recordProjection` brand. A `$view` or a `.pick()` carries none: a partial row is
+   * never a record.
+   */
+  readonly $schema: Schema<unknown, Row>;
   /** `entity:<name>:<id>` — row-level invalidation for live queries. */
   $tagFor(id: string): string;
   /** Fills declared defaults, then validates every column. Throws on a bad value. */
@@ -388,25 +400,11 @@ export const entity = <const C extends ColumnMap>(
     $softDelete: softDelete,
     $tenantColumn: tenantColumn,
     $search: search,
-    $schema: {
-      '~standard': {
-        version: 1,
-        vendor: 'ultimate',
-        validate: (value) => {
-          try {
-            return { value: parse(value) };
-          } catch (error) {
-            // `renderThrowable`, never `error instanceof Error ? error.message : String(error)`:
-            // both halves of that read the caught value directly. `instanceof` consults
-            // `getPrototypeOf` and `String()` runs the value's own coercion, so a `Proxy` or a
-            // null-prototype throwable raised a SECOND, uncatchable `TypeError` out of the
-            // validator — where a rejection belongs. A column parser is app-reachable and an
-            // app's `$parse` may throw anything at all.
-            return { issues: [{ message: renderThrowable(error) }] };
-          }
-        },
-      },
-    },
+    $schema: rowSchema<Row>(
+      { name, table, primaryKey, persist: init.persist === true },
+      entries,
+      parse,
+    ),
     get $row(): Row {
       // Type-only. Reading it means someone expected a value where a type was meant.
       throw invariantViolated(name, '$row', '$row is a type, not a value — use typeof x.$row');
@@ -420,7 +418,14 @@ export const entity = <const C extends ColumnMap>(
     $references: references,
   };
 
-  registerEntity({ name, tableName: table, describe, references });
+  registerEntity({
+    name,
+    tableName: table,
+    persist: init.persist === true,
+    projection: recordProjection(core),
+    describe,
+    references,
+  });
   // The columns land on the entity itself so `orgs.id` is a column reference; every framework
   // member is `$`-prefixed, which is why a column may be called `name`.
   return Object.assign(core, init.columns);

package/src/errors.ts

@@ -1,102 +1,20 @@
 // The entity layer's stable error codes. Each factory produces the exact command
 // that fixes the situation — `X_DB_DRIFT` is the flagship: it names the table, the
-// column and the generator invocation.
-import { registerErrorCodes, UltimateError } from '@ultimat3/core';
+// column and the generator invocation. The code registry, the class, `invariantViolated` and
+// `entityDuplicate` live in `entity-error.ts`, which imports no `@ultimat3/db`; re-exported here.
 import { shellInertIdentifier } from '@ultimat3/db';
+import { EntityError } from './entity-error';
 
-/** Codes this package declares and owns. */
-export const ENTITY_OWNED_ERROR_CODES = [
-  'X_ENTITY_DUPLICATE',
-  'X_INVARIANT_VIOLATED',
-  'X_TENANCY_UNSCOPED',
-  'X_TENANCY_ACTOR_MISMATCH',
-  'X_TENANCY_ACTOR_ORG_REQUIRED',
-  'X_TENANCY_CROSS_DENIED',
-  'X_NOT_FOUND',
-  'X_WRITE_UNFILTERED',
-  'X_PATCH_EMPTY',
-  'X_PRELOAD_UNKNOWN_RELATION',
-  'X_N_PLUS_ONE_QUERY',
-  'X_N_PLUS_ONE_WRITE',
-  'X_REPO_CLIENT_PINNED',
-  'X_AGGREGATE_UNSUPPORTED',
-  'X_AGGREGATE_MIXED_CURRENCY',
-  'X_APPROXIMATE_COUNT_FILTERED',
-  'X_SEARCH_UNDECLARED',
-  'X_SEARCH_IN_MEMORY',
-  'X_STATE_UNDECLARED',
-  'X_STATE_TRANSITION_ILLEGAL',
-  'X_STATE_CONFLICT',
-] as const;
-
-/**
- * `X_DB_DRIFT` is `@ultimat3/db`'s — drift is a fact about migrations, and this package imports db
- * rather than the other way round. `dbDrift()` below throws it; nothing here titles it, because a
- * second copy of the title is what lets the two packages disagree about what the code means.
- */
-export const ENTITY_BORROWED_ERROR_CODES = ['X_DB_DRIFT'] as const;
-
-/** Every code entity can throw: the ones it owns plus the one it borrows. */
-export const ENTITY_ERROR_CODES = [
-  ...ENTITY_OWNED_ERROR_CODES,
-  ...ENTITY_BORROWED_ERROR_CODES,
-] as const;
-
-export type EntityOwnedErrorCode = (typeof ENTITY_OWNED_ERROR_CODES)[number];
-export type EntityErrorCode = (typeof ENTITY_ERROR_CODES)[number];
-
-export const ENTITY_ERROR_TITLES: Readonly<Record<EntityOwnedErrorCode, string>> = {
-  X_ENTITY_DUPLICATE: 'two entities claim the same name',
-  X_INVARIANT_VIOLATED: 'a domain invariant rejected this row',
-  X_TENANCY_UNSCOPED: 'a tenant-scoped query has no org predicate',
-  // "call", not "query": the same code covers a predicate that names another tenant and a row or
-  // patch that writes one, because they are one mistake made in two places.
-  X_TENANCY_ACTOR_MISMATCH: "a call named a tenant other than the actor's",
-  X_TENANCY_ACTOR_ORG_REQUIRED: 'the acting actor carries no tenant',
-  X_TENANCY_CROSS_DENIED: 'a cross-tenant read was entered without the capability',
-  X_NOT_FOUND: 'no row for that id',
-  X_WRITE_UNFILTERED: 'a filtered write named no filter columns',
-  X_PATCH_EMPTY: 'a filtered update named no columns to write',
-  X_PRELOAD_UNKNOWN_RELATION: 'no relation of that name on this entity',
-  X_N_PLUS_ONE_QUERY: 'a read repeated once per row',
-  X_N_PLUS_ONE_WRITE: 'a write repeated once per row',
-  X_REPO_CLIENT_PINNED: 'a repository pinned to its own client cannot join the open transaction',
-  X_AGGREGATE_UNSUPPORTED: 'that column has no aggregate both drivers can answer alike',
-  X_AGGREGATE_MIXED_CURRENCY: 'an amount was aggregated across currencies',
-  X_APPROXIMATE_COUNT_FILTERED: 'an estimate was asked of a filtered chain',
-  X_SEARCH_UNDECLARED: 'this entity has no searchable column',
-  X_SEARCH_IN_MEMORY: 'the in-memory driver cannot answer a full-text match',
-  X_STATE_UNDECLARED: 'that column declares no state machine',
-  X_STATE_TRANSITION_ILLEGAL: 'the machine has no such transition',
-  X_STATE_CONFLICT: 'the row is no longer in the state this transition named',
-};
-
-// Registered at module load, unconditionally, in one call. Without this the registry humanises the
-// code and every surface renders a title this package never wrote; with a presence guard, a second
-// package claiming one of these codes would silently win instead of throwing X_ERROR_CODE_DUPLICATE.
-registerErrorCodes(
-  Object.fromEntries(Object.entries(ENTITY_ERROR_TITLES).map(([code, title]) => [code, { title }])),
-);
-
-/**
- * Base for every error this package throws. No `docs:` — `UltimateError` fills it from
- * `describeErrorCode(code).docs`, which is `@ultimat3/core`'s `ERROR_DOCS_URL`: one page for every
- * code, never one per code, because `wiki/` is the framework's only public documentation surface
- * and a code lives there in a TABLE ROW, which has no anchor. The
- * `https://ultimate.dev/errors/<code>` links this class built until 9.x answered 404, host
- * included, on every refusal it has ever raised.
- */
-export class EntityError extends UltimateError {
-  override readonly name = 'EntityError';
-
-  constructor(init: { code: EntityErrorCode; cause: string; fix: string }) {
-    super({
-      code: init.code,
-      cause: init.cause,
-      fix: init.fix,
-    });
-  }
-}
+export type { EntityErrorCode, EntityOwnedErrorCode } from './entity-error';
+export {
+  ENTITY_BORROWED_ERROR_CODES,
+  ENTITY_ERROR_CODES,
+  ENTITY_ERROR_TITLES,
+  ENTITY_OWNED_ERROR_CODES,
+  EntityError,
+  entityDuplicate,
+  invariantViolated,
+} from './entity-error';
 
 /**
  * A value from an app, rendered for a `cause` — and it may not throw, whatever the app put there.
@@ -130,31 +48,6 @@ const renderValue = (value: unknown): string => {
 const asLiteral = (value: unknown, placeholder: string): string =>
   typeof value === 'string' ? JSON.stringify(value) : placeholder;
 
-export const entityDuplicate = (name: string, existingTable: string): EntityError =>
-  new EntityError({
-    code: 'X_ENTITY_DUPLICATE',
-    cause: `entity "${name}" is already registered for table "${existingTable}"`,
-    fix: `x entities list --json   # then rename one of the two entity({ name }) declarations`,
-  });
-
-/**
- * The entity name is a VALUE, never a literal — `entity.$name`, `table`, the `name` `entity()` was
- * given. A literal is an entity that does not exist, and this fix then hands the reader
- * `x entities describe column --json`, which answers `X_DECLARATION_UNKNOWN` (issue #290). A
- * refusal raised before any entity exists belongs in `refuse.ts`, where the caller supplies the
- * edit; `refuse.test.ts` fails on a literal here.
- */
-export const invariantViolated = (
-  entityName: string,
-  invariantName: string,
-  message: string,
-): EntityError =>
-  new EntityError({
-    code: 'X_INVARIANT_VIOLATED',
-    cause: `${entityName}.${invariantName}: ${message}`,
-    fix: `x entities describe ${entityName} --json   # shows the invariant and its SQL CHECK`,
-  });
-
 /**
  * One code, two situations, and they do not share a repair — so the cause and the fix branch on
  * which one it is rather than one wording claiming the other's facts.

package/src/index.ts

@@ -80,6 +80,7 @@ export { assertInvariants, invariant, MAX_ASSERTED_ROWS } from './invariants';
 export { memoryRepo, memoryTransactor } from './memory-repo';
 export type { StatementLoop } from './n-plus-one';
 export { N_PLUS_ONE_THRESHOLD, nPlusOne, preloadsFor } from './n-plus-one';
+export { persistedRecordTypes } from './persisted-types';
 export type { PostgresDriverOptions } from './pg-driver';
 export { postgresDriver, postgresRepo, postgresTransactor } from './pg-driver';
 // The two page bounds, beside `N_PLUS_ONE_THRESHOLD` and for the same reason: an app validating
@@ -88,6 +89,12 @@ export { DEFAULT_PAGE_SIZE, MAX_PAGE_SIZE } from './plan';
 export type { RelatedTable, RelatedTables } from './preload';
 export type { Preloaded, ReadBuilder, Table } from './query';
 export { tableFor } from './query';
+// The client projection of an entity (plan 101): record type, record key, and the brand on
+// `$schema` that lets an action or query derive its record envelope from its output schema.
+// Value-light — no Postgres driver behind any of them — so a browser store may import them here.
+export type { ProjectedEntity, RecordProjection } from './record-projection';
+export { ENTITY_BRAND, recordProjection } from './record-projection';
+export { recordProjectionForTable, recordTypeForTable } from './record-table';
 export type {
   ColumnDescription,
   EntityDescription,
@@ -119,6 +126,8 @@ export type {
 } from './repo';
 export type { RowBulkChange, RowChange, RowChangeOp, RowObserver } from './row-observer';
 export { observedRepo, rowObserver, setRowObserver } from './row-observer';
+export type { RecordsByKey, RecordsByType } from './rows-of';
+export { hasEntityRows, projectionsIn, rowsOf } from './rows-of';
 // Full-text search. The LANGUAGE set and the weights are values an app reads to build a form;
 // `SEARCH_PROPERTY` is what a `matches` predicate names, which a hand-built `QueryPlan` needs.
 export type { SearchInit, SearchLanguage, SearchSource, SearchVector } from './search';

package/src/persisted-types.ts

@@ -0,0 +1,21 @@
+// The record types the client keeps on disk — every registered entity declared `persist: true`,
+// by name, sorted. What the server renders as `<meta name="ultimate-persist">`, since the browser
+// holds no entity declarations. Memoised against the registry's generation, like `record-table.ts`.
+
+import { registeredEntities, registryGeneration } from './registry';
+
+let cached: { readonly generation: number; readonly types: readonly string[] } | null = null;
+
+/** Sorted, so the rendered meta is byte-identical for one set of declarations. */
+export const persistedRecordTypes = (): readonly string[] => {
+  const generation = registryGeneration();
+  if (cached !== null && cached.generation === generation) return cached.types;
+  const types = Object.freeze(
+    registeredEntities()
+      .filter((entry) => entry.persist === true)
+      .map((entry) => entry.name)
+      .sort(),
+  );
+  cached = { generation, types };
+  return types;
+};

package/src/pg-driver.ts

@@ -60,6 +60,7 @@ import type { FindManyArgs, Repo, Transactor, UpsertArgs } from './repo';
 import type { QueryPlan } from './tenancy';
 import { assertRowTenant } from './tenancy';
 import type { RowWrite } from './types';
+import { taggedWrite } from './write-tag';
 
 export interface PostgresDriverOptions {
   /**
@@ -156,14 +157,14 @@ export const postgresRepo = <Row>(
       : deleteStatement(entity, plan);
 
   /**
-   * Every write goes out through here, which makes it the ONE place the request's preloaded rows
-   * are dropped: a row this statement changes must not be served afterwards from a page read
-   * before it. Before the statement, not after — a row read back afterwards is the row this write
-   * left, and one read concurrently with it was concurrent either way.
+   * Every write goes out through here: the ONE place the request's preloaded rows are dropped (a
+   * row this statement changes must not be served afterwards from a page read before it — so
+   * before the statement, not after), and where a keyed request's write names itself in the WAL
+   * (`write-tag.ts`).
    */
   const writing = <T>(send: () => Promise<T>): Promise<T> => {
     forgetPreloaded(entity.$name);
-    return send();
+    return taggedWrite(config.client !== undefined, send);
   };
 
   /**

package/src/record-key.ts

@@ -0,0 +1,59 @@
+// A row's record key: its primary-key columns rendered to one string, in DECLARED order, so the
+// client store keys one record once whatever order a row's own properties arrived in. Runs in the
+// browser too (the store keys adopted rows with it), so it imports nothing a page cannot carry.
+
+import { isFixShellSafe, type Row, renderFixShellArg } from '@ultimat3/core';
+import { describeValue } from '@ultimat3/schema';
+import { EntityError } from './entity-error';
+
+/**
+ * A row reached a record key without one of its primary-key columns — a handler built the row by
+ * hand, or a partial row was handed where a whole one was declared. Refused, never keyed as
+ * `undefined`: two keyless rows would be ONE record in the store and overwrite each other.
+ *
+ * The value is described by SHAPE, never echoed: a key is the caller's data, and this cause
+ * reaches the log line.
+ */
+export const recordKeyMissing = (type: string, column: string, value: unknown): EntityError =>
+  new EntityError({
+    code: 'X_RECORD_KEY_MISSING',
+    cause: `a ${type} row reached its record key with primary-key column "${column}" holding ${describeValue(value)}, not a string, number, bigint, boolean or Date`,
+    // Screened, never spliced: an entity NAME is only checked as an identifier when it is also the
+    // table, so a declared name carrying shell syntax degrades to prose rather than a command. The
+    // `renderFixShellArg` inside the safe branch is verbatim there; it is the call
+    // `bun run fix-shell-arg` recognises as the screen.
+    fix: isFixShellSafe(type)
+      ? `x entities describe ${renderFixShellArg(type, 'ENTITY')} --json   # lists the primary key; return the whole row (every primary-key column) from the handler that built this one`
+      : 'x entities list --json   # find this entity, then return the whole row (every primary-key column) from the handler that built this one',
+  });
+
+/** One part of a key. `Object.hasOwn`, never `row[column]` alone: an inherited member is no key. */
+const partOf = (type: string, row: Row, column: string): string => {
+  const value = Object.hasOwn(row, column) ? row[column] : undefined;
+  switch (typeof value) {
+    case 'string':
+      return value;
+    case 'number':
+      if (Number.isFinite(value)) return String(value);
+      break;
+    case 'bigint':
+    case 'boolean':
+      return String(value);
+    default:
+      if (value instanceof Date && !Number.isNaN(value.getTime())) return value.toISOString();
+  }
+  throw recordKeyMissing(type, column, value);
+};
+
+/**
+ * A single key is the value itself, so it is the same string `$tagFor(id)` and every realtime
+ * topic already carry. A composite key percent-encodes each part before joining on `:`, so a part
+ * holding the separator cannot make two different rows one key.
+ */
+export const recordKeyOf =
+  (type: string, primaryKey: readonly string[]) =>
+  (row: Row): string => {
+    const [only, ...rest] = primaryKey;
+    if (only !== undefined && rest.length === 0) return partOf(type, row, only);
+    return primaryKey.map((column) => encodeURIComponent(partOf(type, row, column))).join(':');
+  };

package/src/record-projection.ts

@@ -0,0 +1,88 @@
+// An entity's client projection — record type, record key, row node, persist — and the brand that
+// carries it on the entity's row schema. Value-light on purpose: the browser store imports this,
+// and nothing here may reach the Postgres driver.
+
+import type { Row } from '@ultimat3/core';
+import { isSchemaNode, type SchemaNode } from '@ultimat3/schema';
+import { invariantViolated } from './entity-error';
+import { recordKeyOf } from './record-key';
+
+/**
+ * `Symbol.for`, not `Symbol()`: islands are separate bundles, so a row schema declared in one and
+ * walked in another holds a brand minted by a different copy of this module. Only the registry key
+ * is the same symbol in both.
+ */
+export const ENTITY_BRAND: unique symbol = Symbol.for('ultimate.entity');
+
+export interface RecordProjection {
+  /** The wire name — the entity's name, the framework's key for it everywhere else too. */
+  readonly type: string;
+  /**
+   * The physical relation. A changefeed and a snapshot speak TABLES; `recordTypeForTable` is how
+   * they reach `type`, and this is the same fact read from the other end.
+   */
+  readonly table: string;
+  /** Primary key → string, in declared order. Throws `X_RECORD_KEY_MISSING`. */
+  readonly key: (row: Row) => string;
+  /** The row's schema IR — JSON, so a store can put it on disk beside the rows. */
+  readonly schema: SchemaNode;
+  /**
+   * Whether the client keeps this entity's records on disk — `entity(name, { persist: true })`,
+   * default `false`. Realtime's persister reads it here, never off the declaration.
+   */
+  readonly persist: boolean;
+}
+
+/** What `entity()` hands the projection: everything but the row node, which the schema builds. */
+export interface ProjectionIdentity {
+  readonly name: string;
+  readonly table: string;
+  readonly primaryKey: readonly string[];
+  readonly persist: boolean;
+}
+
+/** Built once per `entity()`, frozen: the brand, `recordProjection` and `rowsOf` share one object. */
+export const createProjection = (
+  { name, table, primaryKey, persist }: ProjectionIdentity,
+  schema: SchemaNode,
+): RecordProjection =>
+  Object.freeze({ type: name, table, key: recordKeyOf(name, primaryKey), schema, persist });
+
+/**
+ * The projection a schema node is branded with, or `undefined`. Own and non-enumerable: an
+ * enumerable symbol would ride every spread and `toEqual` of the IR, and an inherited one would
+ * brand every node built from a branded prototype.
+ */
+export const projectionOf = (node: unknown): RecordProjection | undefined => {
+  if (!isSchemaNode(node) || !Object.hasOwn(node, ENTITY_BRAND)) return undefined;
+  return (node as { readonly [ENTITY_BRAND]?: RecordProjection })[ENTITY_BRAND];
+};
+
+/** Brands `node` in place. Called by the row schema on its own node and on each wrapper's. */
+export const brandNode = (node: SchemaNode, projection: RecordProjection): void => {
+  Object.defineProperty(node, ENTITY_BRAND, { value: projection, enumerable: false });
+};
+
+/** The structural slice of an entity this reads — so it never imports `entity.ts`. */
+export interface ProjectedEntity {
+  readonly $name: string;
+  readonly $schema: { readonly node: SchemaNode };
+}
+
+/**
+ * `recordProjection(posts)` — the one answer to "what is this entity on the client". Read off the
+ * brand rather than rebuilt, so the store, the envelope and `rowsOf` hold the same object.
+ */
+export const recordProjection = (entity: ProjectedEntity): RecordProjection => {
+  const projection = projectionOf(entity.$schema.node);
+  // Every `entity()` brands its row schema, so absence means a hand-built lookalike: the type is
+  // `EntityCore`, and the only way here without a brand is a cast.
+  if (projection === undefined) {
+    throw invariantViolated(
+      entity.$name,
+      '$schema',
+      'carries no record brand; declare it with entity()',
+    );
+  }
+  return projection;
+};

package/src/record-table.ts

@@ -0,0 +1,46 @@
+// Table → record type, over the registered entities. A changefeed and a snapshot name the
+// physical relation; the client store keys records by entity name, and this is the one bridge —
+// memoised against the registry's generation, so a per-change lookup is one `Map` read.
+
+import { invariantViolated } from './entity-error';
+import type { RecordProjection } from './record-projection';
+import type { RegistryEntry } from './registry';
+import { registeredEntities, registryGeneration } from './registry';
+
+let cached: {
+  readonly generation: number;
+  readonly byTable: ReadonlyMap<string, RegistryEntry>;
+} | null = null;
+
+const tableIndex = (): ReadonlyMap<string, RegistryEntry> => {
+  const generation = registryGeneration();
+  if (cached !== null && cached.generation === generation) return cached.byTable;
+  const byTable = new Map<string, RegistryEntry>();
+  for (const entry of registeredEntities()) {
+    const other = byTable.get(entry.tableName);
+    // Two entities over one relation (`table:` lets an app adopt a table twice) leave a changed
+    // row with no single record type; refused rather than guessed, since the wrong guess writes
+    // one entity's row into another's records.
+    if (other !== undefined) {
+      throw invariantViolated(
+        entry.name,
+        'table',
+        `shares table "${entry.tableName}" with entity "${other.name}", so a change on it has no one record type — give one of them its own table, or stop streaming it`,
+      );
+    }
+    byTable.set(entry.tableName, entry);
+  }
+  cached = { generation, byTable };
+  return byTable;
+};
+
+/** The record type (entity name) a table's rows belong to, or `undefined` for an unknown table. */
+export const recordTypeForTable = (table: string): string | undefined =>
+  tableIndex().get(table)?.name;
+
+/**
+ * The whole client projection a table's rows belong to — type, key, row schema, `persist` — or
+ * `undefined` for an unknown table. Same index as `recordTypeForTable`, so the two never disagree.
+ */
+export const recordProjectionForTable = (table: string): RecordProjection | undefined =>
+  tableIndex().get(table)?.projection;

package/src/record.ts

@@ -0,0 +1,10 @@
+// `@ultimat3/entity/record` — the entity's client projection, and nothing that reaches a driver.
+// The package barrel re-exports the same bindings for server code; a BROWSER module imports them
+// from here, because the barrel retains ~1 MB of SQL rendering (`pg-sql.ts`, `@ultimat3/db`) a page
+// never runs — measured in `record-bundle.test.ts`, which fails if this entry ever grows it back.
+
+export type { ProjectedEntity, RecordProjection } from './record-projection';
+export { ENTITY_BRAND, recordProjection } from './record-projection';
+export { recordProjectionForTable, recordTypeForTable } from './record-table';
+export type { RecordsByKey, RecordsByType } from './rows-of';
+export { hasEntityRows, rowsOf } from './rows-of';

package/src/registry.ts

@@ -4,8 +4,9 @@
 // than a silent last-one-wins.
 
 import type { IndexMethod } from '@ultimat3/db';
-import { entityDuplicate } from './errors';
+import { entityDuplicate } from './entity-error';
 import type { InvariantKind } from './invariants';
+import type { RecordProjection } from './record-projection';
 import type { ColumnDefault, OnDelete } from './types';
 
 export interface ColumnDescription {
@@ -128,6 +129,10 @@ export interface EntityDescription {
 export interface RegistryEntry {
   readonly name: string;
   readonly tableName: string;
+  /** `entity(name, { persist: true })` — the client keeps this type on disk. Absent = `false`. */
+  readonly persist?: boolean;
+  /** The entity's client projection — what a changefeed's table maps to on the client. */
+  readonly projection?: RecordProjection;
   describe(): EntityDescription;
   /**
    * The foreign keys this entity declares, resolved. This is how a relation reaches query time:

package/src/row-observer.ts

@@ -13,6 +13,7 @@
 // the replicator — `@ultimat3/realtime`'s `selectChangeFeed` still decides, and this is never in
 // that decision.
 
+import { currentWriteOrigin } from '@ultimat3/core';
 import { expectedQueryLoop } from '@ultimat3/db';
 import type { EntityCore } from './entity';
 import { MAX_PAGE_SIZE } from './plan';
@@ -32,6 +33,13 @@ export interface RowChange {
   readonly op: RowChangeOp;
   readonly before: Readonly<Record<string, unknown>> | null;
   readonly after: Readonly<Record<string, unknown>> | null;
+  /**
+   * The keyed write this change belongs to — `@ultimat3/core`'s `currentWriteOrigin()` at the
+   * moment the repository wrote, i.e. the digest of the idempotency key the request arrived with.
+   * The WAL decoder reads the same fact off the transaction's opening message; absent both ways
+   * for a write no keyed request made.
+   */
+  readonly write?: string;
 }
 
 /**
@@ -177,7 +185,15 @@ export function observedRepo<Row>(entity: EntityCore<Row>, repo: Repo<Row>): Rep
   const name = entity.$name;
 
   const emit = (op: RowChangeOp, before: unknown, after: unknown): void => {
-    installed?.onChange({ entity: name, op, before: asRecord(before), after: asRecord(after) });
+    if (installed === null) return;
+    const write = currentWriteOrigin();
+    installed.onChange({
+      entity: name,
+      op,
+      before: asRecord(before),
+      after: asRecord(after),
+      ...(write === undefined ? {} : { write }),
+    });
   };
 
   const bulk = (op: 'delete' | 'update', rows: number): void => {

package/src/row-schema.ts

@@ -0,0 +1,63 @@
+// `entity.$schema` — the whole row as a `t`-compatible schema, branded with the entity's record
+// projection. The brand is what lets `rowsOf` find a row inside any output shape, so it has to
+// survive every wrapper a row can be put in: containers keep the child node by reference, and the
+// five methods that COPY a node are re-branded here rather than in `@ultimat3/schema`.
+
+import { renderThrowable } from '@ultimat3/core';
+import { fail, makeSchema, pass, type Schema, type SchemaNode } from '@ultimat3/schema';
+import {
+  brandNode,
+  createProjection,
+  type ProjectionIdentity,
+  type RecordProjection,
+} from './record-projection';
+import type { AnyColumn } from './types';
+import { columnNode } from './view';
+
+/**
+ * Re-brands whatever a copying method returns. `nullable()`, `optional()`, `default()`,
+ * `describe()` and `refine()` each build a fresh node by spreading this one, and a spread drops a
+ * non-enumerable symbol — so without this, `t.nullable(posts.$schema)` would be a row nobody
+ * recognises. `refine()` keeps the brand because it keeps the shape; `.pick()` is not here
+ * because an entity row schema has none, and a `t.object` that does builds an unbranded node.
+ */
+const branded = <In, Out>(
+  schema: Schema<In, Out>,
+  projection: RecordProjection,
+): Schema<In, Out> => {
+  brandNode(schema.node, projection);
+  return {
+    ...schema,
+    optional: () => branded(schema.optional(), projection),
+    nullable: () => branded(schema.nullable(), projection),
+    default: (value) => branded(schema.default(value), projection),
+    describe: (description) => branded(schema.describe(description), projection),
+    refine: (refinement) => branded(schema.refine(refinement), projection),
+  };
+};
+
+/**
+ * The row schema for one entity. Validation IS `$parse` — defaults filled, every column parsed —
+ * so `$schema` and `$parse` can never disagree about what a row is. A refusal is rendered with
+ * `renderThrowable`, never `instanceof`/`String()`: a column parser is app-reachable and may throw
+ * anything, and a second `TypeError` out of a validator is the one outcome a validator may not have.
+ */
+export const rowSchema = <Row>(
+  identity: ProjectionIdentity,
+  columns: readonly (readonly [string, AnyColumn])[],
+  parse: (value: unknown) => Row,
+): Schema<unknown, Row> => {
+  const node: SchemaNode = {
+    kind: 'object',
+    properties: Object.fromEntries(columns.map(([key, column]) => [key, columnNode(column)])),
+  };
+  const projection = createProjection(identity, node);
+  const schema = makeSchema<unknown, Row>(node, (value, path) => {
+    try {
+      return pass(parse(value));
+    } catch (error) {
+      return fail(path, renderThrowable(error));
+    }
+  });
+  return branded(schema, projection);
+};

package/src/rows-of.ts

@@ -0,0 +1,132 @@
+// Which values in an output are entity rows — read off the output SCHEMA, never declared beside it
+// (axiom 2). `hasEntityRows` answers statically and is memoised per node; `rowsOf` walks only the
+// branches that can hold a row, so an output with none costs one WeakMap read per call.
+
+import type { Row } from '@ultimat3/core';
+import { isSchemaNode, nodeOf, type SchemaNode } from '@ultimat3/schema';
+import { projectionOf, type RecordProjection } from './record-projection';
+
+/** Children in the IR that can hold a value: object fields, array items, record values, arms. */
+const childrenOf = (node: SchemaNode): readonly SchemaNode[] => [
+  ...Object.values(node.properties ?? {}),
+  ...(node.items === undefined ? [] : [node.items]),
+  ...(node.valueNode === undefined ? [] : [node.valueNode]),
+  ...(node.anyOf ?? []),
+];
+
+const holdsRows = new WeakMap<SchemaNode, boolean>();
+
+const containsBrand = (node: SchemaNode): boolean => {
+  const known = holdsRows.get(node);
+  if (known !== undefined) return known;
+  // Seeded `false` before recursing, so a node reachable from itself ends rather than overflows.
+  holdsRows.set(node, false);
+  const answer = projectionOf(node) !== undefined || childrenOf(node).some(containsBrand);
+  holdsRows.set(node, answer);
+  return answer;
+};
+
+/** A schema object (anything carrying `node`) or a bare node; anything else has no rows. */
+const rootOf = (schema: unknown): SchemaNode | undefined =>
+  nodeOf(schema) ?? (isSchemaNode(schema) ? schema : undefined);
+
+/** Does this output schema reference any entity row, at any depth? Static — no value needed. */
+export const hasEntityRows = (schema: unknown): boolean => {
+  const root = rootOf(schema);
+  return root !== undefined && containsBrand(root);
+};
+
+/**
+ * Every entity projection an output schema can carry, one per record type, in first-seen order.
+ * Static, like `hasEntityRows`: a branded node is a row and its columns are never walked. What a
+ * caller needing the ENTITIES rather than the rows reads — `@ultimat3/action`'s mutator clock check.
+ */
+export const projectionsIn = (schema: unknown): readonly RecordProjection[] => {
+  const root = rootOf(schema);
+  if (root === undefined) return [];
+  const found = new Map<string, RecordProjection>();
+  const seen = new Set<SchemaNode>();
+  const visit = (node: SchemaNode): void => {
+    if (seen.has(node) || !containsBrand(node)) return;
+    seen.add(node);
+    const projection = projectionOf(node);
+    if (projection !== undefined) {
+      if (!found.has(projection.type)) found.set(projection.type, projection);
+      return;
+    }
+    for (const child of childrenOf(node)) visit(child);
+  };
+  visit(root);
+  return [...found.values()];
+};
+
+const isObject = (value: unknown): value is Readonly<Record<string, unknown>> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+/**
+ * Inside a union the IR cannot say which arm a value took, so a branded arm claims the value only
+ * when it carries every column of that row as an OWN key — `$parse` writes every column, `null`
+ * included, so a real row always does. Outside a union the output schema already validated the
+ * value, and it is taken as the row it was declared to be.
+ */
+const fits = (projection: RecordProjection, value: Readonly<Record<string, unknown>>): boolean =>
+  Object.keys(projection.schema.properties ?? {}).every((column) => Object.hasOwn(value, column));
+
+type Found = Map<string, Map<string, Row>>;
+
+const collect = (found: Found, projection: RecordProjection, row: Row): void => {
+  const byKey = found.get(projection.type) ?? new Map<string, Row>();
+  found.set(projection.type, byKey);
+  const key = projection.key(row);
+  // First sighting wins: one record shown twice in a response is one record, not two writes.
+  if (!byKey.has(key)) byKey.set(key, row);
+};
+
+const walk = (node: SchemaNode, value: unknown, found: Found, inUnion: boolean): void => {
+  if (value === null || value === undefined || !containsBrand(node)) return;
+  const projection = projectionOf(node);
+  if (projection !== undefined) {
+    // A row's own columns are never walked: a column node carries no brand, and a `json()` value
+    // shaped like a row is data, not a record.
+    if (isObject(value) && (!inUnion || fits(projection, value))) collect(found, projection, value);
+    return;
+  }
+  if (node.kind === 'array' && node.items !== undefined && Array.isArray(value)) {
+    for (const item of value) walk(node.items, item, found, inUnion);
+  } else if (node.kind === 'object' && node.properties !== undefined && isObject(value)) {
+    for (const [key, child] of Object.entries(node.properties)) {
+      if (Object.hasOwn(value, key)) walk(child, value[key], found, inUnion);
+    }
+  } else if (node.kind === 'record' && node.valueNode !== undefined && isObject(value)) {
+    for (const entry of Object.values(value)) walk(node.valueNode, entry, found, inUnion);
+  } else if (node.kind === 'union') {
+    for (const arm of node.anyOf ?? []) walk(arm, value, found, true);
+  }
+};
+
+/** Keyed by record key, null-prototype: a key is data, and `'__proto__'` must stay a key. */
+export type RecordsByKey = Readonly<Record<string, Row>>;
+
+/** Keyed by record type, then by record key — the shape the record envelope carries on the wire. */
+export type RecordsByType = Readonly<Record<string, RecordsByKey>>;
+
+const nullProto = <V>(entries: Iterable<readonly [string, V]>): Readonly<Record<string, V>> => {
+  const out = Object.create(null) as Record<string, V>;
+  for (const [key, value] of entries) out[key] = value;
+  return out;
+};
+
+/**
+ * Every entity row in `value`, grouped by record type and keyed by record key — `{}` when the
+ * schema references none. The KEY travels because the browser cannot compute it: it would have to
+ * import the app's `entity()` declarations. The rows are the SAME objects the handler returned,
+ * one per key; a row with no key is `X_RECORD_KEY_MISSING`, because a keyless record would
+ * overwrite every other keyless one.
+ */
+export const rowsOf = (schema: unknown, value: unknown): RecordsByType => {
+  const root = rootOf(schema);
+  if (root === undefined || !containsBrand(root)) return nullProto([]);
+  const found: Found = new Map();
+  walk(root, value, found, false);
+  return nullProto([...found].map(([type, byKey]) => [type, nullProto(byKey)] as const));
+};

package/src/write-tag.ts

@@ -0,0 +1,75 @@
+// A keyed write names itself in the write-ahead log. The Postgres driver opens the transaction a
+// keyed request's write lands in with `pg_logical_emit_message(true, WRITE_ORIGIN_WAL_PREFIX,
+// <digest>)`, and `@ultimat3/realtime`'s replication stream names every change after it with that
+// digest — which is how a `records` frame produced by the replicator, in another process, still
+// tells the page that wrote it that this is its own echo. The in-process row observer reads the
+// same fact off the request scope and needs none of this.
+
+import { currentWriteOrigin, WRITE_ORIGIN_WAL_PREFIX } from '@ultimat3/core';
+import { currentTx, type DbClient, type DbTx, db, sql, withTransaction } from '@ultimat3/db';
+
+/** Transactions this process already opened with the message: one per transaction is enough. */
+const tagged = new WeakSet<DbTx>();
+
+/**
+ * Whether this database lets the app's role emit the message. Asked once per process and
+ * remembered only once answered: a role without `EXECUTE` (a managed service may revoke it) must
+ * cost the page its echo match, never the write — so the answer is read BEFORE the first emit
+ * rather than learned from a failed one, which would already have aborted the caller's transaction.
+ */
+let emits: Promise<boolean> | undefined;
+
+/**
+ * By name, across overloads: Postgres 17 added a fourth parameter (`flush`, defaulted), so a probe
+ * naming the three-argument signature answered "no such function" there while the call below works
+ * on every version from 14 up. Measured on 17-alpine.
+ */
+const CAN_EMIT = sql`select exists (select 1 from pg_catalog.pg_proc where proname = 'pg_logical_emit_message' and has_function_privilege(oid, 'execute')) as "ok"`;
+
+function canEmit(client: DbClient): Promise<boolean> {
+  if (emits === undefined) {
+    const asked = client.one<{ ok: unknown }>(CAN_EMIT).then((row) => row?.ok === true);
+    emits = asked;
+    // A probe that FAILED answered nothing: the next write asks again.
+    asked.catch(() => {
+      if (emits === asked) emits = undefined;
+    });
+  }
+  return emits.catch(() => false);
+}
+
+const emit = (client: DbClient, digest: string): Promise<unknown> =>
+  client.query(
+    sql`select pg_logical_emit_message(true, ${WRITE_ORIGIN_WAL_PREFIX}::text, ${digest}::text)`,
+  );
+
+/**
+ * Send `write` so the WAL names the keyed write it belongs to. Outside a keyed request, or on a
+ * repository pinned to its own client (which may not join a transaction — `X_REPO_CLIENT_PINNED`),
+ * it is `write()` unchanged. Inside an open transaction the message goes first, once. Outside one,
+ * the write is wrapped in a transaction of its own, because a message in another transaction names
+ * nothing: three more round trips per keyed write, and only for a write a page is waiting on.
+ */
+export async function taggedWrite<T>(pinned: boolean, write: () => Promise<T>): Promise<T> {
+  const digest = currentWriteOrigin();
+  if (digest === undefined || pinned) return write();
+  const open = currentTx();
+  if (!(await canEmit(open ?? db()))) return write();
+  if (open !== undefined) {
+    if (!tagged.has(open)) {
+      await emit(open, digest);
+      tagged.add(open);
+    }
+    return write();
+  }
+  return withTransaction(async (tx) => {
+    await emit(tx, digest);
+    tagged.add(tx);
+    return write();
+  });
+}
+
+/** Forget the capability answer. Tests only: a process asks one database once. */
+export function resetWriteTag(): void {
+  emits = undefined;
+}