@atomicmemory/core 1.0.0

package/dist/storage/raw-content-store.d.ts

@@ -0,0 +1,228 @@
+/**
+ * Raw-content storage interface for the document pipeline.
+ *
+ * Adapter-agnostic facade for the bytes that back a document with
+ * `storage_mode = 'managed_blob'`. Implementations live alongside this
+ * file (`local-fs-store.ts`, `s3-store.ts`); the factory in
+ * `factory.ts` selects one at startup based on `RuntimeConfig`.
+ *
+ * Contract:
+ *
+ * - `put` writes the supplied bytes under the supplied key, returns the
+ *   URI we will persist on `raw_documents.storage_uri`.
+ * - `get` and `head` accept the same URI shape `put` returned. They are
+ *   the read-side hooks the future parsing path will call.
+ * - `delete` is **idempotent**: a missing key returns `{ deleted: false }`,
+ *   not an error. Transport/auth failures still throw.
+ * - Adapters MUST NOT silently fall back to a different provider; if
+ *   their config is wrong or the upstream service is unavailable, they
+ *   must throw.
+ */
+/**
+ * Lifecycle hint returned by `put`. Immediate providers (`local_fs`,
+ * `s3`) always report `'stored'` — bytes are retrievable the moment
+ * `put` returns. Eventual providers (e.g. Filecoin onramps in a future
+ * phase) may report `'pending'` when the provider has accepted the
+ * upload but storage/retrievability is not yet confirmed; the service
+ * layer maps that onto `raw_storage_status='blob_pending'` and a
+ * reconciler later promotes the row to `'blob_available'` or
+ * `'blob_archival_failed'`.
+ */
+export type StoredRawContentStatus = 'stored' | 'pending';
+/** Identifier returned by `put`; opaque to the rest of the codebase. */
+export interface StoredRawContent {
+    /** Adapter-prefixed URI we persist on `raw_documents.storage_uri`. */
+    storageUri: string;
+    /** Adapter id (e.g. `local_fs`, `s3`). Mirrors `raw_documents.storage_provider`. */
+    storageProvider: string;
+    /** SHA-256 hex of the bytes the adapter actually stored. */
+    contentHash: string;
+    /** Bytes actually persisted. Always equals `input.body.length`. */
+    sizeBytes: number;
+    /** See {@link StoredRawContentStatus}. */
+    status: StoredRawContentStatus;
+    /** Provider-side identifiers the service layer persists on `raw_documents.raw_storage_metadata`. */
+    providerMetadata: RawContentProviderMetadata;
+}
+export interface PutRawContentInput {
+    /** Adapter-relative key (e.g. `<prefix>/s/<hmac-hex32>/documents/<doc-id>/<hash>.bin`). */
+    key: string;
+    /** Bytes to persist. The adapter does not mutate this. */
+    body: Buffer;
+    /** Optional MIME type, persisted alongside the blob when supported. */
+    contentType?: string;
+}
+/**
+ * Free-form provider-side metadata. Immediate providers may
+ * populate scalar fields like `etag`/`versionId`/`mtime`;
+ * content-addressed providers nest a provider-keyed sibling
+ * carrying their own internal shape (e.g. the Filecoin adapter
+ * writes `{ filecoin: { piece_cid, copies, … } }`). The exact
+ * sub-shape is provider-specific and treated as opaque by the
+ * upload pipeline; the public-projection seam
+ * (`filecoin-public-metadata.ts` and friends) is the single
+ * translator from that internal shape to the wire response.
+ */
+export type RawContentProviderMetadata = Record<string, unknown>;
+export interface RawContentMetadata {
+    contentLength: number;
+    contentType: string | null;
+    contentHash: string | null;
+    providerMetadata: RawContentProviderMetadata;
+}
+/**
+ * Permanent-failure signal returned by `head()` when the provider
+ * itself reports that this specific URI / CID will NEVER become
+ * retrievable. The reconciler routes a `permanent` head
+ * result directly to `blob_archival_failed` without consuming a
+ * retry — there's no point in continuing to probe.
+ *
+ * Adapters MUST only set this for per-row terminal failures
+ * (Filecoin onramp `status: 'failed'`, malformed `ipfs://` URI,
+ * etc.). Auth / capability / rate-limit / 5xx outages are GLOBAL
+ * infra failures affecting every row — those stay transient
+ * (thrown errors or `exists: false`) so a single misconfigured
+ * deployment doesn't permanently fail every pending row.
+ */
+export interface RawContentPermanentFailure {
+    code: string;
+    message: string;
+}
+export interface RawContentHeadResult {
+    exists: boolean;
+    metadata: RawContentMetadata | null;
+    /** Optional per-row terminal-failure signal; see {@link RawContentPermanentFailure}. */
+    failure?: RawContentPermanentFailure;
+}
+export interface RawContentGetResult {
+    body: Buffer;
+    metadata: RawContentMetadata;
+}
+export interface RawContentDeleteResult {
+    /**
+     * `true` when the adapter actively removed bytes; `false` when the
+     * adapter found nothing to remove (already-missing). Both are
+     * NON-ERROR outcomes — the cleanup helper records both in
+     * `successes[]` and writes a terminal status marker either way.
+     */
+    deleted: boolean;
+    /**
+     * What the adapter's `delete` call DID at the provider boundary
+     * (rev-2 §1, rev-7 §5). Drives the cleanup marker:
+     *
+     *   - `'deleted'`     → `markRawStorageDeletedByUri`   → `blob_deleted`
+     *   - `'unpinned'`    → `markRawStorageTombstonedByUri` → `blob_tombstoned`
+     *   - `'tombstoned'`  → `markRawStorageTombstonedByUri` → `blob_tombstoned`
+     *
+     * Already-missing carries the provider's natural semantics — a
+     * local_fs `ENOENT` is still `'deleted'` (bytes are gone), a
+     * Filecoin already-removed is still `'tombstoned'` (we stop
+     * managing the bytes either way).
+     */
+    semantics: 'deleted' | 'unpinned' | 'tombstoned';
+    /**
+     * **Internal-only** billing/cost-impact metadata for uncertain
+     * delete outcomes (Phase 7 of the Filecoin harvest plan). For
+     * Filecoin, the Synapse SDK's `deletePiece({piece})` returns
+     * an on-chain `0x…` transaction hash that scheduled the
+     * removal — operators correlate this hash to chain-side gas
+     * cost so they can audit the cost-impact of a cleanup pass.
+     * Other providers (`local_fs`, `s3`) leave the field
+     * `undefined`.
+     *
+     * **MUST NOT cross any public boundary.** The cleanup-result
+     * DTO (`ManagedBlobCleanupSuccess`) is closed-key by design;
+     * the route response shape never includes `txHash`. The only
+     * legitimate consumer is the internal observability emitter
+     * (`emitFilecoinEvent('filecoin.delete.tombstoned', { …,
+     * deleteTxHash })`), which logs to operator-side telemetry.
+     * The leak-invariant tests in
+     * `cleanup-leak-invariants.test.ts` pin the absence on the
+     * public side.
+     */
+    txHash?: string;
+}
+/**
+ * Capability advertisement for a `RawContentStore` instance. The
+ * upload service, status mapping, and `/v1/documents/limits` route
+ * read these to decide (a) which `raw_storage_status` to write after a
+ * successful `put`, (b) how `delete` interacts with the managed
+ * object (issued provider removal vs unpin vs tombstone), and (c)
+ * what semantics to advertise to clients via the preflight endpoint.
+ */
+export interface RawContentStoreCapabilities {
+    /**
+     * `'location'` — provider URIs are path-addressed (S3 key, local-fs
+     * path). A subsequent `put` to the same key replaces the bytes the
+     * URI resolves to; the URI does NOT carry a content commitment.
+     * `'content'` — provider URIs are content-addressed (e.g. CID), so
+     * the URI is itself a commitment over the bytes the caller stored.
+     */
+    addressing: 'location' | 'content';
+    /**
+     * `'immediate'` — bytes are retrievable the instant `put` resolves.
+     * `'eventual'` — bytes may not yet be retrievable when `put`
+     * resolves; the provider exposes a separate "is it available yet"
+     * signal that the future reconciler consults.
+     */
+    retrievalConsistency: 'immediate' | 'eventual';
+    /**
+     * Describes what AtomicMemory's `delete` call DOES at the provider
+     * boundary; it does NOT promise universal byte erasure (provider
+     * versioning, object-lock, retention policy, replication, etc. live
+     * outside AtomicMemory's control).
+     *
+     * `'delete'` — `delete` issues the provider's removal operation for
+     * the managed object (e.g. `DeleteObject`, `unlink`). The provider
+     * may still retain prior versions / replicas / backups according to
+     * its own configuration; AtomicMemory does not assert otherwise.
+     * `'unpin'` — `delete` removes AtomicMemory's pin/reference only;
+     * the provider may continue to serve the bytes from other peers.
+     * `'tombstone'` — AtomicMemory stops managing the bytes and cannot
+     * issue removal at the provider (typical for decentralized
+     * networks where AtomicMemory is one of many holders).
+     */
+    deleteSemantics: 'delete' | 'unpin' | 'tombstone';
+    /** Whether `head` is implemented (true for all current adapters). */
+    supportsHead: boolean;
+    /** Whether `get` is implemented (true for all current adapters). */
+    supportsGet: boolean;
+}
+/**
+ * Opaque provider hints that `head`/`delete` MAY consult to optimize
+ * lookups. Shape: a provider-keyed map mirroring the sidecar
+ * `raw_documents.raw_storage_metadata` carries (e.g.
+ * `{ filecoin: { data_set_id: '42' } }`). Adapters MUST treat
+ * unknown / malformed / missing entries as ABSENT and fall back to
+ * their normal lookup path — hints are an optimization, never a
+ * correctness contract. The generic shape stays a plain
+ * `Record<string, unknown>` so the boundary doesn't acquire any
+ * provider-specific surface (rev-c201f21 instruction §4); each
+ * adapter parses its own sibling internally.
+ */
+export type RawContentHints = Readonly<Record<string, unknown>>;
+/**
+ * Raw-content adapter. All methods are user-agnostic — caller scoping
+ * lives in the key the route layer constructs.
+ *
+ * `head` and `delete` accept an optional `hints` object that adapters
+ * MAY use to short-circuit lookups (e.g. the Filecoin adapter reads
+ * `hints.filecoin.data_set_id` so it can call
+ * `createContext({dataSetId})` directly instead of scanning every
+ * owned data set via `findDataSets`). Adapters that don't recognize
+ * a hint MUST ignore it.
+ */
+export interface RawContentStore {
+    /** Adapter id, persisted on `raw_documents.storage_provider`. */
+    readonly provider: string;
+    /** See {@link RawContentStoreCapabilities}. */
+    readonly capabilities: RawContentStoreCapabilities;
+    put(input: PutRawContentInput): Promise<StoredRawContent>;
+    get(storageUri: string): Promise<RawContentGetResult>;
+    head(storageUri: string, hints?: RawContentHints): Promise<RawContentHeadResult>;
+    delete(storageUri: string, hints?: RawContentHints): Promise<RawContentDeleteResult>;
+}
+/** Thrown when a storage URI doesn't match the adapter's expected shape. */
+export declare class RawStorageUriError extends Error {
+    constructor(message: string);
+}

package/dist/storage/raw-content-store.js

@@ -0,0 +1,27 @@
+/**
+ * Raw-content storage interface for the document pipeline.
+ *
+ * Adapter-agnostic facade for the bytes that back a document with
+ * `storage_mode = 'managed_blob'`. Implementations live alongside this
+ * file (`local-fs-store.ts`, `s3-store.ts`); the factory in
+ * `factory.ts` selects one at startup based on `RuntimeConfig`.
+ *
+ * Contract:
+ *
+ * - `put` writes the supplied bytes under the supplied key, returns the
+ *   URI we will persist on `raw_documents.storage_uri`.
+ * - `get` and `head` accept the same URI shape `put` returned. They are
+ *   the read-side hooks the future parsing path will call.
+ * - `delete` is **idempotent**: a missing key returns `{ deleted: false }`,
+ *   not an error. Transport/auth failures still throw.
+ * - Adapters MUST NOT silently fall back to a different provider; if
+ *   their config is wrong or the upstream service is unavailable, they
+ *   must throw.
+ */
+/** Thrown when a storage URI doesn't match the adapter's expected shape. */
+export class RawStorageUriError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'RawStorageUriError';
+    }
+}

package/dist/storage/s3-store.d.ts

@@ -0,0 +1,42 @@
+/**
+ * S3-compatible adapter for `RawContentStore`.
+ *
+ * Backed by `@aws-sdk/client-s3`. Works against AWS S3 (no `endpoint`
+ * override) and against S3-compatible providers like Cloudflare R2 or
+ * MinIO when an explicit `endpoint` URL is supplied. The adapter is
+ * stateless across calls — one `S3Client` is shared per instance.
+ *
+ * Storage URI shape: `s3://<bucket>/<key>`. The bucket carried in the
+ * URI is what the adapter writes/reads; if a future operator changes
+ * `RAW_STORAGE_BUCKET`, the URIs persisted on existing rows still point
+ * at the original bucket, which is the correct semantics for moving the
+ * default bucket without orphaning historical blobs.
+ *
+ * Idempotent delete: S3 `DeleteObject` is itself idempotent (no error
+ * on missing key); `head` translates `NotFound`/`NoSuchKey` to
+ * `{exists: false}` rather than throwing.
+ */
+import { S3Client } from '@aws-sdk/client-s3';
+import { type PutRawContentInput, type RawContentDeleteResult, type RawContentGetResult, type RawContentHeadResult, type RawContentHints, type RawContentStore, type RawContentStoreCapabilities, type StoredRawContent } from './raw-content-store.js';
+export interface S3RawContentStoreOptions {
+    /** Default bucket new puts write to. Existing URIs honor their own bucket. */
+    bucket: string;
+    region: string;
+    /** Custom endpoint URL for R2/MinIO/etc. Omit for AWS S3 default. */
+    endpoint?: string;
+    accessKeyId: string;
+    secretAccessKey: string;
+    /** Optional pre-built client — primarily an injection seam for tests. */
+    client?: S3Client;
+}
+export declare class S3RawContentStore implements RawContentStore {
+    readonly provider: "s3";
+    readonly capabilities: RawContentStoreCapabilities;
+    private readonly client;
+    private readonly bucket;
+    constructor(options: S3RawContentStoreOptions);
+    put(input: PutRawContentInput): Promise<StoredRawContent>;
+    get(storageUri: string): Promise<RawContentGetResult>;
+    head(storageUri: string, _hints?: RawContentHints): Promise<RawContentHeadResult>;
+    delete(storageUri: string, _hints?: RawContentHints): Promise<RawContentDeleteResult>;
+}

package/dist/storage/s3-store.js

@@ -0,0 +1,181 @@
+/**
+ * S3-compatible adapter for `RawContentStore`.
+ *
+ * Backed by `@aws-sdk/client-s3`. Works against AWS S3 (no `endpoint`
+ * override) and against S3-compatible providers like Cloudflare R2 or
+ * MinIO when an explicit `endpoint` URL is supplied. The adapter is
+ * stateless across calls — one `S3Client` is shared per instance.
+ *
+ * Storage URI shape: `s3://<bucket>/<key>`. The bucket carried in the
+ * URI is what the adapter writes/reads; if a future operator changes
+ * `RAW_STORAGE_BUCKET`, the URIs persisted on existing rows still point
+ * at the original bucket, which is the correct semantics for moving the
+ * default bucket without orphaning historical blobs.
+ *
+ * Idempotent delete: S3 `DeleteObject` is itself idempotent (no error
+ * on missing key); `head` translates `NotFound`/`NoSuchKey` to
+ * `{exists: false}` rather than throwing.
+ */
+import { createHash } from 'node:crypto';
+import { DeleteObjectCommand, GetObjectCommand, HeadObjectCommand, PutObjectCommand, S3Client, } from '@aws-sdk/client-s3';
+import { RawStorageUriError, } from './raw-content-store.js';
+const PROVIDER = 's3';
+const URI_PREFIX = 's3://';
+/**
+ * S3 is path-addressed (`s3://<bucket>/<key>` — overwrites of the same
+ * key replace the bytes the URI resolves to), bytes are retrievable
+ * the moment `PutObject` returns (read-after-write consistent), and
+ * `DeleteObject` issues the provider's removal operation for the
+ * managed object. AtomicMemory does not assert what the bucket's
+ * versioning, object-lock, retention, or replication policies do
+ * with that delete call — those live outside the adapter contract.
+ */
+const CAPABILITIES = Object.freeze({
+    addressing: 'location',
+    retrievalConsistency: 'immediate',
+    deleteSemantics: 'delete',
+    supportsHead: true,
+    supportsGet: true,
+});
+export class S3RawContentStore {
+    provider = PROVIDER;
+    capabilities = CAPABILITIES;
+    client;
+    bucket;
+    constructor(options) {
+        if (!options.bucket)
+            throw new Error('S3RawContentStore: bucket is required');
+        if (!options.region)
+            throw new Error('S3RawContentStore: region is required');
+        this.bucket = options.bucket;
+        this.client = options.client ?? new S3Client(buildClientConfig(options));
+    }
+    async put(input) {
+        await this.client.send(new PutObjectCommand({
+            Bucket: this.bucket,
+            Key: input.key,
+            Body: input.body,
+            ContentType: input.contentType,
+        }));
+        return {
+            storageUri: `${URI_PREFIX}${this.bucket}/${input.key}`,
+            storageProvider: PROVIDER,
+            contentHash: sha256Hex(input.body),
+            sizeBytes: input.body.length,
+            status: 'stored',
+            providerMetadata: {},
+        };
+    }
+    async get(storageUri) {
+        const { bucket, key } = parseUri(storageUri);
+        const result = await this.client.send(new GetObjectCommand({ Bucket: bucket, Key: key }));
+        const body = await collectBody(result.Body);
+        return {
+            body,
+            metadata: {
+                contentLength: result.ContentLength ?? body.length,
+                contentType: result.ContentType ?? null,
+                contentHash: sha256Hex(body),
+                providerMetadata: extractProviderMetadata(result),
+            },
+        };
+    }
+    async head(storageUri, _hints) {
+        const { bucket, key } = parseUri(storageUri);
+        try {
+            const result = await this.client.send(new HeadObjectCommand({ Bucket: bucket, Key: key }));
+            return {
+                exists: true,
+                metadata: {
+                    contentLength: result.ContentLength ?? 0,
+                    contentType: result.ContentType ?? null,
+                    contentHash: null,
+                    providerMetadata: extractProviderMetadata(result),
+                },
+            };
+        }
+        catch (err) {
+            if (isNotFound(err))
+                return { exists: false, metadata: null };
+            throw err;
+        }
+    }
+    async delete(storageUri, _hints) {
+        const { bucket, key } = parseUri(storageUri);
+        try {
+            // Pre-check existence so the response distinguishes "we deleted
+            // something" from "it was already gone". S3's DeleteObject would
+            // otherwise return success in both cases.
+            const present = await this.head(storageUri);
+            if (!present.exists)
+                return { deleted: false, semantics: 'deleted' };
+            await this.client.send(new DeleteObjectCommand({ Bucket: bucket, Key: key }));
+            return { deleted: true, semantics: 'deleted' };
+        }
+        catch (err) {
+            if (isNotFound(err))
+                return { deleted: false, semantics: 'deleted' };
+            throw err;
+        }
+    }
+}
+function buildClientConfig(options) {
+    const cfg = {
+        region: options.region,
+        credentials: {
+            accessKeyId: options.accessKeyId,
+            secretAccessKey: options.secretAccessKey,
+        },
+    };
+    if (options.endpoint) {
+        cfg.endpoint = options.endpoint;
+        // R2 / MinIO require path-style addressing; AWS S3 supports it too.
+        cfg.forcePathStyle = true;
+    }
+    return cfg;
+}
+function parseUri(storageUri) {
+    if (!storageUri.startsWith(URI_PREFIX)) {
+        throw new RawStorageUriError(`expected s3:// URI, got: ${storageUri}`);
+    }
+    const trimmed = storageUri.slice(URI_PREFIX.length);
+    const slash = trimmed.indexOf('/');
+    if (slash <= 0 || slash === trimmed.length - 1) {
+        throw new RawStorageUriError(`malformed s3 URI: ${storageUri}`);
+    }
+    return { bucket: trimmed.slice(0, slash), key: trimmed.slice(slash + 1) };
+}
+function sha256Hex(buf) {
+    return createHash('sha256').update(buf).digest('hex');
+}
+async function collectBody(body) {
+    if (body == null)
+        return Buffer.alloc(0);
+    const candidate = body;
+    if (typeof candidate.transformToByteArray === 'function') {
+        return Buffer.from(await candidate.transformToByteArray());
+    }
+    // Fallback for already-buffered bodies (mocks/tests).
+    if (Buffer.isBuffer(body))
+        return body;
+    if (body instanceof Uint8Array)
+        return Buffer.from(body);
+    throw new Error('S3 GetObject body shape not recognized');
+}
+function extractProviderMetadata(result) {
+    const meta = {};
+    if (result.ETag)
+        meta.etag = result.ETag;
+    if (result.VersionId)
+        meta.versionId = result.VersionId;
+    if (result.LastModified)
+        meta.lastModified = result.LastModified.toISOString();
+    return meta;
+}
+function isNotFound(err) {
+    if (typeof err !== 'object' || err === null)
+        return false;
+    const e = err;
+    return e.name === 'NotFound' || e.name === 'NoSuchKey' || e.Code === 'NoSuchKey'
+        || e.$metadata?.httpStatusCode === 404;
+}

package/dist/storage/storage-backend-registry.d.ts

@@ -0,0 +1,58 @@
+/**
+ * @file Per-row `StorageBackend` registry — direct-storage parallel
+ * to `RawContentStoreRegistry`.
+ *
+ * The storage service's read/delete/verify paths dispatch on the
+ * artifact row's `provider` column, NOT on the deployment's active
+ * backend, so a row written when the deployment was on `local_fs`
+ * keeps working after the operator switches to `s3`. Pointer rows
+ * short-circuit before the registry is even consulted (no backend
+ * required for `mode='pointer'`); only managed rows go through
+ * `get(provider)`.
+ *
+ * Failure semantics: a managed row whose provider is not registered
+ * is an operational unavailability (the deployment dropped a
+ * provider that still has live data). The service translates the
+ * `BackendNotRegisteredError` lookup miss into HTTP 503
+ * `storage_backend_unavailable` — see `src/routes/storage.ts`. The
+ * registry itself returns `undefined`; callers MUST fail loud.
+ */
+import type { StorageBackend } from './storage-backend.js';
+export interface StorageBackendRegistry {
+    /**
+     * The backend the deployment writes NEW managed artifacts to.
+     * Returns `null` when the deployment is pointer-only (no managed
+     * uploads); pointer artifacts still work because they
+     * short-circuit before backend lookup.
+     */
+    readonly active: StorageBackend | null;
+    /**
+     * Look up the backend matching `storage_artifacts.provider`.
+     * Returns `undefined` when no adapter is registered for that
+     * provider. Callers (the storage service's read/delete/verify
+     * paths) MUST translate `undefined` into a typed error rather
+     * than fall through to the active backend.
+     */
+    get(provider: string): StorageBackend | undefined;
+    /** True when `provider` has a registered backend in this registry. */
+    has(provider: string): boolean;
+    /**
+     * `(provider, backend)` pairs the registry knows about. Iteration
+     * order is the order providers were registered (active first,
+     * then legacy adapters).
+     */
+    readonly entries: ReadonlyArray<readonly [string, StorageBackend]>;
+}
+/**
+ * Build a backend registry from the active backend + optional
+ * legacy read-only adapters. `active` is `null` for pointer-only
+ * deployments. Throws when the same provider id is registered
+ * twice; that's a composition bug the caller must fix.
+ */
+export declare function buildBackendRegistry(active: StorageBackend | null, legacy?: ReadonlyArray<StorageBackend>): StorageBackendRegistry;
+/**
+ * Convenience for unit tests + single-provider deployments. Wraps
+ * one already-constructed backend (or `null` for pointer-only) in a
+ * registry with no legacy entries.
+ */
+export declare function singleBackendRegistry(backend: StorageBackend | null): StorageBackendRegistry;

package/dist/storage/storage-backend-registry.js

@@ -0,0 +1,56 @@
+/**
+ * @file Per-row `StorageBackend` registry — direct-storage parallel
+ * to `RawContentStoreRegistry`.
+ *
+ * The storage service's read/delete/verify paths dispatch on the
+ * artifact row's `provider` column, NOT on the deployment's active
+ * backend, so a row written when the deployment was on `local_fs`
+ * keeps working after the operator switches to `s3`. Pointer rows
+ * short-circuit before the registry is even consulted (no backend
+ * required for `mode='pointer'`); only managed rows go through
+ * `get(provider)`.
+ *
+ * Failure semantics: a managed row whose provider is not registered
+ * is an operational unavailability (the deployment dropped a
+ * provider that still has live data). The service translates the
+ * `BackendNotRegisteredError` lookup miss into HTTP 503
+ * `storage_backend_unavailable` — see `src/routes/storage.ts`. The
+ * registry itself returns `undefined`; callers MUST fail loud.
+ */
+/**
+ * Build a backend registry from the active backend + optional
+ * legacy read-only adapters. `active` is `null` for pointer-only
+ * deployments. Throws when the same provider id is registered
+ * twice; that's a composition bug the caller must fix.
+ */
+export function buildBackendRegistry(active, legacy = []) {
+    const map = new Map();
+    if (active)
+        map.set(active.provider, active);
+    for (const backend of legacy) {
+        if (map.has(backend.provider)) {
+            throw new Error(`StorageBackendRegistry: provider '${backend.provider}' is registered twice. ` +
+                `Active='${active?.provider ?? 'none'}', legacy contains a duplicate.`);
+        }
+        map.set(backend.provider, backend);
+    }
+    const entries = Array.from(map.entries());
+    return {
+        active,
+        entries,
+        get(provider) {
+            return map.get(provider);
+        },
+        has(provider) {
+            return map.has(provider);
+        },
+    };
+}
+/**
+ * Convenience for unit tests + single-provider deployments. Wraps
+ * one already-constructed backend (or `null` for pointer-only) in a
+ * registry with no legacy entries.
+ */
+export function singleBackendRegistry(backend) {
+    return buildBackendRegistry(backend, []);
+}

package/dist/storage/storage-backend.d.ts

@@ -0,0 +1,82 @@
+/**
+ * @file Backend abstraction the storage service writes through.
+ *
+ * Step 5 of the storage-sibling plan. Adapter, not rewrite: existing
+ * `RawContentStore` providers (`local_fs`, `s3`, `filecoin`) stay
+ * intact; `raw-content-store-backend-adapter.ts` exposes them as a
+ * `StorageBackend` for the storage service so the service never
+ * needs to know which adapter shape it is talking to.
+ *
+ * The backend handles managed-mode I/O only. Pointer-mode artifacts
+ * are metadata-only and live entirely in the database — the storage
+ * service NEVER calls a backend method against a pointer URI.
+ */
+/**
+ * Concrete result of a `put` against a managed backend. The service
+ * persists every field on the `storage_artifacts` row.
+ */
+export interface PutBackendResult {
+    /** Adapter-returned URI we persist on `storage_artifacts.uri`. */
+    uri: string;
+    /** Bytes actually persisted. Equals the input body length. */
+    sizeBytes: number;
+    /**
+     * Plaintext SHA-256 of the caller bytes. For the `identity` codec
+     * (v1 default for `local_fs` and `s3`) this equals `storedHash`.
+     * Always computed; exposed on the wire only when the caller opted
+     * into `disclose_content_hash` at put time.
+     */
+    plaintextHash: string;
+    /**
+     * SHA-256 of the bytes the adapter actually wrote. For the
+     * `aes_gcm` codec this is the ciphertext hash (Filecoin lifecycle)
+     * and is NEVER on the wire. v1 keeps Filecoin direct uploads
+     * behind a 501, so identity-codec equality is the typical case.
+     */
+    storedHash: string;
+    /** Free-form provider sidecar; the service redacts before exposing. */
+    providerMetadata: Record<string, unknown>;
+}
+export interface PutBackendInput {
+    /** Owner-namespaced storage key (e.g. `s/<hmac-hex32>/<artifact-id>.bin`). */
+    key: string;
+    body: Buffer;
+    contentType: string;
+}
+export interface GetBackendResult {
+    body: Buffer;
+    contentType: string | null;
+    sizeBytes: number;
+}
+export interface HeadBackendResult {
+    exists: boolean;
+    sizeBytes: number | null;
+    contentType: string | null;
+}
+export interface DeleteBackendResult {
+    /** `true` when bytes were removed; `false` for already-missing keys. */
+    deleted: boolean;
+    /**
+     * What the adapter's `delete` did at the provider boundary:
+     *   - `'deleted'`     — `local_fs` / `s3` removed the object.
+     *   - `'unpinned'`    — provider supports unpin-only (Filecoin).
+     *   - `'tombstoned'`  — decentralized network: we stopped managing
+     *                       the bytes but the network may still serve.
+     * Drives the cleanup-side terminal raw_storage_status selection
+     * (`blob_deleted` vs `blob_tombstoned`) and the artifact-delete
+     * cascade in `StorageService.deleteArtifact`.
+     */
+    semantics: 'deleted' | 'unpinned' | 'tombstoned';
+}
+/**
+ * Provider-agnostic managed-storage I/O surface the service depends
+ * on. Adapters live alongside this file (`raw-content-store-backend-adapter.ts`).
+ */
+export interface StorageBackend {
+    /** Provider id; matches `RawContentStore.provider`. */
+    readonly provider: string;
+    put(input: PutBackendInput): Promise<PutBackendResult>;
+    get(uri: string): Promise<GetBackendResult>;
+    head(uri: string): Promise<HeadBackendResult>;
+    delete(uri: string): Promise<DeleteBackendResult>;
+}