@atomicmemory/core 1.0.0

package/dist/services/document-upload-beta2-recovery.js

@@ -0,0 +1,94 @@
+/**
+ * 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 { failClaimedUploadWithClient } from '../db/raw-document-blob-repository.js';
+import { describeError } from './upload-helpers.js';
+/**
+ * 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 async function compensateOrphanedBlob(store, storageUri, documentId, cause) {
+    try {
+        await store.delete(storageUri);
+        return { cleanupSucceeded: true };
+    }
+    catch (cleanupErr) {
+        const cleanupErrorMessage = describeError(cleanupErr);
+        // eslint-disable-next-line no-console
+        console.error(`runPhaseBeta2: failed to compensate orphan blob ` +
+            `(documentId=${documentId}, storageUri=${storageUri}) after ` +
+            `${describeError(cause)}; cleanup error: ${cleanupErrorMessage}`);
+        return { cleanupSucceeded: false, cleanupError: cleanupErrorMessage };
+    }
+}
+/**
+ * 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 async function markBeta2FailureOnDocument(args) {
+    const envelope = {
+        layer: 'raw_storage',
+        code: args.reasonCode,
+        message: args.reasonMessage,
+        occurred_at: new Date().toISOString(),
+    };
+    if (!args.compensation.cleanupSucceeded) {
+        envelope.internal_recovery_hint = {
+            storage_uri: args.stored.storageUri,
+            storage_provider: args.stored.storageProvider,
+            cleanup_error: args.compensation.cleanupError,
+        };
+    }
+    try {
+        await failClaimedUploadWithClient(args.pool, {
+            userId: args.document.userId,
+            documentId: args.document.id,
+            claimId: args.claimId,
+            lastError: envelope,
+        });
+    }
+    catch (markerErr) {
+        // eslint-disable-next-line no-console
+        console.error(`runPhaseBeta2: failed to mark raw_storage_failed for ` +
+            `document ${args.document.id} (claim ${args.claimId}); ` +
+            `marker error: ${describeError(markerErr)}; original reason: ${args.reasonMessage}`);
+    }
+}

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

@@ -0,0 +1,44 @@
+/**
+ * Managed-blob upload pipeline for the document registry (the managed-upload
+ * α/β/β2/γ split).
+ *
+ * Atomicity model: the slow `store.put()` no longer runs inside a DB
+ * transaction. Instead the pipeline is split into four phases:
+ *
+ *   - the claim step (short tx, advisory-locked): load the row, run
+ *     `classifyIdempotent` against the incoming hash, either short-
+ *     circuit (returnExisting) or claim the slot. The claim writes
+ *     `raw_storage_status='blob_uploading'` + `raw_storage_claim_id`
+ *     + plaintext `content_hash`/`size_bytes`. COMMIT, release lock.
+ *   - the provider-write step (no DB locks): `codec.encode()` + `store.put()`. On
+ *     throw, mark row `raw_storage_failed` via the per-claim guard.
+ *   - the durable URI-write step (short tx): record `storage_uri`/`storage_provider`/
+ *     `raw_storage_metadata` durably; status STAYS `blob_uploading`.
+ *     Guarded by claim_id; 0-row means another worker reclaimed —
+ *     compensate with `store.delete()`.
+ *   - the finalization step (short tx): compare-and-set status flip to the final
+ *     terminal state via `deriveFinalRawStorageStatus`. Clears claim;
+ *     stamps `pending_since` for the observability metric.
+ *
+ * Same-bytes crash recovery (rev-10 / rev-11):
+ *   - blob_uploading WITHOUT URI → reclaimAndUpload (re-run β/β2/γ).
+ *   - blob_uploading WITH URI    → finalize (skip β + β2; γ alone).
+ *
+ * Plaintext source of truth: `content_hash` and `size_bytes` written
+ * to the row are the PLAINTEXT hash + length; the encoded-byte hash +
+ * encoded size live only under `raw_storage_metadata.codec.*` for ops
+ * diagnostics (rev-2 §5).
+ */
+import pg from 'pg';
+import type { UploadConfig } from './upload-config.js';
+import type { RawContentStore } from '../storage/raw-content-store.js';
+import type { RawContentCodec } from '../storage/raw-content-codec.js';
+import { type UploadRawInput, type UploadRawResult } from './upload-helpers.js';
+export { ManagedStorageDisabledError, UploadDocumentConflictError, UploadDocumentNotFoundError, type UploadRawInput, type UploadRawResult, } from './upload-helpers.js';
+/**
+ * Run the full the managed-upload α/β/β2/γ upload path. Idempotent on
+ * byte-identical input. Crash-recoverable: a process death between
+ * any two phases is resumable by a same-bytes retry — the claim step's
+ * classifyIdempotent decision table picks the right branch.
+ */
+export declare function uploadRawDocument(pool: pg.Pool, store: RawContentStore | null, codec: RawContentCodec, cfg: UploadConfig, input: UploadRawInput): Promise<UploadRawResult>;

package/dist/services/document-upload.js

@@ -0,0 +1,353 @@
+/**
+ * Managed-blob upload pipeline for the document registry (the managed-upload
+ * α/β/β2/γ split).
+ *
+ * Atomicity model: the slow `store.put()` no longer runs inside a DB
+ * transaction. Instead the pipeline is split into four phases:
+ *
+ *   - the claim step (short tx, advisory-locked): load the row, run
+ *     `classifyIdempotent` against the incoming hash, either short-
+ *     circuit (returnExisting) or claim the slot. The claim writes
+ *     `raw_storage_status='blob_uploading'` + `raw_storage_claim_id`
+ *     + plaintext `content_hash`/`size_bytes`. COMMIT, release lock.
+ *   - the provider-write step (no DB locks): `codec.encode()` + `store.put()`. On
+ *     throw, mark row `raw_storage_failed` via the per-claim guard.
+ *   - the durable URI-write step (short tx): record `storage_uri`/`storage_provider`/
+ *     `raw_storage_metadata` durably; status STAYS `blob_uploading`.
+ *     Guarded by claim_id; 0-row means another worker reclaimed —
+ *     compensate with `store.delete()`.
+ *   - the finalization step (short tx): compare-and-set status flip to the final
+ *     terminal state via `deriveFinalRawStorageStatus`. Clears claim;
+ *     stamps `pending_since` for the observability metric.
+ *
+ * Same-bytes crash recovery (rev-10 / rev-11):
+ *   - blob_uploading WITHOUT URI → reclaimAndUpload (re-run β/β2/γ).
+ *   - blob_uploading WITH URI    → finalize (skip β + β2; γ alone).
+ *
+ * Plaintext source of truth: `content_hash` and `size_bytes` written
+ * to the row are the PLAINTEXT hash + length; the encoded-byte hash +
+ * encoded size live only under `raw_storage_metadata.codec.*` for ops
+ * diagnostics (rev-2 §5).
+ */
+import { randomUUID } from 'node:crypto';
+import { claimUploadSlotWithClient } from '../db/raw-document-blob-repository.js';
+import { ArtifactNotLinkableError } from '../db/storage-artifact-repository.js';
+import { deriveStorageKeyPrefix } from './storage-key-prefix.js';
+import { failClaimedUploadAndSyncArtifact, finalizeUploadAndSyncArtifact, recordUploadResultAndSwapArtifact, } from './document-upload-artifact-sync.js';
+import { compensateOrphanedBlob, markBeta2FailureOnDocument, } from './document-upload-beta2-recovery.js';
+import { buildLastError } from '../db/raw-document-status-repository.js';
+import { classifyIdempotent, deriveFinalRawStorageStatus, readPersistedStoredStatus, } from './upload-decision.js';
+import { blobKey, buildPhaseBeta2Metadata, buildUploadResult, describeError, idempotentResult, loadActive, ManagedStorageDisabledError, markRawStorageFailureBestEffort, sha256Hex, UploadClaimLostError, UploadDocumentConflictError, UploadDocumentNotFoundError, } from './upload-helpers.js';
+import { emitFilecoinEvent, sanitizeErrorMessage, } from './filecoin-observability.js';
+export { ManagedStorageDisabledError, UploadDocumentConflictError, UploadDocumentNotFoundError, } from './upload-helpers.js';
+/**
+ * Run the full the managed-upload α/β/β2/γ upload path. Idempotent on
+ * byte-identical input. Crash-recoverable: a process death between
+ * any two phases is resumable by a same-bytes retry — the claim step's
+ * classifyIdempotent decision table picks the right branch.
+ */
+export async function uploadRawDocument(pool, store, codec, cfg, input) {
+    if (cfg.rawStorageMode !== 'managed_blob' || !store) {
+        await markRawStorageFailureBestEffort(pool, input.userId, input.documentId, 'managed_storage_disabled', 'managed_blob storage is not enabled for this deployment');
+        throw new ManagedStorageDisabledError();
+    }
+    const contentHash = sha256Hex(input.body);
+    const sizeBytes = input.body.length;
+    // upload-observability — drives `upload_latency_seconds` aggregation. The
+    // event taxonomy is `filecoin.upload.*` so we only emit when the
+    // active adapter is Filecoin storage. local_fs / s3 uploads
+    // produce no `[FILECOIN]` events.
+    const isFilecoin = store.provider === 'filecoin';
+    const startedAt = Date.now();
+    if (isFilecoin) {
+        emitFilecoinEvent('filecoin.upload.started', {
+            documentId: input.documentId,
+            userId: input.userId,
+        });
+    }
+    return runUploadPhases(pool, store, codec, cfg, contentHash, sizeBytes, input, {
+        startedAt, isFilecoin,
+    });
+}
+async function runUploadPhases(pool, store, codec, cfg, contentHash, sizeBytes, input, obs) {
+    try {
+        const alpha = await runPhaseAlpha(pool, contentHash, sizeBytes, input);
+        const result = alpha.kind === 'returnExisting'
+            ? alpha.result
+            : alpha.kind === 'finalize'
+                ? await runPhaseGammaOnly(pool, alpha, input)
+                : await runPhaseBetaThroughGamma(pool, store, codec, cfg, alpha, input);
+        if (obs.isFilecoin) {
+            emitFilecoinEvent('filecoin.upload.accepted', {
+                documentId: input.documentId,
+                userId: input.userId,
+                provider: result.storageProvider ?? undefined,
+                statusAfter: result.rawStorageStatus,
+                durationMs: Date.now() - obs.startedAt,
+            });
+        }
+        return result;
+    }
+    catch (err) {
+        if (obs.isFilecoin) {
+            emitFilecoinEvent('filecoin.upload.failed', {
+                documentId: input.documentId,
+                userId: input.userId,
+                errorCode: extractUploadErrorCode(err),
+                errorMessage: sanitizeErrorMessage(err),
+                durationMs: Date.now() - obs.startedAt,
+            });
+        }
+        throw err;
+    }
+}
+function extractUploadErrorCode(err) {
+    if (err instanceof Error) {
+        const candidate = err.code;
+        if (typeof candidate === 'string')
+            return candidate;
+        if (err.name === 'UploadDocumentConflictError')
+            return 'document_conflict';
+        if (err.name === 'UploadDocumentNotFoundError')
+            return 'document_not_found';
+        if (err.name === 'UploadClaimLostError')
+            return 'upload_claim_lost';
+        if (err.name === 'ManagedStorageDisabledError')
+            return 'managed_storage_disabled';
+    }
+    return 'unknown';
+}
+async function runPhaseAlpha(pool, contentHash, sizeBytes, input) {
+    const client = await pool.connect();
+    try {
+        await client.query('BEGIN');
+        await client.query('SELECT pg_advisory_xact_lock(hashtext($1))', [input.documentId]);
+        const document = await loadActive(client, input);
+        const decision = classifyIdempotent(document, contentHash);
+        const earlyReturn = checkPhaseAlphaEarlyExit(document, contentHash, sizeBytes, decision);
+        if (earlyReturn) {
+            await client.query('COMMIT');
+            if (earlyReturn.kind === 'throw')
+                throw earlyReturn.err;
+            return earlyReturn.result;
+        }
+        return await commitPhaseAlphaClaim(client, document, contentHash, sizeBytes, decision, input);
+    }
+    catch (err) {
+        await client.query('ROLLBACK').catch(() => undefined);
+        throw err;
+    }
+    finally {
+        client.release();
+    }
+}
+function checkPhaseAlphaEarlyExit(document, contentHash, sizeBytes, decision) {
+    if (decision?.kind === 'returnExisting') {
+        return {
+            kind: 'return',
+            result: { kind: 'returnExisting', result: idempotentResult(document, contentHash, sizeBytes) },
+        };
+    }
+    if (decision === null && hasConflictingManagedBlob(document, contentHash)) {
+        return {
+            kind: 'throw',
+            err: new UploadDocumentConflictError(document.id, document.contentHash ?? '', contentHash),
+        };
+    }
+    return null;
+}
+async function commitPhaseAlphaClaim(client, document, contentHash, sizeBytes, decision, input) {
+    // `checkPhaseAlphaEarlyExit` already handled returnExisting +
+    // conflict; what reaches us is reclaimAndUpload / finalize / null.
+    const branch = decision?.kind === 'finalize' ? 'finalize' : 'reclaimAndUpload';
+    // Finalize preserves the durable URI (the bytes are already on the
+    // provider); reclaim/fresh clear it so a crash before the durable URI-write step can't
+    // strand the row in a finalize-recovery window pointing at stale
+    // bytes (rev-fix HIGH 2).
+    const claimId = randomUUID();
+    const claimed = await claimUploadSlotWithClient(client, {
+        userId: input.userId, documentId: input.documentId, claimId, contentHash, sizeBytes,
+        clearDurableUri: branch === 'reclaimAndUpload',
+    });
+    if (claimed === 0) {
+        await client.query('COMMIT');
+        throw new UploadDocumentNotFoundError(input.documentId);
+    }
+    await client.query('COMMIT');
+    return { kind: branch, claimId, document, contentHash, sizeBytes };
+}
+async function runPhaseBetaThroughGamma(pool, store, codec, cfg, alpha, input) {
+    const stored = await runPhaseBeta(pool, store, codec, cfg, alpha, input);
+    await runPhaseBeta2(pool, store, alpha, stored);
+    return runPhaseGammaFromStored(pool, alpha, stored, input);
+}
+async function runPhaseBeta(pool, store, codec, cfg, alpha, input) {
+    try {
+        const encoded = await codec.encode({ body: input.body });
+        const userPrefix = deriveStorageKeyPrefix(cfg.storageKeyHmacSecret, input.userId);
+        const stored = await store.put({
+            key: blobKey(cfg.rawStoragePrefix, userPrefix, input.documentId, alpha.contentHash),
+            body: encoded.body,
+            contentType: input.contentType,
+        });
+        return { ...stored, codecMetadata: encoded.metadata };
+    }
+    catch (err) {
+        const lastError = buildLastError('raw_storage', 'transport_error', describeError(err));
+        // the paired artifact-sync implementation paired the provider-write step failure: flip raw_storage_status AND
+        // sync the linked artifact to 'failed' in one transaction so
+        // the two rows never diverge across a failed store.put().
+        //
+        // Marker failures used to swallow the inner error silently; we
+        // now log with context so a follow-up worker can see that the
+        // claim cleanup itself failed (the outer throw still wins so
+        // the upload pipeline surfaces the original store.put error).
+        try {
+            await failClaimedUploadAndSyncArtifact(pool, {
+                userId: input.userId,
+                documentId: input.documentId,
+                claimId: alpha.claimId,
+                lastError,
+            });
+        }
+        catch (markerErr) {
+            // eslint-disable-next-line no-console
+            console.error(`runPhaseBeta: failed to mark raw_storage_failed + sync artifact for ` +
+                `document ${input.documentId} after store.put error: ${describeError(markerErr)}`);
+        }
+        throw err;
+    }
+}
+async function runPhaseBeta2(pool, store, alpha, stored) {
+    const metadata = buildPhaseBeta2Metadata(stored);
+    // the paired artifact-sync implementation paired the durable URI-write step: URI write + artifact swap commit
+    // together. Two failure modes after `store.put` has durably
+    // written bytes:
+    //
+    //   1. `rowCount === 0` — the upload claim was lost (another
+    //      worker reclaimed the row). The artifact swap helper
+    //      rolled back; we compensate by deleting the bytes we
+    //      wrote and throw `UploadClaimLostError`. The raw_document
+    //      is now owned by the new worker so we DO NOT write to its
+    //      `last_error`.
+    //   2. The swap helper THROWS (e.g. `ArtifactNotLinkableError`
+    //      when the prior artifact entered a delete lifecycle
+    //      between our claim and the swap). Without explicit
+    //      compensation the bytes would orphan. We catch every
+    //      throw, attempt provider cleanup, AND flip the doc's
+    //      `raw_storage_status` to `raw_storage_failed` with a
+    //      typed `artifact_not_linkable` envelope so the public
+    //      status surfaces stop saying "upload in progress" for a
+    //      doc whose upload actually failed.
+    //
+    // The cleanup `store.delete` call is best-effort. When it fails
+    // the orphan URI + provider are embedded in the raw_document's
+    // `last_error.internal_recovery_hint` (wire-stripped by the
+    // response formatter) so a reconciler / ops can find the
+    // abandoned bytes later.
+    let result;
+    try {
+        result = await recordUploadResultAndSwapArtifact(pool, {
+            userId: alpha.document.userId,
+            documentId: alpha.document.id,
+            claimId: alpha.claimId,
+            storageUri: stored.storageUri,
+            storageProvider: stored.storageProvider,
+            rawStorageMetadata: metadata,
+            document: alpha.document,
+            contentHash: alpha.contentHash,
+            stored,
+        });
+    }
+    catch (err) {
+        const compensation = await compensateOrphanedBlob(store, stored.storageUri, alpha.document.id, err);
+        await markBeta2FailureOnDocument({
+            pool, document: alpha.document, claimId: alpha.claimId, stored,
+            reasonCode: err instanceof ArtifactNotLinkableError ? 'artifact_not_linkable' : 'beta2_swap_failed',
+            reasonMessage: describeError(err),
+            compensation,
+        });
+        throw err;
+    }
+    if (result.rowCount === 0) {
+        // Lost-claim path: another worker now owns the row's lifecycle.
+        // Compensate the orphan bytes if we can, but DO NOT write to
+        // the row's `last_error` — that belongs to the new claim. The
+        // structured log event below carries the orphan info when
+        // cleanup fails (best we can do without clobbering the new
+        // claim's state).
+        await compensateOrphanedBlob(store, stored.storageUri, alpha.document.id, new UploadClaimLostError(alpha.document.id, alpha.claimId, 'beta2'));
+        throw new UploadClaimLostError(alpha.document.id, alpha.claimId, 'beta2');
+    }
+}
+async function runPhaseGammaFromStored(pool, alpha, stored, input) {
+    const finalStatus = deriveFinalRawStorageStatus({
+        storedStatus: stored.status,
+        storageProvider: stored.storageProvider,
+    });
+    const rowCount = await finalizeUploadAndSyncArtifact(pool, {
+        userId: input.userId, documentId: input.documentId,
+        claimId: alpha.claimId, finalStatus,
+    });
+    if (rowCount === 0) {
+        throw new UploadClaimLostError(input.documentId, alpha.claimId, 'gamma');
+    }
+    return buildUploadResult({
+        documentId: alpha.document.id,
+        storageProvider: stored.storageProvider,
+        storageUri: stored.storageUri,
+        contentHash: alpha.contentHash,
+        sizeBytes: alpha.sizeBytes,
+        finalStatus,
+        rawStorageMetadata: buildPhaseBeta2Metadata(stored),
+        idempotentSkip: false,
+    });
+}
+async function runPhaseGammaOnly(pool, alpha, input) {
+    const storedStatus = readPersistedStoredStatus(alpha.document.rawStorageMetadata);
+    if (storedStatus === null) {
+        throw new Error(`the finalization step finalize-recovery: row ${input.documentId} has blob_uploading + storage_uri but ` +
+            'no raw_storage_metadata.upload_result.stored_status sidecar (the durable URI-write step incomplete?)');
+    }
+    const storageProvider = alpha.document.storageProvider;
+    if (!storageProvider) {
+        throw new Error(`the finalization step finalize-recovery: row ${input.documentId} has no storage_provider despite a durable URI`);
+    }
+    const finalStatus = deriveFinalRawStorageStatus({ storedStatus, storageProvider });
+    const rowCount = await finalizeUploadAndSyncArtifact(pool, {
+        userId: input.userId, documentId: input.documentId,
+        claimId: alpha.claimId, finalStatus,
+    });
+    if (rowCount === 0) {
+        throw new UploadClaimLostError(input.documentId, alpha.claimId, 'gamma');
+    }
+    return buildUploadResult({
+        documentId: alpha.document.id,
+        storageProvider,
+        storageUri: alpha.document.storageUri,
+        contentHash: alpha.contentHash,
+        sizeBytes: alpha.sizeBytes,
+        finalStatus,
+        rawStorageMetadata: alpha.document.rawStorageMetadata,
+        idempotentSkip: false,
+    });
+}
+function isManagedBlobOccupied(status) {
+    return status === 'blob_stored'
+        || status === 'blob_pending'
+        || status === 'blob_available'
+        || status === 'blob_uploading';
+}
+/**
+ * Conflict guard: fires on any occupied managed_blob state where the
+ * incoming hash disagrees with the persisted plaintext hash. Crucially
+ * does NOT require `storage_uri !== null` — a `blob_uploading` row
+ * whose the claim step recorded the plaintext hash but whose the durable URI-write step hasn't
+ * yet written the URI still owns the slot, and a different-hash
+ * caller arriving in that window must 409 (rev-fix HIGH 1).
+ */
+function hasConflictingManagedBlob(document, contentHash) {
+    return (isManagedBlobOccupied(document.rawStorageStatus)
+        && document.contentHash !== null
+        && document.contentHash !== contentHash);
+}

package/dist/services/embedding.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Embedding provider abstraction.
+ * Supports OpenAI, Ollama, OpenAI-compatible APIs, Voyage AI, and local
+ * WASM (via @huggingface/transformers with ONNX Runtime). Provider/model
+ * selection comes from the RuntimeConfig bound by createCoreRuntime().
+ */
+import { type WriteCostEventConfig } from './cost-telemetry.js';
+import type { EmbeddingProviderName } from '../config.js';
+/**
+ * Config subset consumed by the embedding module. After Phase 7 Step 3c,
+ * provider/model selection is startup-only, so it's safe for embedding to
+ * hold this as module-level state and rebind only on explicit reinit.
+ *
+ * Includes WriteCostEventConfig so cost-telemetry calls can be threaded
+ * through without a second init.
+ */
+export interface EmbeddingConfig extends WriteCostEventConfig {
+    embeddingProvider: EmbeddingProviderName;
+    embeddingModel: string;
+    embeddingDimensions: number;
+    embeddingApiUrl?: string;
+    embeddingApiKey?: string;
+    voyageApiKey?: string;
+    voyageDocumentModel: string;
+    voyageQueryModel: string;
+    openaiApiKey: string;
+    ollamaBaseUrl: string;
+    embeddingCacheEnabled: boolean;
+    extractionCacheDir: string;
+}
+/**
+ * Bind the embedding module's config. Called once by the composition
+ * root (`createCoreRuntime`). Calling again rebinds and invalidates the
+ * stateful provider cache — primarily for tests that need to swap
+ * providers within a process.
+ */
+export declare function initEmbedding(config: EmbeddingConfig): void;
+export type EmbeddingTask = 'query' | 'document';
+export interface EmbeddingProvider {
+    embed(text: string, task: EmbeddingTask): Promise<number[]>;
+    embedBatch(texts: string[], task: EmbeddingTask): Promise<number[][]>;
+}
+/** Embed a single text — primary API used throughout the codebase. */
+export declare function embedText(text: string, task?: EmbeddingTask): Promise<number[]>;
+/** Embed multiple texts in one call, with per-text cache integration. */
+export declare function embedTexts(texts: string[], task?: EmbeddingTask): Promise<number[][]>;
+/** Get current cache size (for testing/monitoring). */
+export declare function getEmbeddingCacheSize(): number;
+/** Clear the embedding cache (for testing). */
+export declare function clearEmbeddingCache(): void;
+/**
+ * Detect the actual embedding width returned by the active provider.
+ * Some OpenAI-compatible backends ignore the requested dimensions parameter,
+ * so the database schema must align to the real vector width, not just config.
+ */
+export declare function resolveEmbeddingDimensions(): Promise<number>;
+export { cosineSimilarity } from '../vector-math.js';