okengine 0.17.2 → 0.18.4

package/AGENTS.md

@@ -1,5 +1,7 @@
 # OKE — Agent Contract
 
+One law. Eight elements. One contract. The backend model stays small; operational surfaces are derived from it instead of maintained separately.
+
 This file is loaded by every later session. It prevents drift. Product documentation lives in `site/content/docs/`. **If the documentation is silent, stop and ask.**
 
 ## The one law
@@ -27,13 +29,13 @@ There are no separate species called endpoints, handlers, consumers, jobs, subsc
 
 An element earns its place only if it has irreducible physics. New infrastructure becomes a new **driver** for an existing element — never a ninth element.
 
-## The ten exports
+## Core programming vocabulary
 
 ```typescript
 import { on, flow, signal, store, clock, gate, vault, channel, ai, plugin } from "okengine";
 ```
 
-That is the entire public vocabulary. Everything else is derived.
+That is the core programming vocabulary. Everything else is derived.
 
 ## Governing rule
 
@@ -80,7 +82,7 @@ Published packages:
 - `okengine` — framework. Subpath exports: `.`, `./client`, `./test`, `./config`, `./auth`, `./plugins`, `./drivers/*`. `"sideEffects": false`. CLI binary: `oke`.
 - `create-oke` — scaffold CLI (`bunx create-oke@latest <name>`). Lives in `packages/create-oke` and ships Notes starters from `packages/create-oke/templates/{standard,advanced}`.
 
-Engine: Bun `>=1.3.14`.
+Engine: Bun `>=1.4.0`.
 
 ## Documentation authority
 

package/README.md

@@ -2,11 +2,11 @@
   <picture>
     <source
       media="(prefers-color-scheme: dark)"
-      srcset="https://shieldcn.dev/header/grid.svg?title=okengine&subtitle=One+law.+Eight+elements.+Ten+exports.&logo=https://raw.githubusercontent.com/omqkhafi/okengine/main/site/public/logo/OKE-W.svg&theme=zinc&size=banner&mode=dark&font=geist&align=left"
+      srcset="https://shieldcn.dev/header/grid.svg?title=okengine&subtitle=One+law.+Eight+elements.+One+contract.&logo=https://raw.githubusercontent.com/omqkhafi/okengine/main/site/public/logo/OKE-W.svg&theme=zinc&size=banner&mode=dark&font=geist&align=left"
     />
     <img
-      alt="okengine — One law. Eight elements. Ten exports."
-      src="https://shieldcn.dev/header/grid.svg?title=okengine&subtitle=One+law.+Eight+elements.+Ten+exports.&logo=https://raw.githubusercontent.com/omqkhafi/okengine/main/site/public/logo/OKE-B.svg&theme=zinc&size=banner&mode=light&font=geist&align=left"
+      alt="okengine — One law. Eight elements. One contract."
+      src="https://shieldcn.dev/header/grid.svg?title=okengine&subtitle=One+law.+Eight+elements.+One+contract.&logo=https://raw.githubusercontent.com/omqkhafi/okengine/main/site/public/logo/OKE-B.svg&theme=zinc&size=banner&mode=light&font=geist&align=left"
       width="750"
     />
   </picture>
@@ -16,13 +16,13 @@
   <a href="https://www.npmjs.com/package/okengine"><img alt="npm" src="https://shieldcn.dev/npm/okengine.svg?size=sm&variant=outline" /></a>
   <a href="https://jsr.io/@omqkhafi/okengine"><img alt="JSR" src="https://shieldcn.dev/jsr/@omqkhafi/okengine.svg?size=sm&variant=outline" /></a>
   <a href="https://opensource.org/licenses/MIT"><img alt="MIT" src="https://shieldcn.dev/npm/license/okengine.svg?size=sm&variant=outline" /></a>
-  <a href="https://bun.sh"><img alt="Bun >=1.3.14" src="https://shieldcn.dev/badge/Bun-%3E%3D1.3.14.svg?logo=bun&size=sm&variant=outline" /></a>
+  <a href="https://bun.sh"><img alt="Bun >=1.4.0" src="https://shieldcn.dev/badge/Bun-%3E%3D1.4.0.svg?logo=bun&size=sm&variant=outline" /></a>
   <a href="https://github.com/omqkhafi/okengine/actions"><img alt="CI" src="https://shieldcn.dev/github/ci/omqkhafi/okengine.svg?size=sm&variant=outline" /></a>
   <a href="https://github.com/omqkhafi/okengine/commits"><img alt="last commit" src="https://shieldcn.dev/github/last-commit/omqkhafi/okengine.svg?size=sm&variant=outline" /></a>
 </p>
 
 <p align="center">
-  <em>Stop gluing APIs, jobs, and queues into one backend. One law collapses them — client, Console, and infra come free. Yours to host.</em>
+  <em>Modern backends became a pile of disconnected systems. One law collapses them — client, Console, and infra derived from one contract. Yours to host.</em>
 </p>
 
 <p align="center">
@@ -39,7 +39,7 @@
 
 ## Install
 
-Requires [Bun](https://bun.sh) `>=1.3.14`.
+Requires [Bun](https://bun.sh) `>=1.4.0`.
 
 ```bash
 bunx create-oke@latest my-app                      # scaffold (recommended)
@@ -69,12 +69,13 @@ Mnemonic: **O·K·E = 6·5·3**.
 The starter already exports a health Flow — change it and save; App and Console update from the same Manifest:
 
 ```typescript
-import { on, flow, http, gate } from "okengine";
+// src/flows/main/health.ts — folders are the URL: `main/health.ts` → GET /health
+import { on, flow, http } from "okengine";
 import { z } from "zod";
 
 export const health = on(
-  http.get("/health").gate(gate.public),
-  flow("health.check", {
+  http.get().public(),
+  flow({
     out: z.object({ ok: z.literal(true) }),
     do: () => ({ ok: true as const }),
   }),
@@ -91,6 +92,8 @@ const api = createClient<App>("http://localhost:6530");
 const { data, error } = await api.main.health({});
 ```
 
+Native ids: import `okid` from `okengine/okid` — compact, URL-safe, cryptographically random (`okid()`, `okid(16)`, `okid({ sortable: true })`).
+
 Full walkthrough: [Basic usage](https://oke.omqkhafi.dev/docs/get-started/basic-usage).
 
 ## One law
@@ -101,7 +104,7 @@ Every backend behavior is a Flow: `on(Trigger) → Effects`. Endpoints, jobs, co
 import { on, flow, signal, store, clock, gate, vault, channel, ai, plugin } from "okengine";
 ```
 
-That is the entire public vocabulary. World access goes through `fx` — effects are inferred, so the Manifest can derive the typed client, Console, and MCP without a second source of truth.
+That is the core programming vocabulary. World access goes through `fx` — effects are inferred, so the Manifest can derive the typed client, Console, and MCP without a second source of truth.
 
 | Element     | Essence                       |
 | ----------- | ----------------------------- |
@@ -140,6 +143,7 @@ Store apps sync schema with `oke db push|generate|migrate` (local `oke dev` auto
 | Agents index | [/llms.txt](https://oke.omqkhafi.dev/llms.txt)                 |
 | Manifest     | [`manifest.v1.schema.json`](manifest.v1.schema.json)           |
 | Budgets      | [`BUDGETS.md`](BUDGETS.md)                                     |
+| Security     | [`SECURITY.md`](SECURITY.md)                                   |
 | Contributing | [`CONTRIBUTING.md`](CONTRIBUTING.md)                           |
 
 ## License

package/manifest.v1.schema.json

@@ -219,7 +219,17 @@
         "signal": { "type": "string", "minLength": 1 },
         "cron": { "type": "string", "minLength": 1 },
         "every": { "type": "string", "minLength": 1 },
-        "cdc": { "$ref": "#/$defs/CdcTrigger" }
+        "cdc": { "$ref": "#/$defs/CdcTrigger" },
+        "mcp": { "$ref": "#/$defs/McpTrigger" }
+      }
+    },
+    "McpTrigger": {
+      "description": "Explicit MCP tool exposure. Presence means the flow is listed over MCP for OAuth user-plane clients; absence means not an MCP tool (deny-by-default).",
+      "type": "object",
+      "required": ["name"],
+      "additionalProperties": false,
+      "properties": {
+        "name": { "type": "string", "minLength": 1 }
       }
     },
     "Slo": {
@@ -378,7 +388,38 @@
       "type": "object",
       "additionalProperties": false,
       "properties": {
-        "type": { "type": "string", "enum": ["text", "integer"] },
+        "type": {
+          "type": "string",
+          "enum": [
+            "text",
+            "varchar",
+            "char",
+            "boolean",
+            "smallint",
+            "integer",
+            "bigint",
+            "serial",
+            "smallserial",
+            "bigserial",
+            "numeric",
+            "real",
+            "doublePrecision",
+            "json",
+            "jsonb",
+            "uuid",
+            "time",
+            "timestamp",
+            "date",
+            "interval",
+            "point",
+            "line",
+            "bytea",
+            "inet",
+            "cidr",
+            "macaddr",
+            "macaddr8"
+          ]
+        },
         "nullable": { "type": "boolean" },
         "primaryKey": { "type": "boolean" },
         "unique": { "type": "boolean" },
@@ -390,6 +431,24 @@
             { "type": "null" }
           ]
         },
+        "enumValues": {
+          "description": "Allowed string values for enum columns (text/varchar/char).",
+          "type": "array",
+          "items": { "type": "string" },
+          "minItems": 1
+        },
+        "length": { "description": "varchar/char max length.", "type": "integer", "minimum": 1 },
+        "precision": {
+          "description": "Fractional-second digits (time/timestamp, 0-6) or interval precision.",
+          "type": "integer"
+        },
+        "scale": { "description": "numeric(p, s) scale digits.", "type": "integer" },
+        "withTimezone": { "description": "time/timestamp timezone flavor.", "type": "boolean" },
+        "mode": {
+          "description": "JS mapping selector for temporal/numeric/point/line/bigint columns.",
+          "type": "string"
+        },
+        "fields": { "description": "interval field qualifier.", "type": "string" },
         "sqlName": { "type": "string", "minLength": 1 },
         "description": {
           "description": "Optional human description; consumers fall back to the column map key.",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "okengine",
-  "version": "0.17.2",
-  "description": "One law. Eight elements. Ten exports. One package. One manifest. Every backend need is derived, never added.",
+  "version": "0.18.4",
+  "description": "One law. Eight elements. One contract. The backend model stays small; operational surfaces are derived from it instead of maintained separately.",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -72,6 +72,12 @@
     "./client/auth": "./src/client/auth.ts",
     "./client-react": "./src/client-react/index.ts",
     "./test": "./src/test/index.ts",
+    "./testing": {
+      "types": "./src/testing.ts",
+      "bun": "./src/testing.ts",
+      "import": "./dist/testing.js",
+      "default": "./dist/testing.js"
+    },
     "./config": "./src/config/index.ts",
     "./auth": "./src/auth/index.ts",
     "./console": "./src/console/index.ts",
@@ -86,7 +92,13 @@
     "./ai": "./src/elements/ai.ts",
     "./runs": "./src/runs/index.ts",
     "./drivers": "./src/drivers/index.ts",
-    "./drivers/*": "./src/drivers/*"
+    "./drivers/*": "./src/drivers/*",
+    "./okid": {
+      "types": "./src/okid.ts",
+      "bun": "./src/okid.ts",
+      "import": "./dist/okid.js",
+      "default": "./dist/okid.js"
+    }
   },
   "scripts": {
     "typecheck": "tsc --noEmit && tsc --noEmit -p tests/console/tsconfig.ui-next.json && tsc --noEmit -p src/console/ui-next && bun run --cwd packages/create-oke typecheck && bun run --cwd examples/keel typecheck",
@@ -112,7 +124,8 @@
     "test:keel:docker": "OKE_TEST_DOCKER=1 bun run --cwd examples/keel test",
     "build:lib": "bun src/release/build-lib.ts",
     "prepack": "bun run build && bun run build:lib",
-    "bench": "bun test ./src/runtime/cold-start.bench.ts src/client/budget.test.ts src/console/budget.test.ts src/kernel/budget.test.ts src/kernel/routing-budget.test.ts src/runs/bench.test.ts",
+    "bench": "bun test ./src/runtime/cold-start.bench.ts src/client/budget.test.ts src/console/budget.test.ts src/kernel/budget.test.ts src/kernel/routing-budget.test.ts src/runs/bench.test.ts src/okid.bench.test.ts",
+    "bench:load": "OKE_BENCH=1 bun test ./src/bench/*.bench.ts --timeout 600000 --pass-with-no-tests",
     "budgets": "bun src/release/publish.ts",
     "gate": "PUBLISH_GATE=1 bun test src/cli/doc-staleness.test.ts src/cli/competitor-mention-removal.test.ts src/drivers/vault-driver-removal.test.ts src/kernel/errors.registry.test.ts src/upgrade/codemods.test.ts scripts/publish.gate.test.ts",
     "dev": "bun run --cwd site dev",
@@ -121,7 +134,8 @@
     "ci": "bun scripts/ci.ts",
     "bump": "bun run scripts/bump-version.ts",
     "release": "bun run scripts/publish.ts",
-    "g": "gflows"
+    "g": "gflows",
+    "postinstall": "bun run --cwd examples/keel prepare"
   },
   "dependencies": {
     "@clack/prompts": "^1.7.0",

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

@@ -5,7 +5,7 @@ icon: "Bot"
 source: "docs/spec/unified-theory.md"
 ---
 
-Resources for AI agents that read or operate an OKE app — not the `ai` element itself.
+Resources for AI agents that read or operate an OKE app — not the `ai` element itself. In OKE, **MCP is a surface of the model, not the model itself**. Gate governs agents calling in; the AI element governs apps calling out.
 
 ## Pages
 

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

@@ -5,7 +5,16 @@ icon: "Plug"
 source: "docs/spec/unified-theory.md"
 ---
 
-Two directions, same protocol. **Serve:** OKE exposes your running app on port **6535** so an agent can read the Manifest and take confirmed actions. **Consume:** your Flows call _external_ MCP servers as tools — declared on `ai.mcpServer`, dispatched through `fx.call`.
+## Two directions, same execution model
+
+> **MCP is a surface of the model, not the model itself.**
+
+Two genuinely distinct things share the protocol in OKE:
+
+1. **Gate Element (MCP Provider role):** Your app exposes Flows as MCP tools on port **6535** (or via `mcp.tool()` + OAuth 2.1 Authorization Server) so external AI agents (Claude, ChatGPT) can read the Manifest and call declared Flows.
+2. **AI Element (MCP Client role):** Your app consumes _external_ MCP tool servers via `ai.mcpServer(...)`, routing tool calls through `fx.call` inside prompts and agents.
+
+OKE does not create separate security models for users, operators, and agents. They enter the same execution model through different triggers and planes.
 
 The server on **6535** speaks JSON-RPC over HTTP (MCP protocol `2024-11-05`), requires a Bearer token **even on localhost**, and never forwards that token upstream — adapters receive structured operator ids instead.
 

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

@@ -9,18 +9,18 @@ Tools alone don't make a good operator — an agent also needs to know the _voca
 
 ## The layers
 
-| Layer              | Path                         | Loaded when                                       | Teaches                                                               |
-| ------------------ | ---------------------------- | ------------------------------------------------- | --------------------------------------------------------------------- |
-| **Agent contract** | `AGENTS.md` (repo root)      | Every agent session, automatically                | The one law, eight elements, ten exports, the fx rule, ports, budgets |
-| **Element skill**  | `.agents/skills/oke/`        | Building or changing an okengine app              | The element contract in depth — declaration patterns per element      |
-| **Docs skill**     | `.agents/skills/oke-docs/`   | Writing or editing docs under `site/content/docs` | The documentation information-architecture standard and its gates     |
-| **Ship skill**     | `.agents/skills/oke-ship/`   | After any implementation, before claiming done    | Changelog under `## Unreleased` + docs sync via `oke-docs`            |
-| **Deps skill**     | `.agents/skills/oke-deps/`   | Updating `package.json` dependencies              | Scoped bumps, Bun install, pins (Drizzle RC, fumadocs alias, …)       |
-| **Images skill**   | `.agents/skills/oke-images/` | Updating Compose image pins                       | Registry probe, pin style, catalog + recipes + Keel + docs lockstep   |
+| Layer              | Path                         | Loaded when                                       | Teaches                                                                |
+| ------------------ | ---------------------------- | ------------------------------------------------- | ---------------------------------------------------------------------- |
+| **Agent contract** | `AGENTS.md` (repo root)      | Every agent session, automatically                | The one law, eight elements, one contract, the fx rule, ports, budgets |
+| **Element skill**  | `.agents/skills/oke/`        | Building or changing an okengine app              | The element contract in depth — declaration patterns per element       |
+| **Docs skill**     | `.agents/skills/oke-docs/`   | Writing or editing docs under `site/content/docs` | The documentation information-architecture standard and its gates      |
+| **Ship skill**     | `.agents/skills/oke-ship/`   | After any implementation, before claiming done    | Changelog under `## Unreleased` + docs sync via `oke-docs`             |
+| **Deps skill**     | `.agents/skills/oke-deps/`   | Updating `package.json` dependencies              | Scoped bumps, Bun install, pins (Drizzle RC, fumadocs alias, …)        |
+| **Images skill**   | `.agents/skills/oke-images/` | Updating Compose image pins                       | Registry probe, pin style, catalog + recipes + Keel + docs lockstep    |
 
 ## AGENTS.md — the root contract
 
-Every OKE app's repo carries an `AGENTS.md` that agents (Cursor, Claude Code, and peers) read at session start. It is deliberately short and absolute: every backend behavior is a Flow (`on(Trigger) → Effects`), there are eight elements and ten exports, all world access goes through `fx`, drivers are named after protocols, and the ports/budgets are fixed. Its closing rule is the one that keeps agents honest: **if the documentation is silent, stop and ask** — never invent the API.
+Every OKE app's repo carries an `AGENTS.md` that agents (Cursor, Claude Code, and peers) read at session start. It is deliberately short and absolute: every backend behavior is a Flow (`on(Trigger) → Effects`), there are eight elements bound to one contract, all world access goes through `fx`, drivers are named after protocols, and the ports/budgets are fixed. Its closing rule is the one that keeps agents honest: **if the documentation is silent, stop and ask** — never invent the API.
 
 ## Skills — installable know-how
 

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

@@ -129,7 +129,7 @@ const result = await fx.ask(triage, input, {
 });
 ```
 
-External MCP tools take the same path. Declare a server with a **required** allowlist, then pass `server.tool("…")` — never whatever `tools/list` happens to expose:
+External MCP tools take the same path. In OKE, **MCP is a surface of the model, not the model itself** — `ai.mcpServer` models the client role (consuming external tools), while `mcp.tool()` + Gate models the provider role (exposing your flows to agents). Declare a server with a **required** allowlist, then pass `server.tool("…")` — never whatever `tools/list` happens to expose:
 
 ```typescript
 export const github = ai.mcpServer("github", {

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

@@ -141,7 +141,7 @@ reclaimed after its lease expires and continues at the next unfinished step.
 | Guarantee          | What it means                                                                                      |
 | ------------------ | -------------------------------------------------------------------------------------------------- |
 | Leader election    | Instances that share one CronStore fire a given tick once (lease TTL, default 30s)                 |
-| Process identity   | Boot mints one `instanceId` (`inst-<uuid>`) for Clock, Journal, and the fleet registry             |
+| Process identity   | Boot mints one `instanceId` (`inst-<okid>`) for Clock, Journal, and the fleet registry             |
 | Catch-up `"one"`   | Health counts every missed slot; the runtime still fires **once** when overdue — not once per miss |
 | Reconciled at boot | Named clocks land in `oke_crons`; the scheduler reads the Store, not the source                    |
 | DST detection      | Ambiguous local times get a Console warning — schedules are not rewritten or blocked               |

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

@@ -111,7 +111,7 @@ Built-in codes attach a localized `message` ([Errors](/docs/reference/errors));
   — that is the `as never` trap. See [fx](/docs/reference/fx).
 </Callout>
 
-## The five triggers
+## The triggers
 
 <FlowTriggers />
 
@@ -201,6 +201,30 @@ export const getOrder = flow("orders.get", {
 const order = await fx.call(getOrder, { id: orderId }); // from any other flow
 ```
 
+### mcp — an agent calls a tool
+
+`mcp.tool(name)` marks a flow for **OAuth-protected user-plane** exposure over MCP. Deny-by-default: a flow without this trigger is never listed over `tools/list`. A gate is required, exactly like a sensitive HTTP route:
+
+```typescript
+export const createBooking = on(
+  mcp.tool("bookings.create").gate(member), // gates required — deny-by-default
+  flow("bookings.create", {
+    plane: "user",
+    in: BookingRef,
+    out: Booking,
+    do: async ({ id }, fx) => {
+      /* … */
+    },
+  }),
+);
+```
+
+- The tool name is namespaced (`bookings.create`) and appears in the Manifest under `trigger.mcp.name` with its gates.
+- Binding the **same tool name** twice fails boot with **OKE1018** (`MCP tool "{tool}" is bound twice`).
+- Ungated `mcp.tool(...)` fails gate posture at boot (`GateBootError`) — the trigger never exposes an unauthenticated tool.
+
+This is one direction of [MCP](/docs/ai/mcp): exposing your flows as tools. The other is consuming external servers as `ai.mcpServer` tools via `fx.ask` / `ai.agent`.
+
 ## fx — the only door
 
 Everything a flow may touch, on one object:

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

@@ -9,6 +9,8 @@ Gate answers **"may this happen?"** before it happens: is this a verified member
 burned its minute quota? Attach gates to the HTTP trigger — the pipeline checks them before a
 store write, emit, or channel send runs.
 
+> **Same Semantics Across Planes:** OKE does not create separate security models for users, operators, and agents. They enter the same execution model through different triggers and planes: users via sessions, operators via Console policies, and agents via `mcp.tool()` + OAuth 2.1 AS.
+
 <Callout title="The one rule">
   Every HTTP trigger declares posture: attach a real gate, or attach `.public()`. Omitting both
   fails boot. Denial is a typed error value — never a thrown exception mid-`do`.
@@ -63,8 +65,7 @@ import { member, canBook, fair } from "../../gates";
 export const health = on(
   http.get("/health").public(),
   flow("health.check", {
-    out: HealthOut,
-    do: () => ({ ok: true as const }),
+    do: () => ({ ok: true }),
   }),
 );