@wei840222/qmd 2026.8.23

package/dist/embedding/openai.d.ts

@@ -0,0 +1,79 @@
+import { type OpenAIEmbeddingModel } from "./config.js";
+import { type EmbeddingOperationOptions, type EmbeddingProvider, type RemoteEmbeddingRequestGuard, type EmbeddingVector } from "./provider.js";
+export interface OpenAIEmbeddingUsage {
+    readonly promptTokens: number;
+    readonly totalTokens: number;
+}
+export interface OpenAIEmbeddingProviderOptions {
+    apiKey?: string;
+    model?: OpenAIEmbeddingModel;
+    dimension?: number;
+    /** Override the base URL. Falls back to OPENAI_BASE_URL env or the official OpenAI endpoint. */
+    baseUrl?: string;
+    maxAttempts?: number;
+    fetch?: typeof globalThis.fetch;
+    sleep?: (delayMs: number, signal: AbortSignal) => Promise<void>;
+    random?: () => number;
+    now?: () => number;
+    baseRetryDelayMs?: number;
+    maxRetryDelayMs?: number;
+    /** Internal per-attempt timeout test seam. This is deliberately not part of public qmd config. */
+    requestTimeoutMs?: number;
+    /** Mandatory fail-closed policy boundary, invoked immediately before every fetch attempt. */
+    authorizeRequest?: RemoteEmbeddingRequestGuard;
+}
+export declare function canonicalOpenAIEmbeddingIdentityMaterial(model?: OpenAIEmbeddingModel, dimension?: number, baseUrl?: string | undefined): string;
+export declare class UnavailableOpenAIEmbeddingProvider implements EmbeddingProvider {
+    readonly providerId = "openai";
+    readonly model: OpenAIEmbeddingModel;
+    readonly dimension: number;
+    readonly remote = true;
+    private readonly configuredBaseUrl;
+    constructor(options?: {
+        model?: OpenAIEmbeddingModel;
+        dimension?: number;
+        baseUrl?: string;
+    });
+    canonicalIdentityMaterial(): string;
+    formatQuery(query: string): string;
+    formatDocument(text: string, title?: string): string;
+    estimateTokens(text: string): number;
+    embed(_text: string, _options: EmbeddingOperationOptions): Promise<EmbeddingVector>;
+    embedBatch(_texts: string[], _options: EmbeddingOperationOptions): Promise<EmbeddingVector[]>;
+    close(): Promise<void>;
+}
+export declare class OpenAIEmbeddingProvider implements EmbeddingProvider {
+    readonly providerId = "openai";
+    readonly model: OpenAIEmbeddingModel;
+    readonly dimension: number;
+    readonly remote = true;
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    private readonly maxAttempts;
+    private readonly sleep;
+    private readonly random;
+    private readonly now;
+    private readonly baseRetryDelayMs;
+    private readonly maxRetryDelayMs;
+    private readonly requestTimeoutMs;
+    private readonly authorizeRequest?;
+    private readonly fingerprint;
+    private readonly closeController;
+    private requestTail;
+    private closePromise;
+    private closed;
+    constructor(options: OpenAIEmbeddingProviderOptions);
+    canonicalIdentityMaterial(): string;
+    canonicalIdentityMaterialForDimension(dimension: number): string;
+    formatQuery(query: string): string;
+    formatDocument(text: string, title?: string): string;
+    /** Conservative token upper bound: every token contains at least one UTF-8 byte. */
+    estimateTokens(text: string): number;
+    private lifecycleError;
+    private throwIfInterrupted;
+    private acquireRequestSlot;
+    embed(text: string, options: EmbeddingOperationOptions): Promise<EmbeddingVector>;
+    embedBatch(texts: string[], options: EmbeddingOperationOptions): Promise<EmbeddingVector[]>;
+    close(): Promise<void>;
+}

package/dist/embedding/openai.js

@@ -0,0 +1,477 @@
+import { createHash } from "node:crypto";
+import { OPENAI_EMBEDDING_DIMENSION, OPENAI_EMBEDDING_MODEL, OPENAI_EMBEDDING_MODELS, DEFAULT_OPENAI_BASE_URL, } from "./config.js";
+import { EmbeddingProviderError, } from "./provider.js";
+import { canonicalRemoteChunkProfile } from "./remote-chunking.js";
+const MAX_INPUTS_PER_REQUEST = 128;
+const MAX_INPUT_TOKEN_UPPER_BOUND = 8_192;
+const MAX_BATCH_TOKEN_UPPER_BOUND = 300_000;
+const DEFAULT_REQUEST_TIMEOUT_MS = 30_000;
+const utf8Encoder = new TextEncoder();
+function normalizeOpenAIBaseUrl(baseUrl) {
+    return (baseUrl?.trim() || DEFAULT_OPENAI_BASE_URL).replace(/\/+$/, "");
+}
+function endpointFingerprint(baseUrl) {
+    if (baseUrl === DEFAULT_OPENAI_BASE_URL)
+        return undefined;
+    return createHash("sha256").update(baseUrl).digest("hex");
+}
+export function canonicalOpenAIEmbeddingIdentityMaterial(model = OPENAI_EMBEDDING_MODEL, dimension, baseUrl = undefined) {
+    const expectedDimension = OPENAI_EMBEDDING_MODELS.get(model);
+    const effectiveDimension = dimension ?? expectedDimension ?? OPENAI_EMBEDDING_DIMENSION;
+    if (expectedDimension !== undefined && effectiveDimension !== expectedDimension) {
+        throw new EmbeddingProviderError("DIMENSION_MISMATCH", `OpenAI embedding dimension must be ${expectedDimension} for model ${model}.`);
+    }
+    const endpoint = endpointFingerprint(normalizeOpenAIBaseUrl(baseUrl));
+    return JSON.stringify({
+        provider: "openai",
+        model,
+        dimension: effectiveDimension,
+        remote: true,
+        format: "qmd-openai-embedding-v1",
+        chunking: canonicalRemoteChunkProfile(),
+        ...(endpoint === undefined ? {} : { endpointFingerprint: endpoint }),
+    });
+}
+export class UnavailableOpenAIEmbeddingProvider {
+    providerId = "openai";
+    model;
+    dimension;
+    remote = true;
+    configuredBaseUrl;
+    constructor(options) {
+        this.model = options?.model ?? OPENAI_EMBEDDING_MODEL;
+        this.dimension = options?.dimension ?? (OPENAI_EMBEDDING_MODELS.get(this.model) ?? OPENAI_EMBEDDING_DIMENSION);
+        this.configuredBaseUrl = options?.baseUrl;
+    }
+    canonicalIdentityMaterial() {
+        return canonicalOpenAIEmbeddingIdentityMaterial(this.model, this.dimension, this.configuredBaseUrl ?? process.env.OPENAI_BASE_URL);
+    }
+    formatQuery(query) {
+        return query;
+    }
+    formatDocument(text, title) {
+        return title ? `${title}\n${text}` : text;
+    }
+    estimateTokens(text) {
+        return utf8Encoder.encode(text).byteLength;
+    }
+    async embed(_text, _options) {
+        throw new EmbeddingProviderError("PROVIDER_FAILURE", "OpenAI embedding provider is not available (missing API key or configuration).");
+    }
+    async embedBatch(_texts, _options) {
+        throw new EmbeddingProviderError("PROVIDER_FAILURE", "OpenAI embedding provider is not available (missing API key or configuration).");
+    }
+    async close() { }
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function defaultSleep(delayMs, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal.aborted) {
+            reject(new DOMException("aborted", "AbortError"));
+            return;
+        }
+        const timer = setTimeout(resolve, delayMs);
+        signal.addEventListener("abort", () => {
+            clearTimeout(timer);
+            reject(new DOMException("aborted", "AbortError"));
+        }, { once: true });
+    });
+}
+function awaitWithSignal(value, signal) {
+    if (signal.aborted) {
+        return Promise.reject(new DOMException("aborted", "AbortError"));
+    }
+    return new Promise((resolve, reject) => {
+        const onAbort = () => reject(new DOMException("aborted", "AbortError"));
+        signal.addEventListener("abort", onAbort, { once: true });
+        Promise.resolve(value).then(resolve, reject).finally(() => {
+            signal.removeEventListener("abort", onAbort);
+        });
+    });
+}
+function waitForTurn(previous, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal.aborted) {
+            reject(new DOMException("aborted", "AbortError"));
+            return;
+        }
+        const onAbort = () => {
+            signal.removeEventListener("abort", onAbort);
+            reject(new DOMException("aborted", "AbortError"));
+        };
+        signal.addEventListener("abort", onAbort, { once: true });
+        previous.then(() => {
+            signal.removeEventListener("abort", onAbort);
+            resolve();
+        });
+    });
+}
+function parseRetryAfter(value, now) {
+    if (value === null)
+        return null;
+    const seconds = Number(value);
+    if (Number.isFinite(seconds) && seconds >= 0)
+        return seconds * 1_000;
+    const date = Date.parse(value);
+    return Number.isFinite(date) ? Math.max(0, date - now) : null;
+}
+function parseResponse(value, inputCount, tokenUpperBound, expectedModel = OPENAI_EMBEDDING_MODEL, expectedDimension = OPENAI_EMBEDDING_DIMENSION) {
+    if (!isRecord(value) || value.object !== "list" || value.model !== expectedModel) {
+        throw new EmbeddingProviderError("PROVIDER_FAILURE", "OpenAI embedding response schema is invalid.");
+    }
+    if (!isRecord(value.usage)) {
+        throw new EmbeddingProviderError("PROVIDER_FAILURE", "OpenAI embedding usage is invalid.");
+    }
+    const promptTokens = value.usage.prompt_tokens;
+    const totalTokens = value.usage.total_tokens;
+    if (!Number.isSafeInteger(promptTokens) || promptTokens < 0
+        || !Number.isSafeInteger(totalTokens) || totalTokens < 0
+        || totalTokens < promptTokens
+        || promptTokens > tokenUpperBound
+        || totalTokens > tokenUpperBound) {
+        throw new EmbeddingProviderError("PROVIDER_FAILURE", "OpenAI embedding usage is invalid.");
+    }
+    if (!Array.isArray(value.data) || value.data.length !== inputCount) {
+        throw new EmbeddingProviderError("BATCH_CARDINALITY_MISMATCH", "OpenAI embedding response cardinality is invalid.");
+    }
+    const byIndex = new Array(inputCount);
+    for (const item of value.data) {
+        if (!isRecord(item) || item.object !== "embedding") {
+            throw new EmbeddingProviderError("PROVIDER_FAILURE", "OpenAI embedding item schema is invalid.");
+        }
+        const index = item.index;
+        const embedding = item.embedding;
+        if (!Number.isInteger(index) || index < 0 || index >= inputCount) {
+            throw new EmbeddingProviderError("PROVIDER_FAILURE", "OpenAI embedding response index is invalid.");
+        }
+        if (byIndex[index]) {
+            throw new EmbeddingProviderError("RESPONSE_SCHEMA_INVALID", "OpenAI embedding response index is duplicated.");
+        }
+        if (!Array.isArray(embedding)
+            || embedding.length !== expectedDimension
+            || embedding.some(value => typeof value !== "number"
+                || !Number.isFinite(value)
+                || !Number.isFinite(Math.fround(value)))) {
+            throw new EmbeddingProviderError("DIMENSION_MISMATCH", "OpenAI embedding vector is invalid.");
+        }
+        byIndex[index] = {
+            object: "embedding",
+            index: index,
+            embedding: embedding,
+        };
+    }
+    return {
+        object: "list",
+        model: expectedModel,
+        data: byIndex,
+        usage: {
+            prompt_tokens: promptTokens,
+            total_tokens: totalTokens,
+        },
+    };
+}
+export class OpenAIEmbeddingProvider {
+    providerId = "openai";
+    model;
+    dimension;
+    remote = true;
+    apiKey;
+    baseUrl;
+    fetchImpl;
+    maxAttempts;
+    sleep;
+    random;
+    now;
+    baseRetryDelayMs;
+    maxRetryDelayMs;
+    requestTimeoutMs;
+    authorizeRequest;
+    fingerprint;
+    closeController = new AbortController();
+    requestTail = Promise.resolve();
+    closePromise = null;
+    closed = false;
+    constructor(options) {
+        const apiKey = options.apiKey?.trim() || undefined;
+        const maxAttempts = options.maxAttempts ?? 3;
+        if (!Number.isInteger(maxAttempts) || maxAttempts < 1 || maxAttempts > 3) {
+            throw new EmbeddingProviderError("PROVIDER_FAILURE", "OpenAI maxAttempts must be between 1 and 3.");
+        }
+        const requestTimeoutMs = options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+        if (!Number.isFinite(requestTimeoutMs) || requestTimeoutMs <= 0) {
+            throw new EmbeddingProviderError("PROVIDER_FAILURE", "OpenAI requestTimeoutMs must be positive.");
+        }
+        this.model = options.model ?? OPENAI_EMBEDDING_MODEL;
+        this.dimension = options.dimension ?? (OPENAI_EMBEDDING_MODELS.get(this.model) ?? OPENAI_EMBEDDING_DIMENSION);
+        this.apiKey = apiKey;
+        this.baseUrl = normalizeOpenAIBaseUrl(options.baseUrl ?? process.env.OPENAI_BASE_URL);
+        this.fetchImpl = options.fetch ?? globalThis.fetch;
+        this.maxAttempts = maxAttempts;
+        this.sleep = options.sleep ?? defaultSleep;
+        this.random = options.random ?? Math.random;
+        this.now = options.now ?? Date.now;
+        this.baseRetryDelayMs = options.baseRetryDelayMs ?? 250;
+        this.maxRetryDelayMs = options.maxRetryDelayMs ?? 5_000;
+        this.requestTimeoutMs = requestTimeoutMs;
+        this.authorizeRequest = options.authorizeRequest;
+        this.fingerprint = createHash("sha256")
+            .update(this.canonicalIdentityMaterial())
+            .digest("hex");
+    }
+    canonicalIdentityMaterial() {
+        return this.canonicalIdentityMaterialForDimension(this.dimension);
+    }
+    canonicalIdentityMaterialForDimension(dimension) {
+        return canonicalOpenAIEmbeddingIdentityMaterial(this.model, dimension, this.baseUrl);
+    }
+    formatQuery(query) {
+        return query;
+    }
+    formatDocument(text, title) {
+        return title ? `${title}\n${text}` : text;
+    }
+    /** Conservative token upper bound: every token contains at least one UTF-8 byte. */
+    estimateTokens(text) {
+        return utf8Encoder.encode(text).byteLength;
+    }
+    lifecycleError(options, deadlineController) {
+        if (this.closed || this.closeController.signal.aborted) {
+            return new EmbeddingProviderError("PROVIDER_CLOSED", "Embedding provider is closed.");
+        }
+        if (options.signal?.aborted) {
+            return new EmbeddingProviderError("OPERATION_ABORTED", "Embedding operation was aborted.");
+        }
+        if (deadlineController.signal.aborted) {
+            return new EmbeddingProviderError("DEADLINE_EXCEEDED", "Embedding operation deadline was exceeded.");
+        }
+        return null;
+    }
+    throwIfInterrupted(options, deadlineController) {
+        const error = this.lifecycleError(options, deadlineController);
+        if (error)
+            throw error;
+    }
+    async acquireRequestSlot(signal) {
+        const previous = this.requestTail;
+        let release;
+        const gate = new Promise(resolve => { release = resolve; });
+        this.requestTail = previous.then(() => gate);
+        try {
+            await waitForTurn(previous, signal);
+        }
+        catch (error) {
+            release();
+            throw error;
+        }
+        return release;
+    }
+    async embed(text, options) {
+        const results = await this.embedBatch([text], options);
+        return results[0];
+    }
+    async embedBatch(texts, options) {
+        options = Object.freeze({
+            purpose: options.purpose,
+            kind: options.kind,
+            signal: options.signal,
+            deadline: options.deadline,
+            buildLease: options.buildLease ? Object.freeze({ ...options.buildLease }) : undefined,
+            identityFingerprint: options.identityFingerprint,
+        });
+        if (typeof options.identityFingerprint !== "string" || options.identityFingerprint.length === 0) {
+            throw new EmbeddingProviderError("IDENTITY_FINGERPRINT_REQUIRED", "Remote embedding requests require a complete active identity fingerprint.");
+        }
+        if (this.closed) {
+            throw new EmbeddingProviderError("PROVIDER_CLOSED", "Embedding provider is closed.");
+        }
+        if (options.signal?.aborted) {
+            throw new EmbeddingProviderError("OPERATION_ABORTED", "Embedding operation was aborted.");
+        }
+        if (!Array.isArray(texts) || texts.some(text => typeof text !== "string")) {
+            throw new EmbeddingProviderError("INPUT_BUDGET_EXCEEDED", "OpenAI embedding inputs must be strings.");
+        }
+        const inputs = Object.freeze([...texts]);
+        const validPurposeKindPair = (options.purpose === "index-build" && options.kind === "document")
+            || (options.purpose === "query-embedding" && options.kind === "query");
+        if (!validPurposeKindPair) {
+            throw new EmbeddingProviderError("REMOTE_AUTHORIZATION_REQUIRED", "Remote embedding request purpose does not match its input kind.");
+        }
+        if (inputs.length === 0 || inputs.length > MAX_INPUTS_PER_REQUEST) {
+            throw new EmbeddingProviderError("INPUT_BUDGET_EXCEEDED", `OpenAI embedding batches must contain between 1 and ${MAX_INPUTS_PER_REQUEST} inputs.`);
+        }
+        let batchUpperBound = 0;
+        for (const text of inputs) {
+            const upperBound = this.estimateTokens(text);
+            if (upperBound === 0 || upperBound > MAX_INPUT_TOKEN_UPPER_BOUND) {
+                throw new EmbeddingProviderError("INPUT_BUDGET_EXCEEDED", `OpenAI embedding input exceeds the ${MAX_INPUT_TOKEN_UPPER_BOUND}-token upper bound.`);
+            }
+            batchUpperBound += upperBound;
+        }
+        if (batchUpperBound > MAX_BATCH_TOKEN_UPPER_BOUND) {
+            throw new EmbeddingProviderError("INPUT_BUDGET_EXCEEDED", `OpenAI embedding batch exceeds the ${MAX_BATCH_TOKEN_UPPER_BOUND}-token upper bound.`);
+        }
+        const deadlineController = new AbortController();
+        let deadlineTimer;
+        if (options.deadline !== undefined) {
+            const deadline = options.deadline;
+            const remaining = deadline - this.now();
+            if (remaining <= 0) {
+                throw new EmbeddingProviderError("DEADLINE_EXCEEDED", "Embedding operation deadline was exceeded.");
+            }
+            const scheduleDeadline = () => {
+                const nextRemaining = deadline - this.now();
+                if (nextRemaining <= 0) {
+                    deadlineController.abort();
+                    return;
+                }
+                deadlineTimer = setTimeout(scheduleDeadline, Math.min(nextRemaining, 2_147_483_647));
+            };
+            scheduleDeadline();
+        }
+        const signals = [this.closeController.signal, deadlineController.signal];
+        if (options.signal)
+            signals.push(options.signal);
+        const signal = AbortSignal.any(signals);
+        let releaseRequestSlot;
+        try {
+            try {
+                releaseRequestSlot = await this.acquireRequestSlot(signal);
+            }
+            catch {
+                this.throwIfInterrupted(options, deadlineController);
+                throw new EmbeddingProviderError("PROVIDER_FAILURE", "Embedding request queue failed.");
+            }
+            this.throwIfInterrupted(options, deadlineController);
+            const requestBody = JSON.stringify({
+                input: inputs,
+                model: this.model,
+                dimensions: this.dimension,
+                encoding_format: "float",
+            });
+            for (let attempt = 1; attempt <= this.maxAttempts; attempt++) {
+                this.throwIfInterrupted(options, deadlineController);
+                if (!this.authorizeRequest) {
+                    throw new EmbeddingProviderError("REMOTE_AUTHORIZATION_REQUIRED", "Remote embedding request authorization is not configured.");
+                }
+                try {
+                    await awaitWithSignal(this.authorizeRequest({
+                        fingerprint: options.identityFingerprint,
+                        purpose: options.purpose,
+                        kind: options.kind,
+                        attempt,
+                        buildLease: options.buildLease,
+                    }), signal);
+                }
+                catch (error) {
+                    this.throwIfInterrupted(options, deadlineController);
+                    throw error;
+                }
+                this.throwIfInterrupted(options, deadlineController);
+                const requestController = new AbortController();
+                const requestTimer = setTimeout(() => requestController.abort(), this.requestTimeoutMs);
+                const requestSignal = AbortSignal.any([signal, requestController.signal]);
+                let response = null;
+                let responseBodyConsumed = false;
+                try {
+                    try {
+                        response = await this.fetchImpl(`${this.baseUrl}/embeddings`, {
+                            method: "POST",
+                            headers: {
+                                ...(this.apiKey ? { authorization: `Bearer ${this.apiKey}` } : {}),
+                                "content-type": "application/json",
+                            },
+                            body: requestBody,
+                            signal: requestSignal,
+                        });
+                    }
+                    catch {
+                        this.throwIfInterrupted(options, deadlineController);
+                    }
+                    this.throwIfInterrupted(options, deadlineController);
+                    if (requestController.signal.aborted)
+                        response = null;
+                    if (response?.ok) {
+                        let body;
+                        let bodyRead = false;
+                        try {
+                            body = await response.json();
+                            bodyRead = true;
+                            responseBodyConsumed = true;
+                        }
+                        catch (error) {
+                            this.throwIfInterrupted(options, deadlineController);
+                            if (!requestController.signal.aborted && error instanceof SyntaxError) {
+                                throw new EmbeddingProviderError("PROVIDER_FAILURE", "OpenAI embedding response is not valid JSON.");
+                            }
+                            response = null;
+                        }
+                        this.throwIfInterrupted(options, deadlineController);
+                        if (requestController.signal.aborted)
+                            response = null;
+                        if (bodyRead && response) {
+                            const parsed = parseResponse(body, inputs.length, batchUpperBound, this.model, this.dimension);
+                            const usage = Object.freeze({
+                                promptTokens: parsed.usage.prompt_tokens,
+                                totalTokens: parsed.usage.total_tokens,
+                            });
+                            return parsed.data.map(item => ({
+                                vector: item.embedding,
+                                model: parsed.model,
+                                dimension: item.embedding.length,
+                                usage,
+                            }));
+                        }
+                    }
+                }
+                finally {
+                    clearTimeout(requestTimer);
+                    if (response?.body && !responseBodyConsumed) {
+                        void response.body.cancel().catch(() => { });
+                    }
+                }
+                const status = response?.status;
+                const transient = status === undefined || status === 408 || status === 429 || status >= 500;
+                if (!transient) {
+                    throw new EmbeddingProviderError("HTTP_TERMINAL", `OpenAI embedding request failed with HTTP ${status}.`);
+                }
+                if (attempt === this.maxAttempts) {
+                    throw new EmbeddingProviderError("RETRY_EXHAUSTED", "OpenAI embedding request exhausted its retry budget.");
+                }
+                const retryAfter = response
+                    ? parseRetryAfter(response.headers.get("retry-after"), this.now())
+                    : null;
+                const exponential = this.baseRetryDelayMs * (2 ** (attempt - 1));
+                const jittered = exponential * (0.5 + (this.random() * 0.5));
+                const delayMs = Math.min(retryAfter ?? jittered, this.maxRetryDelayMs);
+                if (options.deadline !== undefined && this.now() + delayMs >= options.deadline) {
+                    throw new EmbeddingProviderError("DEADLINE_EXCEEDED", "Embedding operation deadline was exceeded.");
+                }
+                this.throwIfInterrupted(options, deadlineController);
+                try {
+                    await this.sleep(delayMs, signal);
+                }
+                catch {
+                    this.throwIfInterrupted(options, deadlineController);
+                    throw new EmbeddingProviderError("PROVIDER_FAILURE", "OpenAI embedding retry delay failed.");
+                }
+                this.throwIfInterrupted(options, deadlineController);
+            }
+            throw new EmbeddingProviderError("RETRY_EXHAUSTED", "OpenAI embedding request exhausted its retry budget.");
+        }
+        finally {
+            if (deadlineTimer !== undefined)
+                clearTimeout(deadlineTimer);
+            releaseRequestSlot?.();
+        }
+    }
+    async close() {
+        if (!this.closePromise) {
+            this.closed = true;
+            this.closeController.abort();
+            this.closePromise = this.requestTail;
+        }
+        await this.closePromise;
+    }
+}

package/dist/embedding/owner.d.ts

@@ -0,0 +1,13 @@
+import type { EmbeddingProvider, EmbeddingProviderOwner } from "./provider.js";
+export interface DisposableEmbeddingRuntime {
+    dispose(): Promise<void>;
+}
+/** Owns a provider and the runtime it depends on. */
+export declare class CompositeEmbeddingProviderOwner implements EmbeddingProviderOwner {
+    readonly provider: EmbeddingProvider;
+    private readonly runtime;
+    private closePromise;
+    constructor(provider: EmbeddingProvider, runtime: DisposableEmbeddingRuntime);
+    close(): Promise<void>;
+    private closeResources;
+}

package/dist/embedding/owner.js

@@ -0,0 +1,36 @@
+/** Owns a provider and the runtime it depends on. */
+export class CompositeEmbeddingProviderOwner {
+    provider;
+    runtime;
+    closePromise = null;
+    constructor(provider, runtime) {
+        this.provider = provider;
+        this.runtime = runtime;
+    }
+    close() {
+        if (!this.closePromise) {
+            this.closePromise = this.closeResources();
+        }
+        return this.closePromise;
+    }
+    async closeResources() {
+        let providerError;
+        try {
+            await this.provider.close();
+        }
+        catch (error) {
+            providerError = error;
+        }
+        let runtimeError;
+        try {
+            await this.runtime.dispose();
+        }
+        catch (error) {
+            runtimeError = error;
+        }
+        if (providerError !== undefined)
+            throw providerError;
+        if (runtimeError !== undefined)
+            throw runtimeError;
+    }
+}

package/dist/embedding/provider.d.ts

@@ -0,0 +1,68 @@
+import type { EmbeddingBuildLease } from "./identity.js";
+export type EmbeddingInputKind = "query" | "document";
+export type EmbeddingRequestPurpose = "capability-probe" | "index-build" | "query-embedding";
+export declare const REMOTE_CAPABILITY_PROBE_SENTINEL = "qmd-remote-capability-probe-v1";
+export type EmbeddingProviderErrorCode = "PROVIDER_CLOSED" | "OPERATION_ABORTED" | "DEADLINE_EXCEEDED" | "PROVIDER_FAILURE" | "MISSING_EMBEDDING" | "EMPTY_VECTOR" | "NON_FINITE_VECTOR" | "MODEL_MISMATCH" | "DIMENSION_UNKNOWN" | "DIMENSION_MISMATCH" | "BATCH_CARDINALITY_MISMATCH" | "INPUT_BUDGET_EXCEEDED" | "RESPONSE_SCHEMA_INVALID" | "HTTP_TERMINAL" | "RETRY_EXHAUSTED" | "IDENTITY_FINGERPRINT_REQUIRED" | "REMOTE_AUTHORIZATION_REQUIRED";
+export declare class EmbeddingProviderError extends Error {
+    readonly code: EmbeddingProviderErrorCode;
+    readonly operation?: "embed" | "embedBatch";
+    readonly index?: number;
+    /** Native causes are intentionally discarded so provider errors are safe to serialize. */
+    readonly cause: undefined;
+    constructor(code: EmbeddingProviderErrorCode, message: string, options?: {
+        operation?: "embed" | "embedBatch";
+        index?: number;
+    });
+}
+export interface EmbeddingOperationOptions {
+    /** Required purpose used by remote policy guards and request auditing. */
+    purpose: EmbeddingRequestPurpose;
+    /** Whether the caller formatted the input as a query or document. */
+    kind?: EmbeddingInputKind;
+    /** Cancels the caller's wait for this operation. */
+    signal?: AbortSignal;
+    /** Absolute Unix timestamp in milliseconds after which the operation must fail. */
+    deadline?: number;
+    /** Complete active build lease required for remote index-build requests. */
+    buildLease?: EmbeddingBuildLease;
+    /** Full published/build identity fingerprint, including chunking policy. */
+    identityFingerprint: string;
+}
+export interface RemoteEmbeddingRequestAuthorization {
+    readonly fingerprint: string;
+    readonly purpose: EmbeddingRequestPurpose;
+    readonly kind?: EmbeddingInputKind;
+    readonly attempt: number;
+    readonly buildLease?: EmbeddingBuildLease;
+}
+export type RemoteEmbeddingRequestGuard = (request: RemoteEmbeddingRequestAuthorization) => void | Promise<void>;
+export interface EmbeddingVector {
+    vector: number[];
+    model: string;
+    dimension: number;
+    /** Provider-reported numeric usage for this operation, when available. */
+    readonly usage?: Readonly<{
+        promptTokens: number;
+        totalTokens: number;
+    }>;
+}
+export interface EmbeddingProvider {
+    readonly providerId: string;
+    readonly model: string;
+    readonly dimension: number | null;
+    readonly remote: boolean;
+    canonicalIdentityMaterial(): string;
+    /** Compute identity material from a persisted dimension without loading the model. */
+    canonicalIdentityMaterialForDimension?(dimension: number): string;
+    formatQuery(query: string): string;
+    formatDocument(text: string, title?: string): string;
+    embed(text: string, options: EmbeddingOperationOptions): Promise<EmbeddingVector>;
+    embedBatch(texts: string[], options: EmbeddingOperationOptions): Promise<EmbeddingVector[]>;
+    estimateTokens?(text: string): number;
+    close(): Promise<void>;
+}
+/** Owns a provider and every resource needed to service it. */
+export interface EmbeddingProviderOwner {
+    readonly provider: EmbeddingProvider;
+    close(): Promise<void>;
+}