okengine 0.18.4 → 0.19.0

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

@@ -1,6 +1,6 @@
 ---
 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."
+description: "OKE's native id generator — compact, URL-safe, cryptographically random ids from okengine/okid, with opt-in prefix, time-sortable, and alphabet-controlled variants."
 icon: "Hash"
 source: "docs/spec/unified-theory.md"
 ---
@@ -31,6 +31,7 @@ import { okid } from "okengine/okid";
 ```typescript
 const userId = okid();
 const requestId = okid(16);
+const typedId = okid({ prefix: "usr_" });
 const eventKey = okid({ sortable: true });
 const inviteCode = okid({ lookAlikes: false, uppercase: false });
 ```
@@ -55,21 +56,23 @@ The same 21-character id lands in your SQL primary keys, KV keys, and trace ids.
 
 ## 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` |
+| 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, body of `length`           | default 21                              |
+| `okid({ prefix })`                                 | `prefix` + body                          | body length unchanged; see Options      |
+| `okid({ sortable })`                               | time-prefixed body, 8 + `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 |
+| `length`     | `number`  | `21`    | generated body length (8–128); does not include `prefix`    |
+| `prefix`     | `string`  | `""`    | fixed label prepended to the body (e.g. `"usr_"`, `"evt_"`) |
+| `sortable`   | `boolean` | `false` | prefix the body with an 8-char epoch-ms timestamp           |
 | `numbers`    | `boolean` | `true`  | include `0-9`                                               |
 | `lowercase`  | `boolean` | `true`  | include `a-z`                                               |
 | `uppercase`  | `boolean` | `true`  | include `A-Z`                                               |
@@ -83,10 +86,11 @@ The same 21-character id lands in your SQL primary keys, KV keys, and trace ids.
 | `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)   |
+| `OKID_DEFAULT_LENGTH`      | `21`                                      | default body length              |
+| `OKID_MIN_LENGTH`          | `8`                                       | shortest non-sortable body       |
+| `OKID_MAX_LENGTH`          | `128`                                     | longest body                     |
+| `OKID_SORTABLE_MIN_LENGTH` | `16`                                      | shortest sortable body (8+8)     |
+| `OKID_MAX_PREFIX_LENGTH`   | `32`                                      | longest semantic `prefix`        |
 
 ## Collision resistance
 
@@ -94,6 +98,12 @@ Every character is drawn uniformly from the alphabet with `crypto.getRandomValue
 
 **Consequence:** two ids minted at the same millisecond are still distinct — the timestamp prefix never replaces entropy, it prefixes it.
 
+## Semantic prefixes
+
+`prefix` is a fixed label (`"usr_"`, `"evt_"`, `"inst-"`) prepended to the generated body. Characters must belong to `OKID_ALPHABET` (max 32). `length` stays the body size; the returned string is `prefix + body`.
+
+**Consequence:** `okid({ prefix: "usr_", sortable: true })` yields `usr_` + 8-char timestamp + random tail — the label sorts first, then time.
+
 ## 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.
@@ -108,7 +118,7 @@ Turning groups off shrinks the alphabet. With a non-power-of-two alphabet, OKID
 
 ## 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.
+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 body uses only the bytes it needs — no hidden timestamp unless `sortable` is on.
 
 ## Troubleshooting
 
@@ -122,6 +132,13 @@ Passing `numbers: false, lowercase: false, uppercase: false, symbols: false` at
 
 `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="I get a RangeError for a prefix">
+
+Characters outside `OKID_ALPHABET` (for example `usr:` or a space) throw
+`okid: prefix contains invalid character … — use characters from OKID_ALPHABET`.
+A prefix longer than 32 throws `okid: prefix length … exceeds max 32` — stick to `A-Za-z0-9-_`.
+
 </Accordion>
 <Accordion title="My ids are not sortable by the alphabet order I expected">
 
@@ -130,8 +147,16 @@ The default alphabet order is not lexicographic; `_` sorts between uppercase and
 </Accordion>
 </Accordions>
 
-## References
+## Learn more
 
 - [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
+
+## Next
+
+<Cards>
+  <Card title="fx" description="fx.id() in Flows." href="/docs/reference/fx" />
+  <Card title="Store" description="defaultFn(id) on columns." href="/docs/elements/store" />
+  <Card title="Client" description="Ids round-trip on typed routes." href="/docs/client" />
+</Cards>

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

@@ -82,7 +82,7 @@ Every method below exists on both the fluent definition and the boot-time builde
 | `.image(role, recipe)`           | An image recipe for a docker role                                                             |
 | `.table(name, columns, options)` | A whole DB table, merged into the generated schema (`options.description` / `plane` optional) |
 | `.errors(map)`                   | Typed errors flows can fail with                                                              |
-| `.client(name, ext)`             | A typed client extension (reserved seam — not yet merged into `createClient`)                 |
+| `.client(name, ext)`             | Reserved plugin seam — prefer `createAuthClient` method helpers for auth                      |
 | `.consolePanel(panel)`           | A Console panel (ESM entry loaded at runtime)                                                 |
 | `.cli(name, handler)`            | An `oke <name>` CLI command                                                                   |
 | `.config(schema)`                | A config schema; values live on the plugin identity                                           |
@@ -133,7 +133,7 @@ Plugin options are static by default — changing them means a redeploy. Every o
 ### Declare the source and its sync flow
 
 ```typescript title="src/app.ts"
-import { every, oke, on, store } from "okengine";
+import { clock, oke, on, store } from "okengine";
 import { configSource, maintenanceMode } from "okengine/plugins";
 
 const db = store.sql("app");
@@ -146,7 +146,8 @@ const maintenance = configSource({
   kv: cache, // read-through cache (optional)
 });
 
-on(every("30s"), maintenance.sync()); // one clock flow refreshes the box
+const maintenanceSyncClock = clock("maintenance.sync", { every: "30s" });
+on(maintenanceSyncClock, maintenance.sync()); // one clock flow refreshes the box
 
 export const app = oke({ name: "shop", env: "dev" }).plug(maintenanceMode(maintenance));
 ```

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

@@ -0,0 +1,197 @@
+---
+title: "Security"
+description: "Host and Origin allow-lists, user vs operator planes, Console and MCP posture."
+icon: "Shield"
+source: "docs/spec/unified-theory.md"
+---
+
+Every served request on the backend, Console, and app MCP passes Host / Origin checks
+before your Flow runs. Private bind addresses are not a substitute for that check.
+
+Reach for this page when you put a public hostname in front of the app, open Console
+in production, or wire MCP tokens.
+
+<Callout title="The one rule">
+  Pass every public hostname in `allowedHosts` on `createBunRuntime().serve` (and the Console / MCP
+  serve options). Loopback is always allowed; `Origin: null` is always rejected. Failures return
+  **403**.
+</Callout>
+
+## Smallest Example
+
+<Steps>
+
+<Step>
+### Serve with an explicit host allow-list
+
+```typescript title="src/app.ts"
+import { createBunRuntime } from "okengine/http";
+import { app } from "./app";
+
+createBunRuntime().serve(app, {
+  port: Number(process.env.PORT ?? 6530),
+  hostname: "0.0.0.0",
+  allowedHosts: ["app.example.com", ".example.com"],
+});
+```
+
+`.example.com` allows `a.example.com` (Vite-style suffix). Always merged with
+`localhost` · `127.0.0.1` · `::1` and the listen hostname when it is not a
+wildcard bind.
+
+</Step>
+
+<Step>
+### Confirm a bad Host is refused
+
+```bash
+curl -i http://127.0.0.1:6530/health -H "Host: evil.example"
+```
+
+Expect `403` with body `Forbidden: unexpected Host header`.
+
+</Step>
+
+</Steps>
+
+## Progressive Patterns
+
+<Tabs items={["Reverse proxy", "Planes", "MCP"]}>
+
+<Tab value="Reverse proxy">
+
+Edge terminates TLS and forwards to the app. The `Host` the app sees must be on
+the allow-list — usually the public name, not the container hostname.
+
+```typescript
+createBunRuntime().serve(app, {
+  hostname: "0.0.0.0",
+  allowedHosts: ["app.example.com"],
+});
+```
+
+**Consequence:** omitting the public name behind Caddy / nginx / Traefik looks
+like a random 403 to browsers that send the site's `Host`.
+
+</Tab>
+
+<Tab value="Planes">
+
+Only two planes exist: **user** (application Flows, `fx.auth`) and **operator**
+(Console / MCP capability, `fx.operator`). Declare `plane: "operator"` on Flows
+that must stay off the public API.
+
+A user-plane token on an operator Flow (or the reverse) throws `CrossPlaneError`.
+API keys and Console `invoke-as` are attenuated — a derived principal never
+exceeds the creator's scopes.
+
+</Tab>
+
+<Tab value="MCP">
+
+| Surface  | Port     | Auth                                                      |
+| -------- | -------- | --------------------------------------------------------- |
+| App MCP  | **6535** | Bearer required **even on localhost**; audience `oke-mcp` |
+| Docs MCP | **6536** | Host / Origin only — public docs, not a live Manifest     |
+
+App MCP inherits **operator-plane** capability and never exceeds it. Tokens are
+never forwarded upstream. Tools declare scopes; writes need confirmation.
+
+</Tab>
+
+</Tabs>
+
+## Host / Origin Rules
+
+| Check    | Behavior                                                             |
+| -------- | -------------------------------------------------------------------- |
+| `Host`   | Required; must match the effective allow-list                        |
+| `Origin` | When present, host must match; `Origin: null` → 403                  |
+| Defaults | Always includes loopback + listen hostname (unless `0.0.0.0` / `::`) |
+| Extras   | `ServeOptions.allowedHosts` — never replaces the mandatory check     |
+
+`allowedHosts` lives on **serve options**, not in `oke.config.ts`. Pass it wherever
+you call `serve` for **6530**, Console **6533**, and app MCP **6535**.
+
+## Console Posture
+
+| Control       | Meaning                                                                    |
+| ------------- | -------------------------------------------------------------------------- |
+| Host / Origin | Same allow-list logic as the backend                                       |
+| CSP           | `default-src 'self'`; `frame-ancestors 'none'`                             |
+| Cookies       | `SameSite=Strict`                                                          |
+| Claim code    | Printed on `oke dev` TTY; `oke console claim-code` while setup is open     |
+| PII           | Store / Call API mask classified fields unless `revealPii: true` (audited) |
+
+Production Console: set `OKE_CONSOLE_SECRET` and configure
+`console.prod` in [Configuration](/docs/reference/configuration#console).
+
+## Sessions and Audiences
+
+| Audience      | Surface              |
+| ------------- | -------------------- |
+| `oke-app`     | Application sessions |
+| `oke-console` | Console operators    |
+| `oke-mcp`     | App MCP              |
+
+Short access JWT (default ~14m) + rotating refresh. Refresh-token reuse revokes
+the family.
+
+## Troubleshooting
+
+<Accordions>
+
+<Accordion title="403 Forbidden: unexpected Host header">
+  The request `Host` is not on the allow-list. Add the public hostname to `allowedHosts`, or hit
+  loopback (`localhost` / `127.0.0.1`) during local `oke dev`.
+</Accordion>
+
+<Accordion title="403 Forbidden: unexpected Origin header">
+  Browser sent an `Origin` whose host is not allowed, or `Origin: null`. Align the page origin with
+  `allowedHosts`, or call same-origin / non-browser clients without a spoofed Origin.
+</Accordion>
+
+<Accordion title="MCP tools refuse without Bearer on localhost">
+  App MCP on **6535** requires a Bearer with audience `oke-mcp` even on loopback. Docs MCP on
+  **6536** does not — it serves documentation only.
+</Accordion>
+
+<Accordion title="CrossPlaneError">
+  A user-plane token reached an operator Flow (or the reverse). Use the principal that matches the
+  Flow's `plane`.
+</Accordion>
+
+<Accordion title="AttenuationError">
+  A derived key or invoke-as identity requested a scope the creator cannot grant. Re-issue with a
+  subset of the creator's scopes.
+</Accordion>
+
+</Accordions>
+
+## Learn more
+
+- [CLI](/docs/reference/cli) — `oke dev`, `oke console claim-code`
+- [Gate](/docs/elements/gate) — policies, API keys, tenancy
+- [The Model](/docs/understand/the-model) — one shape, one door, fixed vocabulary
+- [Errors](/docs/reference/errors) — `CrossPlaneError`, `SessionError`, `AttenuationError`
+- [Environment Variables](/docs/reference/environment-variables) — `OKE_CONSOLE_SECRET`
+
+## Next
+
+<Cards>
+  <Card
+    title="Gate"
+    description="Auth, authorization, and rate limits."
+    href="/docs/elements/gate"
+  />
+  <Card
+    title="CLI"
+    description="oke and create-oke command catalogue."
+    href="/docs/reference/cli"
+  />
+  <Card
+    title="The Model"
+    description="One shape for every trigger, one door for every effect."
+    href="/docs/understand/the-model"
+  />
+</Cards>

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

@@ -0,0 +1,5 @@
+{
+  "title": "Understand",
+  "icon": "Compass",
+  "pages": ["the-problem", "the-model", "the-vocabulary", "the-anatomy"]
+}

package/site/content/docs/understand/the-anatomy.mdx

@@ -0,0 +1,132 @@
+---
+title: "The Anatomy"
+description: "The five pieces behind on(trigger, flow) — on, trigger, flow, do, and fx — explained one at a time, then combined."
+icon: "PenTool"
+---
+
+Everything a Flow does reduces to one line:
+
+```typescript
+on(
+  trigger,
+  flow({
+    do: (input, fx) => {
+      /* ... */
+    },
+  }),
+);
+```
+
+If that line doesn't mean much yet, that's what this page is for. Five pieces make it up. We'll take them one at a time, then put them together using a complete signup example.
+
+## `on(...)` — wires a trigger to a flow
+
+`on` does exactly one thing: it connects "something that can happen" to "code that should run when it does." Nothing executes until this connection exists.
+
+```typescript
+on(someTrigger, someFlow);
+```
+
+That's the whole job. The interesting parts are what goes in each slot.
+
+## A trigger — the answer to "when"
+
+The first argument to `on` is the trigger: whatever wakes the code up. A trigger doesn't run any of your logic — it only answers one question: _when should this happen?_
+
+```typescript
+http.post(); // path from the file tree — e.g. src/flows/users/signup.ts → POST /users/signup
+```
+
+There are five kinds of trigger in total — the table at the end of this page lists them. For now: the trigger is the _when_, and it's the only thing that changes between an endpoint, a scheduled job, and everything else.
+
+## `flow(...)` — the actual unit of work
+
+The second argument to `on` is a Flow — declared with the `flow()` function. It answers _what_: what work is this, and what does it promise about its inputs and outputs?
+
+```typescript
+flow({
+  do: /* the actual code — next */,
+});
+```
+
+Omit the name on tree files — the compiler stamps `unit.export` (e.g. `users.signup`).
+Pass `flow("users.signup", { … })` only for control: barrels, stable names across
+moves, or call-only Flows you `fx.call` by name.
+
+## `do` — the code that actually runs
+
+`do` is a function you write. It answers _how_. It receives two things: `input` (your data) and `fx` (next). Everything your Flow actually does lives here.
+
+```typescript
+do: async (input, fx) => {
+  return { ok: true };
+};
+```
+
+## `fx` — the only door to the outside world
+
+`fx` is the second argument to `do`, and it's the piece the other four exist to protect. The rule is simple and absolute: **your Flow is not allowed to read a database, send an email, check a clock, or touch anything outside itself except through `fx`.**
+
+```typescript
+do: async (input, fx) => {
+  const user = await fx.store(db).insert(users).values(input); // the database, through fx
+  await fx.send(welcomeEmail, { to: user.email }); // another system, through fx
+  return user;
+};
+```
+
+This one rule is what made the Month 8 drift from The Problem avoidable: if `fx` is the only door, retries, auditing, and idempotency stop being separate systems teams build by hand, and become properties of the one boundary everything already passes through.
+
+## Putting the five pieces together
+
+Here is the complete signup flow, with every piece labeled where it sits:
+
+```typescript title="src/flows/users/signup.ts"
+export const signup = on(
+  http.post(), // ← trigger: when (stamped POST /users/signup)
+  flow({
+    // ↑ flow: what (stamped users.signup)
+    do: async (input, fx) => {
+      // ← do: how
+      const user = await fx.store(db).insert(users).values(input); // ← fx: the only way out
+      await fx.send(welcomeEmail, { to: user.email, data: { name: user.name } });
+      return user;
+    },
+  }),
+);
+```
+
+<Callout title="Call-only flows">
+  A `flow(...)` declared without `on(...)` around it is internal — nothing outside your code can
+  start it. Other flows invoke it directly with `fx.call(flowRef, input)`.
+</Callout>
+## Checking it against the timeline
+
+Nothing about the code above looks more complicated than the four lines that started the drift on The Problem — because it isn't. The difference only shows up when the same pressure from that timeline hits it.
+
+Every fork from that timeline was really the same question, asked at a different point: _is this thing that touches the outside world safe to retry, safe to audit, safe to run twice?_ On The Problem, each answer required a new system, because each system had to invent its own answer. Here, the question has one home:
+
+- **The traffic spike from Week 2** doesn't need a queue you build and wire up by hand — running this later, safely, is something you ask of the trigger or the effect itself, not infrastructure you assemble.
+- **The silent failure from Month 2** doesn't need a hand-picked retry count living in a worker nobody remembers the reasoning for. Retries are a property of the `fx` boundary every effect already passes through.
+- **The compliance question from Month 4** doesn't need a `sent_emails` table written by hand from inside a background job. What was sent, and when, is something the system already knows, because nothing was allowed to send anything outside of `fx` in the first place.
+- **The double-submit from Month 6** doesn't need dedup logic split across a queue and a database that never check each other. There's one call, through one door — there's no second path left for a duplicate to sneak through.
+
+None of that required new code beyond what's above. It required the four lines to already be the kind of thing where those questions have a fixed answer, instead of a new one invented per team, per incident.
+
+## Five kinds of trigger
+
+`flow`, `do`, and `fx` never change shape. Only the trigger does — and there are exactly five kinds, one per element that can independently wake a Flow up:
+
+| Trigger                                             | Element | Starts When                      |
+| --------------------------------------------------- | ------- | -------------------------------- |
+| `http.post()` (path from file tree)                 | Flow    | A request arrives                |
+| `clock("name", { every: "10m" })`                   | Clock   | A time interval elapses          |
+| `signal.once("name", {…})` / `.broadcast` / `.live` | Signal  | Another flow announces something |
+| `db.table(users).changed("email")`                  | Store   | A database row changes           |
+| `mcp.tool("name")`                                  | AI      | An AI agent calls it             |
+
+The next section walks through each element in depth — this is just enough to recognize them when you see them.
+
+## Where this goes next
+
+You've seen the problem, the model, the vocabulary, and now the exact anatomy behind every Flow — proven against the timeline that motivated it. The next step is running it yourself: from an empty folder to this exact Flow answering a real request, in one sitting.

package/site/content/docs/understand/the-model.mdx

@@ -0,0 +1,32 @@
+---
+title: "The Model"
+description: "The one rule that removes the disagreement between systems — stated plainly, in two parts."
+icon: "Compass"
+---
+
+## The fix, stated as a rule
+
+Every seam on the last page came from the same root cause: each system involved had its own idea of when it should run and what it was allowed to touch, and nothing forced those ideas to agree with each other.
+
+OKE removes the disagreement by removing the choice. It's one rule, in two parts.
+
+**First: every trigger reduces to the same shape.** An HTTP request, a scheduled tick, a queue message, a database change — whatever wakes the code up, what follows has one identical anatomy: `on(Trigger) → Effects`. Not four systems that happen to look similar. One system, with four ways to wake it up.
+
+**Second: every effect passes through one door.** Nothing is allowed to touch a database, send an email, check a permission, or read the clock on its own — all of it goes through a single surface. Not because that's tidier. Because it's the only way retries, auditing, idempotency, and permission checks stop being infrastructure every team reinvents at the exact moment they get burned by not having it. Build the door once, correctly, and every trigger that walks through it inherits the same guarantees automatically.
+
+That's the whole model. Not a bigger toolbox — a smaller number of things that are allowed to happen at all.
+
+## Why the door has a fixed vocabulary
+
+A door that lets anything through isn't actually closed. So the door recognizes a fixed set of things it's willing to do, and nothing new gets added to that set unless it does something none of the existing ones can. What that set is, and why it stops at eight, is the next page.
+
+## What this project is called
+
+One shape for every trigger, one door for every effect, a fixed vocabulary for what the door allows — that's what this project built. It's called **OKE**.
+
+---
+
+<sub>
+  *OKE isn't an acronym for anything in the code. It comes from Omq Khafi — the organization this
+  engine grew out of — with "Engine" appended: **O**mq **K**hafi **E**ngine.*
+</sub>

package/site/content/docs/understand/the-problem.mdx

@@ -0,0 +1,74 @@
+---
+title: "The Problem"
+description: "Three unrelated features that hit the exact same wall, and the timeline that shows why."
+icon: "TriangleAlert"
+---
+
+## Three features, same wall
+
+**A signup flow.** A user registers. Send them a welcome email. Four lines of code — until traffic spikes, the mail provider starts rate-limiting, and "send an email" quietly needs a queue, a worker, and a retry policy nobody designed on purpose.
+
+**A payment webhook.** A provider confirms a charge. Mark the order paid. Simple — until the provider retries the same webhook twice during a network hiccup, and "mark the order paid" needs to somehow know it already ran.
+
+**A nightly report.** Summarize yesterday's activity and email it to managers. Trivial — until a manager's access gets revoked at 11:58pm and the report that runs at midnight has no idea the permission it checked when the feature was built isn't the permission that holds right now.
+
+Three teams. Three domains. Nobody on any of them talked to the other two. And all three land on the identical fork: **something has to happen later, exactly once, provably — and nothing in the original four lines said what "provably" would end up costing.**
+
+## Follow one all the way through
+
+Take the first one. Just the signup flow, from the day it shipped.
+
+```typescript
+app.post("/signup", async (req, res) => {
+  const user = await db.users.create(req.body);
+  await sendMail(user.email, "Welcome!", welcomeTemplate(user));
+  res.json(user);
+});
+```
+
+It works. It ships. Two weeks later, a launch drives a traffic spike, the mail provider starts returning `429`, and signups start failing because an unrelated email is slow. You move the send off the request path:
+
+```typescript
+app.post("/signup", async (req, res) => {
+  const user = await db.users.create(req.body);
+  emailQueue.add("welcome", { userId: user.id });
+  res.json(user);
+});
+```
+
+The endpoint is fast again. It's also no longer one system — it's an endpoint, a queue, a worker, and a Redis connection nobody else on the team knew existed until a missing `REDIS_URL` broke staging.
+
+From here the same pattern repeats on a longer clock. A support ticket reveals a job failed silently — nobody had configured retries, so you add them, and now a specific number (3? 5? with what backoff?) lives in a file that nobody will remember the reasoning for in six weeks. Compliance asks for proof of every email sent — you add a table written to from inside the worker, and now that worker has two jobs instead of one, quietly capable of disagreeing with itself if the second write fails. Someone double-clicks submit — two jobs enqueue, two emails send, and idempotency becomes a fact that has to live in two systems that were never introduced to each other.
+
+<SixSystemsDrift />
+
+None of these were mistakes. Each one was the correct call, made by a competent engineer, in direct response to something that actually happened. That's what makes the drift invisible while it's happening — there's no bad decision anywhere in this story to point at.
+
+## What's actually going on
+
+Look at what the six resulting files have in common: none of them agree with each other about the same three things. What counts as "done." What happens on failure. Who's allowed to do this at all.
+
+That's the real cost — not the number of tools, but what sits between them:
+
+- **Failure means something different in each one.** A queue retry, an HTTP 500, and a rejected promise from a mail SDK are three unrelated shapes that all happen to mean "this didn't work."
+- **Permission has no fixed address.** It lives wherever whoever wrote that file remembered to put it — which means a reviewer can't point at one place and ask "is this checked?"
+- **Two systems both think they own the same fact.** The database says an order is paid. The already-running webhook handler doesn't know that yet. Nothing keeps them honest with each other in the gap.
+- **Nobody can see the whole thing at once.** There is no file, diagram, or dashboard where "the signup flow" exists as one object — only as the sum of files that happen to call each other.
+
+## If you've been doing this a while
+
+None of the three stories above are hypothetical to you. You've shipped at least one of them — maybe with a different provider, a different table name, a different Slack channel where the incident got triaged. You've sat in the postmortem. You've written the line in the retro doc that says "we should have thought about retries from the start," knowing full well that thinking about it from the start wouldn't have told you which of forty possible failure modes was going to be the one that mattered.
+
+That's not a criticism of your judgment. It's the actual shape of the problem: every decision in that timeline was locally correct and still added a system that doesn't speak the same language as the five before it. You didn't do this wrong. The tools you were given don't leave room to do it any other way.
+
+## If you haven't yet
+
+If your code right now still looks like the four lines from Day 1 — on any feature, in any domain — this is the part that matters most: **you will hit this fork.** Not "might." Every one of the three stories above started as a sentence a product manager could say out loud in one breath. The traffic spike, the silent retry, the compliance question, the double-submit — these aren't edge cases that happen to unlucky teams. They're what happens to any trigger that lives long enough to matter, and right now you simply haven't reached that point in the timeline yet.
+
+The four lines were never wrong. They were just the first data point on a line that already knew where it was going.
+
+## The actual question
+
+Nothing above was avoidable by writing cleaner code inside any single file. The problem was never inside a file — it was that several files had to agree on things none of them were ever designed to agree on.
+
+What would have to be true on day one for month eight to never happen?

package/site/content/docs/understand/the-vocabulary.mdx

@@ -0,0 +1,26 @@
+---
+title: "The Vocabulary"
+description: "The eight things the door recognizes — what each one replaces, and why nothing else made the cut."
+icon: "Boxes"
+---
+
+## What the door recognizes
+
+The door from the last page isn't open-ended — it recognizes a fixed set of things it's willing to do. Each one made the cut because it has _irreducible physics_: behavior that breaks if you tried to fake it using one of the others. A queue's retry and lease semantics aren't a database's job. A secret's rotation lifecycle isn't a config value's job. Where that distinction is real, it gets a name. Where it isn't, it doesn't — which is why the list stops at eight instead of growing indefinitely.
+
+| Element     | What it is           | What it replaces                                                        |
+| ----------- | -------------------- | ----------------------------------------------------------------------- |
+| **Flow**    | Execution & behavior | endpoint, handler, consumer, job, workflow, webhook                     |
+| **Signal**  | Data in motion       | queue, pub/sub, stream, websocket, SSE, event bus                       |
+| **Store**   | Data at rest         | relational database, cache, key-value store, file storage, search index |
+| **Clock**   | Time & schedules     | cron, delay, timeout, durable sleep, TTL                                |
+| **Gate**    | Permission to act    | auth, session, tenancy, RBAC, rate limit, quota                         |
+| **Vault**   | Protected knowledge  | secrets, encryption keys, rotation, environment variables               |
+| **Channel** | Reaching a human     | transactional email, SMS, push notifications, receipts                  |
+| **AI**      | Machine intelligence | model calls, structured prompts, agents, MCP tools                      |
+
+Read the right column as the honest answer to "what would I have reached for before this?" Every item in it is a separate tool with its own configuration, its own failure modes, and its own place to go wrong. The left column is the same ground, covered by something with one shared door and one shared set of guarantees.
+
+## Where this goes next
+
+The next step is breaking down the five pieces behind every Flow — the exact anatomy that connects a trigger to its effects.

package/src/auth/api-keys.ts

@@ -13,6 +13,7 @@ import { parseDurationMs } from "../elements/clock/duration.ts";
 import { assertAttenuated } from "./attenuation.ts";
 import type { AuthPlane } from "./planes.ts";
 import type { ApiKeyRow } from "./tables.ts";
+import { okid } from "../okid.ts";
 
 /** Capability / Manifest resource for `fx.auth` key methods. */
 export const AUTH_API_KEYS_RESOURCE = "auth:api-keys";
@@ -145,7 +146,7 @@ export async function createApiKey(
   assertAttenuated(options.creatorScopes, options.scopes, "api key");
 
   const now = options.now ?? (() => Date.now());
-  const id = options.id ?? crypto.randomUUID();
+  const id = options.id ?? okid();
   const secret = options.secret ?? `oke_${id.replace(/-/g, "")}_${randomSecret()}`;
   const pepper = options.pepper ?? store.pepper ?? DEFAULT_PEPPER;
   const hash = options.hash ?? (await hashApiKeySecret(secret, pepper));