@classytic/arc 2.30.0 → 2.32.0

package/dist/fastify-augmentation-BppG5bMT.d.mts

@@ -0,0 +1,179 @@
+
+import { hn as HookSystem, z as ResourceRegistry } from "./index-CpzxqePp.mjs";
+import { t as ExternalOpenApiPaths } from "./externalPaths-CmGOxOtD.mjs";
+import { _ as HealthCheck, f as ScheduleDefinition, r as ArcModuleRegistry, t as ArcModule } from "./types-CT5vu6M0.mjs";
+import { s as ModuleState } from "./index-ZWhLTp_s.mjs";
+import { FastifyPluginAsync } from "fastify";
+//#region src/factory/module/descriptor.d.ts
+/**
+ * Resolved module introspection — what a module ACTUALLY composed to.
+ *
+ * `ArcModule` is the authoring shape: `resources` may be an array or a factory,
+ * `owns` may be a list or `"provided"`, and neither tells you what the module
+ * ended up mounting. Consumers that needed the resolved answer were reduced to
+ * inspecting that shape — a downstream conformance suite had to treat every
+ * resource FACTORY as a violation, because it could not distinguish "late-bound
+ * and legitimate" from "unresolvable", and so rejected valid modules.
+ *
+ * A descriptor is the resolved, read-only answer, published after arc has done
+ * the work exactly once. It lets tooling assert on the real graph without
+ * touching arc internals:
+ *
+ *   - conformance suites verify what a module provides and supersedes;
+ *   - `doctor` surfaces duplicate resources and unmet dependencies;
+ *   - tests assert the composed graph instead of re-deriving it;
+ *   - operators inspect a large installation;
+ *   - documentation generators read one stable contract.
+ *
+ * Deliberately DATA — no functions, no live handles. It survives
+ * `structuredClone`, so it can cross a worker boundary or be written to a file
+ * as-is, and holding one cannot keep a closed app alive.
+ */
+/** One resource as arc resolved it. */
+interface ResolvedResourceDescriptor {
+  /** Resource name; absent for an anonymous resource (participates in no dedup). */
+  readonly name?: string;
+  /** Route prefix, when the resource declared one. */
+  readonly prefix?: string;
+  /** Whether the resource opted out of the app-wide `resourcePrefix`. */
+  readonly skipGlobalPrefix: boolean;
+}
+/** Lifecycle surface a module ended up with — counts, not handles. */
+interface ResolvedModuleLifecycle {
+  /** Does the module tear anything down? */
+  readonly hasClose: boolean;
+  /** Event-handler subscriptions arc owns for this module. */
+  readonly subscriptions: number;
+  /** Recurring schedules contributed. */
+  readonly scheduledJobs: number;
+  /** Readiness checks contributed. */
+  readonly healthChecks: number;
+  /** Whether the module contributed a public export at `arc.modules[name]`. */
+  readonly exports: boolean;
+}
+/** The resolved, read-only description of one composed module. */
+interface ResolvedModuleDescriptor {
+  readonly name: string;
+  /** Declared composition edges, in the order the module listed them. */
+  readonly dependsOn: readonly string[];
+  /** Resources this module actually mounted, in registration order. */
+  readonly resources: readonly ResolvedResourceDescriptor[];
+  /**
+   * The EFFECTIVE supersession list — already derived when the module declared
+   * `owns: "provided"`, so callers never re-implement that resolution.
+   */
+  readonly owns: readonly string[];
+  readonly lifecycle: ResolvedModuleLifecycle;
+}
+/** Minimal resource shape the descriptor reads. Structural — matches `ResourceLike`. */
+interface DescribableResource {
+  readonly name?: string | undefined;
+  readonly prefix?: string | undefined;
+  readonly skipGlobalPrefix?: boolean | undefined;
+}
+/**
+ * Build a descriptor. Called by `registerResources` once per module, after
+ * resources are resolved and `owns` is effective.
+ *
+ * Frozen at every level: a descriptor is a snapshot of a completed decision,
+ * and a consumer mutating it would silently disagree with the running app.
+ */
+declare function describeResolvedModule(input: {
+  readonly name: string;
+  readonly dependsOn?: readonly string[] | undefined;
+  readonly resources: readonly DescribableResource[];
+  readonly owns: readonly string[];
+  readonly lifecycle: ResolvedModuleLifecycle;
+}): ResolvedModuleDescriptor;
+//#endregion
+//#region src/core/arcCorePlugin.d.ts
+interface ArcCorePluginOptions {
+  /** Enable event emission for CRUD operations (requires eventPlugin) */
+  emitEvents?: boolean;
+  /** Hook system instance (for testing/custom setup) */
+  hookSystem?: HookSystem;
+  /** Resource registry instance (for testing/custom setup) */
+  registry?: ResourceRegistry;
+}
+interface PluginMeta {
+  name: string;
+  version?: string;
+  options?: Record<string, unknown>;
+  registeredAt: string;
+}
+interface ArcCore {
+  /** Instance-scoped hook system */
+  hooks: HookSystem;
+  /** Instance-scoped resource registry */
+  registry: ResourceRegistry;
+  /** Whether event emission is enabled */
+  emitEvents: boolean;
+  /** External OpenAPI paths contributed by auth adapters or third-party integrations */
+  externalOpenApiPaths: ExternalOpenApiPaths[];
+  /** Registered plugins for introspection */
+  plugins: Map<string, PluginMeta>;
+  /**
+   * Module public exports — `bootstrap()` return values keyed by module name
+   * (see `src/factory/module.ts`). Read via `getModuleExports(fastify, name)`:
+   * augment `ArcModuleRegistry` once and the name infers the export type;
+   * otherwise pass it inline. `Partial<ArcModuleRegistry>` gives augmented
+   * apps typed direct access (`fastify.arc.modules.order`), while the
+   * `Record<string, unknown>` intersection keeps un-augmented reads open.
+   * Populated lazily by `registerResources` — absent until a module exports.
+   */
+  modules?: Partial<ArcModuleRegistry> & Record<string, unknown>;
+  /**
+   * Lifecycle state per composed module (null-proto map, populated by
+   * `registerResources` the moment the graph is validated — so it answers
+   * "is this module composed?" even for resource-only modules that never
+   * record an export). Read via `hasModule(fastify, name)` /
+   * `getModuleState(fastify, name)`; the map itself is internal.
+   */
+  moduleStates?: Record<string, ModuleState>;
+  /**
+   * Module-contributed readiness checks, collected in dependency order and
+   * frozen by `createApp`. The API role merges these into its `healthPlugin`;
+   * `createWorker` reads this to give its probe listener the identical union
+   * (the worker preset disables the main health plugin, so this is how module
+   * checks reach the probe without a double registration). Empty until
+   * `createApp` populates it.
+   */
+  healthChecks?: readonly HealthCheck[];
+  /**
+   * The resolved, dependency-ordered module definitions (frozen by createApp).
+   * Integrations that collect a module arm at their OWN init time — e.g. the
+   * streamline integration calling `collectModuleWorkflows(fastify, defs)` after
+   * it has created + decorated its container — read the list from here. Empty
+   * until createApp populates it.
+   */
+  moduleDefinitions?: readonly ArcModule[];
+  /**
+   * RESOLVED module descriptors — what each module actually composed to
+   * (resources mounted, effective `owns`, lifecycle counts), published once
+   * boot has settled them.
+   *
+   * Read this rather than `moduleDefinitions` for anything that needs the real
+   * graph: a definition's `resources` may still be an unresolved factory and
+   * its `owns` may be `"provided"`, so the authoring shape cannot answer "what
+   * did this module actually mount?". Frozen, plain data — safe to clone, log,
+   * or hand to tooling.
+   */
+  moduleDescriptors?: readonly ResolvedModuleDescriptor[];
+  /**
+   * Module-contributed recurring schedules, resolved once in dependency order
+   * and frozen after bootstraps. The same definitions are executed by Arc's
+   * schedules plugin and exposed here for introspection. Empty until collection.
+   */
+  scheduledJobs?: readonly Readonly<ScheduleDefinition>[];
+}
+declare const arcCorePlugin: FastifyPluginAsync<ArcCorePluginOptions>;
+declare const _default: FastifyPluginAsync<ArcCorePluginOptions>;
+//#endregion
+//#region src/types/fastify-augmentation.d.ts
+declare module "fastify" {
+  interface FastifyInstance {
+    arc?: ArcCore;
+  }
+}
+//#endregion
+export { arcCorePlugin as a, ResolvedResourceDescriptor as c, _default as i, describeResolvedModule as l, ArcCorePluginOptions as n, ResolvedModuleDescriptor as o, PluginMeta as r, ResolvedModuleLifecycle as s, ArcCore as t };

package/dist/{fields-CQ_7KQWw.mjs → fields-DEi65pGj.mjs}

@@ -1,3 +1,4 @@
+/*! @classytic/arc v2.32.0 | MIT | https://classytic.com */
 //#region src/permissions/fields.ts
 /**
 * Field-Level Permissions
@@ -110,10 +111,7 @@ function applyFieldReadPermissions(data, fieldPermissions, userRoles) {
 		case "visibleTo":
 			if (!perm.roles?.some((r) => userRoles.includes(r))) delete result[field];
 			break;
-		case "redactFor":
-			if (perm.roles?.some((r) => userRoles.includes(r))) result[field] = perm.redactValue ?? "***";
-			break;
-		case "writableBy": break;
+		case "redactFor": if (perm.roles?.some((r) => userRoles.includes(r))) result[field] = perm.redactValue ?? "***";
 	}
 	return result;
 }
@@ -139,12 +137,10 @@ function applyFieldWritePermissions(body, fieldPermissions, userRoles) {
 				delete result[field];
 			}
 			break;
-		case "writableBy":
-			if (field in result && !perm.roles?.some((r) => userRoles.includes(r))) {
-				deniedFields.push(field);
-				delete result[field];
-			}
-			break;
+		case "writableBy": if (field in result && !perm.roles?.some((r) => userRoles.includes(r))) {
+			deniedFields.push(field);
+			delete result[field];
+		}
 	}
 	return {
 		body: result,

package/dist/{fields-D3lhgzhD.d.mts → fields-I_EeRWND.d.mts}

@@ -1,3 +1,4 @@
+
 //#region src/permissions/fields.d.ts
 /**
  * Field-Level Permissions

package/dist/{generate-D0wZupBg.mjs → generate-CRSG0jTv.mjs}

@@ -1,4 +1,5 @@
-import { t as pluralize } from "./pluralize-BhrgwZb9.mjs";
+/*! @classytic/arc v2.32.0 | MIT | https://classytic.com */
+import { t as pluralize } from "./pluralize-C2ZkKbsn.mjs";
 import { join } from "node:path";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 //#region src/cli/commands/generate/name-helpers.ts

package/dist/{generate-BnsL9GBm.d.mts → generate-DCGuEbqI.d.mts}

@@ -1,3 +1,4 @@
+
 //#region src/cli/commands/generate/index.d.ts
 /**
  * `arc generate` orchestrator.

package/dist/{headers-BvlQSDMB.mjs → headers-BXjQYbeC.mjs}

@@ -1,4 +1,5 @@
-import { u as ValidationError } from "./errors-DkO8Nk6-.mjs";
+/*! @classytic/arc v2.32.0 | MIT | https://classytic.com */
+import { u as ValidationError } from "./errors-Bh1KK5ps.mjs";
 //#region src/utils/headers.ts
 /**
 * Canonical header typing + accessor.

package/dist/{health-CB_m4S32.mjs → health-5XnTa2uo.mjs}

@@ -1,3 +1,4 @@
+/*! @classytic/arc v2.32.0 | MIT | https://classytic.com */
 import { randomUUID } from "node:crypto";
 import fp from "fastify-plugin";
 //#region src/plugins/requestId.ts

package/dist/hooks/index.d.mts

@@ -1,2 +1,3 @@
-import { Cn as defineHook, Sn as createHookSystem, _n as afterDelete, bn as beforeDelete, cn as DefineHookOptions, dn as HookOperation, fn as HookPhase, gn as afterCreate, hn as HookSystemOptions, ln as HookContext, mn as HookSystem, pn as HookRegistration, un as HookHandler, vn as afterUpdate, xn as beforeUpdate, yn as beforeCreate } from "../index-Q5gzEIWY.mjs";
+
+import { Cn as createHookSystem, Sn as beforeUpdate, _n as afterCreate, bn as beforeCreate, dn as HookHandler, fn as HookOperation, gn as HookSystemOptions, hn as HookSystem, ln as DefineHookOptions, mn as HookRegistration, pn as HookPhase, un as HookContext, vn as afterDelete, wn as defineHook, xn as beforeDelete, yn as afterUpdate } from "../index-CpzxqePp.mjs";
 export { type DefineHookOptions, type HookContext, type HookHandler, type HookOperation, type HookPhase, type HookRegistration, HookSystem, type HookSystemOptions, afterCreate, afterDelete, afterUpdate, beforeCreate, beforeDelete, beforeUpdate, createHookSystem, defineHook };

package/dist/hooks/index.mjs

@@ -1,2 +1,3 @@
-import { a as beforeCreate, c as createHookSystem, i as afterUpdate, l as defineHook, n as afterCreate, o as beforeDelete, r as afterDelete, s as beforeUpdate, t as HookSystem } from "../HookSystem-WkIougo6.mjs";
+/*! @classytic/arc v2.32.0 | MIT | https://classytic.com */
+import { a as beforeCreate, c as createHookSystem, i as afterUpdate, l as defineHook, n as afterCreate, o as beforeDelete, r as afterDelete, s as beforeUpdate, t as HookSystem } from "../HookSystem-vimw5D7Z.mjs";
 export { HookSystem, afterCreate, afterDelete, afterUpdate, beforeCreate, beforeDelete, beforeUpdate, createHookSystem, defineHook };

package/dist/idempotency/index.d.mts

@@ -1,5 +1,6 @@
-import { i as createIdempotencyResult, n as IdempotencyResult, r as IdempotencyStore, t as IdempotencyLock } from "../interface-Uk8ONJv7.mjs";
-import { i as RedisIdempotencyStoreOptions, n as RedisClient } from "../redis-UDtLaNj6.mjs";
+
+import { i as createIdempotencyResult, n as IdempotencyResult, r as IdempotencyStore, t as IdempotencyLock } from "../interface-DEWNOMza.mjs";
+import { i as RedisIdempotencyStoreOptions, n as RedisClient } from "../redis-CduhKsJi.mjs";
 import { FastifyPluginAsync } from "fastify";
 import { RepositoryLike } from "@classytic/repo-core/adapter";
 //#region src/idempotency/idempotencyPlugin.d.ts

package/dist/idempotency/index.mjs

@@ -1,6 +1,7 @@
-import { n as requireSingleHeaderValue } from "../headers-BvlQSDMB.mjs";
-import { n as createSafeGetOne, t as createIsDuplicateKeyError } from "../store-helpers-DY6xq4sM.mjs";
-import { t as createIdempotencyResult } from "../interface-n5hpKg1d.mjs";
+/*! @classytic/arc v2.32.0 | MIT | https://classytic.com */
+import { n as requireSingleHeaderValue } from "../headers-BXjQYbeC.mjs";
+import { n as createSafeGetOne, t as createIsDuplicateKeyError } from "../store-helpers-DmEMHlPQ.mjs";
+import { t as createIdempotencyResult } from "../interface-BP4IJCBO.mjs";
 import { and, eq, exists, gt, lt, or, startsWith } from "@classytic/repo-core/filter";
 import { createHash } from "node:crypto";
 import fp from "fastify-plugin";
@@ -137,8 +138,10 @@ var MemoryIdempotencyStore = class {
 	}
 	async tryLock(key, requestId, ttlMs) {
 		const existing = this.locks.get(key);
-		if (existing) if (/* @__PURE__ */ new Date() > existing.expiresAt) this.locks.delete(key);
-		else return false;
+		if (existing) {
+			if (/* @__PURE__ */ new Date() > existing.expiresAt) this.locks.delete(key);
+			else return false;
+		}
 		this.locks.set(key, {
 			key,
 			requestId,

package/dist/idempotency/redis.d.mts

@@ -1,2 +1,3 @@
-import { a as UpstashRedisLike, i as RedisIdempotencyStoreOptions, n as RedisClient, o as ioredisAsIdempotencyClient, r as RedisIdempotencyStore, s as upstashAsIdempotencyClient, t as IoredisLike } from "../redis-UDtLaNj6.mjs";
+
+import { a as UpstashRedisLike, i as RedisIdempotencyStoreOptions, n as RedisClient, o as ioredisAsIdempotencyClient, r as RedisIdempotencyStore, s as upstashAsIdempotencyClient, t as IoredisLike } from "../redis-CduhKsJi.mjs";
 export { type IoredisLike, type RedisClient, RedisIdempotencyStore, type RedisIdempotencyStoreOptions, type UpstashRedisLike, ioredisAsIdempotencyClient, upstashAsIdempotencyClient };

package/dist/idempotency/redis.mjs

@@ -1,3 +1,4 @@
+/*! @classytic/arc v2.32.0 | MIT | https://classytic.com */
 //#region src/idempotency/stores/redis.ts
 var RedisIdempotencyStore = class {
 	name = "redis";

package/dist/{index-CG4yqMDB.d.mts → index-C-481Zf2.d.mts}

@@ -1,3 +1,5 @@
+
+import { r as PermissionCheck } from "./types-B7XeLEgK.mjs";
 import { FastifyPluginAsync } from "fastify";
 //#region src/integrations/jobs/execution.d.ts
 /**
@@ -43,18 +45,6 @@ interface ExecuteTimedHandlerOptions<T> {
 declare function executeTimedHandler<T>(options: ExecuteTimedHandlerOptions<T>): Promise<T>;
 //#endregion
 //#region src/integrations/jobs/types.d.ts
-/**
- * Job queue integration — public contract (definitions, meta, dispatcher).
- *
- * Directory map (mechanical split of the former single file):
- *   types.ts     — this contract + `defineJob`
- *   execution.ts — `executeTimedHandler` (timeout / cancellation / bulkhead)
- *   repeat.ts    — repeatable-schedule reconciliation (boot hygiene)
- *   plugin.ts    — BullMQ wiring (queues, workers, DLQ, routes, shutdown)
- *   index.ts     — public barrel; `src/integrations/jobs.ts` re-exports it
- *                  so the package subpath is unchanged
- */
-/** Repeat schedule — cron pattern or fixed interval. Explicit timezone is required. */
 interface JobRepeatOptions {
   /** Cron pattern (e.g. '0 9 * * *' = every day 09:00). Mutually exclusive with `every`. */
   pattern?: string;
@@ -177,6 +167,61 @@ interface JobsPluginOptions {
   jobs: JobDefinition[];
   /** URL prefix for job management endpoints (default: '/jobs') */
   prefix?: string;
+  /**
+   * Job management HTTP endpoints (`GET <prefix>/stats`,
+   * `GET <prefix>/:queue/:id/status`).
+   *
+   * **Disabled by default.** A job status carries `returnValue` and
+   * `failedReason` — the handler's own output and error text, which routinely
+   * hold export URLs, billing results, model output, recipient addresses, or
+   * internal stack detail. Serving that unauthenticated turns a job id into a
+   * read primitive over other tenants' work.
+   *
+   * Enable it deliberately, with a permission check:
+   *
+   * ```ts
+   * managementRoutes: { operatorPermission: requireRoles(["platform-ops"]) }
+   * ```
+   *
+   * Queue-level counts are also available through the metrics/health
+   * integration, which does not expose individual jobs.
+   */
+  managementRoutes?: false | {
+    /**
+     * REQUIRED — arc will not mount an unguarded management surface.
+     *
+     * **This is an OPERATOR surface, not a tenant-facing one.** A BullMQ job
+     * carries no framework-level tenant identity, and `getStatus` fetches
+     * straight by queue + id, so a row-level `policy` on the decision has
+     * nothing to filter: `requireOrgRole("manager")` would let a manager in
+     * org A read a known job handle from org B. `/stats` is inherently
+     * global for the same reason.
+     *
+     * Gate it on an operator role — `requireRoles(["platform-ops"])` — and
+     * keep tenant-facing job status in a resource that owns its own row
+     * policy. Arc REFUSES a request whose decision carries a `policy`
+     * rather than silently ignoring it.
+     */
+    operatorPermission: PermissionCheck;
+    /**
+     * Accept an `operatorPermission` that arc cannot prove is platform-only.
+     *
+     * By default the gate must carry `_platformOnly` (i.e. come from
+     * `requirePlatformRole`), because that property is unprovable from
+     * outside: `requireOrgRole("manager")` and the default
+     * `requireRoles(["ops"])` both return a bare allow with no policy, so a
+     * manager in org A passes and reads a known handle from org B. Boot fails
+     * rather than serving a surface whose guard reads as tenant-scoped.
+     *
+     * Set this only for a custom check you have verified consults platform
+     * identity alone.
+     */
+    allowUnverifiedOperatorPermission?: boolean;
+    /** Include the handler's return value in a status response. Default `false`. */
+    exposeResult?: boolean;
+    /** Include `failedReason` in a status response. Default `false`. */
+    exposeFailureReason?: boolean;
+  };
   /** Bridge job events to Arc's event bus (default: true) */
   bridgeEvents?: boolean;
   /** Default job options applied to all jobs */
@@ -192,19 +237,30 @@ interface JobsPluginOptions {
   };
 }
 interface JobDispatcher {
-  dispatch<TData = unknown>(name: string, data: TData, options?: JobDispatchOptions): Promise<{
-    jobId: string;
-  }>;
+  dispatch<TData = unknown>(name: string, data: TData, options?: JobDispatchOptions): Promise<JobHandle>;
   getQueue(name: string): unknown | null;
   getStats(): Promise<Record<string, QueueStats>>;
   /**
    * Fetch a point-in-time status snapshot for a job by its ID.
-   * Searches across all registered queues.
-   * Returns `null` if the job doesn't exist or has been removed by retention policy.
+   * QUEUE-QUALIFIED: BullMQ job ids are local to their queue, so an id alone
+   * cannot identify a job. `dispatch()` returns the queue name alongside the id
+   * for exactly this reason.
+   *
+   * Returns `null` if the queue is not registered, or the job doesn't exist /
+   * has been removed by retention policy.
    */
-  getStatus(jobId: string): Promise<JobStatus | null>;
+  getStatus(queue: string, jobId: string): Promise<JobStatus | null>;
   close(): Promise<void>;
 }
+/**
+ * A dispatched job's address. The queue is part of the identity because BullMQ
+ * ids are queue-local — two queues can both hold `"123"`.
+ */
+interface JobHandle {
+  /** Registered job name (= queue name). */
+  queue: string;
+  jobId: string;
+}
 interface QueueStats {
   waiting: number;
   active: number;