okengine 0.17.2 → 0.18.4

package/site/content/docs/providers/index.mdx

@@ -8,6 +8,8 @@ source: "docs/spec/unified-theory.md"
 Every provider below speaks a protocol oke already drives — Postgres wire or Redis wire.
 Hand the connection string to that driver; no new driver id, no Flow code changes.
 
+These managed providers are real, working infrastructure choices behind the same two templates (`standard`, `advanced`) and the same eight elements — not alternative products or separate frameworks.
+
 <Callout title="The one rule">
   Vendor choice lives in a connection URL (`DATABASE_URL` / `REDIS_URL`) — never in
   `drivers.store.sql` / `drivers.store.kv`, which only ever say `postgres` or `redis`.

package/site/content/docs/recipes/index.mdx

@@ -8,6 +8,8 @@ source: "docs/spec/unified-theory.md"
 Every recipe below is already wired into `oke docker` — pin an image in `oke.config.ts`
 and get env, healthcheck, and a connection URL for free.
 
+These recipes are real, working infrastructure choices behind the same two templates (`standard`, `advanced`) and the same eight elements — not alternative products or separate frameworks.
+
 <Callout title="The one rule">
   Vendor choice lives in `images[…]` — never in `drivers.*`, which only ever say protocol ids
   (`postgres`, `redis`, `s3`, `smtp`, `meilisearch`, `openai-compatible`, `ollama`, …).

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

@@ -27,7 +27,8 @@ oke test                         # bun test with PGLite posture (NODE_ENV=test,
 oke mode                         # removed — prints error; use oke dev (Compose) / oke test (PGLite)
 
 oke start                        # runs exactly what production runs (this is the Docker CMD)
-oke doctor                       # verify secrets, ports, drivers, tenancy, schema drift
+oke doctor                       # verify secrets, ports, drivers, tenancy, schema drift, FD headroom,
+                                 #   CDC outbox backlog/retention, live fan-out pressure
 oke console claim-code           # print setup claim code from .oke/claim-code (after Console boot)
                                  #   → `bun run dev:console` boots kernel + Vite with a fixed
                                  #     operator (`dev@oke.dev` / `Okengine123!`) — Sign in (prefilled)
@@ -141,7 +142,7 @@ the hero (not once per process).
 that `@electric-sql/pglite` resolves, then forwards argv to `bun test`.
 
 `oke mode` and `oke dev --local` / `-l` are removed — they exit with an error.
-See [Migrating environments](/docs/reference/migrating-environments).
+Rename the env keys in `oke.config.ts` to `dev` / `test` / `prod`.
 
 ### create-oke
 

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

@@ -172,7 +172,8 @@ const { data } = await api.auth.signInEmail({ email, password });
 if (data) session.set(data);
 ```
 
-React: `useSession(api, session)` and `useLive(api, signal, input?)` from `okengine/client-react`.
+React: `useSession(api, session)`, `useLive(api, signal, input?)`, and
+`useLiveQuery({ api, listFlow, live, query? })` from `okengine/client-react`.
 
 | Step                   | What happens                                                     |
 | ---------------------- | ---------------------------------------------------------------- |
@@ -205,6 +206,7 @@ A 401 with no `{ data, error }` body becomes `TransportError` with `data.status:
 | `AUTH_ERROR_CODES`          | `okengine/client/auth`  | Common auth Flow / gate codes                    |
 | `useSession(api, session?)` | `okengine/client-react` | React status + `auth.me`                         |
 | `useLive(api, signal, …)`   | `okengine/client-react` | React `events` / `latest` / `isConnected`        |
+| `useLiveQuery({ … })`       | `okengine/client-react` | Live list + optimistic `mutate` over a resource  |
 
 Core `okengine/client` stays under the size budget — helpers are separate exports. Not in
 core today: cookie jars or plugin `.client()` decorations. Browser apps: also see
@@ -305,6 +307,61 @@ const { events, latest, error, isConnected } = useLive(
 );
 ```
 
+### Live queries (`store.resource({ live: true })`)
+
+When a resource opts into `live: true`, the compiler mounts `GET <path>/live` next to the CRUD
+verbs. That route streams **classified** row events — not a shared tape — so each subscriber only
+sees rows that still pass their RLS stamp + list filters:
+
+| `kind`    | Meaning                                                        |
+| --------- | -------------------------------------------------------------- |
+| `upsert`  | Row visible under stamp + query — merge/replace by primary key |
+| `revoked` | Row left visibility (`reason: "rls"` \| `"query"`) — remove    |
+| `delete`  | Row deleted in CDC — remove                                    |
+
+```typescript
+import { useLiveQuery } from "okengine/client-react";
+
+const { data, error, isLoading, isConnected, isReconnecting, refetch, mutate } = useLiveQuery({
+  api,
+  listFlow: api.tasks.list,
+  query: { status: "open" },
+  live: { method: "GET", path: "/tasks/live" }, // from app.$routes
+  options: {
+    enabled: session.status === "authenticated", // default true — idle when false
+    refreshKey: tenantId, // identity change → full re-subscribe
+    onAuthRefresh: onAuthRefreshed, // auth.refresh() → new snapshot + replay
+  },
+});
+
+await mutate(
+  api.tasks.update,
+  { id, status: "done" },
+  {
+    optimistic: (rows) => rows.map((r) => (r.id === id ? { ...r, status: "done" } : r)),
+    pkOf: (input) => input.id,
+  },
+);
+```
+
+Every `mutate` call generates a client UUID sent as the `X-Oke-Mutation-Id`
+header — the server echoes it onto that write's CDC events, so:
+
+- Your own late SSE echoes never double-apply (pending-set dedupe).
+- Reconnects replay-guard by event `seq` (`isReplayedEvent`).
+- Manual `refetch()` re-runs only the HTTP list read; reconnects always do a
+  full subscribe-protocol cycle (new snapshot + replay).
+
+| State            | Meaning                                                             |
+| ---------------- | ------------------------------------------------------------------- |
+| `isLoading`      | Waiting for the first snapshot — no data yet                        |
+| `isConnected`    | SSE stream is open                                                  |
+| `isReconnecting` | Stream dropped after a successful load; reconnect backoff in flight |
+
+**Consequence:** optimistic patches roll back automatically when the Flow returns
+`error !== null`. Server CDC / the successful response clear the override so the next upsert is
+authoritative.
+
 ## Exports
 
 | Export                                    | Kind      | Role                                                |

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

@@ -28,8 +28,7 @@ export default defineConfig({
 | `prod` | Production deploy          | Shared durable backends                               |
 
 Missing `dev` pins fill from `prod` (`fillDevFromProd`). Only `dev` / `test` / `prod` keys are
-valid — see [Migrating environments](/docs/reference/migrating-environments) if you still have
-`local` / `docker` maps.
+valid — rename `local` → `dev` and `docker` → `prod` if you still have the old maps.
 
 ## Quick start
 
@@ -246,7 +245,7 @@ Domain schema sync for `oke db push | generate | migrate` (Drizzle). Unrelated t
 
 <Accordion title='oke.config: … uses removed driver "sqlite"'>
   The `sqlite` driver is gone. Pin `postgres` for `dev`/`prod` and `pglite` for `test`. Edit the
-  file by hand — see [Migrating environments](/docs/reference/migrating-environments).
+  file by hand — rename the env keys to `dev` / `test` / `prod` first.
 </Accordion>
 
 <Accordion title='drivers.store.sql.test must be "pglite"'>
@@ -268,7 +267,6 @@ Domain schema sync for `oke db push | generate | migrate` (Drizzle). Unrelated t
 
 ## Learn more
 
-- [Migrating environments](/docs/reference/migrating-environments) — four-key maps → `dev`/`test`/`prod`
 - [CLI Reference](/docs/reference/cli) — `oke dev` · `oke test` · `oke db`
 - [Environment Variables](/docs/reference/environment-variables) — URL and secret resolution
 - [Store](/docs/elements/store) — what the store drivers back

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

@@ -230,7 +230,9 @@ Returning a plain value instead answers 200 with `{ data: value, error: null }`
 | `fx.log.debug/info/warn/error(msg, data?)` | Redacting — secrets print as `***`                          |
 | `fx.t(key, values?)`                       | ICU MessageFormat — active locale → `i18n.default` → key    |
 | `fx.locale`                                | Active locale (`Accept-Language` matched to `i18n.locales`) |
-| `fx.id()`                                  | UUID — the only legal id generator                          |
+| `fx.id()`                                  | OKID — 21-char native id from `okengine/okid`               |
+
+See [OKID](/docs/reference/okid) for generation options and the entropy model.
 
 `fx.t` uses [ICU MessageFormat](https://unicode-org.github.io/icu/userguide/format_parse/messages/)
 (FormatJS): `{name}`, plurals, `select` / `selectordinal`, rich-text tags.

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

@@ -15,11 +15,6 @@ Dense tables and command lists. Reach for these when you already know what you a
     description="Every option in oke.config.ts."
     href="/docs/reference/configuration"
   />
-  <Card
-    title="Migrating environments"
-    description="local/docker maps → dev/test/prod."
-    href="/docs/reference/migrating-environments"
-  />
   <Card title="fx" description="The complete fx surface and effects." href="/docs/reference/fx" />
   <Card
     title="i18n"

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

@@ -4,7 +4,6 @@
   "pages": [
     "index",
     "configuration",
-    "migrating-environments",
     "fx",
     "i18n",
     "client",
@@ -12,6 +11,7 @@
     "errors",
     "plugins",
     "cli",
-    "security"
+    "security",
+    "okid"
   ]
 }

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

@@ -0,0 +1,137 @@
+---
+title: "OKID"
+description: "OKE's native id generator — compact, URL-safe, cryptographically random ids from okengine/okid, with an opt-in time-sortable and alphabet-controlled variant."
+icon: "Hash"
+source: "docs/spec/unified-theory.md"
+---
+
+Using `okengine/okid` gives you an id for any primary key, request trace, or event that is short (`okid()` is 21 characters), URL-safe, and random from a cryptographic source. Turn to it when a plain UUID string is more than you need; your app already generates them wherever `defaultFn(id)` is used.
+
+<Callout title="The one rule">
+  Use OKID for identity, never for secrets. An id is enumerable by design, so anything you hand to
+  an untrusted client must be a token from the Vault, not an OKID.
+</Callout>
+
+## Quick start
+
+<Steps>
+
+<Step>
+### Install nothing — it is exported by the package
+
+```typescript
+import { okid } from "okengine/okid";
+```
+
+</Step>
+
+<Step>
+### Generate an id
+
+```typescript
+const userId = okid();
+const requestId = okid(16);
+const eventKey = okid({ sortable: true });
+const inviteCode = okid({ lookAlikes: false, uppercase: false });
+```
+
+</Step>
+
+<Step>
+### Store it anywhere a string fits
+
+```typescript
+// field.id() is shorthand for "default generation id" — currently OK ID.
+field.id().primaryKey();
+// Or pin OK ID explicitly:
+field.okid().primaryKey();
+```
+
+The same 21-character id lands in your SQL primary keys, KV keys, and trace ids.
+
+</Step>
+
+</Steps>
+
+## Reference
+
+| Call                                               | Result                                    | Notes                                   |
+| -------------------------------------------------- | ----------------------------------------- | --------------------------------------- |
+| `okid()`                                           | 21-char URL-safe id, 126 bits of entropy  | 64-char alphabet, `a-zA-Z0-9-_`         |
+| `okid(length)`                                     | id of exactly `length` characters         | integer between 8 and 128               |
+| `okid({ length })`                                 | options form, id of `length`              | default 21                              |
+| `okid({ sortable })`                               | time-prefixed id, 8 prefix + `length − 8` | lexicographic order ≈ creation order    |
+| `okid({ numbers, lowercase, uppercase, symbols })` | charset control                           | each group defaults to on               |
+| `okid({ lookAlikes })`                             | confusable-char control                   | `lookAlikes: false` drops `1lI0Oouv5Ss` |
+
+### Options
+
+| Option       | Type      | Default | Meaning                                                     |
+| ------------ | --------- | ------- | ----------------------------------------------------------- |
+| `length`     | `number`  | `21`    | total id length in characters, between 8 and 128            |
+| `sortable`   | `boolean` | `false` | prefix an 8-char epoch-ms timestamp so sorting follows time |
+| `numbers`    | `boolean` | `true`  | include `0-9`                                               |
+| `lowercase`  | `boolean` | `true`  | include `a-z`                                               |
+| `uppercase`  | `boolean` | `true`  | include `A-Z`                                               |
+| `symbols`    | `boolean` | `true`  | include `-` and `_`                                         |
+| `lookAlikes` | `boolean` | `true`  | include confusable chars `1lI0Oouv5Ss`; set `false` to drop |
+
+### Exported constants
+
+| Constant                   | Value                                     | Meaning                          |
+| -------------------------- | ----------------------------------------- | -------------------------------- |
+| `OKID_ALPHABET`            | `a-zA-Z0-9-_`                             | default, Base64URL order         |
+| `OKID_SORTABLE_ALPHABET`   | alphabet sorted by code unit (same chars) | used by the sortable encoder     |
+| `OKID_LOOKALIKE_CHARS`     | `1lI0Oouv5Ss`                             | dropped when `lookAlikes: false` |
+| `OKID_DEFAULT_LENGTH`      | `21`                                      | default length                   |
+| `OKID_MIN_LENGTH`          | `8`                                       | shortest non-sortable length     |
+| `OKID_MAX_LENGTH`          | `128`                                     | longest length                   |
+| `OKID_SORTABLE_MIN_LENGTH` | `16`                                      | shortest sortable length (8+8)   |
+
+## Collision resistance
+
+Every character is drawn uniformly from the alphabet with `crypto.getRandomValues()`. Because it uses an unbiased character selection (never modulo), each character carries exactly `log2(alphabet)` bits of entropy. At the default 21 characters over 64 symbols, that is 126 bits — the birthday-bound collision probability across one billion ids is on the order of `10⁻²¹`. You do not need a UUID for collision resistance; this is where a UUID is stronger only because it is a different format, not a different amount of randomness.
+
+**Consequence:** two ids minted at the same millisecond are still distinct — the timestamp prefix never replaces entropy, it prefixes it.
+
+## Sortable ids
+
+`sortable: true` prepends 48 bits of `Date.now()` encoded in exactly 8 characters, in an alphabet whose sort order matches time order. Sorting a batch of these ids reproduces the creation order across milliseconds.
+
+**Consequence:** a sortable id embeds its creation time (millisecond precision), so keep them out of public, enumerable surfaces. Clock skew distorts order but can never produce a duplicate — the tail stays random.
+
+## Alphabet control
+
+Turning groups off shrinks the alphabet. With a non-power-of-two alphabet, OKID uses rejection sampling instead of modulo, so every remaining character stays equally likely — the output never becomes measurably biased.
+
+**Consequence:** smaller alphabets mean fewer bits per character. `lookAlikes: false` alone drops the default entropy only slightly (126 → ~120 bits); dropping whole groups costs more. Choose the smallest alphabet that fits the human-transcription use case.
+
+## Under the hood
+
+The generator is a pure function: no counters, no process or machine fingerprint, no shared mutable state. It is safe to call concurrently from any number of workers, and every id uses only the bytes it needs — no hidden timestamp, no hidden prefix.
+
+## Troubleshooting
+
+<Accordions>
+<Accordion title="I get an error for an empty alphabet">
+
+Passing `numbers: false, lowercase: false, uppercase: false, symbols: false` at the same time throws a `RangeError` with the message `okid: alphabet is empty — enable at least one character group`. Re-enable at least one group, or don't use the option object and rely on the default alphabet.
+
+</Accordion>
+<Accordion title="I get a RangeError for a length">
+
+`okid(0)`, `okid(-1)`, `okid(7)`, `okid(129)`, and non-integer lengths throw a `RangeError`. Sortable ids have a higher floor: passing a sortable length below 16 throws. Keep lengths between 8 and 128 (16–128 for sortable).
+
+</Accordion>
+<Accordion title="My ids are not sortable by the alphabet order I expected">
+
+The default alphabet order is not lexicographic; `_` sorts between uppercase and lowercase. When `sortable` is on, ids use the code-point-ordered alphabet, so plain string comparison matches time order. Do not customize the alphabet in sortable mode — the option exists exactly because the default order is not trustworthy for ordering.
+
+</Accordion>
+</Accordions>
+
+## References
+
+- [Store](/docs/elements/store) — `defaultFn(id)` in table declarations delegates to `okid()`
+- [fx](/docs/reference/fx) — `fx.id()` in the runtime uses `okid()`
+- [Clock](/docs/elements/clock) — process `instanceId` (`inst-<okid>`) is an OKID

package/src/auth/bindings.ts

@@ -175,7 +175,7 @@ export function createAuthHttpBindings(
   } = {},
 ): AuthHttpMaterialization {
   const sessions = options.sessions ?? config.sessions ?? createSessionStore();
-  const identities = options.identities ?? createIdentityStore();
+  const identities = options.identities ?? config.identities ?? createIdentityStore();
   const loginAttempts = createLoginAttemptBag();
   const rateGates = createAuthRateGates(options.rateLimitEnabled !== false);
   const policyGates = createAuthPolicyGates(config);

package/src/auth/config.ts

@@ -8,6 +8,7 @@ import type { PasswordHashOptions } from "../runtime/types.ts";
 import type { SessionStore } from "./sessions.ts";
 import { createApiKeyStore, type ApiKeyStore } from "./api-keys.ts";
 import type { BreachCheckFn } from "./breach-check.ts";
+import { createIdentityStore, type IdentityStore } from "./identity.ts";
 import type { PasswordPolicyOptions } from "./password-policy.ts";
 import {
   resolveAuthSchema,
@@ -116,6 +117,11 @@ export interface GateAuthOptions extends AuthSchemaOptions {
    * Not part of the public app DX — escape hatch for embedding.
    */
   readonly sessions?: SessionStore;
+  /**
+   * Shared identity / credential store. Created automatically when omitted.
+   * All Gate auth method plugins resolve against this one store by default.
+   */
+  readonly identities?: IdentityStore;
   /**
    * Shared API key store. Created automatically when omitted
    * (`gate.auth.secret` is the HMAC pepper).
@@ -186,6 +192,8 @@ export interface ResolvedGateAuth {
   readonly hooks: AuthDatabaseHooks | undefined;
   readonly sessions: SessionStore | undefined;
   readonly apiKeyStore: ApiKeyStore;
+  /** Shared identity store — the single user/credential source across Gate auth + method plugins. */
+  readonly identities: IdentityStore;
   readonly tenant: ResolvedTenantAuth | undefined;
   readonly tenantStore: TenantStore | undefined;
   readonly now: (() => number) | undefined;
@@ -296,6 +304,7 @@ export function resolveGateAuth(options: ResolveGateAuthOptions): ResolvedGateAu
     hooks: auth.hooks,
     sessions: auth.sessions,
     apiKeyStore: auth.apiKeyStore ?? createApiKeyStore({ pepper: secret }),
+    identities: auth.identities ?? createIdentityStore(),
     tenant: auth.tenant ? resolveTenantAuth(auth.tenant) : undefined,
     tenantStore: auth.tenant ? (auth.tenantStore ?? createTenantStore()) : auth.tenantStore,
     now: auth.now,