@classytic/arc 2.8.4 → 2.8.5

package/dist/{redis-stream-D54N5oXs.d.mts → redis-stream-CrsfUmPt.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 EventTransport, n as EventHandler, r as EventLogger, t as DomainEvent } from "./EventTransport-BXja8NOc.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 RegisterOptions, H as IntrospectionPluginOptions, Kt as ResourceRegistry } from "../interface-CMRutPfe.mjs";
 import { FastifyPluginAsync } from "fastify";
 
 //#region src/registry/introspectionPlugin.d.ts

package/dist/registry/index.mjs

@@ -1,3 +1,3 @@
-import { n as introspectionPlugin_default, t as introspectionPlugin } from "../registry-B0Wl7uVV.mjs";
-import { t as ResourceRegistry } from "../ResourceRegistry-Dq3_zBQP.mjs";
+import { n as introspectionPlugin_default, t as introspectionPlugin } from "../registry-BiTKT1Dg.mjs";
+import { t as ResourceRegistry } from "../ResourceRegistry-C6uXlWe3.mjs";
 export { ResourceRegistry, introspectionPlugin_default as introspectionPlugin, introspectionPlugin as introspectionPluginFn };

package/dist/{resourceToTools-O_HwWXFa.mjs → resourceToTools-8s-EsCCe.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 pluralize } from "./pluralize-CWP6MB39.mjs";
 import { z } from "zod";
 //#region src/integrations/mcp/createMcpServer.ts
 /**

package/dist/rpc/index.d.mts

@@ -1,4 +1,4 @@
-import { r as CircuitBreakerOptions } from "../circuitBreaker-CvXkjfrW.mjs";
+import { r as CircuitBreakerOptions } from "../circuitBreaker-dTtG-UyS.mjs";
 
 //#region src/rpc/serviceClient.d.ts
 interface RetryConfig {

package/dist/{schemaConverter-OxfCshus.mjs → schemaConverter-Y7nCYaLJ.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;
@@ -73,19 +86,22 @@ function convertOpenApiSchemas(schemas) {
 * 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.
 */
-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-DtFxrG0s.mjs";
 //#region src/scope/rateLimitKey.ts
 function createTenantKeyGenerator(opts) {
 	if (opts?.strategy) return opts.strategy;

package/dist/{sse-CJpt7LGI.mjs → sse-Ad7ypl9e.mjs}

@@ -1,6 +1,6 @@
 import { t as __exportAll } from "./chunk-BpYLSNr0.mjs";
 import { n as PUBLIC_SCOPE, o as getOrgId } from "./types-AOD8fxIw.mjs";
-import { t as arcLog } from "./logger-CDjpjySd.mjs";
+import { t as arcLog } from "./logger-D1YrIImS.mjs";
 import fp from "fastify-plugin";
 //#region src/plugins/sse.ts
 var sse_exports = /* @__PURE__ */ __exportAll({

package/dist/storage-Dfzt4VTl.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/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 { Zt as CrudRepository, m as AnyRecord, qt as ResourceDefinition } from "../interface-CMRutPfe.mjs";
+import { d as ResourceLike, r as CreateAppOptions } from "../types-Ch9pTQbf.mjs";
+import { StorageContractSetup, StorageContractSetupResult, runStorageContract } from "./storageContract.mjs";
 import Fastify, { FastifyInstance, FastifyServerOptions } from "fastify";
 import { Connection } from "mongoose";
 import { Mock } from "vitest";
@@ -921,4 +922,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 };

package/dist/testing/index.mjs

@@ -1,5 +1,6 @@
 import { t as CRUD_OPERATIONS } from "../constants-Cxde4rpC.mjs";
 import { n as applyFieldWritePermissions, t as applyFieldReadPermissions } from "../fields-ipsbIRPK.mjs";
+import { runStorageContract } from "./storageContract.mjs";
 import Fastify from "fastify";
 import mongoose from "mongoose";
 import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
@@ -1796,7 +1797,7 @@ function runEventTests(resourceName, displayName, events) {
 * ```
 */
 async function createTestApp(options = {}) {
-	const { createApp } = await import("../createApp-BOYjBgdI.mjs").then((n) => n.r);
+	const { createApp } = await import("../createApp-B1EY8zxa.mjs").then((n) => n.r);
 	const { useInMemoryDb = true, mongoUri: providedMongoUri, ...appOptions } = options;
 	const defaultAuth = {
 		type: "jwt",
@@ -1994,4 +1995,4 @@ var TestDataLoader = class {
 	}
 };
 //#endregion
-export { DatabaseSnapshot, TestFixtures as DbTestFixtures, HttpTestHarness, InMemoryDatabase, TestDataLoader, TestDatabase, TestHarness, TestRequestBuilder, TestSeeder, TestTransaction, 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 { DatabaseSnapshot, TestFixtures as DbTestFixtures, HttpTestHarness, InMemoryDatabase, TestDataLoader, TestDatabase, TestHarness, TestRequestBuilder, TestSeeder, TestTransaction, 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 };

package/dist/testing/storageContract.d.mts

@@ -0,0 +1,26 @@
+import { t as Storage } from "../storage-Dfzt4VTl.mjs";
+
+//#region src/testing/storageContract.d.ts
+interface StorageContractSetupResult {
+  storage: Storage;
+  teardown: () => Promise<void>;
+}
+type StorageContractSetup = () => Promise<StorageContractSetupResult>;
+/**
+ * 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
+ */
+declare function runStorageContract(name: string, setup: StorageContractSetup): void;
+//#endregion
+export { StorageContractSetup, StorageContractSetupResult, runStorageContract };

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