okengine 0.18.5 → 0.19.0

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

@@ -1,328 +0,0 @@
----
-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>

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

@@ -1,114 +0,0 @@
----
-title: Why OKE
-description: The problem of seams across independent backend tools, the insight, and the smaller model.
-source: docs/spec/unified-theory.md
-icon: Compass
----
-
-## The Problem: The Seams You Own
-
-Modern backends accumulate many independently adopted systems: router, queue, cron, websockets, cache, secrets, mailer, AI wrappers, and observability.
-
-<Callout title="A note on the count">
-  'Forty' is a representative illustration of the number of backend concerns developers commonly
-  assemble across modern stacks, not a literal census.
-</Callout>
-
-```text
-many systems → many seams → many contracts → many mental models
-```
-
-Every TypeScript backend works on day one. The bill arrives later in the seams:
-
-- **Cache that lies:** You update a writer, but forget the cache key in checkout.
-- **Secret that fails at 2am:** Deploy boots fine; the first charge fails because the env var was missed.
-- **Permission checks in the wrong place:** Auth logic scattered across handlers instead of verified at the trigger.
-- **The dashboard that doesn't know you:** Observability tools learn routes from traffic samples instead of the compiled model.
-
-## The Insight: One Programming Model
-
-These concerns do not need to become separate programming concepts. They collapse into one closed set:
-
-```text
-Many backend concerns → One programming model
-```
-
-> **One law. Eight elements. One contract.**
-
-## Wrong vs. Right Mental Model
-
-Understanding OKE begins by rejecting the conventional feature-pile model:
-
-| ❌ Wrong Mental Model (Feature Bundle) | ✅ OKEngine Model (Unified Primitives) |
-| -------------------------------------- | -------------------------------------- |
-| Router + Queue + Cron + Auth + ORM     | `on(Trigger) → Flow` (One species)     |
-| Separate mental model per tool         | Eight closed semantic elements         |
-| Ad-hoc side effects everywhere         | Single door to the world: `fx`         |
-| Hand-maintained glue & OpenAPI         | Compiled Manifest contract             |
-| Unchecked runtime drift                | Derived, inspectable surfaces          |
-
-The difference is not how many features OKE has. It is how few concepts you need to understand.
-
-## The Law and the `fx` Rule
-
-Every backend behavior is a Flow:
-
-```typescript
-import { on, flow, http } from "okengine/http";
-
-export const health = on(http.get().public(), flow({ do: () => ({ ok: true }) }));
-```
-
-**All world access goes through `fx`.** A Flow that calls `fetch` directly, imports `node:fs`, or uses `Date.now()` is a defect.
-
-```text
-Flow → fx → observable Effects → Compiler → Manifest → Surfaces
-```
-
-Because all effects pass through `fx`, the compiler infers cache keys, capability matrices, and trace trees without manual annotations.
-
-## One Contract, Many Surfaces
-
-The source of truth is the backend model expressed in code. The **Manifest** is the compiled, versioned contract representing that model.
-
-| Surface                           | Port               | You Maintain?                 |
-| --------------------------------- | ------------------ | ----------------------------- |
-| Typed client (`okengine/client`)  | your app code      | No — derived from Manifest    |
-| Console panels, traces, explorers | `:6533`            | No — reads the Manifest       |
-| MCP for agents                    | `:6535`            | No — reads the Manifest       |
-| Architecture diagram              | Console            | No — it _is_ the effect graph |
-| Capability matrix + cache keys    | compiler / runtime | No — inferred from `fx`       |
-
-Operational surfaces are derived, not separately maintained.
-
-## See the Model Compose
-
-OKE does not add new subsystems when new architectural requirements emerge. The eight closed primitives compose naturally:
-
-- **Realtime:** `Store + Gate + Signal + Flow → Live Query` (Global CDC + RLS re-check + SSE).
-- **Security:** `Gate + Store/RLS + Tenant + fx → Secure execution` (Unified user, operator, and agent boundaries).
-- **Agents:** `MCP + Gate + OAuth + Flow → Agent-accessible backend` (Exposing Flows as MCP tools).
-- **Operations:** `Manifest + Effects + Runs → Inspectable backend` (Wide-event telemetry and live graphs).
-
-> **None of these required a ninth primitive.**
-
-## Core Philosophy
-
-> **Keep the model small. Let the backend grow without growing the mental model.**
-
-Your backend is not just executable. It is inspectable.
-
-## Next Steps
-
-<Cards>
-  <Card
-    title="Introduction"
-    description="The Law, Flow anatomy, and the eight elements."
-    href="/docs/get-started/introduction"
-  />
-  <Card
-    title="Installation"
-    description="Scaffold your first project with create-oke."
-    href="/docs/get-started/installation"
-  />
-</Cards>

package/site/content/docs/recipes/llama-cpp.mdx

@@ -1,151 +0,0 @@
----
-title: "llama.cpp"
-description: "Default local AI image — OpenAI-compatible llama-server, loopback-only publish, pinned build ≥ b8146."
-icon: "Bot"
-source: "docs/spec/unified-theory.md"
----
-
-llama.cpp is the default `images.ai` pin for local inference. It runs
-`llama-server` with an OpenAI-compatible `/v1` API — lightest resource footprint
-for single-user / dev. Driver id stays `openai-compatible`.
-
-<Callout title="The one rule">
-  Pin a verified build ≥ `b8146`, publish only on loopback, and load models only from curated
-  registries (Docker Hub `ai/`) — never arbitrary untrusted GGUF.
-</Callout>
-
-## Quick start
-
-<Steps>
-
-<Step>
-### Pin driver + image
-
-```typescript title="oke.config.ts"
-drivers: {
-  ai: { dev: "openai-compatible", test: "mock", prod: "openai-compatible" },
-},
-images: {
-  ai: "ghcr.io/ggml-org/llama.cpp:server-b10450", // never :latest
-},
-```
-
-Or `oke ai setup --provider llama-cpp` (TTY: banner → Ultra Fast / Fast /
-Balanced / Smart → up to 20 curated Docker Hub `ai/` picks per tier) / `--yes`
-for `granite3.3:2b`.
-
-</Step>
-
-<Step>
-### Env written by the stack
-
-```bash title=".env.local"
-OKE_AI_URL=http://127.0.0.1:8080/v1
-OKE_AI_MODEL=granite3.3:2b
-```
-
-`OKE_AI_MODEL` is a Docker Hub `ai/<id>` model. The recipe writes
-`.oke/llama-entrypoint.py` (generated, gitignored), Hub-pulls into the cache
-volume, then starts `llama-server -m <gguf> --alias <id>` (single-model).
-
-Never set `LLAMA_ARG_MODELS_PRESET` / `LLAMA_ARG_DOCKER_REPO` — those hang on
-b10290+. `oke dev` shows the model id and polls `/v1/models` until `ready`
-(first boot may take minutes).
-
-</Step>
-
-<Step>
-### Ask through the OpenAI-compatible driver
-
-```typescript
-import { ai } from "okengine";
-
-export const smart = ai.model("smart", {
-  provider: "openai-compatible",
-  model: process.env.OKE_AI_MODEL ?? "granite3.3:2b",
-});
-```
-
-</Step>
-
-</Steps>
-
-## Security (hard requirements)
-
-| Control              | Requirement                                                                  |
-| -------------------- | ---------------------------------------------------------------------------- |
-| Host publish         | `127.0.0.1:8080:8080` only — never `0.0.0.0`                                 |
-| Image pin            | Explicit build ≥ **b8146** (CVE-2026-27940 / CVE-2026-33298); never `latest` |
-| Model source         | Docker Hub [`ai/`](https://hub.docker.com/u/ai) namespace (or known HF GGUF) |
-| Untrusted GGUF       | **Forbidden** — crafted files can RCE the parser on unpatched builds         |
-| RPC / extra backends | Not published — OpenAI HTTP only                                             |
-
-Inside the container the server listens on `0.0.0.0` so the Compose network and
-loopback map work. The **host** bind is loopback — same isolation idea as
-Postgres/Redis, stricter on the published interface because of GGUF CVE risk.
-
-## Required env
-
-| Variable       | Required?         | Meaning                                       |
-| -------------- | ----------------- | --------------------------------------------- |
-| `OKE_AI_URL`   | **Yes** in docker | Base URL including `/v1`                      |
-| `OKE_AI_MODEL` | Recommended       | Docker Hub `ai/` id (default `granite3.3:2b`) |
-
-## What the recipe configures
-
-| Field          | Value                                                        |
-| -------------- | ------------------------------------------------------------ |
-| Container port | `8080`                                                       |
-| Host publish   | `127.0.0.1:8080:8080`                                        |
-| Healthcheck    | `GET /health`, every 5s, 24 retries, 900s start              |
-| Connection URL | `http://host:8080/v1`                                        |
-| Model load     | `.oke/llama-entrypoint.py` → Hub pull (incl. CNCF) then `-m` |
-
-## When to choose something else
-
-| Workload                                   | Prefer                                  |
-| ------------------------------------------ | --------------------------------------- |
-| Single-user / dev, lightest footprint      | **llama.cpp** (this recipe)             |
-| Local DX with library pull UX              | [Ollama](/docs/recipes/ollama)          |
-| Multi-user / production concurrency on GPU | [vLLM](/docs/recipes/vllm)              |
-| Structured / agent workloads on GPU        | [SGLang](/docs/recipes/sglang)          |
-| Managed cloud                              | Anthropic / OpenAI / … (no `images.ai`) |
-
-## Troubleshooting
-
-<Accordions>
-<Accordion title="Connection refused on :8080">
-
-Confirm compose published `127.0.0.1:8080:8080` (not bare `8080:8080` on all
-interfaces). `OKE_AI_URL` must include `/v1`.
-
-</Accordion>
-<Accordion title="Model fails to load / slow first boot">
-
-First start Hub-pulls the curated `ai/` model into the named cache volume
-(see logs: `oke ai: ensuring…` / download %). Prefer `oke ai setup` tiers
-(Ultra Fast → `granite3.3:2b`) for smoke tests.
-
-Confirm `OKE_AI_MODEL` in `.env.local`. Watch `oke
-dev` until AI status is `ready`.
-
-If status stays `loading` on Compose that still uses `--models-preset`,
-regenerate `docker/` and recreate AI. Never mount random GGUF or set
-`LLAMA_ARG_MODELS_PRESET` / `LLAMA_ARG_DOCKER_REPO`.
-
-</Accordion>
-</Accordions>
-
-## Learn more
-
-- [AI](/docs/elements/ai) — `fx.ask`, prompts, drivers
-- [Ollama](/docs/recipes/ollama) — fully supported alternative
-- [Environment variables](/docs/reference/environment-variables) — `OKE_AI_*`
-
-## Next
-
-<Cards>
-  <Card title="Ollama" description="Library UX alternative." href="/docs/recipes/ollama" />
-  <Card title="vLLM" description="Production GPU serving." href="/docs/recipes/vllm" />
-  <Card title="AI" description="Prompts, models, guardrails." href="/docs/elements/ai" />
-</Cards>