@atomicmemory/core 1.0.0

package/dist/storage/storage-backend.js

@@ -0,0 +1,14 @@
+/**
+ * @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.
+ */
+export {};

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

@@ -0,0 +1,56 @@
+/**
+ * @file Compute the direct storage API's capability snapshot.
+ *
+ * Maps an active `RawContentStore` (or its absence) to the public
+ * `StorageCapabilitiesResponse` the `/v1/storage/capabilities` route
+ * emits. Pure projection; no IO. Routes hand the result straight to
+ * the schema validator.
+ *
+ * Provider-specific honesty: the response
+ * describes what the **direct** storage API (`/v1/storage/artifacts/*`)
+ * supports. Filecoin direct managed upload is a 501 in v1, so every
+ * "supports*" claim for Filecoin reports `false` here. The fuller
+ * Filecoin feature set (`supportsContentHash`, `supportsContentAddressedUri`,
+ * provider proofs, etc.) is reachable only through document ingestion
+ * and is reported by `/v1/documents/limits` instead — that surface is
+ * untouched.
+ *
+ * Pointer-only deployments (no `RawContentStore`) report `provider:'none'`
+ * with every "supports*" flag false. Pointer-mode put against such a
+ * deployment still works in the storage-route implementation (pointer mode is independent of the
+ * managed backend), but the capabilities response correctly says there
+ * is no direct managed upload available.
+ */
+import type { RawContentStore } from './raw-content-store.js';
+import type { StorageCapabilitiesResponse } from '../schemas/storage-schemas.js';
+export interface StorageCapabilitiesSnapshot {
+    /**
+     * Active raw-content store, or `null` for `pointer_only` deployments.
+     * The route layer reads `runtime.rawContentStore` and forwards it
+     * here unchanged.
+     */
+    activeStore: RawContentStore | null;
+    /**
+     * `rawUploadMaxBytes` from runtime config. v1 keeps the existing
+     * 25 MiB cap from document ingestion (Streaming + Resumable Uploads
+     * PR will lift this).
+     */
+    rawUploadMaxBytes: number;
+}
+/**
+ * Build the capability response for the direct storage API.
+ *
+ * Treats the Filecoin direct-upload carve-out as authoritative:
+ * regardless of what the underlying `FilecoinRawContentStore`
+ * advertises, the direct API surface reports every capability as
+ * false for Filecoin in v1. Lifting that carve-out is the job of a
+ * follow-up PR (storage-artifact reconciler + Filecoin direct
+ * support).
+ *
+ * Unknown providers fail closed: the response carries the provider
+ * name (so operators can see what is configured) but advertises no
+ * direct upload, no content-hash disclosure, no delete, no addressing,
+ * etc. A new backend must be explicitly added to this switch before
+ * any direct-API claim is true for it.
+ */
+export declare function getStorageCapabilities(snapshot: StorageCapabilitiesSnapshot): StorageCapabilitiesResponse;

package/dist/storage/storage-capabilities.js

@@ -0,0 +1,170 @@
+/**
+ * @file Compute the direct storage API's capability snapshot.
+ *
+ * Maps an active `RawContentStore` (or its absence) to the public
+ * `StorageCapabilitiesResponse` the `/v1/storage/capabilities` route
+ * emits. Pure projection; no IO. Routes hand the result straight to
+ * the schema validator.
+ *
+ * Provider-specific honesty: the response
+ * describes what the **direct** storage API (`/v1/storage/artifacts/*`)
+ * supports. Filecoin direct managed upload is a 501 in v1, so every
+ * "supports*" claim for Filecoin reports `false` here. The fuller
+ * Filecoin feature set (`supportsContentHash`, `supportsContentAddressedUri`,
+ * provider proofs, etc.) is reachable only through document ingestion
+ * and is reported by `/v1/documents/limits` instead — that surface is
+ * untouched.
+ *
+ * Pointer-only deployments (no `RawContentStore`) report `provider:'none'`
+ * with every "supports*" flag false. Pointer-mode put against such a
+ * deployment still works in the storage-route implementation (pointer mode is independent of the
+ * managed backend), but the capabilities response correctly says there
+ * is no direct managed upload available.
+ */
+const POINTER_ONLY_PROVIDER = 'none';
+/**
+ * Closed allowlist of providers the direct storage API explicitly
+ * knows about. Any provider not in this set falls through to
+ * `unknownProviderCapabilities`, which reports every `supports*`
+ * flag as false so a future provider or test adapter does not
+ * accidentally inherit the location-addressed
+ * direct-upload shape.
+ */
+const KNOWN_LOCATION_ADDRESSED_PROVIDERS = new Set(['local_fs', 's3']);
+const KNOWN_EVENTUAL_DIRECT_UNSUPPORTED_PROVIDERS = new Set(['filecoin']);
+/**
+ * Build the capability response for the direct storage API.
+ *
+ * Treats the Filecoin direct-upload carve-out as authoritative:
+ * regardless of what the underlying `FilecoinRawContentStore`
+ * advertises, the direct API surface reports every capability as
+ * false for Filecoin in v1. Lifting that carve-out is the job of a
+ * follow-up PR (storage-artifact reconciler + Filecoin direct
+ * support).
+ *
+ * Unknown providers fail closed: the response carries the provider
+ * name (so operators can see what is configured) but advertises no
+ * direct upload, no content-hash disclosure, no delete, no addressing,
+ * etc. A new backend must be explicitly added to this switch before
+ * any direct-API claim is true for it.
+ */
+export function getStorageCapabilities(snapshot) {
+    const store = snapshot.activeStore;
+    if (store === null)
+        return pointerOnlyCapabilities();
+    if (KNOWN_LOCATION_ADDRESSED_PROVIDERS.has(store.provider)) {
+        return locationAddressedCapabilities(store.provider, snapshot.rawUploadMaxBytes);
+    }
+    if (KNOWN_EVENTUAL_DIRECT_UNSUPPORTED_PROVIDERS.has(store.provider)) {
+        return eventualDirectUnsupportedCapabilities(store.provider);
+    }
+    return unknownProviderCapabilities(store.provider);
+}
+function pointerOnlyCapabilities() {
+    return {
+        provider: POINTER_ONLY_PROVIDER,
+        addressing: [],
+        consistency: 'immediate',
+        supportsDirectUpload: false,
+        supportsRangeRead: false,
+        supportsDelete: false,
+        supportsTombstone: false,
+        supportsBundles: false,
+        supportedBundleFormats: [],
+        supportsVerification: false,
+        supportsProviderProofs: false,
+        supportsReplication: false,
+        supportsRetrievalStatus: false,
+        supportsContentHash: false,
+        supportsContentAddressedUri: false,
+        deleteSemantics: [],
+        availabilityModel: 'immediate',
+    };
+}
+/**
+ * Filecoin-shaped eventual providers in v1: direct managed upload is
+ * 501. The plan pins three fields to false (`supportsDirectUpload`,
+ * `supportsContentHash`, `supportsContentAddressedUri`); everything
+ * else also reports false because no direct-API operation can target
+ * these managed artifacts yet.
+ *
+ * `consistency` and `availabilityModel` remain Filecoin-shaped
+ * (`eventual` / `delayed`) so a future release that lifts the carve-out
+ * doesn't have to change those — they describe the backend, not the
+ * v1 carve-out.
+ */
+function eventualDirectUnsupportedCapabilities(provider) {
+    return {
+        provider,
+        addressing: [],
+        consistency: 'eventual',
+        supportsDirectUpload: false,
+        supportsRangeRead: false,
+        supportsDelete: false,
+        supportsTombstone: false,
+        supportsBundles: false,
+        supportedBundleFormats: [],
+        supportsVerification: false,
+        supportsProviderProofs: false,
+        supportsReplication: false,
+        supportsRetrievalStatus: false,
+        supportsContentHash: false,
+        supportsContentAddressedUri: false,
+        deleteSemantics: [],
+        availabilityModel: 'delayed',
+    };
+}
+function locationAddressedCapabilities(provider, maxUploadBytes) {
+    return {
+        provider,
+        addressing: ['location'],
+        consistency: 'immediate',
+        maxUploadBytes,
+        supportsDirectUpload: true,
+        supportsRangeRead: false,
+        supportsDelete: true,
+        supportsTombstone: false,
+        supportsBundles: false,
+        supportedBundleFormats: [],
+        // the storage-route implementation ships the verify route + a backend.head()-based shim;
+        // location-addressed providers report `true`. Pointer-mode
+        // artifacts of any provider still report `kind: 'unsupported'`
+        // at runtime (the server never touches the pointer URI).
+        supportsVerification: true,
+        supportsProviderProofs: false,
+        supportsReplication: false,
+        supportsRetrievalStatus: false,
+        supportsContentHash: true,
+        supportsContentAddressedUri: false,
+        deleteSemantics: ['delete'],
+        availabilityModel: 'immediate',
+    };
+}
+/**
+ * Fail-closed shape for any provider the direct storage API does not
+ * yet explicitly support. Carries the provider name so operators can
+ * see what is configured, but advertises no managed-upload capability.
+ * A new backend must be wired into `getStorageCapabilities` (and the
+ * Step-5 storage service) before any flag becomes true for it.
+ */
+function unknownProviderCapabilities(provider) {
+    return {
+        provider,
+        addressing: [],
+        consistency: 'immediate',
+        supportsDirectUpload: false,
+        supportsRangeRead: false,
+        supportsDelete: false,
+        supportsTombstone: false,
+        supportsBundles: false,
+        supportedBundleFormats: [],
+        supportsVerification: false,
+        supportsProviderProofs: false,
+        supportsReplication: false,
+        supportsRetrievalStatus: false,
+        supportsContentHash: false,
+        supportsContentAddressedUri: false,
+        deleteSemantics: [],
+        availabilityModel: 'immediate',
+    };
+}

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

@@ -0,0 +1,67 @@
+/**
+ * Per-row `RawContentStore` registry (Phase 4a). The composition root
+ * builds one registry from the active provider plus any legacy
+ * read-only adapters (`RAW_STORAGE_LEGACY_PROVIDERS`). Cleanup helpers
+ * dispatch on `blob.storageProvider` — a `local-fs://...` row on a
+ * Filecoin-active deployment is served by the registered legacy
+ * `local_fs` adapter, NOT by the active Filecoin store.
+ *
+ * Why this exists (rev-4 §6): pre-Filecoin, every row carried the
+ * same provider as the active adapter, so `cleanupManagedBlobs(store,
+ * blobs)` was sufficient. Once Filecoin lands alongside legacy s3 /
+ * local_fs rows, the active store may not be able to parse the
+ * historical URIs — silent-no-op (or `RawStorageUriError`) would be
+ * confusing. The registry fails loud when a row carries a provider
+ * the deployment hasn't registered.
+ *
+ * Capability lookup: `getDeleteSemantics` resolves
+ * `provider → 'delete' | 'unpin' | 'tombstone'` for the per-row
+ * `delete_semantics` wire field Phase 7a emits. Reads from the
+ * registered adapter's `capabilities.deleteSemantics`.
+ */
+import type { RawContentStore } from './raw-content-store.js';
+export interface RawContentStoreRegistry {
+    /**
+     * Adapter the deployment writes NEW rows to. Returns `null` when
+     * the deployment is pointer-only (no managed-blob writes).
+     */
+    readonly active: RawContentStore | null;
+    /**
+     * Look up an adapter by `raw_documents.storage_provider`. Returns
+     * `undefined` when the provider isn't registered — caller MUST
+     * fail loud rather than fall through to the active store.
+     */
+    get(provider: string): RawContentStore | undefined;
+    /**
+     * `(provider, store)` pairs the registry knows about. Used by the
+     * `/limits` route + observability surfaces; iteration order is the
+     * order providers were registered (active first, then legacy).
+     */
+    readonly entries: ReadonlyArray<readonly [string, RawContentStore]>;
+}
+/**
+ * Build a registry from the active store + any legacy read-only
+ * adapters. `active` may be `null` for pointer-only deployments;
+ * `legacy` defaults to an empty array.
+ *
+ * Defensive: registering the SAME provider twice (e.g. active=s3 +
+ * legacy=s3) throws — that's a config bug the operator must fix.
+ * `validateRawStorageConfig` already enforces this at startup, but the
+ * registry checks again so direct construction (tests, composition
+ * harnesses) can't drift.
+ */
+export declare function buildStoreRegistry(active: RawContentStore | null, legacy?: ReadonlyArray<RawContentStore>): RawContentStoreRegistry;
+/**
+ * Lookup helper: returns the registered adapter's
+ * `capabilities.deleteSemantics` for the given provider, or `null`
+ * when the provider isn't registered (pointer-only row, or a stale
+ * provider the deployment doesn't recognize). Phase 7a's formatters
+ * project this onto the wire `delete_semantics` field.
+ */
+export declare function getDeleteSemantics(registry: RawContentStoreRegistry, provider: string | null): 'delete' | 'unpin' | 'tombstone' | null;
+/**
+ * Convenience helper for unit tests + single-provider deployments
+ * (the common case today). Wraps one already-constructed store in a
+ * registry with no legacy entries.
+ */
+export declare function singleStoreRegistry(store: RawContentStore | null): RawContentStoreRegistry;

package/dist/storage/store-registry.js

@@ -0,0 +1,77 @@
+/**
+ * Per-row `RawContentStore` registry (Phase 4a). The composition root
+ * builds one registry from the active provider plus any legacy
+ * read-only adapters (`RAW_STORAGE_LEGACY_PROVIDERS`). Cleanup helpers
+ * dispatch on `blob.storageProvider` — a `local-fs://...` row on a
+ * Filecoin-active deployment is served by the registered legacy
+ * `local_fs` adapter, NOT by the active Filecoin store.
+ *
+ * Why this exists (rev-4 §6): pre-Filecoin, every row carried the
+ * same provider as the active adapter, so `cleanupManagedBlobs(store,
+ * blobs)` was sufficient. Once Filecoin lands alongside legacy s3 /
+ * local_fs rows, the active store may not be able to parse the
+ * historical URIs — silent-no-op (or `RawStorageUriError`) would be
+ * confusing. The registry fails loud when a row carries a provider
+ * the deployment hasn't registered.
+ *
+ * Capability lookup: `getDeleteSemantics` resolves
+ * `provider → 'delete' | 'unpin' | 'tombstone'` for the per-row
+ * `delete_semantics` wire field Phase 7a emits. Reads from the
+ * registered adapter's `capabilities.deleteSemantics`.
+ */
+/**
+ * Build a registry from the active store + any legacy read-only
+ * adapters. `active` may be `null` for pointer-only deployments;
+ * `legacy` defaults to an empty array.
+ *
+ * Defensive: registering the SAME provider twice (e.g. active=s3 +
+ * legacy=s3) throws — that's a config bug the operator must fix.
+ * `validateRawStorageConfig` already enforces this at startup, but the
+ * registry checks again so direct construction (tests, composition
+ * harnesses) can't drift.
+ */
+export function buildStoreRegistry(active, legacy = []) {
+    const map = new Map();
+    if (active) {
+        map.set(active.provider, active);
+    }
+    for (const store of legacy) {
+        if (map.has(store.provider)) {
+            throw new Error(`RawContentStoreRegistry: provider '${store.provider}' is registered twice. ` +
+                `Active=${active?.provider ?? 'none'}, legacy contains a duplicate. ` +
+                `Check RAW_STORAGE_PROVIDER and RAW_STORAGE_LEGACY_PROVIDERS.`);
+        }
+        map.set(store.provider, store);
+    }
+    const entries = Array.from(map.entries());
+    return {
+        active,
+        entries,
+        get(provider) {
+            return map.get(provider);
+        },
+    };
+}
+/**
+ * Lookup helper: returns the registered adapter's
+ * `capabilities.deleteSemantics` for the given provider, or `null`
+ * when the provider isn't registered (pointer-only row, or a stale
+ * provider the deployment doesn't recognize). Phase 7a's formatters
+ * project this onto the wire `delete_semantics` field.
+ */
+export function getDeleteSemantics(registry, provider) {
+    if (!provider)
+        return null;
+    const store = registry.get(provider);
+    if (!store)
+        return null;
+    return store.capabilities.deleteSemantics;
+}
+/**
+ * Convenience helper for unit tests + single-provider deployments
+ * (the common case today). Wraps one already-constructed store in a
+ * registry with no legacy entries.
+ */
+export function singleStoreRegistry(store) {
+    return buildStoreRegistry(store, []);
+}

package/dist/vector-math.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Shared vector math utilities used across embedding, search, and MMR modules.
+ * Provides a single canonical implementation of cosine similarity to avoid
+ * duplication across the codebase.
+ */
+/**
+ * Cosine similarity between two vectors.
+ * Returns 0 for missing, empty, mismatched-length, or zero-magnitude vectors.
+ *
+ * Defensive guard: callers downstream of multi-channel RRF can produce
+ * candidates whose `embedding` was projected away by an intermediate stage
+ * (e.g. a cross-encoder rerank that drops the vector to save bytes). Treating
+ * those as zero-similarity is preferable to a 500.
+ */
+export declare function cosineSimilarity(left: number[] | undefined | null, right: number[] | undefined | null): number;

package/dist/vector-math.js

@@ -0,0 +1,31 @@
+/**
+ * Shared vector math utilities used across embedding, search, and MMR modules.
+ * Provides a single canonical implementation of cosine similarity to avoid
+ * duplication across the codebase.
+ */
+/**
+ * Cosine similarity between two vectors.
+ * Returns 0 for missing, empty, mismatched-length, or zero-magnitude vectors.
+ *
+ * Defensive guard: callers downstream of multi-channel RRF can produce
+ * candidates whose `embedding` was projected away by an intermediate stage
+ * (e.g. a cross-encoder rerank that drops the vector to save bytes). Treating
+ * those as zero-similarity is preferable to a 500.
+ */
+export function cosineSimilarity(left, right) {
+    if (!left || !right)
+        return 0;
+    if (left.length === 0 || right.length === 0 || left.length !== right.length)
+        return 0;
+    let dot = 0;
+    let leftNorm = 0;
+    let rightNorm = 0;
+    for (let i = 0; i < left.length; i++) {
+        dot += left[i] * right[i];
+        leftNorm += left[i] * left[i];
+        rightNorm += right[i] * right[i];
+    }
+    if (leftNorm === 0 || rightNorm === 0)
+        return 0;
+    return dot / (Math.sqrt(leftNorm) * Math.sqrt(rightNorm));
+}

package/dist/xml-escape.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Shared XML escaping utility used by retrieval formatting modules.
+ */
+/** Escape special characters for safe embedding in XML/HTML content. */
+export declare function escapeXml(text: string): string;

package/dist/xml-escape.js

@@ -0,0 +1,7 @@
+/**
+ * Shared XML escaping utility used by retrieval formatting modules.
+ */
+/** Escape special characters for safe embedding in XML/HTML content. */
+export function escapeXml(text) {
+    return text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+}