@classytic/arc 2.30.0 → 2.32.0

package/dist/testing/outboxStoreContract.mjs

@@ -1,5 +1,6 @@
+/*! @classytic/arc v2.32.0 | MIT | https://classytic.com */
 import { OutboxOwnershipError } from "@classytic/primitives/outbox";
-import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { afterAll, beforeAll, beforeEach, describe, expect, it } from "vitest";
 //#region src/testing/outboxStoreContract.ts
 let seq = 0;
 /** A minimal well-formed event. Ids are unique per call. */
@@ -29,9 +30,16 @@ function runOutboxStoreContract(name, setup) {
 		afterAll(async () => {
 			if (teardown) await teardown();
 		});
+		/**
+		* Isolation for EVERY test, not just the ones that call `seed()`. Resetting inside
+		* `seed()` left any test that asserts on an empty store — or that only reads —
+		* running against its predecessor's rows.
+		*/
+		beforeEach(async () => {
+			await reset();
+		});
 		/** Save n events, oldest first. */
 		async function seed(n, type) {
-			if (reset) await reset();
 			const events = [];
 			for (let i = 0; i < n; i++) {
 				const e = event(type);
@@ -43,10 +51,10 @@ function runOutboxStoreContract(name, setup) {
 		describe("save — rejects malformed events (invariant 1)", () => {
 			it("persists a well-formed event", async () => {
 				const [e] = await seed(1);
-				expect((await store.getPending(10)).map(idOf)).toContain(idOf(e));
+				const pending = await store.getPending(10);
+				expect(pending.map(idOf)).toContain(idOf(e));
 			});
 			it("THROWS rather than persisting an event with no `type`", async () => {
-				if (reset) await reset();
 				await expect(store.save({
 					payload: {},
 					meta: { id: "no-type" }
@@ -54,7 +62,6 @@ function runOutboxStoreContract(name, setup) {
 				expect((await store.getPending(10)).length).toBe(0);
 			});
 			it("THROWS rather than persisting an event with no `meta.id`", async () => {
-				if (reset) await reset();
 				await expect(store.save({
 					type: "x",
 					payload: {},
@@ -66,7 +73,8 @@ function runOutboxStoreContract(name, setup) {
 		describe("getPending", () => {
 			it("returns events FIFO (oldest first)", async () => {
 				const saved = await seed(3);
-				expect((await store.getPending(10)).slice(0, 3).map(idOf)).toEqual(saved.map(idOf));
+				const pending = await store.getPending(10);
+				expect(pending.slice(0, 3).map(idOf)).toEqual(saved.map(idOf));
 			});
 			it("honours the limit", async () => {
 				await seed(3);
@@ -85,10 +93,11 @@ function runOutboxStoreContract(name, setup) {
 			it("claims pending events", async ({ skip }) => {
 				if (!store.claimPending) return skip();
 				await seed(2);
-				expect((await store.claimPending({
+				const claimed = await store.claimPending({
 					consumerId: "c1",
 					limit: 10
-				})).length).toBe(2);
+				});
+				expect(claimed.length).toBe(2);
 			});
 			it("two concurrent claimers NEVER receive the same event", async ({ skip }) => {
 				if (!store.claimPending) return skip();
@@ -102,7 +111,8 @@ function runOutboxStoreContract(name, setup) {
 				})]);
 				const idsA = a.map(idOf);
 				const idsB = b.map(idOf);
-				expect(idsA.filter((id) => idsB.includes(id))).toEqual([]);
+				const overlap = idsA.filter((id) => idsB.includes(id));
+				expect(overlap).toEqual([]);
 				expect(idsA.length + idsB.length).toBeLessThanOrEqual(6);
 			});
 			it("does not re-claim an event whose lease is still live", async ({ skip }) => {
@@ -113,10 +123,11 @@ function runOutboxStoreContract(name, setup) {
 					limit: 10,
 					leaseMs: 6e4
 				});
-				expect(await store.claimPending({
+				const second = await store.claimPending({
 					consumerId: "c2",
 					limit: 10
-				})).toEqual([]);
+				});
+				expect(second).toEqual([]);
 			});
 			it("RECLAIMS an event whose lease expired (crashed worker)", async ({ skip }) => {
 				if (!store.claimPending) return skip();
@@ -126,18 +137,20 @@ function runOutboxStoreContract(name, setup) {
 					limit: 10,
 					leaseMs: 0
 				});
-				expect((await store.claimPending({
+				const reclaimed = await store.claimPending({
 					consumerId: "c2",
 					limit: 10
-				})).length).toBe(1);
+				});
+				expect(reclaimed.length).toBe(1);
 			});
 			it("claims FIFO", async ({ skip }) => {
 				if (!store.claimPending) return skip();
 				const saved = await seed(3);
-				expect((await store.claimPending({
+				const claimed = await store.claimPending({
 					consumerId: "c1",
 					limit: 2
-				})).map(idOf)).toEqual(saved.slice(0, 2).map(idOf));
+				});
+				expect(claimed.map(idOf)).toEqual(saved.slice(0, 2).map(idOf));
 			});
 		});
 		describe("acknowledge", () => {
@@ -147,7 +160,6 @@ function runOutboxStoreContract(name, setup) {
 				expect((await store.getPending(10)).map(idOf)).not.toContain(idOf(e));
 			});
 			it("is a NO-OP for an unknown id — never an ownership error (invariant 4)", async () => {
-				if (reset) await reset();
 				await expect(store.acknowledge("does-not-exist")).resolves.not.toThrow();
 			});
 			it("THROWS OutboxOwnershipError when consumerId is not the lease owner (invariant 3)", async ({ skip }) => {
@@ -184,10 +196,11 @@ function runOutboxStoreContract(name, setup) {
 				});
 				if (!claimed) return skip();
 				await store.fail(idOf(claimed), { message: "boom" });
-				expect((await store.claimPending({
+				const again = await store.claimPending({
 					consumerId: "c2",
 					limit: 10
-				})).map(idOf)).toContain(idOf(claimed));
+				});
+				expect(again.map(idOf)).toContain(idOf(claimed));
 			});
 			it("THROWS OutboxOwnershipError on a consumerId mismatch (invariant 3)", async ({ skip }) => {
 				if (!store.fail || !store.claimPending) return skip();
@@ -210,10 +223,11 @@ function runOutboxStoreContract(name, setup) {
 				});
 				if (!claimed) return skip();
 				await store.fail(idOf(claimed), { message: "boom" }, { retryAt: new Date(Date.now() + 6e4) });
-				expect((await store.claimPending({
+				const again = await store.claimPending({
 					consumerId: "c2",
 					limit: 10
-				})).map(idOf)).not.toContain(idOf(claimed));
+				});
+				expect(again.map(idOf)).not.toContain(idOf(claimed));
 			});
 			it("`deadLetter: true` removes it from the pending stream", async ({ skip }) => {
 				if (!store.fail) return skip();
@@ -241,6 +255,82 @@ function runOutboxStoreContract(name, setup) {
 				expect((await store.getPending(10)).length).toBe(2);
 			});
 		});
+		/**
+		* `requeue`, `countByStatus` and `oldestPendingAgeMs` were a HOST's three extra
+		* methods before they were contract members — which is why they are pinned here.
+		* A dead-letter row an operator cannot re-drive, or a health number that lies, fails
+		* silently: the operator concludes the queue is fine, and the whole point of the
+		* table is that somebody eventually looks.
+		*/
+		describe("requeue", () => {
+			it("returns a dead-lettered event to pending and clears the attempt count", async ({ skip }) => {
+				if (!store.fail || !store.requeue) return skip();
+				const [e] = await seed(1);
+				const id = idOf(e);
+				await store.fail(id, { message: "fatal" }, { deadLetter: true });
+				expect((await store.getPending(10)).length).toBe(0);
+				expect(await store.requeue(id)).toBe(true);
+				const pending = await store.getPending(10);
+				expect(pending.length).toBe(1);
+				if (store.countByStatus) expect(await store.countByStatus("dead_letter")).toBe(0);
+			});
+			it("REFUSES a pending event — requeue is dead-letter-scoped", async ({ skip }) => {
+				if (!store.requeue) return skip();
+				const [e] = await seed(1);
+				expect(await store.requeue(idOf(e))).toBe(false);
+			});
+			it("is FALSE, not an error, for an unknown id", async ({ skip }) => {
+				if (!store.requeue) return skip();
+				expect(await store.requeue("no-such-event")).toBe(false);
+			});
+		});
+		describe("countByStatus", () => {
+			it("counts pending, and moves the count as events are delivered", async ({ skip }) => {
+				if (!store.countByStatus) return skip();
+				await seed(3);
+				expect(await store.countByStatus("pending")).toBe(3);
+				if (!store.claimPending) return skip();
+				const [claimed] = await store.claimPending({
+					consumerId: "c",
+					limit: 1,
+					leaseMs: 6e4
+				});
+				if (!claimed) return skip();
+				await store.acknowledge(idOf(claimed), { consumerId: "c" });
+				expect(await store.countByStatus("pending")).toBe(2);
+				expect(await store.countByStatus("delivered")).toBe(1);
+			});
+			it("counts dead-lettered rows — the number an alert fires on", async ({ skip }) => {
+				if (!store.countByStatus || !store.fail) return skip();
+				expect(await store.countByStatus("dead_letter")).toBe(0);
+				const [e] = await seed(1);
+				await store.fail(idOf(e), { message: "fatal" }, { deadLetter: true });
+				expect(await store.countByStatus("dead_letter")).toBe(1);
+			});
+		});
+		describe("oldestPendingAgeMs", () => {
+			it("is null on an empty queue, and a non-negative age once something pends", async ({ skip }) => {
+				if (!store.oldestPendingAgeMs) return skip();
+				expect(await store.oldestPendingAgeMs()).toBeNull();
+				await seed(1);
+				const age = await store.oldestPendingAgeMs();
+				expect(age).not.toBeNull();
+				expect(age ?? -1).toBeGreaterThanOrEqual(0);
+			});
+			it("ignores DELIVERED rows — it answers 'how long undelivered', not 'how old'", async ({ skip }) => {
+				if (!store.oldestPendingAgeMs) return skip();
+				if (!store.claimPending) return skip();
+				await seed(1);
+				const [claimed] = await store.claimPending({
+					consumerId: "c",
+					limit: 1,
+					leaseMs: 6e4
+				});
+				if (!claimed) return skip();
+				await store.acknowledge(idOf(claimed), { consumerId: "c" });
+				expect(await store.oldestPendingAgeMs()).toBeNull();
+			});
+		});
 	});
 }
 //#endregion

package/dist/testing/storageContract.d.mts

@@ -1,4 +1,5 @@
-import { t as Storage } from "../storage-DLUZ04kK.mjs";
+
+import { t as Storage } from "../storage-Cx9Sz3Ou.mjs";
 //#region src/testing/storageContract.d.ts
 interface StorageContractSetupResult {
   storage: Storage;

package/dist/testing/storageContract.mjs

@@ -1,3 +1,4 @@
+/*! @classytic/arc v2.32.0 | MIT | https://classytic.com */
 import { afterAll, beforeAll, describe, expect, it } from "vitest";
 //#region src/testing/storageContract.ts
 /**
@@ -88,7 +89,8 @@ function runStorageContract(name, setup) {
 				size: bytes.length
 			}, EMPTY_CTX);
 			const read = await storage.read(file.id, EMPTY_CTX);
-			expect((await readAll(read)).equals(bytes)).toBe(true);
+			const actual = await readAll(read);
+			expect(actual.equals(bytes)).toBe(true);
 			expect(read.contentType).toBe("application/octet-stream");
 			await storage.delete(file.id, EMPTY_CTX);
 		});
@@ -100,7 +102,8 @@ function runStorageContract(name, setup) {
 				mimeType: "application/octet-stream",
 				size: bytes.length
 			}, EMPTY_CTX);
-			expect(await storage.delete(file.id, EMPTY_CTX)).toBe(true);
+			const first = await storage.delete(file.id, EMPTY_CTX);
+			expect(first).toBe(true);
 			let second = "threw";
 			try {
 				second = await storage.delete(file.id, EMPTY_CTX);
@@ -168,8 +171,10 @@ function runStorageContract(name, setup) {
 				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);
+			const before = await readAll(await storage.read(file.id, EMPTY_CTX));
+			expect(before.equals(bytes)).toBe(true);
+			const removed = await storage.delete(file.id, EMPTY_CTX);
+			expect(removed).toBe(true);
 			let rejected = false;
 			try {
 				if (!(await readAll(await storage.read(file.id, EMPTY_CTX))).equals(bytes)) rejected = true;
@@ -188,7 +193,8 @@ function runStorageContract(name, setup) {
 			}, 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);
+			const actual = await readAll(result);
+			expect(actual.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 () => {

package/dist/{tracing-CsGKQJGg.d.mts → tracing-Dro5eH6j.d.mts}

@@ -1,3 +1,4 @@
+
 import { FastifyInstance, FastifyRequest } from "fastify";
 import { Span, Tracer } from "@opentelemetry/api";
 //#region src/plugins/tracing.d.ts

package/dist/{transactionContext-PNdoyLLm.mjs → transactionContext-BvLKvOIL.mjs}

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

package/dist/{typeGuards-C9KXUly6.mjs → typeGuards-B_5-hKjJ.mjs}

@@ -1,3 +1,4 @@
+/*! @classytic/arc v2.32.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,5 +1,6 @@
-import { $ as OpenApiSchemas, A as RequestIdOptions, At as RouteDefinition, Bt as RouteHandler, C as RequestContext, D as HealthCheck, Dt as ActionEntry, E as GracefulShutdownOptions, Et as ActionDefinition, F as FastifyWithDecorators, Ft as ControllerLike, G as OnTenantDeleteConfig, Gt as AuthenticatorContext, H as CrudController, Ht as AuthHelpers, I as MiddlewareHandler, It as FastifyHandler, J as PresetHook, K as ResolvedTenantPurge, Kt as JwtContext, L as RequestWithExtras, Lt as IController, M as EventsDecorator, Mt as RouteMethod, N as FastifyRequestExtras, Nt as RateLimitConfig, O as HealthOptions, Ot as ActionHandlerFn, P as FastifyWithAuth, Pt as ControllerHandler, Q as MiddlewareConfig, Rt as IControllerResponse, S as QueryParserInterface, T as CrudRouterOptions, Tt as ResourceCacheConfig, U as ResourceConfig, Ut as AuthPluginOptions, W as ResourcePermissions, Wt as Authenticator, 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, jt as RouteMcpConfig, k as IntrospectionPluginOptions, kn as BaseControllerOptions, 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, qt as TokenPair, 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, y as OwnershipCheck, zt as IRequestContext } from "../index-Q5gzEIWY.mjs";
-import { i as RequestScope } from "../types-DjC-KUCz.mjs";
-import { a as UserBase, d as JWTPayload, f as ObjectId, i as PermissionContext, l as AnyRecord, m as UserOrganization, n as DataPolicy, p as UserLike, r as PermissionCheck, t as AuthorizationDecision, u as ArcRequest } from "../types-ChvvVNP8.mjs";
-import { n as ElevationOptions, t as ElevationEvent } from "../elevation-C9s5hFP_.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, ObjectId, OnTenantDeleteConfig, OpenApiSchemas, OwnershipCheck, PaginationResult, ParsedQuery, PermissionCheck, PermissionContext, PopulateOption, PresetFunction, PresetHook, PresetResult, QueryParserInterface, RateLimitConfig, RegistryEntry, RegistryStats, RequestContext, RequestIdOptions, RequestScope, RequestWithExtras, ResolvedTenantPurge, ResourceCacheConfig, ResourceConfig, ResourceExtensions, ResourceHookContext, ResourceHooks, ResourceMetadata, ResourcePermissions, RouteDefinition, RouteHandler, RouteHandlerMethod, RouteMcpConfig, RouteMethod, RouteSchemaOptions, ServiceContext, TokenPair, TypedController, TypedRepository, TypedResourceConfig, UserBase, UserLike, UserOrganization, ValidateOptions, ValidationResult };
+
+import { $ as OpenApiSchemas, A as RequestIdOptions, An as BaseControllerOptions, At as RouteDefinition, Bt as RawRouteHandler, C as RequestContext, D as HealthCheck, Dt as ActionEntry, E as GracefulShutdownOptions, Et as ActionDefinition, F as FastifyWithDecorators, Ft as ControllerLike, G as OnTenantDeleteConfig, Gt as Authenticator, H as CrudController, I as MiddlewareHandler, It as FastifyHandler, J as PresetHook, Jt as TokenPair, K as ResolvedTenantPurge, Kt as AuthenticatorContext, L as RequestWithExtras, Lt as IController, M as EventsDecorator, Mt as RouteMethod, N as FastifyRequestExtras, Nt as RateLimitConfig, O as HealthOptions, Ot as ActionHandlerFn, P as FastifyWithAuth, Pt as ControllerHandler, Q as MiddlewareConfig, Rt as IControllerResponse, S as QueryParserInterface, T as CrudRouterOptions, Tt as ResourceCacheConfig, U as ResourceConfig, Ut as AuthHelpers, Vt as RouteHandler, W as ResourcePermissions, Wt as AuthPluginOptions, 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, jt as RouteMcpConfig, k as IntrospectionPluginOptions, 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, qt as JwtContext, 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, y as OwnershipCheck, zt as IRequestContext } from "../index-CpzxqePp.mjs";
+import { i as RequestScope } from "../types-ChuShpCP.mjs";
+import { a as UserBase, d as JWTPayload, f as ObjectId, i as PermissionContext, l as AnyRecord, m as UserOrganization, n as DataPolicy, p as UserLike, r as PermissionCheck, t as AuthorizationDecision, u as ArcRequest } from "../types-B7XeLEgK.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, 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, RouteDefinition, RouteHandler, RouteHandlerMethod, RouteMcpConfig, RouteMethod, RouteSchemaOptions, ServiceContext, TokenPair, TypedController, TypedRepository, TypedResourceConfig, UserBase, UserLike, UserOrganization, ValidateOptions, ValidationResult };

package/dist/types/index.mjs

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

package/dist/types/storage.d.mts

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

package/dist/types/storage.mjs

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

package/dist/{types-ChvvVNP8.d.mts → types-B7XeLEgK.d.mts}

@@ -1,4 +1,5 @@
-import { i as RequestScope } from "./types-DjC-KUCz.mjs";
+
+import { i as RequestScope } from "./types-ChuShpCP.mjs";
 import { FastifyRequest } from "fastify";
 //#region src/types/base.d.ts
 declare module "fastify" {
@@ -53,7 +54,7 @@ interface JWTPayload {
   [key: string]: unknown;
 }
 /**
- * Typed Fastify request with Arc decorations. Use in `raw: true` handlers
+ * Typed Fastify request with Arc decorations. Use in `rawHandler` routes
  * instead of `(req as any).user`.
  *
  * @example
@@ -241,8 +242,27 @@ type PermissionCheck<TDoc = Record<string, unknown>> = ((context: PermissionCont
 interface PermissionCheckMeta {
   /** Set by allowPublic() — marks the endpoint as publicly accessible */
   _isPublic?: boolean;
+  /**
+   * Set by requireAuth() — a pure identity gate (must be signed in) that adds NO
+   * row-level or environmental condition. Marked so `allOf` does not mistake it
+   * for an opaque runtime branch and needlessly taint the composite `conditional`.
+   */
+  _requiresAuth?: boolean;
   /** Set by requireRoles() — the roles required for access */
   _roles?: readonly string[];
+  /**
+   * Set by `requirePlatformRole()` — this gate consults PLATFORM roles only and
+   * can never be satisfied by an organization role.
+   *
+   * It exists because that property is otherwise unprovable from outside a
+   * check. `requireRoles(["ops"])` accepts an ORG role named `ops` by default,
+   * and `requireOrgRole("manager")` grants any org's manager — both return a
+   * bare allow with no policy, so a surface that must be platform-wide cannot
+   * tell them apart from a genuine operator gate by inspecting the decision.
+   * A global surface (see `jobsPlugin`'s `managementRoutes`) requires this
+   * marker at boot rather than trusting the caller's intent.
+   */
+  _platformOnly?: boolean;
   /** Set by requireOrgMembership() — org-level permission type */
   _orgPermission?: string;
   /** Set by requireOrgRole() — the org roles required for access */
@@ -290,6 +310,18 @@ interface PermissionCheckMeta {
     scopes?: readonly string[];
     dpop: boolean;
   };
+  /**
+   * Set by `allOf(...)` when its surfaced role/scope meta is NECESSARY but NOT
+   * SUFFICIENT — the conjunction also contains an opaque runtime branch
+   * (ownership / custom / dynamic / flow-mode / quota …) or a contradictory
+   * constraint that flat metadata can't capture. `describePermission` propagates
+   * it as `conditional: true`, so `explainAccess` reports a role/scope MATCH as
+   * `conditional` (server decides) instead of a definitive — and unsound —
+   * `allow`. A role/scope MISMATCH is still a definitive `deny` (a necessary
+   * condition failed). Without this flag a composed gate could tell a UI "you can"
+   * when the runtime check will refuse.
+   */
+  _conditional?: boolean;
 }
 //#endregion
 export { UserBase as a, normalizeRoles as c, JWTPayload as d, ObjectId as f, PermissionContext as i, AnyRecord as l, UserOrganization as m, DataPolicy as n, getUserId as o, UserLike as p, PermissionCheck as r, getUserRoles as s, AuthorizationDecision as t, ArcRequest as u };

package/dist/{types-Cc91nXuA.d.mts → types-ByHn9rEO.d.mts}

@@ -1,3 +1,4 @@
+
 import { FastifyRequest } from "fastify";
 //#region src/encryption/types.d.ts
 /** JWE key-management algorithm — the protected-header `alg`. */

package/dist/{types-C_ZZRcD6.d.mts → types-C4QE8qnm.d.mts}

@@ -1,3 +1,4 @@
+
 import { PurgeActor, PurgeEvidence, PurgeResourceResult, PurgeStrategyKind as PurgeStrategyKind$1, PurgeVerificationSummary } from "@classytic/primitives/retention";
 //#region src/cleanup/types.d.ts
 /** Ambient context every recipe method receives. Host-injected — never global. */

package/dist/{types-D_n8L6VY.d.mts → types-CT5vu6M0.d.mts}

@@ -1,5 +1,6 @@
-import { n as DomainEvent, r as EventHandler } from "./EventTransport-QmY7A258.mjs";
-import { n as ErrorMapper } from "./errorHandler-C6yv4ZTW.mjs";
+
+import { n as DomainEvent, r as EventHandler } from "./EventTransport-2uVV34WU.mjs";
+import { n as ErrorMapper } from "./errorHandler-CpYUJmPA.mjs";
 import { FastifyInstance, FastifyPluginAsync } from "fastify";
 import { LockAdapter } from "@classytic/repo-core/lock";
 //#region src/plugins/health.d.ts
@@ -319,6 +320,26 @@ interface LoadResourcesOptions<TContext = unknown> {
  */
 declare function loadResources<TContext = unknown>(dir: string, options?: LoadResourcesOptions<TContext>): Promise<ResourceLike[]>;
 //#endregion
+//#region src/factory/module/disposers.d.ts
+/** Teardown callback registered by a setup phase via `defer`. */
+type ModuleDisposer = () => void | Promise<void>;
+/**
+ * Second argument to a module's setup phases (`plugins`, `bootstrap`,
+ * `afterResources`).
+ */
+interface ModuleSetupContext {
+  /**
+   * Register a teardown callback for the resource just acquired. Call it
+   * IMMEDIATELY after acquisition — that is what makes partial-init teardown
+   * exact rather than defensive.
+   *
+   * Disposers run LIFO, after this module's `onClose`, on both the rollback
+   * and shutdown paths, and exactly once. A throwing disposer is logged and
+   * never blocks the ones behind it.
+   */
+  defer(disposer: ModuleDisposer): void;
+}
+//#endregion
 //#region src/factory/module/types.d.ts
 /**
  * A module's contribution of some arm (event handlers, scheduled jobs, …).
@@ -409,6 +430,13 @@ interface ArcModule<TExports = unknown> {
    * *importing* a dependent until its dependency is ready. Use a thunk to gate
    * whether a module is imported at all (region/tier packs); use `dependsOn`
    * to order modules that are already selected.
+   *
+   * **Convention: every HARD sibling dependency belongs here** — including
+   * ones read lazily. `lazyRequiredModuleExports` defers the export READ to
+   * first use (and eagerly validates the module is composed), but only
+   * `dependsOn` orders composition so the sibling's engine exists before
+   * yours initializes. Omit the edge only for genuinely optional
+   * integrations (`lazyModuleExports` / `getOptionalModuleExports`).
    */
   readonly dependsOn?: readonly string[];
   /**
@@ -422,8 +450,18 @@ interface ArcModule<TExports = unknown> {
    * published ecosystem packages: `plugins` = "register infra"; `bootstrap` =
    * "initialise engines (and return the public export)". Registering a plugin
    * inside `bootstrap` still works — this slot just makes the two distinct.
+   *
+   * Receives `{ defer }` to register teardown for anything it acquires, and
+   * may RETURN a single disposer as shorthand for the one-resource case:
+   *
+   * ```ts
+   * plugins: async (fastify) => {
+   *   const conn = await connect();
+   *   return () => conn.close();          // equivalent to defer(...)
+   * },
+   * ```
    */
-  plugins?: (fastify: FastifyInstance) => void | Promise<void>;
+  plugins?: (fastify: FastifyInstance, context: ModuleSetupContext) => ModuleDisposer | undefined | Promise<ModuleDisposer | undefined>;
   /**
    * Domain error mappers this module ships (see `defineErrorMapper`). Merged
    * into the app's error handler at boot, AFTER any host-declared mappers —
@@ -460,8 +498,23 @@ interface ArcModule<TExports = unknown> {
    * // arc-invoice bootstrap, composed AFTER arc-accounting:
    * const acct = getModuleExports<AccountingEngine>(fastify, "accounting");
    * ```
+   *
+   * The return value is the module's export, so teardown here goes through
+   * `defer` (the second argument) rather than a returned disposer — register
+   * each resource the moment it exists and partial-init cleanup becomes exact
+   * instead of a chain of `?.` guards:
+   *
+   * ```ts
+   * bootstrap: async (fastify, { defer }) => {
+   *   const client = await openClient();
+   *   defer(() => client.close());
+   *   const engine = await createEngine(client);   // if this throws, only
+   *   defer(() => engine.stop());                  // the client is released
+   *   return engine;
+   * },
+   * ```
    */
-  bootstrap?: (fastify: FastifyInstance) => TExports | Promise<TExports>;
+  bootstrap?: (fastify: FastifyInstance, context: ModuleSetupContext) => TExports | Promise<TExports>;
   /**
    * App-level resource NAMES this module authoritatively SUPERSEDES. When the
    * host also lists (or `resourceDir`-discovers) a resource of the same name,
@@ -476,17 +529,42 @@ interface ArcModule<TExports = unknown> {
    * Semantics:
    *   - Purely a supersede-the-app-fork switch — it filters the *app* resource
    *     list, never the module's own `resources` (those always register).
-   *   - Static + declarative: read at compose time, so it works regardless of
-   *     whether `resources` is an array or a post-bootstrap factory (no early
-   *     factory resolution, no boot-order coupling).
-   *   - Idempotent + tolerant: an `owns` entry with no matching app resource is
-   *     a silent no-op — a module may pre-declare a name before any fork exists.
+   *   - Idempotent + tolerant on the APP side: an `owns` entry with no matching
+   *     app resource is a silent no-op — a module may pre-declare a name before
+   *     any fork exists.
    *   - Collected across ALL modules; the app-side supersession is their union.
    *
-   * Contract: if you `owns` a name, PROVIDE it (in this module's `resources`).
-   * Dropping the app fork without supplying a replacement removes the route.
+   * **Prefer `owns: "provided"`** (2.32) — arc derives the list from the
+   * resources this module actually returned, so the claim and the reality
+   * cannot disagree:
+   *
+   * ```ts
+   * defineModule({ name: "order", owns: "provided", resources: () => [...] })
+   * ```
+   *
+   * That is the whole arm for most modules. Resources are resolved exactly
+   * once, names are validated (duplicates within a module are rejected), the
+   * effective `owns` is derived, and supersession runs afterward — one atomic
+   * phase arc owns, rather than a rule each module re-states.
+   *
+   * **The explicit-array form is ENFORCED at boot: if you `owns` a name,
+   * PROVIDE it** — in THIS module's own `resources`. Arc fails boot when a
+   * claimed name is not among them, naming the module, the unmet names, and
+   * what it did supply. Without that check, a typo or a resource deleted
+   * without updating the list booted "successfully" with the app's route
+   * silently removed and nothing serving it. Two real cases, both silent 404s:
+   * a POS module claiming a checkout resource it mounted only when the host
+   * supplied a pipeline, and a device gateway claiming a name it never
+   * provided at all.
+   *
+   * Keep the explicit array only when the list is genuinely NOT the module's
+   * own resource set — e.g. pre-declaring a name before the fork exists.
+   *
+   * A sibling module supplying the name does NOT satisfy the claim — ownership
+   * is local to the module that declares it, which is the colocation this arm
+   * exists for.
    */
-  readonly owns?: readonly string[];
+  readonly owns?: readonly string[] | "provided";
   /**
    * The module's resources. Array or factory — the factory form runs AFTER all
    * bootstraps, so `defineResource(...)` receives fully-booted engines. Flows
@@ -498,8 +576,12 @@ interface ArcModule<TExports = unknown> {
    * Post-registration wiring — runs in the `afterResources` phase, once this
    * module's routes are mounted. Use for cross-resource event subscriptions the
    * module owns.
+   *
+   * Receives `{ defer }`, and may return a disposer, on the same terms as
+   * `plugins` — handy for wiring that must be unwound (a subscription, a
+   * listener) without hoisting a handle into module scope.
    */
-  afterResources?: (fastify: FastifyInstance) => void | Promise<void>;
+  afterResources?: (fastify: FastifyInstance, context: ModuleSetupContext) => ModuleDisposer | undefined | Promise<ModuleDisposer | undefined>;
   /**
    * Readiness checks this module contributes to the app's
    * `healthPlugin` (`/_health/ready`). Collected across ALL modules in
@@ -569,9 +651,42 @@ interface ArcModule<TExports = unknown> {
    */
   readonly scheduledJobs?: ModuleContribution<ScheduleDefinition>;
   /**
-   * Teardown — registered as a Fastify `onClose` hook. Destroy engines, stop
-   * timers, flush the module's outbox. Modules close in REVERSE list order
-   * (last composed, first closed), mirroring init.
+   * Teardown — destroy engines, stop timers, flush the module's outbox.
+   * Modules close in REVERSE composition order (last composed, first closed),
+   * mirroring init, BEFORE the app-level `onClose` and before infra plugins'
+   * own close hooks (so teardown still sees a live DB/Redis).
+   *
+   * Boot is transactional: if any phase fails mid-boot — including THIS
+   * module's own `plugins`/`bootstrap` — arc immediately closes every module
+   * that entered an init phase, this closer included, in reverse order, then
+   * rethrows the original boot error. A closer runs AT MOST ONCE across the
+   * rollback and shutdown paths, and one throwing closer never blocks the
+   * rest (best-effort; failures are logged).
+   *
+   * Because rollback fires after a PARTIAL init — your `bootstrap` opened a
+   * client and threw on the next line, or your `plugins` ran but `bootstrap`
+   * never did — write closers defensively. Guard everything init may not have
+   * reached: `client?.close()`, not `client.close()`.
+   *
+   * ```ts
+   * let client: Client | undefined;
+   * defineModule({
+   *   name: "billing",
+   *   bootstrap: async () => {
+   *     client = await openClient();   // allocated…
+   *     await migrate(client);         // …and this may throw
+   *   },
+   *   onClose: async () => { await client?.close(); },  // still runs
+   * });
+   * ```
+   *
+   * Prefer `defer` (the setup phases' second argument) for anything acquired
+   * step-by-step: it registers each teardown at the point of acquisition, so
+   * the runtime knows exactly what was reached and the `?.` guards above
+   * disappear. `onClose` remains the right slot for tearing down what
+   * `bootstrap` RETURNED — the module's engine — and runs FIRST, ahead of the
+   * module's deferred disposers (see `disposers.ts` for the ordering rule).
+   * The two compose; either alone is complete.
    */
   onClose?: (fastify: FastifyInstance) => void | Promise<void>;
 }
@@ -618,4 +733,4 @@ type ArcModuleInput<TExports = unknown> = ArcModule<TExports> | Promise<ArcModul
  */
 interface ArcModuleRegistry {}
 //#endregion
-export { _default$1 as _, ModuleContribution as a, ResourceModule as c, ScheduleStats as d, SchedulesPluginOptions as f, HealthOptions as g, HealthCheck as h, EventHandlerDefinition as i, loadResources as l, schedulesPlugin as m, ArcModuleInput as n, LoadResourcesOptions as o, _default as p, ArcModuleRegistry as r, ResourceLike as s, ArcModule as t, ScheduleDefinition as u, healthPlugin as v };
+export { HealthCheck as _, ModuleContribution as a, healthPlugin as b, LoadResourcesOptions as c, loadResources as d, ScheduleDefinition as f, schedulesPlugin as g, _default as h, EventHandlerDefinition as i, ResourceLike as l, SchedulesPluginOptions as m, ArcModuleInput as n, ModuleDisposer as o, ScheduleStats as p, ArcModuleRegistry as r, ModuleSetupContext as s, ArcModule as t, ResourceModule as u, HealthOptions as v, _default$1 as y };

package/dist/{types-DjC-KUCz.d.mts → types-ChuShpCP.d.mts}

@@ -1,3 +1,4 @@
+
 //#region src/utils/headers.d.ts
 /**
  * Canonical header typing + accessor.