@jini-ai/cms 0.3.10 → 0.4.0

package/dist/trash/adapters/record-store.d.ts

@@ -0,0 +1,52 @@
+/**
+ * @file Marker adapter for record stores in compositions without column SQL.
+ * Persistent adapters must flip marker columns without parsing payloads so corrupt rows remain
+ * removable. A host backed by memory records supplies the same three operations through its store.
+ * This adapter has no trash-index knowledge: the service owns indexing and transactions, and this
+ * supplies only the domain half of the marker flip.
+ */
+import type { TrashAdapter } from "../ports.js";
+/** The narrowest shape a marker flip needs. Host in-memory repositories supply it. */
+export interface TrashRecordStore<T extends {
+    version: number;
+}> {
+    findById(required: {
+        workspaceId: string;
+        id: string;
+    }): Promise<T | null>;
+    save(required: {
+        record: T;
+    }): Promise<void>;
+}
+export interface RecordStoreTrashAdapterDeps<T extends {
+    version: number;
+}> {
+    entityType: string;
+    store: TrashRecordStore<T>;
+    /** Pure: set the hidden marker and stamp the caller-supplied timestamp. */
+    hidden(required: {
+        record: T;
+        at: string;
+    }): T;
+    /** Pure: clear the marker, preserving the stored payload. */
+    shown(required: {
+        record: T;
+        at: string;
+    }): T;
+    /** Detect repeated flips so a no-op cannot re-fire transactional follow-ups. */
+    isHidden(required: {
+        record: T;
+    }): boolean;
+}
+/** @complexity O(1) to build; every method is one store read plus at most one store write. */
+export declare function createRecordStoreTrashAdapter<T extends {
+    version: number;
+}>(deps: RecordStoreTrashAdapterDeps<T>, 
+/** Without physical deletion, purge stands down and never claims a removal it did not make. */
+optional?: {
+    hardDelete?: (required: {
+        workspaceId: string;
+        id: string;
+    }) => Promise<void>;
+}): TrashAdapter;
+//# sourceMappingURL=record-store.d.ts.map

package/dist/trash/adapters/record-store.js

@@ -0,0 +1,36 @@
+/** @complexity O(1) to build; every method is one store read plus at most one store write. */
+export function createRecordStoreTrashAdapter(deps, 
+/** Without physical deletion, purge stands down and never claims a removal it did not make. */
+optional = {}) {
+    async function flip(required, direction) {
+        const existing = await deps.store.findById({ workspaceId: required.workspaceId, id: required.entityId });
+        if (!existing)
+            return { ok: false, reason: "not-found" };
+        if (required.expectedVersion !== null && existing.version !== required.expectedVersion) {
+            return { ok: false, reason: "version-changed" };
+        }
+        const alreadyThere = direction === "hide" ? deps.isHidden({ record: existing }) : !deps.isHidden({ record: existing });
+        if (alreadyThere)
+            return { ok: true, version: existing.version, noop: true };
+        const moved = direction === "hide" ? deps.hidden({ record: existing, at: required.at }) : deps.shown({ record: existing, at: required.at });
+        const next = { ...moved, version: existing.version + 1 };
+        await deps.store.save({ record: next });
+        return { ok: true, version: next.version };
+    }
+    return {
+        entityType: deps.entityType,
+        hide: (required) => flip(required, "hide"),
+        unhide: (required) => flip(required, "unhide"),
+        async purge(required) {
+            const existing = await deps.store.findById({ workspaceId: required.workspaceId, id: required.entityId });
+            if (!existing)
+                return "already-gone";
+            if (required.expectedVersion !== null && existing.version !== required.expectedVersion)
+                return "version-changed";
+            await optional.hardDelete?.({ workspaceId: required.workspaceId, id: required.entityId });
+            const after = await deps.store.findById({ workspaceId: required.workspaceId, id: required.entityId });
+            return after === null ? "purged" : "version-changed";
+        },
+    };
+}
+//# sourceMappingURL=record-store.js.map

package/dist/trash/cursor.d.ts

@@ -0,0 +1,20 @@
+/** @complexity O(1). */
+export declare function encodeTrashCursor(required: {
+    trashedAt: string;
+    id: string;
+}): string;
+/**
+ * Decodes a cursor produced by {@link encodeTrashCursor}.
+ *
+ * Returns `null` for anything unparseable rather than throwing — a stale or hand-edited cursor
+ * degrades to "start from the top", which is the safe reading for a list of deleted things.
+ *
+ * @complexity O(1).
+ */
+export declare function decodeTrashCursor({ cursor }: {
+    cursor: string | null | undefined;
+}): {
+    trashedAt: string;
+    id: string;
+} | null;
+//# sourceMappingURL=cursor.d.ts.map

package/dist/trash/cursor.js

@@ -0,0 +1,36 @@
+/**
+ * @file Keyset cursor codec for the Trash list, shared by both `TrashRepoPort` adapters so the
+ * persistent repo and the in-memory test double cannot drift on pagination.
+ *
+ * Keyset on `(trashed_at, id)` rather than OFFSET: the sweeper deletes rows underneath a paging
+ * reader, and OFFSET would silently skip an item every time a row above the window disappeared.
+ */
+const SEPARATOR = "\u0000";
+/** @complexity O(1). */
+export function encodeTrashCursor(required) {
+    return Buffer.from(`${required.trashedAt}${SEPARATOR}${required.id}`, "utf8").toString("base64url");
+}
+/**
+ * Decodes a cursor produced by {@link encodeTrashCursor}.
+ *
+ * Returns `null` for anything unparseable rather than throwing — a stale or hand-edited cursor
+ * degrades to "start from the top", which is the safe reading for a list of deleted things.
+ *
+ * @complexity O(1).
+ */
+export function decodeTrashCursor({ cursor }) {
+    if (!cursor)
+        return null;
+    let decoded;
+    try {
+        decoded = Buffer.from(cursor, "base64url").toString("utf8");
+    }
+    catch {
+        return null;
+    }
+    const at = decoded.indexOf(SEPARATOR);
+    if (at <= 0 || at === decoded.length - 1)
+        return null;
+    return { trashedAt: decoded.slice(0, at), id: decoded.slice(at + 1) };
+}
+//# sourceMappingURL=cursor.js.map

package/dist/trash/follow-ups.d.ts

@@ -0,0 +1,76 @@
+/**
+ * @file `withFollowUps` — lets one Trash type finish a hide, restore or purge its own generic marker
+ * flip cannot express, without teaching the generic table adapter anything about that type. T1's
+ * generalization of the A0 `withRestoreFollowUp` sketch (plan §2 T1 item 6) into one decorator with
+ * three optional hooks, so T5/T6 (menus, terms, taxonomies) register their own event/revision
+ * follow-ups the same way `widget` already does, rather than each writing a bespoke wrapper.
+ *
+ * Every hook:
+ *  - runs inside the op's own transaction — `TrashPort.trash`/`restore`/`purgeSelected` (`write-
+ *    service.ts`) already wrap the adapter call in `deps.transaction`, and this decorator's hooks run
+ *    from inside that same call, so a hook backed by the same host database connection
+ *    joins it automatically (the transaction runner must be reentrant);
+ *  - runs only on an OK/`"purged"` result that actually changed something — a no-op outcome
+ *    (`not-found`, `version-changed`, `blocked`, `already-gone`) never fires one, because nothing
+ *    changed, and neither does `hide`/`unhide`'s own idempotent "already in the target state" branch,
+ *    which also reports `ok: true` with no transition; `TrashMarkerResult.noop` (`ports.ts`) is what
+ *    tells that branch apart from a real one, since both otherwise share the same `ok: true` shape
+ *    (T1c, `follow-ups.test.ts` — the two were conflated here until that dispatch's direct test of
+ *    this file caught it: a re-hide/re-unhide of an already-trashed/already-live row used to refire
+ *    the hook);
+ *  - propagates a throw, which rolls the whole op back (the state change and the hook are one unit).
+ *
+ * `afterPurge` is paired with `beforePurge`: the row is gone the instant `purge` reports `"purged"`
+ * (a DELETE is visible to later reads in the SAME transaction even before COMMIT), so anything a
+ * purge hook needs to see about the row's pre-purge state (a taxonomy revision's
+ * `previousStateJson`) has to be read BEFORE the delete runs. `beforePurge`'s return value is handed
+ * back to `afterPurge` untouched — this file never interprets it, keeping every hook's own shape a
+ * type-specific concern for its host composition, not for this shared service.
+ */
+import type { TrashAdapter } from "./ports.js";
+/** Finishes one hide. Only fires when `hide` actually transitioned the row (never on the idempotent
+ *  "already trashed" branch, and never when `hide` returned `blocked`/`not-found`/`version-changed`). */
+export type HideFollowUp = (required: {
+    workspaceId: string;
+    entityId: string;
+    at: string;
+}) => Promise<void>;
+/** Finishes one restore. Receives the Trash row's stored `priorMarker`; never called without one —
+ *  same contract the A0 `RestoreFollowUp` (widget adoption) already relied on. */
+export type UnhideFollowUp = (required: {
+    workspaceId: string;
+    entityId: string;
+    priorMarker: string;
+    at: string;
+}) => Promise<void>;
+/** Reads whatever "prior state" a purge follow-up needs, before the row is deleted. Runs even when
+ *  the purge that follows turns out NOT to succeed (a version race) — it is a read, not a write, so
+ *  that costs nothing beyond one extra query on an already-rare path. */
+export type BeforePurge = (required: {
+    workspaceId: string;
+    entityId: string;
+}) => Promise<unknown>;
+/** Finishes one purge. `priorState` is exactly what `beforePurge` returned (`undefined` when the
+ *  caller registered no `beforePurge`). Fires only on a `"purged"` outcome. */
+export type AfterPurge = (required: {
+    workspaceId: string;
+    entityId: string;
+    priorState: unknown;
+}) => Promise<void>;
+export interface TrashFollowUpHooks {
+    afterHide?: HideFollowUp;
+    afterUnhide?: UnhideFollowUp;
+    beforePurge?: BeforePurge;
+    afterPurge?: AfterPurge;
+}
+/**
+ * Wraps `adapter` so its `hide`/`unhide`/`purge` also run whichever of `hooks`'s optional callbacks
+ * applies, per the OK/success rule in the file header. An entry with no hooks at all should not call
+ * this — host composition only wraps entries that have at least one.
+ *
+ * @complexity O(1) beyond the adapter's own methods and whichever hook fires.
+ */
+export declare function withFollowUps(required: {
+    adapter: TrashAdapter;
+}, hooks?: TrashFollowUpHooks): TrashAdapter;
+//# sourceMappingURL=follow-ups.d.ts.map

package/dist/trash/follow-ups.js

@@ -0,0 +1,46 @@
+/**
+ * Wraps `adapter` so its `hide`/`unhide`/`purge` also run whichever of `hooks`'s optional callbacks
+ * applies, per the OK/success rule in the file header. An entry with no hooks at all should not call
+ * this — host composition only wraps entries that have at least one.
+ *
+ * @complexity O(1) beyond the adapter's own methods and whichever hook fires.
+ */
+export function withFollowUps(required, hooks = {}) {
+    const { adapter } = required;
+    return {
+        entityType: adapter.entityType,
+        async hide(hideRequired, hideOptional) {
+            const result = await adapter.hide(hideRequired, hideOptional);
+            // Idempotent flips also report ok:true; noop is the signal that no transition occurred.
+            if (result.ok && !result.noop && hooks.afterHide) {
+                await hooks.afterHide({ workspaceId: hideRequired.workspaceId, entityId: hideRequired.entityId, at: hideRequired.at });
+            }
+            return result;
+        },
+        async unhide(unhideRequired, unhideOptional) {
+            const result = await adapter.unhide(unhideRequired, unhideOptional);
+            const priorMarker = unhideOptional?.priorMarker;
+            // The same noop guard prevents an already-live row from re-firing a restore follow-up.
+            if (result.ok && !result.noop && typeof priorMarker === "string" && hooks.afterUnhide) {
+                await hooks.afterUnhide({
+                    workspaceId: unhideRequired.workspaceId,
+                    entityId: unhideRequired.entityId,
+                    priorMarker,
+                    at: unhideRequired.at,
+                });
+            }
+            return result;
+        },
+        async purge(purgeRequired, purgeOptional) {
+            const priorState = hooks.beforePurge
+                ? await hooks.beforePurge({ workspaceId: purgeRequired.workspaceId, entityId: purgeRequired.entityId })
+                : undefined;
+            const result = await adapter.purge(purgeRequired, purgeOptional);
+            if (result === "purged" && hooks.afterPurge) {
+                await hooks.afterPurge({ workspaceId: purgeRequired.workspaceId, entityId: purgeRequired.entityId, priorState });
+            }
+            return result;
+        },
+    };
+}
+//# sourceMappingURL=follow-ups.js.map

package/dist/trash/index.d.ts

@@ -0,0 +1,8 @@
+export * from "./ports.js";
+export * from "./write-service.js";
+export * from "./sweeper.js";
+export * from "./follow-ups.js";
+export * from "./repo.memory.js";
+export * from "./cursor.js";
+export * from "./adapters/record-store.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/trash/index.js

@@ -0,0 +1,8 @@
+export * from "./ports.js";
+export * from "./write-service.js";
+export * from "./sweeper.js";
+export * from "./follow-ups.js";
+export * from "./repo.memory.js";
+export * from "./cursor.js";
+export * from "./adapters/record-store.js";
+//# sourceMappingURL=index.js.map

package/dist/trash/ports.d.ts

@@ -0,0 +1,308 @@
+/**
+ * @file Column/record contracts for snapshot-only trash listing and atomic marker/index changes.
+ * A trash operation never round-trips an entity payload, and listing never reads the entity at all.
+ * Parsing a payload merely to flip its status fails on the corrupt rows a user most wants gone.
+ * `trash` requires a caller-held display snapshot. Adapters expose only hide/unhide/purge, with no
+ * describe method: a read that can throw must never become a dependency of trash listing.
+ */
+export type TrashEntityType = string;
+/** The two display strings captured from columns at trash time. Never derived by the port. */
+export interface TrashDisplay {
+    title: string;
+    subtitle?: string | null;
+}
+export interface TrashActor {
+    principalId: string;
+    pluginId?: string | null;
+}
+/**
+ * Outcome of a marker flip.
+ *
+ * `version` is the entity's version AFTER the flip — that is what lands in
+ * `trashed_items.entity_version` and what the sweeper's compare-and-delete later checks, so a
+ * restore (which bumps the version again) always wins a race against a purge. `null` for a domain
+ * with no version column.
+ *
+ * `priorMarker` is OPTIONAL and additive (migration 0072): a status-marker adapter (`menu`, `term`,
+ * `taxonomy`) reports the status the row carried immediately before `hide` flipped it to `trash`, so
+ * `restore` can put it back exactly rather than to a fixed fallback. A caller that omits the key
+ * entirely (timestamp adapters) keeps the exact `{ ok: true, version }` shape — do not set this to
+ * `undefined`; leave the key out. `trash.contract.test.ts`'s pinned `assert.deepEqual(trashed, {
+ * ok: true, version: 2 })` depends on that: Node's `assert.deepEqual` treats an extra own-enumerable
+ * property, even one valued `undefined`, as a mismatch.
+ *
+ * `noop` is OPTIONAL and additive (T1c, `follow-ups.test.ts`): host table adapters' `hide`/`unhide`
+ * set it to `true` on their idempotent "already in the target state" branch — the ONE signal that
+ * distinguishes that branch from a real transition, both of which otherwise report the same
+ * `ok: true`. `withFollowUps` (`@jini-ai/cms/trash`) reads it to decide whether a hook actually finished
+ * something. Same leave-the-key-out rule as `priorMarker`: a real transition leaves it absent, so exact-shape assertions remain
+ * valid, so their pinned exact-shape assertions are
+ * unaffected.
+ *
+ * `"blocked"` (T1 item 2, migration-free — no new column) is a THIRD failure reason, alongside
+ * `"not-found"`/`"version-changed"`: the row exists and the version matches, but the host's
+ * declared blocker found rows that must move or be deleted first (a term with child terms). `code`
+ * and `count` are always present together on this branch — the host registry defines their meaning.
+ */
+export type TrashMarkerResult = {
+    ok: true;
+    version: number | null;
+    priorMarker?: string | null;
+    noop?: true;
+} | {
+    ok: false;
+    reason: "not-found" | "version-changed";
+} | {
+    ok: false;
+    reason: "blocked";
+    code: string;
+    count: number;
+};
+/** Outcome of a physical row removal. */
+export type TrashPurgeOutcome = "purged" | "version-changed" | "already-gone";
+/**
+ * One per domain. Built and registered into a plain `Map` at the composition root and resolved
+ * **at call time**, never at registration time: this codebase's module registries (`ToolRegistry`,
+ * routing's `phaseRegistry`) are append-only with no unregister, so anything that filters at
+ * registration runs exactly once. Two real bugs already came from that.
+ *
+ * Persistent host implementations MUST be column-only SQL. No payload parse, no ORM entity hydration, no domain
+ * write-service call that re-validates a record.
+ */
+export interface TrashAdapter {
+    readonly entityType: TrashEntityType;
+    /**
+     * Move the domain's own marker to hidden.
+     *
+     * `at` is supplied by the caller rather than read from an adapter-local clock so the marker's
+     * timestamp is byte-identical to the one the calling domain writes into its revision ledger.
+       */
+    hide(required: {
+        workspaceId: string;
+        entityId: string;
+        at: string;
+        expectedVersion: number | null;
+    }, optional?: {
+        actor?: TrashActor;
+    }): Promise<TrashMarkerResult>;
+    /**
+     * Move it back. Same no-parse rule as {@link TrashAdapter.hide}.
+     *
+     * `priorMarker` (migration 0072) is what {@link TrashItem.priorMarker} stored at trash time —
+     * additive and optional, so every adapter's existing signature stays structurally compatible. A
+     * status-marker adapter restores to `priorMarker ?? restoreFallback`; a timestamp-marker adapter
+     * (timestamp adapters) ignores it, since clearing the marker column needs no prior value.
+       */
+    unhide(required: {
+        workspaceId: string;
+        entityId: string;
+        at: string;
+        expectedVersion: number | null;
+    }, optional?: {
+        priorMarker?: string | null;
+        actor?: TrashActor;
+    }): Promise<TrashMarkerResult>;
+    /** Physically remove the row. Compare-and-delete on `expectedVersion`. */
+    purge(required: {
+        workspaceId: string;
+        entityId: string;
+        expectedVersion: number | null;
+    }, optional?: {
+        actor?: TrashActor;
+    }): Promise<TrashPurgeOutcome>;
+}
+/** One row of the Trash list. Rendered entirely from the snapshot — no entity read. */
+export interface TrashItem {
+    id: string;
+    workspaceId: string;
+    entityType: TrashEntityType;
+    entityId: string;
+    trashedAt: string;
+    purgeAfter: string;
+    actorPrincipalId: string;
+    actorPluginId: string | null;
+    displayTitle: string;
+    displaySubtitle: string | null;
+    entityVersion: number | null;
+    priorMarker: string | null;
+}
+export interface TrashPage {
+    items: TrashItem[];
+    /** Keyset cursor on `(trashed_at, id)`; `null` when the page is the last one. */
+    nextCursor: string | null;
+}
+/** Per-item outcome of {@link TrashPort.purgeSelected}. */
+export type PurgeItemOutcome = "purged" | "already-gone" | "version-changed" | "not-found" | "adapter-unavailable" | "forbidden";
+/**
+ * Decides whether the caller may permanently destroy ONE already-resolved trash row.
+ *
+ * Purge addresses rows by trash row id, and the per-kind permission has to be checked against the
+ * kind the STORED row actually has. A caller that supplied the kind alongside the id could name
+ * `comment` for a post's row and destroy a post holding only `comments.moderate`. So the gate is
+ * handed the row `purgeSelected` looked up, inside the same call that then purges it — which closes
+ * the read-then-act window as well as the escalation.
+ *
+ * Returning `false` (rather than throwing) keeps a denial a per-item outcome: one forbidden row in
+ * a hand-ticked selection must not abort the rows the caller may destroy.
+ */
+export type TrashItemAuthorizer = (required: {
+    item: TrashItem;
+}) => Promise<boolean>;
+export interface PurgeReport {
+    purged: number;
+    results: {
+        id: string;
+        outcome: PurgeItemOutcome;
+    }[];
+}
+/** Outcome of a restore. `adapter-unavailable` is honest degradation, not a throw: the row lists
+ *  from its snapshot even when its plugin has been uninstalled. */
+export type RestoreOutcome = "restored" | "not-found" | "version-changed" | "adapter-unavailable";
+export interface TrashPort {
+    /**
+     * Hide the entity AND index it, as ONE transaction. There is deliberately no public seam that
+     * performs only one of the two writes — a failure between them would leave an item that is in the
+     * Trash and still live on the site, or hidden with no Trash row, which is unrecoverable from the UI.
+       */
+    trash(required: {
+        workspaceId: string;
+        entityType: TrashEntityType;
+        entityId: string;
+        actor: TrashActor;
+        display: TrashDisplay;
+        at: string;
+        expectedVersion: number | null;
+    }, optional?: {
+        priorMarker?: string | null;
+    }): Promise<TrashMarkerResult>;
+    restore(required: {
+        workspaceId: string;
+        entityType: TrashEntityType;
+        entityId: string;
+        at: string;
+    }, optional?: {
+        actor?: TrashActor;
+    }): Promise<RestoreOutcome>;
+    /** Excludes `purge_after <= now`: a dormant site shows nothing expired on its first render, with
+     *  no wait for a sweep. */
+    list(required: {
+        workspaceId: string;
+        now: string;
+        limit: number;
+    }, optional?: {
+        entityTypes?: readonly TrashEntityType[];
+        cursor?: string | null;
+    }): Promise<TrashPage>;
+    /**
+     * Human-confirmed: the admin Trash screen and `permanent-delete` tools may reach this port only
+     * after confirmation. Tool input cannot self-confirm; see the confirmed-call contract tests.
+     *
+     * `authorizeItem` is REQUIRED, not optional. A permission check a call site may omit is a
+     * permission check some call site eventually omits, and this operation is the one that cannot be
+     * undone. See {@link TrashItemAuthorizer} for why the gate takes the resolved row.
+       */
+    purgeSelected(required: {
+        workspaceId: string;
+        ids: readonly string[];
+        actor: TrashActor;
+        authorizeItem: TrashItemAuthorizer;
+    }): Promise<PurgeReport>;
+}
+export type RemoveEntity = (required: {
+    workspaceId: string;
+    id: string;
+    display: TrashDisplay;
+    at: string;
+    expectedVersion: number | null;
+    actor: TrashActor;
+}, optional?: {
+    priorMarker?: string | null;
+}) => Promise<TrashMarkerResult>;
+/**
+ * The function a domain's delete path receives to DROP an index row.
+ *
+ * Needed by any domain that can leave the trashable state by a route other than a Trash-screen
+ * restore or purge: a comment approved back out of `trash` by ordinary moderation, a media asset
+ * hard-purged from the admin delete rung. Without it the index row outlives the condition it
+ * records, and the Trash screen offers a Restore or a permanent delete for something that is either
+ * live again or already gone.
+ *
+ * NOT a half of {@link TrashPort.trash}. It writes no marker and hides nothing — it only forgets a
+ * removal that some other owner has already undone or completed.
+ */
+export type ForgetRemovedEntity = (required: {
+    workspaceId: string;
+    id: string;
+}) => Promise<void>;
+/** A claimed batch of due rows, handed to the sweeper. */
+export interface TrashSweepClaim {
+    id: string;
+    workspaceId: string;
+    entityType: TrashEntityType;
+    entityId: string;
+    entityVersion: number | null;
+}
+/**
+ * Storage for `trashed_items`. Adapters: host persistence + in-memory reference adapter.
+ *
+ * Every method is column-only. Nothing here ever reaches into a domain table.
+ */
+export interface TrashRepoPort {
+    /** Idempotent by `(workspace_id, entity_type, entity_id)` — re-trashing is a no-op, not a
+     *  duplicate row. */
+    insert(required: {
+        row: TrashItem;
+    }): Promise<void>;
+    findByEntity(required: {
+        workspaceId: string;
+        entityType: TrashEntityType;
+        entityId: string;
+    }): Promise<TrashItem | null>;
+    findByIds(required: {
+        workspaceId: string;
+        ids: readonly string[];
+    }): Promise<TrashItem[]>;
+    /** Removes the index row. This IS the restore — there is no second marker to clear. */
+    deleteById(required: {
+        workspaceId: string;
+        id: string;
+    }): Promise<void>;
+    deleteByEntity(required: {
+        workspaceId: string;
+        entityType: TrashEntityType;
+        entityId: string;
+    }): Promise<void>;
+    list(required: {
+        workspaceId: string;
+        now: string;
+        limit: number;
+    }, optional?: {
+        entityTypes?: readonly TrashEntityType[];
+        cursor?: string | null;
+    }): Promise<TrashPage>;
+    /** Atomic claim of due, unleased rows across EVERY workspace in the file (the `purge_after`
+     *  index is global for exactly this query). */
+    claimDue(required: {
+        now: string;
+        leaseOwner: string;
+        leaseUntil: string;
+        limit: number;
+    }): Promise<TrashSweepClaim[]>;
+    /** Explicitly release a claim. The built-in sweep retains stood-down leases for retry backoff. */
+    releaseLease(required: {
+        id: string;
+    }): Promise<void>;
+}
+/**
+ * Marker/index writes and follow-ups must share one reentrant transaction. A domain may already
+ * hold a transaction around its marker/revision writes; nesting must join rather than open another
+ * BEGIN, and a propagated failure must roll back the entire unit.
+ */
+export type TransactionRunner = <T>(required: {
+    work: () => Promise<T>;
+}) => Promise<T>;
+/** Host-owned allowlist evaluated at call time; listing still uses snapshots for missing domains. */
+export type TrashEntityPolicy = (required: {
+    entityType: TrashEntityType;
+}) => boolean;
+//# sourceMappingURL=ports.d.ts.map

package/dist/trash/ports.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=ports.js.map

package/dist/trash/repo.memory.d.ts

@@ -0,0 +1,50 @@
+import type { TrashEntityType, TrashItem, TrashPage, TrashRepoPort, TrashSweepClaim } from "./ports.js";
+export declare class InMemoryTrashRepo implements TrashRepoPort {
+    constructor(_required: Record<string, never>);
+    private readonly rows;
+    private readonly leases;
+    /** Test-only view of everything stored, including expired rows the list hides. */
+    all(_required: Record<string, never>): TrashItem[];
+    /** @complexity O(n) over stored rows (the identity scan); n is a test fixture. */
+    insert({ row }: {
+        row: TrashItem;
+    }): Promise<void>;
+    findByEntity(required: {
+        workspaceId: string;
+        entityType: TrashEntityType;
+        entityId: string;
+    }): Promise<TrashItem | null>;
+    findByIds(required: {
+        workspaceId: string;
+        ids: readonly string[];
+    }): Promise<TrashItem[]>;
+    deleteById(required: {
+        workspaceId: string;
+        id: string;
+    }): Promise<void>;
+    deleteByEntity(required: {
+        workspaceId: string;
+        entityType: TrashEntityType;
+        entityId: string;
+    }): Promise<void>;
+    /** @complexity O(n log n) — sorts the workspace's rows; fixture-sized by construction. */
+    list(required: {
+        workspaceId: string;
+        now: string;
+        limit: number;
+    }, optional?: {
+        entityTypes?: readonly TrashEntityType[];
+        cursor?: string | null;
+    }): Promise<TrashPage>;
+    /** @complexity O(n log n). */
+    claimDue(required: {
+        now: string;
+        leaseOwner: string;
+        leaseUntil: string;
+        limit: number;
+    }): Promise<TrashSweepClaim[]>;
+    releaseLease(required: {
+        id: string;
+    }): Promise<void>;
+}
+//# sourceMappingURL=repo.memory.d.ts.map