@classytic/arc 2.22.0 → 2.23.0

package/dist/testing/index.mjs

@@ -1,5 +1,5 @@
 import { t as CRUD_OPERATIONS } from "../constants-DNre0wRg.mjs";
-import { d as getModuleExports, h as preloadResourcesAsync, m as preloadResources, n as createApp } from "../createApp-Ci7yG5gv.mjs";
+import { d as getModuleExports, h as preloadResourcesAsync, m as preloadResources, n as createApp } from "../createApp-CjOeWJ9_.mjs";
 import { runStorageContract } from "./storageContract.mjs";
 import Fastify from "fastify";
 import { afterAll, describe, expect, it, vi } from "vitest";
@@ -1116,7 +1116,7 @@ function pickDefaultAuth(authMode, callerAuth) {
 	};
 }
 async function createTestApp(options = {}) {
-	const { createApp } = await import("../createApp-Ci7yG5gv.mjs").then((n) => n.r);
+	const { createApp } = await import("../createApp-CjOeWJ9_.mjs").then((n) => n.r);
 	const { resources = [], db = "in-memory", connectMongoose = false, authMode = "jwt", defaultOrgId, plugins, auth: callerAuth, ...appOptions } = options;
 	let dbHandle;
 	let dbUri;

package/dist/types/index.d.mts

@@ -1,4 +1,4 @@
-import { $ as OpenApiSchemas, $t as UserOrganization, A as RequestIdOptions, At as RouteDefinition, Bt as RouteHandler, C as RequestContext, D as HealthCheck, Dt as ActionEntry, E as GracefulShutdownOptions, Et as ActionDefinition, F as FastifyWithDecorators, Fn as BaseControllerOptions, Ft as ControllerLike, G as OnTenantDeleteConfig, Gt as JwtContext, H as CrudController, Ht as AuthPluginOptions, I as MiddlewareHandler, It as FastifyHandler, J as PresetHook, Jt as ApiResponse, K as ResolvedTenantPurge, Kt as TokenPair, L as RequestWithExtras, Lt as IController, M as EventsDecorator, Mt as RouteMethod, N as FastifyRequestExtras, Nt as RateLimitConfig, O as HealthOptions, Ot as ActionHandlerFn, P as FastifyWithAuth, Pt as ControllerHandler, Q as MiddlewareConfig, Qt as UserLike, Rt as IControllerResponse, S as QueryParserInterface, T as CrudRouterOptions, Tt as ResourceCacheConfig, U as ResourceConfig, Ut as Authenticator, Vt as AuthHelpers, W as ResourcePermissions, Wt as AuthenticatorContext, X as CrudRouteKey, Xt as JWTPayload, Y as PresetResult, Yt as ArcRequest, Z as CrudSchemas, Zt as ObjectId, _ as ControllerQueryOptions, a as InferAdapterDoc, at as ResourceExtensions, b as ParsedQuery, c as TypedController, d as PaginationResult, et as RouteSchemaOptions, f as IntrospectionData, g as ArcInternalMetadata, h as ResourceMetadata, i as ValidationResult, it as ResourceHooks, j as ArcDecorator, jt as RouteMcpConfig, k as IntrospectionPluginOptions, kt as ActionsMap, l as TypedRepository, m as RegistryStats, n as ConfigError, nt as FieldRule, o as InferDocType, ot as EventDefinition, p as RegistryEntry, q as PresetFunction, qt as AnyRecord, r as ValidateOptions, rt as ResourceHookContext, s as InferResourceDoc, t as RouteHandlerMethod, tt as ArcFieldRule, u as TypedResourceConfig, v as LookupOption, w as ServiceContext, x as PopulateOption, y as OwnershipCheck, zt as IRequestContext } from "../index-DbtgCOCj.mjs";
+import { $ as OpenApiSchemas, $t as UserLike, A as RequestIdOptions, At as RouteDefinition, Bt as RouteHandler, C as RequestContext, D as HealthCheck, Dt as ActionEntry, E as GracefulShutdownOptions, Et as ActionDefinition, F as FastifyWithDecorators, Ft as ControllerLike, G as OnTenantDeleteConfig, Gt as AuthenticatorContext, H as CrudController, Ht as AuthHelpers, I as MiddlewareHandler, In as BaseControllerOptions, It as FastifyHandler, J as PresetHook, Jt as AnyRecord, K as ResolvedTenantPurge, Kt as JwtContext, L as RequestWithExtras, Lt as IController, M as EventsDecorator, Mt as RouteMethod, N as FastifyRequestExtras, Nt as RateLimitConfig, O as HealthOptions, Ot as ActionHandlerFn, P as FastifyWithAuth, Pt as ControllerHandler, Q as MiddlewareConfig, Qt as ObjectId, Rt as IControllerResponse, S as QueryParserInterface, T as CrudRouterOptions, Tt as ResourceCacheConfig, U as ResourceConfig, Ut as AuthPluginOptions, W as ResourcePermissions, Wt as Authenticator, X as CrudRouteKey, Xt as ArcRequest, Y as PresetResult, Yt as ApiResponse, Z as CrudSchemas, Zt as JWTPayload, _ as ControllerQueryOptions, a as InferAdapterDoc, at as ResourceExtensions, b as ParsedQuery, c as TypedController, d as PaginationResult, en as UserOrganization, et as RouteSchemaOptions, f as IntrospectionData, g as ArcInternalMetadata, h as ResourceMetadata, i as ValidationResult, it as ResourceHooks, j as ArcDecorator, jt as RouteMcpConfig, k as IntrospectionPluginOptions, kt as ActionsMap, l as TypedRepository, m as RegistryStats, n as ConfigError, nt as FieldRule, o as InferDocType, ot as EventDefinition, p as RegistryEntry, q as PresetFunction, qt as TokenPair, r as ValidateOptions, rt as ResourceHookContext, s as InferResourceDoc, t as RouteHandlerMethod, tt as ArcFieldRule, u as TypedResourceConfig, v as LookupOption, w as ServiceContext, x as PopulateOption, y as OwnershipCheck, zt as IRequestContext } from "../index-BBsvQt7U.mjs";
 import { i as RequestScope } from "../types-DH0GupI7.mjs";
 import { i as UserBase, n as PermissionContext, r as PermissionResult, t as PermissionCheck } from "../types-Csxga7d3.mjs";
 import { n as ElevationOptions, t as ElevationEvent } from "../elevation-C9s5hFP_.mjs";

package/dist/{types-Bc42CUyk.d.mts → types-5OuqeTDX.d.mts}

@@ -1,4 +1,4 @@
-import { V as ResourceDefinition } from "./index-DbtgCOCj.mjs";
+import { V as ResourceDefinition } from "./index-BBsvQt7U.mjs";
 import { z } from "zod";
 //#region src/integrations/mcp/types.d.ts
 /** Behavioral hints for MCP clients (tool annotations per MCP spec) */
@@ -157,6 +157,41 @@ interface CrudDescriptionMeta {
  *   Arc's auto-derived filterable-fields blurb.
  */
 type CrudDescriptionOverride = string | ((meta: CrudDescriptionMeta) => string);
+/**
+ * Execution wiring for MCP tools — the app-level services HTTP requests
+ * receive via Fastify decorators (`fastify.arc.hooks`, `fastify.events`,
+ * `fastify.audit`, `fastify.log`, `fastify.idempotency`) and MCP's
+ * synthetic-context path historically dropped.
+ *
+ * When present, tool handlers thread it into the request context so the
+ * controller pipeline achieves FULL HTTP parity: resource hooks run
+ * (before/around/after), the arcCorePlugin after-hook publishes
+ * `<resource>.<op>d` events (→ realtime feeds, webhooks, event-driven
+ * cache invalidation all see MCP-originated mutations), `ctx.server.*`
+ * works inside handlers, and mutating CRUD tools accept an optional
+ * `_idempotencyKey` input for retry-safe execution.
+ *
+ * `mcpPlugin` builds this automatically from its Fastify instance (lazy
+ * getters — decorator registration order doesn't matter). Standalone
+ * `resourceToTools()` / `createMcpServer()` callers pass their own, or
+ * omit it to keep the legacy dispatch-only behavior.
+ */
+interface McpExecutionWiring {
+  /** Shared `HookSystem` — `fastify.arc.hooks`. */
+  readonly hooks?: unknown;
+  /** Event bus decorator — `fastify.events`. */
+  readonly events?: unknown;
+  /** Audit decorator — `fastify.audit`. */
+  readonly audit?: unknown;
+  /** Structured logger — `fastify.log`. */
+  readonly log?: unknown;
+  /**
+   * Idempotency store (the `IdempotencyStore` contract from
+   * `@classytic/arc/idempotency`). Presence advertises `_idempotencyKey`
+   * on mutating CRUD tools and enables executor-level check/lock/replay.
+   */
+  readonly idempotencyStore?: unknown;
+}
 /** Per-resource MCP configuration overrides */
 interface McpResourceConfig {
   /** Which CRUD operations to expose (default: all enabled on the resource) */
@@ -392,4 +427,4 @@ interface CreateMcpServerConfig {
 /** CRUD operation type */
 type CrudOperation = "list" | "get" | "create" | "update" | "delete";
 //#endregion
-export { CrudDescriptionOverride as a, McpAuthResult as c, PromptDefinition as d, PromptResult as f, ToolDefinition as g, ToolContext as h, CrudDescriptionMeta as i, McpPluginOptions as l, ToolAnnotations as m, CallToolResult as n, CrudOperation as o, SessionEntry as p, CreateMcpServerConfig as r, McpAuthResolver as s, BetterAuthHandler as t, McpResourceConfig as u };
+export { ToolDefinition as _, CrudDescriptionOverride as a, McpAuthResult as c, McpResourceConfig as d, PromptDefinition as f, ToolContext as g, ToolAnnotations as h, CrudDescriptionMeta as i, McpExecutionWiring as l, SessionEntry as m, CallToolResult as n, CrudOperation as o, PromptResult as p, CreateMcpServerConfig as r, McpAuthResolver as s, BetterAuthHandler as t, McpPluginOptions as u };

package/dist/utils/index.d.mts

@@ -1,4 +1,4 @@
-import { $ as OpenApiSchemas, Qt as UserLike, S as QueryParserInterface, U as ResourceConfig, b as ParsedQuery, qt as AnyRecord } from "../index-DbtgCOCj.mjs";
+import { $ as OpenApiSchemas, $t as UserLike, Jt as AnyRecord, S as QueryParserInterface, U as ResourceConfig, b as ParsedQuery } from "../index-BBsvQt7U.mjs";
 import { n as ErrorMapper } from "../errorHandler-C6yv4ZTW.mjs";
 import { a as NotFoundError, c as RateLimitError, d as ValidationError, f as createDomainError, i as ForbiddenError, l as ServiceUnavailableError, m as isArcError, n as ConflictError, o as OrgAccessDeniedError, p as createError, r as ErrorOptions, s as OrgRequiredError, t as ArcError, u as UnauthorizedError } from "../errors-DHcHVAgk.mjs";
 import { errorContractSchema, errorDetailSchema } from "@classytic/repo-core/errors";
@@ -437,6 +437,34 @@ declare const NEUTRAL_DIALECT: FilterDialect;
  */
 declare function handleRaw<T>(handler: (request: FastifyRequest, reply: FastifyReply) => Promise<T>, statusCode?: number): (request: FastifyRequest, reply: FastifyReply) => Promise<void>;
 //#endregion
+//#region src/utils/headers.d.ts
+/**
+ * Canonical header typing + accessor.
+ *
+ * Node/Fastify header values are `string | string[] | undefined` — repeated
+ * headers arrive as arrays. `IRequestContext.headers` is DECLARED as
+ * `Record<string, string | undefined>` for ergonomic host code, but the HTTP
+ * adapter passes Fastify's headers object through unchanged, so `string[]`
+ * CAN appear at runtime behind the narrower type (the declared type is
+ * scheduled to widen to {@link ArcHeaders} in v3). Until then, read headers
+ * through {@link getHeader} instead of indexing — it's honest about arrays
+ * and deterministic about duplicates.
+ */
+/** What a headers bag actually contains at runtime — HTTP or synthetic MCP. */
+type ArcHeaders = Readonly<Record<string, string | readonly string[] | undefined>>;
+/**
+ * Read a single header value. Lowercases the name (Node normalizes incoming
+ * header names to lowercase) and returns the FIRST value when the header
+ * was repeated.
+ *
+ * Duplicate policy: first-value is deterministic, but for security-sensitive
+ * headers (authorization material, forwarded-for chains, content-length) a
+ * duplicate usually signals smuggling or a broken proxy — consumers that
+ * care should check `Array.isArray(headers[name])` and REJECT instead of
+ * picking a winner.
+ */
+declare function getHeader(headers: ArcHeaders | Record<string, string | undefined> | undefined, name: string): string | undefined;
+//#endregion
 //#region src/utils/queryParser.d.ts
 interface ArcQueryParserOptions {
   /** Maximum allowed limit value (default: 1000) */
@@ -1215,6 +1243,38 @@ declare function convertRouteSchema(schema: Record<string, unknown>, target?: Js
  */
 declare function simpleEqualityMatcher(item: unknown, filters: Record<string, unknown>): boolean;
 //#endregion
+//#region src/utils/sseStream.d.ts
+interface SseStreamOptions {
+  /** Heartbeat comment interval in ms (default: 30000). */
+  heartbeatMs?: number;
+  /**
+   * Reconnection-delay hint written once at connect as the standard SSE
+   * `retry:` field (WHATWG EventSource honors it natively). Omit to send
+   * no hint (browser default ~3s).
+   */
+  retryMs?: number;
+}
+interface SseStream {
+  /**
+   * Write one SSE frame. `id` (optional) becomes the standard SSE `id:`
+   * field — clients receive it as `lastEventId` (WHATWG), enabling
+   * client-side dedup/resume bookkeeping even when the server keeps no
+   * replay log. Returns `false` when the connection was destroyed
+   * (backpressure) — the stream is already cleaned up; stop writing.
+   */
+  write(eventName: string, data: string, id?: string): boolean;
+  /** Idempotent teardown: heartbeat cleared, cleanups run, socket ended. */
+  close(): void;
+  /** Register teardown work (unsubscribes etc.) — runs exactly once. */
+  onCleanup(fn: () => void): void;
+}
+/**
+ * Take over the reply socket and open an SSE stream. Call ONLY after every
+ * gate (auth, permissions, validation) has passed — after `hijack()` no
+ * JSON error can be sent.
+ */
+declare function openSseStream(request: FastifyRequest, reply: FastifyReply, options?: SseStreamOptions): SseStream;
+//#endregion
 //#region src/utils/stateMachine.d.ts
 /**
  * State Machine Utility
@@ -1475,4 +1535,4 @@ declare function hasEvents(instance: FastifyInstance): instance is FastifyInstan
  */
 declare function getUserId(user: UserLike | null | undefined): string | undefined;
 //#endregion
-export { ArcError, ArcQueryParser, type ArcQueryParserOptions, CircuitBreaker, CircuitBreakerError, type CircuitBreakerOptions, CircuitBreakerRegistry, type CircuitBreakerStats, CircuitState, type CompensationDefinition, type CompensationError, type CompensationHooks, type CompensationResult, type CompensationStep, type ConfigError, ConflictError, type ErrorOptions, type EventsDecorator, type FilterDialect, ForbiddenError, type Guard, type GuardConfig, type JsonSchema, type JsonSchemaTarget, MONGO_DIALECT, NEUTRAL_DIALECT, NotFoundError, OrgAccessDeniedError, OrgRequiredError, type PipeUIMessageStreamOptions, RateLimitError, ServiceUnavailableError, type StateMachine, type TransitionConfig, UI_MESSAGE_STREAM_HEADERS, UnauthorizedError, type ValidateOptions, ValidationError, type ValidationResult, aggregateListResponse, assertValidConfig, bareListResponse, convertOpenApiSchemas, convertRouteSchema, createCircuitBreaker, createCircuitBreakerRegistry, createDomainError, createError, createQueryParser, createStateMachine, defineCompensation, defineErrorMapper, defineGuard, deleteResponse, errorContractSchema, errorDetailSchema, formatValidationErrors, forwardedStreamHeaders, getDefaultCrudSchemas, getListQueryParams, getUserId, handleRaw, hasEvents, isArcError, isJsonSchema, isReadableStream, isZodSchema, keysetListResponse, listResponse, offsetListResponse, paginationSchema, pipeUIMessageStreamToReply, promoteStreamTokenToHeader, queryParams, responses, scheduleBackground, simpleEqualityMatcher, toJsonSchema, validateResourceConfig, withCompensation };
+export { ArcError, type ArcHeaders, ArcQueryParser, type ArcQueryParserOptions, CircuitBreaker, CircuitBreakerError, type CircuitBreakerOptions, CircuitBreakerRegistry, type CircuitBreakerStats, CircuitState, type CompensationDefinition, type CompensationError, type CompensationHooks, type CompensationResult, type CompensationStep, type ConfigError, ConflictError, type ErrorOptions, type EventsDecorator, type FilterDialect, ForbiddenError, type Guard, type GuardConfig, type JsonSchema, type JsonSchemaTarget, MONGO_DIALECT, NEUTRAL_DIALECT, NotFoundError, OrgAccessDeniedError, OrgRequiredError, type PipeUIMessageStreamOptions, RateLimitError, ServiceUnavailableError, type SseStream, type SseStreamOptions, type StateMachine, type TransitionConfig, UI_MESSAGE_STREAM_HEADERS, UnauthorizedError, type ValidateOptions, ValidationError, type ValidationResult, aggregateListResponse, assertValidConfig, bareListResponse, convertOpenApiSchemas, convertRouteSchema, createCircuitBreaker, createCircuitBreakerRegistry, createDomainError, createError, createQueryParser, createStateMachine, defineCompensation, defineErrorMapper, defineGuard, deleteResponse, errorContractSchema, errorDetailSchema, formatValidationErrors, forwardedStreamHeaders, getDefaultCrudSchemas, getHeader, getListQueryParams, getUserId, handleRaw, hasEvents, isArcError, isJsonSchema, isReadableStream, isZodSchema, keysetListResponse, listResponse, offsetListResponse, openSseStream, paginationSchema, pipeUIMessageStreamToReply, promoteStreamTokenToHeader, queryParams, responses, scheduleBackground, simpleEqualityMatcher, toJsonSchema, validateResourceConfig, withCompensation };

package/dist/utils/index.mjs

@@ -1,6 +1,8 @@
 import { a as OrgAccessDeniedError, c as ServiceUnavailableError, d as createDomainError, f as createError, i as NotFoundError, l as UnauthorizedError, n as ConflictError, o as OrgRequiredError, p as isArcError, r as ForbiddenError, s as RateLimitError, t as ArcError, u as ValidationError } from "../errors-DkO8Nk6-.mjs";
-import { A as createCircuitBreaker, C as defineErrorMapper, D as CircuitBreakerError, E as CircuitBreaker, F as simpleEqualityMatcher, M as assertValidConfig, N as formatValidationErrors, O as CircuitBreakerRegistry, P as validateResourceConfig, S as defineGuard, T as withCompensation, _ as ArcQueryParser, a as bareListResponse, b as MONGO_DIALECT, c as errorDetailSchema, d as keysetListResponse, f as listResponse, g as responses, h as queryParams, i as aggregateListResponse, j as createCircuitBreakerRegistry, k as CircuitState, l as getDefaultCrudSchemas, m as paginationSchema, n as createStateMachine, o as deleteResponse, p as offsetListResponse, r as scheduleBackground, s as errorContractSchema, t as getUserId, u as getListQueryParams, v as createQueryParser, w as defineCompensation, x as NEUTRAL_DIALECT, y as handleRaw } from "../utils-FhJ88TJE.mjs";
-import { a as isZodSchema, i as isJsonSchema, n as convertRouteSchema, o as toJsonSchema, t as convertOpenApiSchemas } from "../schemaConverter-Ds5reSGs.mjs";
+import { t as simpleEqualityMatcher } from "../simpleEqualityMatcher-Cg05HPsn.mjs";
+import { A as CircuitState, C as defineGuard, D as CircuitBreaker, E as withCompensation, F as validateResourceConfig, M as createCircuitBreakerRegistry, N as assertValidConfig, O as CircuitBreakerError, P as formatValidationErrors, S as NEUTRAL_DIALECT, T as defineCompensation, _ as ArcQueryParser, a as bareListResponse, b as handleRaw, c as errorDetailSchema, d as keysetListResponse, f as listResponse, g as responses, h as queryParams, i as aggregateListResponse, j as createCircuitBreaker, k as CircuitBreakerRegistry, l as getDefaultCrudSchemas, m as paginationSchema, n as createStateMachine, o as deleteResponse, p as offsetListResponse, r as scheduleBackground, s as errorContractSchema, t as getUserId, u as getListQueryParams, v as createQueryParser, w as defineErrorMapper, x as MONGO_DIALECT, y as getHeader } from "../utils-CZyeRXTh.mjs";
+import { a as isZodSchema, i as isJsonSchema, n as convertRouteSchema, o as toJsonSchema, t as convertOpenApiSchemas } from "../schemaConverter-DJvodiHj.mjs";
 import { a as promoteStreamTokenToHeader, i as pipeUIMessageStreamToReply, n as forwardedStreamHeaders, r as isReadableStream, t as UI_MESSAGE_STREAM_HEADERS } from "../streaming-BQcW6_Kq.mjs";
+import { t as openSseStream } from "../sseStream-BQ7Qaynp.mjs";
 import { t as hasEvents } from "../typeGuards-C9KXUly6.mjs";
-export { ArcError, ArcQueryParser, CircuitBreaker, CircuitBreakerError, CircuitBreakerRegistry, CircuitState, ConflictError, ForbiddenError, MONGO_DIALECT, NEUTRAL_DIALECT, NotFoundError, OrgAccessDeniedError, OrgRequiredError, RateLimitError, ServiceUnavailableError, UI_MESSAGE_STREAM_HEADERS, UnauthorizedError, ValidationError, aggregateListResponse, assertValidConfig, bareListResponse, convertOpenApiSchemas, convertRouteSchema, createCircuitBreaker, createCircuitBreakerRegistry, createDomainError, createError, createQueryParser, createStateMachine, defineCompensation, defineErrorMapper, defineGuard, deleteResponse, errorContractSchema, errorDetailSchema, formatValidationErrors, forwardedStreamHeaders, getDefaultCrudSchemas, getListQueryParams, getUserId, handleRaw, hasEvents, isArcError, isJsonSchema, isReadableStream, isZodSchema, keysetListResponse, listResponse, offsetListResponse, paginationSchema, pipeUIMessageStreamToReply, promoteStreamTokenToHeader, queryParams, responses, scheduleBackground, simpleEqualityMatcher, toJsonSchema, validateResourceConfig, withCompensation };
+export { ArcError, ArcQueryParser, CircuitBreaker, CircuitBreakerError, CircuitBreakerRegistry, CircuitState, ConflictError, ForbiddenError, MONGO_DIALECT, NEUTRAL_DIALECT, NotFoundError, OrgAccessDeniedError, OrgRequiredError, RateLimitError, ServiceUnavailableError, UI_MESSAGE_STREAM_HEADERS, UnauthorizedError, ValidationError, aggregateListResponse, assertValidConfig, bareListResponse, convertOpenApiSchemas, convertRouteSchema, createCircuitBreaker, createCircuitBreakerRegistry, createDomainError, createError, createQueryParser, createStateMachine, defineCompensation, defineErrorMapper, defineGuard, deleteResponse, errorContractSchema, errorDetailSchema, formatValidationErrors, forwardedStreamHeaders, getDefaultCrudSchemas, getHeader, getListQueryParams, getUserId, handleRaw, hasEvents, isArcError, isJsonSchema, isReadableStream, isZodSchema, keysetListResponse, listResponse, offsetListResponse, openSseStream, paginationSchema, pipeUIMessageStreamToReply, promoteStreamTokenToHeader, queryParams, responses, scheduleBackground, simpleEqualityMatcher, toJsonSchema, validateResourceConfig, withCompensation };

package/dist/{utils-FhJ88TJE.mjs → utils-CZyeRXTh.mjs}

@@ -1,75 +1,8 @@
 import { m as RESERVED_QUERY_PARAMS, t as CRUD_OPERATIONS } from "./constants-DNre0wRg.mjs";
 import { arcLog } from "./logger/index.mjs";
 import { t as ArcError } from "./errors-DkO8Nk6-.mjs";
-import { r as getAvailablePresets } from "./presets-gw0ciIUD.mjs";
+import { r as getAvailablePresets } from "./presets-BOe4Ugkl.mjs";
 import { errorContractSchema as errorContractSchema$1, errorDetailSchema as errorDetailSchema$1 } from "@classytic/repo-core/errors";
-//#region src/utils/simpleEqualityMatcher.ts
-/**
-* `simpleEqualityMatcher` — a minimal, dialect-agnostic flat-key equality
-* matcher for `DataAdapter.matchesFilter` / `BaseController({ matchesFilter })`.
-*
-* **What it does:** for each `[key, expected]` in the filter, compares
-* `item[key]` to `expected` via string coercion (so Mongo `ObjectId` values
-* match their string representation) and returns `true` only if every
-* filter entry matches. Array item values are matched implicitly (contains).
-*
-* **What it does NOT do:**
-* - No `$eq` / `$ne` / `$in` / `$nin` / `$gt` / `$lt` / `$regex` / `$exists`
-* - No `$and` / `$or`
-* - No dot-path traversal (`"owner.id"`)
-* - No schema-specific coercion
-*
-* **Why it exists:** 95%+ of arc's `_policyFilters` are produced by built-in
-* permission helpers and are shaped like `{ ownerId: "u1" }` or
-* `{ organizationId: "org_x" }` — flat equality. For that common shape,
-* this helper is a safe, tested, 15-line defense-in-depth matcher that
-* hosts using minimal repos (no `getOne(compoundFilter)` DB path) can opt
-* into without arc shipping a full Mongo-syntax engine.
-*
-* **When to use:**
-* - Your adapter/repo doesn't natively filter on `getOne(compoundFilter)`
-* - Your `_policyFilters` are flat equality (from arc's built-in permission helpers)
-* - You want defense-in-depth on `validateItemAccess` / `fetchDetailed`'s `getById` fallback
-*
-* **When NOT to use:**
-* - Your `_policyFilters` use operators (`$in`, `$ne`, etc.) — supply a
-*   native matcher (mongokit's repo does the filter at the DB layer; for
-*   custom repos, wrap the kit's own predicate engine).
-* - You're a mongokit / sqlitekit / Prisma user — the DB-level filter
-*   applied by `getOne(compoundFilter)` already covers this.
-*
-* @example
-* ```ts
-* import { simpleEqualityMatcher } from '@classytic/arc/utils';
-*
-* // On a custom adapter
-* const adapter: DataAdapter = {
-*   repository,
-*   type: 'custom',
-*   name: 'in-memory',
-*   matchesFilter: simpleEqualityMatcher,
-* };
-*
-* // Or directly on BaseController for ad-hoc controllers
-* new BaseController(repo, { matchesFilter: simpleEqualityMatcher });
-* ```
-*/
-function simpleEqualityMatcher(item, filters) {
-	if (!item || typeof item !== "object") return false;
-	const obj = item;
-	for (const [key, expected] of Object.entries(filters)) {
-		if (expected && typeof expected === "object" && !Array.isArray(expected) && Object.getPrototypeOf(expected) === Object.prototype && Object.keys(expected).some((k) => k.startsWith("$"))) return false;
-		const actual = obj[key];
-		if (Array.isArray(actual)) {
-			const expectedStr = String(expected);
-			if (!actual.some((v) => String(v) === expectedStr)) return false;
-			continue;
-		}
-		if (String(actual) !== String(expected)) return false;
-	}
-	return true;
-}
-//#endregion
 //#region src/core/validateResourceConfig.ts
 /**
 * Resource Configuration Validator
@@ -837,6 +770,25 @@ function handleRaw(handler, statusCode = 200) {
 	};
 }
 //#endregion
+//#region src/utils/headers.ts
+/**
+* Read a single header value. Lowercases the name (Node normalizes incoming
+* header names to lowercase) and returns the FIRST value when the header
+* was repeated.
+*
+* Duplicate policy: first-value is deterministic, but for security-sensitive
+* headers (authorization material, forwarded-for chains, content-length) a
+* duplicate usually signals smuggling or a broken proxy — consumers that
+* care should check `Array.isArray(headers[name])` and REJECT instead of
+* picking a winner.
+*/
+function getHeader(headers, name) {
+	if (!headers) return void 0;
+	const value = headers[name.toLowerCase()];
+	if (Array.isArray(value)) return value[0];
+	return value;
+}
+//#endregion
 //#region src/utils/queryParser.ts
 /**
 * Arc Query Parser - Default URL-to-Query Parser
@@ -1778,4 +1730,4 @@ function getUserId(user) {
 	return id ? String(id) : void 0;
 }
 //#endregion
-export { createCircuitBreaker as A, defineErrorMapper as C, CircuitBreakerError as D, CircuitBreaker as E, simpleEqualityMatcher as F, assertValidConfig as M, formatValidationErrors as N, CircuitBreakerRegistry as O, validateResourceConfig as P, defineGuard as S, withCompensation as T, ArcQueryParser as _, bareListResponse as a, MONGO_DIALECT as b, errorDetailSchema$1 as c, keysetListResponse as d, listResponse as f, responses as g, queryParams as h, aggregateListResponse as i, createCircuitBreakerRegistry as j, CircuitState as k, getDefaultCrudSchemas as l, paginationSchema as m, createStateMachine as n, deleteResponse as o, offsetListResponse as p, scheduleBackground as r, errorContractSchema$1 as s, getUserId as t, getListQueryParams as u, createQueryParser as v, defineCompensation as w, NEUTRAL_DIALECT as x, handleRaw as y };
+export { CircuitState as A, defineGuard as C, CircuitBreaker as D, withCompensation as E, validateResourceConfig as F, createCircuitBreakerRegistry as M, assertValidConfig as N, CircuitBreakerError as O, formatValidationErrors as P, NEUTRAL_DIALECT as S, defineCompensation as T, ArcQueryParser as _, bareListResponse as a, handleRaw as b, errorDetailSchema$1 as c, keysetListResponse as d, listResponse as f, responses as g, queryParams as h, aggregateListResponse as i, createCircuitBreaker as j, CircuitBreakerRegistry as k, getDefaultCrudSchemas as l, paginationSchema as m, createStateMachine as n, deleteResponse as o, offsetListResponse as p, scheduleBackground as r, errorContractSchema$1 as s, getUserId as t, getListQueryParams as u, createQueryParser as v, defineErrorMapper as w, MONGO_DIALECT as x, getHeader as y };

package/dist/{versioning-DLwklPlG.d.mts → versioning-D6PvCwpq.d.mts}

@@ -26,7 +26,7 @@ interface HealthOptions {
   collectHttpMetrics?: boolean;
 }
 declare const healthPlugin: FastifyPluginAsync<HealthOptions>;
-declare const _default$4: FastifyPluginAsync<HealthOptions>;
+declare const _default$5: FastifyPluginAsync<HealthOptions>;
 //#endregion
 //#region src/plugins/caching.d.ts
 interface CachingRule {
@@ -54,7 +54,7 @@ interface CachingOptions {
   rules?: CachingRule[];
 }
 declare const cachingPlugin: FastifyPluginAsync<CachingOptions>;
-declare const _default$3: FastifyPluginAsync<CachingOptions>;
+declare const _default$4: FastifyPluginAsync<CachingOptions>;
 //#endregion
 //#region src/plugins/sse.d.ts
 interface SSEOptions {
@@ -79,7 +79,46 @@ interface SSEOptions {
   tokenQueryParam?: string | null;
 }
 declare const ssePlugin: FastifyPluginAsync<SSEOptions>;
-declare const _default$2: FastifyPluginAsync<SSEOptions>;
+declare const _default$3: FastifyPluginAsync<SSEOptions>;
+//#endregion
+//#region src/plugins/realtime.d.ts
+declare const CHANGE_OPERATIONS: readonly ["created", "updated", "deleted"];
+type ChangeOperation = (typeof CHANGE_OPERATIONS)[number];
+interface RealtimeOptions {
+  /**
+   * Route path — must contain `:resource` (default: `/realtime/:resource`).
+   */
+  path?: string;
+  /** Heartbeat interval in ms (default: 30000). */
+  heartbeat?: number;
+  /**
+   * Subscribable resources. Default: every registered resource — safe
+   * because each subscription runs that resource's own `list` permission;
+   * narrow it when only some resources should have a change feed at all.
+   */
+  resources?: readonly string[];
+  /** Operations streamed (default: created + updated + deleted). */
+  operations?: readonly ChangeOperation[];
+  /**
+   * Query parameter carrying the bearer token for browser `EventSource`
+   * clients (default `'token'`, matching the sse plugin / arc-next).
+   * Set `null` to disable promotion.
+   */
+  tokenQueryParam?: string | null;
+  /**
+   * Hard ceiling (ms) on any single connection's lifetime. Bounds
+   * permission STALENESS: the row filters are snapshotted at connect, so a
+   * caller whose permissions are revoked mid-connection keeps receiving
+   * their old view until they reconnect. Independently, arc ALWAYS closes
+   * the feed when the auth token's `exp` passes (forcing reconnect +
+   * re-authorization with fresh filters) — this option adds a cap for
+   * session/cookie auth that carries no `exp`, or to tighten below the
+   * token TTL. Omit for token-exp-only bounding.
+   */
+  maxConnectionMs?: number;
+}
+declare const realtimePlugin: FastifyPluginAsync<RealtimeOptions>;
+declare const _default$2: FastifyPluginAsync<RealtimeOptions>;
 //#endregion
 //#region src/plugins/metrics.d.ts
 interface MetricsOptions {
@@ -148,4 +187,4 @@ declare module "fastify" {
 declare const versioningPlugin: FastifyPluginAsync<VersioningOptions>;
 declare const _default: FastifyPluginAsync<VersioningOptions>;
 //#endregion
-export { HealthOptions as _, MetricsCollector as a, metricsPlugin as c, ssePlugin as d, CachingOptions as f, HealthCheck as g, cachingPlugin as h, MetricEntry as i, SSEOptions as l, _default$3 as m, _default as n, MetricsOptions as o, CachingRule as p, versioningPlugin as r, _default$1 as s, VersioningOptions as t, _default$2 as u, _default$4 as v, healthPlugin as y };
+export { healthPlugin as C, _default$5 as S, CachingRule as _, MetricsCollector as a, HealthCheck 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, HealthOptions as x, cachingPlugin as y };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/arc",
-  "version": "2.22.0",
+  "version": "2.23.0",
   "description": "Resource-oriented backend framework for Fastify - clean, minimal, powerful, tree-shakable",
   "type": "module",
   "exports": {
@@ -222,6 +222,62 @@
     "access": "public"
   },
   "sideEffects": false,
+  "arc": {
+    "subpathStability": {
+      ".": "stable",
+      "./permissions": "stable",
+      "./cache": "stable",
+      "./types": "stable",
+      "./types/storage": "stable",
+      "./core": "stable",
+      "./presets": "stable",
+      "./presets/tenant": "stable",
+      "./presets/files-upload": "stable",
+      "./presets/search": "stable",
+      "./auth": "stable",
+      "./hooks": "stable",
+      "./middleware": "stable",
+      "./pipeline": "stable",
+      "./context": "stable",
+      "./logger": "stable",
+      "./registry": "stable",
+      "./utils": "stable",
+      "./cli": "stable",
+      "./plugins": "stable",
+      "./plugins/tracing": "stable",
+      "./audit": "stable",
+      "./docs": "stable",
+      "./encryption": "stable",
+      "./idempotency": "stable",
+      "./idempotency/redis": "stable",
+      "./events": "stable",
+      "./events/redis": "stable",
+      "./events/redis-stream": "stable",
+      "./testing": "stable",
+      "./testing/storage": "stable",
+      "./factory": "stable",
+      "./schemas": "stable",
+      "./migrations": "stable",
+      "./discovery": "stable",
+      "./integrations": "stable",
+      "./integrations/streamline": "stable",
+      "./integrations/websocket": "stable",
+      "./integrations/websocket-redis": "stable",
+      "./integrations/websocket-pushref-redis": "stable",
+      "./integrations/jobs": "stable",
+      "./integrations/event-gateway": "experimental",
+      "./integrations/webhooks": "stable",
+      "./auth/redis": "stable",
+      "./plugins/response-cache": "stable",
+      "./scope": "stable",
+      "./mcp": "stable",
+      "./mcp/testing": "stable",
+      "./scim": "stable",
+      "./auth/audit": "stable",
+      "./sync": "experimental",
+      "./usage": "experimental"
+    }
+  },
   "files": [
     "dist",
     "bin",
@@ -253,14 +309,15 @@
     "release": "npm run push -- main && npm run release:tag && npm publish",
     "check:peer-skew": "node scripts/check-peer-skew.mjs",
     "check:docs-drift": "node scripts/check-docs-drift.mjs",
-    "prepublishOnly": "npm run check:peer-skew && npm run check:docs-drift && npm run typecheck && npm run lint && npm run build && npm run test:ci && npm run smoke"
+    "check:boundaries": "node scripts/check-boundaries.mjs",
+    "prepublishOnly": "npm run check:peer-skew && npm run check:docs-drift && npm run check:boundaries && npm run typecheck && npm run lint && npm run build && npm run test:ci && npm run smoke"
   },
   "engines": {
     "node": ">=22"
   },
   "peerDependencies": {
     "@classytic/primitives": ">=0.9.0",
-    "@classytic/repo-core": ">=0.7.0",
+    "@classytic/repo-core": ">=0.14.0",
     "@classytic/streamline": ">=2.7.0",
     "@fastify/cors": ">=11.0.0",
     "@fastify/helmet": ">=13.0.0",
@@ -379,11 +436,14 @@
     "@better-auth/mongo-adapter": "^1.6.19",
     "@biomejs/biome": "^2.5.0",
     "@classytic/dev-tools": "^0.2.0",
+    "@classytic/gitkit": ">=0.1.0",
     "@classytic/mongokit": "^3.22.0",
+    "@classytic/pgkit": "^0.1.0",
     "@classytic/primitives": "^0.9.1",
-    "@classytic/repo-core": "^0.13.0",
+    "@classytic/repo-core": "^0.14.0",
     "@classytic/sqlitekit": "^0.6.0",
     "@classytic/streamline": "^2.7.0",
+    "@electric-sql/pglite": "^0.5.4",
     "@fastify/cors": "^11.2.0",
     "@fastify/helmet": "^13.0.2",
     "@fastify/jwt": "^10.1.0",