@classytic/arc 2.31.0 → 2.33.0

package/dist/{types-CBgvkp8O.d.mts → types-BcTumAz_.d.mts}

@@ -1,6 +1,6 @@
 
-import { n as DomainEvent, r as EventHandler } from "./EventTransport-2uVV34WU.mjs";
-import { n as ErrorMapper } from "./errorHandler-CpYUJmPA.mjs";
+import { n as DomainEvent, r as EventHandler } from "./EventTransport-BEVP50ka.mjs";
+import { n as ErrorMapper } from "./errorHandler-DI5AN2b5.mjs";
 import { FastifyInstance, FastifyPluginAsync } from "fastify";
 import { LockAdapter } from "@classytic/repo-core/lock";
 //#region src/plugins/health.d.ts
@@ -49,6 +49,12 @@ interface ScheduleDefinition {
   handler: (fastify: FastifyInstance) => void | Promise<void>;
   /** Fire once immediately when the app becomes ready (default: false). */
   runOnStart?: boolean;
+  /**
+   * Topology tag: `'relay'` marks an arm a `role: 'relay'` process runs
+   * (outbox relays); everything else is `'job'` (default). See
+   * `CreateAppOptions.role`.
+   */
+  kind?: "relay" | "job";
   /**
    * Random extra delay in `[0, jitterMs)` added to the FIRST tick only.
    * Spreads boot-aligned jobs so multiple same-cadence schedules don't all
@@ -320,6 +326,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, …).
@@ -420,18 +446,56 @@ interface ArcModule<TExports = unknown> {
    */
   readonly dependsOn?: readonly string[];
   /**
-   * Fastify plugins / decorators this module needs — the module-level analog
-   * of the app's `plugins()` slot. Runs in the plugins phase: AFTER the app's
-   * own `plugins()` (so module infra can build on app foundations like a DB
-   * connection) and in `dependsOn` order, but BEFORE any module `bootstrap` —
-   * so engines initialised in `bootstrap` can rely on what's registered here.
+   * Infra SETUP function — the module-level analog of the app's `plugins()`
+   * slot. Runs in the plugins phase: AFTER the app's own `plugins()` (so
+   * module infra can build on app foundations like a DB connection) and in
+   * `dependsOn` order, but BEFORE any module `bootstrap` — so engines
+   * initialised in `bootstrap` can rely on what's registered here.
+   *
+   * ## ⚠ This is NOT itself a Fastify plugin
+   *
+   * Despite the name, arc CALLS this function directly — it is never handed
+   * to `fastify.register()`. Two consequences, both of which bite module
+   * authors coming from ordinary Fastify plugins:
+   *
+   *   - **You must register plugins yourself.** `await fastify.register(x)`,
+   *     not `return x`. A returned function is read as a DISPOSER (below),
+   *     so returning a plugin silently registers nothing and then invokes
+   *     your plugin as a teardown callback. Arc detects the `fastify-plugin`
+   *     case and throws; the bare-function case warns.
+   *   - **There is no encapsulation and no prefix here.** Decorators and
+   *     hooks you add land on the instance arc passes you — the same
+   *     instance every other module sees. Fastify's encapsulation applies
+   *     only inside a `register()` call you make yourself. See
+   *     https://fastify.dev/docs/latest/Reference/Plugins/
+   *
+   * ```ts
+   * plugins: async (fastify) => {
+   *   await fastify.register(somePlugin, { prefix: '/x' });  // ✅ register
+   *   fastify.decorate('thing', thing);                      // ✅ root-visible
+   *   // return somePlugin                                   // ❌ never registered
+   * },
+   * ```
+   *
+   * The name is kept for the 2.x line; v3 renames the slot to `setup` and
+   * REMOVES `plugins` outright — v3 ships no compatibility aliases (v3.md).
    *
    * Separating this from `bootstrap` keeps lifecycle intent explicit for
    * 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 —
@@ -468,8 +532,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,
@@ -489,18 +568,37 @@ interface ArcModule<TExports = unknown> {
    *     any fork exists.
    *   - Collected across ALL modules; the app-side supersession is their union.
    *
-   * **Contract (ENFORCED at boot): if you `owns` a name, PROVIDE it** — in
-   * THIS module's own `resources`. Arc resolves module resources first and
-   * 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 `owns` booted "successfully" with the
-   * app's route silently removed and nothing serving it.
+   * **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
@@ -512,8 +610,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
@@ -611,6 +713,14 @@ interface ArcModule<TExports = unknown> {
    *   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>;
 }
@@ -657,4 +767,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-CwcUQ610.d.mts → types-BfC83KsP.d.mts}

@@ -1,5 +1,5 @@
 
-import { V as ResourceDefinition } from "./index-CpzxqePp.mjs";
+import { V as ResourceDefinition } from "./index-BcR2bFZQ.mjs";
 import { z } from "zod";
 //#region src/integrations/mcp/types.d.ts
 /** Behavioral hints for MCP clients (tool annotations per MCP spec) */
@@ -377,6 +377,20 @@ interface McpAuthResult {
    * Carried on the `service` RequestScope for fine-grained permission checks.
    */
   scopes?: readonly string[];
+  /**
+   * Active team — carried onto a `member` scope so `getTeamId()` answers the
+   * same on MCP as on HTTP. Member-only, like the HTTP surface.
+   */
+  teamId?: string;
+  /**
+   * Host-defined scope dimensions (`branchId`, `projectId`, `region`, …),
+   * carried onto `member` / `service` scopes.
+   *
+   * Declared explicitly because `requireScopeContext()` AUTHORISES against
+   * these: a resource gated on `branchId` denies every MCP call until the
+   * resolver supplies it. Non-string entries are dropped rather than coerced.
+   */
+  context?: Record<string, string>;
   /** Any extra metadata from the auth resolver */
   [key: string]: unknown;
 }

package/dist/{types-Cys0ko9Z.mjs → types-CoqIRrkY.mjs}

@@ -1,7 +1,7 @@
-/*! @classytic/arc v2.31.0 | MIT | https://classytic.com */
-import { l as UnauthorizedError, o as OrgRequiredError } from "./errors-Cj42AntO.mjs";
-import { n as requireSingleHeaderValue } from "./headers-3zvE0rM3.mjs";
-import { t as getUserId$1 } from "./userHelpers-ChYJ6CdK.mjs";
+/*! @classytic/arc v2.34.0 | MIT | https://classytic.com */
+import { l as UnauthorizedError, o as OrgRequiredError } from "./errors-Cd_yy7aW.mjs";
+import { n as requireSingleHeaderValue } from "./headers-CveNO9gR.mjs";
+import { t as getUserId$1 } from "./userHelpers-CWF5pbZD.mjs";
 //#region src/scope/types.ts
 /**
 * Request Scope — The One Standard

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

@@ -40,6 +40,18 @@ interface CleanupExecutionContext extends CleanupContext {
    * commits, call this so the executor learns of a cancel request promptly.
    */
   onStep(step: CleanupStepResult): Promise<void>;
+  /**
+   * Report a STEP LIFECYCLE transition — running / completed / skipped / failed.
+   *
+   * Separate from {@link onStep}, which reports a committed CHUNK and drives the
+   * aggregate counters. Folding both into one call would double-count `steps`
+   * and conflate "a batch landed" with "this phase is now done" — two different
+   * facts an operator reads differently.
+   *
+   * OPTIONAL on the context so a recipe that does not model discrete steps is
+   * unaffected; `recipeFromSteps` drives it for every composed recipe.
+   */
+  onStepState?(state: CleanupStepProgress): Promise<void>;
   /**
    * Throw `CleanupCancelled` if a cancel has been requested for this run. Cheap
    * to call between chunks; backed by the durable `cancelRequested` flag (the
@@ -56,13 +68,72 @@ interface Availability {
 /** Operator-supplied recipe parameters (branch, module set, before-date, …). */
 interface CleanupInput {
   readonly parameters?: Readonly<Record<string, unknown>> | undefined;
+  /**
+   * Step ids the operator chose to LEAVE OUT of this run.
+   *
+   * The obvious shape for this is a free-text ignore-list, which carries one
+   * dangerous gap: anything can be ignored, including the checks. Here a step
+   * that PROTECTS is not excludable — see
+   * {@link CleanupPlanItem.excluded} — because being able to switch off the
+   * thing standing between you and a statutory record makes the guard advisory.
+   * An unknown or unexcludable id REFUSES the plan rather than being dropped: a
+   * silently-ignored exclusion is an operator believing they narrowed a
+   * destructive run when they did not.
+   *
+   * SEALED INTO THE DIGEST. The exclusion set is part of what was consented to,
+   * so a plan previewed with accounting excluded cannot be executed as one that
+   * includes it.
+   *
+   * Framework-level and deliberately NOT smuggled through `parameters`:
+   * parameters are the recipe's domain scope, this is the composition.
+   */
+  readonly excludeSteps?: readonly string[] | undefined;
 }
+/**
+ * What a line's `estimated` COUNTS. Absent ⇒ `'remove'`, so every existing
+ * recipe keeps its meaning.
+ *
+ * A protective guard step reports the records it DEFENDS, not records it would
+ * touch — and summing those into a "records to remove" headline overstates the
+ * damage by exactly the protected count. That is not cosmetic: a pre-live reset
+ * showed **540 records to remove** when 173 of them were posted journal entries
+ * the run would refuse to touch. The number was plausible, internally
+ * consistent, and wrong — this codebase's signature failure, in the one place an
+ * operator reads before authorising a destructive act.
+ *
+ * The count cannot be inferred from `blockers`: a guard that finds nothing still
+ * reports zero protected records, and a REMOVING line can carry a blocker too.
+ * The line has to say which quantity it is.
+ */
+type CleanupPlanItemDisposition = "remove" | "protect" | "rebuild";
 /** One logical line in the preview — a business record class, never a collection. */
 interface CleanupPlanItem {
+  /**
+   * The contributing step, when the recipe is composed from steps.
+   *
+   * Without it the exclusion list is enforceable but not DISCOVERABLE: a UI
+   * showing `resource` labels has no id to send, so the capability exists and
+   * nothing can reach it. Absent for a recipe that is not step-composed.
+   */
+  readonly stepId?: string | undefined;
   /** Logical module / resource label, e.g. `'orders'`, `'journal entries'`. */
   readonly resource: string;
   /** Estimated records affected. */
   readonly estimated: number;
+  /**
+   * Whether `estimated` counts records this line REMOVES, PROTECTS, or REBUILDS.
+   * Defaults to `'remove'` — only a line that does something else must say so.
+   */
+  readonly disposition?: CleanupPlanItemDisposition | undefined;
+  /**
+   * The operator excluded this line from the run.
+   *
+   * It still appears in the plan — showing what was left out is the point; a
+   * line that vanishes is indistinguishable from one that was never in scope.
+   * Its `estimated` is kept out of both totals, and at execute time the step is
+   * reported `skipped` with the reason rather than silently not run.
+   */
+  readonly excluded?: boolean | undefined;
   /** What is retained for this line (e.g. `'measures kept, PII redacted'`). */
   readonly retained?: string | undefined;
   /** Domain blockers preventing this line (e.g. `'OPEN_TRANSFER'`). */
@@ -101,7 +172,26 @@ interface CleanupPlan {
   readonly blockers: readonly string[];
   readonly rebuildActions: readonly string[];
   readonly warnings: readonly string[];
+  /**
+   * Records this plan would REMOVE — the headline an operator authorises against.
+   *
+   * Counts only `disposition: 'remove'` lines. It used to sum every line, so a
+   * protective guard's count landed in the removal total (see
+   * {@link CleanupPlanItemDisposition}).
+   */
   readonly estimatedTotal: number;
+  /**
+   * Records a guard step is DEFENDING in this plan, reported separately so it
+   * can be shown as reassurance rather than as damage. Zero when no line
+   * protects anything.
+   */
+  readonly protectedTotal: number;
+  /**
+   * Step ids the operator left out, SEALED.  re-resolves from here,
+   * never from a fresh caller input, so a run cannot be widened past what was
+   * previewed and confirmed.
+   */
+  readonly excludeSteps: readonly string[];
   readonly confirmationPhrase: string;
   /** Deterministic checksum of the plan's material content — see `computePlanDigest`. */
   readonly digest: string;
@@ -122,11 +212,64 @@ interface CleanupStepResult {
  * fixed-size aggregate, never an unbounded per-chunk array. Detailed steps, if a
  * host wants them, go to a separate capped sink — not this document.
  */
+/**
+ * One step's lifecycle within a run.
+ *
+ * `skipped` and `failed` are DISTINCT from each other and from `completed`,
+ * because collapsing them is what makes a long destructive run unreadable: an
+ * operator watching "1,204 processed" cannot tell whether accounting ran, was
+ * deliberately not applicable, or blew up and left the rest half-done.
+ */
+type CleanupStepRunStatus = "pending" | "running" | "completed" | "skipped" | "failed";
+/**
+ * Per-step progress — the readable half of a run.
+ *
+ * The conventional shape is one FIXED COLUMN per phase, each holding
+ * `Pending | Completed | Skipped`. That works for a fixed pipeline and breaks
+ * the moment the pipeline is composed: adding a phase means a schema migration,
+ * and a recipe assembled from contributed steps has no fixed phase list at all.
+ *
+ * So this is a bounded LIST keyed by step id rather than columns. Two further
+ * properties, both deliberate:
+ *
+ *   - a `Skipped` with no reason is unreadable — "nothing to do" and
+ *     "deliberately excluded" are opposite facts, and a bare status enum cannot
+ *     tell them apart. {@link detail} is REQUIRED for `skipped` and `failed`.
+ *   - per-step `processed` and timings, so a stalled step is visible while it is
+ *     still running instead of after the run ends.
+ *
+ * Bounded by construction: one entry per step in the SEALED plan, and the plan
+ * is already capped at `maxPlanItems`. This is not the unbounded per-chunk array
+ * the progress summary exists to avoid.
+ */
+interface CleanupStepProgress {
+  /** Stable id of the contributing step — survives relabelling of `resource`. */
+  readonly stepId: string;
+  /** Human-facing record class, e.g. `'journal entries'`. */
+  readonly resource: string;
+  readonly status: CleanupStepRunStatus;
+  /** Records this step has processed so far. */
+  readonly processed: number;
+  readonly startedAt?: Date | undefined;
+  readonly completedAt?: Date | undefined;
+  /**
+   * WHY, for any non-`completed` terminal state. Required for `skipped` and
+   * `failed`: an unexplained non-completion is the thing this field exists to
+   * prevent.
+   */
+  readonly detail?: string | undefined;
+}
 interface CleanupProgressSummary {
   /** Running total of processed records across all steps. */
   readonly processed: number;
   /** Count of steps reported so far. */
   readonly steps: number;
+  /**
+   * Per-step lifecycle. Bounded by the sealed plan's step count — see
+   * {@link CleanupStepProgress}. Absent on runs recorded before this existed,
+   * so a reader must treat it as optional rather than assume an empty run.
+   */
+  readonly stepProgress?: readonly CleanupStepProgress[] | undefined;
   /** Resource the last step touched. */
   readonly currentResource?: string | undefined;
   /** Last resume cursor reported. */
@@ -448,4 +591,4 @@ interface CleanupLimits {
 }
 declare const DEFAULT_CLEANUP_LIMITS: CleanupLimits;
 //#endregion
-export { CleanupWriteFence as A, CleanupResult as C, CleanupRunStore as D, CleanupRunStatus as E, PurgeStrategyKind$1 as F, PurgeVerificationSummary as I, VerificationCheck as L, PurgeActor as M, PurgeEvidence as N, CleanupRunTransitionPatch as O, PurgeResourceResult as P, VerificationResult as R, CleanupRecipe as S, CleanupRunCreateResult as T, CleanupPermissions as _, CleanupEvidenceStore as a, CleanupPlanItem as b, CleanupInput as c, CleanupLease as d, CleanupLimits as f, CleanupPermissionCheck as g, CleanupOutcomeStatus as h, CleanupContext as i, DEFAULT_CLEANUP_LIMITS as j, CleanupStepResult as k, CleanupJob as l, CleanupManifest as m, CLEANUP_TERMINAL_STATUSES as n, CleanupExecutionContext as o, CleanupLogger as p, CleanupCancelRequest as r, CleanupFinalizationPayload as s, Availability as t, CleanupJobQueue as u, CleanupPlan as v, CleanupRun as w, CleanupProgressSummary as x, CleanupPlanDraft as y };
+export { CleanupStepResult as A, VerificationResult as B, CleanupResult as C, CleanupRunStore as D, CleanupRunStatus as E, PurgeEvidence as F, PurgeResourceResult as I, PurgeStrategyKind$1 as L, CleanupWriteFence as M, DEFAULT_CLEANUP_LIMITS as N, CleanupRunTransitionPatch as O, PurgeActor as P, PurgeVerificationSummary as R, CleanupRecipe as S, CleanupRunCreateResult as T, CleanupPermissions as _, CleanupEvidenceStore as a, CleanupPlanItem as b, CleanupInput as c, CleanupLease as d, CleanupLimits as f, CleanupPermissionCheck as g, CleanupOutcomeStatus as h, CleanupContext as i, CleanupStepRunStatus as j, CleanupStepProgress as k, CleanupJob as l, CleanupManifest as m, CLEANUP_TERMINAL_STATUSES as n, CleanupExecutionContext as o, CleanupLogger as p, CleanupCancelRequest as r, CleanupFinalizationPayload as s, Availability as t, CleanupJobQueue as u, CleanupPlan as v, CleanupRun as w, CleanupProgressSummary as x, CleanupPlanDraft as y, VerificationCheck as z };

package/dist/usage/index.d.mts

@@ -1,6 +1,6 @@
 
 import { i as RequestScope } from "../types-ChuShpCP.mjs";
-import { i as PermissionContext, r as PermissionCheck } from "../types-B7XeLEgK.mjs";
+import { l as PermissionCheck, u as PermissionContext } from "../base-Csjc2oF-.mjs";
 import { UsageBucket, UsageStore, usagePeriod } from "@classytic/repo-core/usage";
 import { FastifyPluginAsync, FastifyRequest } from "fastify";
 //#region src/usage/requireQuota.d.ts

package/dist/{userHelpers-ChYJ6CdK.mjs → userHelpers-CWF5pbZD.mjs}

@@ -1,4 +1,4 @@
-/*! @classytic/arc v2.31.0 | MIT | https://classytic.com */
+/*! @classytic/arc v2.34.0 | MIT | https://classytic.com */
 //#region src/utils/userHelpers.ts
 /**
 * Extract a user ID from a user object. Accepts `id` or `_id` — returns

package/dist/utils/index.d.mts

@@ -1,8 +1,8 @@
 
-import { $ as OpenApiSchemas, S as QueryParserInterface, b as ParsedQuery } from "../index-CpzxqePp.mjs";
 import { F as getHeader, I as requireSingleHeaderValue, P as ArcHeaders } from "../types-ChuShpCP.mjs";
-import { c as normalizeRoles, l as AnyRecord, o as getUserId, s as getUserRoles } from "../types-B7XeLEgK.mjs";
-import { n as ErrorMapper } from "../errorHandler-CpYUJmPA.mjs";
+import { f as getUserId, m as normalizeRoles, p as getUserRoles, t as AnyRecord } from "../base-Csjc2oF-.mjs";
+import { $ as OpenApiSchemas, S as QueryParserInterface, b as ParsedQuery } from "../index-BcR2bFZQ.mjs";
+import { n as ErrorMapper } from "../errorHandler-DI5AN2b5.mjs";
 import { a as NotFoundError, c as RateLimitError, d as ValidationError, f as createDomainError, i as ForbiddenError, l as ServiceUnavailableError, m as isArcError, n as ConflictError, o as OrgAccessDeniedError, p as createError, r as ErrorOptions, s as OrgRequiredError, t as ArcError, u as UnauthorizedError } from "../errors-BGdVwP25.mjs";
 import { errorContractSchema, errorDetailSchema } from "@classytic/repo-core/errors";
 import { scheduleBackground } from "@classytic/repo-core/cache";
@@ -478,6 +478,29 @@ interface ArcQueryParserOptions {
    * Also used by MCP to auto-derive filterable fields in tool schemas.
    */
   allowedFilterFields?: string[];
+  /**
+   * REFUSE a filter key that is not in {@link allowedFilterFields}, instead of
+   * dropping it (default: `false` — today's drop behaviour, kept because arc
+   * is published and an unconditional throw would reject requests that work).
+   *
+   * Dropping a filter does not fail, it **WIDENS**: the caller asked for a
+   * narrower set and is silently answered with a broader one, HTTP 200. Two
+   * live instances:
+   *
+   *   `?filters[status]=pending` → 200, every row `status:"verified"`
+   *   `?productId=…` (the param is `skuRef`) → a different product's 75 units,
+   *     filed for weeks as "quant leakage"
+   *
+   * Turn this on per-parser, or fleet-wide via `ARC_STRICT_QUERY_PARAMS`.
+   * Mirrors the `ARC_STRICT_PERMISSIONS` precedent: off by default here, and
+   * the HOST opts in from its env-loader so a forgotten `.env` line cannot
+   * silently disable enforcement.
+   *
+   * Only the FILTER whitelist is covered. `allowedSortFields` /
+   * `allowedOperators` keep dropping: a rejected sort or operator degrades
+   * ordering, it does not widen the row set.
+   */
+  strictFilterFields?: boolean;
   /**
    * Whitelist of fields that can be sorted on.
    * When set, sort fields not in this list are silently dropped.
@@ -527,7 +550,12 @@ interface ArcQueryParserOptions {
  * For advanced MongoDB features ($lookup, aggregations), use MongoKit's QueryParser.
  */
 declare class ArcQueryParser implements QueryParserInterface {
-  private readonly maxLimit;
+  /**
+   * PUBLIC, deliberately: `QueryResolver` reads it so it does not apply a second cap
+   * on top of this one. Three layers capping independently, lowest winning silently,
+   * is what made a 696-row chart of accounts render as 100.
+   */
+  readonly maxLimit: number;
   private readonly defaultLimit;
   private readonly maxRegexLength;
   private readonly maxSearchLength;
@@ -535,6 +563,7 @@ declare class ArcQueryParser implements QueryParserInterface {
   private readonly _allowedFilterFields?;
   private readonly _allowedSortFields?;
   private readonly _allowedOperators?;
+  private readonly strictFilterFields;
   /** Allowed filter fields (used by MCP for auto-derive) */
   readonly allowedFilterFields?: readonly string[];
   /** Allowed sort fields (used by MCP for sort descriptions) */
@@ -1105,6 +1134,29 @@ declare function getListQueryParams(): AnyRecord;
  */
 declare function getDefaultCrudSchemas(): Record<string, Record<string, unknown>>;
 //#endregion
+//#region src/utils/runtimeCapabilities.d.ts
+/** What a subsystem declares about the state it holds. */
+interface RuntimeCapabilityDeclaration {
+  /** Dotted subsystem id, e.g. `'webhooks.subscriptions'`, `'events.transport'`. */
+  subsystem: string;
+  /** Where the state lives: `'memory'` = this process only; `'shared'` = external/durable. */
+  durability: "memory" | "shared";
+  /**
+   * `'memory'` durability that is CORRECT by design (per-process micro-cache,
+   * declared single-process topology). Audited as info, never an error —
+   * acceptance must be stated by the declarant, not inferred by the audit.
+   */
+  accepted?: boolean;
+  /** One line for the audit output: what breaks multi-replica, or why accepted. */
+  detail?: string;
+}
+/**
+ * Declare a runtime capability. Callable from ANY registration context —
+ * arc's own plugins, host `plugins()` callbacks, module `plugins` phases —
+ * which is the point: the audit sees what the constructor-time guard cannot.
+ */
+declare function declareRuntimeCapability(fastify: FastifyInstance, decl: RuntimeCapabilityDeclaration): void;
+//#endregion
 //#region src/utils/schemaConverter.d.ts
 /**
  * Supported JSON Schema output targets for Zod v4's `toJSONSchema()`.
@@ -1514,4 +1566,4 @@ declare function hasEvents(instance: FastifyInstance): instance is FastifyInstan
   events: EventsDecorator;
 };
 //#endregion
-export { ArcError, type ArcHeaders, ArcQueryParser, type ArcQueryParserOptions, CircuitBreaker, CircuitBreakerError, type CircuitBreakerOptions, CircuitBreakerRegistry, type CircuitBreakerStats, CircuitState, type CompensationDefinition, type CompensationError, type CompensationHooks, type CompensationResult, type CompensationStep, ConflictError, type ErrorOptions, type EventsDecorator, type FilterDialect, ForbiddenError, type Guard, type GuardConfig, type JsonSchema, type JsonSchemaTarget, MONGO_DIALECT, NEUTRAL_DIALECT, NotFoundError, OrgAccessDeniedError, OrgRequiredError, type PipeUIMessageStreamOptions, RateLimitError, type SchemaIo, ServiceUnavailableError, type SseStream, type SseStreamOptions, type StateMachine, type TransitionConfig, UI_MESSAGE_STREAM_HEADERS, UnauthorizedError, ValidationError, aggregateListResponse, bareListResponse, convertOpenApiSchemas, convertRouteSchema, createCircuitBreaker, createCircuitBreakerRegistry, createDomainError, createError, createQueryParser, createStateMachine, defineCompensation, defineErrorMapper, defineGuard, deleteResponse, errorContractSchema, errorDetailSchema, forwardedStreamHeaders, getDefaultCrudSchemas, getHeader, getListQueryParams, getUserId, getUserRoles, handleRaw, hasEvents, isArcError, isJsonSchema, isReadableStream, isZodSchema, keysetListResponse, listResponse, normalizeRoles, offsetListResponse, openSseStream, paginationSchema, pipeUIMessageStreamToReply, promoteStreamTokenToHeader, queryParams, requireSingleHeaderValue, responses, scheduleBackground, simpleEqualityMatcher, toJsonSchema, withCompensation };
+export { ArcError, type ArcHeaders, ArcQueryParser, type ArcQueryParserOptions, CircuitBreaker, CircuitBreakerError, type CircuitBreakerOptions, CircuitBreakerRegistry, type CircuitBreakerStats, CircuitState, type CompensationDefinition, type CompensationError, type CompensationHooks, type CompensationResult, type CompensationStep, ConflictError, type ErrorOptions, type EventsDecorator, type FilterDialect, ForbiddenError, type Guard, type GuardConfig, type JsonSchema, type JsonSchemaTarget, MONGO_DIALECT, NEUTRAL_DIALECT, NotFoundError, OrgAccessDeniedError, OrgRequiredError, type PipeUIMessageStreamOptions, RateLimitError, type RuntimeCapabilityDeclaration, type SchemaIo, ServiceUnavailableError, type SseStream, type SseStreamOptions, type StateMachine, type TransitionConfig, UI_MESSAGE_STREAM_HEADERS, UnauthorizedError, ValidationError, aggregateListResponse, bareListResponse, convertOpenApiSchemas, convertRouteSchema, createCircuitBreaker, createCircuitBreakerRegistry, createDomainError, createError, createQueryParser, createStateMachine, declareRuntimeCapability, defineCompensation, defineErrorMapper, defineGuard, deleteResponse, errorContractSchema, errorDetailSchema, forwardedStreamHeaders, getDefaultCrudSchemas, getHeader, getListQueryParams, getUserId, getUserRoles, handleRaw, hasEvents, isArcError, isJsonSchema, isReadableStream, isZodSchema, keysetListResponse, listResponse, normalizeRoles, offsetListResponse, openSseStream, paginationSchema, pipeUIMessageStreamToReply, promoteStreamTokenToHeader, queryParams, requireSingleHeaderValue, responses, scheduleBackground, simpleEqualityMatcher, toJsonSchema, withCompensation };

package/dist/utils/index.mjs

@@ -1,11 +1,12 @@
-/*! @classytic/arc v2.31.0 | MIT | https://classytic.com */
-import { a as OrgAccessDeniedError, c as ServiceUnavailableError, d as createDomainError, f as createError, i as NotFoundError, l as UnauthorizedError, n as ConflictError, o as OrgRequiredError, p as isArcError, r as ForbiddenError, s as RateLimitError, t as ArcError, u as ValidationError } from "../errors-Cj42AntO.mjs";
-import { n as requireSingleHeaderValue, t as getHeader } from "../headers-3zvE0rM3.mjs";
-import { n as getUserRoles, r as normalizeRoles, t as getUserId } from "../userHelpers-ChYJ6CdK.mjs";
-import { t as simpleEqualityMatcher } from "../simpleEqualityMatcher-DjQJ7FKA.mjs";
-import { A as createCircuitBreakerRegistry, C as defineCompensation, D as CircuitBreakerRegistry, E as CircuitBreakerError, O as CircuitState, S as defineErrorMapper, T as CircuitBreaker, _ as createQueryParser, a as deleteResponse, b as NEUTRAL_DIALECT, c as getDefaultCrudSchemas, d as listResponse, f as offsetListResponse, g as ArcQueryParser, h as responses, i as bareListResponse, k as createCircuitBreaker, l as getListQueryParams, m as queryParams, n as scheduleBackground, o as errorContractSchema, p as paginationSchema, r as aggregateListResponse, s as errorDetailSchema, t as createStateMachine, u as keysetListResponse, v as handleRaw, w as withCompensation, x as defineGuard, y as MONGO_DIALECT } from "../utils-vL8BrDE2.mjs";
-import { a as isZodSchema, i as isJsonSchema, n as convertRouteSchema, o as toJsonSchema, t as convertOpenApiSchemas } from "../schemaConverter-D--wdJM-.mjs";
-import { a as promoteStreamTokenToHeader, i as pipeUIMessageStreamToReply, n as forwardedStreamHeaders, r as isReadableStream, t as UI_MESSAGE_STREAM_HEADERS } from "../streaming-PSZwi8JV.mjs";
-import { t as openSseStream } from "../sseStream-B_5XcVVd.mjs";
-import { t as hasEvents } from "../typeGuards-B0ryPo3I.mjs";
-export { ArcError, ArcQueryParser, CircuitBreaker, CircuitBreakerError, CircuitBreakerRegistry, CircuitState, ConflictError, ForbiddenError, MONGO_DIALECT, NEUTRAL_DIALECT, NotFoundError, OrgAccessDeniedError, OrgRequiredError, RateLimitError, ServiceUnavailableError, UI_MESSAGE_STREAM_HEADERS, UnauthorizedError, ValidationError, aggregateListResponse, bareListResponse, convertOpenApiSchemas, convertRouteSchema, createCircuitBreaker, createCircuitBreakerRegistry, createDomainError, createError, createQueryParser, createStateMachine, defineCompensation, defineErrorMapper, defineGuard, deleteResponse, errorContractSchema, errorDetailSchema, forwardedStreamHeaders, getDefaultCrudSchemas, getHeader, getListQueryParams, getUserId, getUserRoles, handleRaw, hasEvents, isArcError, isJsonSchema, isReadableStream, isZodSchema, keysetListResponse, listResponse, normalizeRoles, offsetListResponse, openSseStream, paginationSchema, pipeUIMessageStreamToReply, promoteStreamTokenToHeader, queryParams, requireSingleHeaderValue, responses, scheduleBackground, simpleEqualityMatcher, toJsonSchema, withCompensation };
+/*! @classytic/arc v2.34.0 | MIT | https://classytic.com */
+import { a as OrgAccessDeniedError, c as ServiceUnavailableError, d as createDomainError, f as createError, i as NotFoundError, l as UnauthorizedError, n as ConflictError, o as OrgRequiredError, p as isArcError, r as ForbiddenError, s as RateLimitError, t as ArcError, u as ValidationError } from "../errors-Cd_yy7aW.mjs";
+import { n as requireSingleHeaderValue, t as getHeader } from "../headers-CveNO9gR.mjs";
+import { n as getUserRoles, r as normalizeRoles, t as getUserId } from "../userHelpers-CWF5pbZD.mjs";
+import { t as simpleEqualityMatcher } from "../simpleEqualityMatcher-Se8VrsaP.mjs";
+import { A as createCircuitBreakerRegistry, C as defineCompensation, D as CircuitBreakerRegistry, E as CircuitBreakerError, O as CircuitState, S as defineErrorMapper, T as CircuitBreaker, _ as createQueryParser, a as deleteResponse, b as NEUTRAL_DIALECT, c as getDefaultCrudSchemas, d as listResponse, f as offsetListResponse, g as ArcQueryParser, h as responses, i as bareListResponse, k as createCircuitBreaker, l as getListQueryParams, m as queryParams, n as scheduleBackground, o as errorContractSchema, p as paginationSchema, r as aggregateListResponse, s as errorDetailSchema, t as createStateMachine, u as keysetListResponse, v as handleRaw, w as withCompensation, x as defineGuard, y as MONGO_DIALECT } from "../utils-h1V_sT-t.mjs";
+import { n as declareRuntimeCapability } from "../runtimeCapabilities-Dm88DaTW.mjs";
+import { a as isZodSchema, i as isJsonSchema, n as convertRouteSchema, o as toJsonSchema, t as convertOpenApiSchemas } from "../schemaConverter-XH1RZRyu.mjs";
+import { a as promoteStreamTokenToHeader, i as pipeUIMessageStreamToReply, n as forwardedStreamHeaders, r as isReadableStream, t as UI_MESSAGE_STREAM_HEADERS } from "../streaming-DsT1B5zJ.mjs";
+import { t as openSseStream } from "../sseStream-Bvpi-UXQ.mjs";
+import { t as hasEvents } from "../typeGuards-jjKJDN13.mjs";
+export { ArcError, ArcQueryParser, CircuitBreaker, CircuitBreakerError, CircuitBreakerRegistry, CircuitState, ConflictError, ForbiddenError, MONGO_DIALECT, NEUTRAL_DIALECT, NotFoundError, OrgAccessDeniedError, OrgRequiredError, RateLimitError, ServiceUnavailableError, UI_MESSAGE_STREAM_HEADERS, UnauthorizedError, ValidationError, aggregateListResponse, bareListResponse, convertOpenApiSchemas, convertRouteSchema, createCircuitBreaker, createCircuitBreakerRegistry, createDomainError, createError, createQueryParser, createStateMachine, declareRuntimeCapability, defineCompensation, defineErrorMapper, defineGuard, deleteResponse, errorContractSchema, errorDetailSchema, forwardedStreamHeaders, getDefaultCrudSchemas, getHeader, getListQueryParams, getUserId, getUserRoles, handleRaw, hasEvents, isArcError, isJsonSchema, isReadableStream, isZodSchema, keysetListResponse, listResponse, normalizeRoles, offsetListResponse, openSseStream, paginationSchema, pipeUIMessageStreamToReply, promoteStreamTokenToHeader, queryParams, requireSingleHeaderValue, responses, scheduleBackground, simpleEqualityMatcher, toJsonSchema, withCompensation };