okengine 0.17.2 → 0.18.3

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

@@ -173,8 +173,8 @@ A value already in the vault / managed backend wins over a leftover env pin.
 If every layer misses a contract, boot **fails** before any request is served:
 
 ```text
-VaultBootError: 1 secret(s) missing:
-  STRIPE_KEY — Payments gateway key
+vault boot failed — 1 missing secret(s):
+  - STRIPE_KEY: Payments gateway key
 ```
 
 <Callout title="Good to know">
@@ -242,9 +242,9 @@ Backup stays on the CLI (`oke vault backup` / `restore`). The Console never
 accepts a master key in the HTTP body — unseal via `OKE_VAULT_MASTER_KEY`.
 
 <Callout title="Builtin concurrency (rotate / audit / backup)">
-  `rotate-master` uses SKIP LOCKED + lease TTL (one holder; crashed holders reclaim). Audit appends
-  under a transactional row lock. Backups use temp → fsync → rename with end marker + checksum —
-  restore rejects incomplete files before decrypt.
+  `rotate-master` holds a lease (`FOR UPDATE` + lease TTL) so exactly one batch runs at a time; a
+  busy audit append briefly waits rather than being misread as "lease held". Audit appends serialize
+  under a transactional write lock; backups use temp → fsync → rename with end marker + checksum.
 </Callout>
 
 <Callout title="Builtin master keys and expired rows">

package/site/content/docs/get-started/installation.mdx

@@ -146,7 +146,7 @@ Uncommented supported controls in the generated compose env are preserved when
 `oke dev` regenerates the file.
 
 Migrating from `local` / `docker` maps or `oke mode`?
-See [Migrating environments](/docs/reference/migrating-environments).
+Rename the env keys in `oke.config.ts` to `dev` / `test` / `prod`.
 
 ## Troubleshooting
 
@@ -198,7 +198,6 @@ See [Migrating environments](/docs/reference/migrating-environments).
 - [CLI Reference](/docs/reference/cli) — `oke`, `create-oke`, `oke test`, and db commands
 - [Environment variables](/docs/reference/environment-variables) — protocol-shaped env
 - [Configuration](/docs/reference/configuration) — `oke.config.ts` drivers and `db.autoPush`
-- [Migrating environments](/docs/reference/migrating-environments) — four-key maps → three
 
 ## Next
 

package/site/content/docs/get-started/introduction.mdx

@@ -5,25 +5,20 @@ source: docs/spec/unified-theory.md
 icon: BookOpen
 ---
 
-A booking API, a nightly cleanup job, a receipt email, a row-change hook — in
-most stacks those are four frameworks. In OKE they are **one species** with one
-shape. Learn the shape once; only the trigger changes.
+## The One Idea
 
-<Callout title="The one rule">
-  **Every backend behavior is a Flow:** `on(Trigger) → Effects`. There are no separate species
-  called endpoints, handlers, consumers, jobs, or workflows.
-</Callout>
+A booking API, a nightly cleanup job, a receipt email, a row-change hook — in most stacks those are four frameworks. In OKE they are **one species** with one shape. Learn the shape once; only the trigger changes.
 
-## Quick start
+> **The one rule**
+> Every backend behavior is a **Flow**: `on(Trigger) → Effects`. There are no separate species called endpoints, handlers, consumers, jobs, or workflows.
 
-<Steps>
+## Quick Start
 
-<Step>
-### Write one Flow
+### Write One Flow
 
 Four contracts plus a `do`. This is the standard starter's health check:
 
-```typescript title="flows/main/health.ts"
+```typescript
 import { on, flow, http } from "okengine";
 import { z } from "zod";
 
@@ -38,45 +33,29 @@ export const health = on(
 
 `main` omits the URL prefix, so this file is `GET /health` named `main.health`. See [Project structure](/docs/get-started/project-structure). Explicit `http.get("/health")` and `flow("main.health")` still win.
 
-</Step>
+### Change Only the Trigger
 
-<Step>
-### Change only the trigger
+Triggers define what starts the flow. Changing the trigger replaces the entire behavior while keeping the same structure:
 
 | Trigger                            | Starts when        | Replaces           |
 | ---------------------------------- | ------------------ | ------------------ |
-| `http.post("/bookings")`           | a request arrives  | endpoint · handler |
-| `every("10m")`                     | time passes        | cron job           |
-| `orderPlaced` (a signal)           | another flow emits | queue consumer     |
-| `db.table(users).changed("email")` | a row changes      | CDC pipeline       |
+| `http.post("/bookings")`           | A request arrives  | Endpoint · handler |
+| `every("10m")`                     | Time passes        | Cron job           |
+| `orderPlaced` (a signal)           | Another flow emits | Queue consumer     |
+| `db.table(users).changed("email")` | A row changes      | CDC pipeline       |
+
+```typescript
+import { on, flow, http } from "okengine";
 
-```typescript title="triggers"
 on(http.post("/bookings"), createBooking);
 on(every("10m"), expireStale);
 on(orderPlaced, sendReceipt);
 on(db.table(users).changed("email"), reverify);
 ```
 
-</Step>
-
-<Step>
-### See what was derived
-
-Run `oke dev`. Four surfaces come up together — nothing configured by hand in
-a separate dashboard.
-
-<Surfaces />
-
-</Step>
-
-</Steps>
-
 ## Anatomy
 
-One pipeline. Only the trigger changes between an endpoint, a job, a consumer,
-and a row hook.
-
-<FlowShape />
+One pipeline. Only the trigger changes between an endpoint, a job, a consumer, and a row hook.
 
 | Piece         | Role                                                           |
 | ------------- | -------------------------------------------------------------- |
@@ -85,33 +64,25 @@ and a row hook.
 | **`do`**      | The body — every read, write, emit, and call goes through `fx` |
 | **Effects**   | Inferred from those `fx` calls — not hand-annotated            |
 
-| Consequence                        | Follows from   |
-| ---------------------------------- | -------------- |
-| One documentation path             | One species    |
-| One trace shape                    | One Flow model |
-| One thing for an AI agent to learn | One law        |
-
-## The `fx` rule
+Consequence: One documentation path, one trace shape, one Flow model, one thing for an AI agent to learn.
 
-**All world access goes through `fx`.** A Flow that imports `node:fs`, calls
-`fetch` directly, or uses `Date.now()` is a defect.
+## The `fx` Rule
 
-| Inferred from `fx` touches | Without hand annotations |
-| -------------------------- | ------------------------ |
-| Cache invalidation keys    | Yes                      |
-| Live queries               | Yes                      |
-| Least-privilege tokens     | Yes                      |
-| Deterministic tests        | Yes                      |
-| Manifest Diff              | Yes                      |
+**All world access goes through `fx`.** A Flow that imports `node:fs`, calls `fetch` directly, or uses `Date.now()` is a defect.
 
-## What the Manifest derives
+| Inferred From           | With `fx` |
+| ----------------------- | --------- |
+| Cache invalidation keys | Yes       |
+| Live queries            | Yes       |
+| Least-privilege tokens  | Yes       |
+| Deterministic tests     | Yes       |
+| Manifest Diff           | Yes       |
 
-At build time OKE extracts a **Manifest** — a machine-readable description of
-your system. You do not maintain a second source of truth.
+## What the Manifest Derives
 
-<ManifestPipeline />
+At build time OKE extracts a **Manifest** — a machine-readable description of your system. You do not maintain a second source of truth.
 
-| Surface                           | Port / place       | You maintain?                 |
+| Surface                           | Port / Place       | You Maintain?                 |
 | --------------------------------- | ------------------ | ----------------------------- |
 | Typed client (`okengine/client`)  | your app code      | No separate codegen           |
 | Console panels, traces, explorers | `:6533`            | No                            |
@@ -119,47 +90,38 @@ your system. You do not maintain a second source of truth.
 | Architecture diagram              | Console            | No — it _is_ the effect graph |
 | Capability matrix + cache keys    | compiler / runtime | No — from `fx`                |
 
-## Eight elements
+## The Eight Elements
 
-An element earns its place only if it has **irreducible physics**. New
-infrastructure becomes a new **driver** — never a ninth element.
+An element earns its place only if it has **irreducible physics**. New infrastructure becomes a new **driver** — never a ninth element.
 
-<Features />
-
-| Element     | Essence                       | Replaces the zoo of                                       |
+| Element     | Essence                       | Replaces the Zoo                                          |
 | ----------- | ----------------------------- | --------------------------------------------------------- |
-| **Flow**    | behavior                      | endpoint · handler · consumer · job · workflow · webhook  |
-| **Signal**  | data in motion                | queue · pub/sub · stream · websocket · SSE · event bus    |
-| **Store**   | data at rest                  | database · cache · KV · file storage · search index       |
-| **Clock**   | time                          | cron · delay · timeout · durable sleep · TTL              |
-| **Gate**    | permission to act             | auth · session · ABAC · rate limit · quota · feature flag |
-| **Vault**   | protected knowledge           | secrets · config · environment                            |
-| **Channel** | reaching humans               | email · SMS · WhatsApp · push                             |
-| **AI**      | reaching machine intelligence | model calls · prompts · embeddings · agents · RAG         |
+| **Flow**    | Behavior                      | endpoint · handler · consumer · job · workflow · webhook  |
+| **Signal**  | Data in motion                | queue · pub/sub · stream · websocket · SSE · event bus    |
+| **Store**   | Data at rest                  | database · cache · KV · file storage · search index       |
+| **Clock**   | Time                          | cron · delay · timeout · durable sleep · TTL              |
+| **Gate**    | Permission to act             | auth · session · ABAC · rate limit · quota · feature flag |
+| **Vault**   | Protected knowledge           | secrets · config · environment                            |
+| **Channel** | Reaching humans               | email · SMS · WhatsApp · push                             |
+| **AI**      | Reaching machine intelligence | model calls · prompts · embeddings · agents · RAG         |
 
-## Ten exports
+## Ten Exports
 
-The entire public vocabulary fits in one import. Everything else in the docs is
-derived from these ten names:
+The entire public vocabulary fits in one import. Everything else in the docs is derived from these ten names:
 
-```ts title="okengine"
+```ts
 import { on, flow, signal, store, clock, gate, vault, channel, ai, plugin } from "okengine";
 ```
 
-For HTTP-only apps, prefer the slim entry so the cold graph stays on the edge
-router:
+For HTTP-only apps, prefer the slim entry so the cold graph stays on the edge:
 
-```ts title="okengine/http"
+```ts
 import { on, flow, http, gate, oke, createBunRuntime } from "okengine/http";
 ```
 
-Heavy surfaces (`runs`, journal factories, compiler extract, the legacy
-mega-barrel) live on `okengine/runs`, `okengine/journal`, `okengine/compiler`,
-and `okengine/full`.
-
-<Vocabulary />
+Heavy surfaces (runs, journal factories, compiler extract, the legacy mega-barrel) live on `okengine/runs`, `okengine/journal`, `okengine/compiler`, and `okengine/full`.
 
-## Learn more
+## Learn More
 
 | Topic   | Page                                                                            |
 | ------- | ------------------------------------------------------------------------------- |
@@ -169,27 +131,9 @@ and `okengine/full`.
 | `fx`    | [fx](/docs/reference/fx)                                                        |
 | Agents  | [MCP](/docs/ai/mcp) · [Skills](/docs/ai/skills) · [llms.txt](/docs/ai/llms-txt) |
 
-## Next
-
-<Cards>
-  <Card
-    title="Why OKE"
-    description="Traditional backend pain — and what Manifest derivation closes."
-    href="/docs/get-started/why"
-  />
-  <Card
-    title="Installation"
-    description="Scaffold with create-oke and open the Console."
-    href="/docs/get-started/installation"
-  />
-  <Card
-    title="Basic Usage"
-    description="Health Flow, typed client, and bun:test."
-    href="/docs/get-started/basic-usage"
-  />
-  <Card
-    title="Project structure"
-    description="Folders are the URL; unit plus export is the name."
-    href="/docs/get-started/project-structure"
-  />
-</Cards>
+## Next Steps
+
+- [Why OKE](/docs/get-started/why)
+- [Installation](/docs/get-started/installation)
+- [Basic Usage](/docs/get-started/basic-usage)
+- [Project Structure](/docs/get-started/project-structure)

package/site/content/docs/get-started/meta.json

@@ -1,5 +1,13 @@
 {
   "title": "Get Started",
   "icon": "Rocket",
-  "pages": ["index", "introduction", "why", "installation", "basic-usage", "project-structure"]
+  "pages": [
+    "index",
+    "introduction",
+    "why",
+    "installation",
+    "basic-usage",
+    "testing",
+    "project-structure"
+  ]
 }

package/site/content/docs/get-started/testing.mdx

@@ -0,0 +1,328 @@
+---
+title: Testing
+description: Write deterministic tests for your Flows with createTestApp — freeze the clock, mock AI, drain signals, and prove side effects.
+icon: FlaskConical
+---
+
+`createTestApp` boots the **same app** you deploy, but with memory drivers and a
+frozen clock. You drive it through `t.api`, `t.auth`, `t.signals`, `t.clock`,
+and `t.channels` — every assertion is deterministic.
+
+<Callout title="The one rule">
+  Boot the same `app` your server boots. Assert only through the harness surfaces (`t.api`,
+  `t.auth`, `t.signals`, `t.clock`, `t.channels`, `t.ai`, `t.effects`) — never reach into internal
+  runtimes.
+</Callout>
+
+## Import
+
+The harness ships as a separate subpath so production bundles stay small:
+
+```typescript title="tests/orders.test.ts"
+import { describe, expect, test } from "bun:test";
+import { createTestApp } from "okengine/testing"; // or "okengine/test"
+import { app } from "../src/app";
+
+test("orders flow", async () => {
+  const t = await createTestApp(app);
+  // ...
+  await t.close();
+});
+```
+
+Both `okengine/testing` and `okengine/test` are aliases. Use `okengine/testing`
+(→ `dist/testing.js`) for published packages and hoisted monorepos; `okengine/test`
+is the source-only path older starters use.
+
+## Quick start
+
+<Steps>
+
+<Step>
+### Adopt your Flows
+
+Every behavior on the app is reachable. No separate test database or server.
+
+```typescript title="src/flows/orders/index.ts"
+import { on, flow, http } from "okengine";
+import { z } from "zod";
+
+export const create = on(
+  http.post("/orders").gate(member),
+  flow("orders.create", {
+    in: z.object({ sku: z.string(), qty: z.number() }),
+    out: z.object({ id: z.string() }),
+    do: async (input, fx) => {
+      const id = fx.id();
+      await fx.emit(orderPlaced, { orderId: id, ...input });
+      return { id };
+    },
+  }),
+);
+```
+
+</Step>
+
+<Step>
+### Boot the harness
+
+```typescript title="tests/orders.test.ts"
+const t = await createTestApp(app, { gates: [member] });
+```
+
+</Step>
+
+<Step>
+### Login and call
+
+```typescript
+const u = await t.auth.loginAs({ scopes: ["order:create"] });
+const { data, error } = await t.api.orders.create({ sku: "COFFEE", qty: 2 }, { as: u });
+expect(error).toBeNull();
+expect(data).toEqual({ id: expect.any(String) });
+```
+
+</Step>
+
+<Step>
+### Advance time and drain signals
+
+Signal handlers and Clocks are processed deterministically:
+
+```typescript
+await t.signals.drain(); // run queued signal work
+await t.clock.advance("2m"); // tick scheduled Clocks forward
+expect(t.channels.sent()).toContainEqual(expect.objectContaining({ template: "order-confirmed" }));
+```
+
+</Step>
+
+</Steps>
+
+## Harness surface
+
+| Property                                    | What it does                                                                           |
+| ------------------------------------------- | -------------------------------------------------------------------------------------- |
+| `t.api.<unit>.<flow>(input, opts?)`         | Invoke an adopted Flow directly with a `{ as }` principal and optional `{ tenant }`    |
+| `t.auth.loginAs(options)`                   | Returns a verified `TestUser` with `id`, `scopes`, `verified`, and optional `tenantId` |
+| `t.clock.advance(by)` / `t.clock.now()`     | Freeze and move the harness clock (used by durable sleeps and Clocks)                  |
+| `t.cron.run(name)`                          | Run a named Clock / `every()` interval now, still leader-elected                       |
+| `t.signals.drain()`                         | Drain the signal bus until idle (deterministic queued work)                            |
+| `t.signals.subscribeLive(signal, handlers)` | Subscribe to a `delivery: "live"` signal's event stream (deterministic)                |
+| `t.signals.waitForLive(signal, predicate)`  | Resolve once a live event matching `predicate` arrives                                 |
+| `t.channels.sent()`                         | Receipts / inbox entries sent during the test                                          |
+| `t.ai.mock(prompt, output)`                 | Register a canned mock response for a Prompt                                           |
+| `t.ai.cost()`                               | Accumulated AI cost across `fx.ask` calls                                              |
+| `t.effects.of(runId)`                       | Effect ledger for a recorded run (reads / writes / emits / sends)                      |
+| `t.runs()`                                  | All wide events recorded during the test                                               |
+| `t.close()`                                 | Close booted element runtimes                                                          |
+
+## Multi-tenancy & RLS
+
+With `gate.auth: { tenant: true }` you can test tenant isolation with real
+row-level security.
+
+```typescript title="src/db/documents.ts"
+import { store, field } from "okengine";
+
+export const documents = store.schema.table(
+  "documents",
+  {
+    id: field.text().primaryKey(),
+    tenant_id: field.text().notNull(),
+    title: field.text().notNull(),
+  },
+  [store.schema.policy.tenant("tenant_id", { for: "all" })],
+);
+```
+
+Give each test user a tenant, and drive distinct tenants against the same
+
+Flow:
+
+```typescript title="tests/tenant.test.ts"
+const t = await createTestApp(app, {
+  gates: [member],
+  boot: { config: { drivers: { store: { sql: { test: "pglite" } } } } },
+});
+
+const alice = await t.auth.loginAs({ id: "alice", tenantId: "acme" });
+const bob = await t.auth.loginAs({ id: "bob", tenantId: "globex" });
+
+await t.api.docs.create({ title: "Acme Roadmap" }, { as: alice });
+await t.api.docs.create({ title: "Globex Secrets" }, { as: bob });
+
+const acmeDocs = await t.api.docs.list(undefined, { as: alice });
+expect(acmeDocs.data).toHaveLength(1); // only Acme Roadmap
+```
+
+Re-scope a single call to another tenant with `{ tenant }`, independent of the
+principal's own tenant:
+
+```typescript
+const carol = await t.auth.loginAs({ id: "carol", tenantId: "acme" });
+const { data } = await t.api.docs.create(
+  { title: "Globex Carol" },
+  { as: carol, tenant: "globex" },
+);
+expect(data.tenantId).toBe("globex");
+```
+
+RLS policies are row-level: tenant-scoped tables need `store.schema.policy.tenant`
+(or `store.schema.unscoped()` for genuinely global tables). Harness boots do not
+run migrations — in a real app `oke db push` installs those policies.
+
+## Deterministic live signals
+
+Signals with `delivery: "live"` back client feeds and SSE streams. The harness
+exposes the retained event stream so you can assert both sides deterministically:
+
+```typescript title="tests/live.test.ts"
+const orderStatus = signal("order-status", {
+  delivery: "live",
+  retention: { maxCount: 10 },
+});
+
+on(
+  http.post("/orders/status").public(),
+  flow("orders.updateStatus", {
+    in: z.object({ orderId: z.string(), status: z.string() }),
+    effects: { emits: ["order-status"] },
+    do: async (input, fx) => {
+      await fx.emit(orderStatus, input);
+      return { ok: true };
+    },
+  }),
+);
+```
+
+```typescript
+const seen: Array<{ orderId: string; status: string }> = [];
+
+const unsubscribe = t.signals.subscribeLive(orderStatus, {
+  onEvent: (event) => seen.push(event),
+});
+
+await t.api.orders.updateStatus({ orderId: "o1", status: "placed" });
+await t.signals.drain();
+expect(seen.map((e) => e.status)).toEqual(["placed"]);
+
+// Resolve a promise the moment a matching event arrives.
+const deliveredPromise = t.signals.waitForLive(
+  orderStatus,
+  (event) => event.status === "delivered",
+);
+await t.api.orders.updateStatus({ orderId: "o1", status: "delivered" });
+await t.signals.drain();
+const delivered = await deliveredPromise;
+expect(delivered.status).toBe("delivered");
+
+unsubscribe(); // no further events observed
+```
+
+Call `t.signals.drain()` after each emit — live events are staged until the bus
+drains. `retention` caps the replayed tape (`maxCount` / `maxAge`); it is only
+valid on `delivery: "live"` signals.
+
+## Time travel
+
+`t.clock` freezes time. `t.clock.advance("2m")` moves the clock forward and
+resumes any durable sleeps that become due. `t.cron.run("expire-stale")` runs a
+named Clock now:
+
+```typescript
+await t.clock.advance("30s"); // durable sleeps resume
+await t.cron.run("expire-stale"); // named Clock fires
+expect(t.channels.sent()).toHaveLength(1); // side effect observed
+```
+
+## AI & channels
+
+`fx.ask` routes to a mock driver. Register canned outputs and read accumulated
+cost:
+
+```typescript
+t.ai.mock(summarizePrompt, { title: "Mock summary" });
+const { data } = await t.api.posts.summarize({ postId: "p_1" }, { as: u });
+expect(data).toEqual({ title: "Mock summary" });
+expect(t.ai.cost()).toBe(0);
+```
+
+Channels write to an inbox instead of a transport:
+
+```typescript
+expect(t.channels.sent()).toContainEqual(
+  expect.objectContaining({ template: "order-confirmed", to: u.id }),
+);
+```
+
+## Troubleshooting
+
+<Accordions>
+
+<Accordion title="createTestApp fails to boot — missing secrets or stores">
+  The starter patches test drivers and fallback secrets on the app options. If
+  your `oke({ ... })` references a Vault secret or Store that the template does
+  not define, pass them explicitly:
+
+```typescript
+await createTestApp(app, {
+  secrets: [openAiKey],
+  vaultSecrets: { OPENAI_KEY: "sk-test" },
+});
+```
+
+</Accordion>
+
+<Accordion title="My live subscription never receives events">
+  - Live events are staged until `t.signals.drain()` — await `drain()` after
+    every emitting call.
+  - Register `subscribeLive` / `waitForLive` **before** you emit.
+  - A signal with a schema drops violating emits — assert `res.error`.
+
+</Accordion>
+
+<Accordion title="Cross-tenant reads return a stale cached row">
+  Tier-1 read caching keys by flow, input, and user id — tenant is a row-level
+  RLS scope, not a cache dimension. For reads under a `{ tenant }` override, use
+  a distinct call principal (or write first) so the cache key differs.
+
+</Accordion>
+
+<Accordion title="PGlite RLS policies aren't applied in the harness">
+  Test boots never run migrations — `oke db push` installs DDL and
+  `store.schema.policy.tenant` policies in real apps.
+
+Assert real RLS by installing the policy + `oke.*` helpers on the booted
+primary connection (as the repo's `sql-rls-isolation.test.ts` does).
+
+</Accordion>
+
+</Accordions>
+
+## Learn more
+
+- [Flow](/docs/elements/flow) — triggers, contracts, effects, and composition
+- [Store](/docs/elements/store) — SQL, KV, files, index, and RLS policies
+- [Signal](/docs/elements/signal) — delivery physics, retention, and live feeds
+- [Client](/docs/reference/client) — the typed client for real HTTP calls
+
+## Next
+
+<Cards>
+  <Card
+    title="Project structure"
+    description="Folders are the URL; unit plus export is the name."
+    href="/docs/get-started/project-structure"
+  />
+  <Card
+    title="Flow"
+    description="Triggers, contracts, effects, and composition."
+    href="/docs/elements/flow"
+  />
+  <Card
+    title="Signal"
+    description="Delivery physics, retention, and deterministic live feeds."
+    href="/docs/elements/signal"
+  />
+</Cards>