okengine 0.14.1 → 0.16.0

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

@@ -17,6 +17,7 @@ oke --help                       # command list (also what bare `oke` prints whe
 
 oke dev                          # watch · hot reload · Console :6533 · app :6530 · MCP :6535 · docs MCP :6536
                                  #   → always Docker Compose under docker/ + host Bun
+                                 #   → regenerates flows/generated.ts when the flows tree changes
                                  #   → client types + domain schema push on save
                                  #   → Console UI hot-reloads from source (okengine checkout; no bun run build)
 oke dev --no-db-push             #     opt out of auto oke db push on schema input save
@@ -48,7 +49,7 @@ oke schema generate              # core + plugin stubs → .oke/schema/oke.ts (-
 oke db push                      # domain schema.ts → live DB (dev; drizzle-kit)
 oke db generate                  # versioned SQL under drizzle/ (review)
 oke db migrate                   # apply migrations (explicit; never auto in prod)
-oke db seed                      # this app's defineSeed (name + essential + env); never at boot
+oke db seed                      # this app's defineSeed (name + essential + env) — standard CLI path
 oke db seed --env prod --force   # CI: skip prod confirmation prompt
 oke db studio                    # drizzle-kit Studio (long-running)
 oke vault set STRIPE_KEY         # also: list · import .env · key rotate
@@ -112,24 +113,26 @@ not spawn a second stack. Non-TTY / CI keeps the classic help listing
 `oke dev` always starts Compose (requires a running Docker daemon). Boot chrome
 prints immediately (wordmark + Starting + profile), then streams background work
 (compose up, vault, per-service health, AI probe). Status ● is green ready ·
-yellow pending/loading · red error · dim idle. Compose health keeps polling
+yellow pending/loading · red error · dim idle. After bind, Backend · Console ·
+MCP · Docs MCP each get a box (URL + one-line purpose). Compose health keeps polling
 (`docker compose ps -a`); AI ● tracks model phase while the AI container is up.
 Boot does not wait for the model to become ready. A successful session writes
 `.oke/dev.json` (pid · ports · startedAt) and clears it on stop. Durable local
-markers live in `.oke/state.json` (`seededAt` + `seed` after the one-shot
-prompt for this app's `defineSeed({ name })`) — not in the session lock. Console session signing uses
+markers live in `.oke/state.json` — not in the session lock. Console session signing uses
 `.oke/console.secret` (or `OKE_CONSOLE_SECRET`); that is not a Vault secret.
 
 On a TTY, Ink keyboard controls stay active after boot (`useInput` — same
 shortcuts as before). Press `r` to clear the log pane and reprint the latest
 board.
 
-| Key       | Action                              |
-| --------- | ----------------------------------- |
-| `?`       | help                                |
-| `r`       | refresh — clear logs, show latest ● |
-| `q`       | quit `oke dev`                      |
-| `u` / `x` | compose up / stop (whole stack)     |
+| Key | Action                              |
+| --- | ----------------------------------- |
+| `?` | help                                |
+| `r` | refresh — clear logs, show latest ● |
+| `s` | `oke db seed`                       |
+| `q` | quit `oke dev`                      |
+| `u` | compose up (whole stack)            |
+| `x` | compose stop (whole stack)          |
 
 Compose stays quiet unless it fails. Process-local boot notices print once under
 the hero (not once per process).

package/site/content/docs/reference/client.mdx

@@ -5,7 +5,7 @@ icon: "MonitorSmartphone"
 source: "docs/spec/unified-theory.md"
 ---
 
-`okengine/client` is how a browser, CLI, or another service calls your app's flows. Adopt the unit, take `typeof app`, and `api.notes.get({ id })` is fully typed — same contracts the server already has, no separate schema project.
+`okengine/client` is how a browser, CLI, or another service calls your app's flows. Import the generated barrel, take `typeof app`, and `api.notes.get({ id })` is fully typed — same contracts the server already has, no separate schema project.
 
 <Callout title="The one rule">
   Treat every call as a result envelope: `{ data, error }`. Flow failures are values you switch on
@@ -21,19 +21,22 @@ source: "docs/spec/unified-theory.md"
 ### Adopt flows and export `App`
 
 ```typescript title="src/app.ts"
-import { oke } from "okengine";
-import * as main from "./flows/main";
+import "@/core";
+import "@/flows/generated";
+import { oke } from "okengine/http";
 
-export const app = oke({ name: "standard" }).adopt({ main });
+export const app = oke({ name: "notes" });
 export type App = typeof app;
 ```
 
+`.adopt({ notes })` is optional and additive.
+
 </Step>
 
 <Step>
 ### Create the client
 
-Same repo — pass the app value so HTTP triggers hit REST (method + path from adopt):
+Same repo — pass the app value so HTTP triggers hit REST (method + path from `$routes`):
 
 ```typescript title="client"
 import { createClient } from "okengine/client";
@@ -114,7 +117,7 @@ oke client add https://api.example.com --out ./types/oke-client.d.ts
 | Incomplete proxy path (`api.notes()` with no flow) | Result error: `Incomplete path: api.notes(…)`                                                                                                                  |
 
 ```typescript
-// REST — createClient(app, url) saw method/path from on(http.get("/notes/:id"), …)
+// REST — method/path from the bound HTTP trigger (file tree or explicit)
 await api.notes.get({ id: "n_1" }); // GET /notes/n_1
 
 // RPC — untriggered flow named notes.stats
@@ -177,6 +180,9 @@ React: `useSession(api, session)` from `okengine/client-react`.
 | HTTP **401**           | `refresh()` runs **once**, then the same call retries            |
 | HTTP **403** / **429** | No refresh — decode the failure envelope as usual                |
 
+`getToken` may return a session access token or an API key secret — both are Bearer.
+See [Gate](/docs/elements/gate#api-keys). `refresh` applies to sessions only.
+
 **Consequence:** `refresh` must mutate whatever `getToken` reads. Returning a new string alone does
 nothing if storage was not updated.
 
@@ -210,16 +216,16 @@ core today: cookie jars or plugin `.client()` decorations. Browser apps: also se
   outcome by calling a Flow that uses it — or by handling a gate denial on that call.
 </Callout>
 
-| Element                           | On the client | How                                                                                     |
-| --------------------------------- | ------------- | --------------------------------------------------------------------------------------- |
-| [Flow](/docs/elements/flow)       | Direct        | `api.unit.flow(input)` — the only public surface                                        |
-| [Gate](/docs/elements/gate)       | Indirect      | Bearer via `auth`; denials as `Unauthorized` / `Forbidden` / `RateLimited`              |
-| [Store](/docs/elements/store)     | Via Flows     | `fx.store` inside Flows; `store.resource` + `on(http.resource…)` → five Flows you adopt |
-| [Signal](/docs/elements/signal)   | Via Flows     | Emit/consume server-side; no subscribe API on `okengine/client` yet                     |
-| [Clock](/docs/elements/clock)     | Via Flows     | Schedules fire on the server — the client never ticks a clock                           |
-| [Vault](/docs/elements/vault)     | Via Flows     | Secrets stay server-side; never ship them to the browser package                        |
-| [Channel](/docs/elements/channel) | Via Flows     | `fx.send` in a Flow — the client does not send email/SMS/push                           |
-| [AI](/docs/elements/ai)           | Via Flows     | `fx.ask` / `fx.run` inside a Flow; the client gets that Flow’s `out`                    |
+| Element                           | On the client | How                                                                                        |
+| --------------------------------- | ------------- | ------------------------------------------------------------------------------------------ |
+| [Flow](/docs/elements/flow)       | Direct        | `api.unit.flow(input)` — the only public surface                                           |
+| [Gate](/docs/elements/gate)       | Indirect      | Bearer via `auth`; denials as `Unauthorized` / `Forbidden` / `RateLimited`                 |
+| [Store](/docs/elements/store)     | Via Flows     | `fx.store` inside Flows; `store.resource` + `on(http.resource…)` → five Flows on `$routes` |
+| [Signal](/docs/elements/signal)   | Via Flows     | Emit/consume server-side; no subscribe API on `okengine/client` yet                        |
+| [Clock](/docs/elements/clock)     | Via Flows     | Schedules fire on the server — the client never ticks a clock                              |
+| [Vault](/docs/elements/vault)     | Via Flows     | Secrets stay server-side; never ship them to the browser package                           |
+| [Channel](/docs/elements/channel) | Via Flows     | `fx.send` in a Flow — the client does not send email/SMS/push                              |
+| [AI](/docs/elements/ai)           | Via Flows     | `fx.ask` / `fx.run` inside a Flow; the client gets that Flow’s `out`                       |
 
 ### Store resources
 
@@ -227,7 +233,7 @@ Mount a resource, adopt the returned ops, then call the five Flows like any othe
 
 ```typescript
 const notesR = store.resource(db, notes, {/* in, out, list */});
-const mounted = on(http.resource("/notes", notesR.all()).gate.public.live());
+const mounted = on(http.resource("/notes", notesR.all()).public().live());
 // .adopt({ notes: mounted }) →
 const page = await api.notes.list({ limit: 20 });
 const more = await page.next();
@@ -280,9 +286,9 @@ Budget: the `./client` export stays under the measured client-runtime cap (hard
 
 <Accordion title="api.main.health is not a function / type error">
 
-Confirm the flow is `export`ed from the module you `.adopt({ main })`, and that `createClient` is
-typed with that `App` (or ambient `Register` after `oke-client.d.ts` regenerates). Restart
-`oke dev` after renaming exports.
+Confirm the Flow is `export`ed from a generated unit (`import "@/flows/generated"` then `oke({ name })`), or from a module you still `.adopt({ main })`.
+
+Type `createClient` with that `App` (or ambient `Register` after `oke-client.d.ts` regenerates). Restart `oke dev` after renaming exports.
 
 </Accordion>
 
@@ -321,7 +327,8 @@ calls `api.auth.refresh({ refreshToken })`. Re-login when rotation fails or no r
 
 ## Learn more
 
-- [Basic usage](/docs/get-started/basic-usage) — adopt → client → test loop
+- [Project structure](/docs/get-started/project-structure) — folders are the URL; `$routes` without `.adopt()`
+- [Basic usage](/docs/get-started/basic-usage) — generated barrel → client → test loop
 - [Gate](/docs/elements/gate) — policies, `gate.public`, denials
 - [Store](/docs/elements/store) — `store.resource` and list query language
 - [Flow](/docs/elements/flow) — `in` / `out` / `errors` and `fx.fail`

package/site/content/docs/reference/fx.mdx

@@ -14,11 +14,16 @@ flow("orders.example", {
 });
 ```
 
+<Callout title="Extracted helpers">
+  Type a helper's `fx` parameter as `Fx` (`import type {Fx} from "okengine"`). A narrower structural
+  type will not match `store()` overloads. See [Flow](/docs/elements/flow).
+</Callout>
+
 ## Stores
 
 | Signature                                                           | Records      | Returns                                                                                     |
 | ------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------- |
-| `fx.store(sqlDecl).select().from(t)…`                               | `read`       | rows (`where` · `orderBy` · `limit` · `offset` chainable)                                   |
+| `fx.store(sqlDecl).select().from(t)…`                               | `read`       | inferred rows (`where` · `orderBy` · `limit` · `offset` chainable)                          |
 | `fx.store(sqlDecl).insert(t).values(v)`                             | `write`      | `Promise<void>`                                                                             |
 | `fx.store(sqlDecl).update(t).set(v).where(…)`                       | `write`      | `Promise<void>`                                                                             |
 | `fx.store(sqlDecl).delete(t).where(…)`                              | `write`      | `Promise<void>`                                                                             |
@@ -72,16 +77,21 @@ on(
 
 ## Flows
 
-| Signature                    | Records | Returns / notes                                       |
-| ---------------------------- | ------- | ----------------------------------------------------- |
-| `fx.call(flow, input?)`      | `call`  | The callee's `out` — runs through the same pipeline   |
-| `fx.step(name, fn)`          | —       | Durable step: replays from the journal, never re-runs |
-| `fx.all([...thunks])`        | —       | Parallel; first rejection aborts siblings             |
-| `fx.race([...thunks])`       | —       | First settle wins; losers aborted                     |
-| `fx.retry(fn, opts?)`        | —       | Exponential backoff + jitter (plain Promise)          |
-| `fx.using(acq, rel, use)`    | —       | `release` runs once on settle or ambient abort        |
-| `fx.signal`                  | —       | Ambient `AbortSignal` for the current branch          |
-| `fx.fail(code, data, opts?)` | —       | Typed failure value (`opts.message` overrides)        |
+| Signature                                                                      | Records                 | Returns / notes                                                                                    |
+| ------------------------------------------------------------------------------ | ----------------------- | -------------------------------------------------------------------------------------------------- |
+| `fx.call(flow, input?)`                                                        | `call`                  | The callee's `out` — runs through the same pipeline                                                |
+| `fx.step(name, fn)`                                                            | —                       | Durable step: replays from the journal, never re-runs                                              |
+| `fx.all([...thunks])`                                                          | —                       | Parallel; first rejection aborts siblings                                                          |
+| `fx.race([...thunks])`                                                         | —                       | First settle wins; losers aborted                                                                  |
+| `fx.retry(fn, opts?)`                                                          | —                       | Exponential backoff + jitter (plain Promise)                                                       |
+| `fx.using(acq, rel, use)`                                                      | —                       | `release` runs once on settle or ambient abort                                                     |
+| `fx.signal`                                                                    | —                       | Ambient `AbortSignal` for the current branch                                                       |
+| `fx.fail(code, data, opts?)`                                                   | —                       | Typed failure value (`opts.message` overrides)                                                     |
+| `fx.auth.createApiKey({ name, scopes, expiresIn?, ipAllowlist?, rateLimit? })` | `write` `auth:api-keys` | Secret once. Creator is live `userId` / `scopes`. Session only. `ipAllowlist` is IPs or hostnames. |
+| `fx.auth.listApiKeys()`                                                        | `read` `auth:api-keys`  | Keys this session minted                                                                           |
+| `fx.auth.revokeApiKey(id)`                                                     | `write` `auth:api-keys` | Owner only                                                                                         |
+| `fx.auth.rotateApiKey(id)`                                                     | `write` `auth:api-keys` | New secret once. Owner only                                                                        |
+| `fx.auth.updateApiKey(id, …)`                                                  | `write` `auth:api-keys` | Name / scopes / expiry / allowlist / rate. Re-attenuates                                           |
 
 `fx.call` starts the callee with an **empty** `fx.auth` (fail-closed for authorization). For
 audit/attribution only, read `fx.principal` — it propagates the originating identity without
@@ -265,15 +275,16 @@ Built-in `errors.*` / `oke.*` catalogs localize `fx.fail` messages and thrown
 
 ## Principals
 
-| Property       | Shape                                                                     |
-| -------------- | ------------------------------------------------------------------------- |
-| `fx.auth`      | `{ userId: string \| null, scopes: Set<string>, verified?: boolean }`     |
-| `fx.operator`  | `{ id: string \| null }` — Console plane                                  |
-| `fx.principal` | Read-only origin: `userId`, `operatorId`, `scopes`, `verified?`, `plane?` |
-| `fx.tenant`    | `{ id: string \| null }` — active tenant                                  |
+| Property       | Shape                                                                      |
+| -------------- | -------------------------------------------------------------------------- |
+| `fx.auth`      | `{ userId, scopes, verified?, apiKeyId? }` plus key methods (session only) |
+| `fx.operator`  | `{ id: string \| null }` — Console plane                                   |
+| `fx.principal` | Read-only origin: `userId`, `operatorId`, `scopes`, `verified?`, `plane?`  |
+| `fx.tenant`    | `{ id: string \| null }` — active tenant                                   |
 
 **Consequence:** use `fx.auth` / gates for authorization; use `fx.principal` only when a callee
-must log who started the call chain.
+must log who started the call chain. A key Bearer sets `userId` to the issuer and `apiKeyId`
+to the key — see [Gate](/docs/elements/gate#api-keys).
 
 ## Not on `fx`
 

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

@@ -41,13 +41,13 @@ Our path is concrete: a booking name containing "ignore previous instructions an
 #### 10.4 Remaining closures
 
 - **`invoke-as` is attenuated** exactly like an API key: an operator cannot assume a scope set they could not grant. Impersonating a real user is development-only. Console `POST /console/flows/invoke` runs the target flow on a bound host under the selected identity’s scopes (`trustedInvoke` is in-process only — never from public HTTP); when the host adapter is unbound, invoke fails closed.
-- **Store SQL browse** masks classified PII by default. `QUERY /console/store/query` with `revealPii: true` returns cleartext for the current page and writes an audited `console.store.query.reveal` log (operator, ref, child). The SQL query console (`POST /console/store/sql`) stays masked unless `revealPii: true`, which writes `console.store.sql.reveal` (operator, ref). Call API (`POST /console/flows/invoke`) masks the same classified field names on the handler response unless `revealPii: true`, which writes `console.flows.invoke.reveal` and opens the host store session with cleartext so columns the handler reads (for example `ownerEmail`) are not already `[redacted]`. `asGate` (a Manifest policy gate or `public`) sets `oke.gate` and `row_security` on postgres / pglite and writes `console.store.sql.asGate`; Operator (omit `asGate`) still bypasses RLS. Per-cell `POST /console/store/reveal` remains available. The Console auth schema (`sql:oke_console` — `oke_operators`, sessions, roles, keys) is hidden from Store browse unless `OKE_CONSOLE_AUTH_STORE=1`. When listed it is **read-only**; edit / delete / raw SQL are refused so operator-plane rows are never joined to `public`.
+- **Store SQL browse** masks classified PII by default. `QUERY /console/store/query` with `revealPii: true` returns cleartext for the current page and writes an audited `console.store.query.reveal` log (operator, ref, child). The SQL query console (`POST /console/store/sql`) stays masked unless `revealPii: true`, which writes `console.store.sql.reveal` (operator, ref). Call API (`POST /console/flows/invoke`) masks the same classified field names on the handler response unless `revealPii: true`, which writes `console.flows.invoke.reveal` and opens the host store session with cleartext so columns the handler reads (for example `ownerEmail`) are not already `[redacted]`. `{ asGate, asUserId }` on SQL, browse, row edit, and Call API stamps `oke.gate()` / `oke.user()` / `oke.has_scope()` on postgres / pglite (one identity bag; policy-only leaves `oke.user()` empty — never `gate:${name}`); Operator / omit / `bypassGates` still bypasses RLS. The response may include `rls: { gate, userId, applied }`. Catalog DDL stays Operator. Per-cell `POST /console/store/reveal` remains available. The Console auth schema (`sql:oke_console` — `oke_operators`, sessions, roles, keys) is hidden from Store browse unless `OKE_CONSOLE_AUTH_STORE=1`. When listed it is **read-only**; edit / delete / raw SQL are refused so operator-plane rows are never joined to `public`.
 - **Host WideEvent ingest** (`POST /console/runs/ingest`, `oke dev` only) is secret-gated and never echoes the event body. Operators read runs only through `projectRun` / `maskWideEventForConsole` on `GET /console/runs` and `/console/live` — the same PII boundary as Console-local runs.
 - **Store SQL performance** (`QUERY /console/store/sql/stats`, `/locks`, `POST /console/store/sql/advise`) is engine-native query text — not Store browse masking. Statements show `pg_stat_statements` fingerprints (`$n`). Live `pg_stat_activity.query` is collapsed until `revealPii: true`, which writes `console.store.sql.stats.reveal` (operator, ref). Named limitation `StoreSqlStatsQueryTextGap`. This surface does not terminate sessions or call `pg_stat_statements_reset`.
 - **Store KV performance** (`QUERY /console/store/kv/stats`) is Redis-wire `INFO` / `COMMANDSTATS` / `SLOWLOG` / `LATENCY` — not Store browse. INFO is instance-wide (`StoreKvStatsServerWideGap`). SLOWLOG args are keys and values — collapsed until `revealPii: true`, which writes `console.store.kv.stats.reveal` (operator, ref). Named limitation `StoreKvStatsSlowlogArgsGap`. `memory` returns `KvStatsUnsupported`. This surface does not run `MONITOR` and does not invent a hot-key table.
 - **Runs SQL** (`POST /console/runs/query`, Observability SQL tab) is operator-session, read-only, 5s timeout, 1000-row cap. DuckDB filesystem access is disabled for the statement. Masking is column-key only (`dim_*` and JSON blobs `input` / `output` / `logs` / `dimensions`). Aliases and expressions can leak classified values — named limitation `RunsQueryPiiProjectionGap`. This is **not** the `projectRun` guarantee. `revealPii: true` writes `console.runs.query.reveal`. Flow `fx.runs.query` stays unrestricted app SQL.
 - **Plugin panels** run in a sandboxed iframe without `allow-same-origin`, communicating only over a `postMessage` bridge with their own CSP, no access to the operator session token, and exposure limited to that plugin's declared flows.
-- **Session and framing:** `frame-ancestors 'none'`, `SameSite=Strict`, step-up authentication before destructive actions. An expired operator session redirects to Sign in with `?next=` set to the current `/overview`, `/flows`, `/store`, `/vault`, or `/observability` href (search included); after login the operator returns there. `/monitoring` is rewritten to `/observability`. Any other `next` (including `/units`) is dropped so the gate cannot be used as an open redirect. Unknown Console paths are 404.
+- **Session and framing:** `frame-ancestors 'none'`, `SameSite=Strict`, step-up authentication before destructive actions. An expired operator session redirects to Sign in with `?next=` set to the current `/overview`, `/flows`, `/store`, `/vault`, `/access`, or `/observability` href (search included); after login the operator returns there. `/monitoring` is rewritten to `/observability`. Any other `next` (including `/units`) is dropped so the gate cannot be used as an open redirect. Unknown Console paths are 404.
 - **Secret write path:** TLS required, no autocomplete, never echoed, never logged, not retained in browser memory after submission. Vault set / rotate / rotate-master use typed confirm (`SET` / `ROTATE` / `ROTATE_MASTER`). The Console never accepts a master key in the HTTP body (`OKE_VAULT_MASTER_KEY` only). `GET /console/vault/audit/verify` is read-only (no typed phrase).
 - **The setup claim code** is rate-limited and compared in constant time. It is
   printed on the `oke dev` board (TTY only — never on `GET /console/setup/status`)

package/src/auth/api-key-sql.test.ts

@@ -0,0 +1,47 @@
+import { describe, expect, test } from "bun:test";
+import { createApiKey, createApiKeyStore } from "./api-keys.ts";
+import { bindApiKeySqlPersist, hydrateApiKeyStore, type ApiKeySqlExec } from "./api-key-sql.ts";
+
+describe("api-key SQL persist", () => {
+  test("hydrate + persist round-trip", async () => {
+    const rows = new Map<string, Record<string, unknown>>();
+    const sql: ApiKeySqlExec = {
+      async execute(_q, params) {
+        const id = String(params[0]);
+        rows.set(id, {
+          id,
+          plane: params[1],
+          hash: params[2],
+          name: params[3],
+          scopes: params[4],
+          expires_at: params[5],
+          rate_limit: params[6],
+          ip_allowlist: params[7],
+          creator_id: params[8],
+          creator_scopes: params[9],
+          created_at: params[10],
+          last_used_at: params[11],
+          revoked_at: params[12],
+        });
+      },
+      async all() {
+        return [...rows.values()];
+      },
+    };
+    const store = createApiKeyStore();
+    bindApiKeySqlPersist(store, sql);
+    const created = await createApiKey(store, {
+      plane: "user",
+      name: "sql",
+      scopes: ["member"],
+      creatorId: "u1",
+      creatorScopes: ["member"],
+      id: "key_sql",
+    });
+    const other = createApiKeyStore();
+    await hydrateApiKeyStore(sql, other);
+    expect(other.keys.get("key_sql")?.name).toBe("sql");
+    expect(other.keys.get("key_sql")?.creatorId).toBe("u1");
+    expect(other.keys.get("key_sql")?.hash).toBe(created.row.hash);
+  });
+});

package/src/auth/api-key-sql.ts

@@ -0,0 +1,254 @@
+/**
+ * SQL persist / hydrate for {@link ApiKeyRow} on `oke_api_keys`.
+ *
+ * Host path: public schema on the app `store.sql()` connection
+ * (`sharedSqlConn` / `DATABASE_URL`). Console attaches that same
+ * {@link ApiKeyStore} — it does not own a second key table.
+ */
+
+import type { SqlConnection } from "../drivers/types.ts";
+import type { ApiKeyRow } from "./tables.ts";
+import { AUTH_TABLES } from "./tables.ts";
+import type { ApiKeyStore } from "./api-keys.ts";
+
+/** Minimal SQL executor for the auth key table. */
+export interface ApiKeySqlExec {
+  execute(sql: string, params: readonly unknown[]): Promise<void>;
+  all(sql: string): Promise<readonly Record<string, unknown>[]>;
+}
+
+/**
+ * Persist one key row to `oke_api_keys`.
+ *
+ * @param sql - Executor
+ * @param row - Key row
+ * @param table - Physical table (`oke_api_keys` or schema-qualified)
+ */
+export async function persistApiKeyRow(
+  sql: ApiKeySqlExec,
+  row: ApiKeyRow,
+  table: string = AUTH_TABLES.apiKeys,
+): Promise<void> {
+  await sql.execute(
+    `INSERT INTO ${table} (
+      id, plane, hash, name, scopes, expires_at, rate_limit, ip_allowlist,
+      creator_id, creator_scopes, created_at, last_used_at, revoked_at
+    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    ON CONFLICT(id) DO UPDATE SET
+      hash = excluded.hash,
+      name = excluded.name,
+      scopes = excluded.scopes,
+      expires_at = excluded.expires_at,
+      rate_limit = excluded.rate_limit,
+      ip_allowlist = excluded.ip_allowlist,
+      creator_id = excluded.creator_id,
+      creator_scopes = excluded.creator_scopes,
+      last_used_at = excluded.last_used_at,
+      revoked_at = excluded.revoked_at`,
+    [
+      row.id,
+      row.plane,
+      row.hash,
+      row.name,
+      JSON.stringify(row.scopes),
+      row.expiresAt,
+      row.rateLimit ? JSON.stringify(row.rateLimit) : null,
+      JSON.stringify(row.ipAllowlist),
+      row.creatorId,
+      JSON.stringify(row.creatorScopes),
+      row.createdAt,
+      row.lastUsedAt,
+      row.revokedAt,
+    ],
+  );
+}
+
+/**
+ * Load every key row from `oke_api_keys` into a store.
+ *
+ * @param sql - Executor
+ * @param store - Destination store
+ * @param table - Physical table
+ */
+export async function hydrateApiKeyStore(
+  sql: ApiKeySqlExec,
+  store: ApiKeyStore,
+  table: string = AUTH_TABLES.apiKeys,
+): Promise<void> {
+  const rows = await sql.all(`SELECT * FROM ${table}`);
+  for (const raw of rows) {
+    const row = rowFromSql(raw);
+    if (row) store.keys.set(row.id, row);
+  }
+}
+
+/**
+ * Bind write-through persist on a store.
+ *
+ * @param store - Key store
+ * @param sql - Executor
+ * @param table - Physical table
+ */
+export function bindApiKeySqlPersist(
+  store: ApiKeyStore,
+  sql: ApiKeySqlExec,
+  table: string = AUTH_TABLES.apiKeys,
+): void {
+  store.persist = (row) => persistApiKeyRow(sql, row, table);
+}
+
+/** Runtime that can open the app's shared primary SQL connection. */
+export interface HostApiKeySqlRuntime {
+  primarySql(): Promise<SqlConnection | undefined>;
+}
+
+/**
+ * Adapt a driver connection to {@link ApiKeySqlExec}.
+ *
+ * @param conn - Shared `store.sql()` connection
+ */
+export function apiKeySqlExec(conn: SqlConnection): ApiKeySqlExec {
+  return {
+    execute: async (sql, params) => {
+      await conn.exec(sql, params);
+    },
+    all: async (sql) => conn.query(sql),
+  };
+}
+
+/**
+ * Create public `oke_api_keys` when missing (host schema, not `oke_console`).
+ *
+ * @param conn - Shared SQL connection
+ * @param table - Physical table
+ */
+export async function ensureApiKeyTable(
+  conn: SqlConnection,
+  table: string = AUTH_TABLES.apiKeys,
+): Promise<void> {
+  await conn.exec(`
+    CREATE TABLE IF NOT EXISTS ${table} (
+      id TEXT PRIMARY KEY NOT NULL,
+      plane TEXT NOT NULL,
+      hash TEXT NOT NULL,
+      name TEXT NOT NULL,
+      scopes TEXT NOT NULL DEFAULT '[]',
+      expires_at BIGINT,
+      rate_limit TEXT,
+      ip_allowlist TEXT NOT NULL DEFAULT '[]',
+      creator_id TEXT NOT NULL,
+      creator_scopes TEXT NOT NULL DEFAULT '[]',
+      created_at BIGINT NOT NULL,
+      last_used_at BIGINT,
+      revoked_at BIGINT
+    )
+  `);
+}
+
+/**
+ * Hydrate and write-through-persist a host {@link ApiKeyStore} on `conn`.
+ *
+ * Leaves an already-bound `persist` hook in place (injected test stores).
+ *
+ * @param conn - App SQL connection (`sharedSqlConn`)
+ * @param store - `gate.auth.apiKeyStore`
+ * @param table - Physical table (`oke_api_keys` in `public`)
+ */
+export async function bindHostApiKeySql(
+  conn: SqlConnection,
+  store: ApiKeyStore,
+  table: string = AUTH_TABLES.apiKeys,
+): Promise<void> {
+  await ensureApiKeyTable(conn, table);
+  const exec = apiKeySqlExec(conn);
+  await hydrateApiKeyStore(exec, store, table);
+  if (!store.persist) bindApiKeySqlPersist(store, exec, table);
+}
+
+/**
+ * Bind host key persist through {@link HostApiKeySqlRuntime.primarySql}.
+ *
+ * No-ops when the store runtime has no SQL driver (in-memory-only apps).
+ *
+ * @param runtime - Booted `store` element
+ * @param store - `gate.auth.apiKeyStore`
+ */
+export async function bindHostApiKeySqlFromStore(
+  runtime: HostApiKeySqlRuntime,
+  store: ApiKeyStore,
+): Promise<void> {
+  const conn = await runtime.primarySql();
+  if (!conn) return;
+  await bindHostApiKeySql(conn, store);
+}
+
+function rowFromSql(raw: Record<string, unknown>): ApiKeyRow | null {
+  const id = asString(raw.id ?? raw.ID);
+  const plane = raw.plane === "operator" ? "operator" : "user";
+  const hash = asString(raw.hash);
+  const name = asString(raw.name);
+  const creatorId = asString(raw.creator_id ?? raw.creatorId);
+  if (!id || !hash || !name || !creatorId) return null;
+  return {
+    id,
+    plane,
+    hash,
+    name,
+    scopes: asStringArray(raw.scopes),
+    expiresAt: asNumberOrNull(raw.expires_at ?? raw.expiresAt),
+    rateLimit: asRateLimit(raw.rate_limit ?? raw.rateLimit),
+    ipAllowlist: asStringArray(raw.ip_allowlist ?? raw.ipAllowlist),
+    creatorId,
+    creatorScopes: asStringArray(raw.creator_scopes ?? raw.creatorScopes),
+    createdAt: asNumberOrNull(raw.created_at ?? raw.createdAt) ?? 0,
+    lastUsedAt: asNumberOrNull(raw.last_used_at ?? raw.lastUsedAt),
+    revokedAt: asNumberOrNull(raw.revoked_at ?? raw.revokedAt),
+  };
+}
+
+function asString(value: unknown): string | null {
+  return typeof value === "string" && value.length > 0 ? value : null;
+}
+
+function asNumberOrNull(value: unknown): number | null {
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  if (typeof value === "string" && value.length > 0) {
+    const n = Number(value);
+    return Number.isFinite(n) ? n : null;
+  }
+  return null;
+}
+
+function asStringArray(value: unknown): string[] {
+  if (Array.isArray(value)) return value.filter((item): item is string => typeof item === "string");
+  if (typeof value === "string" && value.length > 0) {
+    try {
+      const parsed: unknown = JSON.parse(value);
+      if (Array.isArray(parsed)) {
+        return parsed.filter((item): item is string => typeof item === "string");
+      }
+    } catch {
+      return [];
+    }
+  }
+  return [];
+}
+
+function asRateLimit(value: unknown): { max: number; per: string } | null {
+  const parsed: unknown =
+    typeof value === "string" && value.length > 0
+      ? (() => {
+          try {
+            return JSON.parse(value) as unknown;
+          } catch {
+            return null;
+          }
+        })()
+      : value;
+  if (!parsed || typeof parsed !== "object") return null;
+  const rec = parsed as { max?: unknown; per?: unknown };
+  if (typeof rec.max === "number" && typeof rec.per === "string") {
+    return { max: rec.max, per: rec.per };
+  }
+  return null;
+}