@classytic/arc 2.41.1 → 2.43.0

package/dist/testing/requiredPorts.d.mts

@@ -0,0 +1,17 @@
+
+import { r as ArcModuleInput } from "../types-BJ-2XqVF.mjs";
+//#region src/testing/requiredPorts.d.ts
+interface RequiredPortsOptions {
+  /** Modules composed alongside — the peers the module `dependsOn` or `requires.modules`. */
+  readonly with?: readonly ArcModuleInput[];
+  /** Ports supplied in every case — the peers' own required ports. Never one under test. Values are never read. */
+  readonly ports?: Readonly<Record<string, unknown>>;
+}
+interface RequiredPortsResult {
+  readonly module: string;
+  /** The required ports, in declared order. */
+  readonly ports: readonly string[];
+}
+declare function assertRequiresPorts(module: ArcModuleInput, ports: readonly string[], options?: RequiredPortsOptions): Promise<RequiredPortsResult>;
+//#endregion
+export { RequiredPortsOptions, RequiredPortsResult, assertRequiresPorts };

package/dist/testing/requiredPorts.mjs

@@ -0,0 +1,65 @@
+/*! @classytic/arc v2.43.0 | MIT | https://classytic.com */
+import { c as declareModules, d as resolveModule, i as planModules, r as compositionProblems } from "../plan-FVR6LP59.mjs";
+//#region src/testing/requiredPorts.ts
+/**
+* Assert a module declares EXACTLY `ports` as required, and that composing it without any one of
+* them fails naming the module and that port — alone, and all together in one error. `[]` asserts
+* it declares none and plans with nothing supplied. `with` composes peers it depends on; `ports`
+* supplies what they need. Pass `ports` as a literal, never the module's own list: dropping a port
+* from the module must fail here.
+*
+* ```ts
+* it("fails loud without each port", () =>
+*   assertRequiresPorts(createOrderModule(deps), ["connection", "outbox"], { with: [catalog] }));
+* ```
+*/
+async function assertRequiresPorts(module, ports, options = {}) {
+	const peers = options.with ?? [];
+	const base = options.ports ?? {};
+	const fail = (msg) => {
+		throw new Error(`[arc/testing] assertRequiresPorts: ${msg}`);
+	};
+	const target = await resolveModule(module);
+	const name = target.name;
+	const { active } = await declareModules([...peers, module]);
+	if (!active.some((m) => m.name === name)) fail(`module "${name}" is not active in this composition`);
+	const declared = target.requires?.ports ?? [];
+	if (!sameList(declared, ports)) fail(`module "${name}" declares required ports [${declared.join(", ")}], expected [${ports.join(", ")}]`);
+	const shadowed = ports.filter((p) => Object.hasOwn(base, p));
+	if (shadowed.length > 0) fail(`options.ports supplies a port under test: ${shadowed.join(", ")}`);
+	const supplying = (names) => {
+		const out = { ...base };
+		for (const p of names) out[p] = Object.freeze({ port: p });
+		return out;
+	};
+	const missingFor = (supplied) => {
+		const problems = compositionProblems(active, supplied);
+		const foreign = problems.filter((p) => p.module !== name || p.code !== "missing-port");
+		if (foreign.length > 0) fail(`the composition has problems besides the module's ports — fix \`with\`/\`ports\`:\n${foreign.map((p) => `  - ${p.message}`).join("\n")}`);
+		return problems.map((p) => p.target);
+	};
+	const unplanned = await planModules([...peers, module], { ports: supplying(ports) }).catch((err) => err);
+	if (unplanned instanceof Error) fail(`module "${name}" does not plan with every port supplied: ${unplanned.message}`);
+	if (ports.length === 0) return {
+		module: name,
+		ports
+	};
+	const allMissing = missingFor(supplying([]));
+	if (!sameList(allMissing, ports)) fail(`with no port supplied, module "${name}" reported [${allMissing.join(", ")}], expected [${ports.join(", ")}] in ONE error`);
+	const refused = await planModules([...peers, module], { ports: supplying([]) }).then(() => null, (err) => err instanceof Error ? err.message : String(err));
+	if (refused === null) fail(`module "${name}" planned with none of its required ports supplied`);
+	for (const port of ports) {
+		const missing = missingFor(supplying(ports.filter((p) => p !== port)));
+		if (!sameList(missing, [port])) fail(`without "${port}", module "${name}" reported [${missing.join(", ")}], expected exactly ["${port}"]`);
+		if (!refused?.includes(`module "${name}" requires port "${port}"`)) fail(`the composition error does not name module "${name}" and port "${port}": ${refused}`);
+	}
+	return {
+		module: name,
+		ports
+	};
+}
+function sameList(a, b) {
+	return a.length === b.length && a.every((x, i) => x === b[i]);
+}
+//#endregion
+export { assertRequiresPorts };

package/dist/testing/storageContract.mjs

@@ -1,4 +1,4 @@
-/*! @classytic/arc v2.41.1 | MIT | https://classytic.com */
+/*! @classytic/arc v2.43.0 | MIT | https://classytic.com */
 import { afterAll, beforeAll, describe, expect, it } from "vitest";
 //#region src/testing/storageContract.ts
 /**

package/dist/timing-qczZ0YC-.mjs

@@ -0,0 +1,46 @@
+/*! @classytic/arc v2.43.0 | MIT | https://classytic.com */
+import { createHash } from "node:crypto";
+//#region src/utils/operationIdentity.ts
+/** Security context included in idempotency identities across transports. */
+function operationIdentity(operation, scope, fallbackPrincipal, namespace) {
+	const principal = scope?.kind === "service" ? scope.clientId : scope?.kind === "public" ? fallbackPrincipal : scope?.userId ?? fallbackPrincipal;
+	const org = scope && "organizationId" in scope ? scope.organizationId : void 0;
+	const team = scope && "teamId" in scope ? scope.teamId : void 0;
+	const context = scope && "context" in scope ? Object.entries(scope.context ?? {}).sort(([a], [b]) => a.localeCompare(b)) : [];
+	const identity = JSON.stringify([
+		namespace ?? "",
+		operation,
+		scope?.kind ?? "public",
+		principal ?? "anon",
+		org ?? null,
+		team ?? null,
+		context
+	]);
+	return createHash("sha256").update(identity).digest("hex");
+}
+//#endregion
+//#region src/idempotency/stores/interface.ts
+/**
+* Helper to create a result object
+*/
+function createIdempotencyResult(statusCode, body, headers, ttlMs, requestFingerprint) {
+	const now = /* @__PURE__ */ new Date();
+	return {
+		...requestFingerprint ? { requestFingerprint } : {},
+		statusCode,
+		headers,
+		body,
+		createdAt: now,
+		expiresAt: new Date(now.getTime() + ttlMs)
+	};
+}
+function resolveIdempotencyTiming(ttlMs, lockTimeoutMs) {
+	const timing = {
+		ttlMs: ttlMs ?? 864e5,
+		lockTimeoutMs: lockTimeoutMs ?? 3e4
+	};
+	for (const [name, value] of Object.entries(timing)) if (!Number.isFinite(value) || value <= 0) throw new Error(`[arc idempotency] ${name} must be a positive finite duration in milliseconds.`);
+	return timing;
+}
+//#endregion
+export { createIdempotencyResult as n, operationIdentity as r, resolveIdempotencyTiming as t };

package/dist/{transactionContext-CPbdlnVw.mjs → transactionContext-DjFkrNG6.mjs}

@@ -1,4 +1,4 @@
-/*! @classytic/arc v2.41.1 | MIT | https://classytic.com */
+/*! @classytic/arc v2.43.0 | MIT | https://classytic.com */
 import { AsyncLocalStorage } from "node:async_hooks";
 //#region src/context/transactionContext.ts
 /**

package/dist/{typeGuards-BLjPgVBm.mjs → typeGuards-CySF12G-.mjs}

@@ -1,4 +1,4 @@
-/*! @classytic/arc v2.41.1 | MIT | https://classytic.com */
+/*! @classytic/arc v2.43.0 | MIT | https://classytic.com */
 //#region src/utils/typeGuards.ts
 /** Check if fastify has the events plugin registered */
 function hasEvents(instance) {

package/dist/types/index.d.mts

@@ -1,6 +1,6 @@
 
 import { i as RequestScope } from "../types-Ddl9OjmE.mjs";
-import { a as UserLike, c as DataPolicy, d as UserBase, i as ObjectId, l as PermissionCheck, n as ArcRequest, o as UserOrganization, r as JWTPayload, s as AuthorizationDecision, t as AnyRecord, u as PermissionContext } from "../base-CxrV1LmG.mjs";
-import { $ as OpenApiSchemas, A as RequestIdOptions, An as WriteVerbKey, At as RouteDefinition, C as RequestContext, D as HealthCheck, Dn as MutationWriteContext, Dt as ActionEntry, E as GracefulShutdownOptions, Et as ActionDefinition, F as FastifyWithDecorators, Fn as IControllerResponse, Ft as AuthPluginOptions, G as OnTenantDeleteConfig, H as CrudController, I as MiddlewareHandler, In as IRequestContext, It as Authenticator, J as PresetHook, K as ResolvedTenantPurge, L as RequestWithExtras, Ln as RawRouteHandler, Lt as AuthenticatorContext, M as EventsDecorator, Mn as ControllerLike, Mt as RouteMethod, N as FastifyRequestExtras, Nn as FastifyHandler, Nt as RateLimitConfig, O as HealthOptions, On as ResourceWrites, Ot as ActionHandlerFn, P as FastifyWithAuth, Pn as IController, Pt as AuthHelpers, Q as MiddlewareConfig, Rn as RouteHandler, Rt as JwtContext, S as QueryParserInterface, T as CrudRouterOptions, Tt as ResourceCacheConfig, U as ResourceConfig, W as ResourcePermissions, X as CrudRouteKey, Y as PresetResult, Z as CrudSchemas, _ as ControllerQueryOptions, a as InferAdapterDoc, at as ResourceExtensions, b as ParsedQuery, c as TypedController, d as PaginationResult, et as RouteSchemaOptions, f as IntrospectionData, g as ArcInternalMetadata, h as ResourceMetadata, i as ValidationResult, it as ResourceHooks, j as ArcDecorator, jn as ControllerHandler, jt as RouteMcpConfig, k as IntrospectionPluginOptions, kn as WriteContext, kt as ActionsMap, l as TypedRepository, m as RegistryStats, n as ConfigError, nt as FieldRule, o as InferDocType, ot as EventDefinition, p as RegistryEntry, q as PresetFunction, r as ValidateOptions, rt as ResourceHookContext, s as InferResourceDoc, t as RouteHandlerMethod, tt as ArcFieldRule, u as TypedResourceConfig, v as LookupOption, w as ServiceContext, x as PopulateOption, xn as BaseControllerOptions, y as OwnershipCheck, zt as TokenPair } from "../index-DHbyPo5j.mjs";
-import { n as ElevationOptions, t as ElevationEvent } from "../elevation-BXCfVcNG.mjs";
-export type { ActionDefinition, ActionEntry, ActionHandlerFn, ActionsMap, AnyRecord, ArcDecorator, ArcFieldRule, ArcInternalMetadata, ArcRequest, AuthHelpers, AuthPluginOptions, Authenticator, AuthenticatorContext, AuthorizationDecision, BaseControllerOptions, ConfigError, ControllerHandler, ControllerLike, ControllerQueryOptions, CrudController, CrudRouteKey, CrudRouterOptions, CrudSchemas, DataPolicy, ElevationEvent, ElevationOptions, EventDefinition, EventsDecorator, FastifyHandler, FastifyRequestExtras, FastifyWithAuth, FastifyWithDecorators, FieldRule, GracefulShutdownOptions, HealthCheck, HealthOptions, IController, IControllerResponse, IRequestContext, InferAdapterDoc, InferDocType, InferResourceDoc, IntrospectionData, IntrospectionPluginOptions, JWTPayload, JwtContext, LookupOption, MiddlewareConfig, MiddlewareHandler, MutationWriteContext, ObjectId, OnTenantDeleteConfig, OpenApiSchemas, OwnershipCheck, PaginationResult, ParsedQuery, PermissionCheck, PermissionContext, PopulateOption, PresetFunction, PresetHook, PresetResult, QueryParserInterface, RateLimitConfig, RawRouteHandler, RegistryEntry, RegistryStats, RequestContext, RequestIdOptions, RequestScope, RequestWithExtras, ResolvedTenantPurge, ResourceCacheConfig, ResourceConfig, ResourceExtensions, ResourceHookContext, ResourceHooks, ResourceMetadata, ResourcePermissions, ResourceWrites, RouteDefinition, RouteHandler, RouteHandlerMethod, RouteMcpConfig, RouteMethod, RouteSchemaOptions, ServiceContext, TokenPair, TypedController, TypedRepository, TypedResourceConfig, UserBase, UserLike, UserOrganization, ValidateOptions, ValidationResult, WriteContext, WriteVerbKey };
+import { a as UserLike, c as DataPolicy, d as UserBase, i as ObjectId, l as PermissionCheck, n as ArcRequest, o as UserOrganization, r as JWTPayload, s as AuthorizationDecision, t as AnyRecord, u as PermissionContext } from "../base-CZyixEQR.mjs";
+import { $ as ResourceHookContext, A as RequestWithExtras, An as WriteContext, At as AuthHelpers, B as OnTenantDeleteConfig, C as RequestIdOptions, Ct as ActionEntry, D as FastifyWithAuth, Dt as RouteMcpConfig, E as FastifyRequestExtras, Et as RouteDefinition, Fn as IController, Ft as TokenPair, G as CrudRouteKey, H as PresetFunction, I as CrudController, In as IControllerResponse, J as MiddlewareConfig, K as CrudSchemas, L as ResourceConfig, Ln as IRequestContext, Mn as ControllerHandler, Mt as Authenticator, Nn as ControllerLike, Nt as AuthenticatorContext, O as FastifyWithDecorators, On as MutationWriteContext, Ot as RouteMethod, Pn as FastifyHandler, Pt as JwtContext, Q as FieldRule, R as ResourceIdempotencyConfig, Rn as RawRouteHandler, S as IntrospectionPluginOptions, St as ActionDefinition, T as EventsDecorator, Tt as ActionsMap, U as PresetHook, V as ResolvedTenantPurge, W as PresetResult, X as RouteSchemaOptions, Y as OpenApiSchemas, Z as ArcFieldRule, _ as ServiceContext, a as IntrospectionData, b as HealthCheck, c as ResourceMetadata, d as LookupOption, et as ResourceHooks, f as OwnershipCheck, g as RequestContext, h as QueryParserInterface, i as PaginationResult, jn as WriteVerbKey, jt as AuthPluginOptions, k as MiddlewareHandler, kn as ResourceWrites, kt as RateLimitConfig, l as ArcInternalMetadata, m as PopulateOption, n as InferDocType, nt as EventDefinition, o as RegistryEntry, p as ParsedQuery, q as LookupPolicy, r as InferResourceDoc, s as RegistryStats, t as InferAdapterDoc, tt as ResourceExtensions, u as ControllerQueryOptions, v as CrudRouterOptions, w as ArcDecorator, wt as ActionHandlerFn, x as HealthOptions, xn as BaseControllerOptions, xt as ResourceCacheConfig, y as GracefulShutdownOptions, z as ResourcePermissions, zn as RouteHandler } from "../index-mqaqZNpe.mjs";
+import { n as ElevationOptions, t as ElevationEvent } from "../elevation-BW2J3tNj.mjs";
+export type { ActionDefinition, ActionEntry, ActionHandlerFn, ActionsMap, AnyRecord, ArcDecorator, ArcFieldRule, ArcInternalMetadata, ArcRequest, AuthHelpers, AuthPluginOptions, Authenticator, AuthenticatorContext, AuthorizationDecision, BaseControllerOptions, ControllerHandler, ControllerLike, ControllerQueryOptions, CrudController, CrudRouteKey, CrudRouterOptions, CrudSchemas, DataPolicy, ElevationEvent, ElevationOptions, EventDefinition, EventsDecorator, FastifyHandler, FastifyRequestExtras, FastifyWithAuth, FastifyWithDecorators, FieldRule, GracefulShutdownOptions, HealthCheck, HealthOptions, IController, IControllerResponse, IRequestContext, InferAdapterDoc, InferDocType, InferResourceDoc, IntrospectionData, IntrospectionPluginOptions, JWTPayload, JwtContext, LookupOption, LookupPolicy, MiddlewareConfig, MiddlewareHandler, MutationWriteContext, ObjectId, OnTenantDeleteConfig, OpenApiSchemas, OwnershipCheck, PaginationResult, ParsedQuery, PermissionCheck, PermissionContext, PopulateOption, PresetFunction, PresetHook, PresetResult, QueryParserInterface, RateLimitConfig, RawRouteHandler, RegistryEntry, RegistryStats, RequestContext, RequestIdOptions, RequestScope, RequestWithExtras, ResolvedTenantPurge, ResourceCacheConfig, ResourceConfig, ResourceExtensions, ResourceHookContext, ResourceHooks, ResourceIdempotencyConfig, ResourceMetadata, ResourcePermissions, ResourceWrites, RouteDefinition, RouteHandler, RouteMcpConfig, RouteMethod, RouteSchemaOptions, ServiceContext, TokenPair, UserBase, UserLike, UserOrganization, WriteContext, WriteVerbKey };

package/dist/types/index.mjs

@@ -1,2 +1,2 @@
-/*! @classytic/arc v2.41.1 | MIT | https://classytic.com */
+/*! @classytic/arc v2.43.0 | MIT | https://classytic.com */
 export {};

package/dist/types/storage.mjs

@@ -1,2 +1,2 @@
-/*! @classytic/arc v2.41.1 | MIT | https://classytic.com */
+/*! @classytic/arc v2.43.0 | MIT | https://classytic.com */
 export {};

package/dist/{types-CWQn9-IC.d.mts → types-B4Aq4Sdj.d.mts}

@@ -1,5 +1,6 @@
 
-import { V as ResourceDefinition } from "./index-DHbyPo5j.mjs";
+import { F as ResourceDefinition } from "./index-mqaqZNpe.mjs";
+import { i as ResourceRateLimiter } from "./resourceRateLimit-Wf6d6FL9.mjs";
 import { z } from "zod";
 //#region src/integrations/mcp/types.d.ts
 /** Behavioral hints for MCP clients (tool annotations per MCP spec) */
@@ -87,8 +88,12 @@ interface ToolDefinition<TSession = McpAuthResult> {
   name: string;
   description: string;
   title?: string;
-  /** Flat Zod shape: `{ field: z.string() }`. NOT z.object(). */
-  inputSchema?: Record<string, z.ZodTypeAny>;
+  /**
+   * Flat Zod shape `{ field: z.string() }` (the SDK wraps it in a STRIPPING
+   * `z.object()`), or a whole Zod schema registered as-is — use the whole form
+   * when unknown keys must be refused or the input is a union of objects.
+   */
+  inputSchema?: ToolInputSchema;
   /** Flat Zod shape for structured output validation */
   outputSchema?: Record<string, z.ZodTypeAny>;
   annotations?: ToolAnnotations;
@@ -105,6 +110,8 @@ interface ToolDefinition<TSession = McpAuthResult> {
    */
   source?: string;
 }
+/** A tool's input contract: a flat Zod shape, or a whole Zod schema validated as-is. */
+type ToolInputSchema = Record<string, z.ZodTypeAny> | z.ZodType;
 /** Output of definePrompt() — plain data, not yet registered */
 interface PromptDefinition {
   name: string;
@@ -178,6 +185,8 @@ type CrudDescriptionOverride = string | ((meta: CrudDescriptionMeta) => string);
  * omit it to keep the legacy dispatch-only behavior.
  */
 interface McpExecutionWiring {
+  /** Same resource budget and backend used by REST routes. */
+  readonly rateLimiter?: ResourceRateLimiter;
   /** Shared `HookSystem` — `fastify.arc.hooks`. */
   readonly hooks?: unknown;
   /** Event bus decorator — `fastify.events`. */
@@ -192,6 +201,12 @@ interface McpExecutionWiring {
    * on mutating CRUD tools and enables executor-level check/lock/replay.
    */
   readonly idempotencyStore?: unknown;
+  /** Explicit migration escape matching the HTTP idempotency plugin. */
+  readonly allowUnfencedCompletion?: boolean;
+  /** Cached result lifetime shared with the HTTP plugin; defaults to 24 hours. */
+  readonly idempotencyTtlMs?: number;
+  /** Completion lease shared with the HTTP plugin; defaults to 30 seconds. */
+  readonly idempotencyLockTimeoutMs?: number;
 }
 /** Per-resource MCP configuration overrides */
 interface McpResourceConfig {
@@ -328,7 +343,7 @@ interface McpPluginOptions {
   /** Instructions for the LLM — guidance on tool usage, constraints */
   instructions?: string;
   /**
-   * Resources to exclude by name (ignored if `expose`/`include` is set).
+   * Resources to exclude by name. Mutually exclusive with `expose`.
    *
    * Drift-prone for LLM-facing surfaces: a new `defineResource()` is exposed
    * by default and you have to remember to add it here. Prefer `expose` when
@@ -341,10 +356,8 @@ interface McpPluginOptions {
    * inverse of `exclude`), matching the principle-of-least-authority that
    * LLM-driven tool surfaces want.
    *
-   * Mutually exclusive with `include` (a deprecated alias) — passing both
-   * throws at registration. Mutually exclusive with `exclude`: the deny
-   * default would render the exclude list redundant; passing both throws
-   * with a hint to drop `exclude`.
+   * Mutually exclusive with `exclude` (the deny default makes it redundant);
+   * passing both throws with a hint to drop `exclude`.
    *
    * @example
    * ```ts
@@ -482,4 +495,4 @@ interface CreateMcpServerConfig {
 /** CRUD operation type */
 type CrudOperation = "list" | "get" | "create" | "update" | "delete";
 //#endregion
-export { ToolDefinition as _, CrudDescriptionOverride as a, McpAuthResult as c, McpResourceConfig as d, PromptDefinition as f, ToolContext as g, ToolAnnotations as h, CrudDescriptionMeta as i, McpExecutionWiring as l, SessionEntry as m, CallToolResult as n, CrudOperation as o, PromptResult as p, CreateMcpServerConfig as r, McpAuthResolver as s, BetterAuthHandler as t, McpPluginOptions as u };
+export { ToolDefinition as _, CrudDescriptionOverride as a, McpAuthResult as c, McpResourceConfig as d, PromptDefinition as f, ToolContext as g, ToolAnnotations as h, CrudDescriptionMeta as i, McpExecutionWiring as l, SessionEntry as m, CallToolResult as n, CrudOperation as o, PromptResult as p, CreateMcpServerConfig as r, McpAuthResolver as s, BetterAuthHandler as t, McpPluginOptions as u, ToolInputSchema as v };