okengine 0.10.2 → 0.11.0

package/src/upgrade/codemods.ts

@@ -4,6 +4,10 @@
  * `oke upgrade` runs every applicable transform and prints a diff.
  * Adding a breaking change without a codemod is a process defect; the
  * registry is the checklist.
+ *
+ * Environment-model migrations (`local`/`docker` → `dev`, sqlite removal)
+ * are documented only — see site docs `reference/migrating-environments`.
+ * No soft-compat rewriter for those.
  */
 
 import { readdir } from "node:fs/promises";
@@ -38,49 +42,7 @@ export interface Codemod {
 }
 
 /**
- * Rewrite driver-map keys `dev:` → `local:` and `stack:` → `docker:`.
- *
- * Vault `dev:` fallbacks are intentionally excluded — callers pass only
- * `oke.config.*` paths into this rewriter.
- *
- * @param source - File contents
- */
-export function rewriteConfigEnvKeys(source: string): string {
-  return source
-    .replace(/(^|[^\w.])dev(\s*:)/gm, "$1local$2")
-    .replace(/(^|[^\w.])stack(\s*:)/gm, "$1docker$2");
-}
-
-/**
- * Rewrite removed vault stack markers to docker equivalents.
- *
- * @param source - File contents
- */
-export function rewriteFromStackMarkers(source: string): string {
-  return source
-    .replace(/\bfromStack\b/g, "fromDocker")
-    .replace(/\bFROM_STACK_PREFIX\b/g, "FROM_DOCKER_PREFIX")
-    .replace(/\bisFromStack\b/g, "isFromDocker")
-    .replace(/\bfromStackRole\b/g, "fromDockerRole")
-    .replace(/__oke_from_stack__/g, "__oke_from_docker__");
-}
-
-/**
- * Collect `oke.config.*` files under a project root.
- *
- * @param cwd - Project root
- */
-async function collectConfigCandidates(cwd: string): Promise<string[]> {
-  const out: string[] = [];
-  for (const name of ["oke.config.ts", "oke.config.mts", "oke.config.js"]) {
-    const path = resolve(cwd, name);
-    if (await Bun.file(path).exists()) out.push(path);
-  }
-  return out;
-}
-
-/**
- * Collect TypeScript sources that may reference `fromStack`.
+ * Collect TypeScript sources under `src` / `app`.
  *
  * @param cwd - Project root
  */
@@ -116,30 +78,101 @@ async function walkTs(dir: string, out: string[]): Promise<void> {
 }
 
 /**
- * Built-in transforms.
+ * Rewrite deep `okengine` imports that left the thin root to subpaths.
+ *
+ * @param source - File contents
  */
+export function rewriteThinRootImports(source: string): string {
+  const movers: readonly { readonly names: readonly string[]; readonly from: string }[] = [
+    {
+      names: [
+        "createRunsRuntime",
+        "collectWideEvent",
+        "createRunTelemetry",
+        "explainOutliers",
+        "filesRunsDriver",
+        "memoryRunsDriver",
+        "postgresRunsDriver",
+        "clickhouseRunsDriver",
+        "openDuckDB",
+        "duckQuery",
+      ],
+      from: "okengine/runs",
+    },
+    {
+      names: [
+        "createJournal",
+        "createMemoryJournalStore",
+        "createFileJournalStore",
+        "hasJournalLease",
+        "JOURNAL_DEFAULT_LEASE_MS",
+      ],
+      from: "okengine/journal",
+    },
+    {
+      names: ["compileAot", "compileDynamic", "compileRoute", "sucrose", "extractManifest"],
+      from: "okengine/compiler",
+    },
+    {
+      names: ["formatMessage", "clearMessageFormatCache", "resolveFailureMessage"],
+      from: "okengine/i18n",
+    },
+    {
+      names: [
+        "bootApplication",
+        "mintCapabilities",
+        "createFx",
+        "createRouter",
+        "CONSOLE_PORT",
+        "MCP_PORT",
+      ],
+      from: "okengine/full",
+    },
+  ];
+
+  let text = source;
+  for (const mover of movers) {
+    const re = new RegExp(`import\\s*\\{([^}]*)\\}\\s*from\\s*(["'])okengine\\2`, "g");
+    text = text.replace(re, (full, body: string, quote: string) => {
+      const parts = body
+        .split(",")
+        .map((p) => p.trim())
+        .filter(Boolean);
+      const keep: string[] = [];
+      const move: string[] = [];
+      for (const part of parts) {
+        const base =
+          part
+            .replace(/^type\s+/, "")
+            .split(/\s+as\s+/)[0]
+            ?.trim() ?? part;
+        if (mover.names.includes(base)) move.push(part);
+        else keep.push(part);
+      }
+      if (move.length === 0) return full;
+      const lines: string[] = [];
+      if (keep.length > 0) {
+        lines.push(`import { ${keep.join(", ")} } from ${quote}okengine${quote}`);
+      }
+      lines.push(`import { ${move.join(", ")} } from ${quote}${mover.from}${quote}`);
+      return lines.join(";\n");
+    });
+  }
+  return text;
+}
+
 export const CODEMODS: readonly Codemod[] = [
   {
-    id: "0.2.7-config-env-local-docker",
-    from: "0.2.6",
-    to: "0.2.7",
-    description: "Rename driver-map keys dev→local, stack→docker; fromStack→fromDocker",
+    id: "0.10.3-thin-root-subpaths",
+    from: "0.10.2",
+    to: "0.10.3",
+    description:
+      "Move deep okengine imports (runs/journal/compiler/i18n/boot helpers) to okengine/* subpaths after thin root",
     async apply(cwd) {
       const changes: CodemodChange[] = [];
-      for (const path of await collectConfigCandidates(cwd)) {
-        const before = await Bun.file(path).text();
-        const after = rewriteConfigEnvKeys(before);
-        if (after !== before) {
-          changes.push({
-            path: relative(cwd, path) || path,
-            before,
-            after,
-          });
-        }
-      }
       for (const path of await collectVaultCandidates(cwd)) {
         const before = await Bun.file(path).text();
-        const after = rewriteFromStackMarkers(before);
+        const after = rewriteThinRootImports(before);
         if (after !== before) {
           changes.push({
             path: relative(cwd, path) || path,

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

@@ -1,29 +0,0 @@
----
-title: "Access"
-description: "Identities, roles, API keys."
-icon: "Users"
-source: "docs/spec/console.md"
----
-
-Answers: **identities, roles, API keys**
-
-<Callout title="Governing rule">
-  Granting an application scope to an operator is impossible in the UI — taught by absence, not
-  refusal.
-</Callout>
-
-## What this panel shows
-
-<Cards>
-  <Card title="Two planes" description="Operators and application users never mix." />
-  <Card title="Key creation" description="Value shown once; attenuation to creator scopes only." />
-  <Card title="Revocation" description="Blast radius plus honest JWT validity delay." />
-  <Card title="Hygiene" description="Unused keys, never-signed-in operators, expired invites." />
-</Cards>
-
-## Catalog
-
-<Cards>
-  <Card title="Dev" description="✓" />
-  <Card title="Prod" description="✓ (admin)" />
-</Cards>

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

@@ -1,35 +0,0 @@
----
-title: "AI"
-description: "Prompt versions, eval scores, cost, agent runs."
-icon: "Sparkles"
-source: "docs/spec/console.md"
----
-
-Answers: **prompt versions, eval scores, cost, agent runs**
-
-<Callout title="Governing rule">
-  Everything else in the Console is deterministic; this panel is built on distributions, not single
-  values.
-</Callout>
-
-## What this panel shows
-
-<Cards>
-  <Card title="Prompt versions" description="A version bump is Manifest Diff blast radius." />
-  <Card title="Eval + shape" description="Schema-validation failure is its own class." />
-  <Card
-    title="Agent tools"
-    description="Tools are the app’s own flows — undeclared reach is denied and shown."
-  />
-  <Card
-    title="Budgets"
-    description="Cost, semantic cache, and `allowPii` as standing review surfaces."
-  />
-</Cards>
-
-## Catalog
-
-<Cards>
-  <Card title="Dev" description="full" />
-  <Card title="Prod" description="read + budgets" />
-</Cards>

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

@@ -1,35 +0,0 @@
----
-title: "Architecture"
-description: "How it all connects — the diagram that is the code."
-icon: "Network"
-source: "docs/spec/console.md"
----
-
-Answers: **how it all connects — the diagram that _is_ the code**
-
-<Callout title="Governing rule">
-  Flows answers “which one”; Architecture answers “what shape”. Never shows the whole system by
-  default.
-</Callout>
-
-## What this panel shows
-
-<Cards>
-  <Card title="Unit clusters" description="Default aggregated edges; focus one or two hops." />
-  <Card title="Element layers" description="Toggle data, messaging, time, external edges." />
-  <Card
-    title="Live traffic"
-    description="Edge thickness from real traffic; dashed = never traversed."
-  />
-  <Card
-    title="Pathologies"
-    description="Cycles, god nodes, orphan signals, SPOFs — computed from the graph."
-  />
-</Cards>
-
-## Catalog
-
-<Cards>
-  <Card title="Dev" description="✓" />
-  <Card title="Prod" description="✓" />
-</Cards>

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

@@ -1,37 +0,0 @@
----
-title: "Channels"
-description: "Templates, delivery receipts, bounces, opt-outs."
-icon: "Mailbox"
-source: "docs/spec/console.md"
----
-
-Answers: **templates, delivery receipts, bounces, opt-outs, deliverability (SPF/DKIM/DMARC)**
-
-<Callout title="Governing rule">
-  Suppression is not failure — the taxonomy of “did not arrive” has seven states with verdicts.
-</Callout>
-
-## What this panel shows
-
-<Cards>
-  <Card title="Dev inbox" description="`console` driver lands every medium locally." />
-  <Card
-    title="Deliverability"
-    description="SPF/DKIM/DMARC, bounces, complaints, suppression list."
-  />
-  <Card
-    title="Fallback chains"
-    description="Recorded as chains (e.g. WhatsApp → SMS), not single outcomes."
-  />
-  <Card
-    title="Locale previews"
-    description="Template data bound to schema; RTL-accurate previews."
-  />
-</Cards>
-
-## Catalog
-
-<Cards>
-  <Card title="Dev" description="full + console inbox" />
-  <Card title="Prod" description="send test, inspect delivery" />
-</Cards>

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

@@ -1,51 +0,0 @@
----
-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="Drift, overdue, missed runs · catch-up one, lease holder." />
-  <Card title="Pending wakes" description="Every sleeping durable flow and when it wakes." />
-  <Card
-    title="DST warnings"
-    description="Gap or overlap badge — detect only, no schedule rewrite."
-  />
-  <Card title="Actions" description="Run now, wake early, pause; edit when overridable." />
-</Cards>
-
-## Health numbers
-
-Each cron row projects four numbers plus the lease holder:
-
-| Field           | Meaning                                                           |
-| --------------- | ----------------------------------------------------------------- |
-| Drift           | How far the last run sat from the expected slot                   |
-| Overdue         | Whether the schedule is past due                                  |
-| Missed + policy | Slot count while down · always catch-up `"one"` (one fire, not N) |
-| Lease           | Which instance holds the leader lease (empty when none)           |
-
-## Actions
-
-| Action        | When                                                                   |
-| ------------- | ---------------------------------------------------------------------- |
-| Pause         | Any cron — not gated by `overridable`                                  |
-| Edit schedule | Only when the declaration has `overridable: true`; else loud refuse    |
-| Wake early    | Sleeping durable run — advances `wakeAt` and can resume the journal    |
-| Run now       | Still requires the leader lease across replicas that share a CronStore |
-
-## Catalog
-
-<Cards>
-  <Card title="Dev" description="full" />
-  <Card title="Prod" description="trigger/pause; edit if `overridable`" />
-</Cards>

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

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

@@ -1,73 +0,0 @@
----
-title: "Gates"
-description: "Permission inquiry, rate counters, and continuous audit of unguarded vs explicitly public flows."
-icon: "Shield"
-source: "docs/spec/console.md"
----
-
-The Gates panel answers **who may do what** without dumping a giant roles×permissions matrix as
-the home screen. Inquire from a principal or from a flow; the simulator shows the chain in
-evaluation order.
-
-<Callout title="The one 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 denial stopped." />
-  <Card
-    title="Unguarded vs public"
-    description="Empty chain (missing posture) vs gate.public (intentional)."
-  />
-  <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>
-
-## Unguarded vs explicit public
-
-| Flag            | Meaning                                                                      |
-| --------------- | ---------------------------------------------------------------------------- |
-| Unguarded       | User-plane flow with an **empty** gate chain — missing auth posture          |
-| Explicit public | Chain includes the reserved `public` sentinel (`gate.public` on the trigger) |
-
-App boot fails on unguarded HTTP triggers (`GateBootError`) unless `env === "test"` and
-`gate: { unguardedHttp: "allow" }`. Prefer fixing the flow: attach a policy, or attach
-`gate.public` when the surface is intentionally open.
-
-App authors configure Gate under `oke({ gate: { policies, auth, unguardedHttp } })` — see
-[Gate](/docs/elements/gate). Builtin `/auth/*` Flows from `gate.auth` are audited the same way.
-
-## Catalog
-
-Policies, rates, and `/auth/*` Bindings from the Manifest — inquire and audit, not a live
-rate editor. Rate `overridable` is a catalog flag; schedule edits live under
-[Clock](/docs/console/clock).
-
-<Cards>
-  <Card title="Dev" description="full catalog + simulator" />
-  <Card title="Prod" description="same inquire surface; no silent ungated HTTP" />
-</Cards>
-
-## Learn more
-
-- [Gate](/docs/elements/gate) — policies, rate limits, `gate.auth`, posture
-- [Plugins](/docs/plugins) — plugged sign-in method plugins
-- [Access](/docs/console/access) — roles and API keys
-
-## Next
-
-<Cards>
-  <Card title="Gate" description="Declare policies and auth." href="/docs/elements/gate" />
-  <Card title="Access" description="Roles and API keys." href="/docs/console/access" />
-  <Card
-    title="Overview"
-    description="Console panels from the Manifest."
-    href="/docs/console/overview"
-  />
-</Cards>

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

@@ -1,54 +0,0 @@
----
-title: "Console"
-description: "Manifest-derived operator panels on :6533 — health, elements, traces, access, and more."
-icon: "LayoutDashboard"
-source: "docs/spec/console.md"
----
-
-The Console is derived from your Manifest. Each panel answers one operator question.
-
-## Pages
-
-<Cards>
-  <Card
-    title="Overview"
-    description="Is the system healthy right now?"
-    href="/docs/console/overview"
-  />
-  <Card
-    title="Flows"
-    description="What exists; call it; read its contract."
-    href="/docs/console/flows"
-  />
-  <Card title="Signals" description="Queue depth, in-flight, DLQ." href="/docs/console/signals" />
-  <Card title="Store" description="Browse sql/kv/files/index." href="/docs/console/store" />
-  <Card title="Clock" description="Crons, sleeps, journal." href="/docs/console/clock" />
-  <Card
-    title="Gates"
-    description="Permission matrix and rate counters."
-    href="/docs/console/gates"
-  />
-  <Card title="Vault" description="Secret contracts and rotation." href="/docs/console/vault" />
-  <Card
-    title="Channels"
-    description="Templates, receipts, opt-outs."
-    href="/docs/console/channels"
-  />
-  <Card title="AI" description="Prompts, evals, cost, agents." href="/docs/console/ai" />
-  <Card title="Architecture" description="How it all connects." href="/docs/console/architecture" />
-  <Card title="Traces" description="One timeline across effects." href="/docs/console/traces" />
-  <Card title="Runs" description="Wide events per execution." href="/docs/console/runs" />
-  <Card
-    title="Manifest Diff"
-    description="Blast radius of a deploy."
-    href="/docs/console/manifest-diff"
-  />
-  <Card title="Access" description="Identities, roles, API keys." href="/docs/console/access" />
-  <Card title="Plugins" description="Installed plugins and panels." href="/docs/console/plugins" />
-  <Card title="Privacy" description="Where PII lives (conditional)." href="/docs/console/privacy" />
-  <Card
-    title="Tenancy"
-    description="Per-tenant usage (conditional)."
-    href="/docs/console/tenancy"
-  />
-</Cards>

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

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

@@ -1,24 +0,0 @@
-{
-  "title": "Console",
-  "icon": "LayoutDashboard",
-  "pages": [
-    "index",
-    "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

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

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