@classytic/arc 2.41.1 → 2.44.0

package/dist/{validate-DrYWnOzI.mjs → validate-CWp-lsrm.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.44.0 | MIT | https://classytic.com */
+import { r as __exportAll } from "./rolldown-runtime-MYrLNGnq.mjs";
+import { _ as pathTouchesBlocked } from "./plugin-DALd9dcF.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-CHhL9P3o.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.44.0 | MIT | https://classytic.com */
+import { r as __exportAll } from "./rolldown-runtime-MYrLNGnq.mjs";
+import { d as createDomainError } from "./errors-CW4anJBy.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-n9a7d_lZ.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.44.0 | MIT | https://classytic.com */
+import { n as requestContext } from "./requestContext-C10UeFe5.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.44.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,65 +479,66 @@
     }
   },
   "dependencies": {
+    "@fastify/ajv-compiler": "^4.0.0",
     "fastify-plugin": "^6.0.0",
     "qs": "^6.16.0",
     "secure-json-parse": "^4.1.0"
   },
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.5",
-    "@better-auth/drizzle-adapter": "^1.6.19",
-    "@better-auth/mongo-adapter": "^1.6.19",
-    "@biomejs/biome": "^2.5.7",
-    "@classytic/dev-tools": "^0.2.0",
-    "@classytic/gitkit": ">=0.1.0",
-    "@classytic/mongokit": "^3.33.0",
+    "@better-auth/drizzle-adapter": "^1.7.7",
+    "@better-auth/mongo-adapter": "^1.7.7",
+    "@biomejs/biome": "^2.5.15",
+    "@classytic/dev-tools": "^0.2.1",
+    "@classytic/gitkit": ">=0.3.0",
+    "@classytic/mongokit": "^3.41.0",
     "@classytic/pgkit": "^0.1.0",
-    "@classytic/primitives": "^0.28.0",
-    "@classytic/repo-core": "^0.28.0",
-    "@classytic/sqlitekit": "^0.9.0",
-    "@classytic/streamline": "^2.8.2",
-    "@electric-sql/pglite": "^0.5.4",
-    "@fastify/cors": "^11.2.0",
-    "@fastify/helmet": "^13.0.2",
-    "@fastify/jwt": "^10.1.0",
-    "@fastify/multipart": "^10.0.0",
-    "@fastify/rate-limit": "^11.0.0",
-    "@fastify/sensible": "^6.0.4",
-    "@fastify/static": "^10.1.2",
-    "@fastify/type-provider-typebox": "^6.1.0",
-    "@fastify/under-pressure": "^9.0.3",
-    "@fastify/websocket": "^11.2.0",
-    "@modelcontextprotocol/client": "^2.0.0",
-    "@modelcontextprotocol/node": "^2.0.0",
-    "@modelcontextprotocol/server": "^2.0.0",
+    "@classytic/primitives": "^0.33.0",
+    "@classytic/repo-core": "^0.31.1",
+    "@classytic/sqlitekit": "^0.10.0",
+    "@classytic/streamline": "^2.11.0",
+    "@electric-sql/pglite": "^0.5.9",
+    "@fastify/cors": "^11.3.1",
+    "@fastify/helmet": "^13.2.0",
+    "@fastify/jwt": "^10.2.4",
+    "@fastify/multipart": "^10.1.3",
+    "@fastify/rate-limit": "^11.2.1",
+    "@fastify/sensible": "^6.0.7",
+    "@fastify/static": "^10.1.6",
+    "@fastify/type-provider-typebox": "^6.3.0",
+    "@fastify/under-pressure": "^9.2.1",
+    "@fastify/websocket": "^11.3.4",
+    "@modelcontextprotocol/client": "^2.3.1",
+    "@modelcontextprotocol/node": "^2.1.1",
+    "@modelcontextprotocol/server": "^2.3.1",
     "@opentelemetry/api": "^1.9.1",
     "@types/node": "^22.19.21",
     "@types/qs": "^6.15.1",
-    "@vitest/coverage-v8": "^5.0.0",
+    "@vitest/coverage-v8": "^5.0.4",
     "ajv": "^8.20.0",
-    "better-auth": "^1.7.3",
+    "better-auth": "^1.7.7",
     "better-sqlite3": "^13.0.3",
-    "bullmq": "^6.1.2",
-    "dotenv": "^17.4.2",
-    "drizzle-orm": "^0.45.2",
-    "fast-check": "^4.8.0",
-    "fastify": "^5.12.1",
-    "fastify-raw-body": "^6.0.1",
-    "h3-js": "^4.4.0",
+    "bullmq": "^6.3.15",
+    "dotenv": "^18.0.7",
+    "drizzle-orm": "^0.45.4",
+    "fast-check": "^4.10.2",
+    "fastify": "^5.12.7",
+    "fastify-raw-body": "^6.0.2",
+    "h3-js": "^4.5.0",
     "ioredis": "^6.0.0",
-    "jose": "^6.2.3",
+    "jose": "^6.2.12",
     "jsonwebtoken": "^9.0.3",
-    "knip": "^6.31.0",
-    "mongodb": "^7.3.0",
-    "mongodb-memory-server": "^11.2.0",
-    "mongoose": "^9.9.1",
-    "publint": "^0.3.21",
-    "tsdown": "^0.22.14",
-    "typebox": "^1.3.6",
+    "knip": "^6.41.0",
+    "mongodb": "^7.7.0",
+    "mongodb-memory-server": "^11.3.0",
+    "mongoose": "^9.11.2",
+    "publint": "^0.3.25",
+    "tsdown": "^0.23.1",
+    "typebox": "^1.3.37",
     "typescript": "^7.0.2",
-    "vitest": "^5.0.0",
-    "ws": "^8.21.0",
-    "zod": "^4.4.3"
+    "vitest": "^5.0.4",
+    "ws": "^8.22.0",
+    "zod": "^4.6.7"
   },
   "config": {
     "mongodbMemoryServer": {
@@ -564,11 +568,5 @@
   "repository": {
     "type": "git",
     "url": "git+https://github.com/classytic/arc.git"
-  },
-  "overrides": {
-    "better-sqlite3": "$better-sqlite3",
-    "better-auth": {
-      "vitest": "$vitest"
-    }
   }
 }

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 } } : {}),
+    });
   };
 }
 ```