okengine 0.23.0 → 0.23.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okengine",
-  "version": "0.23.0",
+  "version": "0.23.1",
   "description": "One law. Eight elements. One contract. The backend model stays small; operational surfaces are derived from it instead of maintained separately.",
   "license": "Apache-2.0",
   "repository": {

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

@@ -16,7 +16,7 @@ Two genuinely distinct things share the protocol in OKE:
 
 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.
+The server on **6535** speaks JSON-RPC over HTTP. It implements `initialize`, `ping`, `tools/list`, and `tools/call`, and advertises protocol `2024-11-05`. A client that sends another `protocolVersion` is rejected. An omitted version gets `2024-11-05`. It requires a Bearer token **even on localhost**, and never forwards that token upstream — adapters receive structured operator ids instead. The outbound client that calls external MCP servers probes `2026-07-28` (`_meta` on each request) and falls back to a `2024-11-05` `initialize`. That probe is not what this server advertises.
 
 <Callout title="The one rule">
   MCP inherits the operator's capability and can never exceed it. Server-level controls alone are

package/site/content/docs/elements/channel/index.mdx

@@ -247,7 +247,7 @@ overrides). Manifest stays free of copy.
 | Method                     | Capability / `sends` | Meaning                                     |
 | -------------------------- | -------------------- | ------------------------------------------- |
 | `fx.send(template, opts?)` | template name        | Deliver through the medium’s driver chain   |
-| `fx.sendOtp(opts)`         | `"sms-otp"`          | Provider-managed SMS OTP (Taqnyat Verify)   |
+| `fx.sendOtp(opts)`         | `"sms-otp"`          | Provider-managed SMS OTP.                   |
 | `fx.verifyOtp(opts)`       | `"sms-otp"`          | Check a provider OTP code                   |
 | `fx.deliverOtp(opts)`      | `"auth-otp"`         | App-owned OTP across email / SMS / WhatsApp |
 
@@ -351,9 +351,9 @@ Env knobs: [Environment variables](/docs/reference/environment-variables). Local
 </Accordion>
 
 <Accordion title="Process-local suppression / receipts warning">
-  Boot warns: `Channel suppression/consent/receipts default to process-local memory…` Opt-out on one
-  instance is invisible to others until you inject shared stores or run a single Channel consumer.
-  See [Receipts](/docs/elements/channel/receipts).
+  Boot warns: `Channel suppression/consent/receipts default to process-local memory…` That is
+  `test`, or a boot with no `DATABASE_URL`. Otherwise consent, suppression, and receipts are the
+  Postgres ledger. See [Receipts](/docs/elements/channel/receipts).
 </Accordion>
 
 </Accordions>

package/site/content/docs/elements/channel/receipts.mdx

@@ -1,21 +1,23 @@
 ---
 title: "Receipts"
-description: "Delivery ledger, seven-state outcomes, consent opt-out, and hard-bounce suppression — process-local by default."
+description: "Delivery ledger, seven-state outcomes, consent opt-out, and hard-bounce suppression."
 icon: "ReceiptText"
 source: "docs/spec/unified-theory.md"
 ---
 
 Every Channel send records a **receipt** — success (`sent` / `fallback`), suppression, or a
 classified failure. Provider bounces and complaints update that ledger through normalized
-outcomes. There is no `oke_receipts` SQL table and no `fx.channel.getReceipt` helper.
+outcomes. There is no `fx.channel.getReceipt` helper. Outside `test`, boot stores consent,
+suppression, and receipts in Postgres (`oke_channel_consent`, `oke_channel_bounce`,
+`oke_channel_receipt`) when `DATABASE_URL` is set. `test` stays in memory.
 
 For operators watching deliverability — Console projects the ledger; Flows only see send
 results via `fx.send`’s `{ ok: true }` gate.
 
 <Callout title="The one rule">
-  Consent and prior hard bounces suppress **before** any driver runs. Default suppression / consent
-  / receipts stores are **process-local memory** — inject shared stores for multi-instance, or run a
-  single Channel consumer, until a durable driver ships.
+  Consent and prior hard bounces suppress **before** any driver runs. With `DATABASE_URL` outside
+  `test`, those rows are shared across instances. `test`, and any boot without a SQL URL, keep
+  process-local memory and still warn.
 </Callout>
 
 ## Smallest Example

package/site/content/docs/elements/channel/sms.mdx

@@ -7,7 +7,8 @@ source: "docs/spec/unified-theory.md"
 
 SMS (`channel.sms`) delivers short text and provider-managed one-time codes. Pin an SMS driver
 (no default in any env), declare templates for app-owned messages, or call `fx.sendOtp` when the
-vendor owns the code.
+vendor owns the code. `fx.sendOtp` and `fx.verifyOtp` stay on `fx`. The `mena` plugin opens the
+same providers when you want that packaging.
 
 For developers verifying phones — choose raw Channel OTP vs the [`otp`](/docs/plugins/otp) plugin.
 

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

@@ -220,17 +220,17 @@ Second argument to `flow(name, options)` — or the only argument to a nameless
 Invoke contracts (`in` / `out` / `errors` / `breaking`) belong on the exposure — see
 [Contracts](#contracts) below.
 
-| Option         | Type                                   | Default                   | Meaning                                                                         |
-| -------------- | -------------------------------------- | ------------------------- | ------------------------------------------------------------------------------- |
-| `do`           | `(input, fx) => output \| FlowFailure` | _(required)_              | Handler. Missing `do` throws `flow() expected an options bag with a do handler` |
-| `durable`      | `boolean`                              | `false`                   | Journal `fx.step` / sleep / gated `fx` calls                                    |
-| `retry`        | `FxRetryOptions`                       | omitted                   | Whole-`do` retry on throw (same journal when durable)                           |
-| `cache`        | `boolean \| string`                    | omitted (auto)            | Read-only Flows cache automatically; `false` opts out; `"30s"` adds TTL         |
-| `compensate`   | `(ctx, fx) => unknown`                 | omitted                   | After LIFO `{ undo }`, before the run commits `failed`                          |
-| `plane`        | `"user" \| "operator"`                 | `"user"`                  | Operator bypasses RLS; user must not `fx.call` operator                         |
-| `effects`      | `Effects`                              | inferred                  | Capability token — write this only when inference cannot see the body           |
-| `slo`          | `{ availability?, latency? }`          | omitted                   | Manifest metadata (Console / docs)                                              |
-| `tenantScoped` | `boolean`                              | `true` when tenancy is on | `false` skips tenant-role scope union                                           |
+| Option         | Type                                   | Default                   | Meaning                                                                                                          |
+| -------------- | -------------------------------------- | ------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `do`           | `(input, fx) => output \| FlowFailure` | _(required)_              | Handler. Missing `do` throws `flow() expected an options bag with a do handler`                                  |
+| `durable`      | `boolean`                              | `false`                   | Journal `fx.step` / sleep / gated `fx` calls                                                                     |
+| `retry`        | `FxRetryOptions`                       | omitted                   | Whole-`do` retry on throw (same journal when durable)                                                            |
+| `cache`        | `boolean \| string`                    | omitted (on when pure)    | Pure store reads cache; `false` disables; `"30s"` sets a TTL; app `cache: { auto: false }` turns the default off |
+| `compensate`   | `(ctx, fx) => unknown`                 | omitted                   | After LIFO `{ undo }`, before the run commits `failed`                                                           |
+| `plane`        | `"user" \| "operator"`                 | `"user"`                  | Operator bypasses RLS; user must not `fx.call` operator                                                          |
+| `effects`      | `Effects`                              | inferred                  | Capability token — write this only when inference cannot see the body                                            |
+| `slo`          | `{ availability?, latency? }`          | omitted                   | Manifest metadata (Console / docs)                                                                               |
+| `tenantScoped` | `boolean`                              | `true` when tenancy is on | `false` skips tenant-role scope union                                                                            |
 
 **Consequence:** `durable: true` disables automatic read-cache for that Flow.
 
@@ -438,12 +438,12 @@ durable Flow, or split with `fx.emit`. See [Workflows](/docs/elements/flow/workf
 
 <Tab value="Cache">
 
-Read-only Flows (Store `reads`, no `writes`, no `asks`, not durable) cache automatically.
-No `cache:` option required. Mutations and `durable: true` stay uncached:
+A pure store-read Flow caches on its own. A send, emit, fetch, vault read, ask,
+decide, or `fx.call` is never cached. The key includes the flow, the input, the
+user, the tenant, the locale, and the caller's scopes and membership roles.
 
 ```typescript
 flow("catalog.get", {
-  cache: "30s",
   do: async ({ id }, fx) => {
     const [row] = await fx.store(db).select().from(products).where(eq(products.id, id));
     return row;
@@ -451,7 +451,10 @@ flow("catalog.get", {
 });
 ```
 
-`cache: false` opts out. A duration string adds TTL on top of write invalidation.
+`cache: false` always disables. A duration string adds TTL on top of write
+invalidation. `oke({ cache: { auto: false } })` turns the default off; a Flow
+can still set `cache: true` or `"30s"`. Cross-instance invalidation and writes
+that skip `fx` are not covered.
 
 </Tab>
 
@@ -570,9 +573,10 @@ Default is `true` once `gate.auth.tenant` is on.
 </Accordion>
 
 <Accordion title="Read-only Flow never cache-hits">
-  Auto-cache needs Store `reads`, no `writes`, no `asks`, and `durable` off. Empty effect sets stay
-  uncached. Opt in with a duration (`cache: "30s"`) only after a real read is inferred — or pass
-  `cache: false` to disable.
+  A pure Store read caches unless the Flow sets `cache: false` or the app sets
+  `cache: { auto: false }`. A send, emit, fetch, secret, ask, decide, call, or write
+  is never cached, and `durable: true` is never cached. The key includes tenant,
+  locale, scopes, and roles, so a hit for one caller is a miss for another.
 </Accordion>
 
 <Accordion title='cross-plane call: user flow "…" calls operator flow "…"'>

package/site/content/docs/elements/signal/index.mdx

@@ -331,11 +331,11 @@ Omit `key` for a pure competing pool with no ordering.
 Protocol ids: `memory` · `redis` · `postgres` · `nats`. Defaults (when `oke.config.ts` omits
 `drivers.signal`):
 
-| Env    | Default  | Boot today                                                              |
-| ------ | -------- | ----------------------------------------------------------------------- |
-| `dev`  | `redis`  | Emit relays to Redis; consume / live / drain use a process-local outbox |
-| `test` | `memory` | In-process bus                                                          |
-| `prod` | `redis`  | Same redis honesty as `dev`                                             |
+| Env    | Default  | Boot today                                                                       |
+| ------ | -------- | -------------------------------------------------------------------------------- |
+| `dev`  | `redis`  | Emit relays to Redis. `once` consume is a consumer group (`XREADGROUP` / `XACK`) |
+| `test` | `memory` | In-process bus                                                                   |
+| `prod` | `redis`  | Same redis path as `dev`                                                         |
 
 ```typescript title="oke.config.ts"
 export default defineConfig({
@@ -345,8 +345,10 @@ export default defineConfig({
 });
 ```
 
-`postgres` and `nats` fail loud at boot until a native bind ships — never silently fall back to
-`memory`. Prefer `memory` for tests; pin `redis` when Compose provides Redis.
+`postgres` binds Bun.SQL and the scheduler polls `drain` (`FOR UPDATE SKIP LOCKED`). Bun.SQL has no
+`LISTEN` / `NOTIFY`. `nats` still fails loud at boot — never silently fall back to `memory`. Prefer
+`memory` for tests; pin `redis` when Compose provides Redis. Live history stays on the emitting
+process; `once` is the competing path.
 
 ## Troubleshooting
 
@@ -383,15 +385,14 @@ export default defineConfig({
   consumers](#competing-consumers-once-vs-broadcast).
 </Accordion>
 
-<Accordion title='oke boot: signal driver "postgres" / "nats"'>
-  Those ids are reserved but not bound for production yet. Use `"memory"` or `"redis"`, or inject a
-  custom `elements.signal` runtime.
+<Accordion title='oke boot: signal driver "postgres" needs DATABASE_URL'>
+  `drivers.signal` is `postgres` and neither `DATABASE_URL` nor `OKE_STORE_SQL_URL` is set. Boot
+  polls `drain` on that connection. There is no `LISTEN` / `NOTIFY` requirement.
 </Accordion>
 
-<Accordion title="redis Signal — process-local consume">
-  Boot warns that redis emit relays to Redis while consume / live / drain stay process-local.
-  Multi-instance competing consumers need a shared durable outbox path (or a single consumer
-  instance) until Redis Streams consume ships.
+<Accordion title='oke boot: signal driver "nats"'>
+  `nats` has no production client yet. Use `"memory"`, `"redis"`, or `"postgres"`, or inject a
+  custom `elements.signal` runtime.
 </Accordion>
 
 </Accordions>

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

@@ -22,9 +22,9 @@ app-owned delivery across the channels you declare.
 </Callout>
 
 <Callout type="info" title="fx.sendOtp vs otp()">
-  `fx.sendOtp` / `fx.verifyOtp` are raw Channel capabilities — no `.plug()`. Direct use means you
-  build routes, sessions, rates, and storage yourself. `otp()` provider mode wraps that path; skip
-  it and call the raw methods in your own flow without losing the provider connection.
+  `fx.sendOtp` / `fx.verifyOtp` / `fx.deliverOtp` are supported Channel methods. Direct use means
+  you build routes, sessions, rates, and storage yourself. `otp()` provider mode wraps that path.
+  The `mena` plugin (`menaChannels`) is an additional way to open the same providers.
 </Callout>
 
 ## Quick start

package/site/content/docs/reference/fx.mdx

@@ -158,7 +158,13 @@ on(
 | `fx.auth.upsertTenantRole({ tenantId, roleName, scopes })`                     | `write` `auth:tenants`  | Application scopes only — `console:*` is unknown_scope                                             |
 
 `fx.call` starts the callee with an **empty** `fx.auth` (fail-closed) and propagates `fx.tenant.id`.
-Read `fx.principal` for audit — it does not copy into `fx.auth`.
+Read `fx.principal` for audit — it does not copy into `fx.auth`. Passing a Flow handle types
+`input` and the result. A string name stays `Promise<unknown>`.
+
+`fx.store(db).transaction(async (tx) => { … })` pins one SQL connection. `fx.emit` inside the
+callback stages on the signal outbox and publishes after commit. A throw rolls that batch back.
+`fx.store(db).run(builder)` runs a Drizzle builder through `toSQL()`. Joins stay on that builder;
+the hand-rolled chain does not grow a join API. Inference still records every joined table.
 
 <Callout>
   Gates never consult `fx.principal`. `return fx.fail(...)` is a `FlowFailure`; an unhandled `throw`
@@ -281,9 +287,11 @@ Durations: `"200ms"` · `"30s"` · `"2m"` · `"1h"` · `"7d"`. A `"d"` is 86_400
 
 ## Cache
 
-Read-only flows cache automatically from inferred or ledgered `reads` — no
-`fx.cache` call and no `cache:` default on the flow. Writes invalidate those
-keys. Use `cache: false` to opt out, or `cache: "30s"` for a TTL.
+Pure store-read flows cache by default. A send, emit, fetch, vault read, ask,
+decide, or `fx.call` is never cached. The key includes tenant, locale, scopes,
+and membership roles. Writes through `fx` invalidate those keys. `cache: false`
+always disables. `oke({ cache: { auto: false } })` turns the default off.
+Cross-instance invalidation and out-of-band writes are not covered.
 
 `fx.cache` is the manual (tier-3) surface:
 

package/src/auth/tenants.ts

@@ -359,3 +359,20 @@ export function tenantScopesForMember(
   const role = store.roles.get(roleKey(tenantId, member.role));
   return role?.scopes ?? [];
 }
+
+/**
+ * Membership role name for the tier-1 cache key.
+ *
+ * Same member lookup as {@link tenantScopesForMember}. Not an authorization input.
+ *
+ * @param store - Tenant store
+ * @param tenantId - Tenant id
+ * @param userId - User id
+ */
+export function tenantRoleForMember(
+  store: TenantStore,
+  tenantId: string,
+  userId: string,
+): string | null {
+  return getMember(store, tenantId, userId)?.role ?? null;
+}

package/src/cli/doctor-diff.test.ts

@@ -7,7 +7,7 @@ import { mkdir, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import type { Manifest } from "../manifest/types.ts";
 import { parseManifest } from "../manifest/validate.ts";
-import { runDoctorDiff } from "./doctor-diff.ts";
+import { formatManifestDiffComment, runDoctorDiff } from "./doctor-diff.ts";
 
 const baseUrl = new URL("../manifest/fixtures/base.manifest.json", import.meta.url);
 
@@ -84,4 +84,32 @@ describe("oke doctor --diff", () => {
       await rm(dir, { recursive: true, force: true });
     }
   });
+
+  test("comment lists contract, permission, and effect changes", () => {
+    const body = formatManifestDiffComment([
+      {
+        path: "flows.a",
+        category: "contract-breaking",
+        kind: "changed",
+        summary: "out schema changed",
+      },
+      {
+        path: "flows.b",
+        category: "permission-widening",
+        kind: "changed",
+        summary: "gate removed",
+      },
+      {
+        path: "flows.c",
+        category: "effect-widening",
+        kind: "changed",
+        summary: "writes grew",
+      },
+    ]);
+    expect(body).toContain("Contract breaks");
+    expect(body).toContain("Permission widening");
+    expect(body).toContain("Effect widening");
+    expect(body).toContain("out schema changed");
+    expect(body).toContain("widening are comments only");
+  });
 });

package/src/cli/doctor-diff.ts

@@ -55,6 +55,41 @@ export interface DoctorDiffResult {
   readonly allChanges: readonly ManifestChange[];
 }
 
+const COMMENT_CATEGORIES = ["contract-breaking", "permission-widening", "effect-widening"] as const;
+
+const CATEGORY_LABEL: Record<(typeof COMMENT_CATEGORIES)[number], string> = {
+  "contract-breaking": "Contract breaks",
+  "permission-widening": "Permission widening",
+  "effect-widening": "Effect widening",
+};
+
+/**
+ * Plain-language pull-request comment for the three behavioural categories.
+ * Widening is informational. Contract breaks are the lines that fail CI
+ * when they are undeclared.
+ *
+ * @param changes - {@link diffManifest} changes
+ */
+export function formatManifestDiffComment(changes: readonly ManifestChange[]): string {
+  const lines = ["## Manifest diff", ""];
+  for (const category of COMMENT_CATEGORIES) {
+    const rows = changes.filter((change) => change.category === category);
+    lines.push(`### ${CATEGORY_LABEL[category]}`);
+    if (rows.length === 0) {
+      lines.push("None.");
+    } else {
+      for (const row of rows) {
+        lines.push(`- \`${row.path}\` — ${row.summary}`);
+      }
+    }
+    lines.push("");
+  }
+  lines.push(
+    "Undeclared contract breaks fail the check. Permission and effect widening are comments only. Acknowledge an intentional break with `breaking: true` on the HTTP, call, MCP, or resource contract.",
+  );
+  return lines.join("\n");
+}
+
 /**
  * Diff two manifests and fail on undeclared contract breaks.
  *

package/src/cli/manifest-pr-diff.ts

@@ -0,0 +1,16 @@
+/**
+ * Pull-request manifest diff.
+ *
+ * Writes the comment body, then exits non-zero only for undeclared
+ * contract breaks. Widening changes stay in the comment.
+ *
+ *   bun src/cli/manifest-pr-diff.ts comment.md
+ */
+
+import { writeFileSync } from "node:fs";
+import { formatManifestDiffComment, runDoctorDiff } from "./doctor-diff.ts";
+
+const out = process.argv[2] ?? "manifest-diff.md";
+const result = await runDoctorDiff({ write: () => {} });
+writeFileSync(out, formatManifestDiffComment(result.allChanges));
+process.exit(result.code);

package/src/compiler/effects-fetch.test.ts

@@ -3,6 +3,7 @@
  */
 
 import { describe, expect, test } from "bun:test";
+import { extractFromSources } from "./extract.ts";
 import { inferEffects, type AstNode, type InferBinding } from "./effects-infer.ts";
 
 function parseDo(src: string): AstNode {
@@ -39,5 +40,81 @@ describe("inferEffects — fx.fetch → effects.fetches", () => {
     expect(inferred.effects.fetches).toEqual(["api.stripe.com"]);
     expect(inferred.effects.calls).toBeUndefined();
     expect(inferred.effects.sends).toBeUndefined();
+    expect(inferred.bareIrreversible).toEqual(["fetch"]);
+  });
+
+  test("fx.fetch inside fx.step is not a bare irreversible call", () => {
+    const stepBody = {
+      type: "ArrowFunctionExpression",
+      params: [],
+      body: {
+        type: "BlockStatement",
+        body: [
+          {
+            type: "ExpressionStatement",
+            expression: {
+              type: "CallExpression",
+              callee: {
+                type: "MemberExpression",
+                object: { type: "Identifier", name: "fx" },
+                property: { type: "Identifier", name: "fetch" },
+                computed: false,
+              },
+              arguments: [{ type: "Literal", value: "https://example.com/data" }],
+            },
+          },
+        ],
+      },
+    };
+    const inferred = inferEffects({
+      doNode: {
+        type: "ArrowFunctionExpression",
+        params: [
+          { type: "Identifier", name: "_input" },
+          { type: "Identifier", name: "fx" },
+        ],
+        body: {
+          type: "BlockStatement",
+          body: [
+            {
+              type: "ExpressionStatement",
+              expression: {
+                type: "CallExpression",
+                callee: {
+                  type: "MemberExpression",
+                  object: { type: "Identifier", name: "fx" },
+                  property: { type: "Identifier", name: "step" },
+                  computed: false,
+                },
+                arguments: [{ type: "Literal", value: "load" }, stepBody],
+              },
+            },
+          ],
+        },
+      } as AstNode,
+      bindings: new Map<string, InferBinding>(),
+      hasExplicitEffects: false,
+    });
+    expect(inferred.bareIrreversible).toEqual([]);
+    expect(inferred.steps).toEqual(["load"]);
+    expect(inferred.effects.fetches).toEqual(["example.com"]);
+  });
+});
+
+describe("extract — durable fx.fetch outside fx.step", () => {
+  test("OKE1901 when a durable flow calls fx.fetch directly", async () => {
+    await expect(
+      extractFromSources({
+        "src/flows/load.ts": `
+import { flow, on, http } from "okengine";
+export const load = on(http.get("/load"), flow("load", {
+  durable: true,
+  do: async (_input, fx) => {
+    return fx.fetch("https://example.com/data");
+  },
+}));
+`,
+      }),
+    ).rejects.toThrow(/OKE1901/);
   });
 });