okengine 0.2.8 → 0.3.2

package/site/content/docs/console/clock.mdx

@@ -0,0 +1,31 @@
+---
+title: "Clock"
+description: "Upcoming crons, sleeping durable flows, journal."
+icon: "Clock"
+source: "docs/spec/console.md"
+---
+
+Answers: **upcoming crons, sleeping durable flows, journal**
+
+<Callout title="Governing rule">
+  Looks like time — a forward timeline for schedules and pending wakes, not a flat grid.
+</Callout>
+
+## What this panel shows
+
+<Cards>
+  <Card
+    title="Schedules"
+    description="Recurring crons with drift, overdue, catch-up, lease holder."
+  />
+  <Card title="Pending wakes" description="Every sleeping durable flow and when it wakes." />
+  <Card title="DST warnings" description="Only when the schedule falls in an ambiguous window." />
+  <Card title="Actions" description="Run now, wake early, pause, edit when overridable." />
+</Cards>
+
+## Catalog
+
+<Cards>
+  <Card title="Dev" description="full" />
+  <Card title="Prod" description="trigger/pause; edit if `overridable`" />
+</Cards>

package/site/content/docs/console/flows.mdx

@@ -0,0 +1,31 @@
+---
+title: "Flows"
+description: "What exists; call it; read its contract."
+icon: "GitBranch"
+source: "docs/spec/console.md"
+---
+
+Answers: **what exists; call it; read its contract**
+
+<Callout title="Governing rule">
+  Renders the one law as three columns: `Causes ← Flows → Effects` — not a tree.
+</Callout>
+
+## What this panel shows
+
+<Cards>
+  <Card title="Causes column" description="Triggers and callers — what runs this." />
+  <Card title="Flows column" description="Context-adaptive centre with contracts and invoke." />
+  <Card title="Effects column" description="What changes — store, signal, channel, AI, vault." />
+  <Card
+    title="Flow drawer"
+    description="Workshop peek/expand — save as bun:test from a real response."
+  />
+</Cards>
+
+## Catalog
+
+<Cards>
+  <Card title="Dev" description="full + source links" />
+  <Card title="Prod" description="read + invoke per gates" />
+</Cards>

package/site/content/docs/console/gates.mdx

@@ -0,0 +1,35 @@
+---
+title: "Gates"
+description: "Permission matrix, rate counters, MFA map."
+icon: "Shield"
+source: "docs/spec/console.md"
+---
+
+Answers: **permission matrix, rate counters, MFA map**
+
+<Callout title="Governing rule">
+  Refuse the giant roles×permissions matrix as the entry point — inquire from principal or from
+  flow.
+</Callout>
+
+## What this panel shows
+
+<Cards>
+  <Card title="Simulator" description="Gate chain in evaluation order — where a 403 stopped." />
+  <Card
+    title="Unguarded flows"
+    description="Continuous audit: public user-plane flows after deploy."
+  />
+  <Card title="Deploy diff" description="Permission widening caught from Manifest Diff." />
+  <Card
+    title="Plane separation"
+    description="Operator holding an application scope is a violation."
+  />
+</Cards>
+
+## Catalog
+
+<Cards>
+  <Card title="Dev" description="full" />
+  <Card title="Prod" description="limits if `overridable`" />
+</Cards>

package/site/content/docs/console/manifest-diff.mdx

@@ -0,0 +1,34 @@
+---
+title: "Manifest Diff"
+description: "Blast radius of a deploy: new effects, widened permissions."
+icon: "Diff"
+source: "docs/spec/console.md"
+---
+
+Answers: **blast radius of a deploy: new effects, widened permissions**
+
+<Callout title="Governing rule">
+  Compares meaning rather than lines — behaviour change, sorted by blast radius.
+</Callout>
+
+## What this panel shows
+
+<Cards>
+  <Card title="Contract breaking" description="Existing clients will fail." />
+  <Card
+    title="Permission widening"
+    description="Attack surface grew — gate removed or scope widened."
+  />
+  <Card title="Effect widening" description="New write, external effect, or secret read." />
+  <Card
+    title="CI gate"
+    description="Blocks undeclared breaks; intended breaks need `breaking: true`."
+  />
+</Cards>
+
+## Catalog
+
+<Cards>
+  <Card title="Dev" description="✓" />
+  <Card title="Prod" description="✓" />
+</Cards>

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

@@ -0,0 +1,23 @@
+{
+  "title": "Console",
+  "icon": "LayoutDashboard",
+  "pages": [
+    "overview",
+    "flows",
+    "signals",
+    "store",
+    "clock",
+    "gates",
+    "vault",
+    "channels",
+    "ai",
+    "architecture",
+    "traces",
+    "runs",
+    "manifest-diff",
+    "access",
+    "plugins",
+    "privacy",
+    "tenancy"
+  ]
+}

package/site/content/docs/console/overview.mdx

@@ -0,0 +1,40 @@
+---
+title: "Overview"
+description: "Is the system healthy right now?"
+icon: "Activity"
+source: "docs/spec/console.md"
+---
+
+Answers: **is the system healthy right now?**
+
+<Callout title="Governing rule">
+  Built on declared objectives — burn rate and ranked findings, not a wall of charts nobody reads.
+</Callout>
+
+## What this panel shows
+
+<Cards>
+  <Card
+    title="Declared SLOs"
+    description="Objectives enter the Manifest; lowering a target is a reviewable code change."
+  />
+  <Card
+    title="Burn rate"
+    description="Error rate over tolerable rate — pages and investigates with clear thresholds."
+  />
+  <Card
+    title="Journeys"
+    description="Causal paths, not service lists — impossible compositions rejected at compile."
+  />
+  <Card
+    title="Ranked findings"
+    description="Union of panel findings: user harm first, then irreversibility, then trend."
+  />
+</Cards>
+
+## Catalog
+
+<Cards>
+  <Card title="Dev" description="✓" />
+  <Card title="Prod" description="✓" />
+</Cards>

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

@@ -0,0 +1,41 @@
+---
+title: "Plugins"
+description: "Installed plugins and their contributed panels."
+icon: "Puzzle"
+source: "docs/spec/console.md"
+---
+
+Answers: **installed plugins and their contributed panels**
+
+<Callout title="Governing rule">
+  Scope is the attachment point — `app.plug()` / `unit.plug()` / `flow.plug()`. The Console never
+  installs anything.
+</Callout>
+
+## What this panel shows
+
+<Cards>
+  <Card
+    title="Origin × state"
+    description="Core / Local / Community; state derived from code, not a flag."
+  />
+  <Card
+    title="Declares vs intercepts"
+    description="Boot contributions vs per-request hooks with measured cost."
+  />
+  <Card
+    title="Supply chain"
+    description="No lifecycle scripts; capability widening hits Manifest Diff."
+  />
+  <Card
+    title="Install path"
+    description="Shows state and hands you the command — no browser install."
+  />
+</Cards>
+
+## Catalog
+
+<Cards>
+  <Card title="Dev" description="✓" />
+  <Card title="Prod" description="✓" />
+</Cards>

package/site/content/docs/console/privacy.mdx

@@ -0,0 +1,32 @@
+---
+title: "Privacy"
+description: "Where PII lives, who touches it, export/erase (conditional)."
+icon: "EyeOff"
+source: "docs/spec/console.md"
+---
+
+Answers: **where PII lives, who touches it, export/erase**
+
+<Callout title="Governing rule">
+  Conditional panel — appears when the privacy plugin is plugged. Catalog row is the durable
+  reference.
+</Callout>
+
+## What this panel shows
+
+<Cards>
+  <Card title="PII map" description="Where personal data lives and who touches it." />
+  <Card title="Export / erase" description="`oke privacy export|erase --subject` across stores." />
+</Cards>
+
+## Catalog
+
+<Cards>
+  <Card title="Dev" description="✓" />
+  <Card title="Prod" description="✓" />
+</Cards>
+
+<Callout title="Conditional">
+  This panel appears when the optional core plugin is plugged. There is no separate detailed
+  subsection beyond the catalog row.
+</Callout>

package/site/content/docs/console/runs.mdx

@@ -0,0 +1,40 @@
+---
+title: "Runs"
+description: "Wide events — one record per flow execution."
+icon: "Play"
+source: "docs/spec/console.md"
+---
+
+Answers: **wide events — one record per flow execution, queried by dimension**
+
+<Callout title="Governing rule">
+  One flow execution = one wide event = one span. Analysis by dimension, not a text search box.
+</Callout>
+
+## What this panel shows
+
+<Cards>
+  <Card
+    title="Wide events"
+    description="Dimensions from effects — no manual instrumentation tax."
+  />
+  <Card
+    title="Outlier explanation"
+    description="Compare all dimensions between slow and baseline populations."
+  />
+  <Card
+    title="Storage tiers"
+    description="Default Parquet + DuckDB; optional postgres / clickhouse."
+  />
+  <Card
+    title="Lifecycle"
+    description="Retain by default; redaction and crypto-shredding for compliance."
+  />
+</Cards>
+
+## Catalog
+
+<Cards>
+  <Card title="Dev" description="✓" />
+  <Card title="Prod" description="✓" />
+</Cards>

package/site/content/docs/console/signals.mdx

@@ -0,0 +1,31 @@
+---
+title: "Signals"
+description: "Queue depth, in-flight, DLQ, live monitors."
+icon: "Radio"
+source: "docs/spec/console.md"
+---
+
+Answers: **queue depth, in-flight, DLQ, live monitors**
+
+<Callout title="Governing rule">
+  One list grouped by delivery physics — not three tabs that re-split the element.
+</Callout>
+
+## What this panel shows
+
+<Cards>
+  <Card title="once" description="Pending, in-flight, DLQ, retry policy." />
+  <Card title="broadcast" description="Per-subscriber lag and targeted replay." />
+  <Card title="live" description="Connection count, throughput, payload monitor." />
+  <Card
+    title="DLQ repair"
+    description="Schema form, typed errors, causal chain, dry-run bulk replay."
+  />
+</Cards>
+
+## Catalog
+
+<Cards>
+  <Card title="Dev" description="full" />
+  <Card title="Prod" description="replay/purge per gates" />
+</Cards>

package/site/content/docs/console/store.mdx

@@ -0,0 +1,32 @@
+---
+title: "Store"
+description: "Browse sql/kv/files/index; cache keys; replica lag."
+icon: "Database"
+source: "docs/spec/console.md"
+---
+
+Answers: **browse sql/kv/files/index; cache keys; replica lag**
+
+<Callout title="Governing rule">
+  The most dangerous panel in production — gates, tenant isolation, PII masking, and audit on the
+  data path.
+</Callout>
+
+## What this panel shows
+
+<Cards>
+  <Card title="Four facets" description="sql · kv · files · index with adaptive detail." />
+  <Card title="PII masking" description="Follows schema classification, including raw SQL." />
+  <Card title="Cache keys" description="Which read produced a key; which write invalidates it." />
+  <Card
+    title="Direct edit warning"
+    description="Names what will not happen — not a silent row patch."
+  />
+</Cards>
+
+## Catalog
+
+<Cards>
+  <Card title="Dev" description="full + Studio link" />
+  <Card title="Prod" description="masked, gated, audited" />
+</Cards>

package/site/content/docs/console/tenancy.mdx

@@ -0,0 +1,32 @@
+---
+title: "Tenancy"
+description: "Per-tenant usage, limits, isolation checks (conditional)."
+icon: "Building2"
+source: "docs/spec/console.md"
+---
+
+Answers: **per-tenant usage, limits, isolation checks**
+
+<Callout title="Governing rule">
+  Conditional panel — appears when the tenancy plugin is plugged. Catalog row is the durable
+  reference.
+</Callout>
+
+## What this panel shows
+
+<Cards>
+  <Card title="Usage &amp; limits" description="Per-tenant usage and configured limits." />
+  <Card title="Isolation" description="Checks that tenant boundaries hold." />
+</Cards>
+
+## Catalog
+
+<Cards>
+  <Card title="Dev" description="✓" />
+  <Card title="Prod" description="✓" />
+</Cards>
+
+<Callout title="Conditional">
+  This panel appears when the optional core plugin is plugged. There is no separate detailed
+  subsection beyond the catalog row.
+</Callout>

package/site/content/docs/console/traces.mdx

@@ -0,0 +1,34 @@
+---
+title: "Traces"
+description: "One timeline across http → store → signal → durable steps."
+icon: "Route"
+source: "docs/spec/console.md"
+---
+
+Answers: **one timeline across http → store → signal → durable steps**
+
+<Callout title="Governing rule">
+  Folded time across async boundaries — a seven-day sleep is not 99.99% empty waterfall.
+</Callout>
+
+## What this panel shows
+
+<Cards>
+  <Card title="Causal chain" description="Join parent/child across emit boundaries." />
+  <Card title="Effect tiers" description="Spans coloured by the same vocabulary as Flows." />
+  <Card
+    title="Filter by effect"
+    description="Everything that wrote a table, sent mail, or cost more than X."
+  />
+  <Card
+    title="Why slow / why fail"
+    description="Critical path highlight; open on the failing span."
+  />
+</Cards>
+
+## Catalog
+
+<Cards>
+  <Card title="Dev" description="✓" />
+  <Card title="Prod" description="✓" />
+</Cards>

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

@@ -0,0 +1,37 @@
+---
+title: "Vault"
+description: "Secret contracts, who can read each, rotation due."
+icon: "KeyRound"
+source: "docs/spec/console.md"
+---
+
+Answers: **secret contracts, who can read each, rotation due**
+
+<Callout title="Governing rule">
+  Secrets are write-only — the panel can set and rotate; it can never reveal.
+</Callout>
+
+## What this panel shows
+
+<Cards>
+  <Card
+    title="Fingerprints"
+    description="Salted hash per environment — rotation and drift without exposure."
+  />
+  <Card
+    title="Resolution chain"
+    description="Which source won: env, files, vault driver, or fallback."
+  />
+  <Card title="Who can read" description="Derived from effects that declare `fx.vault`." />
+  <Card
+    title="Rotation blast radius"
+    description="In-flight durable runs that wake with a new key."
+  />
+</Cards>
+
+## Catalog
+
+<Cards>
+  <Card title="Dev" description="full" />
+  <Card title="Prod" description="set/rotate only, never reveal" />
+</Cards>

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

@@ -0,0 +1,180 @@
+---
+title: "AI"
+description: "Reaching machine intelligence — models, versioned prompts, embeddings, and bounded agents, with cost and PII egress as first-class constraints."
+icon: "Bot"
+source: "docs/spec/unified-theory.md"
+---
+
+AI is how your app calls **machine intelligence**: triage a ticket, embed a knowledge base, let an agent resolve a support case. Model calls differ from every other effect — they are nondeterministic, they cost money per call, and your data leaves the building — so prompts are **versioned artifacts**, not strings buried in a handler.
+
+<Callout title="The one rule">
+  The production model is **declared, never guessed** — there is no prod default. Development uses
+  `mock` for determinism, and sending PII to a third-party model fails the **build** unless you
+  explicitly acknowledge it.
+</Callout>
+
+## Quick start
+
+<Steps>
+
+<Step>
+### Declare a model and a prompt
+
+The model is a logical binding (`smart`, `fast`); the prompt is a versioned artifact with a typed output:
+
+```typescript title="src/ai.ts"
+import { ai } from "okengine";
+import { z } from "zod";
+
+export const smart = ai.model("smart", { provider: "anthropic", tier: "opus" });
+
+export const triage = smart.prompt("ticket-triage", {
+  in: z.object({ subject: z.string(), body: z.string() }),
+  out: z.object({ urgency: z.enum(["low", "high"]), team: z.string(), summary: z.string() }),
+  version: 3,
+  budget: { maxCostPerCall: 0.02 },
+});
+```
+
+</Step>
+
+<Step>
+### Ask it from a Flow
+
+`fx.ask` routes the call through the declared model and validates the response against `out`:
+
+```typescript title="src/flows/support/triage.ts"
+do: async (input, fx) => {
+  const result = await fx.ask(triage, { subject: input.subject, body: input.body });
+  // result is typed by the prompt's `out` schema
+};
+```
+
+</Step>
+
+<Step>
+### Gate regressions in CI
+
+Point the prompt at an eval set and it becomes a CI check — a prompt change that degrades answers fails the build like a broken test:
+
+```typescript
+export const triage = smart.prompt("ticket-triage", {
+  // …
+  evals: "./evals/triage.jsonl", // run with `oke eval`
+});
+```
+
+</Step>
+
+</Steps>
+
+## The four building blocks
+
+| Declaration                | Produces                                                           |
+| -------------------------- | ------------------------------------------------------------------ |
+| `ai.model(name, opts)`     | Logical model binding — provider / tier / concrete model id        |
+| `model.prompt(name, opts)` | Versioned prompt with typed in/out, evals, budget                  |
+| `ai.embed(name, opts)`     | Embedding pipeline into a `store.index` (searched via `fx.search`) |
+| `ai.agent(name, opts)`     | Bounded agent whose tools are **your own flows**                   |
+
+### Prompt options
+
+| Option       | Type                  | Meaning                                                        |
+| ------------ | --------------------- | -------------------------------------------------------------- |
+| `in` / `out` | zod / Standard Schema | Input and output contracts — responses validated against `out` |
+| `version`    | number                | Artifact version — diffs and regressions tracked per version   |
+| `evals`      | string                | Path to a `.jsonl` eval set, regression-gated via `oke eval`   |
+| `budget`     | object                | `maxCostPerCall` — cost is a first-class dimension             |
+
+## Agents with real guardrails
+
+An agent's tools are your flows — each carrying its own gates, effects, and typed errors, so the agent can never do anything a flow couldn't:
+
+```typescript
+export const support = ai.agent("support", {
+  model: smart,
+  tools: [getBooking, refundBooking], // flows, with their gates attached
+  maxSteps: 6,
+  budget: { maxCostPerRun: 0.25 },
+});
+```
+
+`maxSteps` bounds the loop; `budget.maxCostPerRun` bounds the spend. Both are declared, so "the agent ran away" is a violated contract, not a surprise.
+
+## PII cannot leak by accident
+
+At build time, OKE checks which fields each `fx.ask` sends against your store classifications. If a PII field (`.pii()` in your schema) would reach a third-party model, the build fails:
+
+```text
+build failed: flow "ticket-triage" sends pii field(s) [email] to a third-party model without allowPii
+```
+
+The escape hatch is explicit acknowledgment — `allowPii: true` (or `pii: "allow"`) on the flow — so egress is a decision that shows up in code review. The `mock` driver and local models are not third-party; the check targets external providers.
+
+## Nondeterminism is priced in
+
+Because `fx.ask` is nondeterministic, the runtime adjusts around it: journaling is **forced** on (durable flows can replay), and auto-caching is disabled for the call. In development and tests the `mock` driver makes model calls deterministic — your suite never hits a network, and CI never flakes on a provider.
+
+## Per-environment drivers
+
+| Driver              | What it is                                            |
+| ------------------- | ----------------------------------------------------- |
+| `mock`              | Deterministic fake — dev + test default               |
+| `anthropic`         | Anthropic API                                         |
+| `openai-compatible` | Any OpenAI-compatible endpoint                        |
+| `bedrock`           | AWS Bedrock                                           |
+| `vertex`            | Google Vertex AI                                      |
+| `ollama`            | Local models — counts as on-premise for the PII check |
+
+There is deliberately **no production default**: `prod` must name a driver, which keeps the model choice visible in `oke.config.ts` where review can see it.
+
+## Troubleshooting
+
+<Accordions>
+<Accordion title="Build fails with AiPiiBuildError">
+
+A flow sends a classified PII field to a third-party model. Either stop sending that field (drop it from the `fx.ask` input), or acknowledge the egress with `allowPii: true` on the flow — the error message names the exact fields.
+
+</Accordion>
+<Accordion title="Which model will prod actually call?">
+
+The one you declared. There is no fallback or guess — if `prod` has no AI driver configured, that's a configuration gap to fix, not a silent default.
+
+</Accordion>
+<Accordion title="A prompt edit made answers worse — how do I catch that pre-merge?">
+
+Attach `evals: "./evals/<name>.jsonl"` to the prompt and run `oke eval` in CI. The suite replays the eval cases and fails on regressions, per prompt version.
+
+</Accordion>
+<Accordion title="An agent looped and burned budget">
+
+Bound it at declaration: `maxSteps` caps iterations, `budget.maxCostPerRun` caps spend. The Console's AI view shows cost per run so you can tune both against real numbers.
+
+</Accordion>
+</Accordions>
+
+## Learn more
+
+- [Flow](/docs/elements/flow) — `fx.ask` and `fx.search` inside `do`
+- [Store](/docs/elements/store) — `store.index`, the home of embeddings
+- [Console · AI](/docs/console/ai) — prompts, versions, cost per run
+
+## Next
+
+<Cards>
+  <Card
+    title="Basic Usage"
+    description="Build from the standard starter."
+    href="/docs/get-started/basic-usage"
+  />
+  <Card
+    title="Introduction"
+    description="Eight elements overview."
+    href="/docs/get-started/introduction"
+  />
+  <Card
+    title="Console"
+    description="Panels derived from the Manifest."
+    href="/docs/console/overview"
+  />
+</Cards>