@classytic/arc 2.16.0 → 2.17.0

package/dist/{index-B-ulKx5P.d.mts → index-CruZir1o.d.mts}

@@ -1,6 +1,6 @@
-import { C as RequestContext, F as FastifyWithDecorators, H as ActionDefinition, K as ArcFieldRule, Kt as AnyRecord, L as RequestWithExtras, T as CrudRouterOptions, Tt as AggregationConfig, V as ResourceDefinition, bt as IRequestContext, ft as RouteMcpConfig, mt as RouteSchemaOptions, q as CrudController, st as ResourceConfig, vt as IController, yt as IControllerResponse } from "./index-CkW0flkU.mjs";
-import { i as RequestScope } from "./types-DVfpSfx2.mjs";
-import { c as PermissionCheck } from "./fields-Anj0xdih.mjs";
+import { C as RequestContext, F as FastifyWithDecorators, H as ActionDefinition, K as ArcFieldRule, Kt as AnyRecord, L as RequestWithExtras, T as CrudRouterOptions, Tt as AggregationConfig, V as ResourceDefinition, bt as IRequestContext, ft as RouteMcpConfig, mt as RouteSchemaOptions, q as CrudController, st as ResourceConfig, vt as IController, yt as IControllerResponse } from "./index-C1JSBan-.mjs";
+import { i as RequestScope } from "./types-CfapW2t8.mjs";
+import { c as PermissionCheck } from "./fields-DqZLp5d6.mjs";
 import { FastifyReply, FastifyRequest, RouteHandlerMethod } from "fastify";
 import { z } from "zod";
 import { AggDateBucket, AggMeasure, AggTopN } from "@classytic/repo-core/repository";
@@ -240,9 +240,13 @@ declare function getEntityQuery(req: RequestWithExtras): Record<string, string>;
 //#endregion
 //#region src/core/fastifyAdapter.d.ts
 /**
- * Create IRequestContext from Fastify request
- *
- * Extracts framework-agnostic context from Fastify-specific request object
+ * Project `FastifyRequest` into the curated `IRequestContext` shape that
+ * arc's controllers receive. This is a developer-facing facade, not a
+ * portability boundary — arc is Fastify-only. The projection lifts the
+ * fields tenant-scoped controllers reach for (`organizationId`,
+ * `teamId`, `scope`, `context`, server accessor) onto a flat, typed
+ * surface so handler code doesn't have to dig through Fastify's
+ * decorator surface or `req.metadata._scope` internals.
  */
 declare function createRequestContext(req: FastifyRequest): IRequestContext;
 /**
@@ -258,25 +262,41 @@ declare function getControllerContext(req: IRequestContext): RequestContext;
  */
 declare function getControllerScope(req: IRequestContext): RequestScope;
 /**
- * Send IControllerResponse via Fastify reply
+ * Send a controller's `IControllerResponse` through Fastify's reply.
+ *
+ * The `IControllerResponse<T>` envelope is arc's internal pipeline
+ * contract — it's how custom `status`, `meta`, `headers`, and field
+ * permissions thread from a handler through interceptors to the wire
+ * without each step having to touch `reply` directly. Not a portability
+ * abstraction (arc is Fastify-only); a pipeline-internal one.
  *
- * Converts framework-agnostic response to Fastify response
- * Applies field masking if specified in request
+ * **Auto-envelope of bare returns.** Custom route handlers are
+ * expected to return the envelope shape so this function can apply
+ * field permissions, attach `fieldCaps`, and flatten paginated lists.
+ * A handler that returns raw `T` (array, plain object, primitive) used
+ * to silently produce a broken response — `response.data` was
+ * `undefined`, the body sent was `undefined`, and any declared
+ * `fields:` permission map was bypassed (the leak shape mentora
+ * flagged). 2.17 detects bare returns and wraps them into
+ * `{ data: response, status: 200 }` before the field-permission
+ * pipeline runs, so `fields:` applies to ALL custom routes whether the
+ * handler envelopes its return value or not. The envelope shape is
+ * still the canonical contract — auto-wrapping is a safety net, not
+ * an invitation to drop the envelope.
  */
 declare function sendControllerResponse<T>(reply: FastifyReply, response: IControllerResponse<T>, request?: FastifyRequest): void;
 /**
- * Create Fastify route handler from IController method
- *
- * Wraps framework-agnostic controller method in Fastify-specific handler
+ * Bridge an `IController` method (`(ctx: IRequestContext) => Promise<IControllerResponse<T>>`)
+ * into a Fastify route handler. Translates between arc's curated request
+ * context surface and Fastify's request/reply, and routes the envelope
+ * through `sendControllerResponse` so the pipeline applies field
+ * permissions, status, and meta uniformly. Internal plumbing, not a
+ * portability layer — arc is Fastify-only.
  *
  * @example
  * ```typescript
  * const controller = new BaseController(repository);
- *
- * // Create Fastify handler
  * const listHandler = createFastifyHandler(controller.list.bind(controller));
- *
- * // Register route
  * fastify.get('/products', listHandler);
  * ```
  */

package/dist/index.d.mts

@@ -1,8 +1,8 @@
-import { $t as BaseController, A as RequestIdOptions, At as AggregationRateLimit, B as defineResource, C as RequestContext, Ct as AggMeasureShorthand, D as HealthCheck, Dt as AggregationIndexHint, E as GracefulShutdownOptions, Et as AggregationDateRangeRequirement, F as FastifyWithDecorators, J as CrudRouteKey, Jt as ArcRequest, Kt as AnyRecord, L as RequestWithExtras, N as FastifyRequestExtras, O as HealthOptions, Ot as AggregationMaterializedContext, P as FastifyWithAuth, Q as MiddlewareConfig, Qt as UserOrganization, S as QueryParserInterface, St as AggMeasureInput, T as CrudRouterOptions, Tt as AggregationConfig, V as ResourceDefinition, Vt as AuthPluginOptions, X as EventDefinition, Y as CrudSchemas, Yt as JWTPayload, Z as FieldRule, _n as ArcListResult, a as InferAdapterDoc, an as SlugMixin, bt as IRequestContext, c as TypedController, cn as BaseControllerOptions, d as PaginationResult, dn as ControllerConstructionOptions, en as SoftDeleteExt, f as IntrospectionData, g as ArcInternalMetadata, gn as ArcGetResult, gt as ControllerLike, h as ResourceMetadata, hn as ArcDeleteResult, i as ValidationResult, in as SlugExt, it as RateLimitConfig, jt as AggregationsMap, k as IntrospectionPluginOptions, kt as AggregationMaterializedResult, l as TypedRepository, ln as BaseCrudController, m as RegistryStats, mn as ArcCreateResult, mt as RouteSchemaOptions, n as ConfigError, nn as TreeExt, o as InferDocType, on as BulkExt, p as RegistryEntry, q as CrudController, qt as ApiResponse, r as ValidateOptions, rn as TreeMixin, rt as PresetResult, s as InferResourceDoc, sn as BulkMixin, st as ResourceConfig, t as RouteHandlerMethod, tn as SoftDeleteMixin, tt as PresetFunction, u as TypedResourceConfig, un as ControllerConfigurableOptions, vn as ArcUpdateResult, vt as IController, w as ServiceContext, wt as AggregationCacheConfig, xt as RouteHandler, y as OwnershipCheck, yn as ListResult, yt as IControllerResponse } from "./index-CkW0flkU.mjs";
-import { a as applyFieldWritePermissions, c as PermissionCheck, d as UserBase, i as applyFieldReadPermissions, l as PermissionContext, n as FieldPermissionMap, o as fields, t as FieldPermission, u as PermissionResult } from "./fields-Anj0xdih.mjs";
-import { A as MAX_FILTER_DEPTH, C as DEFAULT_SORT, D as HOOK_PHASES, E as HOOK_OPERATIONS, F as RESERVED_QUERY_PARAMS, I as SYSTEM_FIELDS, M as MAX_SEARCH_LENGTH, N as MUTATION_OPERATIONS, O as HookOperation, P as MutationOperation, S as DEFAULT_MAX_LIMIT, T as DEFAULT_UPDATE_METHOD, _ as defineAggregation, b as DEFAULT_ID_FIELD, f as defineResourceVariants, j as MAX_REGEX_LENGTH, k as HookPhase, m as defineAction, s as getControllerScope, v as CRUD_OPERATIONS, w as DEFAULT_TENANT_FIELD, x as DEFAULT_LIMIT, y as CrudOperation } from "./index-B-ulKx5P.mjs";
-import { A as requireRoles, C as allOf, E as denyAll, M as when, O as requireAuth, S as createOrgPermissions, T as anyOf, a as presets_d_exports, c as readOnly, d as requireOrgRole, f as requireScopeContext, i as ownerWithAdminBypass, k as requireOwnership, l as requireOrgInScope, m as requireTeamMembership, n as authenticated, o as publicRead, p as requireServiceScope, r as fullPublic, s as publicReadAdminWrite, t as adminOnly, u as requireOrgMembership, v as DynamicPermissionMatrix, w as allowPublic, x as createDynamicPermissionMatrix, y as DynamicPermissionMatrixConfig } from "./index-3oIimXQn.mjs";
-import { a as NotFoundError, d as ValidationError, f as createDomainError, i as ForbiddenError, t as ArcError, u as UnauthorizedError } from "./errors-C1lX_jlm.mjs";
+import { $t as BaseController, A as RequestIdOptions, At as AggregationRateLimit, B as defineResource, C as RequestContext, Ct as AggMeasureShorthand, D as HealthCheck, Dt as AggregationIndexHint, E as GracefulShutdownOptions, Et as AggregationDateRangeRequirement, F as FastifyWithDecorators, J as CrudRouteKey, Jt as ArcRequest, Kt as AnyRecord, L as RequestWithExtras, N as FastifyRequestExtras, O as HealthOptions, Ot as AggregationMaterializedContext, P as FastifyWithAuth, Q as MiddlewareConfig, Qt as UserOrganization, S as QueryParserInterface, St as AggMeasureInput, T as CrudRouterOptions, Tt as AggregationConfig, V as ResourceDefinition, Vt as AuthPluginOptions, X as EventDefinition, Y as CrudSchemas, Yt as JWTPayload, Z as FieldRule, _n as ArcListResult, a as InferAdapterDoc, an as SlugMixin, bt as IRequestContext, c as TypedController, cn as BaseControllerOptions, d as PaginationResult, dn as ControllerConstructionOptions, en as SoftDeleteExt, f as IntrospectionData, g as ArcInternalMetadata, gn as ArcGetResult, gt as ControllerLike, h as ResourceMetadata, hn as ArcDeleteResult, i as ValidationResult, in as SlugExt, it as RateLimitConfig, jt as AggregationsMap, k as IntrospectionPluginOptions, kt as AggregationMaterializedResult, l as TypedRepository, ln as BaseCrudController, m as RegistryStats, mn as ArcCreateResult, mt as RouteSchemaOptions, n as ConfigError, nn as TreeExt, o as InferDocType, on as BulkExt, p as RegistryEntry, q as CrudController, qt as ApiResponse, r as ValidateOptions, rn as TreeMixin, rt as PresetResult, s as InferResourceDoc, sn as BulkMixin, st as ResourceConfig, t as RouteHandlerMethod, tn as SoftDeleteMixin, tt as PresetFunction, u as TypedResourceConfig, un as ControllerConfigurableOptions, vn as ArcUpdateResult, vt as IController, w as ServiceContext, wt as AggregationCacheConfig, xt as RouteHandler, y as OwnershipCheck, yn as ListResult, yt as IControllerResponse } from "./index-C1JSBan-.mjs";
+import { a as applyFieldWritePermissions, c as PermissionCheck, d as UserBase, i as applyFieldReadPermissions, l as PermissionContext, n as FieldPermissionMap, o as fields, t as FieldPermission, u as PermissionResult } from "./fields-DqZLp5d6.mjs";
+import { A as MAX_FILTER_DEPTH, C as DEFAULT_SORT, D as HOOK_PHASES, E as HOOK_OPERATIONS, F as RESERVED_QUERY_PARAMS, I as SYSTEM_FIELDS, M as MAX_SEARCH_LENGTH, N as MUTATION_OPERATIONS, O as HookOperation, P as MutationOperation, S as DEFAULT_MAX_LIMIT, T as DEFAULT_UPDATE_METHOD, _ as defineAggregation, b as DEFAULT_ID_FIELD, f as defineResourceVariants, j as MAX_REGEX_LENGTH, k as HookPhase, m as defineAction, s as getControllerScope, v as CRUD_OPERATIONS, w as DEFAULT_TENANT_FIELD, x as DEFAULT_LIMIT, y as CrudOperation } from "./index-CruZir1o.mjs";
+import { A as requireRoles, C as allOf, E as denyAll, M as when, O as requireAuth, S as createOrgPermissions, T as anyOf, a as presets_d_exports, c as readOnly, d as requireOrgRole, f as requireScopeContext, i as ownerWithAdminBypass, k as requireOwnership, l as requireOrgInScope, m as requireTeamMembership, n as authenticated, o as publicRead, p as requireServiceScope, r as fullPublic, s as publicReadAdminWrite, t as adminOnly, u as requireOrgMembership, v as DynamicPermissionMatrix, w as allowPublic, x as createDynamicPermissionMatrix, y as DynamicPermissionMatrixConfig } from "./index-3L-adFJO.mjs";
+import { a as NotFoundError, d as ValidationError, f as createDomainError, i as ForbiddenError, t as ArcError, u as UnauthorizedError } from "./errors-4ZloYFvm.mjs";
 
 //#region src/index.d.ts
 declare const version: string;

package/dist/index.mjs

@@ -1,10 +1,10 @@
 import { a as DEFAULT_SORT, c as HOOK_OPERATIONS, d as MAX_REGEX_LENGTH, f as MAX_SEARCH_LENGTH, h as SYSTEM_FIELDS, i as DEFAULT_MAX_LIMIT, l as HOOK_PHASES, m as RESERVED_QUERY_PARAMS, n as DEFAULT_ID_FIELD, o as DEFAULT_TENANT_FIELD, p as MUTATION_OPERATIONS, r as DEFAULT_LIMIT, s as DEFAULT_UPDATE_METHOD, t as CRUD_OPERATIONS, u as MAX_FILTER_DEPTH } from "./constants-TrJVIJl0.mjs";
 import { d as createDomainError, i as NotFoundError, l as UnauthorizedError, r as ForbiddenError, t as ArcError, u as ValidationError } from "./errors-j4aJm1Wg.mjs";
-import { a as BulkMixin, i as SlugMixin, n as TreeMixin, o as BaseCrudController, r as SoftDeleteMixin, t as BaseController } from "./BaseController-DlCCTIxJ.mjs";
-import { C as allowPublic, D as requireAuth, O as requireOwnership, S as allOf, T as denyAll, _ as requireOrgMembership, a as presets_exports, b as requireServiceScope, c as readOnly, d as applyFieldWritePermissions, f as fields, g as requireOrgInScope, h as createOrgPermissions, i as ownerWithAdminBypass, j as when, k as requireRoles, m as createDynamicPermissionMatrix, n as authenticated, o as publicRead, r as fullPublic, s as publicReadAdminWrite, t as adminOnly, u as applyFieldReadPermissions, v as requireOrgRole, w as anyOf, x as requireTeamMembership, y as requireScopeContext } from "./permissions-CTxMrreC.mjs";
-import { v as getControllerScope } from "./routerShared-CZV5aabX.mjs";
-import { a as defineResource, i as defineResourceVariants, o as ResourceDefinition, s as defineAction, u as defineAggregation } from "./core-DBJ_j6rX.mjs";
+import { a as BulkMixin, i as SlugMixin, n as TreeMixin, o as BaseCrudController, r as SoftDeleteMixin, t as BaseController } from "./BaseController-Dmeh4Y_y.mjs";
+import { C as requireAuth, D as when, M as applyFieldWritePermissions, N as fields, T as requireRoles, _ as requireTeamMembership, a as presets_exports, b as anyOf, c as readOnly, d as createOrgPermissions, f as requireOrgInScope, g as requireServiceScope, h as requireScopeContext, i as ownerWithAdminBypass, j as applyFieldReadPermissions, m as requireOrgRole, n as authenticated, o as publicRead, p as requireOrgMembership, r as fullPublic, s as publicReadAdminWrite, t as adminOnly, u as createDynamicPermissionMatrix, v as allOf, w as requireOwnership, x as denyAll, y as allowPublic } from "./permissions-B1Qy55fg.mjs";
+import { x as getControllerScope } from "./routerShared-nCyJGOKX.mjs";
+import { a as defineResource, i as defineResourceVariants, o as ResourceDefinition, s as defineAction, u as defineAggregation } from "./core-DYJvu7aI.mjs";
 //#region src/index.ts
-const version = "2.16.0";
+const version = "2.17.0";
 //#endregion
 export { ArcError, BaseController, BaseCrudController, BulkMixin, CRUD_OPERATIONS, DEFAULT_ID_FIELD, DEFAULT_LIMIT, DEFAULT_MAX_LIMIT, DEFAULT_SORT, DEFAULT_TENANT_FIELD, DEFAULT_UPDATE_METHOD, ForbiddenError, HOOK_OPERATIONS, HOOK_PHASES, MAX_FILTER_DEPTH, MAX_REGEX_LENGTH, MAX_SEARCH_LENGTH, MUTATION_OPERATIONS, NotFoundError, RESERVED_QUERY_PARAMS, ResourceDefinition, SYSTEM_FIELDS, SlugMixin, SoftDeleteMixin, TreeMixin, UnauthorizedError, ValidationError, adminOnly, allOf, allowPublic, anyOf, applyFieldReadPermissions, applyFieldWritePermissions, authenticated, createDomainError, createDynamicPermissionMatrix, createOrgPermissions, defineAction, defineAggregation, defineResource, defineResourceVariants, denyAll, fields, fullPublic, getControllerScope, ownerWithAdminBypass, presets_exports as permissions, publicRead, publicReadAdminWrite, readOnly, requireAuth, requireOrgInScope, requireOrgMembership, requireOrgRole, requireOwnership, requireRoles, requireScopeContext, requireServiceScope, requireTeamMembership, version, when };

package/dist/integrations/event-gateway.d.mts

@@ -1,5 +1,5 @@
-import { n as DomainEvent } from "../EventTransport-C-2oAHtw.mjs";
-import { a as WebSocketMessage, i as WebSocketClient } from "../websocket-BkjeGZRn.mjs";
+import { n as DomainEvent } from "../EventTransport-B1GFiYUy.mjs";
+import { a as WebSocketMessage, i as WebSocketClient } from "../websocket-BJ0w-3Dt.mjs";
 import { FastifyPluginAsync, FastifyRequest } from "fastify";
 
 //#region src/integrations/event-gateway.d.ts

package/dist/integrations/event-gateway.mjs

@@ -4,7 +4,7 @@ const eventGatewayPluginImpl = async (fastify, opts = {}) => {
 	const { auth = true, orgScoped = false, roomPolicy, maxMessageBytes, maxSubscriptionsPerClient, authenticate } = opts;
 	if (auth && !authenticate && !fastify.hasDecorator("authenticate")) throw new Error("[arc-event-gateway] auth is true but fastify.authenticate is not registered. Register an auth plugin first, provide a custom authenticate function, or set auth: false.");
 	if (opts.sse !== false) {
-		const { default: ssePlugin } = await import("../sse-BY6sTy4P.mjs").then((n) => n.r);
+		const { default: ssePlugin } = await import("../sse-jh5OqFjR.mjs").then((n) => n.r);
 		await fastify.register(ssePlugin, {
 			path: opts.sse?.path ?? "/events/stream",
 			requireAuth: auth,

package/dist/integrations/index.d.mts

@@ -1,7 +1,7 @@
-import { a as WebSocketMessage, i as WebSocketClient, o as WebSocketPluginOptions } from "../websocket-BkjeGZRn.mjs";
+import { a as WebSocketMessage, i as WebSocketClient, o as WebSocketPluginOptions } from "../websocket-BJ0w-3Dt.mjs";
 import { EventGatewayOptions } from "./event-gateway.mjs";
 import { JobDefinition, JobDispatchOptions, JobDispatcher, JobMeta, JobsPluginOptions, QueueStats } from "./jobs.mjs";
-import { c as McpAuthResult, d as PromptDefinition, g as ToolDefinition, h as ToolContext, l as McpPluginOptions, m as ToolAnnotations, n as CallToolResult, o as CrudOperation, r as CreateMcpServerConfig, t as BetterAuthHandler, u as McpResourceConfig } from "../types-BsJMEQ4D.mjs";
+import { c as McpAuthResult, d as PromptDefinition, g as ToolDefinition, h as ToolContext, l as McpPluginOptions, m as ToolAnnotations, n as CallToolResult, o as CrudOperation, r as CreateMcpServerConfig, t as BetterAuthHandler, u as McpResourceConfig } from "../types-CoMjNmkF.mjs";
 import { StreamlinePluginOptions, WorkflowLike, WorkflowRunLike } from "./streamline.mjs";
 import { WebhookDeliveryRecord, WebhookManager, WebhookPluginOptions, WebhookStore, WebhookSubscription } from "./webhooks.mjs";
 export { type BetterAuthHandler, type CallToolResult, type CreateMcpServerConfig, type CrudOperation, type EventGatewayOptions, type JobDefinition, type JobDispatchOptions, type JobDispatcher, type JobMeta, type JobsPluginOptions, type McpAuthResult, type McpPluginOptions, type McpResourceConfig, type PromptDefinition, type QueueStats, type StreamlinePluginOptions, type ToolAnnotations, type ToolContext, type ToolDefinition, type WebSocketClient, type WebSocketMessage, type WebSocketPluginOptions, type WebhookDeliveryRecord, type WebhookManager, type WebhookPluginOptions, type WebhookStore, type WebhookSubscription, type WorkflowLike, type WorkflowRunLike };

package/dist/integrations/jobs.d.mts

@@ -39,6 +39,14 @@ interface JobDefinition<TData = unknown, TResult = unknown> {
   deadLetterQueue?: string;
   /** Repeat schedule — cron or interval. Requires explicit timezone for cron. */
   repeat?: JobRepeatOptions;
+  /**
+   * Arc-level semaphore: max simultaneous handler executions for this job type.
+   * Jobs that dequeue while all slots are full are held (state stays `active`)
+   * and appear as `throttled: true` in `GET /jobs/:id/status`.
+   * Distinct from BullMQ `concurrency` — use this when the constraint is a
+   * downstream resource (AI model rate limit, DB connection pool, external API).
+   */
+  maxConcurrent?: number;
 }
 interface JobMeta {
   jobId: string;
@@ -59,6 +67,27 @@ interface JobDispatchOptions {
   /** One-shot repeat override at dispatch time. Usually prefer `JobDefinition.repeat`. */
   repeat?: JobRepeatOptions;
 }
+/** Point-in-time snapshot of a single job. */
+interface JobStatus {
+  id: string;
+  /** Registered job name (= queue name). */
+  name: string;
+  state: "waiting" | "active" | "completed" | "failed" | "delayed" | "unknown";
+  /** Progress reported by the handler via BullMQ `job.updateProgress()`. */
+  progress: number | Record<string, unknown>;
+  /** True when the job is dequeued by a worker but blocked on a `maxConcurrent` semaphore slot. */
+  throttled?: boolean;
+  /** Unix ms when the job was enqueued. */
+  timestamp?: number;
+  /** Unix ms when processing started. */
+  processedOn?: number;
+  /** Unix ms when the job finished (completed or failed). */
+  finishedOn?: number;
+  /** Failure message when `state === 'failed'`. */
+  failedReason?: string;
+  /** Handler return value when `state === 'completed'` (only present if removeOnComplete hasn't cleared the job). */
+  returnValue?: unknown;
+}
 interface JobsPluginOptions {
   /** Redis connection options (passed to BullMQ) */
   connection: {
@@ -91,6 +120,12 @@ interface JobDispatcher {
   }>;
   getQueue(name: string): unknown | null;
   getStats(): Promise<Record<string, QueueStats>>;
+  /**
+   * Fetch a point-in-time status snapshot for a job by its ID.
+   * Searches across all registered queues.
+   * Returns `null` if the job doesn't exist or has been removed by retention policy.
+   */
+  getStatus(jobId: string): Promise<JobStatus | null>;
   close(): Promise<void>;
 }
 interface QueueStats {
@@ -122,4 +157,4 @@ declare function defineJob<TData = unknown, TResult = unknown>(definition: JobDe
  */
 declare const jobsPlugin: FastifyPluginAsync<JobsPluginOptions>;
 //#endregion
-export { JobDefinition, JobDispatchOptions, JobDispatcher, JobMeta, JobRepeatOptions, JobsPluginOptions, QueueStats, defineJob, jobsPlugin };
+export { JobDefinition, JobDispatchOptions, JobDispatcher, JobMeta, JobRepeatOptions, JobStatus, JobsPluginOptions, QueueStats, defineJob, jobsPlugin };

package/dist/integrations/jobs.mjs

@@ -16,6 +16,30 @@ import fp from "fastify-plugin";
 function defineJob(definition) {
 	return definition;
 }
+var Semaphore = class {
+	available;
+	waiters = [];
+	constructor(permits) {
+		this.available = permits;
+	}
+	get isFull() {
+		return this.available === 0;
+	}
+	acquire() {
+		if (this.available > 0) {
+			this.available--;
+			return Promise.resolve();
+		}
+		return new Promise((resolve) => {
+			this.waiters.push(resolve);
+		});
+	}
+	release() {
+		const next = this.waiters.shift();
+		if (next) next();
+		else this.available++;
+	}
+};
 const jobsPluginImpl = async (fastify, options) => {
 	const { connection, jobs, prefix = "/jobs", bridgeEvents = true, defaults = {} } = options;
 	let Queue;
@@ -33,6 +57,7 @@ const jobsPluginImpl = async (fastify, options) => {
 	const queues = /* @__PURE__ */ new Map();
 	const dlqQueues = /* @__PURE__ */ new Map();
 	const workers = /* @__PURE__ */ new Map();
+	const throttledJobs = /* @__PURE__ */ new Map();
 	for (const job of jobs) {
 		if (!job.repeat) continue;
 		const { pattern, every, tz } = job.repeat;
@@ -66,24 +91,39 @@ const jobsPluginImpl = async (fastify, options) => {
 			dlqQueues.set(dlqName, dlqQueue);
 		}
 		const jobTimeout = job.timeout ?? defaults.timeout;
+		const semaphore = job.maxConcurrent != null ? new Semaphore(job.maxConcurrent) : null;
+		const throttledSet = /* @__PURE__ */ new Set();
+		throttledJobs.set(queueName, throttledSet);
 		const worker = new Worker(queueName, async (bullJob) => {
 			const meta = {
 				jobId: bullJob.id ?? "",
 				attemptsMade: bullJob.attemptsMade ?? 0,
 				timestamp: Date.now()
 			};
-			let result;
-			if (jobTimeout) {
-				let timer;
-				const timeoutPromise = new Promise((_, reject) => {
-					timer = setTimeout(() => reject(/* @__PURE__ */ new Error(`Job '${queueName}' timed out after ${jobTimeout}ms`)), jobTimeout);
-				});
+			if (semaphore) {
+				if (semaphore.isFull) throttledSet.add(bullJob.id ?? "");
 				try {
-					result = await Promise.race([job.handler(bullJob.data, meta), timeoutPromise]);
+					await semaphore.acquire();
 				} finally {
-					clearTimeout(timer);
+					throttledSet.delete(bullJob.id ?? "");
 				}
-			} else result = await job.handler(bullJob.data, meta);
+			}
+			let result;
+			try {
+				if (jobTimeout) {
+					let timer;
+					const timeoutPromise = new Promise((_, reject) => {
+						timer = setTimeout(() => reject(/* @__PURE__ */ new Error(`Job '${queueName}' timed out after ${jobTimeout}ms`)), jobTimeout);
+					});
+					try {
+						result = await Promise.race([job.handler(bullJob.data, meta), timeoutPromise]);
+					} finally {
+						clearTimeout(timer);
+					}
+				} else result = await job.handler(bullJob.data, meta);
+			} finally {
+				semaphore?.release();
+			}
 			if (bridgeEvents && fastify.events?.publish) try {
 				await fastify.events.publish(`job.${queueName}.completed`, {
 					jobId: bullJob.id,
@@ -197,6 +237,27 @@ const jobsPluginImpl = async (fastify, options) => {
 			}
 			return stats;
 		},
+		async getStatus(jobId) {
+			for (const [name, queue] of queues) {
+				const job = await queue.getJob(jobId);
+				if (!job) continue;
+				const state = typeof job.getState === "function" ? await job.getState() : "unknown";
+				const throttled = throttledJobs.get(name)?.has(jobId) || void 0;
+				return {
+					id: jobId,
+					name,
+					state,
+					progress: job.progress ?? 0,
+					throttled: throttled === true ? true : void 0,
+					timestamp: job.timestamp ?? void 0,
+					processedOn: job.processedOn ?? void 0,
+					finishedOn: job.finishedOn ?? void 0,
+					failedReason: job.failedReason ?? void 0,
+					returnValue: job.returnvalue ?? void 0
+				};
+			}
+			return null;
+		},
 		async close() {
 			await Promise.all(Array.from(workers.values()).map((w) => w.pause().catch(() => {})));
 			const closePromises = [];
@@ -213,6 +274,18 @@ const jobsPluginImpl = async (fastify, options) => {
 			data: await dispatcher.getStats()
 		};
 	});
+	fastify.get(`${prefix}/:id/status`, async (req, reply) => {
+		const { id } = req.params;
+		const status = await dispatcher.getStatus(id);
+		if (!status) return reply.status(404).send({
+			success: false,
+			error: "Job not found"
+		});
+		return {
+			success: true,
+			data: status
+		};
+	});
 	fastify.addHook("onClose", async () => {
 		await dispatcher.close();
 	});

package/dist/integrations/mcp/index.d.mts

@@ -1,7 +1,7 @@
-import { V as ResourceDefinition, bt as IRequestContext, yt as IControllerResponse } from "../../index-CkW0flkU.mjs";
-import { i as RequestScope } from "../../types-DVfpSfx2.mjs";
-import { c as PermissionCheck } from "../../fields-Anj0xdih.mjs";
-import { a as CrudDescriptionOverride, c as McpAuthResult, d as PromptDefinition, f as PromptResult, g as ToolDefinition, h as ToolContext, i as CrudDescriptionMeta, l as McpPluginOptions, m as ToolAnnotations, n as CallToolResult, o as CrudOperation, p as SessionEntry, r as CreateMcpServerConfig, s as McpAuthResolver, t as BetterAuthHandler, u as McpResourceConfig } from "../../types-BsJMEQ4D.mjs";
+import { V as ResourceDefinition, bt as IRequestContext, yt as IControllerResponse } from "../../index-C1JSBan-.mjs";
+import { i as RequestScope } from "../../types-CfapW2t8.mjs";
+import { c as PermissionCheck } from "../../fields-DqZLp5d6.mjs";
+import { a as CrudDescriptionOverride, c as McpAuthResult, d as PromptDefinition, f as PromptResult, g as ToolDefinition, h as ToolContext, i as CrudDescriptionMeta, l as McpPluginOptions, m as ToolAnnotations, n as CallToolResult, o as CrudOperation, p as SessionEntry, r as CreateMcpServerConfig, s as McpAuthResolver, t as BetterAuthHandler, u as McpResourceConfig } from "../../types-CoMjNmkF.mjs";
 import { ErrorContract } from "@classytic/repo-core/errors";
 import { FastifyPluginAsync } from "fastify";
 import { z } from "zod";
@@ -54,6 +54,47 @@ interface BuildMcpToolsFromBridgesOptions {
  */
 declare function buildMcpToolsFromBridges(bridges: readonly McpBridge[], options?: BuildMcpToolsFromBridgesOptions): ToolDefinition[];
 //#endregion
+//#region src/integrations/mcp/betterAuthApiKey.d.ts
+/** Minimal subset of Better Auth's API-key record the helper needs. */
+interface BetterAuthKeyRecord {
+  id?: string;
+  userId?: string;
+  referenceId?: string;
+  metadata?: unknown;
+  permissions?: unknown;
+  scopes?: unknown;
+  expiresAt?: string | Date | null;
+  disabled?: boolean;
+  name?: string | null;
+}
+interface CreateMcpAuthFromBetterAuthApiKeyOptions {
+  /**
+   * How to resolve the organization id from a verified key.
+   *
+   * - `true` (default) — read `key.metadata.organizationId`.
+   * - `false` — never set `organizationId` (single-tenant deployments).
+   * - `(metadata, key) => string | undefined` — custom extractor, e.g.
+   *   `(m) => m?.tenantId` for hosts that named the column differently.
+   */
+  orgFromMetadata?: boolean | ((metadata: unknown, key: BetterAuthKeyRecord) => string | undefined);
+  /**
+   * Field name on `metadata` that holds the org id. Default
+   * `"organizationId"`. Ignored when `orgFromMetadata` is a function.
+   */
+  metadataOrgField?: string;
+  /**
+   * Permission scope name inside `key.permissions` that should be flattened
+   * onto `McpAuthResult.scopes`. Default `"mcp"` — matches Better Auth's
+   * docs example. Set to `false` to keep scopes empty.
+   */
+  permissionScope?: string | false;
+}
+/**
+ * Build an {@link McpAuthResolver} that authenticates MCP requests against
+ * Better Auth's API-key plugin. See module docstring for the rationale.
+ */
+declare function createMcpAuthFromBetterAuthApiKey(auth: BetterAuthHandler, options?: CreateMcpAuthFromBetterAuthApiKeyOptions): McpAuthResolver;
+//#endregion
 //#region src/integrations/mcp/createMcpServer.d.ts
 /**
  * Mutable auth ref — updated per-request by mcpPlugin.
@@ -69,6 +110,27 @@ interface AuthRef {
  * @returns McpServer instance (not yet connected to a transport)
  */
 declare function createMcpServer(config: CreateMcpServerConfig, authRef?: AuthRef): Promise<McpServerInstance>;
+/**
+ * Detect and resolve duplicate MCP tool names across the assembled tool list.
+ *
+ * Two outcomes:
+ *
+ *  1. **Auto-namespace** — when one tool's `source` carries a `preset:<name>`
+ *     prefix and the other doesn't, the preset tool is renamed to
+ *     `<presetName>_<originalName>` (e.g. softDelete's `restore_post`
+ *     becomes `softdelete_restore_post` when the user defines
+ *     `actions.restore`). The user's tool wins the canonical name because
+ *     it's the more-specific intent.
+ *
+ *  2. **Typed throw** — every other collision (two user actions, two
+ *     custom routes, two presets) raises `ArcError('arc.mcp.tool_name_collision')`
+ *     naming both sources so the host's stack trace points at the
+ *     resource definitions, not the MCP SDK internals.
+ *
+ * Exported for the testing harness so collision behaviour can be exercised
+ * without a full server boot.
+ */
+declare function resolveToolCollisions(tools: readonly ToolDefinition[]): ToolDefinition[];
 /** Minimal interface for McpServer — avoids hard SDK type dependency */
 interface McpServerInstance {
   connect: (transport: unknown) => Promise<void>;
@@ -516,4 +578,4 @@ declare function permissionDeniedResult(args: {
   session: McpAuthResult | null;
 }): CallToolResult;
 //#endregion
-export { type AuthRef, type BetterAuthHandler, type BuildMcpToolsFromBridgesOptions, type CallToolResult, type CreateMcpServerConfig, type CrudDescriptionMeta, type CrudDescriptionOverride, type CrudOperation, type DefinePromptConfig, type DefineToolConfig, type FieldRuleEntry, type FieldRulesToZodOptions, type InvokeControllerOptions, type McpAuthResolver, type McpAuthResult, type McpBridge, type McpGuard, type McpOperation, type McpPluginOptions, type McpResourceConfig, type McpServerInstance, type PromptDefinition, type PromptResult, type ResourceToToolsConfig, type ToolAnnotations, type ToolContext, type ToolDefinition, bridgeToMcp, buildMcpToolsFromBridges, buildRequestContext, createMcpServer, customGuard, defaultCrudDescription, definePrompt, defineTool, denied, fieldRulesToZod, filterResourcesForMcp, getOrgId, getUserId, guard, hasOrg, invokeController, isAuthenticated, isOrg, mcpHandlerAdapter, mcpPlugin, permissionDeniedResult, requireAuth, requireOrg, requireOrgId, requireRole, resolveCrudDescription, resourceToTools, toCallToolError, toCallToolResult, toCallToolSuccess };
+export { type AuthRef, type BetterAuthHandler, type BuildMcpToolsFromBridgesOptions, type CallToolResult, type CreateMcpAuthFromBetterAuthApiKeyOptions, type CreateMcpServerConfig, type CrudDescriptionMeta, type CrudDescriptionOverride, type CrudOperation, type DefinePromptConfig, type DefineToolConfig, type FieldRuleEntry, type FieldRulesToZodOptions, type InvokeControllerOptions, type McpAuthResolver, type McpAuthResult, type McpBridge, type McpGuard, type McpOperation, type McpPluginOptions, type McpResourceConfig, type McpServerInstance, type PromptDefinition, type PromptResult, type ResourceToToolsConfig, type ToolAnnotations, type ToolContext, type ToolDefinition, bridgeToMcp, buildMcpToolsFromBridges, buildRequestContext, createMcpAuthFromBetterAuthApiKey, createMcpServer, customGuard, defaultCrudDescription, definePrompt, defineTool, denied, fieldRulesToZod, filterResourcesForMcp, getOrgId, getUserId, guard, hasOrg, invokeController, isAuthenticated, isOrg, mcpHandlerAdapter, mcpPlugin, permissionDeniedResult, requireAuth, requireOrg, requireOrgId, requireRole, resolveCrudDescription, resolveToolCollisions, resourceToTools, toCallToolError, toCallToolResult, toCallToolSuccess };

package/dist/integrations/mcp/index.mjs

@@ -1,4 +1,4 @@
-import { a as defaultCrudDescription, c as mcpHandlerAdapter, d as toCallToolResult, f as toCallToolSuccess, i as fieldRulesToZod, l as permissionDeniedResult, m as createMcpServer, n as mcpPlugin, o as resolveCrudDescription, p as buildRequestContext, r as resourceToTools, s as invokeController, t as filterResourcesForMcp, u as toCallToolError } from "../../mcpPlugin-7vGV51ED.mjs";
+import { a as defaultCrudDescription, c as mcpHandlerAdapter, d as toCallToolResult, f as toCallToolSuccess, h as resolveToolCollisions, i as fieldRulesToZod, l as permissionDeniedResult, m as createMcpServer, n as mcpPlugin, o as resolveCrudDescription, p as buildRequestContext, r as resourceToTools, s as invokeController, t as filterResourcesForMcp, u as toCallToolError } from "../../mcpPlugin-hZE00H74.mjs";
 //#region src/integrations/mcp/defineTool.ts
 /**
 * Define a type-safe MCP tool.
@@ -167,6 +167,97 @@ function buildMcpToolsFromBridges(bridges, options = {}) {
 	}).map(bridgeToMcp);
 }
 //#endregion
+//#region src/integrations/mcp/betterAuthApiKey.ts
+/**
+* Build an {@link McpAuthResolver} that authenticates MCP requests against
+* Better Auth's API-key plugin. See module docstring for the rationale.
+*/
+function createMcpAuthFromBetterAuthApiKey(auth, options = {}) {
+	const verifyApiKey = auth.api?.verifyApiKey;
+	if (typeof verifyApiKey !== "function") throw new Error("createMcpAuthFromBetterAuthApiKey: the provided Better Auth instance does not expose `api.verifyApiKey`. Register the `apiKey()` plugin on your auth instance (see https://www.better-auth.com/docs/plugins/api-key) and pass the same `auth` object you pass to your REST routes.");
+	const orgFromMetadata = options.orgFromMetadata ?? true;
+	const metadataOrgField = options.metadataOrgField ?? "organizationId";
+	const permissionScope = options.permissionScope === void 0 ? "mcp" : options.permissionScope;
+	return async (headers) => {
+		const apiKey = extractApiKey(headers);
+		if (!apiKey) return null;
+		let result;
+		try {
+			result = await verifyApiKey({
+				body: { key: apiKey },
+				headers
+			});
+		} catch {
+			return null;
+		}
+		if (!result?.valid || !result.key) return null;
+		const key = result.key;
+		if (key.disabled === true) return null;
+		if (key.expiresAt) {
+			const exp = key.expiresAt instanceof Date ? key.expiresAt : new Date(key.expiresAt);
+			if (Number.isFinite(exp.getTime()) && exp.getTime() < Date.now()) return null;
+		}
+		const userId = key.userId ?? key.referenceId;
+		const organizationId = resolveOrg(key, orgFromMetadata, metadataOrgField);
+		const scopes = resolveScopes(key, permissionScope);
+		const clientId = !userId && key.id ? key.id : void 0;
+		if (!userId && !clientId) return null;
+		return {
+			...userId ? { userId } : {},
+			...organizationId ? { organizationId } : {},
+			...clientId ? { clientId } : {},
+			...scopes && scopes.length ? { scopes } : {}
+		};
+	};
+}
+function extractApiKey(headers) {
+	const authz = headers.authorization ?? headers.Authorization;
+	if (typeof authz === "string" && authz.length > 0) {
+		const token = /^Bearer\s+(.+)$/i.exec(authz)?.[1];
+		if (token) return token.trim();
+	}
+	const direct = headers["x-api-key"] ?? headers["X-Api-Key"];
+	if (typeof direct === "string" && direct.length > 0) return direct.trim();
+	return null;
+}
+function resolveOrg(key, setting, field) {
+	if (setting === false) return void 0;
+	const metadata = parseMetadata(key.metadata);
+	if (typeof setting === "function") {
+		const value = setting(metadata, key);
+		return typeof value === "string" && value.length > 0 ? value : void 0;
+	}
+	if (metadata && typeof metadata === "object") {
+		const raw = metadata[field];
+		if (typeof raw === "string" && raw.length > 0) return raw;
+	}
+}
+function resolveScopes(key, scopeKey) {
+	if (scopeKey === false) return void 0;
+	const permissions = parseMetadata(key.permissions);
+	if (permissions && typeof permissions === "object") {
+		const bucket = permissions[scopeKey];
+		if (Array.isArray(bucket) && bucket.every((s) => typeof s === "string")) return bucket;
+	}
+	if (Array.isArray(key.scopes) && key.scopes.every((s) => typeof s === "string")) return key.scopes;
+}
+/**
+* Better Auth stores `metadata` and `permissions` as JSON-stringified
+* columns in SQL kits. Accept both shapes — already-parsed objects pass
+* through, strings round-trip through `JSON.parse`. Failures yield
+* `undefined` rather than throwing because malformed metadata should
+* degrade gracefully (key still authenticates; org scope is absent).
+*/
+function parseMetadata(value) {
+	if (value === null || value === void 0) return void 0;
+	if (typeof value === "string") try {
+		return JSON.parse(value);
+	} catch {
+		return;
+	}
+	return value;
+}
+//#endregion
 //#region src/integrations/mcp/definePrompt.ts
 /**
 * Define a type-safe MCP prompt.
@@ -184,4 +275,4 @@ function definePrompt(name, config) {
 	};
 }
 //#endregion
-export { bridgeToMcp, buildMcpToolsFromBridges, buildRequestContext, createMcpServer, customGuard, defaultCrudDescription, definePrompt, defineTool, denied, fieldRulesToZod, filterResourcesForMcp, getOrgId, getUserId, guard, hasOrg, invokeController, isAuthenticated, isOrg, mcpHandlerAdapter, mcpPlugin, permissionDeniedResult, requireAuth, requireOrg, requireOrgId, requireRole, resolveCrudDescription, resourceToTools, toCallToolError, toCallToolResult, toCallToolSuccess };
+export { bridgeToMcp, buildMcpToolsFromBridges, buildRequestContext, createMcpAuthFromBetterAuthApiKey, createMcpServer, customGuard, defaultCrudDescription, definePrompt, defineTool, denied, fieldRulesToZod, filterResourcesForMcp, getOrgId, getUserId, guard, hasOrg, invokeController, isAuthenticated, isOrg, mcpHandlerAdapter, mcpPlugin, permissionDeniedResult, requireAuth, requireOrg, requireOrgId, requireRole, resolveCrudDescription, resolveToolCollisions, resourceToTools, toCallToolError, toCallToolResult, toCallToolSuccess };

package/dist/integrations/mcp/testing.d.mts

@@ -1,4 +1,4 @@
-import { c as McpAuthResult, l as McpPluginOptions } from "../../types-BsJMEQ4D.mjs";
+import { c as McpAuthResult, l as McpPluginOptions } from "../../types-CoMjNmkF.mjs";
 
 //#region src/integrations/mcp/testing.d.ts
 interface TestMcpClientOptions {

package/dist/integrations/mcp/testing.mjs

@@ -1,4 +1,4 @@
-import { m as createMcpServer, r as resourceToTools, t as filterResourcesForMcp } from "../../mcpPlugin-7vGV51ED.mjs";
+import { m as createMcpServer, r as resourceToTools, t as filterResourcesForMcp } from "../../mcpPlugin-hZE00H74.mjs";
 //#region src/integrations/mcp/testing.ts
 /**
 * @classytic/arc/mcp/testing — MCP Test Utilities

package/dist/integrations/websocket-redis.d.mts

@@ -1,4 +1,4 @@
-import { c as WebSocketAdapter } from "../websocket-BkjeGZRn.mjs";
+import { c as WebSocketAdapter } from "../websocket-BJ0w-3Dt.mjs";
 
 //#region src/integrations/websocket-redis.d.ts
 interface RedisLike {

package/dist/integrations/websocket.d.mts

@@ -1,2 +1,2 @@
-import { a as WebSocketMessage, c as WebSocketAdapter, i as WebSocketClient, n as websocketPlugin, o as WebSocketPluginOptions, r as AuthResult, s as LocalWebSocketAdapter, t as RoomManager } from "../websocket-BkjeGZRn.mjs";
+import { a as WebSocketMessage, c as WebSocketAdapter, i as WebSocketClient, n as websocketPlugin, o as WebSocketPluginOptions, r as AuthResult, s as LocalWebSocketAdapter, t as RoomManager } from "../websocket-BJ0w-3Dt.mjs";
 export { AuthResult, LocalWebSocketAdapter, RoomManager, WebSocketAdapter, WebSocketClient, WebSocketMessage, WebSocketPluginOptions, websocketPlugin };

package/dist/integrations/websocket.mjs

@@ -1,3 +1,4 @@
+import sjson from "secure-json-parse";
 import fp from "fastify-plugin";
 //#region src/integrations/websocket/adapter.ts
 /**
@@ -140,7 +141,7 @@ async function handleConnection(ctx, socket, request) {
 		}
 		let msg;
 		try {
-			msg = JSON.parse(typeof raw === "string" ? raw : raw.toString());
+			msg = sjson.parse(typeof raw === "string" ? raw : raw.toString());
 		} catch {
 			socket.send(JSON.stringify({
 				type: "error",

package/dist/{loadResourcesFromEntry-BLMEI2Xa.mjs → loadResourcesFromEntry-DCjYMgfC.mjs}

@@ -1,4 +1,4 @@
-import { t as ResourceRegistry } from "./ResourceRegistry-f48hFk3m.mjs";
+import { t as ResourceRegistry } from "./ResourceRegistry-CzSzVK1m.mjs";
 import { resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 //#region src/cli/utils/loadResourcesFromEntry.ts