@classytic/arc 2.8.4 → 2.9.1

package/dist/redis-MXLp1oOf.d.mts

@@ -0,0 +1,115 @@
+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>;
+}
+/** Minimal ioredis shape we depend on — keeps this file peer-dep-free. */
+interface IoredisLike {
+  get(key: string): Promise<string | null>;
+  set(...args: unknown[]): Promise<string | null>;
+  del(...keys: string[]): Promise<number>;
+  exists(...keys: string[]): Promise<number>;
+  scan(cursor: string | number, ...args: (string | number)[]): Promise<[string, string[]]>;
+  eval?(script: string, numKeys: number, ...args: (string | number)[]): Promise<unknown>;
+  quit?(): Promise<string>;
+  disconnect?(): void;
+}
+/**
+ * Wrap an ioredis instance as the arc idempotency `RedisClient`.
+ *
+ * Arc's idempotency store expects node-redis-v4 style option objects
+ * (`{ EX, NX }`). ioredis uses positional flags. This adapter lets users
+ * plug an ioredis instance in without writing the bridge themselves.
+ *
+ * @example
+ * ```typescript
+ * import Redis from 'ioredis';
+ * import { RedisIdempotencyStore, ioredisAsIdempotencyClient }
+ *   from '@classytic/arc/idempotency/redis';
+ *
+ * const redis = new Redis(process.env.REDIS_URL);
+ * const store = new RedisIdempotencyStore({
+ *   client: ioredisAsIdempotencyClient(redis),
+ * });
+ * ```
+ */
+declare function ioredisAsIdempotencyClient(client: IoredisLike): RedisClient & {
+  eval?: (script: string, numkeys: number, ...args: (string | number)[]) => Promise<unknown>;
+};
+/** Minimal `@upstash/redis` shape we depend on (REST client, edge-safe). */
+interface UpstashRedisLike {
+  get(key: string): Promise<string | null | unknown>;
+  set(key: string, value: unknown, opts?: Record<string, unknown>): Promise<unknown>;
+  del(...keys: string[]): Promise<number>;
+  exists(...keys: string[]): Promise<number>;
+  scan(cursor: number | string, opts?: {
+    match?: string;
+    count?: number;
+  }): Promise<[number, string[]] | [string, string[]]>;
+  eval?(script: string, keys: string[], args: (string | number)[]): Promise<unknown>;
+}
+/**
+ * Wrap an `@upstash/redis` REST client as an idempotency `RedisClient`.
+ *
+ * Enables running arc's idempotency store on Cloudflare Workers, Vercel Edge
+ * and Deno Deploy — runtimes that don't support raw TCP (ioredis).
+ *
+ * @example
+ * ```typescript
+ * import { Redis } from '@upstash/redis';
+ * import { RedisIdempotencyStore, upstashAsIdempotencyClient }
+ *   from '@classytic/arc/idempotency/redis';
+ *
+ * const redis = Redis.fromEnv();
+ * const store = new RedisIdempotencyStore({
+ *   client: upstashAsIdempotencyClient(redis),
+ * });
+ * ```
+ */
+declare function upstashAsIdempotencyClient(client: UpstashRedisLike): RedisClient & {
+  eval?: (script: string, numkeys: number, ...args: (string | number)[]) => Promise<unknown>;
+};
+//#endregion
+export { UpstashRedisLike as a, RedisIdempotencyStoreOptions as i, RedisClient as n, ioredisAsIdempotencyClient as o, RedisIdempotencyStore as r, upstashAsIdempotencyClient as s, IoredisLike as t };

package/dist/{redis-stream-D54N5oXs.d.mts → redis-stream-Bz-4q96t.d.mts}

@@ -1,4 +1,4 @@
-import { i as EventTransport, n as EventHandler, r as EventLogger, t as DomainEvent } from "./EventTransport-CinyO7zQ.mjs";
+import { i as EventLogger, n as DomainEvent, o as EventTransport, r as EventHandler } from "./EventTransport-CqZ8FyM_.mjs";
 
 //#region src/events/transports/redis-stream.d.ts
 interface RedisStreamLike {

package/dist/registry/index.d.mts

@@ -1,4 +1,4 @@
-import { Gt as RegisterOptions, H as IntrospectionPluginOptions, Kt as ResourceRegistry } from "../interface-BVuMfeVv.mjs";
+import { Gt as ResourceRegistry, V as IntrospectionPluginOptions, Wt as RegisterOptions } from "../interface-YrWsmKqE.mjs";
 import { FastifyPluginAsync } from "fastify";
 
 //#region src/registry/introspectionPlugin.d.ts

package/dist/{resourceToTools-O_HwWXFa.mjs → resourceToTools-C3cWymnW.mjs}

@@ -1,6 +1,6 @@
-import { t as BaseController } from "./BaseController-DAGGc5Xn.mjs";
-import { n as normalizePermissionResult } from "./applyPermissionResult-D6GPMsvh.mjs";
-import { t as pluralize } from "./pluralize-A0tWEl1K.mjs";
+import { t as BaseController } from "./BaseController-Vu2yc56T.mjs";
+import { n as normalizePermissionResult } from "./applyPermissionResult-bqGpo9ML.mjs";
+import { t as pluralize } from "./pluralize-CWP6MB39.mjs";
 import { z } from "zod";
 //#region src/integrations/mcp/createMcpServer.ts
 /**
@@ -568,7 +568,7 @@ function resourceToTools(resource, config = {}) {
 	const hasSoftDelete = resource._appliedPresets?.includes("softDelete") ?? false;
 	const tools = [];
 	const prefix = config.toolNamePrefix;
-	if (!controller) {} else {
+	if (controller) {
 		let ops = ALL_CRUD_OPS.filter((op) => {
 			if (resource.disabledRoutes?.includes(op)) return false;
 			return true;
@@ -595,50 +595,51 @@ function resourceToTools(resource, config = {}) {
 				handler: createHandler(op, controller, resource.name, resource.permissions)
 			});
 		}
-		for (const route of resource.additionalRoutes ?? []) {
-			if (route.mcp === false) continue;
-			const mcpHandler = route.mcpHandler;
-			if (!route.wrapHandler && !mcpHandler) continue;
-			if (!mcpHandler && ![
-				"POST",
-				"PUT",
-				"PATCH",
-				"DELETE"
-			].includes(route.method)) continue;
-			const opName = route.operation ?? slugifyRoute(route.method, route.path);
-			const hasId = route.path.includes(":id");
-			const mcpConfig = typeof route.mcp === "object" && route.mcp !== null ? route.mcp : void 0;
-			const toolDescription = mcpConfig?.description ?? route.summary ?? route.description ?? `${opName} on ${resource.displayName}`;
-			const toolAnnotations = mcpConfig?.annotations ? { ...mcpConfig.annotations } : { openWorldHint: true };
-			const inputShape = {};
-			if (hasId) inputShape.id = z.string().describe("Resource ID");
-			if (mcpHandler) tools.push({
-				name: prefix ? `${prefix}_${opName}_${resource.name}` : `${opName}_${resource.name}`,
-				description: toolDescription,
-				annotations: toolAnnotations,
-				inputSchema: inputShape,
-				handler: async (input, _ctx) => {
-					try {
-						return await mcpHandler(input);
-					} catch (err) {
-						return {
-							content: [{
-								type: "text",
-								text: `Error: ${err instanceof Error ? err.message : String(err)}`
-							}],
-							isError: true
-						};
-					}
+	}
+	for (const route of resource.routes ?? []) {
+		if (route.mcp === false) continue;
+		const mcpHandler = route.mcpHandler;
+		if (!!route.raw && !mcpHandler) continue;
+		if (!mcpHandler && ![
+			"POST",
+			"PUT",
+			"PATCH",
+			"DELETE"
+		].includes(route.method)) continue;
+		if (!mcpHandler && typeof route.handler === "string" && !controller) continue;
+		const opName = route.operation ?? slugifyRoute(route.method, route.path);
+		const hasId = route.path.includes(":id");
+		const mcpConfig = typeof route.mcp === "object" && route.mcp !== null ? route.mcp : void 0;
+		const toolDescription = mcpConfig?.description ?? route.summary ?? route.description ?? `${opName} on ${resource.displayName}`;
+		const toolAnnotations = mcpConfig?.annotations ? { ...mcpConfig.annotations } : { openWorldHint: true };
+		const inputShape = {};
+		if (hasId) inputShape.id = z.string().describe("Resource ID");
+		if (mcpHandler) tools.push({
+			name: prefix ? `${prefix}_${opName}_${resource.name}` : `${opName}_${resource.name}`,
+			description: toolDescription,
+			annotations: toolAnnotations,
+			inputSchema: inputShape,
+			handler: async (input, _ctx) => {
+				try {
+					return await mcpHandler(input);
+				} catch (err) {
+					return {
+						content: [{
+							type: "text",
+							text: `Error: ${err instanceof Error ? err.message : String(err)}`
+						}],
+						isError: true
+					};
 				}
-			});
-			else tools.push({
-				name: prefix ? `${prefix}_${opName}_${resource.name}` : `${opName}_${resource.name}`,
-				description: toolDescription,
-				annotations: toolAnnotations,
-				inputSchema: inputShape,
-				handler: createAdditionalRouteHandler(route, controller, hasId)
-			});
-		}
+			}
+		});
+		else tools.push({
+			name: prefix ? `${prefix}_${opName}_${resource.name}` : `${opName}_${resource.name}`,
+			description: toolDescription,
+			annotations: toolAnnotations,
+			inputSchema: inputShape,
+			handler: createCustomRouteHandler(route, controller, hasId)
+		});
 	}
 	if (resource.actions) for (const [actionName, entry] of Object.entries(resource.actions)) {
 		const def = typeof entry === "function" ? { handler: entry } : entry;
@@ -757,11 +758,27 @@ function createHandler(op, controller, resourceName, permissions) {
 		}
 	};
 }
-function createAdditionalRouteHandler(route, controller, hasId) {
+function createCustomRouteHandler(route, controller, hasId) {
 	const ctrl = controller;
 	const handlerName = typeof route.handler === "string" ? route.handler : route.operation ?? slugifyRoute(route.method, route.path);
 	return async (input, ctx) => {
 		try {
+			if (typeof route.handler === "function") {
+				const reqCtx = buildRequestContext(input, ctx.session, hasId ? "update" : "create");
+				const fn = route.handler;
+				const out = await fn(reqCtx);
+				return toCallToolResult(out !== null && typeof out === "object" && "success" in out ? out : {
+					success: true,
+					data: out
+				});
+			}
+			if (!ctrl) return {
+				content: [{
+					type: "text",
+					text: `Handler "${handlerName}" has no controller available`
+				}],
+				isError: true
+			};
 			const method = ctrl[handlerName];
 			if (typeof method !== "function") return {
 				content: [{

package/dist/rpc/index.mjs

@@ -1,4 +1,4 @@
-import { t as CircuitBreaker } from "../circuitBreaker-cmi5XDv5.mjs";
+import { t as CircuitBreaker } from "../circuitBreaker-l18oRgL5.mjs";
 //#region src/rpc/serviceClient.ts
 /**
 * Service Client — Resource-Oriented RPC

package/dist/{schemaConverter-OxfCshus.mjs → schemaConverter-BxFDdtXu.mjs}

@@ -1,4 +1,8 @@
 //#region src/utils/schemaConverter.ts
+/** Default target for Fastify-consumed schemas (matches Fastify v5's default AJV draft). */
+const DEFAULT_FASTIFY_TARGET = "draft-7";
+/** Default target for OpenAPI document generation (matches arc's emitted OpenAPI version). */
+const DEFAULT_OPENAPI_TARGET = "openapi-3.0";
 let _toJSONSchema = null;
 import("zod").then(({ z }) => {
 	if (typeof z?.toJSONSchema === "function") _toJSONSchema = (schema, opts) => z.toJSONSchema(schema, opts);
@@ -26,17 +30,23 @@ function isZodSchema(input) {
 * 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.
 */
-function toJsonSchema(input) {
+function toJsonSchema(input, target = DEFAULT_FASTIFY_TARGET) {
 	if (input == null) return void 0;
 	if (typeof input !== "object") return void 0;
 	if (isJsonSchema(input)) return input;
 	if (isZodSchema(input)) {
 		if (!_toJSONSchema) return input;
 		try {
-			return _toJSONSchema(input, { target: "openapi-3.0" });
+			const converted = _toJSONSchema(input, { target });
+			if ("$schema" in converted) delete converted.$schema;
+			return converted;
 		} catch {
 			return { type: "object" };
 		}
@@ -46,8 +56,11 @@ function toJsonSchema(input) {
 /**
 * 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.
 */
-function convertOpenApiSchemas(schemas) {
+function convertOpenApiSchemas(schemas, target = DEFAULT_OPENAPI_TARGET) {
 	const result = {};
 	const schemaFields = [
 		"entity",
@@ -59,7 +72,7 @@ function convertOpenApiSchemas(schemas) {
 	];
 	for (const field of schemaFields) {
 		const value = schemas[field];
-		if (value !== void 0) result[field] = toJsonSchema(value) ?? value;
+		if (value !== void 0) result[field] = toJsonSchema(value, target) ?? value;
 	}
 	for (const [key, value] of Object.entries(schemas)) if (!schemaFields.includes(key)) result[key] = value;
 	return result;
@@ -72,20 +85,23 @@ function convertOpenApiSchemas(schemas) {
 *
 * JSON Schema values pass through unchanged. Only Zod schemas are converted.
 *
-* Used for both additionalRoutes and customSchemas (CRUD overrides).
+* Used for both custom routes 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.
 */
-function convertRouteSchema(schema) {
+function convertRouteSchema(schema, target = DEFAULT_FASTIFY_TARGET) {
 	const result = { ...schema };
 	for (const field of [
 		"body",
 		"querystring",
 		"params",
 		"headers"
-	]) if (result[field] !== void 0) result[field] = toJsonSchema(result[field]) ?? result[field];
+	]) if (result[field] !== void 0) result[field] = toJsonSchema(result[field], target) ?? result[field];
 	if (result.response !== void 0 && typeof result.response === "object" && result.response !== null) {
 		const responseObj = result.response;
 		const convertedResponse = {};
-		for (const [statusCode, responseSchema] of Object.entries(responseObj)) convertedResponse[statusCode] = toJsonSchema(responseSchema) ?? responseSchema;
+		for (const [statusCode, responseSchema] of Object.entries(responseObj)) convertedResponse[statusCode] = toJsonSchema(responseSchema, target) ?? responseSchema;
 		result.response = convertedResponse;
 	}
 	return result;

package/dist/scope/index.d.mts

@@ -1,5 +1,5 @@
-import { _ as isAuthenticated, a as getClientId, b as isOrgInScope, c as getOrgRoles, d as getScopeContextMap, f as getServiceScopes, g as hasOrgAccess, h as getUserRoles, i as getAncestorOrgIds, l as getRequestScope, m as getUserId, n as PUBLIC_SCOPE, o as getOrgContext, p as getTeamId, r as RequestScope, s as getOrgId, t as AUTHENTICATED_SCOPE, u as getScopeContext, v as isElevated, x as isService, y as isMember } from "../types-C72d3NDn.mjs";
-import { i as elevationPlugin, n as ElevationOptions, r as _default, t as ElevationEvent } from "../elevation-s5ykdNHr.mjs";
+import { _ as isAuthenticated, a as getClientId, b as isOrgInScope, c as getOrgRoles, d as getScopeContextMap, f as getServiceScopes, g as hasOrgAccess, h as getUserRoles, i as getAncestorOrgIds, l as getRequestScope, m as getUserId, n as PUBLIC_SCOPE, o as getOrgContext, p as getTeamId, r as RequestScope, s as getOrgId, t as AUTHENTICATED_SCOPE, u as getScopeContext, v as isElevated, x as isService, y as isMember } from "../types-BD85MlEK.mjs";
+import { i as elevationPlugin, n as ElevationOptions, r as _default, t as ElevationEvent } from "../elevation-B6S5csVA.mjs";
 import { FastifyReply, FastifyRequest } from "fastify";
 
 //#region src/scope/rateLimitKey.d.ts

package/dist/scope/index.mjs

@@ -1,6 +1,6 @@
 import { _ as isElevated, a as getOrgContext, b as isService, c as getRequestScope, d as getServiceScopes, f as getTeamId, g as isAuthenticated, h as hasOrgAccess, i as getClientId, l as getScopeContext, m as getUserRoles, n as PUBLIC_SCOPE, o as getOrgId, p as getUserId, r as getAncestorOrgIds, s as getOrgRoles, t as AUTHENTICATED_SCOPE, u as getScopeContextMap, v as isMember, y as isOrgInScope } from "../types-AOD8fxIw.mjs";
 import { n as normalizeRoles } from "../types-ZUu_h0jp.mjs";
-import { n as elevation_default, t as elevationPlugin } from "../elevation-BBGFjzIP.mjs";
+import { n as elevation_default, t as elevationPlugin } from "../elevation-DxQ6ACbt.mjs";
 //#region src/scope/rateLimitKey.ts
 function createTenantKeyGenerator(opts) {
 	if (opts?.strategy) return opts.strategy;

package/dist/storage-BwGQXUpd.d.mts

@@ -0,0 +1,146 @@
+//#region src/types/storage.d.ts
+/**
+ * Arc's minimal backend-agnostic storage contract.
+ *
+ * Implementations live OUTSIDE arc core. This interface is deliberately
+ * small — no variants, no hashing, no CDN transforms, no multi-tenancy
+ * policy. Those are adapter concerns.
+ *
+ * Adapter authors should verify their implementation with
+ * `runStorageContract()` from `@classytic/arc/testing/storage` —
+ * passing the contract guarantees compatibility with every arc preset
+ * that consumes `Storage`.
+ *
+ * @example
+ * ```typescript
+ * import type { Storage } from '@classytic/arc/types/storage';
+ *
+ * export function memoryStorage(): Storage {
+ *   const rows = new Map<string, { buffer: Buffer; contentType: string }>();
+ *   return {
+ *     async upload(input) {
+ *       const id = crypto.randomUUID();
+ *       rows.set(id, { buffer: input.buffer, contentType: input.mimeType });
+ *       return { id, url: `memory://${id}`, pathname: id, contentType: input.mimeType, bytes: input.size };
+ *     },
+ *     async read(id) {
+ *       const row = rows.get(id);
+ *       if (!row) throw new Error('Not found');
+ *       return { kind: 'buffer', buffer: row.buffer, contentType: row.contentType };
+ *     },
+ *     async delete(id) { return rows.delete(id); },
+ *   };
+ * }
+ * ```
+ */
+/**
+ * Input passed to `Storage.upload()`.
+ * The preset populates this from the parsed multipart file.
+ */
+interface StorageUploadInput {
+  /** File bytes. */
+  buffer: Buffer;
+  /** Original filename from the client. */
+  filename: string;
+  /** IANA media type — preset validates via `multipartBody`. */
+  mimeType: string;
+  /** Size in bytes. Equals `buffer.length`. */
+  size: number;
+}
+/**
+ * Context threaded through every storage call.
+ * Adapters decide which keys they care about.
+ */
+interface StorageContext {
+  /**
+   * App-defined scope. Arc populates this from `RequestScope` via the preset's
+   * `contextFrom` option so adapters can isolate per-tenant / per-user / per-project.
+   */
+  scope?: Record<string, unknown>;
+  /** Optional request correlation id for logging. */
+  requestId?: string;
+}
+/**
+ * Handle returned by `Storage.upload()`.
+ * The adapter owns the id namespace and URL format.
+ */
+interface StorageFile {
+  /** Stable ID — the adapter owns the namespace. Used as the route param for GET/DELETE. */
+  id: string;
+  /** Public or signed URL — what the frontend stores in an `<img src>`. */
+  url: string;
+  /** Storage-side path / key. Opaque to arc; useful for admin tooling. */
+  pathname: string;
+  /** IANA media type — usually echoed from `input.mimeType`. */
+  contentType: string;
+  /** Size in bytes. */
+  bytes: number;
+  /** Adapter-defined metadata passed through to the response body. */
+  metadata?: Record<string, unknown>;
+}
+/**
+ * Optional byte range for partial reads.
+ * End-inclusive, matching HTTP `Range: bytes=start-end` semantics and
+ * media-kit's `StorageDriver.read()` contract.
+ */
+interface StorageReadRange {
+  /** First byte offset (inclusive). */
+  start: number;
+  /** Last byte offset (inclusive). */
+  end: number;
+}
+/**
+ * Result of `Storage.read()`.
+ * Adapters pick whichever shape is natural; the preset handler branches on `kind`.
+ * Large/remote backends should return a stream; small/in-memory backends can
+ * return a buffer without wrapping it in a `PassThrough` for no reason.
+ */
+type StorageReadResult = {
+  kind: "stream";
+  stream: NodeJS.ReadableStream;
+  contentType: string; /** Total size of the full object (NOT the ranged slice). Required for `Content-Range`. */
+  bytes?: number; /** Actual byte range returned when the caller passed `range`. */
+  range?: StorageReadRange;
+} | {
+  kind: "buffer";
+  buffer: Buffer;
+  contentType: string; /** Total size of the full object. Used for `Content-Range` on partial reads. */
+  totalBytes?: number; /** Actual byte range returned when the caller passed `range`. */
+  range?: StorageReadRange;
+};
+/**
+ * Minimal storage contract consumed by `filesUploadPreset`.
+ *
+ * Adapters are ~50–100 LOC wrappers around S3, GCS, local FS, GridFS,
+ * media-kit, or a provider Files API. Ship zero reference adapters in
+ * arc core — the one you'd pick is always the wrong default.
+ */
+interface Storage {
+  /** Write bytes, return a stable handle. */
+  upload(input: StorageUploadInput, ctx: StorageContext): Promise<StorageFile>;
+  /**
+   * Read bytes by id. Streaming preferred; Buffer fine for small files.
+   *
+   * If `range` is provided, implementations SHOULD return only the requested
+   * slice and set `range` on the result. Implementations that cannot range
+   * (e.g. trivial in-memory adapters) MAY return the full object and let the
+   * preset slice it — the preset handles both cases.
+   */
+  read(id: string, ctx: StorageContext, range?: StorageReadRange): Promise<StorageReadResult>;
+  /**
+   * Remove bytes by id. MAY be a soft delete — the interface doesn't
+   * dictate lifecycle. Return `false` when the id was already absent.
+   */
+  delete(id: string, ctx: StorageContext): Promise<boolean>;
+  /** Optional — fast existence check without a full read. */
+  exists?(id: string, ctx: StorageContext): Promise<boolean>;
+  /**
+   * Optional — return a fresh URL for an existing id. Called by the preset
+   * when the stored `url` may have expired (signed URLs, rotated buckets).
+   * Default behavior when omitted: the preset falls back to the url stored
+   * on the original `upload()` result.
+   */
+  resolveUrl?(id: string, ctx: StorageContext): Promise<string>;
+}
+//#endregion
+export { StorageReadResult as a, StorageReadRange as i, StorageContext as n, StorageUploadInput as o, StorageFile as r, Storage as t };

package/dist/store-helpers-DFiZl5TL.mjs

@@ -0,0 +1,57 @@
+//#region src/adapters/store-helpers.ts
+/**
+* Classify an error thrown by `getOne` / `getById` / `update` as a
+* "document not found" miss. Mongokit uses `status: 404`, Prisma uses
+* `code: 'P2025'`, some kits throw `DocumentNotFoundError`. Kits that
+* return `null` on miss never see this predicate fire — it only kicks in
+* when a driver chose to throw.
+*/
+function isNotFoundError(err) {
+	if (!err || typeof err !== "object") return false;
+	const e = err;
+	if (e.status === 404 || e.statusCode === 404) return true;
+	if (e.code === "P2025") return true;
+	if (e.name === "DocumentNotFoundError") return true;
+	return false;
+}
+/**
+* Build a `safeGetOne(filter)` that papers over the throw-vs-null split
+* in kit implementations. Real errors propagate; miss returns `null`.
+* Throws if the repository lacks `getOne` — callers must check.
+*/
+function createSafeGetOne(repository) {
+	if (typeof repository.getOne !== "function") throw new Error("createSafeGetOne: repository.getOne is required");
+	const getOne = repository.getOne.bind(repository);
+	return async (filter) => {
+		try {
+			return await getOne(filter) ?? null;
+		} catch (err) {
+			if (isNotFoundError(err)) return null;
+			throw err;
+		}
+	};
+}
+/**
+* Build a dup-key predicate for the given repository. Prefers the kit's
+* own `isDuplicateKeyError` (it knows its driver — Mongo `11000`, Prisma
+* `P2002`, Postgres `23505`, MySQL `1062`, etc.); falls back to a
+* conservative Mongo check so mongokit ≤3.8 keeps working without changes.
+*
+* Non-mongo kits MUST implement the predicate to participate in
+* idempotency/outbox dup-handling semantics.
+*
+* `name === "MongoServerError"` alone is deliberately NOT matched — that
+* also fires on WriteConflict / NotWritablePrimary / transient failures,
+* which must propagate rather than silently become 409s.
+*/
+function createIsDuplicateKeyError(repository) {
+	const repoPredicate = typeof repository.isDuplicateKeyError === "function" ? repository.isDuplicateKeyError.bind(repository) : null;
+	return (err) => {
+		if (repoPredicate) return repoPredicate(err);
+		if (!err || typeof err !== "object") return false;
+		const e = err;
+		return e.code === 11e3 || e.codeName === "DuplicateKey";
+	};
+}
+//#endregion
+export { createSafeGetOne as n, createIsDuplicateKeyError as t };

package/dist/testing/index.d.mts

@@ -1,5 +1,6 @@
-import { Zt as CrudRepository, m as AnyRecord, qt as ResourceDefinition } from "../interface-BVuMfeVv.mjs";
-import { d as ResourceLike, r as CreateAppOptions } from "../types-Bg2X42_m.mjs";
+import { Kt as ResourceDefinition, Xt as CrudRepository, p as AnyRecord } from "../interface-YrWsmKqE.mjs";
+import { d as ResourceLike, r as CreateAppOptions } from "../types-CunEX4UX.mjs";
+import { StorageContractSetup, StorageContractSetupResult, runStorageContract } from "./storageContract.mjs";
 import Fastify, { FastifyInstance, FastifyServerOptions } from "fastify";
 import { Connection } from "mongoose";
 import { Mock } from "vitest";
@@ -630,21 +631,12 @@ declare class TestHarness<T = unknown> {
   private _createdIds;
   constructor(resource: ResourceDefinition<unknown>, options: TestHarnessOptions<T>);
   /**
-   * Run all baseline tests
+   * Run all baseline tests (schema, presets, field permissions, pipeline, events).
    *
-   * Executes CRUD, validation, and preset tests
+   * For HTTP-level CRUD coverage (routes, auth, permissions), use
+   * {@link HttpTestHarness} instead.
    */
   runAll(): void;
-  /**
-   * Run CRUD operation tests (model-level)
-   *
-   * Tests: create, read (list + getById), update, delete
-   *
-   * @deprecated Use `HttpTestHarness.runCrud()` for HTTP-level CRUD tests.
-   * This method tests Mongoose models directly and does not exercise
-   * HTTP routes, authentication, permissions, or the Arc pipeline.
-   */
-  runCrud(): void;
   /**
    * Run validation tests
    *
@@ -921,4 +913,4 @@ declare class TestDataLoader {
   cleanup(): Promise<void>;
 }
 //#endregion
-export { type AuthProvider, type AuthResponse, type BetterAuthTestHelpers, type BetterAuthTestHelpersOptions, type CreateTestAppOptions, DatabaseSnapshot, TestFixtures as DbTestFixtures, type GenerateTestFileOptions, HttpTestHarness, type HttpTestHarnessOptions, InMemoryDatabase, type OrgResponse, type SetupBetterAuthOrgOptions, type SetupUserConfig, type TestAppResult, TestDataLoader, TestDatabase, type TestFixtures$1 as TestFixtures, TestHarness, type TestHarnessOptions, type TestOrgContext, TestRequestBuilder, TestSeeder, TestTransaction, type TestUserContext, createBetterAuthProvider, createBetterAuthTestHelpers, createConfigTestSuite, createDataFactory, createHttpTestHarness, createJwtAuthProvider, createMinimalTestApp, createMockController, createMockReply, createMockRepository, createMockRequest, createMockUser, createSnapshotMatcher, createSpy, createTestApp, createTestAuth, createTestHarness, createTestTimer, generateTestFile, preloadResources, preloadResourcesAsync, request, safeParseBody, setupBetterAuthOrg, waitFor, withTestDb };
+export { type AuthProvider, type AuthResponse, type BetterAuthTestHelpers, type BetterAuthTestHelpersOptions, type CreateTestAppOptions, DatabaseSnapshot, TestFixtures as DbTestFixtures, type GenerateTestFileOptions, HttpTestHarness, type HttpTestHarnessOptions, InMemoryDatabase, type OrgResponse, type SetupBetterAuthOrgOptions, type SetupUserConfig, type StorageContractSetup, type StorageContractSetupResult, type TestAppResult, TestDataLoader, TestDatabase, type TestFixtures$1 as TestFixtures, TestHarness, type TestHarnessOptions, type TestOrgContext, TestRequestBuilder, TestSeeder, TestTransaction, type TestUserContext, createBetterAuthProvider, createBetterAuthTestHelpers, createConfigTestSuite, createDataFactory, createHttpTestHarness, createJwtAuthProvider, createMinimalTestApp, createMockController, createMockReply, createMockRepository, createMockRequest, createMockUser, createSnapshotMatcher, createSpy, createTestApp, createTestAuth, createTestHarness, createTestTimer, generateTestFile, preloadResources, preloadResourcesAsync, request, runStorageContract, safeParseBody, setupBetterAuthOrg, waitFor, withTestDb };