@atomicmemory/core 1.0.0

package/dist/services/document-service.js

@@ -0,0 +1,325 @@
+/**
+ * Document service — Phases 1 and 2 of the large-file ingestion plan.
+ *
+ * Phase 1: pointer-only registry (register / get / list / delete).
+ * Phase 2: text indexing — `indexText` chunks supplied text, embeds
+ * the chunks via the existing core embedding stack, persists chunks to
+ * `document_chunks`, and writes one provenance-linked memory per chunk
+ * so `/v1/memories/search` can retrieve them. Implementation lives in
+ * `document-indexer.ts`; this service is a thin facade.
+ *
+ * Schema validation lives in `src/schemas/documents.ts`; this service
+ * trusts the validated input shape and only enforces the Phase 1
+ * storage-mode invariant defensively (so direct in-process callers
+ * can't bypass the Zod gate). No managed blob storage, no fact
+ * extraction — those are Phase 3+.
+ *
+ * See `Atomicmemory-research/docs/core-repo/design/large-file-ingestion-and-raw-storage-plan-2026-05-08.md`.
+ */
+import { getRawDocumentById, listRawDocuments, registerRawDocument, upsertRawSource, } from '../db/raw-document-repository.js';
+import { listDocumentsForUser, listDocumentsWithoutMemoriesForUser, } from '../db/document-list-repository.js';
+import { listPassportFeed, } from '../db/passport-feed-repository.js';
+import { decodeListCursor } from '../db/document-list-cursor.js';
+import { listOrphanedManagedBlobsForDocument, } from '../db/raw-document-blob-repository.js';
+import { softDeleteDocumentCascade } from '../db/repository-document-delete.js';
+import { cleanupManagedBlobs, ManagedBlobCleanupError } from '../storage/cleanup.js';
+import { buildRawStorageCleanupFailureEnvelope, markCleanupFailedAndSyncArtifact, markCleanupSuccessAndSyncArtifact, } from '../db/raw-doc-artifact-sync.js';
+import { singleStoreRegistry, } from '../storage/store-registry.js';
+import { indexDocumentText, } from './document-indexer.js';
+import { uploadRawDocument, } from './document-upload.js';
+import { markExtractionFailure as markExtractionFailureCore, markIndexFailure as markIndexFailureCore, } from './document-failure-markers.js';
+import { emitFilecoinEvent } from './filecoin-observability.js';
+import { NoopRawContentCodec } from '../storage/codecs/noop-codec.js';
+const PHASE_1_STORAGE_MODE = 'pointer_only';
+const DEFAULT_UPLOAD_CONFIG = {
+    rawStorageMode: 'pointer_only',
+    rawStoragePrefix: '',
+};
+/**
+ * Document service. Phase 1 covers register/get/list/delete; Phase 2
+ * adds `indexText`; Phase 3 adds `uploadRaw` (managed-blob storage).
+ * The Phase-3 dependencies (`rawContentStore`, raw-storage config) are
+ * optional so existing test contexts that only need pointer-only
+ * registration don't have to thread the new wiring.
+ */
+export class DocumentService {
+    pool;
+    rawContentStore;
+    storeRegistry;
+    codec;
+    uploadConfig;
+    constructor(pool, options = {}) {
+        this.pool = pool;
+        this.rawContentStore = options.rawContentStore ?? null;
+        this.storeRegistry = options.storeRegistry ?? singleStoreRegistry(this.rawContentStore);
+        this.codec = options.codec ?? new NoopRawContentCodec();
+        this.uploadConfig = options.config ?? DEFAULT_UPLOAD_CONFIG;
+    }
+    /**
+     * Per-row provider dispatch registry. Exposed so the route layer's
+     * Phase 7a formatters can resolve `delete_semantics` from each
+     * row's `storage_provider` without rebuilding the registry. The
+     * registry is read-only at the route boundary.
+     */
+    getStoreRegistry() {
+        return this.storeRegistry;
+    }
+    /**
+     * Idempotently register a document pointer. Looks up (or inserts) the
+     * matching `raw_sources` row, then registers the document.
+     *
+     * Returns `{ document, created }` where `created = false` when an
+     * active row already existed for the (user, source, external_id,
+     * provider_version) namespace (route handler maps that to a 200; new
+     * inserts map to 201).
+     */
+    async register(input) {
+        assertPointerOnly(input.storageMode);
+        const source = await upsertRawSource(this.pool, {
+            userId: input.userId,
+            sourceSite: input.sourceSite,
+            provider: input.provider,
+            accountId: input.accountId,
+            storageMode: input.storageMode,
+            retentionPolicy: input.retentionPolicy,
+            consentPolicy: input.consentPolicy,
+        });
+        return registerRawDocument(this.pool, {
+            userId: input.userId,
+            rawSourceId: source.id,
+            externalId: input.externalId,
+            externalUri: input.externalUri,
+            displayName: input.displayName,
+            mimeType: input.mimeType,
+            sizeBytes: input.sizeBytes,
+            contentHash: input.contentHash,
+            providerVersion: input.providerVersion,
+            sourceModifiedAt: input.sourceModifiedAt,
+            storageMode: input.storageMode,
+            metadata: input.metadata,
+            extractionStatus: input.extractionStatus,
+            semanticIndexStatus: input.semanticIndexStatus,
+        });
+    }
+    /** Fetch one active document by id; null when missing/deleted/cross-user. */
+    async get(userId, id) {
+        return getRawDocumentById(this.pool, userId, id);
+    }
+    /** List active documents for a user, optionally filtered by source_site. */
+    async list(input) {
+        return listRawDocuments(this.pool, input);
+    }
+    /**
+     * Phase D — cursor-paginated user-scoped document list with optional
+     * recovery-status bucket filter. Distinct from {@link list} which uses
+     * offset/limit + source_site filter (kept for backwards
+     * compatibility with `GET /v1/documents/list`). The route layer
+     * decodes the opaque `cursor` query param via `decodeListCursor`
+     * BEFORE calling this method, so a malformed cursor surfaces as 400
+     * upstream rather than a 500 from the SQL layer.
+     */
+    async listForUser(input) {
+        const decoded = input.cursor !== undefined
+            ? decodeListCursor(input.cursor)
+            : null;
+        if (input.cursor !== undefined && decoded === null) {
+            throw new InvalidDocumentListCursorError();
+        }
+        const repoInput = {
+            userId: input.userId,
+            limit: input.limit,
+            cursor: decoded,
+            statusFilter: input.statusFilter,
+        };
+        return listDocumentsForUser(this.pool, repoInput);
+    }
+    /**
+     * Phase D — list active documents WITHOUT non-deleted memories,
+     * narrowed by the layer-aware recovery filter. Backs the
+     * passport server-side merge document-only stream and the
+     * `GET /v1/documents/without-memories` endpoint.
+     */
+    async listWithoutMemoriesForUser(input) {
+        const decoded = input.cursor !== undefined
+            ? decodeListCursor(input.cursor)
+            : null;
+        if (input.cursor !== undefined && decoded === null) {
+            throw new InvalidDocumentListCursorError();
+        }
+        const repoInput = {
+            userId: input.userId,
+            limit: input.limit,
+            cursor: decoded,
+            statusFilter: input.statusFilter,
+        };
+        return listDocumentsWithoutMemoriesForUser(this.pool, repoInput);
+    }
+    /**
+     * Phase D — passport feed (data-layer grouped query). Backs
+     * `GET /v1/documents/passport-feed`. The webapp's
+     * `/api/context/passport` route consumes this as the memory-feed
+     * stream of its server-side two-stream merge.
+     *
+     * Cursor decoding mirrors the other Phase D list facades; a
+     * malformed cursor (incl. structurally-valid-but-non-server
+     * sortAt) throws `InvalidDocumentListCursorError` so the route
+     * layer maps it to 400 invalid_cursor.
+     */
+    async listPassportFeed(input) {
+        const decoded = input.cursor !== undefined
+            ? decodeListCursor(input.cursor)
+            : null;
+        if (input.cursor !== undefined && decoded === null) {
+            throw new InvalidDocumentListCursorError();
+        }
+        const repoInput = {
+            userId: input.userId,
+            limit: input.limit ?? 50,
+            cursor: decoded,
+        };
+        return listPassportFeed(this.pool, repoInput);
+    }
+    /**
+     * Soft-delete one document together with its Phase 2 derived chunks
+     * and provenance-linked memories, in one transaction with a per-doc
+     * advisory lock. `alreadyDeleted = true` when the row was missing or
+     * previously tombstoned — keeps DELETE idempotent.
+     */
+    async delete(userId, id) {
+        const { removed, blobs: freshBlobs } = await softDeleteDocumentCascade(this.pool, userId, id);
+        // When the document was already tombstoned by a prior call but
+        // its managed blob still needs cleanup (raw_storage_failed),
+        // pick those orphans up here. Otherwise an `alreadyDeleted=true`
+        // response would hide a still-orphaned blob.
+        const blobs = freshBlobs.length > 0
+            ? freshBlobs
+            : await listOrphanedManagedBlobsForDocument(this.pool, userId, id);
+        if (blobs.length > 0) {
+            await this.runBlobCleanupOrThrow(userId, blobs);
+        }
+        return { success: true, alreadyDeleted: !removed };
+    }
+    /**
+     * Run cleanup against `blobs`; on failure mark each failing row
+     * `raw_storage_failed` and throw, on success flip the rows to the
+     * terminal `blob_deleted` state so a future retry of `DELETE
+     * /v1/documents/:id` short-circuits cleanly.
+     */
+    async runBlobCleanupOrThrow(userId, blobs) {
+        const result = await cleanupManagedBlobs(this.storeRegistry, blobs);
+        // Mark partial successes *before* surfacing the error so a retry
+        // doesn't re-attempt cleanup on URIs that are already clean. Per
+        // Phase 4a §1, the marker is chosen by the adapter's `semantics`
+        // field — `'deleted'` writes `blob_deleted`, `'unpinned'` /
+        // `'tombstoned'` write `blob_tombstoned`. Both terminal states
+        // are clean; the orphan-lookup helpers skip both.
+        //
+        // Step 7 of the storage-sibling plan: each marker write is
+        // paired with a sync onto the linked `storage_artifacts` row so
+        // the artifact's `status` follows `raw_documents` through the
+        // terminal state.
+        for (const success of result.successes) {
+            // Step 7 paired marker + artifact sync. Each `success` carries
+            // its `rawDocumentId` (the cleanup blob-ref now threads the
+            // source-row id) so we never disambiguate by URI.
+            await markCleanupSuccessAndSyncArtifact(this.pool, {
+                userId,
+                rawDocumentId: success.rawDocumentId,
+                storageUri: success.storageUri,
+                semantics: success.semantics,
+            });
+            emitDeleteEvent(userId, success.storageProvider, success.semantics);
+        }
+        if (result.failures.length > 0) {
+            for (const failure of result.failures) {
+                await markCleanupFailedAndSyncArtifact(this.pool, {
+                    userId,
+                    rawDocumentId: failure.rawDocumentId,
+                    lastError: buildRawStorageCleanupFailureEnvelope(failure.message, failure.storageProvider),
+                });
+            }
+            throw new ManagedBlobCleanupError(result);
+        }
+    }
+    /**
+     * Phase 2 indexing entry point. Idempotent on byte-identical text
+     * + current `chunker_version`; otherwise re-chunks (soft-deleting
+     * the prior generation of chunks + derived memories first). The
+     * heavy lifting lives in `document-indexer.ts`.
+     */
+    async indexText(input) {
+        return indexDocumentText(this.pool, input);
+    }
+    /**
+     * Phase 3 managed-blob upload. Throws `ManagedStorageDisabledError`
+     * (→ 503) when the deployment runs `rawStorageMode='pointer_only'`,
+     * `UploadDocumentNotFoundError` (→ 404) when the document is missing
+     * or owned by a different user. Idempotent on byte-identical input.
+     */
+    async uploadRaw(input) {
+        return uploadRawDocument(this.pool, this.rawContentStore, this.codec, this.uploadConfig, input);
+    }
+    /**
+     * Phase C constrained extraction-layer transition. See
+     * `services/document-failure-markers.ts` for the full state-machine
+     * docstring; this is a thin facade so route handlers can call into
+     * the service the same way they do for `register` / `indexText` /
+     * `uploadRaw`.
+     */
+    async markExtractionFailure(input) {
+        return markExtractionFailureCore(this.pool, input);
+    }
+    /**
+     * Phase C constrained semantic-index-layer transition.
+     */
+    async markIndexFailure(input) {
+        return markIndexFailureCore(this.pool, input);
+    }
+}
+/**
+ * Phase D — sentinel thrown by {@link DocumentService.listForUser}
+ * when the supplied opaque cursor is malformed. Route handlers map
+ * this to 400 with `error: 'invalid_cursor'`.
+ */
+export class InvalidDocumentListCursorError extends Error {
+    constructor() {
+        super('cursor: invalid base64 / malformed payload');
+        this.name = 'InvalidDocumentListCursorError';
+    }
+}
+/**
+ * Phase 1 storage-mode invariant. The schema layer rejects non-pointer
+ * modes with 400, so this only fires on direct in-process callers; when
+ * it does, it's a contract violation and a 500 is the right outcome.
+ */
+function assertPointerOnly(mode) {
+    if (mode !== PHASE_1_STORAGE_MODE) {
+        throw new Error(`DocumentService: storage_mode '${mode}' is not yet supported — Phase 1 implements pointer_only only`);
+    }
+}
+/**
+ * Phase 8.5 — emit a delete-path observability event keyed to the
+ * adapter's `semantics`. The event taxonomy is `filecoin.delete.*`
+ * so we ONLY emit when the row's `storageProvider === 'filecoin'`
+ * (review-fix HIGH 3); a hypothetical future immediate provider
+ * with `'unpinned'` semantics (e.g. an S3-Glacier-style adapter)
+ * would need its own provider-prefixed event name.
+ *
+ * `'deleted'` semantics (local_fs / s3) emits nothing — the
+ * Filecoin event stream is for Filecoin-shaped lifecycle moments
+ * only.
+ */
+function emitDeleteEvent(userId, storageProvider, semantics) {
+    if (storageProvider !== 'filecoin')
+        return;
+    if (semantics === 'deleted')
+        return;
+    const name = semantics === 'tombstoned'
+        ? 'filecoin.delete.tombstoned'
+        : 'filecoin.delete.unpinned';
+    emitFilecoinEvent(name, {
+        userId,
+        provider: storageProvider,
+        statusAfter: 'blob_tombstoned',
+    });
+}

package/dist/services/document-upload-artifact-sync.d.ts

@@ -0,0 +1,80 @@
+/**
+ * @file Step-7 storage-sibling artifact wiring for the upload pipeline.
+ *
+ * Extracted from `document-upload.ts` so that file stays under the
+ * workspace 400-non-comment-LOC cap. Owns:
+ *
+ *   - `recordUploadResultAndSwapArtifact` — Phase β2 transactional
+ *     helper that records the upload, soft-deletes any prior pointer
+ *     artifact, and inserts a new managed artifact in
+ *     `status='pending'`.
+ *   - `finalizeUploadAndSyncArtifact` — paired Phase γ transaction
+ *     that runs `finalizeUploadStatusWithClient` AND the artifact
+ *     sync in one BEGIN..COMMIT, so the document's
+ *     `raw_storage_status` and the artifact's `status` either both
+ *     commit or both roll back.
+ *   - `failClaimedUploadAndSyncArtifact` — paired failure tx that
+ *     marks the upload row `raw_storage_failed` AND syncs the
+ *     linked artifact.
+ *
+ * The pointer-mode provider constant `EXTERNAL_POINTER_PROVIDER`
+ * lives in `../db/storage-artifact-providers.ts` (DB-layer, no
+ * service-layer dependency); import it from there directly.
+ */
+import pg from 'pg';
+import type { RawDocumentRow } from '../db/raw-document-types.js';
+import type { StoredRawContent } from '../storage/raw-content-store.js';
+export interface RecordUploadResultInput {
+    userId: string;
+    documentId: string;
+    claimId: string;
+    storageUri: string;
+    storageProvider: string;
+    rawStorageMetadata: Record<string, unknown>;
+}
+export interface SwapToManagedInput {
+    document: Pick<RawDocumentRow, 'id' | 'userId' | 'mimeType'>;
+    contentHash: string;
+    stored: StoredRawContent;
+}
+/**
+ * Phase β2 atomic combo: writes the URI/provider/metadata via
+ * `recordUploadResultWithClient`, soft-deletes any prior pointer
+ * artifact, inserts a new managed artifact in `status='pending'`,
+ * and links the document. All within a single BEGIN..COMMIT so the
+ * row never sees a half-applied transition.
+ *
+ * Returns the new artifact id. Throws when the claim was lost (the
+ * caller maps this to `UploadClaimLostError` and runs compensation).
+ */
+export declare function recordUploadResultAndSwapArtifact(pool: pg.Pool, args: RecordUploadResultInput & SwapToManagedInput): Promise<{
+    rowCount: number;
+    artifactId: string | null;
+}>;
+export interface FinalizeUploadAndSyncInput {
+    userId: string;
+    documentId: string;
+    claimId: string;
+    finalStatus: 'blob_stored' | 'blob_pending' | 'blob_available';
+}
+/**
+ * Phase γ paired transition: flip `raw_storage_status` to the final
+ * terminal state AND sync the artifact in the same transaction.
+ * Returns 0 when the CAS-on-claim missed (caller maps to
+ * `UploadClaimLostError`).
+ */
+export declare function finalizeUploadAndSyncArtifact(pool: pg.Pool, args: FinalizeUploadAndSyncInput): Promise<number>;
+export interface FailClaimedUploadAndSyncInput {
+    userId: string;
+    documentId: string;
+    claimId: string;
+    lastError: Record<string, unknown>;
+}
+/**
+ * Phase β failure path: mark the upload row `raw_storage_failed`
+ * AND sync the artifact to `failed` in one transaction. Errors are
+ * not swallowed — the caller decides whether to propagate, but the
+ * marker write and the sync share the same atomicity guarantee as
+ * every other paired transition in Step 7.
+ */
+export declare function failClaimedUploadAndSyncArtifact(pool: pg.Pool, args: FailClaimedUploadAndSyncInput): Promise<number>;

package/dist/services/document-upload-artifact-sync.js

@@ -0,0 +1,162 @@
+/**
+ * @file Step-7 storage-sibling artifact wiring for the upload pipeline.
+ *
+ * Extracted from `document-upload.ts` so that file stays under the
+ * workspace 400-non-comment-LOC cap. Owns:
+ *
+ *   - `recordUploadResultAndSwapArtifact` — Phase β2 transactional
+ *     helper that records the upload, soft-deletes any prior pointer
+ *     artifact, and inserts a new managed artifact in
+ *     `status='pending'`.
+ *   - `finalizeUploadAndSyncArtifact` — paired Phase γ transaction
+ *     that runs `finalizeUploadStatusWithClient` AND the artifact
+ *     sync in one BEGIN..COMMIT, so the document's
+ *     `raw_storage_status` and the artifact's `status` either both
+ *     commit or both roll back.
+ *   - `failClaimedUploadAndSyncArtifact` — paired failure tx that
+ *     marks the upload row `raw_storage_failed` AND syncs the
+ *     linked artifact.
+ *
+ * The pointer-mode provider constant `EXTERNAL_POINTER_PROVIDER`
+ * lives in `../db/storage-artifact-providers.ts` (DB-layer, no
+ * service-layer dependency); import it from there directly.
+ */
+import { failClaimedUploadWithClient, finalizeUploadStatusWithClient, recordUploadResultWithClient, } from '../db/raw-document-blob-repository.js';
+import { assertArtifactLinkable, createStorageArtifact, softDeleteArtifactByIdWithClient, } from '../db/storage-artifact-repository.js';
+import { projectArtifactProviderFields } from '../storage/provider-metadata-projection.js';
+import { syncArtifactStatusFromRawDocument } from '../db/raw-doc-artifact-sync.js';
+/**
+ * Phase β2 atomic combo: writes the URI/provider/metadata via
+ * `recordUploadResultWithClient`, soft-deletes any prior pointer
+ * artifact, inserts a new managed artifact in `status='pending'`,
+ * and links the document. All within a single BEGIN..COMMIT so the
+ * row never sees a half-applied transition.
+ *
+ * Returns the new artifact id. Throws when the claim was lost (the
+ * caller maps this to `UploadClaimLostError` and runs compensation).
+ */
+export async function recordUploadResultAndSwapArtifact(pool, args) {
+    const client = await pool.connect();
+    try {
+        await client.query('BEGIN');
+        const rowCount = await recordUploadResultWithClient(client, {
+            userId: args.userId,
+            documentId: args.documentId,
+            claimId: args.claimId,
+            storageUri: args.storageUri,
+            storageProvider: args.storageProvider,
+            rawStorageMetadata: args.rawStorageMetadata,
+        });
+        if (rowCount === 0) {
+            await client.query('ROLLBACK');
+            return { rowCount: 0, artifactId: null };
+        }
+        const artifactId = await swapToManagedArtifact(client, args);
+        await client.query('COMMIT');
+        return { rowCount, artifactId };
+    }
+    catch (err) {
+        await client.query('ROLLBACK').catch(() => undefined);
+        throw err;
+    }
+    finally {
+        client.release();
+    }
+}
+async function swapToManagedArtifact(client, args) {
+    const priorLookup = await client.query(`SELECT storage_artifact_id FROM raw_documents WHERE id = $1`, [args.document.id]);
+    const priorArtifactId = priorLookup.rows[0]?.storage_artifact_id ?? null;
+    if (priorArtifactId !== null) {
+        // Refuse the swap if the prior artifact's delete lifecycle has
+        // already started (`deleting` / `deleted` / `delete_failed`).
+        // Otherwise the swap's own soft-delete races with the original
+        // caller's claim-and-finalize flow, leaving the doc's cascade
+        // attached to whichever caller wins. Throwing
+        // `ArtifactNotLinkableError` here is preferable: the upload
+        // caller retries after the in-flight delete completes.
+        await assertArtifactLinkable(client, args.document.userId, priorArtifactId);
+        await softDeleteArtifactByIdWithClient(client, args.document.userId, priorArtifactId);
+    }
+    const projected = projectArtifactProviderFields(args.stored.storageProvider, args.stored.providerMetadata);
+    const artifact = await createStorageArtifact(client, {
+        userId: args.document.userId,
+        provider: args.stored.storageProvider,
+        mode: 'managed',
+        uri: args.stored.storageUri,
+        status: 'pending',
+        sizeBytes: args.stored.sizeBytes,
+        contentType: args.document.mimeType ?? null,
+        plaintextHash: args.contentHash,
+        storedHash: args.stored.contentHash,
+        contentEncoding: 'identity',
+        discloseContentHash: false,
+        identifiers: projected.identifiers,
+        providerDetails: projected.providerDetails,
+        metadata: {},
+    });
+    await client.query(`UPDATE raw_documents SET storage_artifact_id = $1, updated_at = NOW()
+       WHERE id = $2`, [artifact.id, args.document.id]);
+    return artifact.id;
+}
+/**
+ * Phase γ paired transition: flip `raw_storage_status` to the final
+ * terminal state AND sync the artifact in the same transaction.
+ * Returns 0 when the CAS-on-claim missed (caller maps to
+ * `UploadClaimLostError`).
+ */
+export async function finalizeUploadAndSyncArtifact(pool, args) {
+    const client = await pool.connect();
+    try {
+        await client.query('BEGIN');
+        const rowCount = await finalizeUploadStatusWithClient(client, args);
+        if (rowCount === 0) {
+            await client.query('ROLLBACK');
+            return 0;
+        }
+        await syncArtifactStatusFromRawDocument(client, {
+            rawDocumentId: args.documentId,
+            newRawStatus: args.finalStatus,
+        });
+        await client.query('COMMIT');
+        return rowCount;
+    }
+    catch (err) {
+        await client.query('ROLLBACK').catch(() => undefined);
+        throw err;
+    }
+    finally {
+        client.release();
+    }
+}
+/**
+ * Phase β failure path: mark the upload row `raw_storage_failed`
+ * AND sync the artifact to `failed` in one transaction. Errors are
+ * not swallowed — the caller decides whether to propagate, but the
+ * marker write and the sync share the same atomicity guarantee as
+ * every other paired transition in Step 7.
+ */
+export async function failClaimedUploadAndSyncArtifact(pool, args) {
+    const client = await pool.connect();
+    try {
+        await client.query('BEGIN');
+        const rowCount = await failClaimedUploadWithClient(client, args);
+        if (rowCount === 0) {
+            await client.query('ROLLBACK');
+            return 0;
+        }
+        await syncArtifactStatusFromRawDocument(client, {
+            rawDocumentId: args.documentId,
+            newRawStatus: 'raw_storage_failed',
+            lastError: args.lastError,
+        });
+        await client.query('COMMIT');
+        return rowCount;
+    }
+    catch (err) {
+        await client.query('ROLLBACK').catch(() => undefined);
+        throw err;
+    }
+    finally {
+        client.release();
+    }
+}

package/dist/services/document-upload-beta2-recovery.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Phase β2 orphan-bytes compensation + raw-document failure-marker
+ * helpers for the managed-blob upload pipeline.
+ *
+ * Extracted from `document-upload.ts` so the orchestration module
+ * stays under the workspace 400-non-comment-LOC cap. The two
+ * exported helpers cover the post-`store.put` failure window:
+ *
+ *   - `compensateOrphanedBlob` runs a best-effort `store.delete`
+ *     for bytes that were durably written but never linked
+ *     (e.g. the prior artifact entered a delete lifecycle between
+ *     our claim and the swap, so `ArtifactNotLinkableError` fires).
+ *   - `markBeta2FailureOnDocument` flips the raw_document to
+ *     `raw_storage_failed` with a typed envelope so the public
+ *     status surfaces stop saying "upload in progress" for a doc
+ *     whose upload actually failed. When cleanup also failed the
+ *     envelope carries `internal_recovery_hint` so a reconciler /
+ *     ops can find the abandoned bytes. The wire formatter
+ *     (`document-response-formatters.ts`) strips `internal_*`
+ *     keys before exposing `last_error` on the public response.
+ */
+import type pg from 'pg';
+import type { StoredRawContent } from '../storage/raw-content-store.js';
+import type { RawContentStore } from '../storage/raw-content-store.js';
+import type { RawDocumentRow } from '../db/raw-document-types.js';
+export type Beta2Compensation = {
+    cleanupSucceeded: true;
+} | {
+    cleanupSucceeded: false;
+    cleanupError: string;
+};
+/**
+ * Best-effort `store.delete` for the orphan-bytes window between
+ * `store.put` returning and `recordUploadResultAndSwapArtifact`
+ * committing the artifact swap. Returns whether cleanup succeeded
+ * (the caller uses this to decide whether to embed the orphan
+ * URI/provider in the raw_document's recovery-hint envelope).
+ *
+ * A cleanup failure is also logged with the originating error so
+ * a `grep '[STORAGE]'` operator can correlate.
+ */
+export declare function compensateOrphanedBlob(store: RawContentStore, storageUri: string, documentId: string, cause: unknown): Promise<Beta2Compensation>;
+export interface Beta2FailureMarkerArgs {
+    pool: pg.Pool;
+    document: Pick<RawDocumentRow, 'id' | 'userId'>;
+    claimId: string;
+    stored: StoredRawContent & {
+        codecMetadata: Record<string, unknown>;
+    };
+    reasonCode: 'artifact_not_linkable' | 'beta2_swap_failed';
+    reasonMessage: string;
+    compensation: Beta2Compensation;
+}
+/**
+ * Mark the doc `raw_storage_failed` with the `artifact_not_linkable`
+ * envelope (or generic `beta2_swap_failed` for other throws).
+ *
+ * Uses the raw-document-only `failClaimedUploadWithClient` — NOT
+ * the paired `failClaimedUploadAndSyncArtifact`. Syncing here
+ * would clobber the prior artifact's state, which is already in
+ * its OWN delete lifecycle and owned by the caller that's
+ * tombstoning it.
+ *
+ * CAS-guarded by `claim_id`: a no-op when the claim was lost,
+ * which prevents a stale marker from overwriting a fresh
+ * worker's state.
+ *
+ * Orphan recovery hint: when cleanup failed the envelope carries
+ * `internal_recovery_hint: { storage_uri, storage_provider, cleanup_error }`
+ * so a reconciler / ops can find the abandoned bytes.
+ */
+export declare function markBeta2FailureOnDocument(args: Beta2FailureMarkerArgs): Promise<void>;