@classytic/arc 2.41.1 → 2.43.0

package/dist/{validate-DrYWnOzI.mjs → validate-9yzHC1e2.mjs}

@@ -1,5 +1,6 @@
-/*! @classytic/arc v2.41.1 | MIT | https://classytic.com */
-import { t as __exportAll } from "./rolldown-runtime-eysyzFAF.mjs";
+/*! @classytic/arc v2.43.0 | MIT | https://classytic.com */
+import { t as __exportAll } from "./rolldown-runtime-D1w9Y1VJ.mjs";
+import { _ as pathTouchesBlocked } from "./plugin-BccET1tL.mjs";
 //#region src/core/aggregation/normalize.ts
 /**
 * Framework cap on URL-driven aggregation limits when the host opts
@@ -180,11 +181,7 @@ function buildCacheOptions(config) {
 function buildExecutionHints(config) {
 	const hints = {};
 	if (typeof config.timeout === "number" && config.timeout > 0) hints.maxTimeMs = config.timeout;
-	if (config.indexHint && config.indexHint.leadingKeys.length > 0) {
-		const hintObj = {};
-		for (const key of config.indexHint.leadingKeys) hintObj[key] = 1;
-		hints.indexHint = hintObj;
-	}
+	if (config.indexHint && config.indexHint.leadingKeys.length > 0) hints.indexHint = { leadingKeys: [...config.indexHint.leadingKeys] };
 	return Object.keys(hints).length > 0 ? hints : void 0;
 }
 //#endregion
@@ -445,13 +442,8 @@ function validateFieldReferences(input) {
 function assertFieldAllowed(context, ref, input) {
 	const { resourceName, aggregationName, lookupAliases, blockedFields } = input;
 	const dot = ref.indexOf(".");
-	if (dot > 0) {
-		const alias = ref.slice(0, dot);
-		if (lookupAliases.has(alias)) return;
-		if (blockedFields.has(alias)) throw new ArcAggregationConfigError(`Resource "${resourceName}" aggregation "${aggregationName}" references field "${ref}" in ${context} whose root "${alias}" is blocked from aggregation (\`hidden: true\` or \`aggregable: false\` in schemaOptions.fieldRules). Aggregating hidden fields would leak cardinality information.`);
-		return;
-	}
-	if (blockedFields.has(ref)) throw new ArcAggregationConfigError(`Resource "${resourceName}" aggregation "${aggregationName}" references field "${ref}" in ${context}, but the field is blocked from aggregation (\`hidden: true\` or \`aggregable: false\` in schemaOptions.fieldRules). Aggregating hidden fields would leak cardinality information.`);
+	if (dot > 0 && lookupAliases.has(ref.slice(0, dot))) return;
+	if (pathTouchesBlocked(ref, blockedFields, { descendants: true })) throw new ArcAggregationConfigError(`Resource "${resourceName}" aggregation "${aggregationName}" references field "${ref}" in ${context}, but the field is blocked from aggregation (\`hidden: true\` or \`aggregable: false\` in schemaOptions.fieldRules). Aggregating hidden fields would leak cardinality information.`);
 }
 //#endregion
 export { compileAggRequest as i, validateAggregations as n, validate_exports as r, adapterSupportsAggregate as t };

package/dist/{versioning-D6JIK8Tk.d.mts → versioning-Bsb51gGT.d.mts}

@@ -1,5 +1,5 @@
 
-import { n as DomainEvent } from "./EventTransport-CbUKDzZZ.mjs";
+import { n as DomainEvent } from "./EventTransport-CiicKz2Z.mjs";
 import { FastifyPluginAsync, FastifyRequest } from "fastify";
 //#region src/plugins/gracefulShutdown.d.ts
 interface GracefulShutdownOptions {
@@ -46,7 +46,6 @@ interface ShutdownState {
   /** When draining began. */
   readonly since?: Date;
 }
-declare const gracefulShutdownPlugin: FastifyPluginAsync<GracefulShutdownOptions>;
 declare module "fastify" {
   interface FastifyInstance {
     /** Trigger graceful shutdown manually */
@@ -82,7 +81,6 @@ interface CachingOptions {
   /** Custom cache rules per path prefix */
   rules?: CachingRule[];
 }
-declare const cachingPlugin: FastifyPluginAsync<CachingOptions>;
 declare const _default$4: FastifyPluginAsync<CachingOptions>;
 //#endregion
 //#region src/plugins/sse.d.ts
@@ -95,7 +93,22 @@ interface SSEOptions {
   patterns?: string[];
   /** Heartbeat interval in ms (default: 30000) */
   heartbeat?: number;
-  /** Filter events by organizationId from request.scope (default: false) */
+  /**
+   * Deliver an event carrying `meta.organizationId` only to callers in that
+   * organization (default: **true** since 2.41.1).
+   *
+   * It defaulted to `false`, and with `patterns: ['*']` that meant a signed-in
+   * member of one tenant received every other tenant's domain events — CRUD
+   * events carry the full document as `data`. In a framework whose other
+   * defaults fail closed, the stream was the one door left open.
+   *
+   * Flipping it costs single-tenant apps nothing: events with no
+   * `organizationId` are delivered to every caller either way. An elevated
+   * platform admin with NO active organization still sees every tenant — the
+   * same rule `checkOrgScope` applies to elevated reads. Set `false` only for a
+   * stream that is deliberately cross-tenant (an internal ops console), and
+   * put `requireAuth` plus a `filter` in front of it.
+   */
   orgScoped?: boolean;
   /** Custom event filter function */
   filter?: (event: DomainEvent<unknown>, request: FastifyRequest) => boolean;
@@ -107,7 +120,6 @@ interface SSEOptions {
    */
   tokenQueryParam?: string | null;
 }
-declare const ssePlugin: FastifyPluginAsync<SSEOptions>;
 declare const _default$3: FastifyPluginAsync<SSEOptions>;
 //#endregion
 //#region src/plugins/realtime.d.ts
@@ -148,13 +160,21 @@ interface RealtimeOptions {
    */
   maxConnectionMs?: number;
 }
-declare const realtimePlugin: FastifyPluginAsync<RealtimeOptions>;
 declare const _default$2: FastifyPluginAsync<RealtimeOptions>;
 //#endregion
+//#region src/utils/metricSeries.d.ts
+interface MetricSample {
+  labels: Record<string, string>;
+  value: number;
+  suffix?: "_bucket" | "_sum" | "_count";
+}
+//#endregion
 //#region src/plugins/metrics.d.ts
 interface MetricsOptions {
   /** Endpoint path (default: '/_metrics') */
   path?: string;
+  /** Maximum label sets per metric, plus one overflow series (default: 1000). */
+  maxSeries?: number;
   /** Prefix for all metric names (default: 'arc') */
   prefix?: string;
   /** Called after metrics are collected (for OTLP push, etc.) */
@@ -164,10 +184,7 @@ interface MetricEntry {
   name: string;
   type: "counter" | "histogram" | "gauge";
   help: string;
-  values: Array<{
-    labels: Record<string, string>;
-    value: number;
-  }>;
+  values: MetricSample[];
 }
 interface MetricsCollector {
   /** Get all metrics as structured data */
@@ -192,7 +209,6 @@ declare module "fastify" {
     metrics: MetricsCollector;
   }
 }
-declare const metricsPlugin: FastifyPluginAsync<MetricsOptions>;
 declare const _default$1: FastifyPluginAsync<MetricsOptions>;
 //#endregion
 //#region src/plugins/versioning.d.ts
@@ -225,7 +241,6 @@ declare module "fastify" {
     apiVersion: string;
   }
 }
-declare const versioningPlugin: FastifyPluginAsync<VersioningOptions>;
 declare const _default: FastifyPluginAsync<VersioningOptions>;
 //#endregion
-export { gracefulShutdownPlugin as C, _default$5 as S, CachingRule as _, MetricsCollector as a, GracefulShutdownOptions as b, metricsPlugin as c, _default$2 as d, realtimePlugin as f, CachingOptions as g, ssePlugin as h, MetricEntry as i, ChangeOperation as l, _default$3 as m, _default as n, MetricsOptions as o, SSEOptions as p, versioningPlugin as r, _default$1 as s, VersioningOptions as t, RealtimeOptions as u, _default$4 as v, ShutdownState as x, cachingPlugin as y };
+export { _default$5 as _, MetricsOptions as a, RealtimeOptions as c, _default$3 as d, CachingOptions as f, ShutdownState as g, GracefulShutdownOptions as h, MetricsCollector as i, _default$2 as l, _default$4 as m, _default as n, _default$1 as o, CachingRule as p, MetricEntry as r, ChangeOperation as s, VersioningOptions as t, SSEOptions as u };

package/dist/{versioning-DKkT4hNJ.mjs → versioning-fhhWHV74.mjs}

@@ -1,6 +1,6 @@
-/*! @classytic/arc v2.41.1 | MIT | https://classytic.com */
-import { t as __exportAll } from "./rolldown-runtime-eysyzFAF.mjs";
-import { d as createDomainError } from "./errors-BH7YU_9O.mjs";
+/*! @classytic/arc v2.43.0 | MIT | https://classytic.com */
+import { t as __exportAll } from "./rolldown-runtime-D1w9Y1VJ.mjs";
+import { d as createDomainError } from "./errors-CtrywMHP.mjs";
 import fp from "fastify-plugin";
 //#region src/plugins/versioning.ts
 var versioning_exports = /* @__PURE__ */ __exportAll({
@@ -40,4 +40,4 @@ var versioning_default = fp(versioningPlugin, {
 	fastify: "5.x"
 });
 //#endregion
-export { versioning_default as n, versioning_exports as r, versioningPlugin as t };
+export { versioning_exports as n, versioning_default as t };

package/dist/{websocket-BOXVggMf.d.mts → websocket-Cs4awVyD.d.mts}

@@ -1,5 +1,5 @@
 
-import { a as PushRefRegistry, l as EnvelopeWriter, s as PushRefStore } from "./pushref-registry-Dov9l4qE.mjs";
+import { a as PushRefRegistry, l as EnvelopeWriter, s as PushRefStore } from "./pushref-registry-UxCkoA4C.mjs";
 import { FastifyBaseLogger, FastifyPluginAsync } from "fastify";
 //#region src/integrations/websocket/adapter.d.ts
 /**

package/dist/{workScope-CxKqoIFn.mjs → workScope-zpPyge4t.mjs}

@@ -1,5 +1,5 @@
-/*! @classytic/arc v2.41.1 | MIT | https://classytic.com */
-import { n as requestContext } from "./requestContext-cDkAUr-P.mjs";
+/*! @classytic/arc v2.43.0 | MIT | https://classytic.com */
+import { n as requestContext } from "./requestContext-Dsu9P1bV.mjs";
 //#region src/context/workScope.ts
 /** Enter a scope for `fn`, or run it inside the active one. */
 function runWorkScope(seed, fn) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/arc",
-  "version": "2.41.1",
+  "version": "2.43.0",
   "description": "Resource-oriented backend framework for Fastify - clean, minimal, powerful, tree-shakable",
   "type": "module",
   "exports": {
@@ -208,10 +208,6 @@
       "types": "./dist/auth/audit.d.mts",
       "default": "./dist/auth/audit.mjs"
     },
-    "./sync": {
-      "types": "./dist/sync/changelog.d.mts",
-      "default": "./dist/sync/changelog.mjs"
-    },
     "./usage": {
       "types": "./dist/usage/index.d.mts",
       "default": "./dist/usage/index.mjs"
@@ -227,6 +223,10 @@
     "./testing/outbox": {
       "types": "./dist/testing/outboxStoreContract.d.mts",
       "default": "./dist/testing/outboxStoreContract.mjs"
+    },
+    "./testing/ports": {
+      "types": "./dist/testing/requiredPorts.d.mts",
+      "default": "./dist/testing/requiredPorts.mjs"
     }
   },
   "main": "./dist/index.mjs",
@@ -292,9 +292,9 @@
       "./mcp/testing": "stable",
       "./scim": "stable",
       "./auth/audit": "stable",
-      "./sync": "experimental",
       "./usage": "experimental",
       "./testing/outbox": "stable",
+      "./testing/ports": "stable",
       "./outbox-admin": "experimental"
     }
   },
@@ -308,7 +308,7 @@
   "scripts": {
     "build": "tsdown",
     "dev": "tsdown --watch",
-    "typecheck": "npm run typecheck:src && npm run typecheck:types && npm run check:type-lane",
+    "typecheck": "npm run typecheck:src && npm run typecheck:types && npm run typecheck:types-strict && npm run check:type-lane",
     "typecheck:src": "tsc --noEmit",
     "check:type-lane": "node scripts/check-type-lane.mjs",
     "lint": "biome check src/",
@@ -322,6 +322,7 @@
     "test:watch": "vitest",
     "test:ui": "vitest --ui",
     "typecheck:types": "tsc -p tsconfig.types.json",
+    "typecheck:types-strict": "tsc -p tsconfig.types-strict.json",
     "api:surface": "node scripts/check-api-surface.mjs --update",
     "check:api-surface": "node scripts/check-api-surface.mjs",
     "check:package": "publint && attw --pack . --profile esm-only",
@@ -337,6 +338,8 @@
     "smoke": "node scripts/smoke-test.mjs",
     "smoke:consumer": "node scripts/smoke-test.mjs --consumer",
     "smoke:mcp": "node scripts/mcp-e2e.mjs",
+    "bench:memory": "node --expose-gc scripts/bench-memory.mjs",
+    "bench:http": "node --expose-gc scripts/bench-http.mjs",
     "push": "classytic-push",
     "release:tag": "node -e \"require('child_process').execSync('npm run push -- v'+require('./package.json').version,{stdio:'inherit'})\"",
     "release": "npm run push -- main && npm run release:tag && npm publish",
@@ -353,8 +356,8 @@
     "node": ">=22"
   },
   "peerDependencies": {
-    "@classytic/primitives": ">=0.28.0",
-    "@classytic/repo-core": ">=0.28.0",
+    "@classytic/primitives": ">=0.31.0",
+    "@classytic/repo-core": ">=0.31.0",
     "@classytic/streamline": ">=2.8.0",
     "@fastify/cors": ">=11.0.0",
     "@fastify/helmet": ">=13.0.0",
@@ -476,6 +479,7 @@
     }
   },
   "dependencies": {
+    "@fastify/ajv-compiler": "^4.0.0",
     "fastify-plugin": "^6.0.0",
     "qs": "^6.16.0",
     "secure-json-parse": "^4.1.0"
@@ -487,10 +491,10 @@
     "@biomejs/biome": "^2.5.7",
     "@classytic/dev-tools": "^0.2.0",
     "@classytic/gitkit": ">=0.1.0",
-    "@classytic/mongokit": "^3.33.0",
+    "@classytic/mongokit": "^3.40.1",
     "@classytic/pgkit": "^0.1.0",
-    "@classytic/primitives": "^0.28.0",
-    "@classytic/repo-core": "^0.28.0",
+    "@classytic/primitives": "^0.31.0",
+    "@classytic/repo-core": "^0.31.0",
     "@classytic/sqlitekit": "^0.9.0",
     "@classytic/streamline": "^2.8.2",
     "@electric-sql/pglite": "^0.5.4",

package/skills/arc/SKILL.md

@@ -77,7 +77,7 @@ createApp({ role: process.env.ARC_ROLE as 'api' | 'worker' | 'relay' | 'schedule
 
 `api` and `worker` mount NO module schedule arms; `relay` mounts only `kind: 'relay'` arms (the outbox relay, durable webhook delivery); `scheduler` mounts all of them. Declaring `relay`/`scheduler` together with `resources`/`resourceDir` is BOOT-FATAL — a relay process must not serve routes. Default `all` is the pre-2.33 behaviour, unchanged. `createWorker()` forwards `role`; without one it still runs everything non-HTTP.
 
-`beforeBoot()` (2.21) runs before Fastify exists and before module thunks / resource files import — connect the DB there instead of dynamic-import ordering hacks.
+`beforeBoot()` (2.21) runs before Fastify exists and before module thunks / resource files import — connect the DB there instead of dynamic-import ordering hacks. Return a disposer (`() => mongoose.disconnect()`) and arc runs it on close and on a failed boot. A bridge declared as `{ kind: 'bridge', name, dependsOn, load }` is never imported when inactive.
 
 For async-booted engines, pass `resources` as a factory so it runs after `bootstrap[]`:
 
@@ -210,7 +210,14 @@ presets: ['softDelete', { name: 'multiTenant', tenantField: 'organizationId' }]
 
 ## Permissions
 
-A `PermissionCheck` returns `boolean | { granted, reason?, filters?, scope? }`. `filters` propagate into the repo query (row-level ABAC). `scope` stamps attributes downstream.
+A `PermissionCheck` returns `boolean | AuthorizationDecision` — build one with `allow({ policy?, scope? })` / `deny(reason?)`. `policy` is ANDed into the repo query (row-level ABAC); `scope` stamps attributes downstream. The pre-2.30 `{ granted, filters }` shape THROWS — never emit it.
+
+**Public but row-filtered** — use `allowPublic({ policy })`, not a hand-written `allow({ policy })`: a hand-written check lacks the `_isPublic` flag, so anonymous callers get 401.
+
+```typescript
+list: allowPublic({ policy: { status: 'published' } }),              // strangers: published only
+list: allowPublic({ policy: (ctx) => isElevated(scopeOf(ctx)) ? {} : { status: 'published' } }),  // {} = unrestricted
+```
 
 ```typescript
 import {
@@ -233,9 +240,11 @@ permissions: {
 **Custom check:**
 
 ```typescript
+import { allow, deny, type PermissionCheck } from '@classytic/arc/permissions';
+
 const requirePro = (): PermissionCheck => async (ctx) => {
-  if (!ctx.user) return { granted: false, reason: 'Auth required' };
-  return { granted: ctx.user.plan === 'pro' };
+  if (!ctx.user) return deny('Auth required');
+  return ctx.user.plan === 'pro' ? allow() : deny('Pro plan required');
 };
 ```
 

package/skills/arc/references/auth.md

@@ -497,6 +497,7 @@ import {
 | Function | Description |
 |----------|-------------|
 | `allowPublic()` | No authentication |
+| `allowPublic({ policy })` | No authentication, rows narrowed by a filter (or a per-caller resolver; `{}` = unrestricted) |
 | `requireAuth()` | Any authenticated user |
 | `requireRoles(['admin'])` | At least one role matches |
 | `requireOwnership('userId')` | Resource owner only (elevated bypasses) |
@@ -510,9 +511,11 @@ import {
 **Custom permission:**
 
 ```typescript
+import { allow, deny, type PermissionCheck } from '@classytic/arc/permissions';
+
 const requirePro = (): PermissionCheck => async (ctx) => {
-  if (!ctx.user) return { granted: false, reason: 'Auth required' };
-  return { granted: ctx.user.plan === 'pro' };
+  if (!ctx.user) return deny('Auth required');
+  return ctx.user.plan === 'pro' ? allow() : deny('Pro plan required');
 };
 ```
 
@@ -646,12 +649,12 @@ Gate routes on service identity using the scope helpers + a permission builder:
 
 ```typescript
 import { isService, getClientId, getServiceScopes } from '@classytic/arc/scope';
-import type { PermissionCheck } from '@classytic/arc/permissions';
+import { allow, deny, type PermissionCheck } from '@classytic/arc/permissions';
 
 const requireScope = (scope: string): PermissionCheck => (ctx) => {
-  if (!isService(ctx.request.scope)) return { granted: false, reason: 'service only' };
+  if (!isService(ctx.request.scope)) return deny('service only');
   const has = getServiceScopes(ctx.request.scope).includes(scope);
-  return has ? { granted: true } : { granted: false, reason: `missing scope: ${scope}` };
+  return has ? allow() : deny(`missing scope: ${scope}`);
 };
 
 defineResource({

package/skills/arc/references/integrations.md

@@ -238,7 +238,7 @@ Single configuration point for both SSE and WebSocket with shared auth, org-scop
 ```typescript
 await fastify.register(eventGatewayPlugin, {
   auth: true,                     // Fail-closed for both SSE and WebSocket
-  orgScoped: true,                // Filter events by org
+  // orgScoped: omitted → SSE's default (true). Set false only for a cross-tenant ops stream.
   roomPolicy: (client, room) => {
     return ['product', 'order', 'invoice'].includes(room);
   },

package/skills/arc/references/mcp.md

@@ -101,18 +101,20 @@ await app.register(mcpPlugin, {
 
 ### Permission Filters (v2.4.2)
 
-Resource permissions with `filters` are automatically enforced in MCP tools — same as REST:
+Resource permissions that return a row `policy` are automatically enforced in MCP tools — same as REST:
 
 ```typescript
+import { allow, deny } from '@classytic/arc/permissions';
+
 defineResource({
   name: 'task',
   permissions: {
-    list: (ctx) => ({
-      granted: !!ctx.user,
-      filters: { orgId: ctx.user?.orgId, branchId: ctx.user?.branchId },
-    }),
+    list: (ctx) =>
+      ctx.user
+        ? allow({ policy: { orgId: ctx.user.orgId, branchId: ctx.user.branchId } })
+        : deny('Auth required'),
     create: (ctx) => !!ctx.user,                    // boolean works too
-    delete: (ctx) => ({ granted: false, reason: 'Read-only' }),  // deny
+    delete: () => deny('Read-only'),
   },
 });
 

package/skills/arc/references/multi-tenancy.md

@@ -38,15 +38,21 @@ Every request goes through this ladder — if any step is missed, tenant isolati
 
 ## Where `tenantField` is read
 
-Every resource defines `tenantField` (default: `'organizationId'`, or `false` to disable). It is read in **exactly three places** and ALL of them derive the org ID from `metadata._scope` via `getOrgId()`:
+Every resource defines `tenantField` (default: `'organizationId'`, or `false` to disable). **One function decides tenancy — `resolveTenancy()` in `src/core/tenancy.ts`** — and every layer switches on its result:
 
-| File                           | Method                  | Purpose                                        |
-|--------------------------------|-------------------------|------------------------------------------------|
-| `src/core/QueryResolver.ts`    | `resolve()`             | `list` — prepends `{ [tenantField]: orgId }` to the filter |
-| `src/core/AccessControl.ts`    | `buildIdFilter()`       | `get`, `update`, `delete` by ID — compound filter so cross-tenant IDs 404 |
-| `src/core/BaseController.ts`   | `buildBulkFilter()`     | `bulkUpdate`, `bulkDelete` — narrows bulk ops to the caller's org |
+| Result | Meaning |
+|---|---|
+| `{ mode: 'scoped', field, orgId }` | filter by `field = orgId` (a member, a service key, or an elevated admin who SELECTED an org) |
+| `unscoped: 'platform'` | elevated admin with NO org — sees and writes across tenants |
+| `unscoped: 'cross-tenant'` | the route declared `multiTenantPreset({ crossTenant: [...] })` — reads only; the row policy still applies |
+| `unscoped: 'no-org'` | anonymous, or signed in with no org selected — reads get no tenant filter (the preset refuses earlier where one is required); **writes are refused** |
+| `unscoped: 'untenanted-resource'` | `tenantField: false` |
 
-**Everything else** (`BodySanitizer`, `MongoKit QueryParser`, presets) already composes cleanly with these three read points. If `getOrgId(scope)` returns the right value, you have tenant isolation — end of story.
+Consumers: `QueryResolver` (list), `AccessControl.buildIdFilter` (get/update/delete by id) and `checkOrgScope` (post-fetch), `buildTenantRepoOptions` (what the kit is told, `bypassTenant`), the bulk mixin (`bulkCreate` stamping + `buildBulkFilter`), and — via `eventAudienceOf` / `isEventVisible` — the `sse` and `realtime` streams.
+
+**Never re-derive the org from the scope in a new layer.** Each layer used to, with its own condition, and they drifted: `crossTenant` was taught to three of four read layers (`get` silently ignored it for signed-in members), bulk writes skipped the org for ANY elevated admin (an admin acting as org-9 deleted across every tenant), and `realtime` withheld the platform view that reads grant. The union is exhaustive, so a new mode is a compile error in every consumer that has not handled it.
+
+The cache key (`deriveCacheScope`) deliberately does NOT use it: it answers "whose cache partition", which on a cross-tenant read is still the caller's org — dropping it could let one org's cached page answer another's.
 
 ## Filter composition
 
@@ -101,19 +107,18 @@ Return the scope directly from your permission check. This is the cleanest integ
 
 ```ts
 // src/permissions/apiKey.ts
-import type { PermissionCheck } from '@classytic/arc/permissions';
+import { allow, deny, type PermissionCheck } from '@classytic/arc/permissions';
 import { ClientModel } from '../models/Client.js';
 
 export function requireApiKey(): PermissionCheck {
   return async ({ request }) => {
     const apiKey = request.headers['x-api-key'] as string | undefined;
-    if (!apiKey) return { granted: false, reason: 'Missing API key' };
+    if (!apiKey) return deny('Missing API key');
 
     const client = await ClientModel.findOne({ apiKey });
-    if (!client) return { granted: false, reason: 'Invalid API key' };
+    if (!client) return deny('Invalid API key');
 
-    return {
-      granted: true,
+    return allow({
       scope: {
         kind: 'service',
         clientId: String(client._id),
@@ -121,8 +126,8 @@ export function requireApiKey(): PermissionCheck {
         scopes: client.allowedScopes,  // optional OAuth-style scope strings
       },
       // Optional additional row-level narrowing
-      filters: client.projectId ? { projectId: client.projectId } : undefined,
-    };
+      ...(client.projectId ? { policy: { projectId: client.projectId } } : {}),
+    });
   };
 }
 ```

package/skills/arc/references/production.md

@@ -76,8 +76,8 @@ Default `0`, which is the pre-2.41 behaviour: close the moment SIGTERM arrives.
 
 `drainDelayMs` is the window between "start failing readiness" and "stop accepting":
 
-- `/health/ready` → `503 { status: 'draining' }` immediately on signal
-- `/health/live` → stays `200` (a draining process is alive — that's the point; a 503 here gets the pod **killed**, not drained)
+- `/_health/ready` → `503 { status: 'draining' }` immediately on signal
+- `/_health/live` → stays `200` (a draining process is alive — that's the point; a 503 here gets the pod **killed**, not drained)
 - everything already routed here is still served for the whole window
 
 Set it **above** your LB's deregistration window — typically 5000–15000ms. On Kubernetes, also keep `terminationGracePeriodSeconds` > `drainDelayMs + timeout`, or the kubelet SIGKILLs you mid-drain.
@@ -299,7 +299,7 @@ const app = await createApp({
       path: '/events/stream',       // SSE endpoint (default: '/events/stream')
       requireAuth: true,            // Fail-closed auth (default: true)
       patterns: ['order.*', 'product.*'],  // Event patterns to stream (default: ['*'])
-      orgScoped: false,             // Filter events by org from request.scope (default: false)
+      // orgScoped defaults to TRUE (2.41.1) — a caller only sees its own org's events.
       heartbeat: 30000,             // Heartbeat interval in ms (default: 30000)
     },
   },
@@ -307,7 +307,7 @@ const app = await createApp({
 
 // Manual registration
 import { ssePlugin } from '@classytic/arc/plugins';
-await fastify.register(ssePlugin, { requireAuth: true, orgScoped: true });
+await fastify.register(ssePlugin, { requireAuth: true });
 ```
 
 ### Realtime resource change feed (2.22)
@@ -322,12 +322,9 @@ row-permissioned resources through it); event firehose → sse. Massive fan-out
 (viral feeds, live scores) → publish once to a dedicated edge fan-out layer
 via `app.events.subscribe(...)`; full tiering guide: docs/production-ops/realtime.mdx.
 
-```typescript
-```
-
 **Fail-closed auth:** When `requireAuth: true` (default), throws at registration if `fastify.authenticate` is missing — prevents exposing SSE without auth.
 
-**Org-scoped:** When `orgScoped: true`, events with `organizationId` are only sent to clients whose `request.scope` matches. Prevents cross-tenant leakage.
+**Org-scoped by default (2.41.1):** an event carrying `organizationId` reaches only callers in that org. It defaulted to `false` — with `patterns: ['*']`, one tenant's member received every tenant's events, full documents included. Events with no `organizationId` still reach everyone, so single-tenant apps are unaffected; an elevated admin with no active org sees all tenants (the platform view). `orgScoped: false` is for a deliberately cross-tenant stream only — keep `requireAuth` and add a `filter`.
 
 ## Error Handler Plugin
 
@@ -383,7 +380,7 @@ return reply.header('content-type', 'text/csv').send(readableStream);
 
 ### BigInt Serialization
 
-Opt-in: `createApp({ serializeBigInt: true })` — auto-converts BigInt → Number in all JSON responses.
+Opt-in: `createApp({ serializeBigInt: 'string' })` — BigInt → decimal string in JSON responses (lossless); `'number'` is lossy above 2^53-1.
 
 ## Multipart Body Middleware (v2.7.3)
 
@@ -678,7 +675,27 @@ await outbox.store(event, { session });
 const relayed = await outbox.relay();  // publishes pending → transport
 ```
 
-**OutboxStore interface**: `save(event)`, `getPending(limit)`, `acknowledge(eventId)` (+ optional `claimPending`, `fail`, `getDeadLettered`, `purge`). When you pass `repository`, arc adapts it internally.
+**Prefer the module form** — it owns the relay schedule, shutdown, and a readiness check, so none of that is hand-wired:
+
+```typescript
+import { createOutboxModule, exponentialBackoff, repositoryAsOutboxStore } from '@classytic/arc/events';
+
+const outbox = createOutboxModule({
+  store: repositoryAsOutboxStore(new Repository(OutboxModel)),
+  // Bounds retries AND log volume. `attempts` is the DURABLE count (it survives relay
+  // restarts and is shared across relays), so a poison event really does stop at 5.
+  failurePolicy: ({ attempts }) =>
+    attempts >= 5 ? { deadLetter: true } : { retryAt: exponentialBackoff({ attempt: attempts }) },
+  health: { relayLagUnhealthyMs: 5 * 60_000, probeCacheMs: 5_000 },
+});
+// createApp({ modules: [outbox] }); consumers declare dependsOn: ['outbox'].
+```
+
+- `requestDrain()` — nudge a pass after commit (milliseconds, not `relayEveryMs`); runs outside the caller's request scope.
+- `drain()` — await delivery, cascades included. For tests and a shutdown that should empty the queue.
+- `health()` + readiness check `<name>.relay` — **non-critical** (a stalled relay is a cluster problem; pulling one pod would not drain it). Unhealthy on any dead letter or pending lag past the threshold. The probe reuses a reading for `probeCacheMs` so N replicas × probe rate do not become N count queries a second on the outbox table.
+
+**OutboxStore contract** (`@classytic/primitives/outbox`): required `save`, `getPending`, `acknowledge`; optional `claimPending` / `claimPendingFenced` (lease + fencing token, and the durable `attempts`), `fail`, `getDeadLettered`, `requeue`, `purge`, `countByStatus`, `oldestPendingAgeMs`. Prove a custom store with `runOutboxStoreContract` from `@classytic/arc/testing/outbox`. When you pass `repository`, arc adapts it internally.
 
 ## Bulk Operations Preset