@classytic/arc 2.23.0 → 2.28.0

package/dist/{module-B4u10iOJ.d.mts → types-Cu6vVJmh.d.mts}

@@ -1,5 +1,106 @@
+import { r as EventHandler } from "./EventTransport-QmY7A258.mjs";
 import { n as ErrorMapper } from "./errorHandler-C6yv4ZTW.mjs";
-import { FastifyInstance } from "fastify";
+import { FastifyInstance, FastifyPluginAsync } from "fastify";
+import { LockAdapter } from "@classytic/repo-core/lock";
+//#region src/plugins/health.d.ts
+interface HealthCheck {
+  /** Name of the dependency */
+  name: string;
+  /**
+   * Function that returns true if healthy, false otherwise.
+   *
+   * Receives an `AbortSignal` aborted when the check's timeout elapses —
+   * pass it to fetch/driver calls so a stalled dependency probe actually
+   * STOPS instead of accumulating an abandoned operation per readiness
+   * poll. Ignoring the parameter is fine (back-compat): the timeout still
+   * bounds how long the PROBE waits, just not the underlying work.
+   */
+  check: (signal?: AbortSignal) => Promise<boolean> | boolean;
+  /** Optional timeout in ms (default: 5000) */
+  timeout?: number;
+  /** Whether this check is critical for readiness (default: true) */
+  critical?: boolean;
+}
+interface HealthOptions {
+  /** Route prefix (default: '/_health') */
+  prefix?: string;
+  /** Health check dependencies */
+  checks?: readonly HealthCheck[];
+  /** Enable metrics endpoint (default: false) */
+  metrics?: boolean;
+  /** Custom metrics collector function */
+  metricsCollector?: () => Promise<string> | string;
+  /** Version info to include in responses */
+  version?: string;
+  /** Collect HTTP request metrics (default: true if metrics enabled) */
+  collectHttpMetrics?: boolean;
+}
+declare const healthPlugin: FastifyPluginAsync<HealthOptions>;
+declare const _default$1: FastifyPluginAsync<HealthOptions>;
+//#endregion
+//#region src/plugins/schedules.d.ts
+interface ScheduleDefinition {
+  /** Unique name — also the lock key (`arc:schedule:<name>`). */
+  name: string;
+  /** Interval in milliseconds between the END of one run and the next tick. */
+  every: number;
+  /** The work. Receives the Fastify instance; errors are logged, never fatal. */
+  handler: (fastify: FastifyInstance) => void | Promise<void>;
+  /** Fire once immediately when the app becomes ready (default: false). */
+  runOnStart?: boolean;
+  /**
+   * Random extra delay in `[0, jitterMs)` added to the FIRST tick only.
+   * Spreads boot-aligned jobs so multiple same-cadence schedules don't all
+   * fire at exactly `boot + every` after every restart (and, with a lock,
+   * de-synchronizes replicas competing for the same lease). Ignored when
+   * `runOnStart` is true.
+   */
+  jitterMs?: number;
+  /**
+   * Lease duration when a `lock` is configured. Default: `every * 0.9`
+   * (capped at 5 minutes) — long enough that other replicas skip the same
+   * tick, short enough that a crashed leader fails over within one cycle.
+   */
+  leaseMs?: number;
+  /** Per-schedule kill switch (default: true). */
+  enabled?: boolean;
+}
+interface SchedulesPluginOptions {
+  schedules: readonly ScheduleDefinition[];
+  /**
+   * Ecosystem lock adapter (`LockAdapter` from `@classytic/repo-core/lock`)
+   * for multi-replica deployments. Omit for single-instance apps — every
+   * tick runs locally.
+   */
+  lock?: LockAdapter;
+  /**
+   * Identity of this replica for lease ownership. Default: a random id per
+   * process (repo-core's `getInstanceId()` is a good explicit value).
+   */
+  holderId?: string;
+  /**
+   * Master switch — `false` registers a typed no-op (config-gated
+   * environments), same pattern as `idempotencyPlugin`.
+   */
+  enabled?: boolean;
+}
+/** Per-schedule runtime counters, readable via `fastify.getScheduleStats()`. */
+interface ScheduleStats {
+  name: string;
+  runs: number;
+  failures: number;
+  skippedByLock: number;
+  lastRunAt: string | null;
+  lastError: string | null;
+}
+declare module "fastify" {
+  interface FastifyInstance {
+    getScheduleStats?: () => ScheduleStats[];
+  }
+}
+declare const schedulesPlugin: FastifyPluginAsync<SchedulesPluginOptions>;
+declare const _default: FastifyPluginAsync<SchedulesPluginOptions>;
+//#endregion
 //#region src/factory/loadResources.d.ts
 /**
  * loadResources — Auto-discover resource files from a directory.
@@ -218,7 +319,31 @@ interface LoadResourcesOptions<TContext = unknown> {
  */
 declare function loadResources<TContext = unknown>(dir: string, options?: LoadResourcesOptions<TContext>): Promise<ResourceLike[]>;
 //#endregion
-//#region src/factory/module.d.ts
+//#region src/factory/module/types.d.ts
+/**
+ * A module's contribution of some arm (event handlers, scheduled jobs, …).
+ * Either a static array or a factory resolved AFTER all module bootstraps, so a
+ * contribution can close over booted engines / the Fastify instance instead of
+ * reaching for a global getter (the coupling the module contract removes).
+ */
+type ModuleContribution<T> = readonly T[] | ((fastify: FastifyInstance) => readonly T[] | Promise<readonly T[]>);
+/**
+ * A domain-event subscription a module owns. Subscribed in dependency order
+ * during the `afterResources` phase (routes mounted, engines booted) and
+ * auto-unsubscribed at shutdown BEFORE module `onClose` (deps still alive).
+ */
+interface EventHandlerDefinition {
+  /** Event pattern(s) to subscribe — same matcher as `fastify.events.subscribe`. */
+  event: string | readonly string[];
+  /** The subscriber. */
+  handler: EventHandler;
+  /**
+   * Optional stable name — enables duplicate detection + teardown diagnostics.
+   * Third-party modules should prefix it with their module name, for example
+   * `inventory.order-created`; Arc does not silently rewrite public names.
+   */
+  name?: string;
+}
 interface ArcModule<TExports = unknown> {
   /** Stable identifier — appears in boot logs and duplicate-module detection. */
   readonly name: string;
@@ -344,6 +469,74 @@ interface ArcModule<TExports = unknown> {
    * module owns.
    */
   afterResources?: (fastify: FastifyInstance) => void | Promise<void>;
+  /**
+   * Readiness checks this module contributes to the app's
+   * `healthPlugin` (`/_health/ready`). Collected across ALL modules in
+   * dependency order and merged BEFORE the host's app-level `arcPlugins.health`
+   * checks (modules-first, host-last) — the same additive convention arc uses
+   * for resources and error mappers. Check `name`s must be unique across the
+   * module graph (arc fails at boot on a collision, attributing both owners).
+   *
+   * STATIC by design (not a factory): declare the check up front and let its
+   * `check()` closure resolve dependencies LAZILY at probe time, so collection
+   * can happen before the health plugin registers and the worker probe
+   * (`createWorker`) receives the identical union without a second registration.
+   *
+   * ```ts
+   * defineModule({ name: "inventory", healthChecks: [
+   *   { name: "flow-engine", check: () => flow.isReady() },
+   * ] })
+   * ```
+   */
+  readonly healthChecks?: readonly HealthCheck[];
+  /**
+   * Domain-event subscriptions this module owns — the declarative replacement
+   * for imperative `fastify.events.subscribe(...)` calls inside
+   * `afterResources`. Subscribed in dependency order during the
+   * `afterResources` phase (routes mounted, engines booted), and arc RETAINS
+   * every unsubscribe and invokes it at shutdown BEFORE module `onClose` (while
+   * module deps are still alive). Named handlers must be unique across the
+   * module graph; a module that declares handlers while the event subsystem is
+   * disabled (`arcPlugins.events: false`) fails at boot. Array or factory (the
+   * factory runs after bootstraps, so it can close over booted engines).
+   *
+   * ```ts
+   * defineModule({ name: "party", eventHandlers: [
+   *   { name: "party.link-customer", event: ["customer:created"], handler: onCustomer },
+   * ] })
+   * ```
+   */
+  readonly eventHandlers?: ModuleContribution<EventHandlerDefinition>;
+  /**
+   * Durable workflows this module owns. OPAQUE to arc core — arc never imports
+   * `@classytic/streamline`; the value flows through untouched and the
+   * streamline integration (`@classytic/arc/integrations/streamline`, a peer)
+   * gives it meaning (name/shape validation, registration). Collected via
+   * `collectModuleWorkflows` at integration-init time (after module bootstraps),
+   * so a factory can close over the shared workflow container the integration
+   * decorates on the instance.
+   *
+   * ```ts
+   * defineModule({ name: "invoice",
+   *   workflows: (f) => createInvoiceWorkflows(f.streamlineContainer) })
+   * ```
+   */
+  readonly workflows?: ModuleContribution<unknown>;
+  /**
+   * Recurring interval schedules this module owns. Arc composes them into its
+   * existing `schedulesPlugin` after bootstraps, in dependency order. Names
+   * must be unique across the module graph. Configure multi-replica locking via
+   * `arcPlugins.schedules`; explicitly disabling that runner while a module
+   * declares schedules fails boot instead of silently dropping work. Array or
+   * factory (the factory runs once after bootstraps and may close over engines).
+   *
+   * ```ts
+   * defineModule({ name: "loyalty", scheduledJobs: [
+   *   { name: "loyalty.point.expiration", every: 3_600_000, handler: () => sweep() },
+   * ] })
+   * ```
+   */
+  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
@@ -375,31 +568,6 @@ interface ArcModule<TExports = unknown> {
  * ```
  */
 type ArcModuleInput<TExports = unknown> = ArcModule<TExports> | Promise<ArcModule<TExports>> | (() => ArcModule<TExports> | Promise<ArcModule<TExports>>);
-/**
- * Resolve any module-input form to a concrete `ArcModule`. A thunk is invoked
- * (this is where a dynamic `import()` fires); a promise (or plain module) is
- * awaited. Called once per module at the start of the bootstrap phase.
- */
-declare function resolveModule(input: ArcModuleInput): Promise<ArcModule>;
-/**
- * Order modules for composition by their `dependsOn` edges — a STABLE
- * topological sort. Called once at the start of the bootstrap phase; every
- * subsequent phase (bootstrap, resources, afterResources, and reverse-order
- * onClose) iterates the returned list, so a module's declared dependencies are
- * always composed before it.
- *
- * "Stable" = modules with no edge between them keep their original list order,
- * so declaring `dependsOn` on one module never silently reorders an unrelated
- * one. Backward compatible: a `modules` array with NO `dependsOn` anywhere is
- * returned unchanged.
- *
- * Fail-fast — throws (never reorders past a broken contract) on:
- *   - duplicate module names (the name is the graph key)
- *   - a `dependsOn` name not present in the composed set
- *   - a self-reference (`dependsOn` includes the module's own name)
- *   - a dependency cycle (reports the concrete `a → b → … → a` path)
- */
-declare function orderModules(modules: readonly ArcModule[]): ArcModule[];
 /**
  * Typed module registry — hosts augment this via declaration merging so
  * `getModuleExports(f, "order")` infers the export type without a manual type
@@ -418,37 +586,5 @@ declare function orderModules(modules: readonly ArcModule[]): ArcModule[];
  * available for apps that don't augment it.
  */
 interface ArcModuleRegistry {}
-/**
- * Identity helper for authoring a typed module — mirrors `defineResource`.
- * Gives inference + a single obvious construction site; does no work.
- *
- * `TExports` is inferred from the `bootstrap` return value, so a module
- * author gets a typed public export for free:
- *
- * ```ts
- * export const accountingModule = (deps: Deps) =>
- *   defineModule({
- *     name: "accounting",
- *     bootstrap: async () => createAccountingEngine(deps), // TExports inferred
- *   });
- * ```
- */
-declare function defineModule<TExports = unknown>(module: ArcModule<TExports>): ArcModule<TExports>;
-/**
- * Typed accessor for a module's public export (its `bootstrap` return value),
- * recorded at `fastify.arc.modules[name]`.
- *
- * Throwing, in line with the fail-fast contract (and `requireOrgId`-style
- * accessors): a missing entry means the module either isn't composed, is
- * composed AFTER the caller (list order = init order), or returned nothing —
- * all wiring bugs that must surface at boot, not as `undefined` downstream.
- *
- * The type parameter is an assertion, not a proof. Two ways to type it:
- *   - augment `ArcModuleRegistry` once — then the name alone infers the type:
- *     `getModuleExports(f, "accounting")` → `AccountingEngine`.
- *   - or pass it inline: `getModuleExports<AccountingEngine>(f, "accounting")`.
- */
-declare function getModuleExports<K extends keyof ArcModuleRegistry>(fastify: FastifyInstance, name: K): ArcModuleRegistry[K];
-declare function getModuleExports<TExports = unknown>(fastify: FastifyInstance, name: string): TExports;
 //#endregion
-export { getModuleExports as a, LoadResourcesOptions as c, loadResources as d, defineModule as i, ResourceLike as l, ArcModuleInput as n, orderModules as o, ArcModuleRegistry as r, resolveModule as s, ArcModule as t, ResourceModule as u };
+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 };

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

@@ -1,24 +1,39 @@
-//#region src/scope/types.d.ts
+//#region src/utils/headers.d.ts
 /**
- * Request Scope — The One Standard
- *
- * Discriminated union representing the access context of every request.
- * Replaces scattered orgScope/orgRoles/organizationId/bypassRoles.
- *
- * Set once by auth adapters, read everywhere by permissions/presets/guards.
+ * Canonical header typing + accessor.
+ *
+ * Node/Fastify header values are `string | string[] | undefined` — repeated
+ * headers arrive as arrays. `IRequestContext.headers` is DECLARED as
+ * `Record<string, string | undefined>` for ergonomic host code, but the HTTP
+ * adapter passes Fastify's headers object through unchanged, so `string[]`
+ * CAN appear at runtime behind the narrower type (the declared type is
+ * scheduled to widen to {@link ArcHeaders} in v3). Until then, read headers
+ * through {@link getHeader} instead of indexing — it's honest about arrays
+ * and deterministic about duplicates.
+ */
+/** What a headers bag actually contains at runtime — HTTP or synthetic MCP. */
+type ArcHeaders = Readonly<Record<string, string | readonly string[] | undefined>>;
+/**
+ * Read a single header value. Lowercases the name (Node normalizes incoming
+ * header names to lowercase) and returns the FIRST value when the header
+ * was repeated.
+ *
+ * Duplicate policy: first-value is deterministic, but for security-sensitive
+ * headers (authorization material, forwarded-for chains, content-length) a
+ * duplicate usually signals smuggling or a broken proxy — consumers that
+ * care should check `Array.isArray(headers[name])` and REJECT instead of
+ * picking a winner.
+ */
+declare function getHeader(headers: ArcHeaders | Record<string, string | undefined> | undefined, name: string): string | undefined;
+/**
+ * Read an identity-bearing or protocol header and reject repeated values.
  *
- * @example
- * ```typescript
- * // In a permission check
- * const scope = request.scope;
- * if (isElevated(scope)) return true;
- * if (isMember(scope) && scope.orgRoles.includes('admin')) return true;
- *
- * // Get user identity from scope
- * const userId = getUserId(scope);
- * const globalRoles = getUserRoles(scope);
- * ```
+ * Repeated security-sensitive headers are ambiguous at proxy boundaries and
+ * may indicate request smuggling. Callers must not silently choose a winner.
  */
+declare function requireSingleHeaderValue(headers: ArcHeaders | Record<string, string | undefined> | undefined, name: string): string | undefined;
+//#endregion
+//#region src/scope/types.d.ts
 /**
  * A capability mandate — declarative, time-boxed, optionally cap-bounded
  * authorization for a single high-value action by an AI agent or service.
@@ -118,7 +133,9 @@ interface Mandate {
  * | elevated      | Platform admin, explicit elevation               |
  *
  * **Identity fields by kind:**
- * - `userId` / `userRoles` — available on `authenticated`, `member`, `elevated` (a real human)
+ * - `userId` — available on `authenticated`, `member`, `elevated` (a real human)
+ * - `userRoles` — available on `authenticated` and `member`; elevated scope
+ *   bypasses role gates explicitly and therefore does not carry role claims
  * - `clientId` — available on `service` (a machine identity, NOT a user)
  * - `organizationId` — required on `member` and `service`, optional on `elevated`
  * - `orgRoles` — org-level roles, only on `member` (from membership records)
@@ -517,9 +534,90 @@ declare function getOrgContext(request: {
 declare function getRequestScope(request: {
   scope?: RequestScope;
 }): RequestScope;
+/** Options for {@link scopeFirstCtx}. */
+interface ScopeFirstCtxOptions {
+  /**
+   * Tenant-selection header consulted ONLY when the scope carries no org —
+   * the custom-auth/public bridge (same semantics as `getTenantFromRequest`).
+   * A validated scope org always wins; the header never overrides it.
+   * Default `'x-organization-id'`; pass `false` to disable the bridge and
+   * read strictly from scope.
+   */
+  orgHeader?: string | false;
+  /**
+   * Actor id substituted when the scope carries no user/client identity
+   * (e.g. `'system'` / `'anonymous'`). When provided, the returned `actorId`
+   * narrows to `string`; omit to receive `actorId: undefined` on
+   * unauthenticated requests and apply your own policy.
+   */
+  fallbackActorId?: string;
+}
+/** Return shape of {@link scopeFirstCtx}. */
+interface ScopeFirstCtx {
+  actorId?: string;
+  organizationId?: string;
+}
+/**
+ * Request shape accepted by {@link scopeFirstCtx} — deliberately structural so
+ * ONE helper serves both surfaces:
+ * - a raw `FastifyRequest`, whose `scope` is the discriminated {@link RequestScope}
+ * - arc's `IRequestContext` (controller overrides, pipeline handlers, actions),
+ *   whose `scope` is the FLAT projection (`{ organizationId?, userId?, orgRoles? }`
+ *   lifted from `metadata._scope` — see `RequestScopeProjection`)
+ */
+interface ScopeFirstCtxRequest {
+  scope?: RequestScope | {
+    organizationId?: string | undefined;
+    userId?: string | undefined;
+    orgRoles?: string[] | undefined;
+  } | undefined;
+  /** `ArcHeaders` — readonly, repeated headers may arrive as arrays. Fastify's `IncomingHttpHeaders` assigns cleanly. */
+  headers?: ArcHeaders | undefined;
+}
+/**
+ * The ONE shared actor/org derivation for resource handlers and module
+ * packages (`arc-*` fleet) — scope-FIRST, per the canonical precedence:
+ *
+ * 1. `request.scope` (arc's validated `RequestScope`, set by auth adapters):
+ *    `userId` (human) or `clientId` (service) → `actorId`; `getOrgId(scope)`
+ *    → `organizationId`.
+ * 2. The `x-organization-id` header — ONLY when the scope carries no org.
+ *    This is the bridge for custom-auth/public routes where arc leaves scope
+ *    unpopulated; it never overrides a validated scope.
+ *
+ * Replaces per-package hand-rolled clones of
+ * `req.user?._id ?? req.user?.id ?? headers['x-organization-id']` — that
+ * pattern re-implements (and drifts from) arc's canonical resolution. A
+ * package's `ctxOf(req)` should call this for the shared
+ * `{ actorId, organizationId }` and only ADD its kernel-specific fields
+ * (`actorKind` / `correlationId` / `roles` / `idempotencyKey`).
+ *
+ * Structural request shape — works on a raw `FastifyRequest` AND on arc's
+ * `IRequestContext` (see {@link ScopeFirstCtxRequest}: the discriminated
+ * `RequestScope` and the flat controller projection are both understood).
+ *
+ * @example
+ * ```typescript
+ * import { scopeFirstCtx } from '@classytic/arc/scope';
+ *
+ * // Guaranteed actor (kernel context requires one):
+ * const { actorId, organizationId } = scopeFirstCtx(req, { fallbackActorId: 'system' });
+ *
+ * // Optional actor (package applies its own policy):
+ * const ctx = scopeFirstCtx(req);
+ * if (ctx.actorId) audit.record({ actor: ctx.actorId });
+ * ```
+ */
+declare function scopeFirstCtx(req: ScopeFirstCtxRequest, options: ScopeFirstCtxOptions & {
+  fallbackActorId: string;
+}): {
+  actorId: string;
+  organizationId?: string;
+};
+declare function scopeFirstCtx(req: ScopeFirstCtxRequest, options?: ScopeFirstCtxOptions): ScopeFirstCtx;
 /** Default public scope — used as initial decoration value */
 declare const PUBLIC_SCOPE: Readonly<RequestScope>;
 /** Default authenticated scope — used when user is logged in but no org */
 declare const AUTHENTICATED_SCOPE: Readonly<RequestScope>;
 //#endregion
-export { isMember as C, requireOrgId as D, requireClientId as E, requireTeamId as O, isElevated as S, isService as T, getTenantFromRequest as _, getAncestorOrgIds as a, hasOrgAccess as b, getMandate as c, getOrgRoles as d, getRequestScope as f, getTeamId as g, getServiceScopes as h, RequestScope as i, requireUserId as k, getOrgContext as l, getScopeContextMap as m, Mandate as n, getClientId as o, getScopeContext as p, PUBLIC_SCOPE as r, getDPoPJkt as s, AUTHENTICATED_SCOPE as t, getOrgId as u, getUserId as v, isOrgInScope as w, isAuthenticated as x, getUserRoles as y };
+export { requireOrgId as A, hasOrgAccess as C, isOrgInScope as D, isMember as E, getHeader as F, requireSingleHeaderValue as I, requireUserId as M, scopeFirstCtx as N, isService as O, ArcHeaders as P, getUserRoles as S, isElevated as T, getScopeContextMap as _, ScopeFirstCtx as a, getTenantFromRequest as b, getAncestorOrgIds as c, getMandate as d, getOrgContext as f, getScopeContext as g, getRequestScope as h, RequestScope as i, requireTeamId as j, requireClientId as k, getClientId as l, getOrgRoles as m, Mandate as n, ScopeFirstCtxOptions as o, getOrgId as p, PUBLIC_SCOPE as r, ScopeFirstCtxRequest as s, AUTHENTICATED_SCOPE as t, getDPoPJkt as u, getServiceScopes as v, isAuthenticated as w, getUserId as x, getTeamId as y };

package/dist/{types-Csxga7d3.d.mts → types-Dmw-6Qeo.d.mts}

@@ -1,5 +1,99 @@
-import { i as RequestScope } from "./types-DH0GupI7.mjs";
+import { i as RequestScope } from "./types-DjC-KUCz.mjs";
 import { FastifyRequest } from "fastify";
+//#region src/types/base.d.ts
+declare module "fastify" {
+  interface FastifyRequest {
+    /** Request scope — set by auth adapter, read by permissions/presets/guards */
+    scope: RequestScope;
+    /**
+     * Current user — set by auth adapter (Better Auth, JWT, custom).
+     * `undefined` on public routes (`auth: false`) or unauthenticated requests.
+     * Guard with `if (request.user)` on routes that allow anonymous access.
+     *
+     * Kept as required (not `user?`) because `@fastify/jwt` declares it
+     * as required — declaration merges must have identical modifiers.
+     * The `| undefined` in the type achieves the same DX.
+     */
+    user: Record<string, unknown> | undefined;
+    /** Policy-injected query filters (e.g. ownership, org-scoping) */
+    _policyFilters?: Record<string, unknown>;
+    /** Field mask — fields to include/exclude in responses */
+    fieldMask?: {
+      include?: string[];
+      exclude?: string[];
+    };
+    /** Arbitrary policy metadata for downstream consumers */
+    policyMetadata?: Record<string, unknown>;
+    /** Document loaded by policy middleware for ownership checks */
+    document?: unknown;
+    /** Ownership check context (field name + user field) */
+    _ownershipCheck?: Record<string, unknown>;
+  }
+}
+type AnyRecord = Record<string, unknown>;
+/** MongoDB ObjectId — accepts string or any object with a `toString()` (e.g. mongoose ObjectId). */
+type ObjectId = string | {
+  toString(): string;
+};
+/**
+ * Flexible user type that accepts any object with id/_id properties.
+ * The actual user structure is defined by your app's auth system.
+ */
+type UserLike = UserBase & {
+  /** User email (optional) */
+  email?: string;
+};
+interface UserOrganization {
+  userId: string;
+  organizationId: string;
+  [key: string]: unknown;
+}
+interface JWTPayload {
+  sub: string;
+  [key: string]: unknown;
+}
+/**
+ * Typed Fastify request with Arc decorations. Use in `raw: true` handlers
+ * instead of `(req as any).user`.
+ *
+ * @example
+ * ```typescript
+ * import type { ArcRequest } from '@classytic/arc';
+ *
+ * handler: async (req: ArcRequest, reply) => {
+ *   req.user?.id;                    // typed
+ *   req.scope.organizationId;        // typed (when member)
+ *   req.signal;                      // AbortSignal (Fastify 5)
+ * }
+ * ```
+ */
+type ArcRequest = FastifyRequest & {
+  scope: RequestScope;
+  user: Record<string, unknown> | undefined;
+  signal: AbortSignal;
+};
+//#endregion
+//#region src/utils/userHelpers.d.ts
+/**
+ * Extract a user ID from a user object. Accepts `id` or `_id` — returns
+ * `undefined` when neither is present. Used by arc's controllers to
+ * populate `createdBy` / `updatedBy` fields and for cache scoping.
+ *
+ * @example
+ * ```ts
+ * import { getUserId } from '@classytic/arc/utils';
+ * const uid = getUserId(request.user);
+ * ```
+ */
+declare function getUserId(user: UserLike | null | undefined): string | undefined;
+/** Normalize a raw role value from Better Auth, JWT, or a custom identity provider. */
+declare function normalizeRoles(value: unknown): string[];
+/** Extract normalized roles from a user-like object. */
+declare function getUserRoles(user: {
+  role?: unknown;
+  roles?: unknown;
+} | null | undefined): string[];
+//#endregion
 //#region src/permissions/types.d.ts
 /**
  * User base interface - minimal shape Arc expects
@@ -24,8 +118,6 @@ interface UserBase {
  * Normalize a raw role value (string, comma-separated string, or array) into a string[].
  * Shared low-level helper used by both getUserRoles() and the Better Auth adapter.
  */
-declare function normalizeRoles(value: unknown): string[];
-declare function getUserRoles(user: UserBase | null | undefined): string[];
 /**
  * Context passed to permission check functions
  */
@@ -195,4 +287,4 @@ interface PermissionCheckMeta {
   };
 }
 //#endregion
-export { getUserRoles as a, UserBase as i, PermissionContext as n, normalizeRoles as o, PermissionResult as r, PermissionCheck as t };
+export { getUserId as a, AnyRecord as c, ObjectId as d, UserLike as f, UserBase as i, ArcRequest as l, PermissionContext as n, getUserRoles as o, UserOrganization as p, PermissionResult as r, normalizeRoles as s, PermissionCheck as t, JWTPayload as u };

package/dist/{types-5OuqeTDX.d.mts → types-QFGc3Cjv.d.mts}

@@ -1,4 +1,4 @@
-import { V as ResourceDefinition } from "./index-BBsvQt7U.mjs";
+import { V as ResourceDefinition } from "./index-DPRH0Cme.mjs";
 import { z } from "zod";
 //#region src/integrations/mcp/types.d.ts
 /** Behavioral hints for MCP clients (tool annotations per MCP spec) */

package/dist/usage/index.d.mts

@@ -1,5 +1,6 @@
-import { i as RequestScope } from "../types-DH0GupI7.mjs";
-import { n as PermissionContext, t as PermissionCheck } from "../types-Csxga7d3.mjs";
+import { i as RequestScope } from "../types-DjC-KUCz.mjs";
+import { n as PermissionContext, t as PermissionCheck } from "../types-Dmw-6Qeo.mjs";
+import { UsageBucket, UsageStore, usagePeriod } from "@classytic/repo-core/usage";
 import { FastifyPluginAsync, FastifyRequest } from "fastify";
 //#region src/usage/requireQuota.d.ts
 interface QuotaOptions {
@@ -28,56 +29,6 @@ interface QuotaOptions {
 }
 declare function requireQuota(options: QuotaOptions): PermissionCheck;
 //#endregion
-//#region src/usage/stores/interface.d.ts
-/**
- * Usage store contract — period-bucketed counters per actor.
- *
- * CANONICAL HOME: `@classytic/repo-core/usage` (>=0.10) owns this
- * contract for the ecosystem — kits implement it there without ever
- * depending on arc (`@classytic/mongokit/usage`, ...). This file is a
- * deliberate STRUCTURAL MIRROR of that shape — same trick as
- * `ScheduleLockLike` vs repo-core's `LockAdapter` — so arc's emitted
- * declarations carry no repo-core@>=0.10 subpath reference and the
- * peer floor stays honest. Any conforming adapter assigns directly.
- *
- * The deliberately tiny surface (one increment, one read) is what makes
- * every backend trivial: memory (dev/tests), Redis (`HINCRBY`), or any kit
- * (Mongo `$inc` upsert) implements it in a handful of lines. Aggregation
- * happens IN the store — arc never buffers counters in process memory
- * beyond the built-in memory store, so multi-replica deployments stay
- * correct as long as the store is shared.
- *
- * This is the HORIZONTAL usage layer (per-actor, per-period platform
- * accounting for quotas/plans/billing). Itemized vertical records — e.g.
- * `@classytic/arc-ai/usage`'s per-run AI token/cost tracking — keep their
- * own richer stores and can sink into this one (`kind: 'ai.tokens'`).
- */
-/** One counter cell: (actor, period, kind). */
-interface UsageBucket {
-  /** Who consumed — org / user / client id, or an IP-derived fallback. */
-  actor: string;
-  /** Aggregation period, `YYYY-MM` (see `usagePeriod()`). */
-  period: string;
-  /** Namespaced counter, dot-separated: `api.requests`, `ai.tokens`, `storage.bytes`. */
-  kind: string;
-}
-interface UsageStore {
-  /** Store name for diagnostics (e.g. 'memory', 'redis', 'mongo'). */
-  readonly name: string;
-  /** Add `amount` to the bucket's counter, creating it at 0 first. MUST be atomic per bucket. */
-  increment(bucket: UsageBucket, amount: number): Promise<void> | void;
-  /** Every counter for an actor in a period: `{ 'api.requests': 40231, ... }`. */
-  summary(actor: string, period: string): Promise<Record<string, number>>;
-  /** Optional cleanup hook (connections, timers). */
-  close?(): Promise<void>;
-}
-/**
- * Canonical period key for a date — calendar month, UTC: `2026-07`.
- * Monthly is the billing-native granularity; stores that want finer
- * windows can shard internally without changing the contract.
- */
-declare function usagePeriod(date?: Date): string;
-//#endregion
 //#region src/usage/stores/memory.d.ts
 declare class MemoryUsageStore implements UsageStore {
   #private;

package/dist/userHelpers-Cg_y3fBz.mjs

@@ -0,0 +1,29 @@
+//#region src/utils/userHelpers.ts
+/**
+* Extract a user ID from a user object. Accepts `id` or `_id` — returns
+* `undefined` when neither is present. Used by arc's controllers to
+* populate `createdBy` / `updatedBy` fields and for cache scoping.
+*
+* @example
+* ```ts
+* import { getUserId } from '@classytic/arc/utils';
+* const uid = getUserId(request.user);
+* ```
+*/
+function getUserId(user) {
+	if (!user) return void 0;
+	const id = user.id ?? user._id;
+	return id ? String(id) : void 0;
+}
+/** Normalize a raw role value from Better Auth, JWT, or a custom identity provider. */
+function normalizeRoles(value) {
+	if (Array.isArray(value)) return value.map((role) => String(role).trim()).filter(Boolean);
+	if (typeof value === "string" && value.length > 0) return value.split(",").map((role) => role.trim()).filter(Boolean);
+	return [];
+}
+/** Extract normalized roles from a user-like object. */
+function getUserRoles(user) {
+	return user ? normalizeRoles(user.role ?? user.roles) : [];
+}
+//#endregion
+export { getUserRoles as n, normalizeRoles as r, getUserId as t };