@ordinatio/trash 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ordinatio
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,35 @@
-# Temporary Holding Version
+# @ordinatio/trash
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A Trash for any product, with no database, no framework and no brand. A row that is deleted stays with `deletedAt` set; this package holds the parts every product repeats: the helpers that say "only live rows", the trash and restore state machine, the paging of the Trash list, the operator erase pipeline, and (on its own subpath) a scanner that finds reads which forgot to leave the Trash out. The product wires its tables in through small ports; the package never opens a connection, reads the clock or imports Prisma.
+
+Three entries:
+
+- `@ordinatio/trash` (main; imports nothing, not even `typescript`)
+- `@ordinatio/trash/scan` (the syntax-tree scanner; needs the `typescript` package, an optional peer, and node:fs)
+- `@ordinatio/trash/cli` (the command-line rules of the erase script; reads node:util)
+
+## Main entry
+
+- `live(where)` / `trashedOnly(where)`: the `where` with `deletedAt` overwritten by `null` / `{ not: null }`. The input is never changed.
+- `createTrashService(ports)` returns `{ trash(organizationId, id, actorId), restore(organizationId, id) }`. Each call is one short transaction: limit the lock wait, lock the row, read it in ANY state, then a compare-and-set that returns how many rows it changed. Outcomes are values: `trashed` (with `before` and `deletedAt`), `alreadyTrashed`, `notFound`, `restored` (with `before`), `notTrashed`. Exactly one of ten parallel clicks wins. A lock timeout or any other fault THROWS, unchanged. Every port call carries the `organizationId`, so another organization's id is `notFound`.
+  - ports: `runTransaction(work, options)`, `limitLockWait(tx, ms)`, `transaction` (the options), `lockWaitMs`, `lock(tx, orgId, id)`, `readAnyState(tx, orgId, id)`, `markTrashed(tx, orgId, id, deletedAt, actorId)` and `markRestored(tx, orgId, id)` (both return the changed count), `now()`.
+- `pageWindow(request, maxPageSize, defaultPageSize = 50)`: `{ page, pageSize, skip, take }` for a Trash list; the size is clamped to 1..max, the page to 1 or more.
+- The erase pipeline for an operator who erases rows that are already in the Trash:
+  - `buildPlan(deps, db, options)`: READ-ONLY dry run. Each named id (or the trashed rows, for `--all`) becomes `erasable`, `already-erased` (an earlier audit entry), `scrub-only` (only old activity text is left), or `refused` (live, in another organization, or not found). Also gives the paste-ready confirm command.
+  - `formatPlan(plan, options, mode, hooks)`, `planExitCode(plan)`, `buildConfirmCommand(prefix, options, ids)`, `DRY_RUN_LAST_LINE`.
+  - `erase(deps, db, plan, options)`: ONE transaction per row: bounded lock wait, the model's guarded delete (still in the Trash?), scrub of the linked Activity text, recently-viewed removal and the content-free audit entry INSIDE the transaction, so a failed audit rolls the erase back. A lock timeout is `refused` with "busy, retry"; any other failure is `failed` and rolled back.
+  - `summarize(results, confirmed, caveats)`: lines and the exit code (0 only when every id is erased, already erased or scrubbed).
+  - `createPurge(deps)` binds the two to your ports. `deps` = `{ store, planners, erasers, commandPrefix }`: `store` holds the shared statements (organization, recently-viewed, audit, transaction runner, `isBusy`), `planners` and `erasers` are one per model (`ModelPlanner`, `Eraser`), keyed by the model's `noun`.
+  - `escapeLike(text)` for ILIKE searches.
+
+## Scan entry
+
+`scanSource(file, text, relations, models)`, `scanTree(root, models, where?)`, `sourceFiles(root, dir?)`, `countMarkers(root, dir?)`, `relationMapOf(schemaText)`, `modelOfDelegate`, `delegateOf`. It reads TypeScript as a syntax tree and reports each Prisma-style read of a trashable model that is not limited with `live(...)`/`trashedOnly(...)` or `deletedAt: null`, unless a `// trash-ok(<Model>): <reason naming organizationId scoping>` comment is directly above it. Site kinds: `read`, `dynamic`, `raw`, `nested`, `stale-marker`, `weak-marker`.
+
+## CLI entry
+
+`parseTrashArgs(argv, models, defaultOperator)` refuses everything unsafe before any database is touched (no organization, no selector, `--confirm` without named ids, `--all` with `--confirm`, a reason that is not a ticket reference). `models` is `[{ model, handler | 'not-trashable-yet' }]`.
+
+## Guard rails
+
+A source scan in the package's tests (a guard rail, not a proof) fails on `process.`, the wall clock, `fetch`, `@prisma/client` and any import other than the ones named above; a build test checks that the built main entry imports nothing at all.

package/dist/cli.d.ts

@@ -0,0 +1,21 @@
+import { H as Handler, P as PurgeOptions } from './purge-types-CSptXruj.js';
+
+/** A ticket reference: letters, digits and . _ : / # - only, 10 to 200 characters. No spaces and no `@`, which keeps most names and every email address out. */
+declare const REASON_PATTERN: RegExp;
+declare const PURGE_ALL_CAP = 50;
+/** One Trash-enabled model: its own name (as the schema calls it) and its handler, or 'not-trashable-yet' when it has no eraser. */
+type ModelHandler<Model extends string, H extends Handler> = {
+    model: Model;
+    handler: H | 'not-trashable-yet';
+};
+type ParsedTrashArgs<Model extends string, H extends Handler> = {
+    ok: true;
+    options: PurgeOptions<Model, H>;
+} | {
+    ok: false;
+    error: string;
+};
+/** Reads and validates the command line. Never touches the database. `models` is in the order the error message lists them. */
+declare function parseTrashArgs<Model extends string, H extends Handler>(argv: string[], models: ReadonlyArray<ModelHandler<Model, H>>, defaultOperator: string): ParsedTrashArgs<Model, H>;
+
+export { type ModelHandler, PURGE_ALL_CAP, type ParsedTrashArgs, REASON_PATTERN, parseTrashArgs };

package/dist/cli.js

@@ -0,0 +1,62 @@
+// src/cli.ts
+import { parseArgs } from "util";
+var REASON_PATTERN = /^[A-Za-z0-9._:/#-]{10,200}$/;
+var PURGE_ALL_CAP = 50;
+var ID_PATTERN = /^[A-Za-z0-9_-]{1,64}$/;
+var OPERATOR_PATTERN = /^[A-Za-z0-9._-]{1,64}$/;
+var refuse = (error) => ({ ok: false, error });
+function parseTrashArgs(argv, models, defaultOperator) {
+  let values;
+  try {
+    values = parseArgs({
+      args: argv,
+      strict: true,
+      allowPositionals: false,
+      options: {
+        org: { type: "string" },
+        model: { type: "string" },
+        id: { type: "string", multiple: true },
+        all: { type: "boolean" },
+        limit: { type: "string" },
+        confirm: { type: "boolean" },
+        reason: { type: "string" },
+        operator: { type: "string" }
+      }
+    }).values;
+  } catch (error) {
+    return refuse(error instanceof Error ? error.message : "Could not read the arguments.");
+  }
+  const organizationId = typeof values.org === "string" ? values.org : "";
+  if (!ID_PATTERN.test(organizationId)) return refuse("--org <organizationId> is required (letters, digits, - and _ only).");
+  const modelArg = typeof values.model === "string" ? values.model.toLowerCase() : "";
+  const noun = (entry2) => entry2.handler === "not-trashable-yet" ? entry2.model.toLowerCase() : entry2.handler.noun;
+  const entry = models.find((m) => noun(m) === modelArg);
+  if (!entry) return refuse(`--model must be one of: ${models.map(noun).join(", ")}.`);
+  const handler = entry.handler;
+  if (handler === "not-trashable-yet") return refuse(`The ${modelArg} model has no eraser yet (it is not Trash-enabled): nothing can be erased for it.`);
+  const rawIds = Array.isArray(values.id) ? values.id.filter((v) => typeof v === "string") : [];
+  for (const id of rawIds) if (!ID_PATTERN.test(id)) return refuse(`Not a valid id: "${id.slice(0, 80)}".`);
+  const ids = [...new Set(rawIds)];
+  const all = values.all === true;
+  const confirm = values.confirm === true;
+  if (ids.length === 0 && !all) return refuse("Name what to erase: one or more --id <id>, or --all (dry run only).");
+  if (ids.length > 0 && all) return refuse("Use either --id or --all, not both.");
+  if (all && confirm) return refuse("--all is for the dry run only; --confirm needs the ids you read in the dry run (--id <id> ...).");
+  let limit = PURGE_ALL_CAP;
+  if (typeof values.limit === "string") {
+    if (!all) return refuse("--limit only applies together with --all (it caps how many trashed rows are listed).");
+    if (!/^\d{1,3}$/.test(values.limit) || Number(values.limit) < 1 || Number(values.limit) > PURGE_ALL_CAP) return refuse(`--limit must be a whole number from 1 to ${PURGE_ALL_CAP}.`);
+    limit = Number(values.limit);
+  }
+  const reason = typeof values.reason === "string" ? values.reason : null;
+  if (reason !== null && !REASON_PATTERN.test(reason)) return refuse("--reason must be a ticket reference (letters, digits and . _ : / # - only, 10 to 200 characters; no spaces or @), for example ERASE-2026-10-15-117. It is shown to everyone in the workspace, so it should be a ticket reference, not a name.");
+  if (confirm && reason === null) return refuse("--confirm needs --reason <ticket reference>.");
+  const operator = typeof values.operator === "string" ? values.operator : defaultOperator;
+  if (!OPERATOR_PATTERN.test(operator)) return refuse("--operator must be 1 to 64 characters (letters, digits and . _ - only).");
+  return { ok: true, options: { organizationId, model: entry.model, handler, ids, all, limit, confirm, reason, operator } };
+}
+export {
+  PURGE_ALL_CAP,
+  REASON_PATTERN,
+  parseTrashArgs
+};

package/dist/index.d.ts

@@ -0,0 +1,137 @@
+import { a as PurgeStore, M as ModelPlanner, P as PurgeOptions, b as PlanResult, E as Eraser, c as PurgePlan, d as EraseResult, e as ErasableRow } from './purge-types-CSptXruj.js';
+export { A as AuditEntry, C as Cascade, f as EraseOutcome, H as Handler, R as RowPlan, g as RowRead } from './purge-types-CSptXruj.js';
+
+/** `where` limited to live rows. The `deletedAt` of the input is overwritten, so a caller cannot ask for trashed rows through it. The input is not changed. */
+declare function live<W extends object>(where: W): Omit<W, 'deletedAt'> & {
+    deletedAt: null;
+};
+/** `where` limited to rows in the Trash (the Trash page). The input is not changed. */
+declare function trashedOnly<W extends object>(where: W): Omit<W, 'deletedAt'> & {
+    deletedAt: {
+        not: null;
+    };
+};
+
+declare const DEFAULT_TRASHED_PAGE_SIZE = 50;
+type PageRequest = {
+    page?: number;
+    pageSize?: number;
+};
+type PageWindow = {
+    page: number;
+    pageSize: number;
+    skip: number;
+    take: number;
+};
+/**
+ * The page size is a whole number from 1 to `maxPageSize` (missing, zero or not a number gives `defaultPageSize`; a negative number gives 1; a fraction is rounded down); the page is a whole number from 1
+ * (missing, zero or not a number gives 1). `skip` and `take` are what a store's findMany takes.
+ */
+declare function pageWindow(request: PageRequest | undefined, maxPageSize: number, defaultPageSize?: number): PageWindow;
+
+type TransactionPorts<Tx, TOptions> = {
+    /** Runs `work` inside one database transaction opened with `options`; commits when `work` returns, rolls back when it throws. */
+    runTransaction<T>(work: (tx: Tx) => Promise<T>, options: TOptions): Promise<T>;
+    /** Sets the longest a statement of this transaction may wait for a row lock. Always the FIRST statement. */
+    limitLockWait(tx: Tx, ms: number): Promise<void>;
+    /** The transaction options (timeouts) of this model. */
+    transaction: TOptions;
+    /** The lock wait in milliseconds. */
+    lockWaitMs: number;
+};
+/** Opens the transaction, limits the lock wait first, then runs the work. Whatever throws, throws out. */
+declare function inLockedTransaction<Tx, TOptions, T>(ports: TransactionPorts<Tx, TOptions>, work: (tx: Tx) => Promise<T>): Promise<T>;
+
+/** What the service needs to know about a row: whether it is in the Trash. */
+type TrashRowState = {
+    deletedAt: Date | null;
+};
+type TrashStorePorts<S extends TrashRowState, Tx> = {
+    /** Takes the row lock in ANY state, scoped by organization (nothing happens when the row is not there). */
+    lock(tx: Tx, organizationId: string, id: string): Promise<void>;
+    /** Reads the row in ANY state (live or trashed), scoped by organization; null when it is not in this organization. */
+    readAnyState(tx: Tx, organizationId: string, id: string): Promise<S | null>;
+    /** Compare-and-set: sets deletedAt (and who did it) only where the row is still live in this organization. Returns how many rows changed (0 or 1). */
+    markTrashed(tx: Tx, organizationId: string, id: string, deletedAt: Date, actorId: string): Promise<number>;
+    /** Compare-and-set: clears deletedAt only where the row is still in the Trash of this organization. Returns how many rows changed (0 or 1). */
+    markRestored(tx: Tx, organizationId: string, id: string): Promise<number>;
+    /** The clock, read only after the row was found live. */
+    now(): Date;
+};
+type TrashOutcome<S extends TrashRowState> = {
+    kind: 'trashed';
+    before: S;
+    deletedAt: Date;
+} | {
+    kind: 'notFound';
+} | {
+    kind: 'alreadyTrashed';
+};
+type RestoreOutcome<S extends TrashRowState> = {
+    kind: 'restored';
+    before: S;
+} | {
+    kind: 'notFound';
+} | {
+    kind: 'notTrashed';
+};
+type TrashService<S extends TrashRowState> = {
+    /** Moves a live row to the Trash. `before` is the row as it was read (live). A lock timeout throws. */
+    trash(organizationId: string, id: string, actorId: string): Promise<TrashOutcome<S>>;
+    /** Brings a trashed row back. `before` is the row as it was read (trashed). A lock timeout throws. */
+    restore(organizationId: string, id: string): Promise<RestoreOutcome<S>>;
+};
+declare function createTrashService<S extends TrashRowState, Tx, TOptions>(ports: TrashStorePorts<S, Tx> & TransactionPorts<Tx, TOptions>): TrashService<S>;
+
+/** Escapes `\`, `%` and `_` so a searched text containing them matches only itself in an ILIKE ... ESCAPE '\'. */
+declare const escapeLike: (text: string) => string;
+type PlanDeps<R, Db extends R, Tx extends R, TOptions, X extends object> = {
+    store: PurgeStore<R, Db, Tx, TOptions>;
+    /** One planner per handler noun. */
+    planners: Record<string, ModelPlanner<R, X>>;
+    /** The command that runs the erase script, printed in the confirm command (for example `npx tsx scripts/purge-trashed.ts`). */
+    commandPrefix: string;
+};
+/** The exact command that erases what the dry run listed (ids that would change something), with the reason left for the operator to fill in. */
+declare function buildConfirmCommand(commandPrefix: string, options: Pick<PurgeOptions, 'organizationId' | 'handler'>, ids: string[]): string;
+/** 0 when nothing is refused; non-zero when any named id is refused. */
+declare const planExitCode: (plan: {
+    rows: Array<{
+        kind: string;
+    }>;
+}) => number;
+/** READ-ONLY: reads the organization, the named rows (or up to the cap of trashed rows for --all) and what an erase would touch. Writes nothing. */
+declare function buildPlan<R, Db extends R, Tx extends R, TOptions, X extends object = Record<never, never>>(deps: PlanDeps<R, Db, Tx, TOptions, X>, db: Db, options: PurgeOptions): Promise<PlanResult<X>>;
+
+type EraseDeps<R, Db extends R, Tx extends R, TOptions> = {
+    store: PurgeStore<R, Db, Tx, TOptions>;
+    /** One eraser per handler noun. */
+    erasers: Record<string, Eraser<Db, Tx, TOptions>>;
+};
+/** Executes a plan, one transaction per erasable row. Refused rows pass through unchanged. Needs a validated ticket reference (the argument parser checks it). */
+declare function erase<R, Db extends R, Tx extends R, TOptions, X extends object>(deps: EraseDeps<R, Db, Tx, TOptions>, db: Db, plan: PurgePlan<X>, options: Pick<PurgeOptions, 'organizationId' | 'handler' | 'operator' | 'reason'>): Promise<EraseResult[]>;
+
+type PurgeDeps<R, Db extends R, Tx extends R, TOptions, X extends object> = PlanDeps<R, Db, Tx, TOptions, X> & EraseDeps<R, Db, Tx, TOptions>;
+declare function createPurge<R, Db extends R, Tx extends R, TOptions, X extends object = Record<never, never>>(deps: PurgeDeps<R, Db, Tx, TOptions, X>): {
+    /** READ-ONLY dry run. */
+    buildPlan: (db: Db, options: PurgeOptions) => Promise<PlanResult<X>>;
+    /** One transaction per erasable row. */
+    erase: (db: Db, plan: PurgePlan<X>, options: Pick<PurgeOptions, "organizationId" | "handler" | "operator" | "reason">) => Promise<EraseResult[]>;
+};
+
+declare const DRY_RUN_LAST_LINE = "dry run: nothing was changed";
+type PlanFormatHooks<X extends object> = {
+    /** Extra lines for an erasable row, printed after its `extra` lines and before the "not scrubbed" line (a model-specific block, for example unlinked mail). */
+    afterExtra?: (row: ErasableRow<X>) => string[];
+};
+/** The lines the script prints for a plan. */
+declare function formatPlan<X extends object = Record<never, never>>(plan: PurgePlan<X>, options: Pick<PurgeOptions, 'limit'>, mode?: {
+    confirmed: boolean;
+}, hooks?: PlanFormatHooks<X>): string[];
+/** Lines for the terminal and the exit code: 0 only when every named id was erased, already erased or scrubbed; anything refused or failed (or nothing named) is non-zero. `caveats` (what "erased" means for this model) are printed after a confirmed run. */
+declare function summarize(results: EraseResult[], confirmed: boolean, caveats: readonly string[]): {
+    lines: string[];
+    exitCode: number;
+};
+
+export { DEFAULT_TRASHED_PAGE_SIZE, DRY_RUN_LAST_LINE, ErasableRow, type EraseDeps, EraseResult, Eraser, ModelPlanner, type PageRequest, type PageWindow, type PlanDeps, type PlanFormatHooks, PlanResult, type PurgeDeps, PurgeOptions, PurgePlan, PurgeStore, type RestoreOutcome, type TransactionPorts, type TrashOutcome, type TrashRowState, type TrashService, type TrashStorePorts, buildConfirmCommand, buildPlan, createPurge, createTrashService, erase, escapeLike, formatPlan, inLockedTransaction, live, pageWindow, planExitCode, summarize, trashedOnly };

package/dist/index.js

@@ -0,0 +1,234 @@
+// src/rows.ts
+function live(where) {
+  return { ...where, deletedAt: null };
+}
+function trashedOnly(where) {
+  return { ...where, deletedAt: { not: null } };
+}
+
+// src/paging.ts
+var DEFAULT_TRASHED_PAGE_SIZE = 50;
+function pageWindow(request, maxPageSize, defaultPageSize = DEFAULT_TRASHED_PAGE_SIZE) {
+  const options = request ?? {};
+  const pageSize = Math.max(1, Math.min(Math.floor(options.pageSize ?? defaultPageSize) || defaultPageSize, maxPageSize));
+  const page = Math.max(1, Math.floor(options.page ?? 1) || 1);
+  return { page, pageSize, skip: (page - 1) * pageSize, take: pageSize };
+}
+
+// src/transaction.ts
+function inLockedTransaction(ports, work) {
+  return ports.runTransaction(async (tx) => {
+    await ports.limitLockWait(tx, ports.lockWaitMs);
+    return work(tx);
+  }, ports.transaction);
+}
+
+// src/service.ts
+function createTrashService(ports) {
+  return {
+    trash: (organizationId, id, actorId) => inLockedTransaction(ports, async (tx) => {
+      await ports.lock(tx, organizationId, id);
+      const state = await ports.readAnyState(tx, organizationId, id);
+      if (!state) return { kind: "notFound" };
+      if (state.deletedAt !== null) return { kind: "alreadyTrashed" };
+      const deletedAt = ports.now();
+      const changed = await ports.markTrashed(tx, organizationId, id, deletedAt, actorId);
+      return changed === 1 ? { kind: "trashed", before: state, deletedAt } : { kind: "alreadyTrashed" };
+    }),
+    restore: (organizationId, id) => inLockedTransaction(ports, async (tx) => {
+      await ports.lock(tx, organizationId, id);
+      const state = await ports.readAnyState(tx, organizationId, id);
+      if (!state) return { kind: "notFound" };
+      if (state.deletedAt === null) return { kind: "notTrashed" };
+      const changed = await ports.markRestored(tx, organizationId, id);
+      return changed === 1 ? { kind: "restored", before: state } : { kind: "notTrashed" };
+    })
+  };
+}
+
+// src/purge-plan.ts
+var escapeLike = (text) => text.replace(/[\\%_]/g, (c) => `\\${c}`);
+function buildConfirmCommand(commandPrefix, options, ids) {
+  const idArgs = ids.map((id) => `--id ${id}`).join(" ");
+  return `${commandPrefix} --org ${options.organizationId} --model ${options.handler.noun} ${idArgs} --confirm --reason "<ticket reference>"`;
+}
+var planExitCode = (plan) => plan.rows.some((r) => r.kind === "refused") ? 1 : 0;
+function plannerOf(planners, noun) {
+  const planner = planners[noun];
+  if (!planner) throw new Error(`No planner for ${noun}.`);
+  return planner;
+}
+async function planRow(deps, db, options, id) {
+  const { organizationId, handler } = options;
+  const planner = plannerOf(deps.planners, handler.noun);
+  const row = await planner.read(db, organizationId, id);
+  if (row) {
+    if (row.deletedAt === null) return { kind: "refused", id, reason: `live: it is not in the Trash, and this script never erases a live ${handler.noun}` };
+    return {
+      kind: "erasable",
+      id,
+      title: row.label,
+      trashedBy: row.deletedBy,
+      trashedAt: row.deletedAt,
+      cascades: await planner.cascades(db, organizationId, id),
+      extra: await planner.extra(db, organizationId, id, row),
+      linkedActivity: await planner.linkedActivity(db, organizationId, id),
+      recentViews: await deps.store.countRecentViews(db, organizationId, handler.recentViewType, id),
+      quotingOthers: await planner.quotingOthers(db, organizationId, id, row.quoteTerms),
+      ...planner.enrich ? await planner.enrich(db, organizationId, id, row) : {}
+    };
+  }
+  const linkedActivity = await planner.linkedActivity(db, organizationId, id);
+  const recentViews = await deps.store.countRecentViews(db, organizationId, handler.recentViewType, id);
+  if (await deps.store.findEraseAudit(db, organizationId, handler.noun, id)) return { kind: "already-erased", id, linkedActivity, recentViews };
+  if (linkedActivity > 0) return { kind: "scrub-only", id, linkedActivity, recentViews };
+  return { kind: "refused", id, reason: await planner.existsAnywhere(db, id) ? "exists in another organization: nothing written" : "not found in this organization" };
+}
+async function buildPlan(deps, db, options) {
+  const organization = await deps.store.findOrganization(db, options.organizationId);
+  if (!organization) return { ok: false, error: `No organization with id ${options.organizationId}: nothing was read or changed.` };
+  let ids = options.ids;
+  let capped = false;
+  if (options.all) {
+    const trashed = await plannerOf(deps.planners, options.handler.noun).listTrashed(db, options.organizationId, options.limit + 1);
+    capped = trashed.length > options.limit;
+    ids = trashed.slice(0, options.limit);
+  }
+  const rows = [];
+  for (const id of ids) rows.push(await planRow(deps, db, options, id));
+  const actionable = rows.filter((r) => r.kind !== "refused").map((r) => r.id);
+  return {
+    ok: true,
+    plan: {
+      organizationId: organization.id,
+      organizationName: organization.name,
+      noun: options.handler.noun,
+      plural: options.handler.plural,
+      quoteSubject: options.handler.quoteSubject,
+      rows,
+      capped,
+      confirmCommand: actionable.length > 0 ? buildConfirmCommand(deps.commandPrefix, options, actionable) : null
+    }
+  };
+}
+
+// src/purge-erase.ts
+async function scrub(deps, eraser, tx, options, id) {
+  await eraser.scrubLinkedActivity(tx, options.organizationId, id, options.handler.scrubbedDescription);
+  await deps.store.removeRecentViews(tx, options.organizationId, options.handler.recentViewType, id);
+}
+async function writeAudit(deps, tx, options, id, scrubOnly) {
+  await deps.store.writeAudit(tx, {
+    organizationId: options.organizationId,
+    description: scrubOnly ? options.handler.scrubOnlyAuditDescription : options.handler.auditDescription,
+    metadata: { model: options.handler.noun, id, reason: options.reason, operator: options.operator, ...scrubOnly ? { kind: "scrub-only" } : {} }
+  });
+}
+async function eraseRow(deps, db, options, row) {
+  const { id, kind } = row;
+  const { organizationId, handler } = options;
+  const eraser = deps.erasers[handler.noun];
+  if (!eraser) throw new Error(`No eraser for ${handler.noun}.`);
+  let prepared;
+  try {
+    if (kind === "erasable" && eraser.prepare) prepared = await eraser.prepare(db, organizationId, id);
+  } catch (error) {
+    return { id, outcome: "failed", detail: `${error instanceof Error ? error.message : "unknown error"}: nothing was changed` };
+  }
+  const ports = { transaction: eraser.transaction, lockWaitMs: eraser.lockWaitMs, limitLockWait: deps.store.limitLockWait, runTransaction: (work, o) => deps.store.runTransaction(db, work, o) };
+  return inLockedTransaction(ports, async (tx) => {
+    if (kind === "erasable") {
+      const deleted = await eraser.deleteRow(tx, organizationId, id, prepared);
+      if (!deleted.deleted) return { id, outcome: "refused", detail: "no longer in the Trash (restored or already erased): nothing was changed" };
+      await scrub(deps, eraser, tx, options, id);
+      await writeAudit(deps, tx, options, id, false);
+      return { id, outcome: "erased", detail: `row, cascades, linked activity text and recently-viewed rows removed; audit entry written${deleted.note ?? ""}` };
+    }
+    if (await eraser.stillExists(tx, organizationId, id)) return { id, outcome: "refused", detail: `a ${handler.noun} with this id exists now: nothing was changed` };
+    const audited = await deps.store.findEraseAudit(tx, organizationId, handler.noun, id);
+    await scrub(deps, eraser, tx, options, id);
+    if (audited) return { id, outcome: "already-erased", detail: "linked activity text re-scrubbed; no new audit entry" };
+    await writeAudit(deps, tx, options, id, true);
+    return { id, outcome: "scrub-only", detail: "row was gone before this script (old delete); linked activity text scrubbed; audit entry written" };
+  }).catch((error) => {
+    if (deps.store.isBusy(error)) return { id, outcome: "refused", detail: "busy, retry: the database was busy or another request holds the row; nothing was changed" };
+    return { id, outcome: "failed", detail: `${error instanceof Error ? error.message : "unknown error"}: the erase was rolled back (if this was a dropped connection at commit, check the row before retrying)` };
+  });
+}
+async function erase(deps, db, plan, options) {
+  if (options.reason === null) throw new Error("erase needs a reason (a ticket reference).");
+  if (options.organizationId !== plan.organizationId) throw new Error("The plan belongs to another organization.");
+  if (options.handler.noun !== plan.noun) throw new Error("The plan was built for another kind of row.");
+  const confirmed = { organizationId: options.organizationId, handler: options.handler, operator: options.operator, reason: options.reason };
+  const results = [];
+  for (const row of plan.rows) {
+    results.push(row.kind === "refused" ? { id: row.id, outcome: "refused", detail: row.reason } : await eraseRow(deps, db, confirmed, row));
+  }
+  return results;
+}
+
+// src/purge.ts
+function createPurge(deps) {
+  return {
+    /** READ-ONLY dry run. */
+    buildPlan: (db, options) => buildPlan(deps, db, options),
+    /** One transaction per erasable row. */
+    erase: (db, plan, options) => erase(deps, db, plan, options)
+  };
+}
+
+// src/purge-format.ts
+var DRY_RUN_LAST_LINE = "dry run: nothing was changed";
+function formatPlan(plan, options, mode = { confirmed: false }, hooks = {}) {
+  const { plural, quoteSubject } = plan;
+  const out = [`Organization: ${plan.organizationName} (${plan.organizationId})`, `The audit line of a real erase shows in THIS organization's activity feed, with the ticket reference only.`];
+  if (plan.rows.length === 0) out.push(`No ${plural} are in the Trash of this organization.`);
+  for (const row of plan.rows) {
+    if (row.kind === "erasable") {
+      out.push(`ERASE ${plan.noun} ${row.id}: "${row.title}" (trashed${row.trashedBy ? ` by ${row.trashedBy}` : ""}${row.trashedAt ? ` on ${row.trashedAt.toISOString()}` : ""})`);
+      out.push(`  goes with it: ${row.cascades.map((c) => `${c.count} ${c.label}`).join(", ")}`);
+      out.push(`  activity entries linked to it, to be scrubbed: ${row.linkedActivity}; recently-viewed rows to remove: ${row.recentViews}`);
+      for (const line of row.extra) out.push(`  ${line}`);
+      for (const line of hooks.afterExtra?.(row) ?? []) out.push(`  ${line}`);
+      out.push(`  not scrubbed: review by hand: ${row.quotingOthers} OTHER entries whose description or metadata text contains ${quoteSubject} (both were searched)`);
+    } else if (row.kind === "already-erased") {
+      out.push(`ALREADY ERASED ${plan.noun} ${row.id}: an earlier run left its audit entry; ${row.linkedActivity} linked entries and ${row.recentViews} recently-viewed rows would be re-scrubbed (no new audit entry)`);
+    } else if (row.kind === "scrub-only") {
+      out.push(`SCRUB ONLY ${plan.noun} ${row.id}: row was gone before this script (old delete); ${row.linkedActivity} linked entries would be scrubbed and ${row.recentViews} recently-viewed rows removed, with one audit entry`);
+    } else out.push(`REFUSED ${plan.noun} ${row.id}: ${row.reason}`);
+  }
+  if (plan.capped) out.push(`Only the first ${options.limit} trashed ${plural} are listed (the cap); there are more.`);
+  if (mode.confirmed) return out;
+  if (plan.confirmCommand) out.push("To erase exactly these, run (fill in the ticket reference):", plan.confirmCommand);
+  out.push(DRY_RUN_LAST_LINE);
+  return out;
+}
+var TITLES = { erased: "Erased", "already-erased": "Already erased", "scrub-only": "Scrubbed (row was already gone)", refused: "REFUSED", failed: "FAILED" };
+function summarize(results, confirmed, caveats) {
+  const lines = [];
+  for (const outcome of Object.keys(TITLES)) {
+    for (const r of results.filter((x) => x.outcome === outcome)) lines.push(`${TITLES[outcome]}: ${r.id}: ${r.detail}`);
+  }
+  const good = results.filter((r) => r.outcome === "erased" || r.outcome === "already-erased" || r.outcome === "scrub-only").length;
+  const exitCode = results.length > 0 && good === results.length ? 0 : 1;
+  lines.push(`${good} of ${results.length} named ids are done${exitCode === 0 ? "." : "; the rest are listed above and need attention (exit code 1)."}`);
+  if (confirmed) lines.push(...caveats);
+  return { lines, exitCode };
+}
+export {
+  DEFAULT_TRASHED_PAGE_SIZE,
+  DRY_RUN_LAST_LINE,
+  buildConfirmCommand,
+  buildPlan,
+  createPurge,
+  createTrashService,
+  erase,
+  escapeLike,
+  formatPlan,
+  inLockedTransaction,
+  live,
+  pageWindow,
+  planExitCode,
+  summarize,
+  trashedOnly
+};

package/dist/purge-types-CSptXruj.d.ts

@@ -0,0 +1,160 @@
+/** What the generic erase code needs to know about one model. */
+type Handler<Noun extends string = string> = {
+    /** Lower-case name used on the command line (`--model <noun>`) and recorded as `metadata.model` of the audit entry. */
+    noun: Noun;
+    /** Plural used in printed lines ("No people are in the Trash"). */
+    plural: string;
+    /** What the by-hand count of OTHER Activity entries searches for ("the title", "the name or email"). */
+    quoteSubject: string;
+    /** The recently-viewed `entityType` of this model. */
+    recentViewType: string;
+    /** What the linked Activity entries say after the scrub. */
+    scrubbedDescription: string;
+    /** The audit entry's description for a row that was in the Trash. */
+    auditDescription: string;
+    /** The audit entry's description for an id whose row was already gone before the script existed. */
+    scrubOnlyAuditDescription: string;
+};
+type PurgeOptions<Model extends string = string, H extends Handler = Handler> = {
+    organizationId: string;
+    model: Model;
+    handler: H;
+    ids: string[];
+    all: boolean;
+    /** How many trashed rows `--all` may list (1 to PURGE_ALL_CAP). */
+    limit: number;
+    confirm: boolean;
+    reason: string | null;
+    operator: string;
+};
+type Cascade = {
+    key: string;
+    label: string;
+    count: number;
+};
+/** What a model's planner reads about one row: its printed label, its Trash state and the texts other Activity entries might quote. */
+type RowRead = {
+    label: string;
+    deletedAt: Date | null;
+    deletedBy: string | null;
+    quoteTerms: string[];
+    email?: string;
+};
+/** The per-model half of the dry run. Every method is READ-ONLY and every one that takes an organizationId scopes by it, except `existsAnywhere`. */
+type ModelPlanner<R, X extends object = Record<never, never>> = {
+    /** Reads a row in ANY state of the organization. */
+    read(db: R, organizationId: string, id: string): Promise<RowRead | null>;
+    /** What cascades from the row, one counter per approved cascade. */
+    cascades(db: R, organizationId: string, id: string): Promise<Cascade[]>;
+    /** Extra printed lines. `row` is what `read` returned. */
+    extra(db: R, organizationId: string, id: string, row: RowRead): Promise<string[]>;
+    /** The Activity entries linked to the id (they are scrubbed, never deleted). */
+    linkedActivity(db: R, organizationId: string, id: string): Promise<number>;
+    /** How many OTHER Activity entries only quote the row (reviewed by hand). */
+    quotingOthers(db: R, organizationId: string, id: string, quoteTerms: string[]): Promise<number>;
+    /** Does the id exist in ANOTHER organization (or any)? Existence only: the caller prints nothing but the refusal. */
+    existsAnywhere(db: R, id: string): Promise<boolean>;
+    /** Up to `take` ids in the Trash of the organization, newest trashed first. */
+    listTrashed(db: R, organizationId: string, take: number): Promise<string[]>;
+    /** Optional extra data for the plan row of an erasable row (merged into it, after `quotingOthers`); the product prints it through `PlanFormatHooks`. */
+    enrich?(db: R, organizationId: string, id: string, row: RowRead): Promise<X>;
+};
+/** The per-model half of the erase transaction. */
+type Eraser<Db, Tx, TOptions> = {
+    /** The transaction options (timeouts) of this model's erase. */
+    transaction: TOptions;
+    /** The bounded lock wait in milliseconds. */
+    lockWaitMs: number;
+    /** Lock the row, delete it only while it is STILL in the Trash of the organization, clear pointers without a foreign key. `deleted: false` (and nothing else touched) when it is no longer in the Trash. */
+    deleteRow(tx: Tx, organizationId: string, id: string, prepared: unknown): Promise<{
+        deleted: boolean;
+        note?: string;
+    }>;
+    /** Optional READ before the transaction; its result is handed to deleteRow. A throw reports the row as failed with nothing changed. */
+    prepare?(db: Db, organizationId: string, id: string): Promise<unknown>;
+    /** Replaces the text of the Activity entries linked to the id with `description` and clears their metadata (they are scrubbed, never deleted). */
+    scrubLinkedActivity(tx: Tx, organizationId: string, id: string, description: string): Promise<void>;
+    /** Does a row with this id exist now, in any state of this organization? */
+    stillExists(tx: Tx, organizationId: string, id: string): Promise<boolean>;
+};
+/** The content-free audit entry of an erase; the product adds its own action, severity and "system" flags. `metadata` never holds the erased content. */
+type AuditEntry = {
+    organizationId: string;
+    description: string;
+    metadata: {
+        model: string;
+        id: string;
+        reason: string;
+        operator: string;
+        kind?: 'scrub-only';
+    };
+};
+/** The store half the pipeline shares across models. */
+type PurgeStore<R, Db extends R, Tx extends R, TOptions> = {
+    findOrganization(db: Db, organizationId: string): Promise<{
+        id: string;
+        name: string;
+    } | null>;
+    countRecentViews(db: R, organizationId: string, entityType: string, id: string): Promise<number>;
+    /** The audit entry an earlier erase wrote for the id, if any (matched on organization, model and id). */
+    findEraseAudit(db: R, organizationId: string, noun: string, id: string): Promise<boolean>;
+    removeRecentViews(tx: Tx, organizationId: string, entityType: string, id: string): Promise<void>;
+    /** Writes the audit entry INSIDE the erase transaction; a failure must throw (it rolls the erase back). */
+    writeAudit(tx: Tx, entry: AuditEntry): Promise<void>;
+    runTransaction<T>(db: Db, work: (tx: Tx) => Promise<T>, options: TOptions): Promise<T>;
+    limitLockWait(tx: Tx, ms: number): Promise<void>;
+    /** True when the error means "busy, retry" (a lock timeout, a pool that could not start the transaction), false for a fault. */
+    isBusy(error: unknown): boolean;
+};
+type ErasableRow<X extends object = Record<never, never>> = {
+    kind: 'erasable';
+    id: string;
+    title: string;
+    trashedBy: string | null;
+    trashedAt: Date | null;
+    cascades: Cascade[];
+    extra: string[];
+    linkedActivity: number;
+    recentViews: number;
+    quotingOthers: number;
+} & X;
+type RowPlan<X extends object = Record<never, never>> = ErasableRow<X> | {
+    kind: 'already-erased';
+    id: string;
+    linkedActivity: number;
+    recentViews: number;
+} | {
+    kind: 'scrub-only';
+    id: string;
+    linkedActivity: number;
+    recentViews: number;
+} | {
+    kind: 'refused';
+    id: string;
+    reason: string;
+};
+type PurgePlan<X extends object = Record<never, never>> = {
+    organizationId: string;
+    organizationName: string;
+    noun: string;
+    plural: string;
+    quoteSubject: string;
+    rows: RowPlan<X>[];
+    capped: boolean;
+    confirmCommand: string | null;
+};
+type PlanResult<X extends object = Record<never, never>> = {
+    ok: true;
+    plan: PurgePlan<X>;
+} | {
+    ok: false;
+    error: string;
+};
+type EraseOutcome = 'erased' | 'already-erased' | 'scrub-only' | 'refused' | 'failed';
+type EraseResult = {
+    id: string;
+    outcome: EraseOutcome;
+    detail: string;
+};
+
+export type { AuditEntry as A, Cascade as C, Eraser as E, Handler as H, ModelPlanner as M, PurgeOptions as P, RowPlan as R, PurgeStore as a, PlanResult as b, PurgePlan as c, EraseResult as d, ErasableRow as e, EraseOutcome as f, RowRead as g };

package/dist/scan.d.ts

@@ -0,0 +1,29 @@
+/** parent model name -> (field name -> target model name). */
+type RelationMap = Map<string, Map<string, string>>;
+/** Builds the relation map from the text of schema.prisma. Comments are ignored; scalar, enum and native-typed fields are not relations. */
+declare function relationMapOf(schema: string): RelationMap;
+/** The client delegate name of a model: `Contact` -> `contact`, `EmailMessage` -> `emailMessage`. */
+declare const delegateOf: (model: string) => string;
+/** The model a delegate name belongs to, or undefined when no model has that delegate. */
+declare function modelOfDelegate(map: RelationMap, delegate: string): string | undefined;
+
+type SiteKind = 'read' | 'dynamic' | 'raw' | 'nested' | 'stale-marker' | 'weak-marker';
+type Site = {
+    file: string;
+    line: number;
+    kind: SiteKind;
+    model: string;
+    message: string;
+};
+declare function scanSource(file: string, text: string, relations: RelationMap, models: readonly string[]): Site[];
+/** Every non-test source file under `dir` (relative to the project root). */
+declare function sourceFiles(root: string, dir?: string): string[];
+/** Scans the whole tree for the given models. The schema is read from `prisma/schema.prisma` and the sources from `src`, unless `where` says otherwise. */
+declare function scanTree(root: string, models: readonly string[], where?: {
+    schemaPath?: string;
+    sourceDir?: string;
+}): Site[];
+/** How many `// trash-ok` markers the source tree holds (the test pins this number so an addition shows in a diff). */
+declare function countMarkers(root: string, sourceDir?: string): number;
+
+export { type RelationMap, type Site, type SiteKind, countMarkers, delegateOf, modelOfDelegate, relationMapOf, scanSource, scanTree, sourceFiles };

package/dist/scan.js

@@ -0,0 +1,222 @@
+// src/scan.ts
+import { readdirSync, readFileSync, statSync } from "fs";
+import { join } from "path";
+import ts from "typescript";
+
+// src/scan-schema.ts
+function relationMapOf(schema) {
+  const clean = schema.replace(/(^|\s)\/\/.*$/gm, "$1");
+  const models = /* @__PURE__ */ new Map();
+  for (const m of clean.matchAll(/^model (\w+) \{([\s\S]*?)^\}/gm)) models.set(m[1], m[2]);
+  const map = /* @__PURE__ */ new Map();
+  for (const [name, text] of models) {
+    const fields = /* @__PURE__ */ new Map();
+    for (const line of text.split("\n")) {
+      const field = /^\s*(\w+)\s+(\w+)(\[\]|\?)?(\s|$)/.exec(line);
+      if (field && models.has(field[2])) fields.set(field[1], field[2]);
+    }
+    map.set(name, fields);
+  }
+  return map;
+}
+var delegateOf = (model) => model.charAt(0).toLowerCase() + model.slice(1);
+function modelOfDelegate(map, delegate) {
+  return [...map.keys()].find((model) => delegateOf(model) === delegate);
+}
+
+// src/scan.ts
+var NESTED_ONLY_OPS = /* @__PURE__ */ new Set(["create", "update", "upsert", "delete"]);
+var READ_OPS = /* @__PURE__ */ new Set(["findMany", "findFirst", "findFirstOrThrow", "findUnique", "findUniqueOrThrow", "count", "groupBy", "aggregate"]);
+var RAW_CALLS = /* @__PURE__ */ new Set(["$queryRaw", "$queryRawUnsafe", "$executeRaw", "$executeRawUnsafe"]);
+var MARKER = /^\s*\/\/\s*trash-ok\((\w+)\):\s*(.*)$/;
+var HOW = "wrap its where in live(...) or add `// trash-ok(<Model>): <reason that names its organizationId scoping>` directly above it";
+var HOW_DYNAMIC = "the model is chosen at run time, so live(...) cannot be checked: add `// trash-ok(dynamic): <reason that names its organizationId scoping and how trashed rows are handled>` directly above it";
+var unwrap = (node) => ts.isParenthesizedExpression(node) || ts.isAsExpression(node) || ts.isNonNullExpression(node) || ts.isTypeAssertionExpression(node) ? unwrap(node.expression) : node;
+var propName = (p) => p.name && (ts.isIdentifier(p.name) || ts.isStringLiteral(p.name)) ? p.name.text : void 0;
+var propsOf = (obj) => obj && ts.isObjectLiteralExpression(unwrap(obj)) ? unwrap(obj).properties : [];
+var isNull = (node) => unwrap(node).kind === ts.SyntaxKind.NullKeyword;
+var isNotNull = (node) => {
+  const value = unwrap(node);
+  return ts.isObjectLiteralExpression(value) && value.properties.some((p) => ts.isPropertyAssignment(p) && propName(p) === "not" && isNull(p.initializer));
+};
+var isScope = (n) => ts.isBlock(n) || ts.isSourceFile(n) || ts.isCaseBlock(n) || ts.isModuleBlock(n);
+function scanSource(file, text, relations, models) {
+  if (models.length === 0) return [];
+  const source = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true, file.endsWith("x") ? ts.ScriptKind.TSX : ts.ScriptKind.TS);
+  const lines = text.split("\n");
+  const lineOf = (node) => source.getLineAndCharacterOfPosition(node.getStart(source)).line + 1;
+  const sites = [];
+  const markers = [];
+  lines.forEach((content, index) => {
+    const m = MARKER.exec(content);
+    if (m) markers.push({ line: index + 1, model: m[1], reason: m[2], used: false });
+  });
+  const markerAbove = (line, model) => {
+    for (let at = line - 1; at >= 1; at--) {
+      const marker = markers.find((m) => m.line === at);
+      if (!marker) return void 0;
+      if (marker.model === model) return marker;
+    }
+    return void 0;
+  };
+  const declared = /* @__PURE__ */ new Map();
+  const collect = (n) => {
+    if (ts.isVariableDeclaration(n) && ts.isIdentifier(n.name) && n.initializer) {
+      let scope = n.parent;
+      while (scope && !isScope(scope)) scope = scope.parent;
+      if (scope) {
+        const byName = declared.get(scope) ?? /* @__PURE__ */ new Map();
+        byName.set(n.name.text, [...byName.get(n.name.text) ?? [], n.initializer]);
+        declared.set(scope, byName);
+      }
+    }
+    ts.forEachChild(n, collect);
+  };
+  collect(source);
+  const declarationsOf = (id) => {
+    for (let scope = id.parent; scope; scope = scope.parent) {
+      const found = isScope(scope) ? declared.get(scope)?.get(id.text) : void 0;
+      if (found) return found;
+    }
+    return [];
+  };
+  const resolved = (value) => {
+    const inner = unwrap(value);
+    return ts.isIdentifier(inner) ? [inner, ...declarationsOf(inner)] : [inner];
+  };
+  const filteredWhere = (node, depth = 0) => {
+    const e = unwrap(node);
+    if (ts.isCallExpression(e)) return ts.isIdentifier(e.expression) && (e.expression.text === "live" || e.expression.text === "trashedOnly");
+    if (ts.isIdentifier(e)) return depth < 3 && declarationsOf(e).some((d) => filteredWhere(d, depth + 1));
+    if (ts.isArrayLiteralExpression(e)) return e.elements.some((el) => filteredWhere(el, depth + 1));
+    if (!ts.isObjectLiteralExpression(e)) return false;
+    return e.properties.some((p, index) => {
+      if (e.properties.slice(index + 1).some((later) => ts.isSpreadAssignment(later))) return false;
+      if (ts.isSpreadAssignment(p)) return filteredWhere(p.expression, depth + 1);
+      if (!ts.isPropertyAssignment(p)) return false;
+      const key = propName(p);
+      if (key === "deletedAt") return isNull(p.initializer) || isNotNull(p.initializer);
+      return key === "AND" ? filteredWhere(p.initializer, depth + 1) : false;
+    });
+  };
+  const report = (node, kind, model, why) => {
+    const line = lineOf(node);
+    if (kind === "stale-marker" || kind === "weak-marker") {
+      sites.push({ file, line, kind, model, message: `${file}:${line} ${why}` });
+      return;
+    }
+    const marker = markerAbove(line, kind === "dynamic" ? "dynamic" : model);
+    if (marker) {
+      marker.used = true;
+      if (marker.reason.trim().length < 10 || !/organizationId|org-scoped/.test(marker.reason)) sites.push({ file, line: marker.line, kind: "weak-marker", model, message: `${file}:${marker.line} trash-ok(${marker.model}) needs a reason of 10+ characters that names its organizationId scoping` });
+      return;
+    }
+    sites.push({ file, line, kind, model, message: kind === "dynamic" ? `${file}:${line} ${why}: ${HOW_DYNAMIC}` : `${file}:${line} ${why} without a trash filter: ${HOW}` });
+  };
+  const whereFiltered = (args) => {
+    for (const p of propsOf(args[0])) {
+      if (propName(p) !== "where") continue;
+      const value = ts.isShorthandPropertyAssignment(p) ? p.name : ts.isPropertyAssignment(p) ? p.initializer : void 0;
+      if (value && filteredWhere(value)) return true;
+    }
+    return false;
+  };
+  const checkNested = (parentModel, args, call) => {
+    const walk = (parent, node) => {
+      for (const p of propsOf(node)) {
+        const key = propName(p);
+        if (key !== "include" && key !== "select") continue;
+        const holder = ts.isShorthandPropertyAssignment(p) ? p.name : ts.isPropertyAssignment(p) ? p.initializer : void 0;
+        for (const group of holder ? resolved(holder) : []) {
+          for (const rel of propsOf(group)) {
+            const relName = propName(rel);
+            const target = relName ? relations.get(parent)?.get(relName) : void 0;
+            if (!relName || !target) continue;
+            const value = ts.isPropertyAssignment(rel) ? rel.initializer : void 0;
+            if (models.includes(target) && !(value && resolved(value).some((v) => propsOf(v).some((x) => propName(x) === "where" && ts.isPropertyAssignment(x) && filteredWhere(x.initializer))))) {
+              report(call, "nested", target, `${parent}.${relName} is included`);
+            }
+            if (value) walk(target, value);
+          }
+        }
+      }
+    };
+    walk(parentModel, args[0]);
+  };
+  const isDynamic = (callee) => {
+    const target = unwrap(callee.expression);
+    if (ts.isElementAccessExpression(target)) return !ts.isStringLiteral(target.argumentExpression);
+    if (ts.isIdentifier(target)) return declarationsOf(target).some((d) => ts.isElementAccessExpression(unwrap(d)) && !ts.isStringLiteral(unwrap(d).argumentExpression));
+    return false;
+  };
+  const rawModels = (literal) => models.filter((model) => literal.includes(`"${model}"`) && !literal.includes('"deletedAt"'));
+  const literalText = (node) => {
+    if (ts.isNoSubstitutionTemplateLiteral(node) || ts.isStringLiteral(node)) return node.text;
+    if (ts.isTemplateExpression(node)) return node.head.text + node.templateSpans.map((s) => s.literal.text).join(" ");
+    return void 0;
+  };
+  const visit = (node) => {
+    if (ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression)) {
+      const callee = node.expression;
+      const op = callee.name.text;
+      if (READ_OPS.has(op) || NESTED_ONLY_OPS.has(op)) {
+        const holder = unwrap(callee.expression);
+        const delegate = ts.isPropertyAccessExpression(holder) ? holder.name.text : void 0;
+        const model = delegate ? modelOfDelegate(relations, delegate) : void 0;
+        if (model && ts.isPropertyAccessExpression(holder)) {
+          if (READ_OPS.has(op) && models.includes(model) && !whereFiltered(node.arguments)) report(node, "read", model, `${model}.${op} reads`);
+          checkNested(model, node.arguments, node);
+        } else if (READ_OPS.has(op) && isDynamic(callee)) {
+          report(node, "dynamic", "dynamic", `a dynamically chosen model's ${op} reads`);
+        }
+      }
+      if (RAW_CALLS.has(callee.name.text)) {
+        for (const arg of node.arguments.slice(0, 1)) {
+          const text2 = literalText(arg);
+          if (text2 !== void 0) for (const model of rawModels(text2)) report(node, "raw", model, `raw SQL on "${model}" reads`);
+        }
+      }
+    }
+    if (ts.isTaggedTemplateExpression(node)) {
+      const tag = node.tag.getText(source);
+      if (tag === "Prisma.sql" || tag === "sql" || RAW_CALLS.has(tag.split(".").pop() ?? "")) {
+        const text2 = literalText(node.template);
+        if (text2 !== void 0) for (const model of rawModels(text2)) report(node, "raw", model, `raw SQL on "${model}" reads`);
+      }
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(source);
+  for (const marker of markers) {
+    if (!marker.used) sites.push({ file, line: marker.line, kind: "stale-marker", model: marker.model, message: `${file}:${marker.line} trash-ok(${marker.model}) excuses no read directly below it: remove it` });
+  }
+  return sites.sort((a, b) => a.line - b.line);
+}
+function sourceFiles(root, dir = "src") {
+  const out = [];
+  const walk = (current) => {
+    for (const name of readdirSync(join(root, current))) {
+      const path = join(current, name);
+      if (statSync(join(root, path)).isDirectory()) walk(path);
+      else if (/\.tsx?$/.test(name) && !/\.test\.tsx?$|\.d\.ts$/.test(name)) out.push(path);
+    }
+  };
+  walk(dir);
+  return out;
+}
+function scanTree(root, models, where = {}) {
+  const relations = relationMapOf(readFileSync(join(root, where.schemaPath ?? join("prisma", "schema.prisma")), "utf8"));
+  return sourceFiles(root, where.sourceDir).flatMap((file) => scanSource(file, readFileSync(join(root, file), "utf8"), relations, models));
+}
+function countMarkers(root, sourceDir) {
+  return sourceFiles(root, sourceDir).reduce((total, file) => total + readFileSync(join(root, file), "utf8").split("\n").filter((line) => MARKER.test(line)).length, 0);
+}
+export {
+  countMarkers,
+  delegateOf,
+  modelOfDelegate,
+  relationMapOf,
+  scanSource,
+  scanTree,
+  sourceFiles
+};

package/package.json

@@ -1,6 +1,59 @@
 {
   "name": "@ordinatio/trash",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.0.0",
+  "private": false,
+  "license": "MIT",
+  "description": "A Trash for any product, with no database and no framework: row-state helpers, the trash and restore state machine behind a store port (outcomes as values, one winner under parallel clicks), trashed-list paging, the operator erase pipeline (read-only plan, one transaction per row, audit inside it, exit codes, command-line rules) and, on its own subpath, a syntax-tree scanner that finds reads which forgot to leave the Trash out",
+  "type": "module",
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./scan": {
+      "types": "./dist/scan.d.ts",
+      "import": "./dist/scan.js",
+      "default": "./dist/scan.js"
+    },
+    "./cli": {
+      "types": "./dist/cli.d.ts",
+      "import": "./dist/cli.js",
+      "default": "./dist/cli.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "peerDependencies": {
+    "typescript": ">=5"
+  },
+  "peerDependenciesMeta": {
+    "typescript": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsup": "^8.5.1",
+    "typescript": "^5.8.3",
+    "vitest": "^4.0.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest",
+    "test:run": "vitest run"
+  }
 }