@atomicmemory/core 1.0.0

package/dist/services/storage-service-errors.js

@@ -0,0 +1,189 @@
+/**
+ * @file Typed errors thrown by `StorageService`.
+ *
+ * The route layer pattern-matches these by `instanceof` to emit the
+ * correct HTTP status + error envelope. Service code never embeds
+ * status codes itself; the route is the single place where service
+ * outcomes map to HTTP.
+ */
+export class StorageArtifactNotFoundError extends Error {
+    artifactId;
+    constructor(artifactId) {
+        super(`storage artifact ${artifactId} not found`);
+        this.name = 'StorageArtifactNotFoundError';
+        this.artifactId = artifactId;
+    }
+}
+export class PointerContentNotManagedError extends Error {
+    artifactId;
+    uri;
+    constructor(artifactId, uri) {
+        super(`artifact ${artifactId} is pointer-mode; the server does not proxy pointer content`);
+        this.name = 'PointerContentNotManagedError';
+        this.artifactId = artifactId;
+        this.uri = uri;
+    }
+}
+export class FilecoinDirectStorageNotSupportedError extends Error {
+    provider;
+    constructor(provider = 'filecoin') {
+        super(`Direct ${provider} artifact uploads are not supported in this version. ` +
+            'Use document ingestion or pointer mode.');
+        this.name = 'FilecoinDirectStorageNotSupportedError';
+        this.provider = provider;
+    }
+}
+export class UnsupportedPointerSchemeError extends Error {
+    uri;
+    allowedSchemes;
+    constructor(uri, allowedSchemes) {
+        super(`pointer URI scheme is not allowlisted: ${uri}`);
+        this.name = 'UnsupportedPointerSchemeError';
+        this.uri = uri;
+        this.allowedSchemes = allowedSchemes;
+    }
+}
+export class ArtifactInUseError extends Error {
+    artifactId;
+    referencedByDocumentCount;
+    constructor(artifactId, count) {
+        super(`artifact ${artifactId} is referenced by ${count} document(s)`);
+        this.name = 'ArtifactInUseError';
+        this.artifactId = artifactId;
+        this.referencedByDocumentCount = count;
+    }
+}
+export class ManagedStorageDisabledError extends Error {
+    constructor() {
+        super('managed storage is disabled; the active deployment has ' +
+            "rawStorageMode='pointer_only' so no direct managed upload is possible");
+        this.name = 'ManagedStorageDisabledError';
+    }
+}
+export class InvalidArtifactMetadataError extends Error {
+    reason;
+    constructor(reason) {
+        super(`invalid artifact metadata: ${reason}`);
+        this.name = 'InvalidArtifactMetadataError';
+        this.reason = reason;
+    }
+}
+/**
+ * Thrown when a managed-mode artifact row's `provider` is not
+ * registered with the active `StorageBackendRegistry`. This is an
+ * operational unavailability (the deployment dropped a backend that
+ * still has live data), NOT a 5xx crash — the route layer maps it
+ * to HTTP 503 `storage_backend_unavailable`. The envelope carries
+ * only `provider_id`; internal stack/error details stay server-side.
+ */
+export class BackendNotRegisteredError extends Error {
+    providerId;
+    artifactId;
+    constructor(providerId, artifactId) {
+        super(`storage_backend_unavailable: artifact '${artifactId}' is backed by ` +
+            `provider '${providerId}' which is not registered with this deployment`);
+        this.name = 'BackendNotRegisteredError';
+        this.providerId = providerId;
+        this.artifactId = artifactId;
+    }
+}
+/**
+ * Thrown by `StorageService.putManaged` when the put would write
+ * through a backend whose provider isn't part of the registry's
+ * known set (registered backends + the pointer-only marker). The
+ * route maps this to HTTP 503 `storage_backend_unavailable`. Unlike
+ * `BackendNotRegisteredError` (which fires on read against an
+ * already-persisted row), this fires BEFORE any DB write — the
+ * upload is rejected at the entry point.
+ */
+export class UnregisteredProviderError extends Error {
+    providerId;
+    constructor(providerId) {
+        super(`storage_backend_unavailable: provider '${providerId}' is not registered ` +
+            'with this deployment');
+        this.name = 'UnregisteredProviderError';
+        this.providerId = providerId;
+    }
+}
+/**
+ * Thrown by `StorageService.putManaged` when `backend.put` succeeded
+ * but the post-put DB update and the subsequent recovery (DB retry +
+ * backend cleanup of the just-uploaded bytes) ALL failed. At that
+ * point the bytes survive at the backend AND the DB does not know
+ * the URI. The route maps this to HTTP 503 `put_post_persist_failed`
+ * with the artifact id and provider so ops can investigate. The
+ * orphan URI is captured server-side (in the row's `last_error`
+ * envelope + a structured `storage.put.post_put_unrecoverable`
+ * event) but NEVER on the wire.
+ */
+export class PutPostPersistError extends Error {
+    artifactId;
+    providerId;
+    /** Orphan URI — internal only; the route never surfaces this on the wire. */
+    uri;
+    constructor(artifactId, providerId, uri, cause) {
+        super(`put_post_persist_failed: backend.put succeeded for artifact '${artifactId}' ` +
+            `(provider='${providerId}') but every recovery path failed: ${cause}`);
+        this.name = 'PutPostPersistError';
+        this.artifactId = artifactId;
+        this.providerId = providerId;
+        this.uri = uri;
+    }
+}
+/**
+ * Thrown when a public API caller requests bytes or verifies an
+ * artifact whose managed upload is still in flight (`status='pending'`).
+ * Route maps this to HTTP 409 `artifact_not_ready`. Distinct from
+ * `ArtifactUnavailableError` (terminal `failed`) because the row
+ * MIGHT still reach `stored` if the upload finishes.
+ */
+export class ArtifactNotReadyError extends Error {
+    artifactId;
+    constructor(artifactId) {
+        super(`artifact ${artifactId} is still pending upload finalization`);
+        this.name = 'ArtifactNotReadyError';
+        this.artifactId = artifactId;
+    }
+}
+/**
+ * Thrown when a public API caller requests bytes or verifies an
+ * artifact whose managed upload terminally failed (`status='failed'`
+ * with no URI). The row exists for ops visibility — the caller's
+ * action against it would never succeed because the backend never
+ * persisted the bytes. Route maps this to HTTP 410 `artifact_unavailable`.
+ */
+export class ArtifactUnavailableError extends Error {
+    artifactId;
+    reason;
+    constructor(artifactId, reason) {
+        super(`artifact ${artifactId} is unavailable: ${reason}`);
+        this.name = 'ArtifactUnavailableError';
+        this.artifactId = artifactId;
+        this.reason = reason;
+    }
+}
+/**
+ * Thrown by `deleteArtifact` when `claimDeleteAttempt` returns null
+ * AND the row is currently in `status='deleting'` — another caller
+ * holds an active claim and is mid-cascade / mid-backend-delete.
+ *
+ * Distinct from the idempotent terminal `status='deleted'` path
+ * (which still returns the prior terminal envelope as success) and
+ * from `StorageArtifactNotFoundError` (missing / cross-user). Route
+ * maps this to HTTP 409 `delete_in_flight` with `retryable=true` so
+ * the caller knows the action isn't fatal — just contended — and a
+ * later retry will either find the row `deleted` (idempotent
+ * success) or re-claim it (if the other caller's attempt failed
+ * and the row transitioned to `delete_failed`).
+ */
+export class ArtifactDeleteInFlightError extends Error {
+    artifactId;
+    currentStatus;
+    constructor(artifactId, currentStatus) {
+        super(`delete_in_flight: artifact '${artifactId}' is currently being ` +
+            `deleted by another caller (status='${currentStatus}')`);
+        this.name = 'ArtifactDeleteInFlightError';
+        this.artifactId = artifactId;
+        this.currentStatus = currentStatus;
+    }
+}

package/dist/services/storage-service.d.ts

@@ -0,0 +1,176 @@
+/**
+ * @file Direct storage API orchestration — the seam between the
+ * route layer and the `storage_artifacts` repository + the managed
+ * `StorageBackend`.
+ *
+ * Owns the put-pointer/managed branch, get-content pointer-mode 409,
+ * the delete-policy state
+ * machine (claim → backend-call → mark-success/failure), and the
+ * verify shim. Pointer URIs are validated against the operator
+ * allowlist here; the service NEVER fetches a pointer URI.
+ *
+ * Filecoin-shaped direct managed uploads are gated with a 501 by throwing
+ * `FilecoinDirectStorageNotSupportedError` before the backend is
+ * touched. Pointer mode against these providers is still allowed (it is
+ * metadata-only and backend-independent).
+ */
+import type pg from 'pg';
+import { type StorageArtifactRow, type ListArtifactsOptions, type ListArtifactsResult } from '../db/storage-artifact-repository.js';
+import type { PointerUriScheme } from '../config.js';
+import type { StorageBackendRegistry } from '../storage/storage-backend-registry.js';
+export type ArtifactMetadata = Record<string, string | number | boolean>;
+export interface PutPointerInput {
+    userId: string;
+    uri: string;
+    contentType: string;
+    sizeBytes?: number | null;
+    contentHash?: string | null;
+    metadata?: ArtifactMetadata;
+}
+export interface PutManagedInput {
+    userId: string;
+    body: Buffer;
+    contentType: string;
+    discloseContentHash: boolean;
+    metadata?: ArtifactMetadata;
+}
+export type DeleteArtifactPolicy = 'artifact_only' | 'with_documents';
+export interface DeleteArtifactInput {
+    userId: string;
+    id: string;
+    policy: DeleteArtifactPolicy;
+}
+export interface DeleteArtifactResult {
+    artifact: StorageArtifactRow;
+    cascadedDocumentIds: string[];
+}
+export type VerifyArtifactResult = {
+    kind: 'verified';
+    details?: Record<string, unknown>;
+} | {
+    kind: 'failed';
+    reason: string;
+} | {
+    kind: 'unsupported';
+    reason: string;
+};
+export interface StorageServiceDeps {
+    pool: pg.Pool;
+    /**
+     * Per-row backend dispatch registry. The service's read/delete/verify
+     * paths look up the backend matching the row's `provider` column;
+     * the write path (`putManaged`) writes through `registry.active`.
+     * Pointer artifacts never reach the registry — they short-circuit
+     * in `getArtifactContent`, `deleteArtifact` (`executeBackendDelete`),
+     * and `verifyArtifact` before any lookup. Pointer-only deployments
+     * pass a registry with `active === null` and no legacy backends.
+     *
+     * Legacy callers that pass a single `backend` can wrap it with
+     * `singleBackendRegistry(backend)`.
+     */
+    backendRegistry: StorageBackendRegistry;
+    /** Allowlisted pointer-mode URI schemes captured at startup. */
+    pointerSchemes: ReadonlyArray<PointerUriScheme>;
+    /**
+     * `RuntimeConfig.storageKeyHmacSecret` — used by `putManaged` to
+     * derive a PII-safe per-user prefix for the backend key. Replaces
+     * the plaintext `users/${userId}/...` leg of the previous key
+     * shape. Required at startup; never read env here. See
+     * `storage-key-prefix.ts` for the derivation contract.
+     */
+    storageKeyHmacSecret: string;
+}
+export declare class StorageService {
+    private readonly pool;
+    private readonly backendRegistry;
+    private readonly pointerSchemes;
+    private readonly storageKeyHmacSecret;
+    constructor(deps: StorageServiceDeps);
+    /** The backend the deployment writes NEW managed artifacts to. */
+    private get activeBackend();
+    /**
+     * Resolve the backend for an already-persisted managed-mode row.
+     * Throws `BackendNotRegisteredError` when no adapter matches the
+     * row's `provider`. Pointer rows must short-circuit before this is
+     * called; calling it on a pointer row is a service-layer bug.
+     */
+    private resolveBackendForRow;
+    putPointer(input: PutPointerInput): Promise<StorageArtifactRow>;
+    /**
+     * Managed-mode put — pending-row-first contract.
+     *
+     * 1. Validate gates: managed-storage enabled, provider registered,
+     *    Filecoin-direct carve-out (501).
+     * 2. INSERT a `status='pending'` row with `uri=NULL` and a fresh
+     *    `put_attempt_id`. (This is the DB claim; no backend call yet.)
+     * 3. Call `backend.put(...)` OUTSIDE the DB transaction.
+     * 4. On `backend.put` success: CAS-flip the row to `'stored'` via
+     *    `recordUploadedArtifact`. Recovery handles the rare case
+     *    where that UPDATE fails after the bytes are at the backend
+     *    (single immediate retry, then backend cleanup, then a
+     *    best-effort failure marker — see `recoverPostPutFailure`).
+     * 5. On `backend.put` failure: CAS-flip the row to `'failed'` via
+     *    `markPutFailed`, then re-throw the original backend error.
+     */
+    putManaged(input: PutManagedInput): Promise<StorageArtifactRow>;
+    /**
+     * Validate the deployment can accept a managed write. Throws
+     * `ManagedStorageDisabledError` for pointer-only deployments,
+     * `FilecoinDirectStorageNotSupportedError` for the v1
+     * content-addressed eventual-provider carve-out, and
+     * `UnregisteredProviderError` as a defensive check
+     * against a composition bug where `active` isn't in the registry.
+     */
+    private requireWritableBackend;
+    getArtifactMetadata(userId: string, id: string): Promise<StorageArtifactRow>;
+    getArtifactContent(userId: string, id: string): Promise<{
+        row: StorageArtifactRow;
+        body: Buffer;
+    }>;
+    listArtifacts(userId: string, opts: ListArtifactsOptions): Promise<ListArtifactsResult>;
+    deleteArtifact(input: DeleteArtifactInput): Promise<DeleteArtifactResult>;
+    verifyArtifact(userId: string, id: string): Promise<VerifyArtifactResult>;
+    /**
+     * Reference-count gate + optional document cascade. Runs INSIDE
+     * the claim window (Commit D): the artifact is already in
+     * `status='deleting'`, so concurrent INSERTs are refused by
+     * `assertArtifactLinkable` at the link-write sites — the count
+     * is stable for the rest of the call.
+     *
+     * Every `delete_failed` retry rechecks references too. The old
+     * "delete_failed short-circuits the gate" rule could silently
+     * bulldoze a fresh link added between attempts; this implementation
+     * refuses to finalize unless the policy explicitly opts into a
+     * cascade.
+     *
+     * On `ArtifactInUseError` the caller releases the claim and the
+     * row goes back to its pre-delete state.
+     */
+    private maybeCascadeDocuments;
+    private cascadeDocuments;
+    /**
+     * Run the backend cleanup ONCE (skipped when `backend === null`,
+     * which is the pointer-mode case — pointer rows have no bytes at
+     * a backend), then finalize the artifact AND propagate the
+     * terminal state to every cascaded document in one atomic paired
+     * transaction (`finalizeArtifactDeleteSuccessTx` / `…FailureTx`).
+     *
+     * `backend.delete` runs OUTSIDE the transaction (it is a network
+     * call); the DB finalization either commits both rows together or
+     * rolls them both back. A partial commit that leaves the artifact
+     * terminal while the linked raw_documents stay at
+     * `blob_stored`/`blob_available` is no longer possible. The
+     * document cleanup path never sees the URI here, so there is no
+     * double-delete of the backend object.
+     *
+     * The backend is resolved BEFORE this is called (see
+     * `deleteArtifact` above), so this function never needs to handle
+     * `BackendNotRegisteredError`. Any thrown backend error here is a
+     * runtime delete failure (network outage, etc.) and lands the
+     * artifact in `delete_failed` with a sanitized envelope.
+     */
+    private executeBackendDelete;
+}
+export declare function validateArtifactMetadata(value: unknown): ArtifactMetadata;
+/** SHA-256 helper exposed for tests of the upload-hash contract. */
+export declare function sha256Hex(buffer: Buffer): string;