okengine 0.23.0 → 0.23.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okengine",
-  "version": "0.23.0",
+  "version": "0.23.2",
   "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
@@ -52,16 +52,16 @@ Two actions are write-class, and each call needs a **fresh, single-use** confirm
 <Steps>
 
 <Step>
-### Request a confirmation token
+### Ask for confirmation
 
-`oke.action.confirm` with the target `tool`, the exact `args`, and a human `reason` — it returns a single-use token.
+The write returns an opaque `confirmationId`. It does not return a token. Confirm from a **different auth session** (`claims.sid`) than the session that will invoke. The same principal is allowed. A confirmation issued on another process is unknown.
 
 </Step>
 
 <Step>
 ### Call the write tool
 
-Pass the token as `confirmToken` plus the phrase `CONFIRM` in `confirmation`. Token, phrase, args, and principal must all match what was confirmed.
+`oke.action.confirm(confirmationId, reason)` returns a single-use token. Pass it as `confirmToken` plus the phrase `CONFIRM`. The invoking session must be the one that asked, and it must not be the session that confirmed.
 
 </Step>
 

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/broadcast.mdx

@@ -12,8 +12,10 @@ For developers invalidating caches or syncing in-process state — declare the S
 more `on(signal, flow)` subscribers, emit with `fx.emit`.
 
 <Callout title="The one rule">
-  Broadcast is ephemeral. If a subscriber is offline or restarts during the emit, it does not
-  receive past events. Use [`live`](/docs/elements/signal/live) when clients need replay. Use
+  Broadcast is ephemeral. Each running instance handles a message once. If a subscriber is offline
+  during the emit, it does not receive that event. Postgres delivery is best-effort within `lagMs`
+  (default 30 seconds): a transaction that commits later than that can be missed. Use
+  [`live`](/docs/elements/signal/live) when clients need replay. Use
   [`once`](/docs/elements/signal/once) when exactly one worker must claim the job.
 </Callout>
 

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/configuration.mdx

@@ -237,6 +237,22 @@ Domain schema sync for `oke db push | generate | migrate` (Drizzle). Unrelated t
 | `console` | `6533`  | Console |
 | `mcp`     | `6535`  | MCP     |
 
+## App options
+
+These sit on `oke({ ... })`, not in `oke.config.ts`.
+
+| Option               | Default   | Meaning                                                                                                                                                                     |
+| -------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `codeVersion`        | unset     | Opt-in durable stamp `app:<version>`. Unset checks nothing. A stored `0.23.1`-style stamp is compatible and restamped. A different `app:` stamp fails the run with OKE1076. |
+| `maxRequestBodySize` | `1048576` | Body cap in bytes. A route `maxBodySize` overrides it. Bun's listen backstop uses the same number.                                                                          |
+| `cache.maxEntries`   | `10000`   | Auto-cache entry cap.                                                                                                                                                       |
+| `cache.defaultTtlMs` | `60000`   | Auto-cache TTL when the flow does not set `cache: "5m"`.                                                                                                                    |
+| `cache.auto`         | on        | `false` turns automatic caching off. A flow can still opt in.                                                                                                               |
+
+Postgres broadcast and live poll with `lagMs`, default `30000`. That window is best-effort, not a gap-free cursor.
+
+A write drops the auto-cache on every instance. With Redis configured, the notice is published on `oke:cache:invalidate`. Otherwise a Postgres app polls `oke_cache_invalidations`. One process does not broadcast.
+
 ## console
 
 | Option         | Type                                 | Default | Meaning                   |

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

@@ -117,25 +117,37 @@ The typed client always includes built-in codes. A declared key still wins.
 A bare `404` with body `Not Found` means **no route matched**. `fx.fail.notFound` is a JSON envelope
 at **404**. Clients distinguish by envelope, not status. Domain codes stay **400**.
 
-| Code                                             | Status      | Helper                                                 |
-| ------------------------------------------------ | ----------- | ------------------------------------------------------ |
-| `ValidationError`                                | `422`       | none — failed `in`, `do` never runs                    |
-| `IdempotencyKeyMissing`                          | `400`       | none — `idempotency: "required"` and no header         |
-| `IdempotencyKeyInvalid`                          | `400`       | none — header is not 16–255 printable ASCII            |
-| `IdempotencyKeyReused`                           | `422`       | none — same key, different payload                     |
-| `IdempotencyInProgress`                          | `409`       | none — `Retry-After` until the in-flight call finishes |
-| `Unauthorized`                                   | `401`       | `unauthorized` · also a gate denial                    |
-| `Forbidden`                                      | `403`       | `forbidden` · also a gate denial                       |
-| `NotFound`                                       | `404`       | `notFound`                                             |
-| `Conflict` / `ForeignKey`                        | `409`       | `conflict` / `foreignKey`                              |
-| `UnsupportedMediaType`                           | `415`       | none — QUERY `Content-Type` is not `application/json`  |
-| `RateLimited` / `AuthRateLimited`                | `429`       | `rateLimited` · `AuthRateLimited` has none             |
-| `InvalidQuery`                                   | `400`       | none — QUERY missing `Content-Type` or body isn't JSON |
-| `AuthFailed`                                     | `400`       | none — credentials / policy, not “no session”          |
-| `DatabaseError`                                  | by `reason` | `database`                                             |
-| `ServiceUnavailable`                             | `503`       | `serviceUnavailable`                                   |
-| `InternalError`                                  | `500`       | `internal` — never copies a thrown `message`           |
-| Domain (`OutOfStock`, `FlightFull`, `Duplicate`) | `400`       | `fx.fail("OutOfStock", data)`                          |
+| Code                                             | Status      | Helper                                                                       |
+| ------------------------------------------------ | ----------- | ---------------------------------------------------------------------------- |
+| `ValidationError`                                | `422`       | none — failed `in`, `do` never runs                                          |
+| `IdempotencyKeyMissing`                          | `400`       | none — `idempotency: "required"` and no header                               |
+| `IdempotencyKeyInvalid`                          | `400`       | none — header is not 16–255 printable ASCII                                  |
+| `IdempotencyKeyReused`                           | `422`       | none — same key, different payload                                           |
+| `IdempotencyInProgress`                          | `409`       | none — `Retry-After` until the in-flight call finishes                       |
+| `Unauthorized`                                   | `401`       | `unauthorized` · also a gate denial                                          |
+| `Forbidden`                                      | `403`       | `forbidden` · also a gate denial                                             |
+| `NotFound`                                       | `404`       | `notFound`                                                                   |
+| `Conflict` / `ForeignKey`                        | `409`       | `conflict` / `foreignKey`                                                    |
+| `UnsupportedMediaType`                           | `415`       | none — QUERY, or a JSON-shaped body that is not `application/json` / `+json` |
+| `PayloadTooLarge`                                | `413`       | none — body exceeds `maxRequestBodySize` or the route `maxBodySize`          |
+| `RateLimited` / `AuthRateLimited`                | `429`       | `rateLimited` · `AuthRateLimited` has none                                   |
+| `InvalidQuery`                                   | `400`       | none — QUERY or JSON body that does not parse (`malformed_body`)             |
+| `AuthFailed`                                     | `400`       | none — credentials / policy, not “no session”                                |
+| `DatabaseError`                                  | by `reason` | `database`                                                                   |
+| `ServiceUnavailable`                             | `503`       | `serviceUnavailable`                                                         |
+| `InternalError`                                  | `500`       | `internal` — never copies a thrown `message`                                 |
+| Domain (`OutOfStock`, `FlightFull`, `Duplicate`) | `400`       | `fx.fail("OutOfStock", data)`                                                |
+
+`UnsupportedMediaType` (415) is this rule, for a non-empty body. Let `mt` be the media type before `;`:
+
+1. `application/json` or `application/*+json` is parsed. A parse failure is 400 `InvalidQuery` with reason `malformed_body`.
+2. A route with `jsonContentType: "any"` tries JSON and otherwise keeps the raw string.
+3. `text/plain`, form-urlencoded, multipart, or a missing type, when the trimmed body starts with `{` or `[` and parses as JSON, is 415.
+4. Anything else is the raw string. `curl -d` needs `-H 'content-type: application/json'`.
+
+`OKE1074` means the durable run lost its lease. The step result is not written and compensation does not run. The caller sees a busy lease, not a new failure of the work.
+
+`OKE1076` means `codeVersion` was set and the stored stamp is a different `app:` value. Leave the old value pinned until sleeping runs drain, then change it. Unset `codeVersion` checks nothing. A stored stamp from 0.23.1 (no `app:` prefix) is restamped, not failed.
 
 ### Client chrome
 

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/aot.test.ts

@@ -97,6 +97,7 @@ describe("compileAot", () => {
     const bad = await compiled.parseValidate(
       new Request("http://localhost/bookings", {
         method: "POST",
+        headers: { "content-type": "application/json" },
         body: JSON.stringify({ flightId: "SK1", seats: 0 }),
       }),
       {},
@@ -235,9 +236,9 @@ describe("AoT throughput ≥ 1.5× dynamic", () => {
     }
 
     const iterations = 4_000;
-    // Best of trials — single wall-clock ratio is noisy under full-suite load.
+    // Best of trials — a single wall-clock ratio moves under load.
     let best = 0;
-    for (let trial = 0; trial < 3; trial++) {
+    for (let trial = 0; trial < 8; trial++) {
       const t0 = performance.now();
       for (let i = 0; i < iterations; i++) {
         await aot.parseValidate(makeReq(), {});

package/src/compiler/aot.ts

@@ -6,9 +6,11 @@
  * {@link compileDynamic} / `aot: false` on edge runtimes that ban `eval`.
  */
 
+import { fail } from "../kernel/errors.ts";
 import { validate, type SchemaInput } from "../validation/standard-schema.ts";
 import {
   assembleInput,
+  HttpBodyRejected,
   parseBody,
   parseCookie,
   parseHeaders,
@@ -33,6 +35,8 @@ export interface CompileRouteOptions {
   readonly hooks?: ReadonlyArray<(...args: never[]) => unknown>;
   /** Input schema (Standard Schema when present). */
   readonly schema?: SchemaInput | undefined;
+  /** Body cap and JSON content-type policy. */
+  readonly body?: import("./http-parse.ts").ParseBodyOptions;
 }
 
 /** Bundle returned by the compilers. */
@@ -55,6 +59,16 @@ interface AotHelpers {
   parseCookie: typeof parseCookie;
   assembleInput: typeof assembleInput;
   validate: typeof validate;
+  readonly body?: import("./http-parse.ts").ParseBodyOptions;
+  readBody: (
+    request: Request,
+  ) => Promise<
+    { ok: true; value: unknown } | { ok: false; failure: import("../kernel/errors.ts").FlowFailure }
+  >;
+  bodyFailure: (
+    err: unknown,
+    request: Request,
+  ) => { ok: false; failure: import("../kernel/errors.ts").FlowFailure } | undefined;
 }
 
 /**
@@ -82,6 +96,34 @@ export function compileAot(options: CompileRouteOptions): CompiledRoute {
     parseCookie,
     assembleInput,
     validate,
+    body: options.body,
+    async readBody(request: Request) {
+      try {
+        return { ok: true as const, value: await parseBody(request, options.body) };
+      } catch (err) {
+        const rejected = this.bodyFailure(err, request);
+        if (rejected) return rejected;
+        throw err;
+      }
+    },
+    bodyFailure(err, request) {
+      if (!(err instanceof HttpBodyRejected)) return undefined;
+      if (err.code === "InvalidQuery") {
+        return {
+          ok: false,
+          failure: fail("InvalidQuery", { reason: err.reason ?? "malformed_body" }),
+        };
+      }
+      if (err.code === "UnsupportedMediaType") {
+        return {
+          ok: false,
+          failure: fail("UnsupportedMediaType", {
+            contentType: request.headers.get("content-type") ?? "",
+          }),
+        };
+      }
+      return { ok: false, failure: fail("PayloadTooLarge", {}) };
+    },
   };
 
   try {
@@ -122,7 +164,9 @@ function generateParseValidate(
     lines.push("parts.cookie = helpers.parseCookie(request);");
   }
   if (inference.body) {
-    lines.push("parts.body = await helpers.parseBody(request);");
+    lines.push("const bodyResult = await helpers.readBody(request);");
+    lines.push("if (bodyResult.ok === false) return bodyResult;");
+    lines.push("parts.body = bodyResult.value;");
   }
 
   lines.push("const raw = helpers.assembleInput(parts);");

package/src/compiler/dynamic.ts

@@ -28,7 +28,7 @@ function loadAot(): typeof import("./aot.ts") {
 export function compileDynamic(options: CompileRouteOptions): CompiledRoute {
   return {
     inference: FULL_INFERENCE,
-    parseValidate: createInterpretedParseValidate(FULL_INFERENCE, options.schema),
+    parseValidate: createInterpretedParseValidate(FULL_INFERENCE, options.schema, options.body),
     aot: false,
   };
 }