@classytic/arc 2.15.4 → 2.16.0

package/dist/registry/index.d.mts

@@ -1,8 +1,325 @@
-import { R as RegisterOptions, k as IntrospectionPluginOptions, z as ResourceRegistry } from "../index-BswOSJCE.mjs";
+import { J as CrudRouteKey, R as RegisterOptions, V as ResourceDefinition, at as ResolvedTenantPurge, k as IntrospectionPluginOptions, p as RegistryEntry, z as ResourceRegistry } from "../index-CkW0flkU.mjs";
 import { FastifyPluginAsync } from "fastify";
+import { TenantPurgeProgress, TenantPurgeStrategy } from "@classytic/repo-core/repository";
 
+//#region src/registry/assertNoTenantData.d.ts
+interface AssertNoTenantDataOptions {
+  readonly organizationId: string;
+  /**
+   * Limit the check to a subset of resources. Default: every cascading
+   * resource (matches the cascade runner's filter).
+   */
+  readonly only?: readonly string[];
+  /**
+   * Skip resources whose strategy is `anonymize` (the rows legitimately
+   * remain). Default `true` — the smoke test focuses on "did data leave?"
+   * not "did anonymize keep rows?". Set `false` for a full pass.
+   */
+  readonly skipAnonymize?: boolean;
+}
+interface TenantDataLeak {
+  readonly resource: string;
+  readonly tenantField: string;
+  readonly strategy: TenantPurgeStrategy["type"];
+  readonly expected: number;
+  readonly actual: number;
+  readonly reason?: string;
+}
+interface AssertNoTenantDataReport {
+  readonly ok: boolean;
+  readonly organizationId: string;
+  readonly checked: number;
+  readonly skipped: readonly {
+    resource: string;
+    reason: string;
+  }[];
+  readonly leaks: readonly TenantDataLeak[];
+}
+/**
+ * Walk every cascading resource, run a tenant-scoped count, compare
+ * against the strategy's expected outcome.
+ *
+ * Designed for use inside compliance tests:
+ *
+ * ```ts
+ * import { assertNoTenantData } from '@classytic/arc/registry';
+ *
+ * it('after org delete, no tenant data leaks', async () => {
+ *   await cascadeDeleteForOrganization(arc.registry, { organizationId: 'test-org' });
+ *   const report = await assertNoTenantData(arc.registry, { organizationId: 'test-org' });
+ *   expect(report.ok).toBe(true);
+ *   expect(report.leaks).toHaveLength(0);
+ * });
+ * ```
+ */
+declare function assertNoTenantData(registry: ResourceRegistry, options: AssertNoTenantDataOptions): Promise<AssertNoTenantDataReport>;
+//#endregion
+//#region src/registry/purgeResource.d.ts
+/**
+ * Outcome for one resource. Wider than `TenantPurgeResult` because it
+ * carries the resource name + tenantField for the aggregate report,
+ * and a `path` discriminator so audit consumers can tell which code
+ * path ran.
+ */
+interface PurgeResourceOutcome {
+  readonly resource: string;
+  readonly tenantField: string;
+  readonly strategy: TenantPurgeStrategy["type"];
+  readonly processed: number;
+  readonly ok: boolean;
+  readonly path: "purgeByField" | "legacy-deleteMany" | "skipped" | "unsupported";
+  readonly skipReason?: string;
+  readonly error?: {
+    code?: string;
+    message: string;
+  };
+  readonly durationMs?: number;
+}
+//#endregion
+//#region src/registry/cascadeOrgDelete.d.ts
+/**
+ * Per-resource result row. One entry for every resource Arc attempted to
+ * cascade-delete for the given org. `deletedCount: -1` means the adapter
+ * doesn't surface a row count (the delete still ran).
+ */
+interface CascadeResourceReport {
+  readonly resource: string;
+  readonly tenantField: string;
+  /**
+   * Rows processed. For `hard` strategy this equals rows that no longer
+   * exist; for `soft`/`anonymize` it's rows touched (still present).
+   * `-1` only on legacy `deleteMany` adapters that don't surface a count.
+   */
+  readonly deletedCount: number;
+  /**
+   * Strategy that actually ran for this resource — `'hard'` / `'soft'` /
+   * `'anonymize'` / `'skip'`. Audit consumers branch on this to answer
+   * "did data physically leave the system?".
+   */
+  readonly strategy?: TenantPurgeStrategy["type"];
+  /**
+   * Where the strategy came from — `'declared'` (host wrote
+   * `onTenantDelete`) or `'disabled'` (filtered out before reaching
+   * this report). Future sources may be added; treat the field as a
+   * read-only audit signal.
+   */
+  readonly strategySource?: ResolvedTenantPurge["source"];
+  /**
+   * Code path that executed — `'purgeByField'` (preferred, chunked),
+   * `'legacy-deleteMany'` (single-shot fallback for old adapters),
+   * `'skipped'` (skip strategy), `'unsupported'` (adapter can't run
+   * the declared strategy — surfaces in `failures`).
+   */
+  readonly path?: PurgeResourceOutcome["path"];
+  /** Echoed for `skip` strategy — the declared reason. */
+  readonly skipReason?: string;
+  readonly error?: {
+    code?: string;
+    message: string;
+  };
+}
+/** Aggregate report — splits successful and failed resources for the caller. */
+interface CascadeReport {
+  readonly organizationId: string;
+  readonly resources: readonly CascadeResourceReport[];
+  readonly successes: readonly CascadeResourceReport[];
+  readonly failures: readonly CascadeResourceReport[];
+  readonly totalDeleted: number;
+  readonly durationMs: number;
+}
+/** Lightweight logger shape — `fastify.log`, `pino`, or `console` all fit. */
+interface CascadeLogger {
+  info?: (obj: unknown, msg?: string) => void;
+  warn?: (obj: unknown, msg?: string) => void;
+  error?: (obj: unknown, msg?: string) => void;
+}
+interface CascadeOptions {
+  /** Organization id whose tenant-scoped rows should be deleted. */
+  readonly organizationId: string;
+  /**
+   * Skip these resources even if they declare `onTenantDelete`.
+   * Useful for stage-gated rollouts ("cascade everything except `audit_log`
+   * — we want to keep the trail").
+   */
+  readonly skip?: readonly string[];
+  /**
+   * Resource names to LIMIT cascade to. When set, only these resources
+   * cascade — useful for partial-cleanup scripts and the test path that
+   * verifies one resource at a time.
+   */
+  readonly only?: readonly string[];
+  /** Optional logger — info on each resource, warn/error on failures. */
+  readonly logger?: CascadeLogger;
+  /**
+   * Forwarded to each resource's `purgeByField` — emits per-chunk
+   * progress. The event includes the resource name so a single
+   * progress handler can drive a multi-resource progress UI.
+   */
+  readonly onProgress?: (event: TenantPurgeProgress & {
+    resource: string;
+  }) => void | Promise<void>;
+  /**
+   * Forwarded to each resource's `purgeByField`. The runner checks
+   * between resources too — aborting mid-cascade stops the next
+   * resource from starting, in addition to stopping the currently-
+   * running purge between chunks.
+   */
+  readonly signal?: AbortSignal;
+  /**
+   * Global override for per-resource batchSize. Per-resource declarations
+   * (`onTenantDelete.batchSize`) win when set; this is the fallback.
+   */
+  readonly batchSize?: number;
+  /**
+   * Run up to `concurrency` resources in parallel. **Priority groups
+   * remain barriers** — all priority-10 resources finish before any
+   * priority-50 resource starts. Within a priority, resources run
+   * concurrently up to this cap. Default `1` (sequential, safest).
+   *
+   * Resources are independent (different collections / tables, no
+   * cross-resource constraints), so parallelism is safe — but oplog
+   * pressure / connection-pool exhaustion / replication lag scale with
+   * concurrency. Tune per environment; `4` is usually fine for cloud
+   * Mongo + small connection pools, `8`–`16` for high-throughput tiers.
+   */
+  readonly concurrency?: number;
+  /**
+   * Cascade-level checkpoint — survive a crash mid-cascade and resume
+   * from the last completed resource. `read()` returns the last cascade
+   * state (or `undefined` for a fresh run); `write()` persists state
+   * after each resource completes. Hosts plumb to Redis / a status
+   * table / a dedicated checkpoint store.
+   *
+   * Per-purge checkpointing is intentionally NOT offered — the chunked
+   * primitive is already idempotent (re-running a partially-completed
+   * cascade is safe because already-deleted rows don't match the next
+   * SELECT). The cascade-level checkpoint just skips entire resources
+   * known-completed in the prior pass — wasteful round-trips, not
+   * wasteful writes.
+   */
+  readonly checkpoint?: CascadeCheckpoint;
+}
+/** Cascade resume state. Persist between runs; rehydrate on retry. */
+interface CascadeCheckpointState {
+  /** Names of resources fully completed in a prior pass. Skipped on resume. */
+  readonly completedResources: readonly string[];
+}
+interface CascadeCheckpoint {
+  /** Load the prior cascade state for this org. Return `undefined` for a fresh run. */
+  read(): Promise<CascadeCheckpointState | undefined>;
+  /** Persist updated state after a resource finishes. */
+  write(state: CascadeCheckpointState): Promise<void>;
+}
+/**
+ * Names of resources flagged for cascade — used by audit scripts.
+ * A resource is cascading when its resolved strategy isn't `disabled`
+ * (i.e. the host declared `onTenantDelete`).
+ */
+declare function getCascadingResources(registry: ResourceRegistry): readonly string[];
+/**
+ * Rich introspection — returns the resolved strategy + source per
+ * cascading resource. Use for audit dashboards that answer "what
+ * happens to this resource on org-delete?" without grepping the
+ * source.
+ */
+declare function getCascadingResourcesWithMetadata(registry: ResourceRegistry): readonly {
+  name: string;
+  tenantField: string;
+  strategy: TenantPurgeStrategy["type"];
+  source: ResolvedTenantPurge["source"];
+  priority: number;
+}[];
+/**
+ * Cascade-cleanup every tenant-scoped resource for the given organization.
+ * Walks the registry in **ascending priority order** (`onTenantDelete.priority`
+ * — leaf data first, references last), runs each resource's resolved
+ * strategy via `purgeByField` when available (chunked, progress, abort),
+ * and returns a structured report.
+ *
+ * **Strategy resolution** lives in `resolveTenantPurge.ts` — this runner
+ * just reads `resource.resolvedTenantPurge` (computed once at boot).
+ *
+ * **Per-resource execution** lives in `purgeResource.ts` — preferred
+ * path is the kit's `purgeByField` (chunked + plugin-composed); falls
+ * back to legacy `deleteMany` only for `hard` strategy on adapters that
+ * haven't been upgraded.
+ *
+ * **Failure semantics**: continues on per-resource error, returns the
+ * full report. Hosts decide whether a partial cascade is a hard
+ * failure (re-throw) or degraded mode (log + alert).
+ *
+ * @param registry  The arc resource registry (`fastify.arc.registry`).
+ * @param options   Org id + filters + logger + progress + signal.
+ */
+declare function cascadeDeleteForOrganization(registry: ResourceRegistry, options: CascadeOptions): Promise<CascadeReport>;
+//#endregion
 //#region src/registry/introspectionPlugin.d.ts
 declare const introspectionPlugin: FastifyPluginAsync<IntrospectionPluginOptions>;
 declare const _default: FastifyPluginAsync<IntrospectionPluginOptions>;
 //#endregion
-export { type IntrospectionPluginOptions, type RegisterOptions, ResourceRegistry, _default as introspectionPlugin, introspectionPlugin as introspectionPluginFn };
+//#region src/registry/manifest.d.ts
+/** Mount-point string the FE uses to derive the URL for an action call. */
+type ActionMount = "/:id/action" | "/action";
+/**
+ * One action entry in a resource manifest. `requiresId` is the boolean
+ * the FE checks to decide whether its helper takes `(id, body)` or just
+ * `(body)`; `mount` is the URL suffix to append to the resource prefix.
+ */
+interface ActionManifestEntry {
+  readonly name: string;
+  readonly mount: ActionMount;
+  readonly requiresId: boolean;
+  readonly description?: string;
+}
+/** Aggregation entry — one per `defineAggregation()` declaration. */
+interface AggregationManifestEntry {
+  readonly name: string;
+  readonly path: string;
+  readonly summary?: string;
+  readonly description?: string;
+}
+/** Custom (non-CRUD, non-action) route entry. */
+interface CustomRouteManifestEntry {
+  readonly method: string;
+  readonly path: string;
+  readonly operation?: string;
+  readonly summary?: string;
+}
+/**
+ * Single resource manifest. Everything an FE codegen needs to wire a
+ * typed client over the resource's HTTP surface.
+ */
+interface ResourceManifest {
+  readonly name: string;
+  readonly displayName: string;
+  readonly prefix: string;
+  readonly idField: string;
+  /** Update method used for `/:id` PATCH / PUT routes. */
+  readonly updateMethod: "PUT" | "PATCH" | "both";
+  /** Enabled CRUD operations — filtered by `disabledRoutes` and `disableDefaultRoutes`. */
+  readonly crudOps: readonly CrudRouteKey[];
+  readonly actions: readonly ActionManifestEntry[];
+  readonly aggregations: readonly AggregationManifestEntry[];
+  readonly customRoutes: readonly CustomRouteManifestEntry[];
+  /** Tenant scoping field (when set) — surfaces for FE callers that need to send `x-organization-id`. */
+  readonly tenantField?: string | false;
+}
+/**
+ * Build a manifest from a `ResourceDefinition` (the value returned by
+ * `defineResource(...)`). Use at build time when you have direct access
+ * to the resource module — typically the simplest codegen path.
+ */
+declare function buildResourceManifest(resource: ResourceDefinition): ResourceManifest;
+/**
+ * Build a manifest from a `RegistryEntry` — use when the resource is
+ * already registered (introspection endpoint, runtime audit script).
+ *
+ * Equivalent to {@link buildResourceManifest} but reads from the projected
+ * registry shape, so a host that doesn't have the original `defineResource`
+ * value in scope (e.g. an FE-gen sidecar that scrapes a running server's
+ * `/_resources` endpoint) gets the same output without dragging the resource
+ * module into the codegen path.
+ */
+declare function buildResourceManifestFromRegistry(entry: RegistryEntry): ResourceManifest;
+//#endregion
+export { type ActionManifestEntry, type ActionMount, type AggregationManifestEntry, type AssertNoTenantDataOptions, type AssertNoTenantDataReport, type CascadeCheckpoint, type CascadeCheckpointState, type CascadeOptions, type CascadeReport, type CascadeResourceReport, type CustomRouteManifestEntry, type IntrospectionPluginOptions, type RegisterOptions, type ResourceManifest, ResourceRegistry, type TenantDataLeak, assertNoTenantData, buildResourceManifest, buildResourceManifestFromRegistry, cascadeDeleteForOrganization, getCascadingResources, getCascadingResourcesWithMetadata, _default as introspectionPlugin, introspectionPlugin as introspectionPluginFn };

package/dist/registry/index.mjs

@@ -1,3 +1,3 @@
-import { n as introspectionPlugin_default, t as introspectionPlugin } from "../registry-I-ogLgL9.mjs";
-import { t as ResourceRegistry } from "../ResourceRegistry-CTERg_2x.mjs";
-export { ResourceRegistry, introspectionPlugin_default as introspectionPlugin, introspectionPlugin as introspectionPluginFn };
+import { a as cascadeDeleteForOrganization, c as assertNoTenantData, i as introspectionPlugin_default, n as buildResourceManifestFromRegistry, o as getCascadingResources, r as introspectionPlugin, s as getCascadingResourcesWithMetadata, t as buildResourceManifest } from "../registry-BBE23CDj.mjs";
+import { t as ResourceRegistry } from "../ResourceRegistry-f48hFk3m.mjs";
+export { ResourceRegistry, assertNoTenantData, buildResourceManifest, buildResourceManifestFromRegistry, cascadeDeleteForOrganization, getCascadingResources, getCascadingResourcesWithMetadata, introspectionPlugin_default as introspectionPlugin, introspectionPlugin as introspectionPluginFn };