@classytic/arc 2.25.0 → 2.30.0

package/dist/types-C_ZZRcD6.d.mts

@@ -0,0 +1,450 @@
+import { PurgeActor, PurgeEvidence, PurgeResourceResult, PurgeStrategyKind as PurgeStrategyKind$1, PurgeVerificationSummary } from "@classytic/primitives/retention";
+//#region src/cleanup/types.d.ts
+/** Ambient context every recipe method receives. Host-injected — never global. */
+interface CleanupContext {
+  /** Who requested the operation. */
+  readonly actor: PurgeActor;
+  /** Injected clock — recipes never call `new Date()` directly (testability). */
+  readonly now: Date;
+  /** Cooperative cancellation — checked between chunks/steps. */
+  readonly signal?: AbortSignal | undefined;
+  /** Optional structured logger. */
+  readonly logger?: CleanupLogger | undefined;
+  /**
+   * Opaque host-provided ambient values (e.g. the resolved company/branch
+   * scope). MUST be JSON-serializable — it is persisted on the run so a worker
+   * (different process) can rebuild the exact operation context. Recipes read
+   * what they declared they need; the framework never inspects it.
+   */
+  readonly ambient?: Readonly<Record<string, unknown>> | undefined;
+}
+interface CleanupLogger {
+  info(msg: string, meta?: Record<string, unknown>): void;
+  warn(msg: string, meta?: Record<string, unknown>): void;
+  error(msg: string, meta?: Record<string, unknown>): void;
+}
+/**
+ * Execution-time context — adds progress reporting + the run/operation ids +
+ * cooperative cancellation.
+ */
+interface CleanupExecutionContext extends CleanupContext {
+  /** Durable run id this execution belongs to. */
+  readonly runId: string;
+  /** Stable operation id threaded through logs, audit, and evidence. */
+  readonly operationId: string;
+  /**
+   * Report one committed chunk. Updates the run's BOUNDED progress summary
+   * (counts / current resource / cursor / heartbeat) — it does NOT retain
+   * every step in memory. Also refreshes the cancellation view: after a chunk
+   * commits, call this so the executor learns of a cancel request promptly.
+   */
+  onStep(step: CleanupStepResult): 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
+   * source of truth) plus the in-process `signal`.
+   */
+  throwIfCancelled(): Promise<void>;
+}
+/** Whether a recipe may run right now, and why not. */
+interface Availability {
+  readonly available: boolean;
+  /** Required when `available` is false — surfaced to the operator. */
+  readonly reason?: string | undefined;
+}
+/** Operator-supplied recipe parameters (branch, module set, before-date, …). */
+interface CleanupInput {
+  readonly parameters?: Readonly<Record<string, unknown>> | undefined;
+}
+/** One logical line in the preview — a business record class, never a collection. */
+interface CleanupPlanItem {
+  /** Logical module / resource label, e.g. `'orders'`, `'journal entries'`. */
+  readonly resource: string;
+  /** Estimated records affected. */
+  readonly estimated: number;
+  /** 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'`). */
+  readonly blockers?: readonly string[] | undefined;
+}
+/**
+ * A recipe's plan BEFORE the framework seals it — the recipe returns this; the
+ * service computes {@link CleanupPlan.digest} + stamps {@link CleanupPlan.recipeId}.
+ */
+interface CleanupPlanDraft {
+  readonly items: readonly CleanupPlanItem[];
+  /** Top-level categories the recipe explicitly RETAINS. */
+  readonly retains?: readonly string[] | undefined;
+  /**
+   * Top-level blockers. A NON-EMPTY blockers list is a HARD STOP — the service
+   * refuses `execute` with `CLEANUP_BLOCKED`. Preview surfaces them so the
+   * operator resolves them (or the recipe stops listing them) before running.
+   */
+  readonly blockers?: readonly string[] | undefined;
+  /** Projection/scaffolding rebuilds the recipe will perform after cleanup. */
+  readonly rebuildActions?: readonly string[] | undefined;
+  /** Non-blocking warnings for the operator. */
+  readonly warnings?: readonly string[] | undefined;
+  /**
+   * The exact phrase the operator must type to confirm a destructive run.
+   * Defaults (in the service) to the recipe id when omitted.
+   */
+  readonly confirmationPhrase?: string | undefined;
+}
+/** A sealed, digest-stamped plan. The digest makes confirmation tamper-evident. */
+interface CleanupPlan {
+  readonly recipeId: string;
+  readonly parameters: Readonly<Record<string, unknown>>;
+  readonly items: readonly CleanupPlanItem[];
+  readonly retains: readonly string[];
+  readonly blockers: readonly string[];
+  readonly rebuildActions: readonly string[];
+  readonly warnings: readonly string[];
+  readonly estimatedTotal: number;
+  readonly confirmationPhrase: string;
+  /** Deterministic checksum of the plan's material content — see `computePlanDigest`. */
+  readonly digest: string;
+}
+/** One committed step's outcome — reported via `onStep`, folded into the summary. */
+interface CleanupStepResult {
+  readonly resource: string;
+  readonly processed: number;
+  readonly ok: boolean;
+  readonly error?: string | undefined;
+  /** Opaque resume cursor the recipe may surface for observability. */
+  readonly cursor?: string | undefined;
+  readonly startedAt?: Date | undefined;
+  readonly completedAt?: Date | undefined;
+}
+/**
+ * BOUNDED progress summary persisted on the run (design "Node.js memory"): a
+ * 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.
+ */
+interface CleanupProgressSummary {
+  /** Running total of processed records across all steps. */
+  readonly processed: number;
+  /** Count of steps reported so far. */
+  readonly steps: number;
+  /** Resource the last step touched. */
+  readonly currentResource?: string | undefined;
+  /** Last resume cursor reported. */
+  readonly lastCursor?: string | undefined;
+  /** When the last step landed — liveness/heartbeat. */
+  readonly heartbeatAt?: Date | undefined;
+  /** Count of failed steps (a run with any is never a clean success). */
+  readonly failed?: number | undefined;
+}
+/** One verification invariant's outcome. */
+interface VerificationCheck {
+  readonly name: string;
+  readonly ok: boolean;
+  readonly detail?: string | undefined;
+}
+/** The recipe's own post-checks — a delete count alone is never success (§9). */
+interface VerificationResult {
+  readonly ok: boolean;
+  readonly checks: readonly VerificationCheck[];
+}
+type CleanupOutcomeStatus = "completed" | "partial" | "failed" | "cancelled";
+/** What `execute` returns — the per-step results + a terminal status. */
+interface CleanupResult {
+  readonly status: Exclude<CleanupOutcomeStatus, "cancelled">;
+  readonly results: readonly CleanupStepResult[];
+}
+/**
+ * The finalization payload persisted ON the run BEFORE it enters `finalizing`
+ * (same CAS patch). This is what makes a `finalizing` crash recoverable
+ * WITHOUT re-executing the recipe: a recovering worker replays ONLY
+ * `evidenceStore.finalize()` + the terminal CAS from this durable snapshot —
+ * never `recipe.execute()` again.
+ */
+interface CleanupFinalizationPayload {
+  readonly status: CleanupOutcomeStatus;
+  readonly results: readonly CleanupStepResult[];
+  readonly verification: VerificationResult;
+  /** Count of verification checks dropped by `maxChecks` truncation. */
+  readonly checksTruncated?: number | undefined;
+  readonly failureReason?: string | undefined;
+}
+/**
+ * A cleanup recipe — the unit operators choose. Pure provider: the four
+ * methods are the only surface arc calls. A recipe delegates the actual
+ * domain work to kernel-provided steps; it never runs a raw Mongo cascade.
+ */
+interface CleanupRecipe {
+  /** Stable machine id, e.g. `'cleanup.pre-live-reset'`. Unique in a registry. */
+  readonly id: string;
+  /** Plain-language name for the UI. */
+  readonly label: string;
+  /** Whether this recipe removes data (gates confirmation + single-run fence). */
+  readonly destructive: boolean;
+  /**
+   * Recipe/plan-schema version. Persisted on the run; a retry that finds a
+   * different current version requires a fresh preview rather than replaying an
+   * incompatible sealed plan. Defaults to `'1'`.
+   */
+  readonly version?: string;
+  /**
+   * The purge strategy this recipe's evidence records (`'hard'` deletion,
+   * `'soft'` deactivation, `'anonymize'` redaction). Defaults to `'hard'`.
+   * A pure projection-rebuild recipe should declare `'soft'` (nothing about the
+   * SOURCE data is removed) or, better, the closest honest label — evidence
+   * must never overstate destructiveness.
+   */
+  readonly evidenceStrategy?: PurgeStrategyKind$1;
+  /** Whether this recipe may run right now (e.g. pre-go-live only). */
+  available(ctx: CleanupContext): Promise<Availability>;
+  /** Compute a preview WITHOUT mutating anything. Idempotent + side-effect-free. */
+  plan(input: CleanupInput, ctx: CleanupContext): Promise<CleanupPlanDraft>;
+  /** Execute the sealed plan. Must be chunked, idempotent, and cancellation-aware. */
+  execute(plan: CleanupPlan, ctx: CleanupExecutionContext): Promise<CleanupResult>;
+  /** Verify the post-state — the recipe owns what "clean" means. */
+  verify(plan: CleanupPlan, ctx: CleanupContext): Promise<VerificationResult>;
+}
+type CleanupRunStatus = "planned" | "queued" | "running" | "finalizing" | "completed" | "failed" | "cancelled";
+/** Terminal states — no further transition is valid. */
+declare const CLEANUP_TERMINAL_STATUSES: readonly CleanupRunStatus[];
+interface CleanupRun {
+  readonly id: string;
+  readonly recipeId: string;
+  readonly recipeVersion: string;
+  readonly status: CleanupRunStatus;
+  readonly planDigest: string;
+  /** The immutable sealed plan — replayed verbatim by the worker / a retry. */
+  readonly sealedPlan: CleanupPlan;
+  /** The operator-supplied parameters (also inside sealedPlan; kept explicit). */
+  readonly parameters: Readonly<Record<string, unknown>>;
+  /** The authorizing actor — persisted so a worker attributes the op correctly. */
+  readonly actor: PurgeActor;
+  /** Serializable ambient scope captured at request time (branch/company). */
+  readonly ambient?: Readonly<Record<string, unknown>> | undefined;
+  readonly requestedBy: string;
+  readonly reason: string;
+  readonly operationId: string;
+  /**
+   * Whether the recipe was destructive at request time — persisted so a
+   * GENERIC store can enforce the single-destructive-run policy without
+   * consulting the registry (and so non-destructive rebuilds need not
+   * serialize behind it).
+   */
+  readonly destructive: boolean;
+  /**
+   * Admission-control key the store serializes on (e.g. `'global-destructive'`).
+   * Absent for runs that need no mutual exclusion. Hosts may shard it later
+   * (`'branch:<id>'`) without an arc change.
+   */
+  readonly concurrencyKey?: string | undefined;
+  /** How many times a worker has claimed this run (1 = first execution). */
+  readonly attempt: number;
+  /**
+   * Exclusive worker lease. A run in `running`/`finalizing` with an UNEXPIRED
+   * lease is owned — `claim` refuses it. Progress + status writes carry the
+   * token so a stalled ex-owner that wakes past expiry cannot clobber the new
+   * owner's writes.
+   */
+  readonly leaseToken?: string | undefined;
+  readonly leaseExpiresAt?: Date | undefined;
+  readonly progress: CleanupProgressSummary;
+  /** Durable cancellation request — the source of truth the executor polls. */
+  readonly cancelRequested: boolean;
+  /** Who requested the cancel + why + when (audit — §8, cancel evidence). */
+  readonly cancelRequestedBy?: PurgeActor | undefined;
+  readonly cancelReason?: string | undefined;
+  readonly cancelRequestedAt?: Date | undefined;
+  /** Durable finalization snapshot — see {@link CleanupFinalizationPayload}. */
+  readonly finalization?: CleanupFinalizationPayload | undefined;
+  readonly queuedAt?: Date | undefined;
+  readonly startedAt?: Date | undefined;
+  readonly completedAt?: Date | undefined;
+  readonly failureReason?: string | undefined;
+}
+/** Immutable proof of a completed run (§5) — deterministically checksummed. */
+interface CleanupManifest {
+  readonly runId: string;
+  readonly recipeId: string;
+  readonly recipeVersion: string;
+  readonly operationId: string;
+  readonly planDigest: string;
+  readonly status: CleanupOutcomeStatus;
+  readonly actor: PurgeActor;
+  readonly reason: string;
+  readonly results: readonly CleanupStepResult[];
+  readonly verification: VerificationResult;
+  /**
+   * Count of verification checks DROPPED by the `maxChecks` cap. Present and
+   * non-zero whenever `verification.checks` is not the complete set — evidence
+   * must say so rather than silently show only the retained checks.
+   */
+  readonly checksTruncated?: number | undefined;
+  readonly completedAt: Date;
+  /**
+   * Integrity CHECKSUM of the manifest content (not tamper-PROOF: plain SHA-256
+   * does not stop an attacker with write access from replacing the record and
+   * recomputing the digest — pair with access control / keyed signatures for
+   * that). Detects accidental corruption + drift.
+   */
+  readonly manifestDigest: string;
+}
+type CleanupRunCreateResult = {
+  readonly created: true;
+} | {
+  readonly created: false;
+  readonly activeRunId: string;
+};
+/** Fields a status transition may also patch. */
+interface CleanupRunTransitionPatch {
+  readonly queuedAt?: Date;
+  readonly startedAt?: Date;
+  readonly completedAt?: Date;
+  readonly failureReason?: string;
+  readonly progress?: CleanupProgressSummary;
+  /** Reset the cancellation flag — used when a terminal run is re-armed on retry. */
+  readonly cancelRequested?: boolean;
+  /** Persist the durable finalization snapshot (set entering `finalizing`). */
+  readonly finalization?: CleanupFinalizationPayload;
+}
+/** An exclusive worker lease on a run. */
+interface CleanupLease {
+  /** Opaque token identifying THIS worker's ownership of the run. */
+  readonly token: string;
+  /** When the lease lapses and the run becomes claimable again. */
+  readonly expiresAt: Date;
+}
+/** Metadata persisted with a durable cancel request (audit). */
+interface CleanupCancelRequest {
+  readonly actor?: PurgeActor | undefined;
+  readonly reason?: string | undefined;
+  readonly requestedAt: Date;
+}
+/**
+ * Durable store for cleanup runs. The host owns persistence (Mongo/SQL/…) AND
+ * the atomicity of these operations — the framework's safety rests on them:
+ *
+ *   - `createIfPermitted` MUST be atomic: for a run with a `concurrencyKey` it
+ *     inserts ONLY if no other run with the same key is in a non-terminal
+ *     state, backed by a unique partial index / conditional insert / lock. A
+ *     check-then-create is NOT sufficient. Runs WITHOUT a key are always
+ *     admitted.
+ *   - `claim` MUST be atomic and EXCLUSIVE: grant the lease ONLY if the run is
+ *     `queued`, OR is `running`/`finalizing` with an ABSENT or EXPIRED lease
+ *     (`leaseExpiresAt <= now`). On grant it sets `leaseToken`/`leaseExpiresAt`,
+ *     increments `attempt`, and returns the run (status UNCHANGED — the service
+ *     branches on it: `finalizing` recovers finalization only, never
+ *     re-executes). A run whose lease is live is OWNED — return `null`.
+ *   - `compareAndTransition` MUST be a compare-and-set: apply the transition
+ *     ONLY if the current status is one of `expected` AND, when `leaseToken`
+ *     is given, the run's current lease token matches. This is the ONLY way
+ *     status changes — it makes cancel-vs-complete AND stale-ex-owner races
+ *     safe.
+ *   - `reArmIfPermitted` MUST apply the same admission policy as
+ *     `createIfPermitted` atomically with the terminal→`queued` transition
+ *     (a retry must not slip past the single-destructive-run guard).
+ */
+interface CleanupRunStore {
+  /** Atomic conditional insert (admission control by `concurrencyKey`, §8). */
+  createIfPermitted(run: CleanupRun): Promise<CleanupRunCreateResult>;
+  get(id: string): Promise<CleanupRun | null>;
+  /**
+   * Atomically acquire the exclusive worker lease (see contract above).
+   * Returns the claimed run with the lease applied, or `null` if the run is
+   * owned, terminal, or missing.
+   */
+  claim(id: string, lease: CleanupLease): Promise<CleanupRun | null>;
+  /**
+   * CAS the status: set `status=to` (+ `patch`) ONLY if current status ∈
+   * `expected` and (when given) `leaseToken` matches the run's current lease.
+   * Returns the updated run, or `null` if the CAS lost the race.
+   */
+  compareAndTransition(id: string, expected: readonly CleanupRunStatus[], to: CleanupRunStatus, patch?: CleanupRunTransitionPatch, leaseToken?: string): Promise<CleanupRun | null>;
+  /**
+   * Atomically re-arm a terminal (`failed`/`cancelled`) run back to `queued`
+   * under the SAME admission policy as `createIfPermitted` (its
+   * `concurrencyKey` must not collide with another non-terminal run). Clears
+   * the cancel flag/metadata + lease. Returns `{created:false}`-style refusal
+   * via `null` + the blocking run id in the second tuple slot is NOT modeled —
+   * a `null` simply means "not permitted or not in a terminal state."
+   */
+  reArmIfPermitted(id: string, patch: CleanupRunTransitionPatch): Promise<CleanupRun | null>;
+  /**
+   * Set `cancelRequested = true` (+ audit metadata, idempotent — first request
+   * wins). Does NOT change `status`.
+   */
+  requestCancel(id: string, request?: CleanupCancelRequest): Promise<CleanupRun | null>;
+  /**
+   * Overwrite the small bounded progress summary (frequent, non-status).
+   * When `lease` is given, ALSO extend `leaseExpiresAt` (heartbeat renewal) —
+   * and apply ONLY if the run's current lease token matches `lease.token`.
+   */
+  saveProgress(id: string, progress: CleanupProgressSummary, lease?: CleanupLease): Promise<void>;
+}
+/**
+ * Durable store for the evidence + manifest a run leaves behind. `finalize`
+ * MUST be idempotent by `evidence.operationId` — a retry / restart that
+ * re-finalizes the same operation is a no-op (or an upsert), never a duplicate.
+ * Ideally the host writes both in one transaction (with the terminal run
+ * transition); the framework tolerates a `finalizing` intermediate + re-run.
+ */
+interface CleanupEvidenceStore {
+  finalize(input: {
+    evidence: PurgeEvidence;
+    manifest: CleanupManifest;
+  }): Promise<void>;
+}
+/** A serializable job — everything the worker needs is the run id. */
+interface CleanupJob {
+  readonly runId: string;
+}
+/**
+ * Durable job queue (§8). `execute()` enqueues a `{ runId }`; a worker later
+ * dequeues and calls `service.processRun(runId)` — a DIFFERENT process can do
+ * this because the run carries the whole sealed operation. The default in-proc
+ * queue defers to a microtask (still off the request path within one process);
+ * production injects BullMQ / SQS / a repo-backed queue for cross-process
+ * durability, claim/lease, and restart recovery.
+ */
+interface CleanupJobQueue {
+  enqueue(job: CleanupJob): Promise<void>;
+}
+/**
+ * A company/target write fence (§8) — blocks new writes for the duration of a
+ * destructive run. Acquire/release keyed by the operation id so a crashed run's
+ * fence is recoverable by op id.
+ *
+ * `acquire` MAY return a fencing token; when it does, the service passes the
+ * SAME token back to `release`, and the fence MUST refuse a release carrying a
+ * stale token. This closes the distributed race where a stalled ex-owner wakes
+ * after lease expiry and releases the fence out from under the new owner.
+ * Implementations without cross-process workers may return `undefined` and
+ * ignore the token.
+ */
+interface CleanupWriteFence {
+  acquire(operationId: string): Promise<string | undefined | void>;
+  release(operationId: string, token?: string): Promise<void>;
+}
+interface CleanupPermissions {
+  /** May preview/observe runs. */
+  view: CleanupPermissionCheck;
+  /** May execute a run. Superadmin in the reference host. */
+  execute: CleanupPermissionCheck;
+  /** May cancel/retry a run. Defaults to `execute` when omitted. */
+  manage?: CleanupPermissionCheck;
+}
+/** Host permission predicate — receives whatever the host passes as the request scope. */
+type CleanupPermissionCheck = (scope: unknown) => boolean | Promise<boolean>;
+/** Framework size caps that keep runs + documents bounded (design "memory"). */
+interface CleanupLimits {
+  /** Max plan items. Default 500. */
+  readonly maxPlanItems: number;
+  /** Max per-run result rows folded into the manifest. Default 1000. */
+  readonly maxResults: number;
+  /** Max verification checks. Default 200. */
+  readonly maxChecks: number;
+  /** Max reason string length. Default 2000. */
+  readonly maxReasonLength: number;
+  /** Max nesting depth of the parameters object. Default 8. */
+  readonly maxParamDepth: number;
+}
+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 };

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

@@ -95,6 +95,56 @@ declare function getUserRoles(user: {
 } | null | undefined): string[];
 //#endregion
 //#region src/permissions/types.d.ts
+/**
+ * Row-level data policy — the constraint every returned/queried row must
+ * satisfy. This is arc's **Mongo-style record dialect** (`{ ownerId }`,
+ * `{ $or: [...] }`, `{ status: { $ne: "archived" } }`), the ONE canonical
+ * internal representation every permission helper emits and every enforcement
+ * seam composes (`conjoinPolicyFilters`).
+ *
+ * It is compiled to the portable repo-core `Filter` IR at the repository
+ * boundary (`core/repositoryFilter.ts` → `policyRecordToFilter`) so it runs
+ * identically on Mongo / SQL / any kit — arc's answer to oso-style "data
+ * filtering" + Postgres RLS, but datastore-portable and in-process. The IR is a
+ * boundary/compile concern, NOT the decision surface: keeping the decision in
+ * one record dialect means composition (`allOf`/`anyOf`/`conjoin`) has a single
+ * well-defined shape instead of a `Filter | Record` union the composer can't
+ * honor.
+ */
+type DataPolicy = Record<string, unknown>;
+/**
+ * The canonical authorization decision (arc 2.30). A single typed value that
+ * cleanly separates the concerns a permission check expresses:
+ *
+ *  - `effect` — allow / deny (Cedar / XACML decision)
+ *  - `reason` — human-readable diagnostic for the denial (explainability)
+ *  - `policy` — row-level {@link DataPolicy} to enforce at the repository
+ *  - `scope`  — identity/context to install on the request (PIP)
+ *
+ * Build one with the `allow()` / `deny()` constructors. A check may also return
+ * a bare `boolean` (terse allow/deny), normalized via `normalizeToDecision`.
+ *
+ * NOTE: arc deliberately does NOT model XACML-style "obligations" on the
+ * decision. Audit and field redaction are first-class arc subsystems already
+ * (`audit: true` on a resource; field-level read/write permissions), so an
+ * obligations channel would be a second, unenforced way to ask for the same
+ * effects. If a future need arises it will ship WITH a dispatcher that every
+ * enforcement surface runs — never as a declared-but-ignored contract.
+ */
+interface AuthorizationDecision {
+  /** Allow or deny. */
+  effect: "allow" | "deny";
+  /** Human-readable denial reason (surfaced in error messages / explain). */
+  reason?: string;
+  /** Row-level data policy to enforce at the repository layer. */
+  policy?: DataPolicy;
+  /**
+   * Scope to install on `request.scope` when allowed — flows to
+   * `metadata._scope` for tenant-field filtering. The clean integration point
+   * for custom auth (API keys, service accounts, gateway headers).
+   */
+  scope?: RequestScope;
+}
 /**
  * User base interface - minimal shape Arc expects
  * Your actual User can have any additional fields
@@ -107,25 +157,33 @@ interface UserBase {
   [key: string]: unknown;
 }
 /**
- * Extract normalized roles from a user object.
+ * Context passed to permission check functions.
  *
- * Reads `user.role` which can be:
- * - A comma-separated string: `"superadmin,user"` (Better Auth admin plugin)
- * - A string array: `["admin", "user"]` (JWT / custom auth)
- * - A single string: `"admin"`
- */
-/**
- * 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.
- */
-/**
- * Context passed to permission check functions
+ * arc 2.30: checks read FACTS off this context — never off a raw request. Use
+ * `scopeOf(ctx)` (from `./context.js`) to read the scope; it prefers the
+ * first-class {@link PermissionContext.scope} and lets combinators thread an
+ * updated scope to child checks WITHOUT mutating the request. `request` is a
+ * transport escape hatch (present for HTTP; absent for MCP/jobs/ws) and is being
+ * retired as the primary channel.
  */
 interface PermissionContext<TDoc = Record<string, unknown>> {
   /** Authenticated user or null if unauthenticated */
   user: UserBase | null;
-  /** Fastify request object */
-  request: FastifyRequest;
+  /**
+   * Resolved request scope (identity + tenant/org context). First-class so
+   * combinators can thread an accumulated scope purely and non-HTTP transports
+   * need no request. Read via `scopeOf(ctx)`.
+   */
+  scope?: RequestScope;
+  /**
+   * Raw Fastify request — transport escape hatch, present ONLY on the HTTP
+   * surface. It is `undefined` for MCP, jobs, and any non-Fastify transport, so
+   * a permission check must NOT depend on it: read identity via `scopeOf(ctx)`,
+   * inputs via `ctx.data` / `ctx.params`, and host facts via `ctx.attributes`.
+   * Kept solely for genuinely HTTP-coupled checks (e.g. a usage meter on
+   * `request.server`) which are inherently transport-specific.
+   */
+  request?: FastifyRequest;
   /** Resource name being accessed */
   resource: string;
   /** Action being performed (list, get, create, update, delete, or custom operation name) */
@@ -136,93 +194,40 @@ interface PermissionContext<TDoc = Record<string, unknown>> {
   params?: Record<string, string>;
   /** Request body data */
   data?: Partial<TDoc> | Record<string, unknown>;
-}
-/**
- * Result from a permission check.
- *
- * Permission checks can do three things:
- * 1. **Grant or deny** access (`granted`, `reason`)
- * 2. **Attach row-level filters** (`filters`) — these merge into `_policyFilters`
- *    and narrow subsequent queries (e.g. `{ userId: ctx.user.id }` for ownership)
- * 3. **Install the request scope** (`scope`) — when a custom authenticator wants
- *    to set tenant/identity context directly from the permission layer, without
- *    relying on a separate auth plugin
- *
- * The `scope` field is the clean integration point for custom auth strategies
- * (API keys, service accounts, gateway headers). When present, Arc writes it to
- * `request.scope` which then flows through the normal tenant-filtering pipeline
- * (QueryResolver + AccessControl). This is the idiomatic way to wire non-Better-Auth
- * identity providers into Arc's multi-tenancy without touching the auth plugin layer.
- *
- * @example
- * ```typescript
- * // Custom API-key auth — grant access AND install a service scope in one step
- * export function requireApiKey(): PermissionCheck {
- *   return async ({ request }) => {
- *     const apiKey = request.headers['x-api-key'] as string | undefined;
- *     if (!apiKey) return { granted: false, reason: 'Missing API key' };
- *
- *     const client = await ClientModel.findOne({ apiKey });
- *     if (!client) return { granted: false, reason: 'Invalid API key' };
- *
- *     return {
- *       granted: true,
- *       // Install service scope — Arc writes this to request.scope automatically,
- *       // and tenantField filtering picks it up via metadata._scope
- *       scope: {
- *         kind: 'service',
- *         clientId: String(client._id),
- *         organizationId: String(client.companyId),
- *         scopes: client.allowedScopes,
- *       },
- *       // Optional row-level narrowing (e.g. per-project API keys)
- *       filters: client.projectId ? { projectId: client.projectId } : undefined,
- *     };
- *   };
- * }
- * ```
- */
-interface PermissionResult {
-  /** Whether access is granted */
-  granted: boolean;
-  /** Reason for denial (for error messages) */
-  reason?: string;
-  /** Query filters to apply (for ownership / row-level security patterns) */
-  filters?: Record<string, unknown>;
   /**
-   * Install this scope on `request.scope` when granted. Flows through to
-   * `metadata._scope` and is read by QueryResolver / AccessControl for
-   * tenant-field filtering. Use this to wire custom auth (API keys, service
-   * accounts, gateway headers) into Arc's multi-tenancy without a separate
-   * auth plugin.
+   * Transport/host-supplied attributes a check may need for ABAC decisions
+   * (headers, claims, feature flags) without reaching into the raw request.
    */
-  scope?: RequestScope;
+  attributes?: Readonly<Record<string, unknown>>;
 }
 /**
- * Permission Check Function
+ * Permission Check Function — THE way to define permissions in Arc.
  *
- * THE ONLY way to define permissions in Arc.
- * Returns boolean, PermissionResult, or Promise of either.
+ * Returns a `boolean` (terse allow/deny) or an {@link AuthorizationDecision}
+ * (effect + optional data `policy` and `scope`). Build decisions with the
+ * `allow()` / `deny()` constructors from `@classytic/arc/permissions`.
  *
  * @example
  * ```typescript
- * // Simple boolean return
+ * // Simple boolean
  * const isAdmin: PermissionCheck = (ctx) => getUserRoles(ctx.user).includes('admin');
  *
- * // With filters for ownership
- * const ownedByUser: PermissionCheck = (ctx) => ({
- *   granted: true,
- *   filters: { userId: ctx.user?.id }
- * });
+ * // Grant + row-level data policy (ownership)
+ * const ownedByUser: PermissionCheck = (ctx) =>
+ *   allow({ policy: { userId: ctx.user?.id } });
  *
- * // Async check
- * const canAccessOrg: PermissionCheck = async (ctx) => {
- *   const isMember = await checkMembership(ctx.user?.id, ctx.organizationId);
- *   return { granted: isMember, reason: isMember ? undefined : 'Not a member' };
+ * // Custom API-key auth — grant AND install a service scope
+ * const requireApiKey: PermissionCheck = async ({ request }) => {
+ *   const client = await lookup(request.headers['x-api-key']);
+ *   if (!client) return deny('Invalid API key');
+ *   return allow({
+ *     scope: { kind: 'service', clientId: String(client._id), organizationId: String(client.companyId) },
+ *     ...(client.projectId ? { policy: { projectId: client.projectId } } : {}),
+ *   });
  * };
  * ```
  */
-type PermissionCheck<TDoc = Record<string, unknown>> = ((context: PermissionContext<TDoc>) => boolean | PermissionResult | Promise<boolean | PermissionResult>) & PermissionCheckMeta;
+type PermissionCheck<TDoc = Record<string, unknown>> = ((context: PermissionContext<TDoc>) => boolean | AuthorizationDecision | Promise<boolean | AuthorizationDecision>) & PermissionCheckMeta;
 /**
  * Optional metadata attached to permission check functions.
  * Used for OpenAPI data, introspection, and route-level auth decisions.
@@ -287,4 +292,4 @@ interface PermissionCheckMeta {
   };
 }
 //#endregion
-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 };
+export { UserBase as a, normalizeRoles as c, JWTPayload as d, ObjectId as f, PermissionContext as i, AnyRecord as l, UserOrganization as m, DataPolicy as n, getUserId as o, UserLike as p, PermissionCheck as r, getUserRoles as s, AuthorizationDecision as t, ArcRequest as u };