okengine 0.17.2 → 0.18.3

package/site/content/docs/elements/store.mdx

@@ -5,9 +5,7 @@ icon: "Database"
 source: "docs/spec/unified-theory.md"
 ---
 
-Store is one handle, four independent facets — **sql · kv · files · index**. Each has its own
-shape; nothing forces you to use more than one. Flow code stays the same across environments;
-only the driver changes.
+Store is one handle, four independent facets — **sql · kv · files · index**. Each has its own shape; nothing forces you to use more than one. Flow code stays the same across environments; only the driver changes. Every facet accepts an optional `description` — a human title in the Console (falls back to the store name) — and auto-registers when its declaring module is imported before `oke()` (`oke({ stores })` is still valid and additive).
 
 <Callout title="The one rule">
   Drivers are named after **protocols**, not vendors (`postgres`, `redis`, `s3` — never `neon` or
@@ -16,98 +14,7 @@ only the driver changes.
 
 <StoreFacets />
 
-Every facet accepts optional `description` — a human title in the Console (falls back to the store
-name).
-
-`store.sql` / `kv` / `files` / `index` auto-register when the declaring module is imported before
-`oke()`. `oke({ stores })` is still valid and additive.
-
-## SQL
-
-<StoreFacetMark facet="sql" />
-
-The relational facet: tables, schema, and typed single-table sessions through `fx.store`.
-
-The Console SQL band opens a query console (`POST /console/store/sql`) for
-DML and DDL. ⌘Enter runs the current statement or selection; ⌘⇧Enter runs
-the whole script sequentially and stops on the first error.
-
-EXPLAIN / EXPLAIN ANALYZE wrap the current statement. A script with more
-than one result opens a tab per statement.
-
-The table grid can insert a row (`POST /console/store/edit` without `id`).
-Double-click a tab to rename; Save keeps named queries. Completions cover
-Manifest tables, columns, and keywords.
-
-Classified PII stays masked unless the toolbar **PII** control is on
-(`revealPii: true`, audited).
-
-**Gate** views as Operator (bypass), public, a user, or a policy. SQL,
-browse, and grid edit send `{ asGate, asUserId }`. postgres / pglite stamp
-`oke.gate()` / `oke.user()` / `oke.has_scope()`; memory is catalog-only.
-
-The SQL band **Schema** control opens a visualizer of Manifest tables and
-relations — declared `.references()` plus inferred `*_id` columns — not the
-query-console Schema rail.
-
-<Callout title="Query performance">
-  SQL **Performance** reads `pg_stat_statements` and live locks
-  (`QUERY /console/store/sql/stats` and `/locks`).
-
-Alpine needs preload plus `CREATE EXTENSION`. Index Advisor is opt-in on
-[Postgres](/docs/recipes/postgres#query-performance).
-
-KV **Performance** reads Redis-wire `INFO` / `COMMANDSTATS` / `SLOWLOG`
-(`QUERY /console/store/kv/stats`). In-process `memory` is unsupported.
-
-INFO is instance-wide (`StoreKvStatsServerWideGap`). SLOWLOG args collapse
-until reveal (`StoreKvStatsSlowlogArgsGap`). No hot-key table.
-
-</Callout>
-
-**Colorize** groups tables by prefix and FK family. Click a related table to
-dim the rest; click the canvas to show all again.
-
-Edges mark cardinality with icons (many-to-one, one-to-one, many-to-many,
-self). Cards and the query Schema rail mark primary (key), foreign (link),
-and unique (diamond) columns.
-
-Each SQL store also lists **Indexes**, **Functions**, **Triggers**,
-**Extensions**, and **RLS Policies**.
-
-Indexes, Functions, and Triggers use the same flat form as RLS Policies —
-paired fields, compact templates, and a pinned SQL editor — then run
-`CREATE INDEX` / `CREATE FUNCTION` / `CREATE TRIGGER`.
-
-**Advanced** unlocks the leftover Postgres knobs (`CONCURRENTLY` / `INCLUDE`,
-`SECURITY DEFINER` / `PARALLEL`, `CONSTRAINT` / `UPDATE OF`).
-
-Extensions list built-in contrib plus a **Library** (featured cards, search,
-category filter) for TimescaleDB, PostGIS, and `pg_cron`.
-
-Install reviews the `CREATE EXTENSION` SQL; **Advanced** can set `SCHEMA`,
-`VERSION`, and `CASCADE` (`pg_catalog` is refused).
-
-When a newer packaged version exists, the name chip shows **Upgrade**
-(`ALTER EXTENSION … UPDATE`). Names link to the project or Postgres docs.
-
-SQL table rows and the resource header show RLS (emerald / muted shield;
-**N RLS** when policies exist) before **PII**. KV, files, and index have
-no badge — enabling RLS on create flips the shield.
-
-**RLS Policies** lists `pg_policies` plus Manifest `declared` / `live`.
-Two-finger click a row for its sheet, or empty grid to create. Create
-pins SQL | Code (`store.schema.policy` + `pgPolicy`); drag to resize.
-
-**Templates** use `oke.user()` / `oke.gate()` / `oke.has_scope()`.
-Owner cards pick a **Column** (guess `creator_email` / `owner_email`)
-with PK / FK marks. Create stays blocked until a column is picked.
-
-Create policy picks a Gate posture (Read / Write / Both), or **Policy &
-scope**. Those picks fill `USING` / `WITH CHECK`. `TO` stays `public` —
-Gate names are not Postgres roles.
-
-### Quick start
+## Quick start
 
 <Steps>
 
@@ -117,22 +24,22 @@ Gate names are not Postgres roles.
 In `src/schema.decl.ts`, describe your tables with plain field builders — no ORM syntax:
 
 ```typescript title="src/schema.decl.ts"
-import { store, field, id, now } from "okengine";
+import { store, field } from "okengine";
 
 export const notes = store.schema.table("notes", {
-  id: field.text().primaryKey().defaultFn(id),
+  id: field.id().primaryKey(),
   title: field.text().notNull(),
   body: field.text().notNull(),
-  createdAt: field.integer().notNull().defaultFn(now),
+  createdAt: field.integer().notNull().now(),
 });
 ```
 
 </Step>
 
 <Step>
-### Declare the store
+### Declare the store and push the schema
 
-Bind the schema to a SQL store in `src/core.ts`:
+Bind the schema to a SQL store in `src/core.ts`. `oke dev` auto-pushes on save — or run it by hand:
 
 ```typescript title="src/core.ts"
 import { store } from "okengine";
@@ -141,13 +48,6 @@ import { notes } from "./schema.decl";
 export const db = store.sql("notes", { schema: { notes } });
 ```
 
-</Step>
-
-<Step>
-### Push the schema
-
-`oke dev` runs this automatically on save; or run it by hand:
-
 ```bash
 oke db push   # dev — applies the schema to your local database
 ```
@@ -181,7 +81,13 @@ export const createNote = on(
 
 </Steps>
 
-### CRUD without boilerplate — `store.resource`
+## SQL
+
+<StoreFacetMark facet="sql" />
+
+The relational facet: tables, schema, and typed single-table sessions through `fx.store`.
+
+### Resource routes — `store.resource`
 
 Five conventional endpoints (list, create, get, update, remove) expand from one declaration. Each is an ordinary Flow underneath — same contracts, same `fx`:
 
@@ -202,7 +108,7 @@ const notesR = store.resource(db, notes, {
 const mounted = on(http.resource("/notes", notesR.all()).public());
 ```
 
-`.gate(...)` / `.public()` chain like `http.get` — gates on every verb. Live SSE is `.live(signal)` on a GET, not on `http.resource`.
+`.gate(...)` / `.public()` chain like `http.get` — gates on every verb. Passing `live: true` also mounts an SSE `GET <path>/live`; see Live queries below.
 
 The list endpoint's URL is the whole query language:
 
@@ -217,29 +123,123 @@ The list endpoint's URL is the whole query language:
 
 Responses follow the Stripe-style envelope: `{ data, meta, error }`. Clients page with `page.next()` or `for await (const page of api.notes.list({ limit: 20 }))` — `meta.next` / `meta.prev` are the next request (`{ cursor }`), not flags. `mode` is diagnostic. `create` answers **201**, `remove` answers **204**, and a missing row is a typed `NotFound` — never a crash.
 
-#### An admin table
+**Consequence:** `count: "exact"` (the offset default) runs `COUNT(*)` per page. Set `count: "none"` to return only `meta.offset`. Keyset (cursor) paging is the default when `cursor` columns are set — pages stay stable while new rows are inserted, where offset pages would shift and show duplicates.
+
+A request that filters on a forbidden column — `?secret=eq.x` — fails with **422** and the exact message `unknown list param "secret"`. Filterable columns are a whitelist, never an accident.
+
+### Live queries — `live: true` and `.live(table)`
+
+Pass `live: true` to also mount `GET <path>/live` — an SSE feed of per-subscriber classified events (`upsert` / `revoked` / `delete`), gated the same way as the CRUD verbs:
 
 ```typescript
-list: { mode: "offset", count: "exact", limit: 20 },
+const notesR = store.resource(db, notes, {
+  in: NewNote,
+  out: Note,
+  live: true, // synthesizes GET /notes/live + internal live signal
+});
+
+const mounted = on(http.resource("/notes", notesR.all()).gate(member));
 ```
 
-**Consequence:** `count: "exact"` (the offset default) runs `COUNT(*)` to fill `meta.total`. On a huge table that count is the real cost — set `count: "none"` to return only `meta.offset`.
+The live route re-checks RLS for every CDC event under the subscriber's stamped identity. A row that leaves the caller's visibility window arrives as `{ kind: "revoked", id, reason: "rls" | "query" }` — never as a silent stale upsert. `"rls"` means the row no longer passes the subscriber's policies; `"query"` means RLS still allows it but it fell out of the filter or search window. Clients consume it with `useLiveQuery` from `okengine/client-react`.
 
-#### An infinite feed
+`store.resource` is optional. A hand-written flow declares the same live surface with the `.live(table)` trigger modifier and the `liveQuery` helper — identical stream, guardrails, and per-subscriber classification:
 
 ```typescript
-list: { cursor: [notes.createdAt, notes.id], direction: "desc", limit: 20, maxLimit: 100 },
+import { liveQuery } from "okengine";
+
+export const live = on(
+  http.get("/tasks/live").gate(member).live(tasks),
+  flow("tasks.live", {
+    in: { unknown: true },
+    do: async (input, fx) =>
+      liveQuery(fx, tasks, input, {
+        search: [tasks.title],
+        filter: [tasks.status], // same list grammar as store.resource
+        order: "all",
+      }),
+  }),
+);
 ```
 
-**Consequence:** keyset (cursor) paging is the default when `cursor` columns are set — pages stay stable while new rows are inserted, where offset pages would shift and show duplicates.
+`.live(tasks)` stamps the internal `oke/live/sql:tasks` signal at extract and enforces the same guardrails as `live: true` (PK required; `updatedAt` / RLS warnings). The flow body parses the request's query params with the exact list grammar, then opens the classified CDC stream.
 
-#### A public, restricted endpoint
+- `?status=eq.open` filters the live window the same way it filters `GET /tasks`.
+- A flow that also writes other tables (an activity log alongside the main write) never leaks those tables into the stream: classification is per-table.
+
+#### The project-wide default — `oke({ store: { live: true } })`
+
+Live remains **explicitly per-table** (`live: true` / `.live(table)`) unless you flip the whole project. Pass `store: { live: true }` to `oke()` to make every **new** `store.schema.table()` declaration live-by-default — the same automatic CDC + RLS-per-event stream `live: true` provides, without writing it on each declaration:
+
+```typescript
+const app = oke({
+  name: "shop",
+  store: { live: true }, // new tables are live by default from here on
+});
+```
 
 ```typescript
-list: { mode: "offset", filter: "none", limit: 20 },
+// No explicit live needed — this table is live by default.
+export const notes = store.schema.table(
+  "notes",
+  {
+    id: field.text().primaryKey(),
+    updatedAt: field.integer().notNull(),
+  },
+  [store.schema.policy.owner("owner")],
+);
+
+const notesR = store.resource(db, notes, {}); // GET /notes/live synthesized
+const mounted = on(http.resource("/notes", notesR.all()).gate(member));
 ```
 
-**Consequence:** a request that filters on a forbidden column — `?secret=eq.x` — fails with **422** and the exact message `unknown list param "secret"`. Filterable columns are a whitelist, never an accident.
+Three rules keep the flip predictable:
+
+- **Default `false`** — today's explicit-only behavior is unchanged. An app that never sets `store.live` pays zero: no signals synthesized, no `/live` routes, no bundle or runtime difference.
+- **Per-table opt-out** — a specific table stays NOT live under the project flag by declaring `store.schema.live(false)` in its extras array (the same third-argument slot as `store.schema.unscoped()` / `rls()` / policies). `store.resource(db, table, { live: false })` is the equivalent opt-out at the resource layer.
+- **Explicit still wins** — `live: true` on a resource or `.live(table)` on a flow opts a specific surface back in even under an opt-out, matching today's behavior.
+
+```typescript
+export const archive = store.schema.table(
+  "archive",
+  {
+    id: field.text().primaryKey(),
+  },
+  [
+    store.schema.policy.owner("owner"),
+    store.schema.live(false), // exempt from the project-wide default
+  ],
+);
+```
+
+**This flag changes declaration defaults only — never the runtime cost model.** Live-by-default consumes the exact same per-event RLS stamping as an explicit `live: true`. The guardrails below (PK required; `updatedAt` / RLS warnings) fire identically whether a table became live explicitly or via the default flip — there is no separate, weaker code path. What you are trading against is the fan-out profile of the writes below.
+
+#### Live fan-out latency — the real cost model
+
+Every live write fans out one **stamped RLS visibility check per subscriber** (per-event, per-connection): p50 fan-out for one CDC event to `S` subscribers grows linearly with `S` (default Postgres pool concurrency ~16–32, `stamp_p50` ≈ 0.5–1 ms):
+
+```
+p50_fanout ≈ ceil(S / pool_concurrency) × stamp_p50
+```
+
+Measured from the benchmark sweep (G8a / G8c):
+
+| Active subscribers (same table/query) | Estimated p50 fan-out | UX                                            |
+| ------------------------------------- | --------------------- | --------------------------------------------- |
+| **1–30**                              | 1–15 ms               | Instant                                       |
+| **30–80**                             | 15–50 ms              | Instant to snappy                             |
+| **80–150**                            | 50–100 ms             | Snappy; power users may notice on hot tables  |
+| **150–300**                           | 100–200 ms            | **Perceptible lag** — updates arrive in waves |
+| **300+**                              | 200 ms+ linear        | **Not instant** — capacity planning required  |
+
+So before you flip `store.live` project-wide on a large application, weigh it against how many concurrent subscribers each hot table is likely to hold. **>150 concurrent live subscribers on the same resource starts to feel like perceptible lag; >300 is the soft ceiling** for the "real-time feel" without an architectural change. Same cost either way — explicit `live: true` or the default flip — this table is the tradeoff you are enabling. (PGlite dev serializes stamping behind a lock; treat fan-out numbers there as correctness-only, never prod latency.)
+
+`live: true` carries compile-time guardrails at extract, plus durable delivery and runtime watchtowers:
+
+- A table with **no primary key fails extract loud** — upsert/revoked/delete address rows by PK.
+- Missing `updatedAt` / `updated_at` warns (no `rowVersion` LWW guard; races rely on `X-Oke-Mutation-Id` echo dedupe), missing RLS policies warns (every gated subscriber would see every row).
+- CDC events ride the durable `oke_cdc_outbox`; delivered rows prune on retention defaults (24h / 50k) so the outbox never grows unbounded.
+- `oke doctor` findings watch the runtime side: `cdc_outbox_backlog`, `cdc_outbox_retention`, `live_subscriber_pressure` (~150 subs/table in v1), and `live_fanout_queue_saturated`.
 
 ### Handwritten HTTP lists
 
@@ -267,10 +267,6 @@ Zero-config: `?q=` searches every string field, extra keys auto-eq except path `
   shape matches `store.resource` and the typed client (`data` is the page, `meta` is the pager).
 </Callout>
 
-**Consequence:** returning `{ items, count }` from `do` nests as `{ data: { items, count }, error: null }` — the pager is no longer top-level `meta`.
-
-`fx.json.with({ data, meta })` stays for a page you already built. A third argument locks the surface or switches to keyset (`mode: "cursor"`, `cursor: ["createdAt", "id"]`).
-
 ### Querying by hand
 
 When the list is not conventional CRUD, `fx.store(db)` is the full single-table session:
@@ -291,8 +287,7 @@ await fx.store(db).update(notes).set({ title: input.title }).where(eq(notes.id,
 await fx.store(db).delete(notes).where(lt(notes.createdAt, cutoff));
 ```
 
-`select().from(notes)` infers the declared row (`string` / `number` / `null` from
-`field.*`). A `select({ title: notes.title })` projection stays untyped.
+`select().from(notes)` infers the declared row (`string` / `number` / `null` from `field.*`). A `select({ title: notes.title })` projection stays untyped.
 
 <Callout title="One table per call — no relational with:">
   `fx.store` is deliberately **single-table**: Drizzle's relational `findMany({ with: … })` is not
@@ -304,46 +299,37 @@ await fx.store(db).delete(notes).where(lt(notes.createdAt, cutoff));
 
 The recommended path: declare tables ORM-agnostically, then let `oke db` emit real Drizzle (`pgTable` for Postgres / PGLite) into `src/db/schema.drizzle.ts`.
 
-| Field API                                     | Meaning                                                                           |
-| --------------------------------------------- | --------------------------------------------------------------------------------- |
-| `field.text()` / `field.integer()`            | v1 column primitives                                                              |
-| `.primaryKey()` · `.notNull()` · `.unique()`  | constraints                                                                       |
-| `.default(v)` · `.defaultFn(id \| now)`       | defaults                                                                          |
-| `.pii()` · `.sensitive()` · `.retain("30d")`  | privacy classification                                                            |
-| `.as("sql_name")`                             | override the automatic `camelCase → snake_case`                                   |
-| `.describe("…")`                              | human title in the Console (falls back to key)                                    |
-| `.references(() => col, { onDelete })`        | foreign key                                                                       |
-| `store.schema.rls()`                          | `pgTable.withRLS` when there are no policies                                      |
-| `store.schema.policy.gate/owner/scope/tenant` | happy-path RLS (`oke.gate()` / `oke.user()` / `oke.has_scope()` / `oke.tenant()`) |
-| `store.schema.unscoped()`                     | Shared table — required when tenancy is on and there is no tenant policy          |
-
-Third argument on `store.schema.table` is Drizzle-shaped extras:
-
-```typescript
-export const bookings = store.schema.table(
-  "bookings",
-  {
-    id: field.text().primaryKey(),
-    owner: field.text().notNull(),
-  },
-  [
-    store.schema.policy.gate("member", { for: "select" }),
-    store.schema.policy.owner("owner", { for: "all" }),
-    store.schema.policy.scope("booking:create", { for: "insert" }),
-    store.schema.policy.tenant("tenant_id"),
-  ],
-);
-```
-
-Helpers emit stable names (`gate_member_select`). Raw
-`store.schema.policy("name", { as, to, for, using, withCheck })` is the
-escape hatch — predicates use `oke.*`, never `current_setting`.
-
-<Callout title="User-plane fx.store applies RLS">
-  HTTP / resource flows stamp Gate identity (`SET LOCAL ROLE oke_app` + `set_config`). Operator /
-  cron / CDC / signal stay unstamped. Tenancy on: also `oke.tenant()`; tables need `policy.tenant`
-  or `unscoped()`.
-</Callout>
+| Field API                                                    | Meaning                                                                                                                                                                                 |
+| ------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `field.text({ enum })`                                       | text; enum narrows to a literal union                                                                                                                                                   |
+| `field.id()`                                                 | id column with the default generation id (currently OK ID) minted on insert                                                                                                             |
+| `field.okid()`                                               | id column explicitly generated with OK ID                                                                                                                                               |
+| `field.varchar({ length })` · `field.char`                   | bounded strings (same enum support)                                                                                                                                                     |
+| `field.boolean()`                                            | boolean                                                                                                                                                                                 |
+| `field.smallint()` · `field.integer()`                       | ints (abstract integer emits as Drizzle `bigint`)                                                                                                                                       |
+| `field.bigint({ mode })`                                     | int8 — JS `number` (default) / `bigint` / `string`                                                                                                                                      |
+| `field.serial()` · `smallserial` · `bigserial`               | auto-increment — NOT NULL by SQL physics                                                                                                                                                |
+| `field.numeric({ precision, scale })`                        | exact decimals — infers `string`; `{ mode }` opts into `number` / `bigint`                                                                                                              |
+| `field.real()` · `doublePrecision()`                         | floats (~6 / ~15 significant digits)                                                                                                                                                    |
+| `field.json<T>()` · `jsonb<T>()`                             | JSON payloads with a generic type                                                                                                                                                       |
+| `field.uuid()`                                               | UUID strings                                                                                                                                                                            |
+| `field.time()` · `timestamp()` · `date()`                    | temporals — `Date` by default; `{ mode: "string" }` opts into ISO `string`                                                                                                              |
+| `field.interval({ fields })`                                 | time spans                                                                                                                                                                              |
+| `field.point({ mode })` · `line()`                           | geometric tuples or objects                                                                                                                                                             |
+| `field.bytea()`                                              | binary (`Buffer`)                                                                                                                                                                       |
+| `field.inet()` · `cidr` · `macaddr8`                         | network addresses as strings                                                                                                                                                            |
+| `.primaryKey()` · `.notNull()` · `.unique()`                 | constraints                                                                                                                                                                             |
+| `.default(v)` · `.defaultFn(id \| now \| nowIso \| nowDate)` | defaults — typed against the column's JS type                                                                                                                                           |
+| `.okid()` · `.now()`                                         | prepared defaults — fresh OKID / current instant. `.now()` resolves by column: epoch-ms on numbers, ISO-8601 on string-mode temporals, `Date` on default / `{ mode: "date" }` temporals |
+| `.type<T>()`                                                 | override the inferred JS type (mirrors Drizzle `$type<T>`)                                                                                                                              |
+| `.pii()` · `.sensitive()` · `.retain("30d")`                 | privacy classification                                                                                                                                                                  |
+| `.as("sql_name")`                                            | override the automatic `camelCase → snake_case`                                                                                                                                         |
+| `.describe("…")`                                             | human title in the Console (falls back to key)                                                                                                                                          |
+| `.references(() => col, { onDelete })`                       | foreign key                                                                                                                                                                             |
+| `store.schema.rls()`                                         | `pgTable.withRLS` when there are no policies                                                                                                                                            |
+| `store.schema.policy.gate/owner/scope/tenant`                | happy-path RLS (`oke.gate()` / `oke.user()` / `oke.has_scope()` / `oke.tenant()`)                                                                                                       |
+| `store.schema.unscoped()`                                    | Shared table — required when tenancy is on and there is no tenant policy                                                                                                                |
+| `store.schema.live(false)`                                   | Per-table opt-out from the project-wide `store.live` default — not live-by-default, no synthesized `/live` surface                                                                      |
 
 #### Foreign keys and relations
 
@@ -379,20 +365,12 @@ export const relations = store.schema.relations({ links, daily }, (r) => ({
 | `oke db generate` | Write versioned SQL under `drizzle/` for review                |
 | `oke db migrate`  | Apply those files — human or CI, **never** at boot             |
 
-`oke dev` auto-pushes on schema _inputs_ (`schema.decl.ts`, hand-written `schema.ts`,
-`app.ts` plugin tables, `drizzle.config.ts`) — not when emit rewrites `schema.drizzle.ts`.
-A `schema.decl.ts` error prints `schema.decl.ts has an error — …` (red ●) and keeps running.
+`oke dev` auto-pushes on schema _inputs_ (`schema.decl.ts`, hand-written `schema.ts`, `app.ts` plugin tables, `drizzle.config.ts`) — not when emit rewrites `schema.drizzle.ts`. A `schema.decl.ts` error prints `schema.decl.ts has an error — …` (red ●) and keeps running.
 
-Opt out with `--no-db-push` or `db: { autoPush: false }`. `prod` **never**
-auto-applies DDL; a missing table fails as **OKE1101** (`oke db migrate`).
+Opt out with `--no-db-push` or `db: { autoPush: false }`. `prod` **never** auto-applies DDL; a missing table fails as **OKE1101** (`oke db migrate`).
 
 #### Multiple environments
 
-`dev` can `oke db push` freely — safe to wipe and regenerate.
-
-Staging/prod accumulate versioned SQL under `drizzle/` (`oke db generate`).
-`oke db migrate` applies only unrecorded files in order — behind DBs catch up.
-
 | Environment    | Sync                                                           |
 | -------------- | -------------------------------------------------------------- |
 | `dev`          | `oke db push` (or auto-push from `oke dev`)                    |
@@ -404,19 +382,13 @@ Staging/prod accumulate versioned SQL under `drizzle/` (`oke db generate`).
   that transaction — a leaked `BEGIN` exhausts checkout.
 </Callout>
 
-**Why PgDog (not PgBouncer as the default).** Transaction pooling fixes the
-math; naive poolers can leak session state (`SET`, RLS vars, `LISTEN`/`NOTIFY`)
-across clients. PgDog re-applies those under transaction mode (PgBouncer is fine — not shipped).
+**Why PgDog (not PgBouncer as the default).** Transaction pooling fixes the math; naive poolers can leak session state (`SET`, RLS vars, `LISTEN`/`NOTIFY`) across clients. PgDog re-applies those under transaction mode (PgBouncer is fine — not shipped).
 
-**Read replicas later, zero app changes.** Add `role = "replica"` in
-`pgdog.toml` later: `BEGIN READ ONLY` → replica, failover on promotion.
-Not wired this round — readiness only.
+**Read replicas later, zero app changes.** Add `role = "replica"` in `pgdog.toml` later: `BEGIN READ ONLY` → replica, failover on promotion. Not wired this round — readiness only.
 
 #### Seeding
 
-`oke db seed` loads `defineSeed` from `src/db/seed/index.ts` — a separate
-command, never at boot. Not every project has a seed. In `oke dev`, `s` runs
-the same command. `name` is this app's seed (template or example).
+`oke db seed` loads `defineSeed` from `src/db/seed/index.ts` — a separate command, never at boot. Not every project has a seed. In `oke dev`, `s` runs the same command. `name` is this app's seed (template or example).
 
 <StoreSeeding />
 
@@ -483,39 +455,30 @@ export default defineSeed({
 | `already-existed` | match found; default leaves it alone       |
 | `changed`         | match found and `{ onExisting: "update" }` |
 
-Default upsert is **insert-if-missing**. Pass `{ onExisting: "update" }` only when this
-call should also rewrite other columns on a match — opt-in per call, never global.
+Default upsert is **insert-if-missing**. Pass `{ onExisting: "update" }` only when this call should also rewrite other columns on a match — opt-in per call, never global.
 
 ```ts
 // Safe bootstrap — second seed run leaves the row alone
-await fx.store(db).upsert(
-  notes,
-  { id: "welcome" },
-  {
-    id: "welcome",
-    title: "Welcome",
-    body: "Your Notes API is ready.",
-    createdAt: 1,
-  },
-);
+await fx
+  .store(db)
+  .upsert(
+    notes,
+    { id: "welcome" },
+    { id: "welcome", title: "Welcome", body: "Your Notes API is ready.", createdAt: 1 },
+  );
 
 // Refresh copy on every seed — match stays; title/body are rewritten
-await fx.store(db).upsert(
-  notes,
-  { id: "welcome" },
-  {
-    id: "welcome",
-    title: "Welcome (updated)",
-    body: "New bootstrap copy.",
-    createdAt: 1,
-  },
-  { onExisting: "update" },
-);
+await fx
+  .store(db)
+  .upsert(
+    notes,
+    { id: "welcome" },
+    { id: "welcome", title: "Welcome (updated)", body: "New bootstrap copy.", createdAt: 1 },
+    { onExisting: "update" },
+  );
 ```
 
-**Consequence:** default keeps operator edits safe across re-seeds; `onExisting: "update"`
-is for seed-owned rows you intentionally overwrite. Schema-wide data fixes still belong in
-migrations, not seed.
+Default keeps operator edits safe across re-seeds; `onExisting: "update"` is for seed-owned rows you intentionally overwrite. Schema-wide data fixes still belong in migrations, not seed.
 
 | Env            | Confirm                                               |
 | -------------- | ----------------------------------------------------- |
@@ -540,6 +503,34 @@ oke db seed --env prod --force
   extending an app-owned table with plugin columns is not supported in v1.
 </Callout>
 
+### Access policies — owner, tenant, scope
+
+Row-level security is declared per table as the third argument to `store.schema.table` — the policy list is Drizzle-shaped extras:
+
+```typescript
+export const bookings = store.schema.table(
+  "bookings",
+  {
+    id: field.text().primaryKey(),
+    owner: field.text().notNull(),
+  },
+  [
+    store.schema.policy.gate("member", { for: "select" }),
+    store.schema.policy.owner("owner", { for: "all" }),
+    store.schema.policy.scope("booking:create", { for: "insert" }),
+    store.schema.policy.tenant("tenant_id"),
+  ],
+);
+```
+
+Helpers emit stable names (`gate_member_select`). Raw `store.schema.policy("name", { as, to, for, using, withCheck })` is the escape hatch — predicates use `oke.*`, never `current_setting`. `policy.scope` takes a scope name or the `gate.scope("…")` declaration, so you can reuse the same scope in both the gate and the policy instead of repeating the string.
+
+<Callout title="User-plane fx.store applies RLS">
+  HTTP / resource flows stamp Gate identity (`SET LOCAL ROLE oke_app` + `set_config`). Operator /
+  cron / CDC / signal stay unstamped. Tenancy on: also `oke.tenant()`; tables need `policy.tenant`
+  or `unscoped()`.
+</Callout>
+
 ### Per-environment SQL drivers
 
 Same flow code, different backends — configured once in `oke.config.ts`:
@@ -568,14 +559,11 @@ SQL-backed index driver `pgvector` shares this facet's connection — see [Advan
 
 <StoreFacetMark facet="kv" />
 
-The key-value facet: short-lived cache and session data behind `fx.store`. One namespace per
-declaration; drivers swap `memory` ↔ `redis` per environment.
+The key-value facet: short-lived cache and session data behind `fx.store`. One namespace per declaration; drivers swap `memory` ↔ `redis` per environment.
 
-The Console KV band opens a query console for `list`, `get`, `set`, `delete`, and `ttl`.
-Prettify rewrites commands to call form and indents `set` JSON.
+The Console KV band opens a query console for `list`, `get`, `set`, `delete`, and `ttl`. Prettify rewrites commands to call form and indents `set` JSON.
 
-The same band’s **Performance** control opens engine telemetry on the `redis`
-driver. In-process `memory` is unsupported (`KvStatsUnsupported`).
+The same band's **Performance** control opens engine telemetry on the `redis` driver. In-process `memory` is unsupported (`KvStatsUnsupported`).
 
 ### Quick start
 
@@ -620,68 +608,17 @@ do: async ({ userId, data }, fx) => {
 
 ### TTL
 
-Optional third argument on `set` is a duration string: `(\d+)(ms|s|m|h|d)` — e.g. `"30m"`, `"1h"`,
-`"5000ms"`. Same call — opposite physics under each driver. Console KV browse edits that TTL
-(empty clears expiry) and can add a key through the same `set` path.
+Optional third argument on `set` is a duration string: `(\d+)(ms|s|m|h|d)` — e.g. `"30m"`, `"1h"`, `"5000ms"`. Same call — opposite physics under each driver. Console KV browse edits that TTL (empty clears expiry) and can add a key through the same `set` path.
 
 <StoreKvTtl />
 
-**Consequence:** a TTL you rely on in prod does nothing under the `test` `memory` driver. Exercise
-expiry against `redis` under `oke dev` when lifetime matters.
-
-### Examples — what follows from each choice
-
-#### A session with expiry
-
-```typescript
-await fx.store(sessions).set(`sess:${token}`, { userId }, "7d");
-```
-
-**Consequence:** under `redis`, the key vanishes after seven days without a sweeper Flow. Under
-`memory`, it lives until process exit or an explicit `delete`.
-
-#### Browse by prefix
-
-```typescript
-const keys = await fx.store(sessions).list("sess:");
-```
-
-**Consequence:** `list` enumerates a namespace. Prefer stable key prefixes (`user:`, `sess:`) so
-your Flows and operator tools stay readable.
-
-### Per-environment KV drivers
-
-```typescript title="oke.config.ts"
-drivers: {
-  store: {
-    kv: { dev: "redis", test: "memory", prod: "redis" },
-  },
-},
-images: {
-  store: { kv: "redis:8-alpine" },
-  // or: "valkey/valkey:8-alpine"
-  // or: "docker.dragonflydb.io/dragonflydb/dragonfly"
-},
-```
-
-| Facet | `dev` / `prod` | `test`   | Runs as                |
-| ----- | -------------- | -------- | ---------------------- |
-| `kv`  | `redis`        | `memory` | container → in-process |
-
-| Variable           | When                             |
-| ------------------ | -------------------------------- |
-| `REDIS_URL`        | Required for the `redis` driver  |
-| `OKE_STORE_KV_URL` | Override if `REDIS_URL` is unset |
-| `OKE_KV_DRIVER`    | Force a driver id                |
-
-Missing Redis URL fails boot loudly: `oke boot: redis driver needs REDIS_URL`.
+**Consequence:** a TTL you rely on in prod does nothing under the `test` `memory` driver. Exercise expiry against `redis` under `oke dev` when lifetime matters.
 
 ### Durable KV
 
 Default `store.kv("sessions")` is cache-shaped — a Redis recreate drops keys.
 
-`{ durable: true }` persists that namespace in your SQL database (`oke_kv` JSONB on
-`DATABASE_URL`). Not a per-key Redis flag, not Flow `durable`, not tier-1 auto-cache.
+`{ durable: true }` persists that namespace in your SQL database (`oke_kv` JSONB on `DATABASE_URL`). Not a per-key Redis flag, not Flow `durable`, not tier-1 auto-cache.
 
 ```typescript
 export const sessions = store.kv("sessions", { description: "Session cache" });
@@ -689,24 +626,18 @@ export const ledger = store.kv("ledger", { durable: true, description: "Idempote
 export const drafts = store.kv("drafts", { durable: true, description: "Compose drafts" });
 ```
 
-**Consequence:** `oke db seed` into cache Redis looks fine until compose recreates the
-container — Console Store then shows **No rows.** Seeded namespaces need `{ durable: true }`.
+**Consequence:** `oke db seed` into cache Redis looks fine until compose recreates the container — Console Store then shows **No rows.** Seeded namespaces need `{ durable: true }`.
 
-With `gate.auth.tenant` on, KV keys are prefixed `{tenantId}:` (logical keys in `do` stay
-unprefixed). Missing `fx.tenant.id` throws **OKE1015**. Opt out with
-`store.kv("sessions", { tenantScoped: false })`.
+With `gate.auth.tenant` on, KV keys are prefixed `{tenantId}:` (logical keys in `do` stay unprefixed). Missing `fx.tenant.id` throws **OKE1015**. Opt out with `store.kv("sessions", { tenantScoped: false })`.
 
-Gate rates and Signal stay on `REDIS_URL`. Missing `DATABASE_URL` with the postgres driver
-fails boot: `oke boot: durable store.kv needs DATABASE_URL`.
+Gate rates and Signal stay on `REDIS_URL`. Missing `DATABASE_URL` with the postgres driver fails boot: `oke boot: durable store.kv needs DATABASE_URL`.
 
 <Callout title="Not per-key, not Flow durable, not auto-cache">
   Durable KV is a JSONB table on the same Postgres as `store.sql`. Flow `durable` journals steps.
   Tier-1 auto-cache is an in-process Map and never reads `store.kv`.
 </Callout>
 
-Driver id stays `redis` for every image below — same `REDIS_URL`, zero Flow changes.
-Redis is the default because it is the most mature and battle-tested; Valkey and
-Dragonfly are equally legitimate opt-in pins.
+Driver id stays `redis` for every image below — same `REDIS_URL`, zero Flow changes. Redis is the default because it is the most mature and battle-tested; Valkey and Dragonfly are equally legitimate opt-in pins.
 
 | Image         | Pin                                           | Why pick it                       | License                                                                                                                                           |
 | ------------- | --------------------------------------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -717,7 +648,7 @@ Dragonfly are equally legitimate opt-in pins.
 <Callout title="Licenses bite managed-service resellers — read this once" type="warn">
   RSAL, SSPL, and BSL service restrictions apply when you offer that specific datastore **as a
   service** to third parties — not when you run it for your own app. Pick for your situation; OKE
-  does not pick a “safer” default for you.
+  does not pick a "safer" default for you.
 </Callout>
 
 <Callout title="Dry-run refuses KV writes">
@@ -725,13 +656,38 @@ Dragonfly are equally legitimate opt-in pins.
   double-write against a shared Redis. Reads (`get` / `list`) still run.
 </Callout>
 
+### Per-environment KV drivers
+
+```typescript title="oke.config.ts"
+drivers: {
+  store: {
+    kv: { dev: "redis", test: "memory", prod: "redis" },
+  },
+},
+images: {
+  store: { kv: "redis:8-alpine" },
+  // or: "valkey/valkey:8-alpine"
+  // or: "docker.dragonflydb.io/dragonflydb/dragonfly"
+},
+```
+
+| Facet | `dev` / `prod` | `test`   | Runs as                |
+| ----- | -------------- | -------- | ---------------------- |
+| `kv`  | `redis`        | `memory` | container → in-process |
+
+| Variable           | When                             |
+| ------------------ | -------------------------------- |
+| `REDIS_URL`        | Required for the `redis` driver  |
+| `OKE_STORE_KV_URL` | Override if `REDIS_URL` is unset |
+| `OKE_KV_DRIVER`    | Force a driver id                |
+
+Missing Redis URL fails boot loudly: `oke boot: redis driver needs REDIS_URL`.
+
 ## Files
 
 <StoreFacetMark facet="files" />
 
-The blob facet: opaque objects (`Uint8Array` or string) on the same handle as the optional image
-pipeline. Drivers swap `fs` ↔ `s3` (plus `memory` for tests). The Console Files band is a folder
-browser — upload, download, delete — not a signed-URL mint.
+The blob facet: opaque objects (`Uint8Array` or string) on the same handle as the optional image pipeline. Drivers swap `fs` ↔ `s3` (plus `memory` for tests). The Console Files band is a folder browser — upload, download, delete — not a signed-URL mint.
 
 ### Quick start
 
@@ -829,8 +785,7 @@ images: {
 
 ### Images — `image` / `putImage`
 
-For photos, use Bun's built-in `Bun.Image` pipeline on the same handle (requires Bun `>=1.4.0`).
-`putImage` is one write that fans into several keys:
+For photos, use Bun's built-in `Bun.Image` pipeline on the same handle (requires Bun `>=1.4.0`). `putImage` is one write that fans into several keys:
 
 <StoreFilesVariants />
 
@@ -876,8 +831,7 @@ const result = await fx.store(uploads).putImage("photos/x.jpg", bytes, {
 
 <StoreFacetMark facet="index" />
 
-The search / similarity facet: vector ANN and opt-in full-text, both behind `store.index`. The
-handle is a **discriminated union** on `driverId` — vector methods and text methods never mix.
+The search / similarity facet: vector ANN and opt-in full-text, both behind `store.index`. The handle is a **discriminated union** on `driverId` — vector methods and text methods never mix.
 
 ### Quick start
 
@@ -934,8 +888,7 @@ One declaration shape — two search physics. The handle is a **discriminated un
   probe. Meilisearch uses full-text `q`.
 </Callout>
 
-TypeScript rejects a vector query against a text index (and vice versa) at compile time — never at
-runtime.
+TypeScript rejects a vector query against a text index (and vice versa) at compile time — never at runtime.
 
 ### Vector ANN
 
@@ -944,16 +897,13 @@ runtime.
 | `memory`         | — (in-process, default)    | Full scan cosine        |
 | `pgvector`       | `postgres` or `pglite` sql | HNSW + `cosineDistance` |
 
-**Consequence:** a configured SQL-backed index that cannot reach its engine — missing peer, missing
-`vector` extension, wrong sql driver — fails loudly at first use. It never silently falls back to
-`memory`. A vector whose length ≠ `dims` throws `vector dims X !== index dims Y`.
+**Consequence:** a configured SQL-backed index that cannot reach its engine — missing peer, missing `vector` extension, wrong sql driver — fails loudly at first use. It never silently falls back to `memory`. A vector whose length ≠ `dims` throws `vector dims X !== index dims Y`.
 
 Pair SQL + index under [Advanced — composing facets together](#advanced--composing-facets-together).
 
 ### Full-text search — `meilisearch` (opt-in)
 
-`meilisearch` is a fourth `store.index` backend, opt-in only — `memory` stays the default when
-`drivers.store.index` is unset. Typo-tolerant, faceted full-text relevance — not cosine similarity.
+`meilisearch` is a fourth `store.index` backend, opt-in only — `memory` stays the default when `drivers.store.index` is unset. Typo-tolerant, faceted full-text relevance — not cosine similarity.
 
 ```typescript
 export const kb = store.index("kb", { description: "Help articles" });
@@ -1012,9 +962,7 @@ drivers: {
 
 ### With AI embeddings
 
-`ai.embed` writes into a vector `store.index`; Flows search it with `fx.search` (or
-`fx.store(index).search`). See [AI](/docs/elements/ai) — this path is vector-only and will not
-target meilisearch.
+`ai.embed` writes into a vector `store.index`; Flows search it with `fx.search` (or `fx.store(index).search`). See [AI](/docs/elements/ai) — this path is vector-only and will not target meilisearch.
 
 ## Advanced — composing facets together
 
@@ -1049,84 +997,82 @@ Container images come from the `images` map — change the vendor by changing th
 
 Columns tagged `.pii()` or `.sensitive()` are masked at the store boundary — flows, logs, and the Console see a mask, not the value. Revealing cleartext PII requires an explicit `pii:reveal` gate on the flow, so access is a permission, not a convention.
 
-Optional `description` on a store (and `.describe("…")` on fields) becomes its human title in
-operator tools. Single-table `reads` / `writes` in the Manifest power cache invalidation and that
-same PII masking — see the Callout under [Querying by hand](#querying-by-hand).
+Optional `description` on a store (and `.describe("…")` on fields) becomes its human title in operator tools. Single-table `reads` / `writes` in the Manifest power cache invalidation and that same PII masking — see the Callout under [Querying by hand](#querying-by-hand).
 
 ## Troubleshooting
 
 <Accordions>
-<Accordion title="Unable to resolve table name from value">
-
-A `store.schema.table` column named `name` used to shadow the SQL table name.
-Inserts and selects now resolve it from the declaration. Keep the `name` column.
 
+<Accordion title="Unable to resolve table name from value">
+  A `store.schema.table` column named `name` used to shadow the SQL table name. Inserts and selects
+  now resolve it from the declaration. Keep the `name` column.
 </Accordion>
-<Accordion title="OKE1101 — missing table in prod">
-
-Schema DDL never runs automatically in `prod`. Under `oke dev`, `db.autoPush` (default `true`) runs `oke db push`. For production use `oke db generate` + `oke db migrate`.
 
+<Accordion title="OKE1101 — missing table in prod">
+  Schema DDL never runs automatically in `prod`. Under `oke dev`, `db.autoPush` (default `true`)
+  runs `oke db push`. For production use `oke db generate` + `oke db migrate`.
 </Accordion>
-<Accordion title="oke db push: missing_hints">
-
-New tables are created automatically. Push only manages `public` — it will not drop schema `oke` (RLS helpers) or `oke_console`. Remaining `missing_hints` are destructive (drop a non-empty public table, type change). Review with `oke db generate`.
 
+<Accordion title="oke db push: missing_hints">
+  New tables are created automatically. Push only manages `public` — it will not drop schema `oke`
+  (RLS helpers) or `oke_console`. Remaining `missing_hints` are destructive (drop a non-empty public
+  table, type change). Review with `oke db generate`.
 </Accordion>
-<Accordion title="I need a join — with: is not supported">
-
-`fx.store` is one table per call by design. Read each table separately and compose in the flow (or extract a shared flow and `fx.call` it). Every table then appears explicitly in the Manifest's effect graph — which is what powers cache invalidation and PII masking.
 
+<Accordion title="I need a join — with: is not supported">
+  `fx.store` is one table per call by design. Read each table separately and compose in the flow (or
+  extract a shared flow and `fx.call` it). Every table then appears explicitly in the Manifest's
+  effect graph — which is what powers cache invalidation and PII masking.
 </Accordion>
-<Accordion title="Pagination shows duplicates when rows are inserted">
-
-You are on offset paging. Switch `list` to keyset by setting `cursor` columns with a stable order (e.g. `[createdAt, id]`) — the page boundary becomes a row predicate, not a row count.
 
+<Accordion title="Pagination shows duplicates when rows are inserted">
+  You are on offset paging. Switch `list` to keyset by setting `cursor` columns with a stable order
+  (e.g. `[createdAt, id]`) — the page boundary becomes a row predicate, not a row count.
 </Accordion>
-<Accordion title="meta.total is slow on a big table">
-
-`count: "exact"` runs `COUNT(*)` per page. Set `count: "none"` in the `list` options to skip it, or use keyset mode where totals are rarely needed.
 
+<Accordion title="meta.total is slow on a big table">
+  `count: "exact"` runs `COUNT(*)` per page. Set `count: "none"` in the `list` options to skip it,
+  or use keyset mode where totals are rarely needed.
 </Accordion>
-<Accordion title="List data is { items, count } instead of an array">
 
+<Accordion title="List data is { items, count } instead of an array">
 Success already wraps `{ data, error: null }`. Returning a page object from `do` nests the pager inside `data`. Prefer `out: z.array(Item)` and `return fx.json.withQuery(rows, input)`. Any other declared `out` is still valid.
-
 </Accordion>
-<Accordion title="KV TTL never expires in tests">
-
-The `test` default is `memory`, which ignores TTL on `set`. Under `oke dev`, KV is `redis` by default — use that when you need real expiry.
 
+<Accordion title="KV TTL never expires in tests">
+  The `test` default is `memory`, which ignores TTL on `set`. Under `oke dev`, KV is `redis` by
+  default — use that when you need real expiry.
 </Accordion>
-<Accordion title="oke boot: redis / meilisearch / S3 URL missing">
-
-Driver-backed facets fail boot when their URL is absent — Redis needs `REDIS_URL`, meilisearch needs `OKE_STORE_INDEX_URL`, S3 needs `S3_BUCKET`. `oke dev` writes these into the Compose env.
 
+<Accordion title="oke boot: redis / meilisearch / S3 URL missing">
+  Driver-backed facets fail boot when their URL is absent — Redis needs `REDIS_URL`, meilisearch
+  needs `OKE_STORE_INDEX_URL`, S3 needs `S3_BUCKET`. `oke dev` writes these into the Compose env.
 </Accordion>
-<Accordion title="vector dims X !== index dims Y">
-
-The vector length must match `store.index(…, { dims })` (runtime default `3` if unset). Align `dims` with your embedder, or fix the vector you pass to `upsert` / `search`.
 
+<Accordion title="vector dims X !== index dims Y">
+  The vector length must match `store.index(…, {dims})` (runtime default `3` if unset). Align `dims`
+  with your embedder, or fix the vector you pass to `upsert` / `search`.
 </Accordion>
-<Accordion title="Index stays on memory under oke dev">
-
-Unlike KV/Files, unset `drivers.store.index` does **not** promote to `pgvector` in `dev` — it stays `memory`. Set the map explicitly (and pair SQL for `pgvector`).
 
+<Accordion title="Index stays on memory under oke dev">
+  Unlike KV/Files, unset `drivers.store.index` does **not** promote to `pgvector` in `dev` — it
+  stays `memory`. Set the map explicitly (and pair SQL for `pgvector`).
 </Accordion>
-<Accordion title="Console warns Non-ASCII object key">
-
-`fx.store(files).put` stores the key as-is. Console uploads mint an ASCII key and keep the original name in `.oke/catalog.json`. Re-upload to rewrite an existing object.
 
+<Accordion title="Console warns Non-ASCII object key">
+  `fx.store(files).put` stores the key as-is. Console uploads mint an ASCII key and keep the
+  original name in `.oke/catalog.json`. Re-upload to rewrite an existing object.
 </Accordion>
-<Accordion title="oke dev skipped the seed prompt">
-
-`.oke/state.json` stores `seededAt` plus this app's `defineSeed({ name })` — notes vs keel are different ids. A new name re-asks. Clear those keys to prompt again.
 
+<Accordion title="oke dev skipped the seed prompt">
+  `.oke/state.json` stores `seededAt` plus this app's `defineSeed({name})` — notes vs keel are
+  different ids. A new name re-asks. Clear those keys to prompt again.
 </Accordion>
-<Accordion title="Console KV shows No rows after oke db seed">
 
+<Accordion title="Console KV shows No rows after oke db seed">
 Default `store.kv` is cache Redis with no AOF — a recreate drops keys. SQL seed still looks full. Mark seeded namespaces `{ durable: true }` so they live in `oke_kv`, then restart and seed again.
-
 </Accordion>
+
 </Accordions>
 
 ## Learn more