okengine 0.15.2 → 0.17.0

package/manifest.v1.schema.json

@@ -298,7 +298,10 @@
           "enum": ["user", "operator"]
         },
         "durable": { "type": "boolean" },
-        "live": { "type": "boolean" },
+        "live": {
+          "type": "string",
+          "description": "Live signal name when this flow streams delivery: live SSE."
+        },
         "cache": {
           "oneOf": [{ "type": "boolean" }, { "type": "string", "minLength": 1 }]
         },
@@ -342,7 +345,23 @@
         "retries": { "type": "integer", "minimum": 0 },
         "deadLetter": { "type": "boolean" },
         "schema": { "$ref": "#/$defs/JsonSchema" },
-        "optional": { "type": "boolean" }
+        "optional": { "type": "boolean" },
+        "retention": {
+          "description": "Live-tape cap (delivery: live only). Omitted = unbounded.",
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "maxAge": {
+              "type": "string",
+              "description": "Drop events older than this duration (7d, 1h, 30s, …)."
+            },
+            "maxCount": {
+              "type": "integer",
+              "minimum": 1,
+              "description": "Keep only the newest N live events."
+            }
+          }
+        }
       }
     },
     "ColumnClassification": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okengine",
-  "version": "0.15.2",
+  "version": "0.17.0",
   "description": "One law. Eight elements. Ten exports. One package. One manifest. Every backend need is derived, never added.",
   "license": "MIT",
   "repository": {

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

@@ -102,6 +102,12 @@ difference.
 | `timezone`    | string  | `"UTC"` | IANA timezone for cron evaluation                                                                                        |
 | `overridable` | boolean | `false` | Allow the Console to **edit** the schedule (pause is separate)                                                           |
 | `description` | string  | —       | Human title in the Console (falls back to the clock name)                                                                |
+| `perTenant`   | boolean | `false` | Expand to one `oke_crons` row per tenant (`{name}#{tenantId}`). Prefer `clock.perTenant(name, opts)`                     |
+
+<Callout title="Per-tenant clocks never tick the template">
+  Bind `on(clock.perTenant("invoices", { every: "1h" }), flow(...))`. Rows are `invoices#acme`;
+  tenant create/delete adds or orphans them. Fire stamps `fx.tenant.id`.
+</Callout>
 
 ### `fx.clock`
 
@@ -222,6 +228,7 @@ The registry is off in `test` and when there is no shared SQL URL. `dev`/`prod`
 
 - [Project structure](/docs/get-started/project-structure) — clock flows in the tree get a name, never a URL
 - [Flow](/docs/elements/flow) — `on(trigger, flow)` and the `fx` surface
+- [Gate](/docs/elements/gate) — `clock.perTenant` when `gate.auth.tenant` is on
 - [fx · Runs](/docs/reference/fx#runs-observability-read) — native SLO checkers via `on(every(…))` + `fx.runs`
 - [Signal](/docs/elements/signal) — reacting to events instead of time
 

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

@@ -71,16 +71,17 @@ curl -X POST localhost:6530/orders -d '{"sku":"SKU-1","qty":2}' -H 'content-type
 
 ## Anatomy of a Flow
 
-| Part         | Role                                                                              |
-| ------------ | --------------------------------------------------------------------------------- |
-| trigger      | What starts the flow — `http`, a signal, `every`, a row change                    |
-| `in`         | Input contract — validated before `do` runs; bad input is a 422                   |
-| `out`        | Output contract — the return value is checked against it                          |
-| `errors`     | Typed failures — **returned** with `fx.fail`, never thrown                        |
-| `retry`      | Optional whole-`do` backoff on thrown errors (same journal)                       |
-| `cache`      | Optional — `false` opts out; `"30s"` adds a TTL. Read-only flows cache by default |
-| `do`         | The work — every read, write, emit, and call goes through `fx`                    |
-| `compensate` | Durable only — optional hook after auto per-step `{ undo }` (same journal)        |
+| Part           | Role                                                                                 |
+| -------------- | ------------------------------------------------------------------------------------ |
+| trigger        | What starts the flow — `http`, a signal, `every`, a row change                       |
+| `in`           | Input contract — validated before `do` runs; bad input is a 422                      |
+| `out`          | Output contract — the return value is checked against it                             |
+| `errors`       | Typed failures — **returned** with `fx.fail`, never thrown                           |
+| `retry`        | Optional whole-`do` backoff on thrown errors (same journal)                          |
+| `cache`        | Optional — `false` opts out; `"30s"` adds a TTL. Read-only flows cache by default    |
+| `tenantScoped` | Default `true` when `gate.auth.tenant` is on — set `false` to skip tenant-role union |
+| `do`           | The work — every read, write, emit, and call goes through `fx`                       |
+| `compensate`   | Durable only — optional hook after auto per-step `{ undo }` (same journal)           |
 
 Failures are values, not exceptions:
 
@@ -104,6 +105,12 @@ Built-in codes attach a localized `message` ([Errors](/docs/reference/errors));
   [Store](/docs/elements/store#handwritten-http-lists).
 </Callout>
 
+<Callout title="Helpers take the real Fx">
+  Type a helper's `fx` as the exported `Fx` (`import type { Fx } from
+  "okengine"`). A narrower `{ store: … }` will not match `store()` overloads
+  — that is the `as never` trap. See [fx](/docs/reference/fx).
+</Callout>
+
 ## The five triggers
 
 <FlowTriggers />
@@ -133,8 +140,8 @@ export const findOrder = on(
 ### signal — another flow emits
 
 The producer emits through `fx`. For `once` and `broadcast` the consumer is the same species —
-`on(signal, flow)`, no `subscribe()` registration. `live` replay is the exception: `bus.live()` on
-the server, not a Flow.
+`on(signal, flow)`, no `subscribe()` registration. `live` replay is HTTP SSE: `.live(signal)` on a
+GET trigger, `fx.live` as the stream carrier, `api.live` on the client.
 
 ```typescript
 await fx.emit(orderPlaced, { orderId: id }); // inside the producing flow
@@ -203,6 +210,7 @@ Everything a flow may touch, on one object:
 | `fx.store(db).select/insert/…`              | read / write    | SQL, KV, files, index sessions                     |
 | `fx.emit(signal, payload)`                  | emit            | Publish a signal (transactional with writes)       |
 | `fx.deadLetters(signal)`                    | read            | Dead-lettered messages for that signal             |
+| `fx.live(signal, { match? })`               | read            | Live signal SSE carrier (`JsonStreamResult`)       |
 | `fx.send(template, opts)`                   | send            | Reach a human (email · SMS · …)                    |
 | `fx.ask(prompt, input)`                     | ask             | Call a versioned AI prompt                         |
 | `fx.run(agent, input)`                      | ask             | Run a bounded agent                                |

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

@@ -236,6 +236,7 @@ export const app = oke({
 | `session.singleSessionPerUser`              | `false`   | Opt-in: issuing a session revokes other families for that user                                                             |
 | `cookies.enabled`                           | `false`   | Opt-in HttpOnly cookie mirror (Bearer stays default)                                                                       |
 | `secondaryStorage.enabled`                  | `false`   | Hot auth data in `store.kv` when configured                                                                                |
+| `tenant`                                    | unset     | Opt-in identity dimension — `true` or `{ required, source, header, resolve, authoritative }`                               |
 | `user` / `session` / …                      | defaults  | `modelName` / `fields` / `additionalFields`                                                                                |
 
 HIBP via `createHibpBreachCheck` from `okengine/auth` (k-anonymity range API; requires
@@ -256,6 +257,83 @@ Customize tables, then `oke schema generate` (`.oke/schema/oke.ts`; `--check` in
 sign-in shapes: [Plugins](/docs/plugins). Call auth from
 [createClient](/docs/reference/client) — helpers in `okengine/client/auth`.
 
+## Tenants (identity dimension)
+
+`gate.auth.tenant: true` (or an options bag) is **not** a second authorization system and not an
+organizations product. Tenant is a dimension of identity, like `fx.auth` / `fx.operator`.
+
+```typescript
+export const app = oke({
+  name: "shop",
+  gate: { auth: { tenant: true } },
+});
+```
+
+| Option          | Default        | Meaning                                                                                          |
+| --------------- | -------------- | ------------------------------------------------------------------------------------------------ |
+| `required`      | `false`        | Pure B2B: authenticated user-plane requests without a tenant are `Forbidden` / `tenant_required` |
+| `source`        | `"claim"`      | `"claim"` · `"header"` · `"subdomain"` · `"resolve"`                                             |
+| `header`        | `x-oke-tenant` | Header name when `source` is `"header"`                                                          |
+| `resolve`       | unset          | Callback that returns an id; membership is still checked unless `authoritative`                  |
+| `authoritative` | `false`        | Trust `resolve` without a membership query                                                       |
+
+Three tiers, fail-safe:
+
+1. **Claim** — signed JWT `tid` or API-key `tenantId`. The id is trusted; no membership query.
+2. **Header / subdomain** — never trust a client-supplied id without membership.
+3. **`resolve`** — still membership-checked unless `authoritative: true`.
+
+`required: false` (default) is B2C+B2B: `fx.tenant.id` may be `null`. Internal / cron / `fx.call`
+have no HTTP request — header and subdomain sources keep the stamped claim.
+
+`fx.auth.switchTenant(id)` issues a **new** access+refresh pair and a **new** family (so tab A
+rotation cannot reuse-detect tab B). It never Set-Cookies.
+
+Refresh copies that row's `tid`; tenant-role scopes never melt into the JWT.
+
+`fx.auth.listTenants` / `createTenant` / `addMember` / `upsertTenantRole` are session-only
+(`auth:tenants`). Tenant roles may grant application scopes only — `console:*` fails like an
+unknown name.
+
+Live `fx.auth.scopes` unions those grants only when `fx.tenant.id` is set, the flow is
+tenant-scoped (default on; `flow({ tenantScoped: false })` opts out), and user-plane.
+`gate.scope()` still reads `auth.scopes.has(name)`.
+
+SQL stamps `oke.tenant()` when tenancy is on — [Store](/docs/elements/store) and
+built-in [Vault](/docs/elements/vault#tenant-isolation-built-in-store) ciphertext.
+
+## API keys
+
+A key is the **issuer with fewer gates** — not a second permission system.
+Bearer secrets authenticate as the creator; `fx.auth.scopes` shrink to the key.
+
+| Field                               | Session        | API key                 |
+| ----------------------------------- | -------------- | ----------------------- |
+| `fx.auth.userId` / `fx.operator.id` | subject        | creator (`creatorId`)   |
+| `fx.auth.scopes`                    | session scopes | key scopes (attenuated) |
+| `fx.auth.apiKeyId`                  | `null`         | key id                  |
+| WideEvent `principal`               | subject        | issuer                  |
+| `dimensions.api_key`                | absent         | key id                  |
+
+`gate.auth` always creates a shared key store (HMAC-SHA-256 with `gate.auth.secret`).
+Do not pass `apiKeyStore` unless you are injecting a test Map.
+
+<Callout title="Keys live on the app database">
+  With `store.sql()`, boot hydrates public `oke_api_keys` on that connection (`DATABASE_URL`) and
+  write-through persists create / rotate / revoke. Console **Access** attaches this host store — it
+  does not keep a second key database.
+</Callout>
+
+Session Flows manage keys via [fx](/docs/reference/fx) (`createApiKey`, `listApiKeys`,
+`revokeApiKey`, `rotateApiKey`, `updateApiKey`). A key-authenticated caller cannot.
+
+Declare `effects.reads: ["auth:api-keys"]` / `effects.writes: ["auth:api-keys"]` — never
+`sql:oke_api_keys`. Console **Access** (`:6533` → `/access`) mints operator keys as the
+operator, and user-plane keys only as a picked issuer (`creatorUserId`).
+
+Verify rejects expired, revoked, allowlist-miss, and over-rate secrets with `401`
+and no `api_key` dimension.
+
 ## Identity and decisions
 
 Gates decide on principals that already exist. `gate.auth` issues hybrid sessions onto
@@ -268,8 +346,8 @@ edit live today.
 
 <Callout title="RLS reads the stamped principal">
   After HTTP Gate passes, user-plane `fx.store` stamps `oke.gate()`, `oke.user()`, and
-  `oke.has_scope()`. Rate, cron, CDC, and signal stay unstamped. Helpers:
-  [Store](/docs/elements/store).
+  `oke.has_scope()`. With `gate.auth.tenant` on, a fourth GUC `oke.tenant()` is set. Rate, cron,
+  CDC, and signal stay unstamped. Helpers: [Store](/docs/elements/store).
 </Callout>
 
 ## Troubleshooting
@@ -292,6 +370,12 @@ decisions belong inside `do` as typed `errors`.
 `Forbidden` means authenticated but a policy said no. Check `verified` or a missing scope —
 the failure includes the gate name and reason.
 
+</Accordion>
+<Accordion title="Forbidden tenant_required / not_member">
+
+`required: true` and no resolved tenant → `tenant_required`. Header/subdomain id that is not a
+membership → `not_member`. Call `fx.auth.switchTenant(id)` or send a signed `tid`.
+
 </Accordion>
 <Accordion title="Prod boot: gate.auth: secret is required">
 
@@ -310,6 +394,27 @@ character classes.
 `"ip"` for public surfaces (sign-up, password reset), `"user"` for authenticated quotas.
 Keying an authenticated endpoint by IP punishes shared NAT.
 
+</Accordion>
+<Accordion title="API key Bearer returns 401">
+
+Expired, revoked, allowlist miss, or over `rateLimit`. `ipAllowlist` uses the
+same X-Forwarded-For hop as `ip-allowlist` (IP or hostname; lookup failure is closed).
+Rotate if the secret was shown once and then lost.
+
+</Accordion>
+<Accordion title="Keys vanish after an app restart">
+
+No SQL store, or a new `gate.auth.secret`. Declare `store.sql()`, keep
+`DATABASE_URL` (or the same PGlite datadir) and the auth secret stable.
+Console does not persist keys in `oke_console`.
+
+</Accordion>
+<Accordion title="Key can call a route the issuer cannot">
+
+That is a bug in the mint. `createApiKey` / `fx.auth.createApiKey` re-run
+`assertAttenuated` against the issuer's live scopes. Custom `gate.policy`
+predicates that ignore scopes still see `verified: true`.
+
 </Accordion>
 </Accordions>
 
@@ -317,7 +422,7 @@ Keying an authenticated endpoint by IP punishes shared NAT.
 
 - [Project structure](/docs/get-started/project-structure) — `http.get()` and `flow({…})` fill path and name from the file tree
 - [Flow](/docs/elements/flow) — the trigger pipeline gates plug into
-- [fx](/docs/reference/fx) — `fx.auth`, `fx.operator`, `fx.principal`
+- [fx](/docs/reference/fx) — `fx.auth`, `fx.operator`, `fx.principal`, `fx.tenant`
 - [Client](/docs/reference/client) — Bearer `createClient` + `okengine/client/auth`
 - [Plugins](/docs/plugins) — username, magic link, OTP, TOTP, passkeys
 - [Vault](/docs/elements/vault) — credentials your policies protect

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

@@ -72,7 +72,7 @@ export const sendConfirmation = on(
 </Steps>
 
 That's the loop for `once` and `broadcast`: declare → `fx.emit` → `on(signal, flow)`.
-`live` keeps the same emit; the listener is `bus.live()`, not a Flow.
+`live` keeps the same emit; expose it over HTTP with `.live(signal)` and subscribe from `api.live`.
 
 ## The three delivery physics
 
@@ -90,6 +90,7 @@ The declaration is identical in shape for all three — switching physics later
 | `retries`     | number                            | `3`              | Retry budget for `once` — dead-letter when `attempts > retries` (`retries + 1` total invocations) |
 | `deadLetter`  | boolean                           | `true`           | Preserve exhausted messages in the DLQ (`once`)                                                   |
 | `optional`    | boolean                           | `false`          | Allow emitting while nobody subscribes (skip the orphan check)                                    |
+| `retention`   | `{ maxAge?, maxCount? }`          | unbounded        | Live tape cap (`delivery: "live"` only). Both limits AND-combine when set                         |
 
 ## One order, three modes
 
@@ -124,6 +125,7 @@ export const orderStatus = signal("order-status", {
   }),
   delivery: "live",
   optional: true, // clients may not be connected yet
+  retention: { maxAge: "24h", maxCount: 500 },
 });
 ```
 
@@ -182,19 +184,31 @@ export const notifyCustomer = on(
 );
 ```
 
-`live` — retain the tape. A late subscriber replays **full history** (`placed → fulfilling → shipped`), then keeps going.
+`live` — retain the tape. A late subscriber replays history (`placed → fulfilling → shipped`), then keeps going. Omit `retention` and that history is **unbounded** — declare `maxAge` / `maxCount` in production.
 
-The listener is **`bus.live()`**, not `on(orderStatus, flow)`. `on(signal, flow)` does not replay retained live payloads. Today that API is server-side; `createClient` has no SSE / WebSocket / `client.live` yet — see [Client](/docs/reference/client#signal-and-live-queries).
+The listener is **not** `on(orderStatus, flow)` — that trigger does not replay retained payloads. Expose GET SSE with `.live(signal)`, then subscribe from the typed client. `optional: true` is required so emits succeed before anyone is connected.
 
 ```typescript
-const bus = app.bootResult?.signal?.bus;
-if (!bus) throw new Error("signal runtime not booted");
+export const events = on(http.get("/orders/:orderId/events").gate(member).live(orderStatus));
 
-const unsub = await bus.live("order-status", (payload) => {
-  /* placed → fulfilling → shipped */
-});
+export const adminFeed = on(http.get("/admin/order-status").gate(admin).live(orderStatus));
+
+const stop = api.live(
+  orderStatus,
+  { orderId: "ord_1" },
+  {
+    onEvent: (event) => {
+      /* placed → fulfilling → shipped */
+    },
+  },
+);
+stop();
 ```
 
+Same signal, two audiences: member filter on `:orderId`, admin firehose. Duplicate `(signal, gates, match)` is **OKE1013**. Same HTTP path is still **OKE1011**. Firehose default: `on(http.live(orderStatus).gate(member))` → `GET /_oke/live/order-status`.
+
+Server-side `fx.live` **is** the SSE carrier (`JsonStreamResult`). Custom `do` is allowed; authors do not wrap `fx.json.stream`. Reconnects send `Last-Event-ID`; a missing cursor is **OKE1014** / HTTP 410, not a silent full replay. `autoResubscribe: true` backs off 500ms…30s and, after a 410, replays the remaining tape.
+
 **Why separate signals:** delivery is fixed per declaration. Competing work stays on `once`; fan-out stays on `broadcast`; the timeline stays on `live`. Switching a word later is cheap; mixing physics on one name is not.
 
 ## When delivery fails
@@ -252,12 +266,16 @@ Committed `once` messages survive process death. A claim sets `lockedBy` and a v
 
 <SignalLiveReplay />
 
-`live` retains every delivered message and replays the **full history** to a late `bus.live()` subscriber. There is no TTL or max-count window on that retention today (the Console payload monitor shows only the newest 50 for display).
+`live` retains delivered messages and replays them to a late subscriber. Omit `retention` for an unbounded tape (a production hazard). `maxAge` (clock duration) and `maxCount` AND-combine when both are set. Drivers prune on write and when `live()` opens — no background sweeper.
+
+Reconnects send SSE `Last-Event-ID`. If that id was pruned or never existed, the server returns **410** `{ error: { code: "LiveResumeGap" } }` (**OKE1014**) before opening the stream. The client clears the cursor; `autoResubscribe` then replays whatever remains.
 
-<Callout title="Client subscription is not shipped yet">
-  `delivery: "live"` means the **driver** retains and replays. Listen with `bus.live()` on the
-  server — not `on(signal, flow)`. `createClient` has no SSE yet — poll HTTP. See
-  [Client](/docs/reference/client#signal-and-live-queries).
+The Console payload monitor still shows only the newest 50 for display — that cap is not the retained tape.
+
+<Callout title="HTTP live is GET SSE">
+  Expose with `http.get(path).live(signal)` or `http.live(signal)`. Subscribe with `api.live(signal,
+  input?, {onEvent})` — callback + unsubscribe, not `for await`. See
+  [Client](/docs/reference/client#live-signals).
 </Callout>
 
 ## Orphaned signal config
@@ -291,7 +309,7 @@ Pairing an arbitrary Store insert with emit inside **one** shared SQL transactio
 You emitted a signal that nobody currently subscribes to. For `once` and `broadcast`, wire
 `on(signal, flow)` before emit.
 
-`live` listeners are `bus.live()`, not a Flow — set `optional: true` when they may connect later.
+`live` listeners are HTTP SSE (`api.live` / `fx.live`), not a Flow — set `optional: true` when they may connect later.
 
 </Accordion>
 <Accordion title="Emit fails with OKE1043 (schema)">
@@ -306,13 +324,24 @@ When `attempts > retries` the message moves to the DLQ (if `deadLetter: true`)
 </Accordion>
 <Accordion title="fx.deadLetters throws OKE1001">
 
-The flow read a signal it did not declare. The compiler infers `reads: ["signal:<name>"]` from `fx.deadLetters(signal)`. A different handle needs its own read.
+The flow read a signal it did not declare. The compiler infers `reads: ["signal:<name>"]` from `fx.deadLetters(signal)` and `fx.live(signal)`. A different handle needs its own read.
+
+</Accordion>
+<Accordion title="Boot fails with OKE1013 (live exposure duplicate)">
+
+Two GET routes expose the same live signal with the same gates and match.
+Change the gate or path-param filter, or drop the extra route (same path is **OKE1011**).
+
+</Accordion>
+<Accordion title="Subscribe gets HTTP 410 LiveResumeGap (OKE1014)">
+
+The `Last-Event-ID` cursor is not on the retained tape (pruned, never existed, or the memory bus restarted). The gap is visible in `onError`. With `autoResubscribe: true` the next request omits the header and replays what remains.
 
 </Accordion>
 <Accordion title="on(liveSignal, flow) never replays history">
 
-`on(signal, flow)` listens for `once` and `broadcast`. `live` replay is `bus.live()` on the Signal
-bus — a Flow trigger does not replay retained payloads.
+`on(signal, flow)` listens for `once` and `broadcast`. `live` replay is HTTP SSE (`api.live` /
+`fx.live`) — a Flow trigger does not replay retained payloads.
 
 </Accordion>
 <Accordion title="once vs broadcast vs live — how do I choose?">

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

@@ -91,22 +91,17 @@ Install reviews the `CREATE EXTENSION` SQL; **Advanced** can set `SCHEMA`,
 When a newer packaged version exists, the name chip shows **Upgrade**
 (`ALTER EXTENSION … UPDATE`). Names link to the project or Postgres docs.
 
-Each SQL table row shows whether Postgres RLS is on (emerald shield)
-or off (muted shield). The resource header repeats that as an **RLS**
-chip before **PII** — **N RLS** when enabled and policies exist. KV,
-files, and index have no badge. Enabling RLS on create flips that
-shield.
-
-**RLS Policies** lists `pg_policies` plus Manifest policies (`declared` /
-`live`). Two-finger click a row to open its sheet (Edit / Save on editable
-columns); two-finger click empty grid to create. Create policy pins
-SQL | Code (`store.schema.policy` + `pgPolicy`); drag the handle to
-resize the preview.
+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 open a **Column** select of the table fields (guessed
-`creator_email` / `owner_email` when present) with the same PK / FK
-marks as schema cards. Create stays blocked until a real column is
-picked.
+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` —
@@ -204,10 +199,10 @@ const notesR = store.resource(db, notes, {
   },
 });
 
-const mounted = on(http.resource("/notes", notesR.all()).public().live());
+const mounted = on(http.resource("/notes", notesR.all()).public());
 ```
 
-`.gate(...)` / `.live()` chain like `http.get` — gates on every verb, live on list and get.
+`.gate(...)` / `.public()` chain like `http.get` — gates on every verb. Live SSE is `.live(signal)` on a GET, not on `http.resource`.
 
 The list endpoint's URL is the whole query language:
 
@@ -296,6 +291,9 @@ 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.
+
 <Callout title="One table per call — no relational with:">
   `fx.store` is deliberately **single-table**: Drizzle's relational `findMany({ with: … })` is not
   available through `fx`. Compose joins as separate single-table reads (or `fx.call`) so every
@@ -306,17 +304,18 @@ 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`       | happy-path RLS (`oke.gate()` / `oke.user()` / `oke.has_scope()`) |
+| 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:
 
@@ -331,6 +330,7 @@ export const bookings = store.schema.table(
     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"),
   ],
 );
 ```
@@ -340,9 +340,9 @@ Helpers emit stable names (`gate_member_select`). Raw
 escape hatch — predicates use `oke.*`, never `current_setting`.
 
 <Callout title="User-plane fx.store applies RLS">
-  HTTP / resource flows stamp Gate identity onto every postgres / pglite statement (`SET LOCAL ROLE
-  oke_app` + `set_config` in one pinned transaction). Table-owner bypass ends there; operator / cron
-  / CDC / signal / catalog stay unstamped.
+  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>
 
 #### Foreign keys and relations
@@ -692,6 +692,10 @@ export const drafts = store.kv("drafts", { durable: true, description: "Compose
 **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 })`.
+
 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`.
 
@@ -1130,7 +1134,7 @@ Default `store.kv` is cache Redis with no AOF — a recreate drops keys. SQL see
 - [Project structure](/docs/get-started/project-structure) — `list.ts` + `http.get()` is `GET /notes` named `notes.list`
 - [Flow](/docs/elements/flow) — the `fx.store` session inside `do`
 - [AI](/docs/elements/ai) — `ai.embed` into a vector `store.index`, searched via `fx.search`
-- [Gate](/docs/elements/gate) — `pii:reveal` and other permissions on flows
+- [Gate](/docs/elements/gate) — `pii:reveal`, `gate.auth.tenant`, and `oke.tenant()`
 - [CLI Reference](/docs/reference/cli) — `oke db push` · `generate` · `migrate`
 - [Configuration](/docs/reference/configuration) — `drivers.store` maps and `images` pins
 - [Environment variables](/docs/reference/environment-variables) — Redis · S3 · meilisearch URLs

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

@@ -151,6 +151,7 @@ Every name passed to `vault.env.required` is registered, so boot reports missing
 | `schema`      | zod / Standard Schema | Validated at boot; a bad value fails boot like a missing one                                                                                     |
 | `dev`         | string                | Local-only fallback when no source provides a value (never used in prod)                                                                         |
 | `sensitive`   | boolean               | Override the default (`true` for secrets, `false` for config)                                                                                    |
+| `perTenant`   | boolean               | Resolve at request time under `{tenantId}/{contract}`. Default `true` when `gate.auth.tenant` is on. Boot skips these contracts.                 |
 
 ### Zero-setup Compose fallback
 
@@ -201,6 +202,9 @@ The **Console** (`:6533`) **Vault** page (`/vault`) groups **Secrets** and
 **Config**. Secrets are write-only: a salted fingerprint (`sha256:…`), never
 the cleartext. Config rows show the value — that is `vault.config()`.
 
+API keys are principals — mint them on **Access** (`/access`), not Vault.
+See [Gate](/docs/elements/gate#api-keys).
+
 Add (`+`) creates a contract from Console as well as from source. Those rows
 show `console` until you declare the same name in the Manifest.
 
@@ -294,6 +298,20 @@ For production built-in stores, set `vault.encryption.masterKey` to a KMS source
 `@aws-sdk/client-kms`) or use `managed` with a provider below. `oke doctor` warns when prod would
 take the master key from the environment.
 
+## Tenant isolation (built-in store)
+
+When `gate.auth.tenant` is on, `perTenant` contracts resolve at request time under
+`{tenantId}/{contract}`. Boot skips those contracts.
+
+The built-in Postgres table `oke_vault_secrets` carries `tenant_id` and the same
+`oke.tenant()` helper as domain tables — not a second GUC.
+
+<Callout title="RLS on ciphertext rows">
+  `tenant_id = oke.tenant() OR tenant_id IS NULL`. ENABLE without FORCE: the adapter (owner) still
+  sees every row; Console / `oke_app` cannot list another tenant's ciphertext. Global `NULL` rows
+  stay visible to every stamped tenant.
+</Callout>
+
 ## Managed providers (official)
 
 Set `drivers.vault` to `"managed"` and `OKE_VAULT_PROVIDER` to an id below. Omit the provider when
@@ -346,6 +364,13 @@ radius before you rotate, and `is:overdue` when a secret is past its
 Prefer `oke vault unseal --key -` and pipe the key on stdin, or omit `--key` on a
 TTY and type it at the hidden prompt. Avoid `--key <base64>` on shared hosts.
 
+</Accordion>
+<Accordion title="Console SQL lists another tenant's vault rows">
+
+User-plane SQL is stamped `oke.tenant()`. The policy hides other tenants' ciphertext
+and keeps global `NULL` rows. The Vault adapter is table owner, so ENABLE (not FORCE)
+does not hide rows from itself.
+
 </Accordion>
 <Accordion title="Expired secrets still take space in Postgres">
 
@@ -365,6 +390,7 @@ Schedule the live command with cron when you want automatic cleanup.
 
 - [Project structure](/docs/get-started/project-structure) — `flow({…})` names as `unit.export`; `flow("billing.charge")` still wins
 - [Flow](/docs/elements/flow) — how `fx.vault.get` reads secrets inside `do`
+- [Gate](/docs/elements/gate) — `perTenant` contracts when `gate.auth.tenant` is on
 - [CLI Reference](/docs/reference/cli) — `oke vault set` · `list` · `import`
 
 ## Next

package/site/content/docs/get-started/project-structure.mdx

@@ -701,7 +701,7 @@ Plugin `.binding()` is never inferred. File tree is app flows only.
 
 ```typescript title="flows/my/index.ts"
 export const tasks = on(
-  http.get("/me/tasks").gate(member).live(),
+  http.get("/me/tasks").gate(member),
   flow("my.tasks", {
     do: async (_input, fx) => fx.store(db).select().from(tasks),
   }),
@@ -773,9 +773,9 @@ import { noteCreated } from "./signals";
 
 ### `http.resource` in a tree
 
-Five reserved leaves reproduce `GET|POST /notes` and `GET|PATCH|DELETE /notes/:id`, but not one shared `.gate()` / `.live()` and not `store.resource().all()` in a single declaration.
+Five reserved leaves reproduce `GET|POST /notes` and `GET|PATCH|DELETE /notes/:id`, but not one shared `.gate()` and not `store.resource().all()` in a single declaration.
 
-Put `on(http.resource("/notes", ops).public().live())` in `route.ts`. Inference is skipped — the five verbs already declare those paths. Extra actions (`[id]/archive.ts`) sit beside it. Pathless `http.resource()` is not a thing.
+Put `on(http.resource("/notes", ops).public())` in `route.ts`. Inference is skipped — the five verbs already declare those paths. Extra actions (`[id]/archive.ts`) sit beside it. Pathless `http.resource()` is not a thing.
 
 | Verb     | Path                |
 | -------- | ------------------- |
@@ -790,7 +790,7 @@ Put `on(http.resource("/notes", ops).public().live())` in `route.ts`. Inference
 
 ```typescript title="flows/notes/route.ts"
 const notesR = store.resource(db, notes, { in: NewNote, out: Note });
-export const mounted = on(http.resource("/notes", notesR.all()).public().live());
+export const mounted = on(http.resource("/notes", notesR.all()).public());
 ```
 
 </Tab>

package/site/content/docs/reference/cli.md

@@ -65,7 +65,7 @@ oke docker clean --yes           # non-TTY: current project only
 oke docker clean --all --yes     # non-TTY: every oke-dev-* project on this machine
 oke images pin                   # tags → digests in oke.images.lock
 
-oke build --target edge          # < 15 kB kernel profile
+oke build --target edge          # < 16 kB kernel profile
 oke eval                         # run prompt eval sets; fails CI on regression
 oke ai setup                     # configure AI driver + models (TTY wizard or flags)
 oke branch prod --at "yesterday" # fork journaled state into a sandbox