okengine 0.17.1 → 0.18.3

package/README.md

@@ -16,7 +16,7 @@
   <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>
@@ -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
@@ -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,6 +1,6 @@
 {
   "name": "okengine",
-  "version": "0.17.1",
+  "version": "0.18.3",
   "description": "One law. Eight elements. Ten exports. One package. One manifest. Every backend need is derived, never added.",
   "license": "MIT",
   "repository": {
@@ -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,15 +124,18 @@
     "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",
     "site:build": "bun run --cwd site build",
+    "verify": "bun run lint && bun run fmt:check && bun run typecheck && bun run test && bun run gate && bun run site:build",
     "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/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: