@classytic/arc 2.8.3 → 2.8.5

package/dist/testing/storageContract.mjs

@@ -0,0 +1,216 @@
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+//#region src/testing/storageContract.ts
+/**
+* Storage Contract Suite
+*
+* Any implementation of `@classytic/arc/types/storage`'s `Storage` interface
+* can import this and run it against a live instance to guarantee preset
+* compatibility. Passing this suite is the contract.
+*
+* @example
+* ```typescript
+* import { runStorageContract } from '@classytic/arc/testing/storage';
+* import { s3Storage } from '../src/storage/s3-storage.js';
+*
+* runStorageContract('s3Storage', async () => {
+*   const storage = s3Storage({ bucket: 'test-bucket' });
+*   return { storage, teardown: async () => {} };
+* });
+* ```
+*
+* This module statically imports `vitest`. Only load it from test code — arc's
+* production bundle never references this subpath, so the import tree stays
+* clean under tree-shaking.
+*/
+function makeBytes(size, seed = 0) {
+	const buf = Buffer.allocUnsafe(size);
+	for (let i = 0; i < size; i++) buf[i] = i + seed & 255;
+	return buf;
+}
+async function readAll(result) {
+	if (result.kind === "buffer") return result.buffer;
+	const chunks = [];
+	for await (const chunk of result.stream) chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk);
+	return Buffer.concat(chunks);
+}
+const EMPTY_CTX = { scope: {} };
+function ctxFor(scope) {
+	return { scope };
+}
+/**
+* Register the storage contract suite under the caller's name.
+*
+* Assertions covered:
+*  1. upload() returns a StorageFile with every required field populated
+*  2. read(upload.id) round-trips the exact bytes
+*  3. delete() returns true on first call
+*  4. delete() returns false (or throws) on a missing id
+*  5. exists() (if implemented) agrees with upload/delete state
+*  6. resolveUrl() (if implemented) returns a non-empty URL for an existing id
+*  7. Two isolated scopes don't collide (scope threading)
+*  8. Full lifecycle: upload → read → delete → read rejects
+*  9. Both `kind: "stream"` and `kind: "buffer"` read results deliver correct bytes
+* 10. Ranged reads (if adapter supports them) slice correctly
+*/
+function runStorageContract(name, setup) {
+	describe(`Storage contract — ${name}`, () => {
+		let storage;
+		let teardown;
+		beforeAll(async () => {
+			const result = await setup();
+			storage = result.storage;
+			teardown = result.teardown;
+		});
+		afterAll(async () => {
+			if (teardown) await teardown();
+		});
+		it("upload() returns a populated StorageFile", async () => {
+			const bytes = makeBytes(64);
+			const file = await storage.upload({
+				buffer: bytes,
+				filename: "contract-1.bin",
+				mimeType: "application/octet-stream",
+				size: bytes.length
+			}, EMPTY_CTX);
+			expect(file.id).toBeTruthy();
+			expect(file.url).toBeTruthy();
+			expect(file.pathname).toBeTruthy();
+			expect(file.contentType).toBe("application/octet-stream");
+			expect(file.bytes).toBe(bytes.length);
+			await storage.delete(file.id, EMPTY_CTX);
+		});
+		it("read() round-trips the exact bytes uploaded", async () => {
+			const bytes = makeBytes(1024, 7);
+			const file = await storage.upload({
+				buffer: bytes,
+				filename: "contract-2.bin",
+				mimeType: "application/octet-stream",
+				size: bytes.length
+			}, EMPTY_CTX);
+			const read = await storage.read(file.id, EMPTY_CTX);
+			expect((await readAll(read)).equals(bytes)).toBe(true);
+			expect(read.contentType).toBe("application/octet-stream");
+			await storage.delete(file.id, EMPTY_CTX);
+		});
+		it("delete() returns true the first time, false (or throws) the second time", async () => {
+			const bytes = makeBytes(32);
+			const file = await storage.upload({
+				buffer: bytes,
+				filename: "contract-3.bin",
+				mimeType: "application/octet-stream",
+				size: bytes.length
+			}, EMPTY_CTX);
+			expect(await storage.delete(file.id, EMPTY_CTX)).toBe(true);
+			let second = "threw";
+			try {
+				second = await storage.delete(file.id, EMPTY_CTX);
+			} catch {
+				second = "threw";
+			}
+			expect(second === false || second === "threw").toBe(true);
+		});
+		it("exists() agrees with upload/delete state (if implemented)", async () => {
+			if (!storage.exists) return;
+			const bytes = makeBytes(16);
+			const file = await storage.upload({
+				buffer: bytes,
+				filename: "contract-4.bin",
+				mimeType: "application/octet-stream",
+				size: bytes.length
+			}, EMPTY_CTX);
+			expect(await storage.exists(file.id, EMPTY_CTX)).toBe(true);
+			await storage.delete(file.id, EMPTY_CTX);
+			expect(await storage.exists(file.id, EMPTY_CTX)).toBe(false);
+		});
+		it("resolveUrl() returns a non-empty URL for an existing id (if implemented)", async () => {
+			if (!storage.resolveUrl) return;
+			const bytes = makeBytes(8);
+			const file = await storage.upload({
+				buffer: bytes,
+				filename: "contract-5.bin",
+				mimeType: "application/octet-stream",
+				size: bytes.length
+			}, EMPTY_CTX);
+			const url = await storage.resolveUrl(file.id, EMPTY_CTX);
+			expect(typeof url).toBe("string");
+			expect(url.length).toBeGreaterThan(0);
+			await storage.delete(file.id, EMPTY_CTX);
+		});
+		it("two different scopes get distinct ids (scope threading)", async () => {
+			const bytes = makeBytes(24, 42);
+			const scopeA = ctxFor({ organizationId: "org-a" });
+			const scopeB = ctxFor({ organizationId: "org-b" });
+			const a = await storage.upload({
+				buffer: bytes,
+				filename: "scoped.bin",
+				mimeType: "application/octet-stream",
+				size: bytes.length
+			}, scopeA);
+			const b = await storage.upload({
+				buffer: bytes,
+				filename: "scoped.bin",
+				mimeType: "application/octet-stream",
+				size: bytes.length
+			}, scopeB);
+			expect(a.id).not.toBe(b.id);
+			const readA = await readAll(await storage.read(a.id, scopeA));
+			const readB = await readAll(await storage.read(b.id, scopeB));
+			expect(readA.equals(bytes)).toBe(true);
+			expect(readB.equals(bytes)).toBe(true);
+			await storage.delete(a.id, scopeA);
+			await storage.delete(b.id, scopeB);
+		});
+		it("full lifecycle: upload → read → delete → read rejects", async () => {
+			const bytes = makeBytes(128);
+			const file = await storage.upload({
+				buffer: bytes,
+				filename: "lifecycle.bin",
+				mimeType: "application/octet-stream",
+				size: bytes.length
+			}, EMPTY_CTX);
+			expect((await readAll(await storage.read(file.id, EMPTY_CTX))).equals(bytes)).toBe(true);
+			expect(await storage.delete(file.id, EMPTY_CTX)).toBe(true);
+			let rejected = false;
+			try {
+				if (!(await readAll(await storage.read(file.id, EMPTY_CTX))).equals(bytes)) rejected = true;
+			} catch {
+				rejected = true;
+			}
+			expect(rejected).toBe(true);
+		});
+		it("read() handles both stream and buffer kinds", async () => {
+			const bytes = makeBytes(256, 9);
+			const file = await storage.upload({
+				buffer: bytes,
+				filename: "kind.bin",
+				mimeType: "application/octet-stream",
+				size: bytes.length
+			}, EMPTY_CTX);
+			const result = await storage.read(file.id, EMPTY_CTX);
+			expect(result.kind === "stream" || result.kind === "buffer").toBe(true);
+			expect((await readAll(result)).equals(bytes)).toBe(true);
+			await storage.delete(file.id, EMPTY_CTX);
+		});
+		it("read() with a mid-object range slices correctly (when adapter supports ranges)", async () => {
+			const bytes = makeBytes(1024, 13);
+			const file = await storage.upload({
+				buffer: bytes,
+				filename: "range.bin",
+				mimeType: "application/octet-stream",
+				size: bytes.length
+			}, EMPTY_CTX);
+			const result = await storage.read(file.id, EMPTY_CTX, {
+				start: 100,
+				end: 199
+			});
+			const actual = await readAll(result);
+			if (result.range) {
+				expect(actual.length).toBe(100);
+				expect(actual.equals(bytes.subarray(100, 200))).toBe(true);
+			} else expect(actual.length).toBe(bytes.length);
+			await storage.delete(file.id, EMPTY_CTX);
+		});
+	});
+}
+//#endregion
+export { runStorageContract };

package/dist/types/index.d.mts

@@ -1,5 +1,5 @@
-import { _ as isAuthenticated, c as getOrgRoles, g as hasOrgAccess, n as PUBLIC_SCOPE, p as getTeamId, r as RequestScope, s as getOrgId, t as AUTHENTICATED_SCOPE, v as isElevated, y as isMember } from "../types-C72d3NDn.mjs";
-import { $ as PresetFunction, $t as DeleteOptions, A as EventsDecorator, B as InferResourceDoc, Bt as FastifyHandler, C as ConfigError, Ct as TypedResourceConfig, D as CrudRouterOptions, Dt as ValidationResult, E as CrudRouteKey, Et as ValidateOptions, F as GracefulShutdownOptions, G as LookupOption, H as IntrospectionPluginOptions, Ht as IControllerResponse, I as HealthCheck, J as ObjectId, K as MiddlewareConfig, L as HealthOptions, M as FastifyWithAuth, N as FastifyWithDecorators, O as CrudSchemas, Ot as envelope, P as FieldRule, Q as PopulateOption, Qt as DeleteManyResult, R as InferAdapterDoc, Rt as ControllerHandler, S as AuthenticatorContext, St as TypedRepository, T as CrudController, Tt as UserOrganization, U as JWTPayload, Ut as IRequestContext, V as IntrospectionData, Vt as IController, W as JwtContext, Wt as RouteHandler, X as OwnershipCheck, Xt as BulkWriteResult, Y as OpenApiSchemas, Yt as BulkWriteOperation, Z as ParsedQuery, Zt as CrudRepository, _ as ArcInternalMetadata, _t as RouteMcpConfig, an as PaginationParams, at as RegistryStats, b as AuthPluginOptions, bt as TokenPair, cn as RepositorySession, ct as RequestWithExtras, d as ActionHandlerFn, dt as ResourceHookContext, en as DeleteResult, et as PresetHook, f as ActionsMap, ft as ResourceHooks, g as ArcDecorator, gt as RouteHandlerMethod, h as ApiResponse, ht as RouteDefinition, in as PaginatedResult, it as RegistryEntry, j as FastifyRequestExtras, jt as BaseControllerOptions, k as EventDefinition, kt as getUserId, l as ActionDefinition, ln as UpdateManyResult, lt as ResourceCacheConfig, m as AnyRecord, mt as ResourcePermissions, nn as KeysetPaginatedResult, nt as QueryParserInterface, on as PaginationResult, ot as RequestContext, p as AdditionalRoute, pt as ResourceMetadata, q as MiddlewareHandler, rn as OffsetPaginatedResult, rt as RateLimitConfig, sn as QueryOptions, st as RequestIdOptions, tn as InferDoc, tt as PresetResult, u as ActionEntry, un as WriteOptions, ut as ResourceConfig, v as ArcRequest, vt as RouteSchemaOptions, w as ControllerQueryOptions, wt as UserLike, x as Authenticator, xt as TypedController, y as AuthHelpers, yt as ServiceContext, z as InferDocType, zt as ControllerLike } from "../interface-BVuMfeVv.mjs";
-import { i as UserBase, n as PermissionContext, r as PermissionResult, t as PermissionCheck } from "../types-CVC4HOKi.mjs";
-import { n as ElevationOptions, t as ElevationEvent } from "../elevation-s5ykdNHr.mjs";
+import { _ as isAuthenticated, c as getOrgRoles, g as hasOrgAccess, n as PUBLIC_SCOPE, p as getTeamId, r as RequestScope, s as getOrgId, t as AUTHENTICATED_SCOPE, v as isElevated, y as isMember } from "../types-BD85MlEK.mjs";
+import { $ as PresetFunction, $t as DeleteOptions, A as EventsDecorator, B as InferResourceDoc, Bt as FastifyHandler, C as ConfigError, Ct as TypedResourceConfig, D as CrudRouterOptions, Dt as ValidationResult, E as CrudRouteKey, Et as ValidateOptions, F as GracefulShutdownOptions, G as LookupOption, H as IntrospectionPluginOptions, Ht as IControllerResponse, I as HealthCheck, J as ObjectId, K as MiddlewareConfig, L as HealthOptions, M as FastifyWithAuth, N as FastifyWithDecorators, O as CrudSchemas, Ot as envelope, P as FieldRule, Q as PopulateOption, Qt as DeleteManyResult, R as InferAdapterDoc, Rt as ControllerHandler, S as AuthenticatorContext, St as TypedRepository, T as CrudController, Tt as UserOrganization, U as JWTPayload, Ut as IRequestContext, V as IntrospectionData, Vt as IController, W as JwtContext, Wt as RouteHandler, X as OwnershipCheck, Xt as BulkWriteResult, Y as OpenApiSchemas, Yt as BulkWriteOperation, Z as ParsedQuery, Zt as CrudRepository, _ as ArcInternalMetadata, _t as RouteMcpConfig, an as PaginationParams, at as RegistryStats, b as AuthPluginOptions, bt as TokenPair, cn as RepositorySession, ct as RequestWithExtras, d as ActionHandlerFn, dt as ResourceHookContext, en as DeleteResult, et as PresetHook, f as ActionsMap, ft as ResourceHooks, g as ArcDecorator, gt as RouteHandlerMethod, h as ApiResponse, ht as RouteDefinition, in as PaginatedResult, it as RegistryEntry, j as FastifyRequestExtras, jt as BaseControllerOptions, k as EventDefinition, kt as getUserId, l as ActionDefinition, ln as UpdateManyResult, lt as ResourceCacheConfig, m as AnyRecord, mt as ResourcePermissions, nn as KeysetPaginatedResult, nt as QueryParserInterface, on as PaginationResult, ot as RequestContext, p as AdditionalRoute, pt as ResourceMetadata, q as MiddlewareHandler, rn as OffsetPaginatedResult, rt as RateLimitConfig, sn as QueryOptions, st as RequestIdOptions, tn as InferDoc, tt as PresetResult, u as ActionEntry, un as WriteOptions, ut as ResourceConfig, v as ArcRequest, vt as RouteSchemaOptions, w as ControllerQueryOptions, wt as UserLike, x as Authenticator, xt as TypedController, y as AuthHelpers, yt as ServiceContext, z as InferDocType, zt as ControllerLike } from "../interface-CMRutPfe.mjs";
+import { i as UserBase, n as PermissionContext, r as PermissionResult, t as PermissionCheck } from "../types-DZi1aYhm.mjs";
+import { n as ElevationOptions, t as ElevationEvent } from "../elevation-B6S5csVA.mjs";
 export { AUTHENTICATED_SCOPE, ActionDefinition, ActionEntry, ActionHandlerFn, ActionsMap, AdditionalRoute, AnyRecord, ApiResponse, ArcDecorator, ArcInternalMetadata, ArcRequest, AuthHelpers, AuthPluginOptions, Authenticator, AuthenticatorContext, BaseControllerOptions, BulkWriteOperation, BulkWriteResult, ConfigError, ControllerHandler, ControllerLike, ControllerQueryOptions, CrudController, CrudRepository, CrudRouteKey, CrudRouterOptions, CrudSchemas, DeleteManyResult, DeleteOptions, DeleteResult, ElevationEvent, ElevationOptions, EventDefinition, EventsDecorator, FastifyHandler, FastifyRequestExtras, FastifyWithAuth, FastifyWithDecorators, FieldRule, GracefulShutdownOptions, HealthCheck, HealthOptions, IController, IControllerResponse, IRequestContext, InferAdapterDoc, InferDoc, InferDocType, InferResourceDoc, IntrospectionData, IntrospectionPluginOptions, JWTPayload, JwtContext, KeysetPaginatedResult, LookupOption, MiddlewareConfig, MiddlewareHandler, ObjectId, OffsetPaginatedResult, OpenApiSchemas, OwnershipCheck, PUBLIC_SCOPE, PaginatedResult, PaginationParams, PaginationResult, ParsedQuery, PermissionCheck, PermissionContext, PermissionResult, PopulateOption, PresetFunction, PresetHook, PresetResult, QueryOptions, QueryParserInterface, RateLimitConfig, RegistryEntry, RegistryStats, RepositorySession, RequestContext, RequestIdOptions, RequestScope, RequestWithExtras, ResourceCacheConfig, ResourceConfig, ResourceHookContext, ResourceHooks, ResourceMetadata, ResourcePermissions, RouteDefinition, RouteHandler, RouteHandlerMethod, RouteMcpConfig, RouteSchemaOptions, ServiceContext, TokenPair, TypedController, TypedRepository, TypedResourceConfig, UpdateManyResult, UserBase, UserLike, UserOrganization, ValidateOptions, ValidationResult, WriteOptions, envelope, getOrgId, getOrgRoles, getTeamId, getUserId, hasOrgAccess, isAuthenticated, isElevated, isMember };

package/dist/types/storage.d.mts

@@ -0,0 +1,2 @@
+import { a as StorageReadResult, i as StorageReadRange, n as StorageContext, o as StorageUploadInput, r as StorageFile, t as Storage } from "../storage-Dfzt4VTl.mjs";
+export { Storage, StorageContext, StorageFile, StorageReadRange, StorageReadResult, StorageUploadInput };

package/dist/types/storage.mjs

@@ -0,0 +1 @@
+export {};

package/dist/{types-CcG4avic.d.mts → types-BsbNMEDR.d.mts}

@@ -1,4 +1,4 @@
-import { qt as ResourceDefinition } from "./interface-BVuMfeVv.mjs";
+import { qt as ResourceDefinition } from "./interface-CMRutPfe.mjs";
 import { z } from "zod";
 
 //#region src/integrations/mcp/types.d.ts

package/dist/{types-Bg2X42_m.d.mts → types-Ch9pTQbf.d.mts}

@@ -1,12 +1,12 @@
-import { x as Authenticator } from "./interface-BVuMfeVv.mjs";
-import { n as ElevationOptions } from "./elevation-s5ykdNHr.mjs";
-import { t as ExternalOpenApiPaths } from "./externalPaths-Bapitwvd.mjs";
-import { i as CacheStore } from "./interface-DplgQO2e.mjs";
-import { r as QueryCachePluginOptions } from "./queryCachePlugin-CnTZZTC5.mjs";
-import { i as EventTransport } from "./EventTransport-CinyO7zQ.mjs";
-import { t as EventPluginOptions } from "./eventPlugin-CVxlE6De.mjs";
-import { f as SSEOptions, h as CachingOptions, i as VersioningOptions, l as MetricsOptions, t as ErrorHandlerOptions } from "./errorHandler-CdZDavNH.mjs";
-import { r as IdempotencyStore } from "./interface-B-pe8fhj.mjs";
+import { x as Authenticator } from "./interface-CMRutPfe.mjs";
+import { n as ElevationOptions } from "./elevation-B6S5csVA.mjs";
+import { t as ExternalOpenApiPaths } from "./externalPaths-BnkYrNzp.mjs";
+import { i as CacheStore } from "./interface-4y979v99.mjs";
+import { r as QueryCachePluginOptions } from "./queryCachePlugin-BJJGBTlu.mjs";
+import { i as EventTransport } from "./EventTransport-BXja8NOc.mjs";
+import { t as EventPluginOptions } from "./eventPlugin-D9DKB2zM.mjs";
+import { f as SSEOptions, h as CachingOptions, i as VersioningOptions, l as MetricsOptions, t as ErrorHandlerOptions } from "./errorHandler-Bah5JhBd.mjs";
+import { r as IdempotencyStore } from "./interface-DfLGcus7.mjs";
 import { FastifyInstance, FastifyPluginAsync, FastifyReply, FastifyRequest, FastifyServerOptions } from "fastify";
 
 //#region src/factory/loadResources.d.ts

package/dist/{types-CVC4HOKi.d.mts → types-DZi1aYhm.d.mts}

@@ -1,4 +1,4 @@
-import { r as RequestScope } from "./types-C72d3NDn.mjs";
+import { r as RequestScope } from "./types-BD85MlEK.mjs";
 import { FastifyRequest } from "fastify";
 
 //#region src/permissions/types.d.ts

package/dist/utils/index.d.mts

@@ -1,6 +1,6 @@
-import { Y as OpenApiSchemas, Z as ParsedQuery, m as AnyRecord, nt as QueryParserInterface } from "../interface-BVuMfeVv.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 ErrorDetails, s as OrgRequiredError, t as ArcError, u as UnauthorizedError } from "../errors-Bmn3eZT6.mjs";
-import { a as CircuitBreakerStats, c as createCircuitBreakerRegistry, i as CircuitBreakerRegistry, n as CircuitBreakerError, o as CircuitState, r as CircuitBreakerOptions, s as createCircuitBreaker, t as CircuitBreaker } from "../circuitBreaker-CvXkjfrW.mjs";
+import { Y as OpenApiSchemas, Z as ParsedQuery, m as AnyRecord, nt as QueryParserInterface } from "../interface-CMRutPfe.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 ErrorDetails, s as OrgRequiredError, t as ArcError, u as UnauthorizedError } from "../errors-Ck2h67pm.mjs";
+import { a as CircuitBreakerStats, c as createCircuitBreakerRegistry, i as CircuitBreakerRegistry, n as CircuitBreakerError, o as CircuitState, r as CircuitBreakerOptions, s as createCircuitBreaker, t as CircuitBreaker } from "../circuitBreaker-dTtG-UyS.mjs";
 import { FastifyInstance, FastifyReply, FastifyRequest, RouteHandlerMethod } from "fastify";
 
 //#region src/utils/compensation.d.ts
@@ -506,6 +506,14 @@ declare function getListQueryParams(): AnyRecord;
 declare function getDefaultCrudSchemas(): Record<string, Record<string, unknown>>;
 //#endregion
 //#region src/utils/schemaConverter.d.ts
+/**
+ * Supported JSON Schema output targets for Zod v4's `toJSONSchema()`.
+ * - `draft-7`: Fastify/AJV validation (default)
+ * - `draft-2020-12`: AJV 2020 (opt-in, requires ajv/dist/2020)
+ * - `openapi-3.0`: OpenAPI 3.0 document generation
+ * - `openapi-3.1`: OpenAPI 3.1 document generation
+ */
+type JsonSchemaTarget = "draft-7" | "draft-2020-12" | "openapi-3.0" | "openapi-3.1";
 /**
  * Check if an object is already a plain JSON Schema.
  * Returns true if it has JSON Schema markers (`type`, `properties`, `$ref`,
@@ -522,15 +530,22 @@ declare function isZodSchema(input: unknown): boolean;
  * Detection order:
  * 1. `null`/`undefined` → `undefined`
  * 2. Already JSON Schema → pass through as-is (zero overhead)
- * 3. Zod v4 schema → `z.toJSONSchema(schema, { target: 'openapi-3.0' })`
+ * 3. Zod v4 schema → `z.toJSONSchema(schema, { target })`
  * 4. Unrecognized object → return as-is (treat as opaque schema)
+ *
+ * @param input Schema (Zod, plain JSON Schema, or opaque object)
+ * @param target Output target — defaults to `draft-7` for Fastify compatibility.
+ *               Pass `openapi-3.0`/`openapi-3.1` for OpenAPI document generation.
  */
-declare function toJsonSchema(input: unknown): Record<string, unknown> | undefined;
+declare function toJsonSchema(input: unknown, target?: JsonSchemaTarget): Record<string, unknown> | undefined;
 /**
  * Convert all schema fields in an OpenApiSchemas object.
  * JSON Schema values pass through unchanged. Only Zod schemas are converted.
+ *
+ * Defaults to the `openapi-3.0` target since this function feeds OpenAPI doc
+ * generation, not Fastify route validation.
  */
-declare function convertOpenApiSchemas(schemas: OpenApiSchemas): OpenApiSchemas;
+declare function convertOpenApiSchemas(schemas: OpenApiSchemas, target?: JsonSchemaTarget): OpenApiSchemas;
 /**
  * Convert schema values in a Fastify route schema record.
  *
@@ -540,8 +555,11 @@ declare function convertOpenApiSchemas(schemas: OpenApiSchemas): OpenApiSchemas;
  * JSON Schema values pass through unchanged. Only Zod schemas are converted.
  *
  * Used for both additionalRoutes and customSchemas (CRUD overrides).
+ *
+ * Defaults to `draft-7` so Fastify v5's bundled AJV 8 accepts the output.
+ * Pass `openapi-3.0` (or `openapi-3.1`) when generating OpenAPI documents.
  */
-declare function convertRouteSchema(schema: Record<string, unknown>): Record<string, unknown>;
+declare function convertRouteSchema(schema: Record<string, unknown>, target?: JsonSchemaTarget): Record<string, unknown>;
 //#endregion
 //#region src/utils/stateMachine.d.ts
 /**
@@ -673,4 +691,4 @@ declare function hasEvents(instance: FastifyInstance): instance is FastifyInstan
   events: EventsDecorator;
 };
 //#endregion
-export { ArcError, ArcQueryParser, type ArcQueryParserOptions, CircuitBreaker, CircuitBreakerError, type CircuitBreakerOptions, CircuitBreakerRegistry, type CircuitBreakerStats, CircuitState, type CompensationDefinition, type CompensationError, type CompensationHooks, type CompensationResult, type CompensationStep, ConflictError, type ErrorDetails, type EventsDecorator, ForbiddenError, type Guard, type GuardConfig, type JsonSchema, NotFoundError, OrgAccessDeniedError, OrgRequiredError, RateLimitError, ServiceUnavailableError, type StateMachine, type TransitionConfig, UnauthorizedError, ValidationError, convertOpenApiSchemas, convertRouteSchema, createCircuitBreaker, createCircuitBreakerRegistry, createDomainError, createError, createQueryParser, createStateMachine, defineCompensation, defineGuard, deleteResponse, errorResponseSchema, getDefaultCrudSchemas, getListQueryParams, handleRaw, hasEvents, isArcError, isJsonSchema, isZodSchema, itemResponse, listResponse, mutationResponse, paginationSchema, queryParams, responses, successResponseSchema, toJsonSchema, withCompensation, wrapResponse };
+export { ArcError, ArcQueryParser, type ArcQueryParserOptions, CircuitBreaker, CircuitBreakerError, type CircuitBreakerOptions, CircuitBreakerRegistry, type CircuitBreakerStats, CircuitState, type CompensationDefinition, type CompensationError, type CompensationHooks, type CompensationResult, type CompensationStep, ConflictError, type ErrorDetails, type EventsDecorator, ForbiddenError, type Guard, type GuardConfig, type JsonSchema, type JsonSchemaTarget, NotFoundError, OrgAccessDeniedError, OrgRequiredError, RateLimitError, ServiceUnavailableError, type StateMachine, type TransitionConfig, UnauthorizedError, ValidationError, convertOpenApiSchemas, convertRouteSchema, createCircuitBreaker, createCircuitBreakerRegistry, createDomainError, createError, createQueryParser, createStateMachine, defineCompensation, defineGuard, deleteResponse, errorResponseSchema, getDefaultCrudSchemas, getListQueryParams, handleRaw, hasEvents, isArcError, isJsonSchema, isZodSchema, itemResponse, listResponse, mutationResponse, paginationSchema, queryParams, responses, successResponseSchema, toJsonSchema, withCompensation, wrapResponse };

package/dist/utils/index.mjs

@@ -1,5 +1,5 @@
 import { n as createQueryParser, t as ArcQueryParser } from "../queryParser-CgCtsjti.mjs";
-import { a as toJsonSchema, i as isZodSchema, n as convertRouteSchema, r as isJsonSchema, t as convertOpenApiSchemas } from "../schemaConverter-OxfCshus.mjs";
+import { a as toJsonSchema, i as isZodSchema, n as convertRouteSchema, r as isJsonSchema, t as convertOpenApiSchemas } from "../schemaConverter-Y7nCYaLJ.mjs";
 import { a as createCircuitBreaker, i as CircuitState, n as CircuitBreakerError, o as createCircuitBreakerRegistry, r as CircuitBreakerRegistry, t as CircuitBreaker } from "../circuitBreaker-cmi5XDv5.mjs";
 import { _ as withCompensation, a as getListQueryParams, c as mutationResponse, d as responses, f as successResponseSchema, g as defineCompensation, h as defineGuard, i as getDefaultCrudSchemas, l as paginationSchema, m as handleRaw, n as deleteResponse, o as itemResponse, p as wrapResponse, r as errorResponseSchema, s as listResponse, t as createStateMachine, u as queryParams } from "../utils-yYT3HDXt.mjs";
 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-BF2bIOIS.mjs";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/arc",
-  "version": "2.8.3",
+  "version": "2.8.5",
   "description": "Resource-oriented backend framework for Fastify — clean, minimal, powerful, tree-shakable",
   "type": "module",
   "exports": {
@@ -20,6 +20,10 @@
       "types": "./dist/types/index.d.mts",
       "default": "./dist/types/index.mjs"
     },
+    "./types/storage": {
+      "types": "./dist/types/storage.d.mts",
+      "default": "./dist/types/storage.mjs"
+    },
     "./adapters": {
       "types": "./dist/adapters/index.d.mts",
       "default": "./dist/adapters/index.mjs"
@@ -36,6 +40,10 @@
       "types": "./dist/presets/multiTenant.d.mts",
       "default": "./dist/presets/multiTenant.mjs"
     },
+    "./presets/files-upload": {
+      "types": "./dist/presets/filesUpload.d.mts",
+      "default": "./dist/presets/filesUpload.mjs"
+    },
     "./auth": {
       "types": "./dist/auth/index.d.mts",
       "default": "./dist/auth/index.mjs"
@@ -116,6 +124,10 @@
       "types": "./dist/testing/index.d.mts",
       "default": "./dist/testing/index.mjs"
     },
+    "./testing/storage": {
+      "types": "./dist/testing/storageContract.d.mts",
+      "default": "./dist/testing/storageContract.mjs"
+    },
     "./policies": {
       "types": "./dist/policies/index.d.mts",
       "default": "./dist/policies/index.mjs"
@@ -364,7 +376,10 @@
     "@vitest/coverage-v8": "^3.2.4",
     "ajv": "^8.18.0",
     "better-auth": "^1.6.2",
+    "bullmq": "^5.73.5",
+    "dotenv": "^17.4.2",
     "fastify-raw-body": "^5.0.0",
+    "ioredis": "^5.10.1",
     "jsonwebtoken": "^9.0.0",
     "knip": "^6.4.1",
     "mongodb": "^7.1.0",

package/skills/arc/SKILL.md

@@ -856,6 +856,28 @@ auth: async (headers) => ({
 
 **Guards** for custom tools: `guard(requireAuth, requireOrg, requireRole('admin'), handler)`
 
+**AI SDK bridge** (v2.8.4+) — expose AI SDK `tool()` definitions over MCP without duplicating glue. Handles auth, guards, `{ error } → isError` translation, and thrown-error mapping:
+
+```typescript
+import { bridgeToMcp, buildMcpToolsFromBridges, getUserId, hasOrg, type McpBridge } from '@classytic/arc/mcp';
+
+export const triggerJobBridge: McpBridge = {
+  name: 'trigger_job',
+  description: 'Start a job.',
+  inputSchema: { phase: z.enum(['investigate', 'fix']) },
+  annotations: { destructiveHint: true },
+  buildTool: (ctx) => buildTriggerJobTool(getUserId(ctx) ?? ''),
+  guard: (ctx) => (hasOrg(ctx) ? null : 'Organization scope required'),
+};
+
+await app.register(mcpPlugin, {
+  resources,
+  extraTools: buildMcpToolsFromBridges([triggerJobBridge], {
+    exclude: process.env.DEPLOYMENT === 'readonly' ? ['trigger_job'] : [],
+  }),
+});
+```
+
 **Service scope**: When `clientId` is set in auth result, MCP produces `kind: "service"` RequestScope — works with `requireServiceScope()`, `getClientId()`, `getServiceScopes()`. No synthetic userId needed for machine principals.
 
 **Multi-tenancy**: `organizationId` from auth flows into BaseController org-scoping automatically.

package/skills/arc/references/events.md

@@ -168,6 +168,35 @@ class KafkaTransport implements EventTransport {
 | Redis Pub/Sub | `@classytic/arc/events/redis` | Multi-instance, real-time |
 | Redis Streams | `@classytic/arc/events/redis-stream` | Ordered, persistent, consumer groups |
 
+### Streams vs Pub/Sub — pick the right one
+
+Choosing wrong loses messages silently. Default to **Streams** for anything business-critical.
+
+| Requirement | Use |
+|---|---|
+| Message MUST NOT be lost (billing, payments, audit) | **Streams** |
+| Real-time notifications, OK to miss when no subscriber is up | Pub/Sub |
+| Need to replay/reprocess past events | **Streams** |
+| Multiple workers processing the same queue | **Streams** (consumer groups) |
+| Simple broadcast to live WebSocket clients | Pub/Sub |
+| Event sourcing or audit trail | **Streams** |
+| Single-instance dev | Memory |
+| At-least-once delivery with durable WAL | **Streams** + outbox pattern |
+
+**Why it matters:** Pub/Sub is fire-and-forget. If no subscriber is connected when you publish, the message is gone. Streams persist until every consumer group acknowledges them — crashes, restarts, and network blips are survivable.
+
+**Defense-in-depth:** pair `eventPlugin` with the transactional outbox (`EventOutbox` + `MemoryOutboxStore` or your own persistent store) for guaranteed delivery even if Redis is unreachable at publish time.
+
+### Redis eviction policy — required for queues and idempotency
+
+When you back events (Streams), jobs (BullMQ), idempotency, or cache with Redis, your Redis instance **must** be configured with `maxmemory-policy: noeviction`. Any other policy can silently evict in-flight stream entries or pending jobs.
+
+- **Self-hosted Redis:** `redis-cli CONFIG SET maxmemory-policy noeviction` (or set in `redis.conf`).
+- **Upstash:** free/paid DBs default to `optimistic-volatile`. You'll see `IMPORTANT! Eviction policy is optimistic-volatile. It should be "noeviction"` in BullMQ logs. **Do one of:** open a support ticket to request `noeviction`, use a dedicated DB for queues, or accept that long-idle jobs may be evicted.
+- **ElastiCache / Redis Cloud:** set the parameter group's `maxmemory-policy` to `noeviction` before pointing arc at it.
+
+For a pure cache DB (no queues, no idempotency), `allkeys-lru` is correct and what you want.
+
 ## Injectable Logger
 
 All transports and retry accept a `logger` option — defaults to `console`, compatible with pino/fastify.log:

package/skills/arc/references/mcp.md

@@ -430,6 +430,43 @@ const createShape = fieldRulesToZod(resource.schemaOptions.fieldRules, {
 // → { name: z.string(), price: z.number(), category: z.enum([...]) }
 ```
 
+## AI SDK Bridge (v2.8.4+)
+
+Expose AI SDK `tool()` definitions over MCP without duplicating glue. The bridge handles `isAuthenticated` rejection, optional custom guards, `{ error }` → `isError: true` envelope translation, and thrown-error mapping.
+
+```typescript
+import { bridgeToMcp, buildMcpToolsFromBridges, getUserId, hasOrg, type McpBridge } from '@classytic/arc/mcp';
+import { tool } from 'ai';
+import { z } from 'zod';
+
+function buildTriggerJobTool(companyId: string) {
+  return tool({
+    description: 'Start a job.',
+    inputSchema: z.object({ phase: z.enum(['investigate', 'fix']) }),
+    execute: async ({ phase }) => ({ jobId: `${companyId}-${phase}-${Date.now()}` }),
+  });
+}
+
+export const triggerJobBridge: McpBridge = {
+  name: 'trigger_job',
+  description: 'Start a job.',
+  inputSchema: { phase: z.enum(['investigate', 'fix']) },
+  annotations: { destructiveHint: true },
+  buildTool: (ctx) => buildTriggerJobTool(getUserId(ctx) ?? ''),
+  guard: (ctx) => (hasOrg(ctx) ? null : 'Organization scope required'),
+};
+
+await app.register(mcpPlugin, {
+  resources,
+  extraTools: buildMcpToolsFromBridges([triggerJobBridge], {
+    // Per-environment filtering — read-only deployments hide destructive tools
+    exclude: process.env.DEPLOYMENT === 'readonly' ? ['trigger_job'] : [],
+  }),
+});
+```
+
+`buildMcpToolsFromBridges` also accepts `{ include: [...] }` for strict allowlists. `buildTool` is called fresh per request — safe for per-tenant dep resolution. `McpBridge.annotations` is the same `ToolAnnotations` shape as `defineTool`.
+
 ## Schema Discovery — MCP Resources
 
 Auto-registered for agent discovery:

package/dist/redis-z3sFr1UP.d.mts

@@ -1,49 +0,0 @@
-import { n as IdempotencyResult, r as IdempotencyStore } from "./interface-B-pe8fhj.mjs";
-
-//#region src/idempotency/stores/redis.d.ts
-interface RedisClient {
-  get(key: string): Promise<string | null>;
-  set(key: string, value: string, options?: {
-    EX?: number;
-    NX?: boolean;
-  }): Promise<string | null>;
-  del(key: string | string[]): Promise<number>;
-  exists(key: string | string[]): Promise<number>;
-  /** SCAN command — compatible with node-redis and ioredis varargs signatures. */
-  scan?(cursor: string | number, ...args: (string | number)[]): Promise<[string | number, string[]]>;
-  quit?(): Promise<string>;
-  disconnect?(): Promise<void>;
-}
-interface RedisIdempotencyStoreOptions {
-  /** Redis client instance */
-  client: RedisClient;
-  /** Key prefix (default: 'idem:') */
-  prefix?: string;
-  /** Lock key prefix (default: 'idem:lock:') */
-  lockPrefix?: string;
-  /** Default TTL in ms (default: 86400000 = 24 hours) */
-  ttlMs?: number;
-}
-declare class RedisIdempotencyStore implements IdempotencyStore {
-  readonly name = "redis";
-  private client;
-  private prefix;
-  private lockPrefix;
-  private ttlMs;
-  constructor(options: RedisIdempotencyStoreOptions);
-  private resultKey;
-  private lockKey;
-  get(key: string): Promise<IdempotencyResult | undefined>;
-  set(key: string, result: Omit<IdempotencyResult, "key">): Promise<void>;
-  tryLock(key: string, requestId: string, ttlMs: number): Promise<boolean>;
-  unlock(key: string, requestId: string): Promise<void>;
-  isLocked(key: string): Promise<boolean>;
-  delete(key: string): Promise<void>;
-  deleteByPrefix(prefix: string): Promise<number>;
-  findByPrefix(prefix: string): Promise<IdempotencyResult | undefined>;
-  /** Scan Redis keys matching a prefix pattern. Falls back to empty if SCAN unavailable. */
-  private scanByPrefix;
-  close(): Promise<void>;
-}
-//#endregion
-export { RedisIdempotencyStore as n, RedisIdempotencyStoreOptions as r, RedisClient as t };