okengine 0.11.1 → 0.12.0

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

@@ -97,28 +97,29 @@ Built-in defaults (`DRIVER_DEFAULTS`) when a key is omitted:
 | `vault`         | `env`      | `memory`  | `vault`    |
 | `channel.email` | `smtp`     | `console` | `smtp`     |
 | `channel.sms`   | — (opt-in) | —         | —          |
+| `runs`          | `files`    | `memory`  | `files`    |
 
 `store.index`, `channel.whatsapp` / `push`, and `ai` have no single three-env default table — set them explicitly when you need them. create-oke templates pin `vault.dev: "vault"` (built-in) because the default `dev` driver is `env`.
 
 ## Driver keys and ids
 
-| Key                | Shape          | Driver ids                                                                   |
-| ------------------ | -------------- | ---------------------------------------------------------------------------- |
-| `store.sql`        | env driver map | `postgres` · `pglite` · `memory`                                             |
-| `store.kv`         | env driver map | `memory` · `redis`                                                           |
-| `store.files`      | env driver map | `memory` · `fs` · `s3`                                                       |
-| `store.index`      | env driver map | `memory` · `pgvector` · `meilisearch`                                        |
-| `signal`           | env driver map | `memory` · `redis` (boot); `postgres` · `nats` fail loud until clients bind  |
-| `clock`            | env driver map | `memory` · `postgres` · `file` · `frozen`                                    |
-| `journal`          | env driver map | `memory` · `file` · `postgres`                                               |
-| `vault`            | env driver map | `env` · `vault` · `memory` · `managed`                                       |
-| `channel.email`    | env driver map | `console` · `smtp` · `resend` · `sndr` · `taqnyat-mail`                      |
-| `channel.sms`      | env driver map | `console` · `taqnyat` · `msegat` · `unifonic`                                |
-| `channel.whatsapp` | env driver map | `console` · `wa-cloud`                                                       |
-| `channel.push`     | env driver map | `console` · `webpush` · `fcm`                                                |
-| `ai`               | env driver map | `mock` · `anthropic` · `openai-compatible` · `bedrock` · `vertex` · `ollama` |
-| `runs`             | env driver map | runs-store driver (distinct from top-level `runs`)                           |
-| `prod`             | `string[]`     | flat protocol list for the Manifest — nested maps are preferred              |
+| Key                | Shape          | Driver ids                                                                       |
+| ------------------ | -------------- | -------------------------------------------------------------------------------- |
+| `store.sql`        | env driver map | `postgres` · `pglite` · `memory`                                                 |
+| `store.kv`         | env driver map | `memory` · `redis`                                                               |
+| `store.files`      | env driver map | `memory` · `fs` · `s3`                                                           |
+| `store.index`      | env driver map | `memory` · `pgvector` · `meilisearch`                                            |
+| `signal`           | env driver map | `memory` · `redis` (boot); `postgres` · `nats` fail loud until clients bind      |
+| `clock`            | env driver map | `memory` · `postgres` · `file` · `frozen`                                        |
+| `journal`          | env driver map | `memory` · `file` · `postgres`                                                   |
+| `vault`            | env driver map | `env` · `vault` · `memory` · `managed`                                           |
+| `channel.email`    | env driver map | `console` · `smtp` · `resend` · `sndr` · `taqnyat-mail`                          |
+| `channel.sms`      | env driver map | `console` · `taqnyat` · `msegat` · `unifonic`                                    |
+| `channel.whatsapp` | env driver map | `console` · `wa-cloud`                                                           |
+| `channel.push`     | env driver map | `console` · `webpush` · `fcm`                                                    |
+| `ai`               | env driver map | `mock` · `anthropic` · `openai-compatible` · `bedrock` · `vertex` · `ollama`     |
+| `runs`             | env driver map | `memory` · `files` (Parquet + DuckDB at `.oke/runs`) · `postgres` · `clickhouse` |
+| `prod`             | `string[]`     | flat protocol list for the Manifest — nested maps are preferred                  |
 
 ### Safety rules
 
@@ -150,11 +151,11 @@ images: {
   store: {
     sql: "postgres:18-alpine",
     kv: "redis:8-alpine",
-    files: "rustfs/rustfs:1.0.0-beta.11",
+    files: "rustfs/rustfs:1.0.0-rc.2",
   },
-  channel: { email: "axllent/mailpit:v1.22.3" },
-  pgdog: "ghcr.io/pgdogdev/pgdog:v0.1.51",
-  // ai: "ghcr.io/ggml-org/llama.cpp:server-b10290",
+  channel: { email: "axllent/mailpit:v1.30.7" },
+  pgdog: "ghcr.io/pgdogdev/pgdog:v0.1.53",
+  // ai: "ghcr.io/ggml-org/llama.cpp:server-b10450",
   // proxy: "caddy:2-alpine",
 },
 ```
@@ -195,9 +196,10 @@ privacy: {},
 
 Runs retention and redaction — **not** the same key as `drivers.runs`.
 
-| Option   | Type                     | Meaning                                               |
-| -------- | ------------------------ | ----------------------------------------------------- |
-| `redact` | `Record<string, string>` | Field → retention duration; presence turns privacy on |
+| Option   | Type                     | Meaning                                                                    |
+| -------- | ------------------------ | -------------------------------------------------------------------------- |
+| `keep`   | `string` \| `"forever"`  | Delete Parquet partitions older than this (`7d` in `dev`, `30d` in `prod`) |
+| `redact` | `Record<string, string>` | Field → retention duration; presence turns privacy on                      |
 
 ## db
 
@@ -252,6 +254,11 @@ Domain schema sync for `oke db push | generate | migrate` (Drizzle). Unrelated t
   `postgres` / `pglite`. `oke mode` was removed — `oke dev` always starts Docker Compose.
 </Accordion>
 
+<Accordion title="Runs DuckDB / Parquet queries requires @duckdb/node-api">
+  The `files` driver needs `@duckdb/node-api`. create-oke templates add it. Install with `bun add
+  @duckdb/node-api` if an older app is missing the peer.
+</Accordion>
+
 </Accordions>
 
 ## Learn more

package/site/content/docs/reference/environment-variables.mdx

@@ -4,7 +4,7 @@ description: "Every environment variable OKE reads — connection URLs, driver o
 icon: "Terminal"
 ---
 
-OKE reads environment variables at boot for connection detail and secrets — never for behavior you could declare in `oke.config.ts`. Under `oke dev`, Compose writes these into `docker/.env.docker`; this page is the full map.
+OKE reads environment variables at boot for connection detail and secrets — never for behavior you could declare in `oke.config.ts`. Under `oke dev`, Compose writes these into `.env.local`; this page is the full map.
 
 <Callout title="Precedence">
   For anything with both an `OKE_*` variable and a conventional one (like `DATABASE_URL`), the
@@ -54,17 +54,17 @@ OKE reads environment variables at boot for connection detail and secrets — ne
 
 ## Vault
 
-Built-in store uses `OKE_VAULT_MASTER_KEY` (or `--key` / stdin on CLI). Managed AWS Secrets Manager
-uses the provider + region vars below.
+Built-in store uses `OKE_VAULT_MASTER_KEY` (or `--key` / stdin on CLI). Managed providers use the
+vars below — see [Vault](/docs/elements/vault) for which each id needs.
 
-| Variable               | Used for                                     | Default when unset    |
-| ---------------------- | -------------------------------------------- | --------------------- |
-| `OKE_VAULT_PROVIDER`   | Managed backend (`aws-secrets-manager`)      | — (platform-injected) |
-| `OKE_VAULT_REGION`     | Cloud region for AWS Secrets Manager         | —                     |
-| `OKE_VAULT_MOUNT`      | Secret-name prefix for AWS SM (`oke/prod/`)  | —                     |
-| `OKE_VAULT_MASTER_KEY` | Built-in vault master key (base64)           | —                     |
-| `OKE_VAULT_URL`        | Optional remote URL for community adapters   | —                     |
-| `OKE_VAULT_TOKEN`      | Optional remote token for community adapters | —                     |
+| Variable               | Used for                                                                                                     | Default when unset    |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------ | --------------------- |
+| `OKE_VAULT_PROVIDER`   | Managed backend (`aws-secrets-manager` · `azure-key-vault` · `gcp-secret-manager` · `doppler` · `1password`) | — (platform-injected) |
+| `OKE_VAULT_REGION`     | Cloud region (AWS Secrets Manager; GCP user-managed replication)                                             | —                     |
+| `OKE_VAULT_MOUNT`      | Scope: AWS/Azure prefix, GCP `project[/prefix]`, Doppler `project/config`, 1Password vault name              | —                     |
+| `OKE_VAULT_MASTER_KEY` | Built-in vault master key (base64)                                                                           | —                     |
+| `OKE_VAULT_URL`        | Azure Key Vault URI, 1Password Connect host, optional Doppler origin                                         | —                     |
+| `OKE_VAULT_TOKEN`      | Doppler service/personal token, 1Password Connect token                                                      | —                     |
 
 ## Channel (email) — boot binder
 
@@ -128,15 +128,18 @@ provider's real credentials — credentials alone never send.
 
 ## Framework behavior
 
-| Variable              | Used for                                                                                   |
-| --------------------- | ------------------------------------------------------------------------------------------ |
-| `OKE_DOCKER`          | `"1"` marks Compose / `oke dev` posture (set by the CLI)                                   |
-| `OKE_DB_AUTO_PUSH`    | Overrides `db.autoPush` at boot                                                            |
-| `OKE_DRIZZLE_DIALECT` | `"postgresql"` for drizzle-kit overlays (templates hardcode it)                            |
-| `OKE_DEV_REQUEST_LOG` | `"1"` logs requests during `oke dev` (set by the CLI)                                      |
-| `OKE_CONSOLE_SECRET`  | Console session signing secret — set explicitly in production (else `.oke/console.secret`) |
-| `PORT`                | App port in production containers (default `6530`)                                         |
-| `NODE_ENV`            | `"production"` switches the Console to its production posture                              |
+| Variable                 | Used for                                                                                                              |
+| ------------------------ | --------------------------------------------------------------------------------------------------------------------- |
+| `OKE_DOCKER`             | `"1"` marks Compose / `oke dev` posture (set by the CLI)                                                              |
+| `OKE_DB_AUTO_PUSH`       | Overrides `db.autoPush` at boot                                                                                       |
+| `OKE_DRIZZLE_DIALECT`    | `"postgresql"` for drizzle-kit overlays (templates hardcode it)                                                       |
+| `OKE_DEV_REQUEST_LOG`    | `"1"` logs requests during `oke dev` (set by the CLI) — surface, flow, status, timestamp, run id                      |
+| `OKE_CONSOLE_SECRET`     | Console operator-session signing secret (HMAC) — set in production; else `.oke/console.secret`. Not a Vault contract. |
+| `OKE_CONSOLE_AUTH_STORE` | `"1"` lists the operator-plane `oke_console` schema in Store browse (read-only). Hidden by default.                   |
+| `OKE_RUNS_INGEST_URL`    | Host → Console WideEvent ingest URL (`oke dev` sets this on the app child). Enables a memory runs store + push.       |
+| `OKE_RUNS_INGEST_SECRET` | Shared secret for `POST /console/runs/ingest` (`x-oke-runs-ingest` header). Minted by `oke dev`; never return events. |
+| `PORT`                   | App port in production containers (default `6530`)                                                                    |
+| `NODE_ENV`               | `"production"` switches the Console to its production posture                                                         |
 
 Console operator rows are **not** stored in `.oke/console.sqlite`. With `DATABASE_URL` (or
 `OKE_STORE_SQL_URL`) they live in Postgres schema `oke_console`. Without a Postgres URL,

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

@@ -60,31 +60,36 @@ Returned, not thrown — the request never reached `do`:
 
 ## Framework validation failures
 
-| Code              | When                                                                                       |
-| ----------------- | ------------------------------------------------------------------------------------------ |
-| `ValidationError` | Input failed the `in` schema, or a list param isn't whitelisted (`unknown list param "x"`) |
-| `NotFound`        | A `store.resource` get/update/remove hit a missing row                                     |
+| Code                   | When                                                                                                                |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| `ValidationError`      | Input failed the `in` schema, or a list param isn't whitelisted (`unknown list param "x"`)                          |
+| `NotFound`             | A `store.resource` get/update/remove hit a missing row                                                              |
+| `InvalidQuery`         | QUERY missing `Content-Type` (`reason: missing_content_type`) or body isn't JSON (`inconsistent_content`) — **400** |
+| `UnsupportedMediaType` | QUERY `Content-Type` is present but not `application/json` — **415**, `Accept-Query` lists JSON                     |
 
 ## Subsystem errors
 
 Thrown by specific subsystems — each names its own cause:
 
-| Error                         | Thrown when                                                        | What to do                                             |
-| ----------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------ |
-| `VaultBootError`              | A vault contract has no value in any resolution layer              | Set the missing names — the error lists every gap      |
-| `VaultError` (`UNSUPPORTED`)  | Managed provider unknown or not implemented in core                | Use `aws-secrets-manager`, built-in `vault`, or `env`  |
-| `AiPiiBuildError`             | Build: a flow sends PII fields to a third-party model              | Drop the fields or add `allowPii: true` — fields named |
-| `AiSchemaValidationError`     | A model response failed the prompt's `out` schema                  | Fix the prompt or the schema — response didn't conform |
-| `ScheduleNotOverridableError` | Console tried to edit a clock declared without `overridable: true` | Declare it overridable and redeploy                    |
-| `ClockResourceNotFoundError`  | Console action targeted an unknown clock name                      | Check the name against your `clock()` declarations     |
-| `DryRunWriteIsolationError`   | A write attempted inside a dry run                                 | Dry runs never write — use a real run                  |
-| `ManifestValidationError`     | The compiled Manifest failed schema validation                     | Re-run the build; the error names the offending entry  |
-| `CrossPlaneError`             | A user-plane token was used on the operator plane (or vice versa)  | Use the correct principal for the plane                |
-| `AttenuationError`            | A token was used beyond its attenuated scope                       | Re-issue with the needed scope                         |
-| `SessionError`                | Session token invalid, expired, or malformed                       | Re-authenticate                                        |
-| `OperatorError`               | Operator-plane operation failed its checks                         | Error message names the failed check                   |
-| `AccessGrantError`            | Console access grant rejected                                      | Re-request access with a valid grant                   |
-| `UnsupportedPathError`        | A route path shape the router can't compile                        | Simplify the path pattern                              |
+| Error                         | Thrown when                                                        | What to do                                                            |
+| ----------------------------- | ------------------------------------------------------------------ | --------------------------------------------------------------------- |
+| `VaultBootError`              | A vault contract has no value in any resolution layer              | Set the missing names — the error lists every gap                     |
+| `VaultError` (`UNSUPPORTED`)  | Managed provider unknown                                           | Use an official id, built-in `vault`, or `env`                        |
+| `VaultSealed`                 | Console rotate-master while this process holds no master key       | Export `OKE_VAULT_MASTER_KEY` or run `oke vault unseal`               |
+| `VaultRotateBusy`             | Master-rotation lease held or a batch is already in flight         | Wait and continue, or resume with `oke vault rotate-master --new-key` |
+| `VaultUnsupported`            | Console vault action on a non-builtin backend or missing SQL       | Use `drivers.vault = "vault"` and set `DATABASE_URL`                  |
+| `AiPiiBuildError`             | Build: a flow sends PII fields to a third-party model              | Drop the fields or add `allowPii: true` — fields named                |
+| `AiSchemaValidationError`     | A model response failed the prompt's `out` schema                  | Fix the prompt or the schema — response didn't conform                |
+| `ScheduleNotOverridableError` | Console tried to edit a clock declared without `overridable: true` | Declare it overridable and redeploy                                   |
+| `ClockResourceNotFoundError`  | Console action targeted an unknown clock name                      | Check the name against your `clock()` declarations                    |
+| `DryRunWriteIsolationError`   | A write attempted inside a dry run                                 | Dry runs never write — use a real run                                 |
+| `ManifestValidationError`     | The compiled Manifest failed schema validation                     | Re-run the build; the error names the offending entry                 |
+| `CrossPlaneError`             | A user-plane token was used on the operator plane (or vice versa)  | Use the correct principal for the plane                               |
+| `AttenuationError`            | A token was used beyond its attenuated scope                       | Re-issue with the needed scope                                        |
+| `SessionError`                | Session token invalid, expired, or malformed                       | Re-authenticate                                                       |
+| `OperatorError`               | Operator-plane operation failed its checks                         | Error message names the failed check                                  |
+| `AccessGrantError`            | Console access grant rejected                                      | Re-request access with a valid grant                                  |
+| `UnsupportedPathError`        | A route path shape the router can't compile                        | Simplify the path pattern                                             |
 
 ## Learn more
 

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

@@ -41,12 +41,12 @@ See [Store](/docs/elements/store) for the query-builder surface.
 
 Declare `effects: { reads: ["runs"] }`. Powers native SLO checkers (Clock + Channel) without a parallel metrics API.
 
-| Signature                                | Records       | Returns                                       |
-| ---------------------------------------- | ------------- | --------------------------------------------- |
-| `fx.runs.query(sql)`                     | `read` `runs` | SQL rows (`FROM runs` on files/memory)        |
-| `fx.runs.all()`                          | `read` `runs` | All wide events                               |
-| `fx.runs.window(flow, windowMs?)`        | `read` `runs` | Rolling P50/P95/P99 + error rate (default 5m) |
-| `fx.runs.checkSlo(flow, slo, windowMs?)` | `read` `runs` | Availability / latency breaches               |
+| Signature                                | Records       | Returns                                                                                  |
+| ---------------------------------------- | ------------- | ---------------------------------------------------------------------------------------- |
+| `fx.runs.query(sql)`                     | `read` `runs` | SQL rows (`FROM runs` on files/memory). Unrestricted Flow SQL — not the Console sandbox. |
+| `fx.runs.all()`                          | `read` `runs` | All wide events                                                                          |
+| `fx.runs.window(flow, windowMs?)`        | `read` `runs` | Rolling P50/P95/P99 + error rate (default 5m)                                            |
+| `fx.runs.checkSlo(flow, slo, windowMs?)` | `read` `runs` | Availability / latency breaches                                                          |
 
 ```typescript
 on(
@@ -178,6 +178,12 @@ Durations: `"200ms"` · `"30s"` · `"2m"` · `"1h"` · `"7d"`.
 
 ## Cache
 
+Read-only flows cache automatically from inferred or ledgered `reads` — no
+`fx.cache` call and no `cache:` default on the flow. Writes invalidate those
+keys. Use `cache: false` to opt out, or `cache: "30s"` for a TTL.
+
+`fx.cache` is the manual (tier-3) surface:
+
 | Signature                              | Notes                                     |
 | -------------------------------------- | ----------------------------------------- |
 | `fx.cache.get(key)`                    | Value or `undefined`                      |
@@ -186,12 +192,13 @@ Durations: `"200ms"` · `"30s"` · `"2m"` · `"1h"` · `"7d"`.
 
 ## Responses
 
-| Helper                         | Status | Body                           |
-| ------------------------------ | ------ | ------------------------------ |
-| `fx.json.ok(value, { meta? })` | 200    | `{ data, meta?, error: null }` |
-| `fx.json.create(value)`        | 201    | `{ data, error: null }`        |
-| `fx.json.empty()`              | 204    | no body                        |
-| `fx.json.with(data, meta)`     | 200    | paginated envelope             |
+| Helper                                    | Status | Body                                                        |
+| ----------------------------------------- | ------ | ----------------------------------------------------------- |
+| `fx.json.ok(value, { meta? })`            | 200    | `{ data, meta?, error: null }`                              |
+| `fx.json.create(value)`                   | 201    | `{ data, error: null }`                                     |
+| `fx.json.empty()`                         | 204    | no body                                                     |
+| `fx.json.with(page)` / `with(data, meta)` | 200    | `{ data, meta, error: null }` — already-built pager         |
+| `fx.json.withQuery(rows, input, spec?)`   | 200    | In-memory list page — zero-config `q` / auto-eq / PostgREST |
 
 Returning a plain value instead answers 200 with `{ data: value, error: null }` — the helpers exist for status and `meta` control.
 

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

@@ -110,14 +110,14 @@ At `onResponse`, `ctx.response` holds the **final serialized HTTP response** —
 
 ## Edge handlers answer unmatched requests
 
-Hooks only ever see requests a flow owns — an `OPTIONS` preflight for a path bound to `GET` matches nothing and would 404 untouched. `.edge(fn)` closes that gap: handlers run in install order when the router finds no flow, the first returned `Response` answers, and `undefined` passes to the next handler, then the plain 404:
+Hooks only ever see requests a flow owns — an `OPTIONS` preflight for a path bound to `GET` matches nothing and would 405 untouched. `.edge(fn)` closes that gap: handlers run in install order when the router finds no flow, the first returned `Response` answers, and `undefined` passes to the next handler, then **405** if the path exists for other methods, else 404:
 
 ```typescript
 plugin("cors", { version: "1.0.0" }).edge((request, info) => {
   if (info.method === "OPTIONS" && request.headers.has("origin")) {
     return new Response(null, { status: 204, headers: preflightHeaders(request) });
   }
-  return undefined; // not mine — let someone else answer, else 404
+  return undefined; // not mine — let someone else answer, else 405/404
 });
 ```
 

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

@@ -40,14 +40,23 @@ 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.
-- **Exports are a separate capability** — row-limited by default, audited with the query recorded, PII masked without `pii:reveal`, and **CSV formula injection neutralised** (values beginning `=`, `+`, `-`, `@` are quoted, or Excel executes them on the recipient's machine).
+- **`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`.
+- **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.
-- **Secret write path:** TLS required, no autocomplete, never echoed, never logged, not retained in browser memory after submission.
-- **The setup claim code** is rate-limited and compared in constant time. The first-operator password
-  uses the same policy as Gate auth (minLength 12, letter + number); weak passwords return
-  `ClaimFailed` / `password_policy`, not an opaque 500.
+- **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.
+- **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`)
+  and mirrored to gitignored `.oke/claim-code` (mode 0600) for
+  `oke console claim-code` while setup is open; the file is removed after a
+  successful claim. The first-operator password
+  uses Console policy (minLength 12, upper + lower + number + special / `requireSpecial` — stricter than Gate auth’s
+  minLength 8 with the same character classes); weak passwords return `ClaimFailed` /
+  `password_policy`, not an opaque 500.
 
 #### 10.5 Reversibility governs the confirmation pattern
 

package/src/auth/auth.test.ts

@@ -274,7 +274,7 @@ describe("operator plane", () => {
     const op = await createOperator(store, {
       email: "ops@example.com",
       name: "Ops",
-      password: "correct horse battery staple 1",
+      password: "Correct Horse Battery Staple 1!",
     });
 
     expect(store.credentials.has(op.id)).toBe(true);
@@ -287,7 +287,7 @@ describe("operator plane", () => {
     const authed = await authenticateOperator(
       store,
       "ops@example.com",
-      "correct horse battery staple 1",
+      "Correct Horse Battery Staple 1!",
     );
     expect(authed?.id).toBe(op.id);
   });

package/src/auth/bindings.ts

@@ -275,10 +275,10 @@ export function createAuthHttpBindings(
   } = { refresh, revoke, me };
   const bindings: Binding[] = [
     bindAuthHttp(
-      http.post(`${base}/refresh`).gate(gate.public, ...(refreshRate ? [refreshRate] : [])),
+      http.post(`${base}/refresh`).gate.public.gate(...(refreshRate ? [refreshRate] : [])),
       refresh,
     ),
-    bindAuthHttp(http.post(`${base}/revoke`).gate(gate.public), revoke),
+    bindAuthHttp(http.post(`${base}/revoke`).gate.public, revoke),
     bindAuthHttp(http.get(`${base}/me`).gate(AUTH_SESSION_GATE), me),
   ];
 
@@ -371,11 +371,11 @@ export function createAuthHttpBindings(
     flows.signUpEmail = signUpEmail;
     bindings.push(
       bindAuthHttp(
-        http.post(`${base}/sign-in/email`).gate(gate.public, ...(signInRate ? [signInRate] : [])),
+        http.post(`${base}/sign-in/email`).gate.public.gate(...(signInRate ? [signInRate] : [])),
         signInEmail,
       ),
       bindAuthHttp(
-        http.post(`${base}/sign-up/email`).gate(gate.public, ...(signUpRate ? [signUpRate] : [])),
+        http.post(`${base}/sign-up/email`).gate.public.gate(...(signUpRate ? [signUpRate] : [])),
         signUpEmail,
       ),
     );
@@ -406,7 +406,7 @@ export function isSessionFresh(
  * @param flowDef - Flow
  */
 export function bindAuthHttp(trigger: HttpTrigger, flowDef: AnyFlowDef): Binding {
-  const withPosture = trigger.gates.length > 0 ? trigger : trigger.gate(gate.public);
+  const withPosture = trigger.gates.length > 0 ? trigger : trigger.gate.public;
   const normalized = normalizeTrigger(withPosture);
   const list = flowDef.triggers as Trigger[];
   list.push(normalized);

package/src/auth/config.ts

@@ -6,6 +6,7 @@
 
 import type { PasswordHashOptions } from "../runtime/types.ts";
 import type { SessionStore } from "./sessions.ts";
+import type { ApiKeyStore } from "./api-keys.ts";
 import type { BreachCheckFn } from "./breach-check.ts";
 import type { PasswordPolicyOptions } from "./password-policy.ts";
 import {
@@ -109,6 +110,11 @@ export interface GateAuthOptions extends AuthSchemaOptions {
    * Not part of the public app DX — escape hatch for embedding.
    */
   readonly sessions?: SessionStore;
+  /**
+   * In-memory API key store for Bearer key auth (tests / embedding).
+   * Distinct from schema `apiKeys` table options.
+   */
+  readonly apiKeyStore?: ApiKeyStore;
   /** Injectable clock. */
   readonly now?: () => number;
 }
@@ -164,6 +170,7 @@ export interface ResolvedGateAuth {
   };
   readonly hooks: AuthDatabaseHooks | undefined;
   readonly sessions: SessionStore | undefined;
+  readonly apiKeyStore: ApiKeyStore | undefined;
   readonly now: (() => number) | undefined;
 }
 
@@ -271,6 +278,7 @@ export function resolveGateAuth(options: ResolveGateAuthOptions): ResolvedGateAu
     },
     hooks: auth.hooks,
     sessions: auth.sessions,
+    apiKeyStore: auth.apiKeyStore,
     now: auth.now,
   };
 }

package/src/auth/gate-auth.test.ts

@@ -176,7 +176,7 @@ describe("gate.auth — email Flows + security", () => {
         headers: { "content-type": "application/json" },
         body: JSON.stringify({
           email: "user@example.com",
-          password: "CorrectHorse1",
+          password: "CorrectHorse1!",
           name: "User",
         }),
       }),
@@ -192,7 +192,7 @@ describe("gate.auth — email Flows + security", () => {
       new Request("http://localhost/auth/sign-in/email", {
         method: "POST",
         headers: { "content-type": "application/json" },
-        body: JSON.stringify({ email: "missing@example.com", password: "CorrectHorse1" }),
+        body: JSON.stringify({ email: "missing@example.com", password: "CorrectHorse1!" }),
       }),
     );
     const badBody = (await bad.json()) as { error: { code: string; data?: { reason?: string } } };
@@ -262,7 +262,7 @@ describe("gate.auth — email Flows + security", () => {
         headers: { "content-type": "application/json" },
         body: JSON.stringify({
           email: "weak@example.com",
-          password: "CorrectHorse1",
+          password: "CorrectHorse1!",
           name: "Strong",
         }),
       }),
@@ -289,14 +289,14 @@ describe("gate.auth — email Flows + security", () => {
       new Request("http://localhost/auth/sign-up/email", {
         method: "POST",
         headers: { "content-type": "application/json" },
-        body: JSON.stringify({ email: "dup@example.com", password: "CorrectHorse1" }),
+        body: JSON.stringify({ email: "dup@example.com", password: "CorrectHorse1!" }),
       }),
     );
     const again = await app.fetch(
       new Request("http://localhost/auth/sign-up/email", {
         method: "POST",
         headers: { "content-type": "application/json" },
-        body: JSON.stringify({ email: "dup@example.com", password: "CorrectHorse1" }),
+        body: JSON.stringify({ email: "dup@example.com", password: "CorrectHorse1!" }),
       }),
     );
     const body = (await again.json()) as { error: { data?: { reason?: string } } };

package/src/auth/index.ts

@@ -113,9 +113,12 @@ export {
 
 export {
   assertPasswordPolicy,
+  generatePassword,
   resolvePasswordPolicy,
   PasswordPolicyError,
   DEFAULT_PASSWORD_MIN_LENGTH,
+  DEFAULT_PASSWORD_POLICY,
+  type GeneratePasswordOptions,
   type PasswordPolicyOptions,
   type ResolvedPasswordPolicy,
 } from "./password-policy.ts";

package/src/auth/operator.ts

@@ -43,7 +43,7 @@ export interface CreateOperatorOptions {
   readonly roles?: readonly string[];
   /**
    * Password length / character-class policy. Defaults applied when omitted
-   * (minLength 12, letter + number). Pass custom knobs to tighten/loosen
+   * (minLength 8, letter, number, upper, lower, symbol). Pass custom knobs to tighten/loosen
    * within reason — never skip without {@link skipPasswordPolicy}.
    */
   readonly passwordPolicy?: PasswordPolicyOptions;