@atomicmemory/core 1.0.0

package/dist/db/storage-artifact-delete-tx.d.ts

@@ -0,0 +1,56 @@
+/**
+ * @file Paired DB transactions for `StorageService.deleteArtifact`'s
+ * `policy=with_documents` finalization.
+ *
+ * Step 7 follow-up fix: the artifact's CAS-on-claim update and the
+ * cascaded `raw_documents.raw_storage_status` propagation must
+ * commit or roll back together. If they were two separate DB
+ * operations a partial-commit could leave the artifact terminal
+ * (`deleted` / `delete_failed`) while the linked raw_documents
+ * stayed at `blob_stored`/`blob_available`, and the
+ * `deleteArtifact` retry path would not heal it (a second DELETE
+ * on a `deleted` artifact short-circuits early; a `delete_failed`
+ * artifact skips the reference gate).
+ *
+ * Backend.delete itself runs OUTSIDE the transaction (it is a
+ * network call); the DB finalization of `artifact + cascaded docs`
+ * is what must be atomic.
+ */
+import pg from 'pg';
+import { type StorageArtifactRow } from './storage-artifact-repository.js';
+export interface FinalizeArtifactDeleteSuccessInput {
+    userId: string;
+    artifactId: string;
+    claimId: string;
+    cascadedDocumentIds: ReadonlyArray<string>;
+    /** Backend's delete semantics — drives the cascaded doc state. */
+    semantics: 'deleted' | 'unpinned' | 'tombstoned';
+}
+export interface FinalizeArtifactDeleteFailureInput {
+    userId: string;
+    artifactId: string;
+    claimId: string;
+    cascadedDocumentIds: ReadonlyArray<string>;
+    /** Error envelope for the artifact's `last_error` + each cascaded doc. */
+    lastError: Record<string, unknown>;
+}
+/**
+ * Success-path transaction. CAS-flips the artifact to `deleted` AND
+ * advances every cascaded raw_documents row to its terminal
+ * `blob_deleted` / `blob_tombstoned` state in one BEGIN..COMMIT.
+ * Either both commit or both roll back; a partial-commit cannot
+ * leave the rows in a drifted state.
+ */
+export declare function finalizeArtifactDeleteSuccessTx(pool: pg.Pool, input: FinalizeArtifactDeleteSuccessInput): Promise<StorageArtifactRow>;
+/**
+ * Failure-path transaction. CAS-flips the artifact to `delete_failed`
+ * (recording `last_error`) AND advances every cascaded
+ * raw_documents row to `raw_storage_failed` with the same envelope,
+ * atomically.
+ */
+export declare function finalizeArtifactDeleteFailureTx(pool: pg.Pool, input: FinalizeArtifactDeleteFailureInput): Promise<StorageArtifactRow>;
+export declare class CascadedRawDocumentMismatchError extends Error {
+    readonly matched: number;
+    readonly expectedIds: ReadonlyArray<string>;
+    constructor(matched: number, expectedIds: ReadonlyArray<string>);
+}

package/dist/db/storage-artifact-delete-tx.js

@@ -0,0 +1,123 @@
+/**
+ * @file Paired DB transactions for `StorageService.deleteArtifact`'s
+ * `policy=with_documents` finalization.
+ *
+ * Step 7 follow-up fix: the artifact's CAS-on-claim update and the
+ * cascaded `raw_documents.raw_storage_status` propagation must
+ * commit or roll back together. If they were two separate DB
+ * operations a partial-commit could leave the artifact terminal
+ * (`deleted` / `delete_failed`) while the linked raw_documents
+ * stayed at `blob_stored`/`blob_available`, and the
+ * `deleteArtifact` retry path would not heal it (a second DELETE
+ * on a `deleted` artifact short-circuits early; a `delete_failed`
+ * artifact skips the reference gate).
+ *
+ * Backend.delete itself runs OUTSIDE the transaction (it is a
+ * network call); the DB finalization of `artifact + cascaded docs`
+ * is what must be atomic.
+ */
+import { markDeleteFailed, markDeleteSuccess, } from './storage-artifact-repository.js';
+/**
+ * Success-path transaction. CAS-flips the artifact to `deleted` AND
+ * advances every cascaded raw_documents row to its terminal
+ * `blob_deleted` / `blob_tombstoned` state in one BEGIN..COMMIT.
+ * Either both commit or both roll back; a partial-commit cannot
+ * leave the rows in a drifted state.
+ */
+export async function finalizeArtifactDeleteSuccessTx(pool, input) {
+    const client = await pool.connect();
+    try {
+        await client.query('BEGIN');
+        const artifact = await markDeleteSuccess(client, {
+            userId: input.userId,
+            id: input.artifactId,
+            claimId: input.claimId,
+        });
+        await propagateRawStorageTerminalWithClient(client, input.userId, input.cascadedDocumentIds, input.semantics);
+        await client.query('COMMIT');
+        return artifact;
+    }
+    catch (err) {
+        await client.query('ROLLBACK').catch(() => undefined);
+        throw err;
+    }
+    finally {
+        client.release();
+    }
+}
+/**
+ * Failure-path transaction. CAS-flips the artifact to `delete_failed`
+ * (recording `last_error`) AND advances every cascaded
+ * raw_documents row to `raw_storage_failed` with the same envelope,
+ * atomically.
+ */
+export async function finalizeArtifactDeleteFailureTx(pool, input) {
+    const client = await pool.connect();
+    try {
+        await client.query('BEGIN');
+        const artifact = await markDeleteFailed(client, {
+            userId: input.userId,
+            id: input.artifactId,
+            claimId: input.claimId,
+            lastError: input.lastError,
+        });
+        await propagateRawStorageFailureWithClient(client, input.userId, input.cascadedDocumentIds, input.lastError);
+        await client.query('COMMIT');
+        return artifact;
+    }
+    catch (err) {
+        await client.query('ROLLBACK').catch(() => undefined);
+        throw err;
+    }
+    finally {
+        client.release();
+    }
+}
+async function propagateRawStorageTerminalWithClient(client, userId, ids, semantics) {
+    if (ids.length === 0)
+        return;
+    const uniqueIds = Array.from(new Set(ids));
+    const newStatus = semantics === 'deleted' ? 'blob_deleted' : 'blob_tombstoned';
+    const result = await client.query(`UPDATE raw_documents
+        SET raw_storage_status = $1, updated_at = NOW()
+      WHERE user_id = $2 AND id = ANY($3::uuid[]) AND deleted_at IS NOT NULL`, [newStatus, userId, uniqueIds]);
+    assertCascadedRowCount(result.rowCount ?? 0, uniqueIds);
+}
+async function propagateRawStorageFailureWithClient(client, userId, ids, lastError) {
+    if (ids.length === 0)
+        return;
+    const uniqueIds = Array.from(new Set(ids));
+    const result = await client.query(`UPDATE raw_documents
+        SET raw_storage_status = 'raw_storage_failed',
+            last_error = $1::jsonb,
+            updated_at = NOW()
+      WHERE user_id = $2 AND id = ANY($3::uuid[]) AND deleted_at IS NOT NULL`, [JSON.stringify(lastError), userId, uniqueIds]);
+    assertCascadedRowCount(result.rowCount ?? 0, uniqueIds);
+}
+/**
+ * Refuse to commit the paired tx when the cascaded raw_documents
+ * UPDATE matched fewer rows than the caller asked us to propagate
+ * onto. SQL UPDATE success is not semantic success — a stale id,
+ * wrong-owner id, or not-yet-soft-deleted id would otherwise let the
+ * artifact finalize as `deleted` / `delete_failed` while at least
+ * one intended raw_document stayed at `blob_stored` / `blob_available`,
+ * and no retry path heals that drift. Throwing rolls back the whole
+ * tx so caller + DB stay consistent.
+ */
+function assertCascadedRowCount(matched, uniqueIds) {
+    if (matched === uniqueIds.length)
+        return;
+    throw new CascadedRawDocumentMismatchError(matched, uniqueIds);
+}
+export class CascadedRawDocumentMismatchError extends Error {
+    matched;
+    expectedIds;
+    constructor(matched, expectedIds) {
+        super(`finalize cascade matched ${matched} of ${expectedIds.length} raw_documents ` +
+            `(ids: ${expectedIds.join(', ')}) — refusing to finalize artifact while ` +
+            'a cascaded row remains stale');
+        this.matched = matched;
+        this.expectedIds = expectedIds;
+        this.name = 'CascadedRawDocumentMismatchError';
+    }
+}

package/dist/db/storage-artifact-providers.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @file Neutral constants for `storage_artifacts.provider` values.
+ *
+ * Step 7 originally exported `EXTERNAL_POINTER_PROVIDER` from
+ * `services/document-upload-artifact-sync.ts`, but that reversed the
+ * dependency direction: `db/raw-document-repository.ts` (a low-level
+ * persistence module) had to import from a service. Moving the
+ * constant here keeps the DB and service layers free to share it
+ * without the cycle.
+ */
+/**
+ * `provider` value for pointer-mode `storage_artifacts` rows created
+ * at document-registration time. The bytes live at a caller-supplied
+ * URI managed by some external system; the AtomicMemory deployment
+ * is NOT the provider — it only tracks the reference. Treated as a
+ * backend-agnostic external pointer; the redaction allowlist
+ * (`src/storage/artifact-public-redaction.ts`) does not have an
+ * entry for `'external_pointer'`, so `identifiers` /
+ * `provider_details` come back as empty objects on the wire.
+ */
+export declare const EXTERNAL_POINTER_PROVIDER: "external_pointer";

package/dist/db/storage-artifact-providers.js

@@ -0,0 +1,21 @@
+/**
+ * @file Neutral constants for `storage_artifacts.provider` values.
+ *
+ * Step 7 originally exported `EXTERNAL_POINTER_PROVIDER` from
+ * `services/document-upload-artifact-sync.ts`, but that reversed the
+ * dependency direction: `db/raw-document-repository.ts` (a low-level
+ * persistence module) had to import from a service. Moving the
+ * constant here keeps the DB and service layers free to share it
+ * without the cycle.
+ */
+/**
+ * `provider` value for pointer-mode `storage_artifacts` rows created
+ * at document-registration time. The bytes live at a caller-supplied
+ * URI managed by some external system; the AtomicMemory deployment
+ * is NOT the provider — it only tracks the reference. Treated as a
+ * backend-agnostic external pointer; the redaction allowlist
+ * (`src/storage/artifact-public-redaction.ts`) does not have an
+ * entry for `'external_pointer'`, so `identifiers` /
+ * `provider_details` come back as empty objects on the wire.
+ */
+export const EXTERNAL_POINTER_PROVIDER = 'external_pointer';

package/dist/db/storage-artifact-recovery-repository.d.ts

@@ -0,0 +1,66 @@
+/**
+ * @file Storage-level recovery-hint repository.
+ *
+ * `recordStorageUploadRecoveryHint` writes an
+ * `internal_recovery_hint` envelope onto `storage_artifacts.last_error`
+ * for a pending row, scoped by `(id, user_id, put_attempt_id)` CAS.
+ * The helper exists as its own module (not folded into
+ * `storage-artifact-repository.ts`) so the existing 800-line repo
+ * file stays under the workspace LOC cap and so the recovery
+ * envelope shape is documented in a single place.
+ *
+ * v1 path: reuses the existing `last_error` JSONB column. A
+ * dedicated `storage_recovery_events` table is deferred — multi-step
+ * recovery state machines can land that table when a real consumer
+ * shows up.
+ *
+ * Document-side recovery (the rarer post-put orphan branch in
+ * `storage-put-recovery.ts`) writes its own envelopes. This helper
+ * is for non-document storage flows that produce a recovery hint
+ * BEFORE the row leaves the `pending` state — direct
+ * `POST /v1/storage/artifacts` uploads, the future Filecoin
+ * readiness gate, etc. The envelope shape matches the existing
+ * `{ layer, code, message, occurred_at }` contract so log readers
+ * see one consistent shape.
+ */
+import type pg from 'pg';
+/**
+ * Closed type for the recovery hint code. New entries land here as
+ * the contract grows; ad-hoc strings are rejected at the API
+ * boundary so log consumers can rely on a stable enum.
+ */
+export type StorageUploadRecoveryHintCode = 'manual_delete_required' | 'awaiting_provider_readiness' | 'awaiting_payment_authorization' | 'operator_intervention_required';
+export interface StorageUploadRecoveryHintInput {
+    readonly artifactId: string;
+    readonly userId: string;
+    readonly putAttemptId: string;
+    readonly hint: StorageUploadRecoveryHintCode;
+    readonly message?: string;
+    readonly storageProvider?: string;
+}
+/**
+ * Shape of the JSONB envelope written to `storage_artifacts.last_error`.
+ * Exported so tests + downstream log consumers can construct or
+ * inspect envelopes without re-typing the field set.
+ */
+export interface StorageUploadRecoveryHintEnvelope {
+    readonly layer: 'raw_storage';
+    readonly code: 'internal_recovery_hint';
+    readonly internal_recovery_hint: StorageUploadRecoveryHintCode;
+    readonly message: string;
+    readonly storage_provider?: string;
+    readonly occurred_at: string;
+}
+export declare function buildRecoveryHintEnvelope(input: StorageUploadRecoveryHintInput, now?: () => Date): StorageUploadRecoveryHintEnvelope;
+/**
+ * CAS-write a recovery hint onto `storage_artifacts.last_error` for
+ * a pending row. Returns `true` when the CAS matched (`id`,
+ * `user_id`, `put_attempt_id`, `status='pending'`), `false` when
+ * the row was finalized or claimed by another worker.
+ *
+ * The hint is RECORDED ONLY — this helper does not mutate `status`,
+ * `put_attempt_id`, or any other column. The next phase (manual
+ * operator intervention, retry, etc.) is responsible for clearing
+ * or replacing the hint via the existing CAS helpers.
+ */
+export declare function recordStorageUploadRecoveryHint(q: pg.Pool | pg.PoolClient, input: StorageUploadRecoveryHintInput, now?: () => Date): Promise<boolean>;

package/dist/db/storage-artifact-recovery-repository.js

@@ -0,0 +1,58 @@
+/**
+ * @file Storage-level recovery-hint repository.
+ *
+ * `recordStorageUploadRecoveryHint` writes an
+ * `internal_recovery_hint` envelope onto `storage_artifacts.last_error`
+ * for a pending row, scoped by `(id, user_id, put_attempt_id)` CAS.
+ * The helper exists as its own module (not folded into
+ * `storage-artifact-repository.ts`) so the existing 800-line repo
+ * file stays under the workspace LOC cap and so the recovery
+ * envelope shape is documented in a single place.
+ *
+ * v1 path: reuses the existing `last_error` JSONB column. A
+ * dedicated `storage_recovery_events` table is deferred — multi-step
+ * recovery state machines can land that table when a real consumer
+ * shows up.
+ *
+ * Document-side recovery (the rarer post-put orphan branch in
+ * `storage-put-recovery.ts`) writes its own envelopes. This helper
+ * is for non-document storage flows that produce a recovery hint
+ * BEFORE the row leaves the `pending` state — direct
+ * `POST /v1/storage/artifacts` uploads, the future Filecoin
+ * readiness gate, etc. The envelope shape matches the existing
+ * `{ layer, code, message, occurred_at }` contract so log readers
+ * see one consistent shape.
+ */
+export function buildRecoveryHintEnvelope(input, now = () => new Date()) {
+    const envelope = {
+        layer: 'raw_storage',
+        code: 'internal_recovery_hint',
+        internal_recovery_hint: input.hint,
+        message: input.message ?? input.hint,
+        ...(input.storageProvider ? { storage_provider: input.storageProvider } : {}),
+        occurred_at: now().toISOString(),
+    };
+    return envelope;
+}
+/**
+ * CAS-write a recovery hint onto `storage_artifacts.last_error` for
+ * a pending row. Returns `true` when the CAS matched (`id`,
+ * `user_id`, `put_attempt_id`, `status='pending'`), `false` when
+ * the row was finalized or claimed by another worker.
+ *
+ * The hint is RECORDED ONLY — this helper does not mutate `status`,
+ * `put_attempt_id`, or any other column. The next phase (manual
+ * operator intervention, retry, etc.) is responsible for clearing
+ * or replacing the hint via the existing CAS helpers.
+ */
+export async function recordStorageUploadRecoveryHint(q, input, now = () => new Date()) {
+    const envelope = buildRecoveryHintEnvelope(input, now);
+    const result = await q.query(`UPDATE storage_artifacts
+       SET last_error = $4::jsonb,
+           updated_at = NOW()
+       WHERE id = $1
+         AND user_id = $2
+         AND put_attempt_id = $3
+         AND status = 'pending'`, [input.artifactId, input.userId, input.putAttemptId, JSON.stringify(envelope)]);
+    return (result.rowCount ?? 0) > 0;
+}

package/dist/db/storage-artifact-repository.d.ts

@@ -0,0 +1,329 @@
+/**
+ * @file Postgres queries for the `storage_artifacts` table.
+ *
+ * Step 4 of the storage-sibling plan. Single DB seam for everything
+ * artifact-shaped. No HTTP routes, no business logic, no response
+ * formatters — those land in Step 5.
+ *
+ * Owner-scoping rule: every public method except `createStorageArtifact`
+ * takes `userId` and routes it into the WHERE clause. Cross-user reads
+ * and writes return `null` / zero / no rows; they never throw. The
+ * route layer (Step 5) is responsible for translating that into the
+ * correct 404 envelope.
+ *
+ * Internal columns:
+ *   * `plaintext_hash` / `stored_hash` — visible on the repository's
+ *     row type for diagnostic queries. The Step-5 response formatter
+ *     is the only call site that decides whether to expose them on
+ *     the wire (gated by `discloseContentHash`).
+ *   * `last_error` — internal failure envelope; same story.
+ *
+ * The repo writes a closed set of `status` values:
+ *
+ *   stored | pending | available | unavailable | deleting | deleted
+ *   | delete_failed | failed
+ *
+ * Mirrors the SDK's `StorageArtifactStatus` and is enforced by the
+ * `storage_artifacts_status_check` constraint in `schema.sql`.
+ */
+import pg from 'pg';
+/** Internal lifecycle state — closed enum mirrored from the SDK. */
+export type StorageArtifactStatus = 'stored' | 'pending' | 'available' | 'unavailable' | 'deleting' | 'deleted' | 'delete_failed' | 'failed';
+export type StorageArtifactMode = 'pointer' | 'managed';
+export type StorageContentEncoding = 'identity' | 'aes_gcm';
+/**
+ * Full column projection. Carries the internal-only columns
+ * (`plaintext_hash`, `stored_hash`, `last_error`) — Step-5 wire
+ * projection is responsible for redaction.
+ */
+export interface StorageArtifactRow {
+    id: string;
+    userId: string;
+    orgId: string | null;
+    projectId: string | null;
+    provider: string;
+    mode: StorageArtifactMode;
+    /**
+     * Adapter URI. NULL while a managed row is in `pending` (the
+     * backend hasn't returned a URI yet) or `failed` (backend.put
+     * threw). Always set on `pointer` rows and on managed rows that
+     * reached `stored` / `available`.
+     */
+    uri: string | null;
+    status: StorageArtifactStatus;
+    sizeBytes: number | null;
+    contentType: string | null;
+    plaintextHash: string | null;
+    storedHash: string | null;
+    contentEncoding: StorageContentEncoding;
+    discloseContentHash: boolean;
+    identifiers: Record<string, unknown>;
+    lifecycle: Record<string, unknown>;
+    replication: Record<string, unknown> | null;
+    verification: Record<string, unknown> | null;
+    retrieval: Record<string, unknown> | null;
+    providerDetails: Record<string, unknown> | null;
+    metadata: Record<string, unknown>;
+    lastError: Record<string, unknown> | null;
+    /** CAS token for the upload pipeline (pending → stored / failed). */
+    putAttemptId: string | null;
+    deleteAttemptId: string | null;
+    createdAt: Date;
+    updatedAt: Date;
+    deletedAt: Date | null;
+}
+export interface CreateStorageArtifactInput {
+    userId: string;
+    orgId?: string | null;
+    projectId?: string | null;
+    provider: string;
+    mode: StorageArtifactMode;
+    uri: string;
+    status: StorageArtifactStatus;
+    sizeBytes?: number | null;
+    contentType?: string | null;
+    plaintextHash?: string | null;
+    storedHash?: string | null;
+    contentEncoding?: StorageContentEncoding;
+    discloseContentHash?: boolean;
+    identifiers?: Record<string, unknown>;
+    lifecycle?: Record<string, unknown>;
+    replication?: Record<string, unknown> | null;
+    verification?: Record<string, unknown> | null;
+    retrieval?: Record<string, unknown> | null;
+    providerDetails?: Record<string, unknown> | null;
+    metadata?: Record<string, unknown>;
+}
+export interface StorageArtifactListCursor {
+    createdAt: string;
+    id: string;
+}
+export interface ListArtifactsOptions {
+    limit: number;
+    cursor?: StorageArtifactListCursor;
+}
+export interface ListArtifactsResult {
+    rows: StorageArtifactRow[];
+    nextCursor: StorageArtifactListCursor | null;
+}
+export interface MarkDeleteSuccessInput {
+    userId: string;
+    id: string;
+    claimId: string;
+}
+export interface MarkDeleteFailedInput {
+    userId: string;
+    id: string;
+    claimId: string;
+    lastError: Record<string, unknown>;
+}
+/**
+ * Insert a new artifact row. Status, provider, and mode must already
+ * be validated by the caller — the DB-level CHECKs are a backstop, not
+ * a substitute for service-layer input validation.
+ */
+export declare function createStorageArtifact(q: pg.Pool | pg.PoolClient, input: CreateStorageArtifactInput): Promise<StorageArtifactRow>;
+/**
+ * Pending-row-first upload helpers — see
+ * `StorageService.putManaged` for the full lifecycle. The flow:
+ *
+ *   1. `claimPendingArtifact` inserts `status='pending'`, `uri=NULL`,
+ *      `put_attempt_id=<fresh uuid>`. Returns the row + claim id.
+ *   2. Service calls `backend.put(...)` OUTSIDE the DB.
+ *   3a. On success: `recordUploadedArtifact` CAS-flips the row to
+ *       `status='stored'`, sets `uri` + hashes + size, clears
+ *       `put_attempt_id`. Returns the updated row.
+ *   3b. On `backend.put` failure: `markPutFailed` CAS-flips the row
+ *       to `status='failed'`, records `last_error`, clears
+ *       `put_attempt_id`.
+ *   3c. On post-put DB failure: the service's recovery path runs
+ *       backend cleanup and writes a durable failed marker on the
+ *       row (`put_post_persist_failed_cleaned_up` envelope) so ops
+ *       sees `status='failed'`. When cleanup also fails, a durable
+ *       `put_post_persist_unrecoverable` envelope captures the
+ *       orphan URI on `last_error` server-side so the reconciler
+ *       can find and delete the abandoned bytes later. See
+ *       `services/storage-put-recovery.ts` for the full branch tree.
+ */
+export interface ClaimPendingArtifactInput {
+    userId: string;
+    orgId?: string | null;
+    projectId?: string | null;
+    provider: string;
+    contentType?: string | null;
+    contentEncoding?: StorageContentEncoding;
+    discloseContentHash?: boolean;
+    metadata?: Record<string, unknown>;
+}
+export interface ClaimPendingArtifactResult {
+    row: StorageArtifactRow;
+    claimId: string;
+}
+/**
+ * Insert a `status='pending'` managed artifact row with a fresh
+ * `put_attempt_id`. The URI is NULL — set by `recordUploadedArtifact`
+ * after the backend put succeeds.
+ */
+export declare function claimPendingArtifact(q: pg.Pool | pg.PoolClient, input: ClaimPendingArtifactInput): Promise<ClaimPendingArtifactResult>;
+export interface RecordUploadedArtifactInput {
+    userId: string;
+    artifactId: string;
+    putAttemptId: string;
+    uri: string;
+    sizeBytes: number;
+    plaintextHash: string;
+    storedHash: string;
+    identifiers?: Record<string, unknown>;
+    providerDetails?: Record<string, unknown> | null;
+}
+/**
+ * CAS-flip a pending row to `status='stored'`. Matches on
+ * `(id, user_id, put_attempt_id, status='pending')` so a stale
+ * caller cannot finalize someone else's claim. Returns the updated
+ * row when the CAS succeeded; `null` when it lost the race.
+ */
+export declare function recordUploadedArtifact(q: pg.Pool | pg.PoolClient, input: RecordUploadedArtifactInput): Promise<StorageArtifactRow | null>;
+export interface MarkPutFailedInput {
+    userId: string;
+    artifactId: string;
+    putAttemptId: string;
+    lastError: Record<string, unknown>;
+}
+/**
+ * CAS-flip a pending row to `status='failed'` with the supplied
+ * `last_error` envelope. Same CAS shape as `recordUploadedArtifact`.
+ * Returns the failed row when the CAS succeeded; `null` when it
+ * lost the race (claim already cleared by another caller).
+ */
+export declare function markPutFailed(q: pg.Pool | pg.PoolClient, input: MarkPutFailedInput): Promise<StorageArtifactRow | null>;
+/** Owner-scoped lookup. Returns `null` for cross-user / missing / deleted rows. */
+export declare function getStorageArtifactById(pool: pg.Pool, userId: string, id: string): Promise<StorageArtifactRow | null>;
+/**
+ * Owner-scoped lookup that DOES return soft-deleted rows. Used by
+ * the delete-policy state machine so a second `DELETE` on an
+ * already-deleted artifact can return the prior terminal envelope
+ * (the plan's idempotency contract) instead of a 404.
+ */
+export declare function getStorageArtifactByIdIncludingDeleted(pool: pg.Pool, userId: string, id: string): Promise<StorageArtifactRow | null>;
+/**
+ * Mark an artifact `status='deleted'` + stamp `deleted_at`. Used by
+ * Step 7's document-ingestion refactor when a managed upload
+ * replaces a previously-linked pointer artifact (or when a managed
+ * artifact's bytes are cleaned up post-document-delete). Owner-
+ * scoped + idempotent: a row that is already `deleted` stays so.
+ *
+ * Distinct from `markDeleteSuccess` because there is no claim id
+ * to CAS on — the caller has already confirmed the row should be
+ * tombstoned (e.g. the upload service holds the document-row
+ * advisory lock).
+ */
+export declare function softDeleteArtifactByIdWithClient(q: pg.Pool | pg.PoolClient, userId: string, id: string): Promise<void>;
+/**
+ * Count active `raw_documents` rows that reference this artifact for
+ * the supplied owner. The Step-5 delete route uses this to enforce
+ * the `artifact_in_use` 409 envelope when callers omit
+ * `policy=with_documents`.
+ *
+ * Owner-scope invariant: the count includes a row only when BOTH the
+ * artifact and the referencing document belong to `$userId`. The
+ * schema-level composite FK on `raw_documents(storage_artifact_id,
+ * user_id) -> storage_artifacts(id, user_id)` makes the cross-user
+ * row impossible, but this join restates the invariant explicitly so
+ * the query is unambiguous against any DB that pre-dates the
+ * composite FK.
+ */
+export declare function countReferencingDocuments(pool: pg.Pool, userId: string, artifactId: string): Promise<number>;
+/**
+ * Return the ids of active `raw_documents` rows that reference this
+ * artifact for the supplied owner. Same owner-scope invariant as
+ * `countReferencingDocuments`. Used by the delete `with_documents`
+ * cascade path so the service can soft-delete each referencing
+ * document before flipping the artifact's status.
+ */
+export declare function listReferencingDocumentIds(pool: pg.Pool, userId: string, artifactId: string): Promise<string[]>;
+/**
+ * Atomically transition an artifact into `status='deleting'` and stamp
+ * a fresh `delete_attempt_id`. Returns the new claim id on success,
+ * `null` when the row is missing, cross-user, or already in a state
+ * that forbids a new claim (`deleting` / `deleted`).
+ *
+ * `delete_failed` rows ARE re-claimable so the delete-retry path can
+ * make forward progress; the plan defines the second `DELETE` on a
+ * `delete_failed` row as a retry, not an error. The retry path also
+ * clears the prior `last_error` so the in-flight artifact never
+ * reports `status='deleting'` alongside a stale provider error — the
+ * field is repopulated only if THIS attempt fails.
+ */
+export declare function claimDeleteAttempt(pool: pg.Pool, userId: string, id: string): Promise<{
+    claimId: string;
+} | null>;
+/**
+ * Finalize a successful delete. The row's `status` flips to `deleted`,
+ * `deleted_at` is stamped, and the `delete_attempt_id` is cleared.
+ * The CAS condition (matching claim id + current `status='deleting'`)
+ * means a stale caller cannot finalize someone else's claim.
+ *
+ * Throws when no row matches — callers MUST hold a current claim.
+ */
+export declare function markDeleteSuccess(q: pg.Pool | pg.PoolClient, args: MarkDeleteSuccessInput): Promise<StorageArtifactRow>;
+/**
+ * Record a provider-cleanup failure. Same CAS guard as
+ * `markDeleteSuccess`; `last_error` is replaced with the supplied
+ * envelope so the caller can retry against a clean state. Status
+ * lands on `delete_failed`, which is re-claimable by a subsequent
+ * `claimDeleteAttempt`.
+ */
+export declare function markDeleteFailed(q: pg.Pool | pg.PoolClient, args: MarkDeleteFailedInput): Promise<StorageArtifactRow>;
+export interface ReleaseDeleteClaimInput {
+    userId: string;
+    id: string;
+    claimId: string;
+    /** Status the row must revert to (typically the pre-claim status). */
+    restoreStatus: StorageArtifactStatus;
+    /** `last_error` the row had before the claim cleared it. */
+    restoreLastError: Record<string, unknown> | null;
+}
+/**
+ * Release a `deleting` claim without finalizing. Used by the
+ * delete-cascade race fix (Commit D): claim runs BEFORE the
+ * reference-count gate so concurrent INSERTs cannot slip in a new
+ * link, but if the gate then throws `ArtifactInUseError` we must
+ * revert the row from `deleting` back to its pre-claim status
+ * (and restore the pre-claim `last_error`, since `claimDeleteAttempt`
+ * cleared it). CAS-scoped to the row's `(user_id, delete_attempt_id,
+ * status='deleting')` so a stale caller cannot revert someone
+ * else's claim. Returns true on a real revert, false on CAS miss
+ * (e.g., concurrent recovery already finalized the row).
+ */
+export declare function releaseDeleteClaim(pool: pg.Pool, args: ReleaseDeleteClaimInput): Promise<boolean>;
+/**
+ * Sentinel thrown by `assertArtifactLinkable` when a caller tries
+ * to link a `raw_documents.storage_artifact_id` to an artifact
+ * that has already entered (or completed) its delete lifecycle.
+ * The link-write sites surface this so a concurrent delete cannot
+ * race with a fresh link and end up with a document pointing at
+ * deleted content.
+ */
+export declare class ArtifactNotLinkableError extends Error {
+    readonly artifactId: string;
+    readonly status: StorageArtifactStatus;
+    constructor(artifactId: string, status: StorageArtifactStatus);
+}
+/**
+ * Refuse to link a `raw_documents` row to an artifact whose status
+ * is in `UNLINKABLE_STATUSES`. Throws `ArtifactNotLinkableError`
+ * on a hit; no-ops otherwise. Takes a `PoolClient` so the caller
+ * can scope the check to its own transaction.
+ */
+export declare function assertArtifactLinkable(q: pg.Pool | pg.PoolClient, userId: string, artifactId: string): Promise<void>;
+/**
+ * List a user's artifacts in `(created_at DESC, id DESC)` order with
+ * keyset pagination. The cursor encodes the last row of the previous
+ * page; pass `undefined` for the first page. Returns `nextCursor=null`
+ * when the caller has reached the end of the user's rows.
+ *
+ * Soft-deleted rows (`deleted_at IS NOT NULL`) are excluded from the
+ * listing — the Step-5 list endpoint does NOT show tombstones by
+ * default.
+ */
+export declare function listArtifactsForUser(pool: pg.Pool, userId: string, opts: ListArtifactsOptions): Promise<ListArtifactsResult>;