okengine 0.2.8 → 0.3.2

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

@@ -0,0 +1,171 @@
+---
+title: "Gate"
+description: "Permission to act — auth policies and rate limits attached to the trigger, evaluated before any effect runs, denied as typed errors."
+icon: "ShieldCheck"
+source: "docs/spec/unified-theory.md"
+---
+
+Gate is how your app answers **"may this happen?"** before it happens: is this request from a verified member? has this IP exhausted its minute quota? Gates attach to the trigger — the pipeline evaluates them before a single store write, emit, or channel send runs.
+
+<Callout title="The one rule">
+  Permission sits **at the trigger**, and denial is a typed error value — never a thrown exception,
+  never an effect that runs halfway and rolls back.
+</Callout>
+
+## Quick start
+
+<Steps>
+
+<Step>
+### Declare your gates
+
+Policies are named predicates; rate limits are declarative budgets. Both live once, app-wide:
+
+```typescript title="src/gates.ts"
+import { gate } from "okengine";
+
+export const member = gate.policy("member", ({ auth }) => !!auth?.verified);
+
+export const fair = gate.rate({
+  strategy: "sliding-window-counter", // the default — near-exact, no boundary bursts
+  max: 60,
+  per: "1m",
+  keyBy: "ip",
+});
+```
+
+</Step>
+
+<Step>
+### Attach them to triggers
+
+`.gate(...)` composes in registration order — evaluated left to right, first denial wins:
+
+```typescript title="src/flows/links/shorten.ts"
+export const shorten = on(
+  http.post("/links").gate(member, fair),
+  flow({
+    in: NewLink,
+    out: LinkCode,
+    errors: { Taken },
+    do: async ({ url, code }, fx) => {
+      /* runs only if both gates passed */
+    },
+  }),
+);
+```
+
+</Step>
+
+<Step>
+### Denials are typed failures
+
+A denied request never reaches `do`. It returns one of three typed failures, like any entry in `errors: { … }`:
+
+| Gate result                      | Typed failure                         |
+| -------------------------------- | ------------------------------------- |
+| Policy denied, not authenticated | `Unauthorized`                        |
+| Policy denied, authenticated     | `Forbidden` (with gate name + reason) |
+| Rate limit exceeded              | `RateLimited` (with `retryAfterMs`)   |
+
+</Step>
+
+</Steps>
+
+## Two kinds of gates
+
+| Declaration                | Question it answers                    | Evaluated against                  |
+| -------------------------- | -------------------------------------- | ---------------------------------- |
+| `gate.policy(name, check)` | Is this principal allowed? (ABAC)      | auth / operator / request metadata |
+| `gate.rate(options)`       | Is there budget left for this subject? | an atomic counter on the kv driver |
+
+### The policy context
+
+The predicate receives everything it may decide with — nothing else:
+
+| Field      | Contents                                                 |
+| ---------- | -------------------------------------------------------- |
+| `auth`     | User principal: `userId`, `scopes` (a `Set`), `verified` |
+| `operator` | Operator principal (Console plane): `id`                 |
+| `meta`     | Request metadata for keying decisions: `ip`, `userId`, … |
+
+```typescript
+export const admin = gate.policy("admin", ({ auth }) => auth.scopes.has("admin"));
+```
+
+A policy name containing `:` is also a `Module:Action` permission — the same declaration feeds role-based access reviews in the Console.
+
+### Rate options
+
+| Option        | Type         | Default                    | Meaning                                      |
+| ------------- | ------------ | -------------------------- | -------------------------------------------- |
+| `max`         | number       | — (**required**)           | Takes allowed within `per`                   |
+| `per`         | string       | — (**required**)           | Window / refill period (`"1m"`, `"60s"`, …)  |
+| `keyBy`       | string       | —                          | Subject dimension (`"ip"`, `"user"`, …)      |
+| `strategy`    | RateStrategy | `"sliding-window-counter"` | Algorithm (below)                            |
+| `overridable` | boolean      | `false`                    | Allow the Console to retune `max`/`per` live |
+
+| Strategy                 | Behavior                                               |
+| ------------------------ | ------------------------------------------------------ |
+| `sliding-window-counter` | Near-exact, two keys, no boundary bursts — the default |
+| `fixed-window`           | Cheapest; allows bursts at window boundaries           |
+| `sliding-log`            | Exact; stores one timestamp per take                   |
+| `token-bucket`           | Steady refill; permits saved-up bursts                 |
+| `leaky-bucket`           | Smooths output to a constant rate                      |
+
+All five run as atomic Lua on the kv driver — correct under concurrency, identical on the memory driver in tests.
+
+## Identity comes from auth
+
+Gates don't log users in — they decide about principals that already exist. The built-in auth plugin (`okengine/auth`) provides the user plane: hybrid sessions, argon2id password hashing, roles, API keys, and invites, with zero-config defaults. Whatever it establishes lands on `fx.auth`, which is exactly what your policies read.
+
+## Every decision is recorded
+
+Pass **and** deny, every evaluation lands on the run's `gates` dimension in the telemetry trace. The Console (`:6533` → Gates) shows which gates fired on a request and their outcomes — an audit trail of permission decisions you never had to build. Rate gates declared `overridable: true` can also be retuned (`max`/`per`) from the Console without a redeploy; anything else rejects edits by design.
+
+## Troubleshooting
+
+<Accordions>
+<Accordion title="Can a policy read the request body?">
+
+No — and that is deliberate. Gates run before the flow, so they see only the policy context (`auth`, `operator`, `meta`). Body-dependent decisions belong inside `do`, expressed as typed `errors`.
+
+</Accordion>
+<Accordion title="Logged-in users still get Forbidden">
+
+`Forbidden` means the request _was_ authenticated but a policy said no. The failure includes the gate name and reason — check whether your predicate requires `verified` or a scope the user lacks.
+
+</Accordion>
+<Accordion title="Which keyBy should I use?">
+
+`"ip"` for public unauthenticated surfaces (sign-up, password reset), `"user"` for authenticated quotas. Keying an authenticated endpoint by IP punishes users behind shared NAT; keying a public endpoint by user is impossible.
+
+</Accordion>
+<Accordion title="The Console won't retune my rate limit">
+
+The gate was declared without `overridable: true`. Add it and redeploy — live retuning is opt-in per gate so a mistyped change cannot silently open a floodgate.
+
+</Accordion>
+</Accordions>
+
+## Learn more
+
+- [Flow](/docs/elements/flow) — the trigger pipeline gates plug into
+- [Console · Gates](/docs/console/gates) — decision audit and live retuning
+- [Vault](/docs/elements/vault) — the credentials your policies protect
+
+## Next
+
+<Cards>
+  <Card title="Vault" description="Continue to Vault." href="/docs/elements/vault" />
+  <Card
+    title="Introduction"
+    description="Eight elements overview."
+    href="/docs/get-started/introduction"
+  />
+  <Card
+    title="Console"
+    description="Panels derived from the Manifest."
+    href="/docs/console/overview"
+  />
+</Cards>

package/site/content/docs/elements/meta.json

@@ -0,0 +1,5 @@
+{
+  "title": "Elements",
+  "icon": "Boxes",
+  "pages": ["flow", "signal", "store", "clock", "gate", "vault", "channel", "ai"]
+}

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

@@ -0,0 +1,171 @@
+---
+title: "Signal"
+description: "Data in motion — queues, pub/sub, and streams as one declaration whose delivery physics you choose explicitly."
+icon: "Radio"
+source: "docs/spec/unified-theory.md"
+---
+
+Signal is how your app moves data between flows and to clients: background jobs, events, fan-out notifications, live feeds. What other stacks split into a queue library, a pub/sub client, and a streaming platform is **one declaration** here — you pick the delivery physics, and the driver underneath is swappable per environment.
+
+<Callout title="The one rule">
+  `delivery` is **mandatory with no default**. Delivery physics is a semantic decision about your
+  data — guessing it produces silent, expensive bugs, so omitting it is a type error.
+</Callout>
+
+## Quick start
+
+<Steps>
+
+<Step>
+### Declare the signal
+
+A signal is a named, typed channel. The schema describes the payload; `delivery` describes its physics:
+
+```typescript title="src/signals.ts"
+import { signal } from "okengine";
+import { z } from "zod";
+
+export const orderPlaced = signal("order-placed", {
+  schema: z.object({ orderId: z.string(), total: z.number() }),
+  delivery: "once", // queue physics: one consumer, retries, DLQ
+  retries: 3,
+  deadLetter: true,
+});
+```
+
+</Step>
+
+<Step>
+### Emit it from a Flow
+
+Producers never touch a broker client — they call `fx.emit`:
+
+```typescript title="src/flows/orders/place.ts"
+do: async (input, fx) => {
+  await fx.store(db).insert(orders).values({ id: input.id /* … */ });
+  await fx.emit(orderPlaced, { orderId: input.id, total: input.total });
+  // With the postgres driver this enrols in the same transaction as the insert —
+  // the message is only ever sent if the row is committed.
+};
+```
+
+</Step>
+
+<Step>
+### Consume it with a Flow
+
+A signal is a trigger like any other — the consumer is an ordinary Flow:
+
+```typescript title="src/flows/orders/send-confirmation.ts"
+export const sendConfirmation = on(
+  orderPlaced,
+  flow({
+    in: z.object({ orderId: z.string(), total: z.number() }),
+    do: async (input, fx) => {
+      await fx.channel(email).send(/* … */);
+    },
+  }),
+);
+```
+
+</Step>
+
+</Steps>
+
+That's the loop: declare → `fx.emit` → `on(signal, flow)`. The runtime handles routing, retries, and dead-lettering.
+
+## The three delivery physics
+
+| `delivery`    | Semantics                                              | Use for                                                    |
+| ------------- | ------------------------------------------------------ | ---------------------------------------------------------- |
+| `"once"`      | Queue: competing consumers, retries, dead-letter queue | Jobs that must happen exactly once — emails, payments sync |
+| `"broadcast"` | Pub/sub: **every** subscriber receives a copy          | Cache invalidation, cross-service events                   |
+| `"live"`      | Stream: client-subscribable and replayable             | Live feeds, dashboards, progress updates                   |
+
+The declaration is identical in shape for all three — switching physics later is a one-word change, not a migration to another library.
+
+### Options
+
+| Option       | Type                              | Default          | Meaning                                                        |
+| ------------ | --------------------------------- | ---------------- | -------------------------------------------------------------- |
+| `delivery`   | `"once" \| "broadcast" \| "live"` | — (**required**) | Delivery physics                                               |
+| `schema`     | zod / Standard Schema             | —                | Payload contract; typed emits and Manifest docs                |
+| `retries`    | number                            | `3`              | Max delivery attempts before dead-letter (`once`)              |
+| `deadLetter` | boolean                           | `true`           | Preserve exhausted messages in the DLQ (`once`)                |
+| `optional`   | boolean                           | `false`          | Allow emitting while nobody subscribes (skip the orphan check) |
+
+## When delivery fails
+
+`once` signals retry automatically. Every attempt keeps a **typed failure reason**, and the full attempt history survives into the DLQ — so when a message lands there you see _why_ each attempt failed, not just that it did.
+
+The **Console** (`:6533` → Signals) shows the topology (which flows emit and consume each signal), per-subscriber delivery stats, and the DLQ contents with replay / discard controls — no separate broker UI to run.
+
+<Callout title="Orphan emits fail loudly">
+  Emitting a signal with zero subscribers is normally an error — it almost always means a typo or a
+  forgotten consumer. Set `optional: true` on the declaration only when zero-subscriber emits are
+  genuinely expected (e.g. an integration hook).
+</Callout>
+
+## Per-environment drivers
+
+```typescript title="oke.config.ts"
+drivers: {
+  signal: { local: "memory", docker: "postgres", test: "memory", prod: "postgres" },
+},
+```
+
+| Driver     | Runs as                          | Best for                                                                  |
+| ---------- | -------------------------------- | ------------------------------------------------------------------------- |
+| `memory`   | in-process                       | Local loop + tests — zero infrastructure                                  |
+| `postgres` | your existing Postgres container | Default for docker/prod — emits join your DB transaction (outbox pattern) |
+| `redis`    | Redis container                  | Explicit alternative when throughput outgrows Postgres                    |
+| `nats`     | NATS container                   | High-throughput fan-out                                                   |
+
+`postgres` is the default outside local dev for a reason: `fx.emit` enrols in the caller's transaction, so "write row + emit event" commits or rolls back **atomically** — the classic dual-write bug is designed out.
+
+## Troubleshooting
+
+<Accordions>
+<Accordion title="Emit fails with a 'no subscribers' error">
+
+You emitted a signal that no flow consumes. Either wire a consumer with `on(signal, flow)`, or set `optional: true` on the declaration if zero-subscriber emits are intentional.
+
+</Accordion>
+<Accordion title="A message keeps retrying and then disappears">
+
+After `retries` attempts the message moves to the DLQ — it is not lost. Open Console → Signals, inspect the typed failure reasons on each attempt, fix the consumer, then replay.
+
+</Accordion>
+<Accordion title="once vs broadcast vs live — how do I choose?">
+
+Ask: _how many consumers should process each message?_ One → `once`. All of them → `broadcast`. Clients over time, with replay → `live`. If you need retries and a DLQ, you want `once`.
+
+</Accordion>
+<Accordion title="My emit happened but the row didn't (or vice versa)">
+
+That is the dual-write problem, and it means the signal driver is not `postgres`. With the `postgres` driver the emit joins your SQL transaction; with `redis` / `nats` an outbox relay keeps the guarantee, but `postgres` is the only mode where atomicity is literal.
+
+</Accordion>
+</Accordions>
+
+## Learn more
+
+- [Flow](/docs/elements/flow) — `on(trigger, flow)` and `fx.emit`
+- [Console · Signals](/docs/console/signals) — topology, delivery stats, DLQ replay
+- [Clock](/docs/elements/clock) — scheduled and delayed work
+
+## Next
+
+<Cards>
+  <Card title="Store" description="Continue to Store." href="/docs/elements/store" />
+  <Card
+    title="Introduction"
+    description="Eight elements overview."
+    href="/docs/get-started/introduction"
+  />
+  <Card
+    title="Console"
+    description="Panels derived from the Manifest."
+    href="/docs/console/overview"
+  />
+</Cards>

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

@@ -0,0 +1,320 @@
+---
+title: "Store"
+description: "Data at rest — SQL tables, KV cache, file blobs, and vector search, declared once and swapped per environment by driver."
+icon: "Database"
+source: "docs/spec/unified-theory.md"
+---
+
+Store is where your app's **data at rest** lives. It covers four kinds of storage — relational tables, key-value cache, file blobs, and vector search — behind one declaration style. Your flow code never changes between SQLite on your laptop and Postgres in production; only the driver does.
+
+<Callout title="The one rule">
+  Drivers are named after **protocols**, not vendors (`postgres`, `redis`, `s3` — never `neon` or
+  `minio`). Vendor choice lives in the `images` map of `oke.config.ts`.
+</Callout>
+
+## Quick start
+
+<Steps>
+
+<Step>
+### Declare a table
+
+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";
+
+export const notes = store.schema.table("notes", {
+  id: field.text().primaryKey().defaultFn(id),
+  title: field.text().notNull(),
+  body: field.text().notNull(),
+  createdAt: field.integer().notNull().defaultFn(now),
+});
+```
+
+</Step>
+
+<Step>
+### Declare the store
+
+Bind the schema to a SQL store in `src/core.ts`:
+
+```typescript title="src/core.ts"
+import { store } from "okengine";
+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
+```
+
+</Step>
+
+<Step>
+### Read and write in a Flow
+
+All data access goes through `fx.store(db)` — a typed session, one table at a time:
+
+```typescript title="src/flows/notes/create.ts"
+export const createNote = on(
+  http.post("/notes"),
+  flow({
+    in: z.object({ title: z.string(), body: z.string() }),
+    out: z.object({ id: z.string() }),
+    do: async (input, fx) => {
+      const id = fx.id();
+      await fx
+        .store(db)
+        .insert(notes)
+        .values({ id, ...input, createdAt: Date.now() });
+      return { id };
+    },
+  }),
+);
+```
+
+</Step>
+
+</Steps>
+
+## The four facets
+
+Pick the facet that matches the physics of your data. Each declaration is one line; the runtime handle shows what flows can do with it.
+
+| Facet                     | Declares          | Best for                              | `fx.store(…)` handle                                   |
+| ------------------------- | ----------------- | ------------------------------------- | ------------------------------------------------------ |
+| `store.sql(name, opts)`   | a SQL database    | domain tables, relations, constraints | `select` · `insert` · `update` · `delete` · `findById` |
+| `store.kv(name)`          | a key-value space | cache, sessions, rate limits          | `get` · `set(key, value, ttl?)` · `delete` · `list`    |
+| `store.files(name)`       | a blob bucket     | uploads, exports, attachments         | `put` · `get` · `delete` · `list(prefix?)`             |
+| `store.index(name, opts)` | a vector index    | semantic search / RAG (`dims`)        | `upsert` · `search(vector, topK?)` · `delete`          |
+
+```typescript
+export const cache = store.kv("sessions");
+export const uploads = store.files("attachments");
+export const embeddings = store.index("docs", { dims: 1536 });
+```
+
+## CRUD without boilerplate — `store.resource`
+
+Five conventional endpoints (list, create, get, update, remove) expand from one declaration. Each is an ordinary Flow underneath — same contracts, same `fx`:
+
+```typescript
+const notesR = store.resource(db, notes, {
+  in: NewNote, // create/update input schema
+  out: Note, // response schema
+  update: NewNote.partial(),
+  list: {
+    cursor: [notes.createdAt, notes.id], // keyset pagination columns
+    direction: "desc",
+    search: [notes.title], // ?search= / ?q=
+    filter: "all", // ?col=op.value — "all" | Column[] | "none"
+    order: "all", // ?order=col.desc
+  },
+  unit: "notes",
+});
+
+const mounted = on(http.resource("/notes", notesR.all()));
+```
+
+The list endpoint's URL is the whole query language:
+
+| Param                               | Meaning                                             | Example                 |
+| ----------------------------------- | --------------------------------------------------- | ----------------------- |
+| `?cursor=` / `?offset=` / `?limit=` | paginate (keyset when `cursor` columns are set)     | `?limit=20&cursor=eyJ…` |
+| `?search=` (`?q=`)                  | substring match over `search` columns               | `?q=invoice`            |
+| `?col=op.value`                     | filter — ops `eq ne gt gte lt lte like ilike in is` | `?title=like.%draft%`   |
+| `?or=(…)` / `?and=(…)`              | grouped boolean filters                             | `?or=(a.eq.1,b.eq.2)`   |
+| `?order=`                           | sort                                                | `?order=createdAt.desc` |
+| `?select=`                          | project columns                                     | `?select=id,title`      |
+
+Responses follow the Stripe-style envelope: `{ data, meta: { nextCursor, hasNextPage }, error }`. `create` answers **201**, `remove` answers **204**, and a missing row is a typed `NotFound` — never a crash.
+
+## Querying by hand
+
+When `store.resource` is too conventional, `fx.store(db)` is the full single-table session:
+
+```typescript
+// select — chain where / orderBy / limit / offset in any order
+const latest = await fx
+  .store(db)
+  .select()
+  .from(notes)
+  .where(like(notes.title, `%${input.q}%`))
+  .orderBy(desc(notes.createdAt))
+  .limit(20);
+
+// findById, insert, update, delete
+const one = await fx.store(db).findById(notes, input.id);
+await fx.store(db).update(notes).set({ title: input.title }).where(eq(notes.id, input.id));
+await fx.store(db).delete(notes).where(lt(notes.createdAt, cutoff));
+```
+
+<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
+  table shows up explicitly in the Manifest's `reads` / `writes` — powering caching and PII masking.
+</Callout>
+
+## Schema — declare once, generate per dialect
+
+The recommended path: declare tables ORM-agnostically, then let `oke db` emit real Drizzle for the active dialect (`sqliteTable` locally, `pgTable` in docker/prod) into `src/schema.generated.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` |
+| `.references(() => col, { onDelete })`       | foreign key                                     |
+
+### Foreign keys and relations
+
+Declare FKs on fields, and relation metadata once per schema:
+
+```typescript
+export const daily = store.schema.table("daily", {
+  id: field.text().primaryKey(),
+  code: field
+    .text()
+    .notNull()
+    .references(() => links.code),
+  day: field.text().notNull(),
+  clicks: field.integer().notNull().default(0),
+});
+
+export const relations = store.schema.relations({ links, daily }, (r) => ({
+  links: { daily: r.many.daily({ from: r.links.code, to: r.daily.code }) },
+  daily: { link: r.one.links({ from: r.daily.code, to: r.links.code, optional: false }) },
+}));
+```
+
+<Callout title="Many-to-many">
+  A junction table with two foreign keys plus two `one` / `many` relations composes many-to-many.
+  There is no separate API and no `.through()` — the junction is an ordinary table.
+</Callout>
+
+### Syncing the schema
+
+| Command           | When                                                           |
+| ----------------- | -------------------------------------------------------------- |
+| `oke db push`     | Dev — apply directly to the live local DB (no migration files) |
+| `oke db generate` | Write versioned SQL under `drizzle/` for review                |
+| `oke db migrate`  | Apply those files — human or CI, **never** at boot             |
+
+`oke dev` (local) auto-pushes when the schema file changes — opt out with `--no-db-push` or `db: { autoPush: false }`. Docker/prod **never** auto-apply DDL; a missing table fails loudly as **OKE1101**, telling you to run `oke db migrate`.
+
+<Callout title="Escape hatch">
+  Hand-written Drizzle in `src/schema.ts` stays supported — if there is nothing to emit, the emit
+  step is skipped and your file is used as-is. Plugins may contribute **whole new tables**;
+  extending an app-owned table with plugin columns is not supported in v1.
+</Callout>
+
+## Per-environment drivers
+
+Same flow code, different backends — configured once in `oke.config.ts`:
+
+```typescript title="oke.config.ts"
+drivers: {
+  store: {
+    sql:   { local: "sqlite", docker: "postgres", test: "memory", prod: "postgres" },
+    kv:    { local: "memory", docker: "redis",    test: "memory", prod: "redis" },
+    files: { local: "fs",     docker: "s3",       test: "memory", prod: "s3" },
+  },
+},
+```
+
+| Facet   | Local    | Docker / prod | Runs as                                 |
+| ------- | -------- | ------------- | --------------------------------------- |
+| `sql`   | `sqlite` | `postgres`    | file on disk → container + named volume |
+| `kv`    | `memory` | `redis`       | in-process → container                  |
+| `files` | `fs`     | `s3`          | project folder → RustFS container       |
+| `index` | `memory` | `pgvector`    | in-process → pgvector image             |
+
+Container images come from the `images` map — change the vendor by changing the pin, never the driver id.
+
+## Privacy built in
+
+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.
+
+## Examples — what follows from each choice
+
+### An admin table
+
+```typescript
+list: { mode: "offset", count: "exact", limit: 20 },
+```
+
+**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`.
+
+### An infinite feed
+
+```typescript
+list: { cursor: [notes.createdAt, notes.id], direction: "desc", limit: 20, maxLimit: 100 },
+```
+
+**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.
+
+### A public, restricted endpoint
+
+```typescript
+list: { mode: "offset", filter: "none", limit: 20 },
+```
+
+**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.
+
+## Troubleshooting
+
+<Accordions>
+<Accordion title="OKE1101 — missing table in docker or prod">
+
+Schema DDL never runs automatically outside local dev. Run `oke db push` against the target database for a dev-style sync, or `oke db generate` + `oke db migrate` for reviewed, versioned migrations.
+
+</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>
+<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>
+</Accordions>
+
+## Learn more
+
+- [Flow](/docs/elements/flow) — the `fx.store` session inside `do`
+- [Console · Store](/docs/console/store) — browse data, cache keys, PII masking
+- [CLI Reference](/docs/reference/cli) — `oke db push` · `generate` · `migrate`
+
+## Next
+
+<Cards>
+  <Card title="Clock" description="Continue to Clock." href="/docs/elements/clock" />
+  <Card
+    title="Introduction"
+    description="Eight elements overview."
+    href="/docs/get-started/introduction"
+  />
+  <Card
+    title="Console"
+    description="Panels derived from the Manifest."
+    href="/docs/console/overview"
+  />
+</Cards>