@jini-ai/cms 0.3.11 → 0.4.1

package/dist/trash/repo.memory.js

@@ -0,0 +1,114 @@
+/**
+ * @file In-memory `TrashRepoPort` (rule-of-two adapter #1), mirroring the convention
+ * host in-memory repository conventions established: a real adapter used by tests, not a stub.
+ *
+ * Ordering, the lazy `purge_after` filter and the keyset cursor are implemented here the same way
+ * persistent adapters implement them, and both share this package's cursor codec, so a test that passes against
+ * this double is testing the behaviour the durable adapter has.
+ */
+import { decodeTrashCursor, encodeTrashCursor } from "./cursor.js";
+function identityKey(workspaceId, entityType, entityId) {
+    return `${workspaceId}\u0000${entityType}\u0000${entityId}`;
+}
+/** Newest first, `id` breaking ties so the keyset cursor is total. @complexity O(1). */
+function compareDesc(a, b) {
+    if (a.trashedAt !== b.trashedAt)
+        return a.trashedAt < b.trashedAt ? 1 : -1;
+    if (a.id !== b.id)
+        return a.id < b.id ? 1 : -1;
+    return 0;
+}
+export class InMemoryTrashRepo {
+    constructor(_required) { }
+    rows = new Map();
+    leases = new Map();
+    /** Test-only view of everything stored, including expired rows the list hides. */
+    all(_required) {
+        return [...this.rows.values()].sort(compareDesc);
+    }
+    /** @complexity O(n) over stored rows (the identity scan); n is a test fixture. */
+    async insert({ row }) {
+        for (const existing of this.rows.values()) {
+            if (identityKey(existing.workspaceId, existing.entityType, existing.entityId) ===
+                identityKey(row.workspaceId, row.entityType, row.entityId)) {
+                return; // INSERT OR IGNORE against `trashed_items_identity_unique`
+            }
+        }
+        this.rows.set(row.id, { ...row });
+    }
+    async findByEntity(required) {
+        const wanted = identityKey(required.workspaceId, required.entityType, required.entityId);
+        for (const row of this.rows.values()) {
+            if (identityKey(row.workspaceId, row.entityType, row.entityId) === wanted)
+                return { ...row };
+        }
+        return null;
+    }
+    async findByIds(required) {
+        return required.ids
+            .map((id) => this.rows.get(id))
+            .filter((row) => row !== undefined && row.workspaceId === required.workspaceId)
+            .map((row) => ({ ...row }));
+    }
+    async deleteById(required) {
+        const row = this.rows.get(required.id);
+        if (row && row.workspaceId === required.workspaceId) {
+            this.rows.delete(required.id);
+            this.leases.delete(required.id);
+        }
+    }
+    async deleteByEntity(required) {
+        const found = await this.findByEntity(required);
+        if (found) {
+            this.rows.delete(found.id);
+            this.leases.delete(found.id);
+        }
+    }
+    /** @complexity O(n log n) — sorts the workspace's rows; fixture-sized by construction. */
+    async list(required, optional = {}) {
+        const after = decodeTrashCursor({ cursor: optional.cursor });
+        const types = optional.entityTypes && optional.entityTypes.length > 0 ? new Set(optional.entityTypes) : null;
+        const matched = [...this.rows.values()]
+            .filter((row) => row.workspaceId === required.workspaceId)
+            // Expired rows vanish immediately on list, even if a sweeper has never run in this host.
+            .filter((row) => row.purgeAfter > required.now)
+            .filter((row) => (types ? types.has(row.entityType) : true))
+            .sort(compareDesc)
+            .filter((row) => {
+            if (!after)
+                return true;
+            if (row.trashedAt !== after.trashedAt)
+                return row.trashedAt < after.trashedAt;
+            return row.id < after.id;
+        });
+        const items = matched.slice(0, required.limit).map((row) => ({ ...row }));
+        const last = items.at(-1);
+        const nextCursor = matched.length > required.limit && last ? encodeTrashCursor(last) : null;
+        return { items, nextCursor };
+    }
+    /** @complexity O(n log n). */
+    async claimDue(required) {
+        const due = [...this.rows.values()]
+            .filter((row) => row.purgeAfter <= required.now)
+            .filter((row) => {
+            const lease = this.leases.get(row.id);
+            return !lease || lease.expiresAt <= required.now;
+        })
+            .sort((a, b) => (a.purgeAfter < b.purgeAfter ? -1 : a.purgeAfter > b.purgeAfter ? 1 : 0))
+            .slice(0, required.limit);
+        for (const row of due) {
+            this.leases.set(row.id, { owner: required.leaseOwner, expiresAt: required.leaseUntil });
+        }
+        return due.map((row) => ({
+            id: row.id,
+            workspaceId: row.workspaceId,
+            entityType: row.entityType,
+            entityId: row.entityId,
+            entityVersion: row.entityVersion,
+        }));
+    }
+    async releaseLease(required) {
+        this.leases.delete(required.id);
+    }
+}
+//# sourceMappingURL=repo.memory.js.map

package/dist/trash/sweeper.d.ts

@@ -0,0 +1,77 @@
+import type { Clock } from "@jini-ai/core/primitives";
+/** Claim then re-read inside the purge transaction; a concurrent restore always wins. */
+import type { PurgeItemOutcome, TrashAdapter, TrashEntityType, TrashEntityPolicy, TrashRepoPort, TransactionRunner } from "./ports.js";
+/** Idle wait between sweeps. Retention is measured in days, so an hour of lateness costs nothing,
+ *  and a desktop site that is only open for minutes still sweeps once at boot. */
+export declare const DEFAULT_TRASH_SWEEP_INTERVAL_MS: number;
+/** Rows claimed per sweep. Each one costs a transaction, so this bounds a single sweep's hold on
+ *  the write lock; a full batch sweeps again immediately rather than waiting out the interval. */
+export declare const DEFAULT_TRASH_SWEEP_BATCH_SIZE = 50;
+/** How long a claim hides a row from other sweeps. Also the retry backoff for a row that stood
+ *  down: nothing releases it early, so it is re-tried at most once per lease. */
+export declare const DEFAULT_TRASH_SWEEP_LEASE_MS: number;
+export interface TrashSweepDeps {
+    repo: TrashRepoPort;
+    /** The same call-time `Map` the write service resolves against — never a module-level registry. */
+    adapters: ReadonlyMap<TrashEntityType, TrashAdapter>;
+    /** Reentrant; see {@link TransactionRunner}. */
+    transaction: TransactionRunner;
+    entityPolicy: TrashEntityPolicy;
+}
+export interface TrashSweepReport {
+    /** Rows this sweep leased. `claimed === limit` means there is probably more due right now. */
+    claimed: number;
+    purged: number;
+    results: {
+        id: string;
+        outcome: PurgeItemOutcome;
+    }[];
+}
+/**
+ * One pass of the backstop. Time, identity and batch size are arguments rather than dependencies so
+ * the decision logic stays deterministic.
+ */
+export type TrashSweepOnce = (required: {
+    now: string;
+    leaseOwner: string;
+    leaseUntil: string;
+    limit: number;
+}) => Promise<TrashSweepReport>;
+export interface TrashSweeper {
+    /** Stops scheduling sweeps, then resolves once a sweep already running has settled. Idempotent. */
+    stop(required: Record<string, never>): Promise<void>;
+}
+/**
+ * Builds the sweep pass.
+ *
+ * @param deps the trash repo, the call-time adapter map and a reentrant transaction runner.
+ * @returns a {@link TrashSweepOnce}. It never throws for a single bad row — one missing adapter or
+ *          one stale version is recorded as that row's outcome and the rest of the batch continues.
+ *          A repo-level failure (a locked database) does propagate; the caller's `onError` owns it.
+ * @complexity O(limit) transactions per pass, each O(1); one indexed claim query.
+ */
+export declare function createTrashSweep(deps: TrashSweepDeps): TrashSweepOnce;
+/** Host scheduler owns timers, unref and cancellation. schedule must defer run to a later turn. */
+export interface TrashSchedulerPort {
+    schedule(required: {
+        delayMs: number;
+        run: () => void;
+    }): unknown;
+    cancel(required: {
+        handle: unknown;
+    }): void;
+}
+export declare function startTrashSweeper(required: {
+    sweep: TrashSweepOnce;
+    clock: Clock;
+    scheduler: TrashSchedulerPort;
+    leaseOwner: string;
+}, optional?: {
+    intervalMs?: number;
+    batchSize?: number;
+    leaseMs?: number;
+    onError?: (required: {
+        error: unknown;
+    }) => void;
+}): TrashSweeper;
+//# sourceMappingURL=sweeper.d.ts.map

package/dist/trash/sweeper.js

@@ -0,0 +1,127 @@
+/**
+ * @file The retention auto-purge backstop (60 days by default) — claim, compare, delete, in that order.
+ *
+ * Two halves on purpose, because they fail in completely different ways:
+ *
+ *  - {@link createTrashSweep} is the decision half. It has no clock, no timer and no randomness, so
+ *    every branch below (the restore race, a stale version, a missing adapter) is a plain function
+ *    call in a test rather than something you have to wait for.
+ *  - {@link startTrashSweeper} is the effect half: a non-overlapping loop over an injected scheduler. The host owns timer cancellation and
+ *    `unref`, so the loop stays portable without changing its first-turn and shutdown behavior.
+ *
+ * **A concurrent restore always wins.** That is the whole safety property, and it is bought twice
+ * over, because either guard alone has a hole:
+ *
+ *  1. Inside the purge transaction the index row is re-read by id. A restore deletes that row in
+ *     its own transaction, so a sweep whose claim is already in hand finds nothing and never calls
+ *     `purge` at all. Version alone would not cover a domain whose `entity_version` is `null`
+ *     (comments and redirects both are) — there is no version there to have changed.
+ *  2. `adapter.purge` is still a compare-and-delete on the version captured at trash time, so a
+ *     domain that does carry a version stands down even if the row somehow survived step 1.
+ *
+ * The lease is the third leg: a claimed row is invisible to other sweeps until `leaseUntil`, so two
+ * processes serving the same file cannot both purge it, and a sweep that dies mid-batch releases
+ * its rows by expiry rather than wedging them forever.
+ */
+import { nowIso as kernelNowIso } from "@jini-ai/core/primitives";
+/** Idle wait between sweeps. Retention is measured in days, so an hour of lateness costs nothing,
+ *  and a desktop site that is only open for minutes still sweeps once at boot. */
+export const DEFAULT_TRASH_SWEEP_INTERVAL_MS = 60 * 60 * 1000;
+/** Rows claimed per sweep. Each one costs a transaction, so this bounds a single sweep's hold on
+ *  the write lock; a full batch sweeps again immediately rather than waiting out the interval. */
+export const DEFAULT_TRASH_SWEEP_BATCH_SIZE = 50;
+/** How long a claim hides a row from other sweeps. Also the retry backoff for a row that stood
+ *  down: nothing releases it early, so it is re-tried at most once per lease. */
+export const DEFAULT_TRASH_SWEEP_LEASE_MS = 5 * 60 * 1000;
+/**
+ * Builds the sweep pass.
+ *
+ * @param deps the trash repo, the call-time adapter map and a reentrant transaction runner.
+ * @returns a {@link TrashSweepOnce}. It never throws for a single bad row — one missing adapter or
+ *          one stale version is recorded as that row's outcome and the rest of the batch continues.
+ *          A repo-level failure (a locked database) does propagate; the caller's `onError` owns it.
+ * @complexity O(limit) transactions per pass, each O(1); one indexed claim query.
+ */
+export function createTrashSweep(deps) {
+    return async function sweepTrashOnce(required) {
+        const claims = await deps.repo.claimDue(required);
+        const results = [];
+        for (const claim of claims) {
+            const adapter = deps.adapters.get(claim.entityType);
+            if (!adapter) {
+                // Keep the lease: immediately retrying an uninstalled domain would starve the batch.
+                // Its snapshot stays listed until expiry, and removal can resume when the domain returns.
+                results.push({ id: claim.id, outcome: "adapter-unavailable" });
+                continue;
+            }
+            if (!deps.entityPolicy({ entityType: claim.entityType })) {
+                results.push({ id: claim.id, outcome: "forbidden" });
+                continue;
+            }
+            const outcome = await deps.transaction({
+                work: async () => {
+                    // Restore removes the index in its own transaction, including unversioned domains.
+                    const [row] = await deps.repo.findByIds({ workspaceId: claim.workspaceId, ids: [claim.id] });
+                    if (!row)
+                        return "not-found";
+                    // Versioned domains also stand down on a compare-and-delete mismatch.
+                    const result = await adapter.purge({
+                        workspaceId: row.workspaceId,
+                        entityId: row.entityId,
+                        expectedVersion: row.entityVersion,
+                    });
+                    if (result === "purged" || result === "already-gone") {
+                        await deps.repo.deleteById({ workspaceId: row.workspaceId, id: row.id });
+                    }
+                    return result;
+                }
+            });
+            results.push({ id: claim.id, outcome });
+        }
+        return {
+            claimed: claims.length,
+            purged: results.filter((r) => r.outcome === "purged").length,
+            results,
+        };
+    };
+}
+export function startTrashSweeper(required, optional = {}) {
+    const intervalMs = optional.intervalMs ?? DEFAULT_TRASH_SWEEP_INTERVAL_MS;
+    const batchSize = optional.batchSize ?? DEFAULT_TRASH_SWEEP_BATCH_SIZE;
+    const leaseMs = optional.leaseMs ?? DEFAULT_TRASH_SWEEP_LEASE_MS;
+    for (const value of [intervalMs, batchSize, leaseMs]) {
+        if (!Number.isSafeInteger(value) || value <= 0)
+            throw new RangeError("trash sweep bounds must be positive integers");
+    }
+    if (!required.leaseOwner)
+        throw new RangeError("trash sweep leaseOwner must not be empty");
+    let stopped = false;
+    let timer;
+    let inFlight = Promise.resolve();
+    const schedule = (delayMs) => {
+        if (stopped)
+            return;
+        timer = required.scheduler.schedule({ delayMs, run: () => { inFlight = sweep(); } });
+    };
+    const sweep = async () => {
+        let claimed = 0;
+        try {
+            const now = kernelNowIso({ clock: required.clock });
+            const report = await required.sweep({
+                now, leaseOwner: required.leaseOwner,
+                leaseUntil: new Date(Date.parse(now) + leaseMs).toISOString(), limit: batchSize
+            });
+            claimed = report.claimed;
+        }
+        catch (error) {
+            try {
+                optional.onError?.({ error });
+            }
+            catch { /* reporter cannot stop the loop */ }
+        }
+        schedule(claimed >= batchSize ? 0 : intervalMs);
+    };
+    schedule(0);
+    return { async stop(_required) { stopped = true; required.scheduler.cancel({ handle: timer }); await inFlight; } };
+}
+//# sourceMappingURL=sweeper.js.map

package/dist/trash/write-service.d.ts

@@ -0,0 +1,100 @@
+/**
+ * @file The Trash write chokepoint (design §2.2).
+ *
+ * The one thing to understand before editing: **`trash` performs BOTH writes — the domain's marker
+ * flip and the `trashed_items` index insert — inside a single transaction.** The design as first
+ * written had the caller do two writes (`port.trash()` then `adapter.hide()`), and nothing made
+ * them atomic; a failure between them leaves an item that is in the Trash *and still live on the
+ * site*, or hidden with no Trash row, which is unrecoverable through the UI. Removing that seam is
+ * the point of this module, so there is deliberately no exported way to perform half of it.
+ *
+ * Domains do not import this file. They receive {@link RemoveEntity} through their own dependency
+ * object, pre-bound at the composition root with their `entityType` — see `bindRemoveEntity`.
+ */
+import type { IdGenerator } from "@jini-ai/core/primitives";
+import type { ForgetRemovedEntity, RemoveEntity, TrashAdapter, TrashEntityType, TrashEntityPolicy, TrashPort, TrashRepoPort, TransactionRunner } from "./ports.js";
+/** What {@link TrashServiceOptional.onChanged} receives. One event per state change — a no-op outcome
+ *  (`not-found`, `version-changed`, `already-gone`, `forbidden`, `adapter-unavailable`) never fires
+ *  it, because nothing changed. */
+export interface TrashChangeEvent {
+    workspaceId: string;
+    entityType: TrashEntityType;
+    entityId: string;
+    change: "trash" | "restore" | "purge";
+}
+export interface TrashServiceDeps {
+    repo: TrashRepoPort;
+    /**
+     * Plain `Map`, built at the composition root, resolved on EVERY call — never a module-level
+     * registry. This codebase's registries are append-only with no unregister, so any filtering done
+     * at registration time runs exactly once (two real bugs already).
+       */
+    adapters: ReadonlyMap<TrashEntityType, TrashAdapter>;
+    idGen: IdGenerator;
+    entityPolicy: TrashEntityPolicy;
+    transaction: TransactionRunner;
+}
+/** Notifications are best effort inside the operation; transactional follow-ups use withFollowUps. */
+export interface TrashServiceOptional {
+    /** Retention is stamped once when removed; defaults to 60 days. */
+    retentionDays?: number;
+    /**
+     * Fires inside the same transaction after successful marker/index changes. Hosts may stamp a
+     * recovery watermark and enqueue an outbox event here; per-type revisions/events use follow-ups.
+     * Failures are reported and swallowed so notification failure cannot undo the completed writes.
+     */
+    onChanged?: (required: TrashChangeEvent) => void | Promise<void>;
+    onError?: (required: {
+        error: unknown;
+    }) => void;
+}
+/** A host composition error: fail fast rather than hide an entity that can never be restored. */
+export declare class TrashAdapterMissingError extends Error {
+    constructor({ message }: {
+        message: string;
+    }, optional?: {
+        cause?: unknown;
+    });
+}
+/** Stamp retention once at removal; later policy changes cannot shorten an existing promise. */
+export declare const DEFAULT_TRASH_RETENTION_DAYS = 60;
+/**
+ * `at` + {@link DEFAULT_TRASH_RETENTION_DAYS}, as an ISO timestamp.
+ *
+ * Stamped at trash time, not computed at read time, so changing the constant later never
+ * retroactively purges what a user was already promised.
+ *
+ * @complexity O(1).
+ */
+export declare function computePurgeAfter({ at }: {
+    at: string;
+}, optional?: {
+    retentionDays?: number;
+}): string;
+/**
+ * Builds the Trash service.
+ *
+ * @param deps repo, the call-time adapter map, an id generator and a reentrant transaction runner.
+ * @returns the {@link TrashPort} surface. `purgeSelected` requires host-owned human confirmation and per-row authorization.
+ * @complexity O(1) to build.
+ */
+export declare function createTrashService(deps: TrashServiceDeps, optional?: TrashServiceOptional): TrashPort;
+/**
+ * Pre-binds an index-row drop to one `entityType`, producing the function a domain receives as
+ * `deps.forgetRemoved` (see {@link ForgetRemovedEntity} for when a domain needs one).
+ *
+ * Binds against the repo rather than the service on purpose: there is no marker to move here, and
+ * routing it through `TrashPort` would put a method on that port which does half of a `trash`.
+ *
+ * @complexity O(1).
+ */
+export declare function bindForgetRemovedEntity({ repo, entityType }: {
+    repo: TrashRepoPort;
+    entityType: TrashEntityType;
+}): ForgetRemovedEntity;
+/** Bind a domain without making its callers depend on trash vocabulary. */
+export declare function bindRemoveEntity({ trash, entityType }: {
+    trash: TrashPort;
+    entityType: TrashEntityType;
+}): RemoveEntity;
+//# sourceMappingURL=write-service.d.ts.map

package/dist/trash/write-service.js

@@ -0,0 +1,242 @@
+/**
+ * Calls `optional.onChanged`, if present, and never lets it throw. See
+ * {@link TrashServiceOptional.onChanged} for why a failure here must not propagate.
+ *
+ * @complexity O(1) beyond the hook itself.
+ */
+async function notifyChanged(optional, event) {
+    if (!optional.onChanged)
+        return;
+    try {
+        await optional.onChanged(event);
+    }
+    catch (error) {
+        try {
+            optional.onError?.({ error });
+        }
+        catch { /* reporting never undoes a state transition */ }
+    }
+}
+/** A host composition error: fail fast rather than hide an entity that can never be restored. */
+export class TrashAdapterMissingError extends Error {
+    constructor({ message }, optional = {}) {
+        super(message, optional);
+    }
+}
+/** Stamp retention once at removal; later policy changes cannot shorten an existing promise. */
+export const DEFAULT_TRASH_RETENTION_DAYS = 60;
+/**
+ * `at` + {@link DEFAULT_TRASH_RETENTION_DAYS}, as an ISO timestamp.
+ *
+ * Stamped at trash time, not computed at read time, so changing the constant later never
+ * retroactively purges what a user was already promised.
+ *
+ * @complexity O(1).
+ */
+export function computePurgeAfter({ at }, optional = {}) {
+    const retentionDays = optional.retentionDays ?? DEFAULT_TRASH_RETENTION_DAYS;
+    if (!Number.isFinite(retentionDays) || retentionDays < 0)
+        throw new RangeError("trash retentionDays must be non-negative and finite");
+    const base = new Date(at);
+    if (Number.isNaN(base.getTime())) {
+        throw new RangeError(`trash: 'at' is not a parseable timestamp (received ${JSON.stringify(at)})`);
+    }
+    return new Date(base.getTime() + retentionDays * 24 * 60 * 60 * 1000).toISOString();
+}
+/**
+ * Builds the Trash service.
+ *
+ * @param deps repo, the call-time adapter map, an id generator and a reentrant transaction runner.
+ * @returns the {@link TrashPort} surface. `purgeSelected` requires host-owned human confirmation and per-row authorization.
+ * @complexity O(1) to build.
+ */
+export function createTrashService(deps, optional = {}) {
+    const retentionDays = optional.retentionDays ?? DEFAULT_TRASH_RETENTION_DAYS;
+    computePurgeAfter({ at: "2000-01-01T00:00:00.000Z" }, { retentionDays });
+    /** Resolved on every call — see {@link TrashServiceDeps.adapters}. @complexity O(1). */
+    function requireAdapter(entityType) {
+        const adapter = deps.adapters.get(entityType);
+        if (!adapter || !deps.entityPolicy({ entityType })) {
+            throw new TrashAdapterMissingError({ message: `trash: no adapter is registered for entity type '${entityType}'` });
+        }
+        return adapter;
+    }
+    return {
+        /**
+         * Hides the entity and indexes it as one unit.
+         *
+         * @complexity O(1) — one marker UPDATE plus one index INSERT, both inside one transaction.
+             */
+        async trash(required, trashOptional = {}) {
+            const adapter = requireAdapter(required.entityType);
+            return deps.transaction({
+                work: async () => {
+                    const marker = await adapter.hide({
+                        workspaceId: required.workspaceId,
+                        entityId: required.entityId,
+                        at: required.at,
+                        expectedVersion: required.expectedVersion,
+                    }, { actor: required.actor });
+                    if (!marker.ok)
+                        return marker;
+                    const row = {
+                        id: deps.idGen.newId(),
+                        workspaceId: required.workspaceId,
+                        entityType: required.entityType,
+                        entityId: required.entityId,
+                        trashedAt: required.at,
+                        purgeAfter: computePurgeAfter({ at: required.at }, { retentionDays }),
+                        actorPrincipalId: required.actor.principalId,
+                        actorPluginId: required.actor.pluginId ?? null,
+                        displayTitle: required.display.title,
+                        displaySubtitle: required.display.subtitle ?? null,
+                        entityVersion: marker.version,
+                        // The adapter's marker reading wins; caller state only fills in for adapters without one.
+                        priorMarker: marker.priorMarker ?? trashOptional.priorMarker ?? null,
+                    };
+                    await deps.repo.insert({ row });
+                    await notifyChanged(optional, {
+                        workspaceId: required.workspaceId,
+                        entityType: required.entityType,
+                        entityId: required.entityId,
+                        change: "trash",
+                    });
+                    return marker;
+                }
+            });
+        },
+        /**
+         * Clears the domain marker and removes the index row, as one unit.
+         *
+         * An entity whose row was deleted out from under the index returns `"not-found"` and the index
+         * row is LEFT IN PLACE — purge is the only path that removes an index row, and the user can
+         * still select it there. One deletion path, not two.
+         *
+         * @complexity O(1).
+             */
+        async restore(required, restoreOptional = {}) {
+            const row = await deps.repo.findByEntity(required);
+            if (!row)
+                return "not-found";
+            const adapter = deps.adapters.get(required.entityType);
+            if (!adapter || !deps.entityPolicy({ entityType: required.entityType }))
+                return "adapter-unavailable";
+            return deps.transaction({
+                work: async () => {
+                    const marker = await adapter.unhide({
+                        workspaceId: required.workspaceId,
+                        entityId: required.entityId,
+                        at: required.at,
+                        expectedVersion: row.entityVersion,
+                    }, {
+                        priorMarker: row.priorMarker,
+                        ...(restoreOptional.actor !== undefined ? { actor: restoreOptional.actor } : {}),
+                    });
+                    if (!marker.ok)
+                        return marker.reason === "not-found" ? "not-found" : "version-changed";
+                    await deps.repo.deleteById({ workspaceId: required.workspaceId, id: row.id });
+                    await notifyChanged(optional, {
+                        workspaceId: required.workspaceId,
+                        entityType: required.entityType,
+                        entityId: required.entityId,
+                        change: "restore",
+                    });
+                    return "restored";
+                }
+            });
+        },
+        /** @complexity one indexed keyset read; see `TrashRepoPort.list`. */
+        async list(required, listOptional = {}) {
+            return deps.repo.list(required, listOptional);
+        },
+        /**
+         * Permanent deletion of selected rows. Called by the admin Trash screen or the assistant's
+         * human-confirmed permanent-delete tools; callers own confirmation, this service owns row auth.
+         *
+         * Per item, and per item only: one unavailable adapter, one stale version or one row the caller
+         * may not touch must not abort the rest of the selection, so each row gets its own permission
+         * check, its own transaction and its own recorded outcome.
+         *
+         * The gate runs on the row this method looked up, BEFORE the adapter is resolved: a caller who
+         * may not destroy a row must not learn from the outcome whether its domain is still installed.
+         *
+         * @complexity O(k) authorization calls and at most O(k) transactions for k selected ids.
+             */
+        async purgeSelected(required) {
+            const rows = await deps.repo.findByIds({ workspaceId: required.workspaceId, ids: required.ids });
+            const byId = new Map(rows.map((row) => [row.id, row]));
+            const results = [];
+            for (const id of required.ids) {
+                const row = byId.get(id);
+                if (!row) {
+                    results.push({ id, outcome: "not-found" });
+                    continue;
+                }
+                if (!(await required.authorizeItem({ item: row }))) {
+                    results.push({ id, outcome: "forbidden" });
+                    continue;
+                }
+                const adapter = deps.adapters.get(row.entityType);
+                if (!adapter) {
+                    results.push({ id, outcome: "adapter-unavailable" });
+                    continue;
+                }
+                if (!deps.entityPolicy({ entityType: row.entityType })) {
+                    results.push({ id, outcome: "forbidden" });
+                    continue;
+                }
+                const outcome = await deps.transaction({
+                    work: async () => {
+                        const result = await adapter.purge({
+                            workspaceId: row.workspaceId,
+                            entityId: row.entityId,
+                            expectedVersion: row.entityVersion,
+                        }, { actor: required.actor });
+                        // A changed version leaves the index in place: the safe outcome of a restore/edit race
+                        // is that the item survives. Only completed or already-completed removals drop the index.
+                        if (result === "purged" || result === "already-gone") {
+                            await deps.repo.deleteById({ workspaceId: row.workspaceId, id: row.id });
+                        }
+                        // Already-gone is a no-op: nothing changed here, so no notification fires.
+                        if (result === "purged") {
+                            await notifyChanged(optional, {
+                                workspaceId: row.workspaceId,
+                                entityType: row.entityType,
+                                entityId: row.entityId,
+                                change: "purge",
+                            });
+                        }
+                        return result;
+                    }
+                });
+                results.push({ id, outcome });
+            }
+            return { purged: results.filter((r) => r.outcome === "purged").length, results };
+        },
+    };
+}
+/**
+ * Pre-binds an index-row drop to one `entityType`, producing the function a domain receives as
+ * `deps.forgetRemoved` (see {@link ForgetRemovedEntity} for when a domain needs one).
+ *
+ * Binds against the repo rather than the service on purpose: there is no marker to move here, and
+ * routing it through `TrashPort` would put a method on that port which does half of a `trash`.
+ *
+ * @complexity O(1).
+ */
+export function bindForgetRemovedEntity({ repo, entityType }) {
+    return (required) => repo.deleteByEntity({ workspaceId: required.workspaceId, entityType, entityId: required.id });
+}
+/** Bind a domain without making its callers depend on trash vocabulary. */
+export function bindRemoveEntity({ trash, entityType }) {
+    return (required, optional = {}) => trash.trash({
+        workspaceId: required.workspaceId,
+        entityType,
+        entityId: required.id,
+        actor: required.actor,
+        display: required.display,
+        at: required.at,
+        expectedVersion: required.expectedVersion,
+    }, optional);
+}
+//# sourceMappingURL=write-service.js.map