@wei840222/qmd 2026.8.23

package/dist/diagnostics.js

@@ -0,0 +1,260 @@
+import { createHash } from "node:crypto";
+import { createEmbeddingIdentity } from "./embedding/identity.js";
+import { canonicalLocalEmbeddingIdentityMaterial } from "./embedding/local-identity.js";
+import { canonicalOpenAIEmbeddingIdentityMaterial } from "./embedding/openai.js";
+import { getCjkAnalyzerFingerprint } from "./search/cjk-index.js";
+import { canonicalEmbeddingBuildMaterial } from "./store.js";
+function tableExists(db, name) {
+    return db.prepare(`
+    SELECT 1 FROM sqlite_master WHERE type IN ('table', 'view') AND name = ?
+  `).get(name) != null;
+}
+function tableColumns(db, name) {
+    if (!tableExists(db, name))
+        return new Set();
+    return new Set(db.prepare(`PRAGMA table_info("${name}")`).all()
+        .map(column => column.name));
+}
+function countRows(db, table) {
+    if (!tableExists(db, table))
+        return null;
+    try {
+        const row = db.prepare(`SELECT COUNT(*) AS count FROM "${table}"`).get();
+        return Number(row.count);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (table === "vectors_vec" && /no such module:\s*vec0/i.test(message))
+            return null;
+        if (table.startsWith("documents_fts") && /no such column/i.test(message))
+            return null;
+        throw error;
+    }
+}
+function activeDocumentCount(db) {
+    if (!tableExists(db, "documents"))
+        return 0;
+    const row = db.prepare(`SELECT COUNT(*) AS count FROM documents WHERE active = 1`).get();
+    return Number(row.count);
+}
+function shortFingerprint(value) {
+    return value == null ? null : value.slice(0, 12);
+}
+function resolvedIdentity(provider, configured, stored) {
+    const providerId = provider?.providerId ?? configured?.id;
+    const model = provider?.model ?? configured?.model;
+    const remote = provider?.remote ?? configured?.remote;
+    if (providerId == null || model == null || remote == null)
+        return undefined;
+    const storedMatches = stored?.provider_id === providerId && stored.model === model;
+    const dimension = provider?.dimension ?? configured?.dimension
+        ?? (storedMatches ? Number(stored.dimension) : null);
+    if (dimension == null)
+        return undefined;
+    try {
+        const providerMaterial = provider
+            ? provider.canonicalIdentityMaterialForDimension?.(dimension)
+                ?? provider.canonicalIdentityMaterial()
+            : providerId === "local-llama-cpp"
+                ? canonicalLocalEmbeddingIdentityMaterial(model, dimension)
+                : providerId === "openai"
+                    ? canonicalOpenAIEmbeddingIdentityMaterial(model, dimension)
+                    : undefined;
+        if (providerMaterial == null)
+            return undefined;
+        const identities = ["regex", "auto"].map(chunkStrategy => createEmbeddingIdentity({
+            providerId,
+            model,
+            dimension,
+            remote,
+            canonicalMaterial: canonicalEmbeddingBuildMaterial(providerMaterial, chunkStrategy),
+        }));
+        return identities.find(identity => identity.fingerprint === stored?.fingerprint)
+            ?? identities[0];
+    }
+    catch {
+        return undefined;
+    }
+}
+function inspectEmbeddingDiagnostics(db, fallbackModel, provider, keyConfigured, configured) {
+    const stateColumns = tableColumns(db, "embedding_index_state");
+    const stored = stateColumns.has("fingerprint")
+        ? db.prepare(`
+        SELECT fingerprint, provider_id, model, dimension, remote, status,
+               generation, lease_expires_at
+        FROM embedding_index_state WHERE singleton = 1
+      `).get()
+        : undefined;
+    const expected = resolvedIdentity(provider, configured, stored);
+    const model = provider?.model ?? configured?.model ?? stored?.model ?? fallbackModel;
+    const fingerprint = expected?.fingerprint
+        ?? (stored != null
+            && stored.provider_id === provider?.providerId
+            && stored.model === model
+            ? stored.fingerprint
+            : null);
+    const activeDocs = activeDocumentCount(db);
+    const metadataColumns = tableColumns(db, "content_vectors");
+    const hasMetadata = metadataColumns.has("hash") && metadataColumns.has("seq");
+    const hasFingerprint = metadataColumns.has("embed_fingerprint");
+    const hasLayouts = metadataColumns.has("total_chunks");
+    const hasVectors = tableExists(db, "vectors_vec");
+    const vectorChunkCount = countRows(db, "vectors_vec");
+    const vectorsReadable = vectorChunkCount != null;
+    const hasEmbeddingRows = (countRows(db, "content_vectors") ?? 0) > 0
+        || (vectorChunkCount ?? 0) > 0;
+    let metadataOnly = 0;
+    let vectorOnly = 0;
+    let incompleteLayouts = 0;
+    let pendingDocuments = activeDocs;
+    if (hasMetadata) {
+        if (vectorsReadable) {
+            const cvRows = db.prepare(`SELECT hash, seq FROM content_vectors`).all();
+            const vvRows = db.prepare(`SELECT hash_seq FROM vectors_vec`).all();
+            const vvKeys = new Set(vvRows.map(r => r.hash_seq));
+            const cvKeys = new Set(cvRows.map(r => `${r.hash}_${r.seq}`));
+            for (const cv of cvRows) {
+                if (!vvKeys.has(`${cv.hash}_${cv.seq}`))
+                    metadataOnly++;
+            }
+            for (const vv of vvRows) {
+                if (!cvKeys.has(vv.hash_seq))
+                    vectorOnly++;
+            }
+        }
+        if (hasLayouts) {
+            incompleteLayouts = Number(db.prepare(`
+        SELECT COUNT(*) AS count FROM (
+          SELECT hash, model
+          FROM content_vectors
+          GROUP BY hash, model, embed_fingerprint
+          HAVING COUNT(*) <> MAX(total_chunks)
+        )
+      `).get().count);
+        }
+        if (fingerprint != null && hasFingerprint && hasLayouts) {
+            pendingDocuments = Number(db.prepare(`
+        SELECT COUNT(*) AS count
+        FROM documents d
+        LEFT JOIN (
+          SELECT cv.hash
+          FROM content_vectors cv
+          WHERE cv.model = ? AND cv.embed_fingerprint = ?
+          GROUP BY cv.hash
+          HAVING COUNT(*) = MAX(cv.total_chunks)
+        ) complete ON complete.hash = d.hash
+        WHERE d.active = 1 AND complete.hash IS NULL
+      `).get(model, fingerprint).count);
+        }
+    }
+    const compatible = stored != null && fingerprint != null && stored.fingerprint === fingerprint;
+    let buildState;
+    if (!tableExists(db, "embedding_index_state")) {
+        buildState = hasEmbeddingRows ? "incompatible" : "missing";
+    }
+    else if (!stored) {
+        buildState = hasEmbeddingRows ? "incompatible" : "empty";
+    }
+    else if (!compatible) {
+        buildState = "incompatible";
+    }
+    else if (stored.status === "building") {
+        buildState = stored.lease_expires_at != null && stored.lease_expires_at > Date.now()
+            ? "building"
+            : "partial";
+    }
+    else if (metadataOnly > 0 || vectorOnly > 0 || incompleteLayouts > 0 || pendingDocuments > 0) {
+        buildState = "partial";
+    }
+    else {
+        buildState = "ready";
+    }
+    const effectiveRemote = provider?.remote ?? configured?.remote ?? false;
+    return {
+        provider: {
+            id: provider?.providerId ?? configured?.id ?? stored?.provider_id ?? null,
+            remote: provider?.remote ?? configured?.remote ?? stored?.remote === 1,
+            model,
+            dimension: provider?.dimension ?? configured?.dimension ?? (stored ? Number(stored.dimension) : null),
+            keyConfigured: (provider?.remote ?? configured?.remote) === true && keyConfigured,
+        },
+        identity: {
+            shortFingerprint: shortFingerprint(fingerprint),
+            fullFingerprint: fingerprint,
+            storedShortFingerprint: shortFingerprint(stored?.fingerprint ?? null),
+            storedFullFingerprint: stored?.fingerprint ?? null,
+            compatible,
+        },
+        build: {
+            state: buildState,
+            generation: stored ? Number(stored.generation) : null,
+            leaseExpiresAt: stored?.lease_expires_at == null ? null : Number(stored.lease_expires_at),
+        },
+        chunks: { pendingDocuments, metadataOnly, vectorOnly, incompleteLayouts },
+        repairCommand: buildState === "ready" || buildState === "empty" ? null : effectiveRemote
+            ? "qmd embed --force"
+            : "qmd embed --force",
+    };
+}
+function channelReadiness(rowCount, activeDocs, state, fingerprintMatches, wordChannel) {
+    if (rowCount == null)
+        return "missing";
+    if (wordChannel && state?.word_capability === "unavailable")
+        return "incompatible";
+    if (wordChannel && (!fingerprintMatches || state?.status === "dirty"))
+        return "stale";
+    if (rowCount !== activeDocs)
+        return "partial";
+    return "ready";
+}
+function inspectLexicalDiagnostics(db) {
+    const activeDocs = activeDocumentCount(db);
+    const currentFingerprint = getCjkAnalyzerFingerprint();
+    const stateColumns = tableColumns(db, "cjk_index_state");
+    const state = stateColumns.has("analyzer_fingerprint")
+        ? db.prepare(`
+        SELECT status, analyzer_fingerprint, word_capability, diagnostic_code,
+               dirty_since_mutation_seq
+        FROM cjk_index_state WHERE singleton = 1
+      `).get()
+        : undefined;
+    const fingerprintMatches = activeDocs === 0
+        || state?.analyzer_fingerprint === currentFingerprint;
+    const channels = {
+        char: channelReadiness(countRows(db, "documents_fts"), activeDocs, state, true, false),
+        word: channelReadiness(countRows(db, "documents_fts_words"), activeDocs, state, fingerprintMatches, true),
+        bigram: channelReadiness(countRows(db, "documents_fts_bigrams"), activeDocs, state, fingerprintMatches, true),
+    };
+    const rebuildReason = state?.status === "dirty"
+        ? state.diagnostic_code ?? "dirty"
+        : activeDocs === 0
+            ? null
+            : !state
+                ? "schema-missing"
+                : !fingerprintMatches
+                    ? "analyzer-fingerprint-mismatch"
+                    : Object.values(channels).some(channel => channel !== "ready")
+                        ? "channel-readiness-incomplete"
+                        : null;
+    return {
+        jiebaCapability: state?.word_capability ?? "unknown",
+        analyzerFingerprint: currentFingerprint,
+        storedAnalyzerFingerprint: state?.analyzer_fingerprint ?? null,
+        state: state?.status ?? "missing",
+        channels,
+        dirtySinceMutationSeq: state?.dirty_since_mutation_seq == null
+            ? null
+            : Number(state.dirty_since_mutation_seq),
+        rebuildReason,
+        repairCommand: rebuildReason == null ? null : "qmd update",
+    };
+}
+export function inspectIndexDiagnostics(db, options) {
+    return {
+        embedding: inspectEmbeddingDiagnostics(db, options.fallbackModel, options.provider, options.keyConfigured === true, options.configuredProvider),
+        lexical: inspectLexicalDiagnostics(db),
+    };
+}
+export function diagnosticsSnapshotHash(diagnostics) {
+    return createHash("sha256").update(JSON.stringify(diagnostics)).digest("hex");
+}

package/dist/embedding/config.d.ts

@@ -0,0 +1,52 @@
+import type { Database } from "../db.js";
+export declare const OPENAI_EMBEDDING_MODEL: "text-embedding-3-small";
+export declare const OPENAI_EMBEDDING_DIMENSION: 1536;
+export declare const EMBEDDING_CONFIG_DB_KEY: "embedding_config";
+export declare const DEFAULT_OPENAI_BASE_URL: "https://api.openai.com/v1";
+/** Supported OpenAI embedding models and their native dimensions. */
+export declare const OPENAI_EMBEDDING_MODELS: ReadonlyMap<string, number>;
+export type OpenAIEmbeddingModel = "text-embedding-3-small" | "text-embedding-3-large";
+export type EmbeddingProviderName = "local" | "openai";
+export type EmbeddingConfig = {
+    provider: "local";
+    model?: string;
+    dimension?: number;
+} | {
+    provider: "openai";
+    model?: OpenAIEmbeddingModel;
+    dimension?: number;
+    baseUrl?: string;
+};
+export type CanonicalEmbeddingConfig = Readonly<{
+    provider: "local";
+    model: string;
+    dimension: number | null;
+} | {
+    provider: "openai";
+    model: OpenAIEmbeddingModel;
+    dimension: number;
+    baseUrl: string;
+}>;
+export type EmbeddingConfigSource = "embedding-block" | "legacy-models" | "database" | "local-default";
+export interface ResolvedEmbeddingConfig {
+    readonly canonical: CanonicalEmbeddingConfig;
+    readonly source: EmbeddingConfigSource;
+    readonly credentialAvailable: boolean;
+    /** Remote transport is configured; consent and purpose guards still apply per request. */
+    readonly remoteRequestsEnabled: boolean;
+}
+export declare class EmbeddingConfigError extends Error {
+    constructor(message: string);
+}
+export interface ResolveEmbeddingConfigOptions {
+    /** Per-store SDK inline/configPath or CLI YAML snapshot. */
+    config?: unknown;
+    /** Canonical, non-secret configuration restored from SQLite. */
+    dbConfig?: unknown;
+    defaultLocalModel: string;
+    env?: Readonly<Record<string, string | undefined>>;
+}
+export declare function resolveEmbeddingConfig(options: ResolveEmbeddingConfigOptions): ResolvedEmbeddingConfig;
+export declare function resolveEmbeddingModelOverride(resolved: ResolvedEmbeddingConfig, override: string | undefined): string;
+export declare function readCanonicalEmbeddingConfig(db: Database): CanonicalEmbeddingConfig | undefined;
+export declare function writeCanonicalEmbeddingConfig(db: Database, config: CanonicalEmbeddingConfig): void;

package/dist/embedding/config.js

@@ -0,0 +1,229 @@
+export const OPENAI_EMBEDDING_MODEL = "text-embedding-3-small";
+export const OPENAI_EMBEDDING_DIMENSION = 1536;
+export const EMBEDDING_CONFIG_DB_KEY = "embedding_config";
+export const DEFAULT_OPENAI_BASE_URL = "https://api.openai.com/v1";
+/** Supported OpenAI embedding models and their native dimensions. */
+export const OPENAI_EMBEDDING_MODELS = new Map([
+    ["text-embedding-3-small", 1536],
+    ["text-embedding-3-large", 3072],
+]);
+export class EmbeddingConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "EmbeddingConfigError";
+    }
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function hasOwn(value, key) {
+    return Object.prototype.hasOwnProperty.call(value, key);
+}
+function requireRecord(value, label) {
+    if (!isRecord(value)) {
+        throw new EmbeddingConfigError(`${label} must be an object.`);
+    }
+    return value;
+}
+function requireModel(value, label) {
+    if (typeof value !== "string" || value.trim() === "") {
+        throw new EmbeddingConfigError(`${label} must be a non-empty string.`);
+    }
+    return value;
+}
+function parseDimension(value, label) {
+    if (!Number.isInteger(value) || value < 1) {
+        throw new EmbeddingConfigError(`${label} must be a positive integer.`);
+    }
+    return value;
+}
+function requireBaseUrl(value, label) {
+    if (typeof value !== "string" || value.trim() === "") {
+        throw new EmbeddingConfigError(`${label} must be a non-empty string.`);
+    }
+    return value.trim().replace(/\/+$/, "");
+}
+function assertKnownKeys(value, label) {
+    const allowed = new Set(["provider", "model", "dimension", "baseUrl"]);
+    const unknown = Object.keys(value).filter(key => !allowed.has(key));
+    if (unknown.length > 0) {
+        throw new EmbeddingConfigError(`${label} contains unsupported field ${unknown[0]}.`);
+    }
+}
+function parseEmbeddingBlock(input, defaultLocalModel, label, requireCanonicalValues) {
+    const value = requireRecord(input, label);
+    assertKnownKeys(value, label);
+    const rawProvider = hasOwn(value, "provider") ? value.provider : undefined;
+    const rawBaseUrl = hasOwn(value, "baseUrl") ? value.baseUrl : undefined;
+    // Infer provider: "openai" if provider is omitted but baseUrl is present
+    const provider = rawProvider ?? (rawBaseUrl ? "openai" : "local");
+    if (provider === "local") {
+        const model = hasOwn(value, "model")
+            ? requireModel(value.model, `${label}.model`)
+            : requireCanonicalValues
+                ? requireModel(undefined, `${label}.model`)
+                : defaultLocalModel;
+        const dimension = hasOwn(value, "dimension")
+            ? value.dimension === null && requireCanonicalValues
+                ? null
+                : parseDimension(value.dimension, `${label}.dimension`)
+            : requireCanonicalValues
+                ? null
+                : null;
+        return Object.freeze({ provider: "local", model, dimension });
+    }
+    if (provider === "openai") {
+        const model = hasOwn(value, "model")
+            ? requireModel(value.model, `${label}.model`)
+            : OPENAI_EMBEDDING_MODEL;
+        const expectedDimension = OPENAI_EMBEDDING_MODELS.get(model);
+        if (expectedDimension === undefined) {
+            const supported = Array.from(OPENAI_EMBEDDING_MODELS.keys()).join(", ");
+            throw new EmbeddingConfigError(`${label}.model must be one of: ${supported}. Got: ${model}`);
+        }
+        const dimension = hasOwn(value, "dimension")
+            ? parseDimension(value.dimension, `${label}.dimension`)
+            : expectedDimension;
+        if (dimension !== expectedDimension) {
+            throw new EmbeddingConfigError(`${label}.dimension must be ${expectedDimension} for model ${model}.`);
+        }
+        const baseUrl = rawBaseUrl
+            ? requireBaseUrl(rawBaseUrl, `${label}.baseUrl`)
+            : DEFAULT_OPENAI_BASE_URL;
+        return Object.freeze({
+            provider: "openai",
+            model: model,
+            dimension: expectedDimension,
+            baseUrl,
+        });
+    }
+    throw new EmbeddingConfigError(`${label}.provider must be local or openai.`);
+}
+function resolveSource(options) {
+    const defaultLocalModel = requireModel(options.defaultLocalModel, "default local embedding model");
+    if (options.config !== undefined) {
+        const config = requireRecord(options.config, "embedding config source");
+        if (hasOwn(config, "embedding")) {
+            const canonical = parseEmbeddingBlock(config.embedding, defaultLocalModel, "embedding config", false);
+            if (canonical.provider === "openai") {
+                throw new EmbeddingConfigError("embedding config no longer selects remote embeddings; configure models.embed_api_url and models.embed_api_model instead.");
+            }
+            return {
+                canonical,
+                source: "embedding-block",
+            };
+        }
+        if (hasOwn(config, "models")) {
+            const models = requireRecord(config.models, "models");
+            const hasEmbed = hasOwn(models, "embed");
+            const embedModel = hasEmbed ? requireModel(models.embed, "models.embed") : undefined;
+            if (embedModel === "openai" || embedModel?.startsWith("openai:")) {
+                throw new EmbeddingConfigError("models.embed no longer accepts OpenAI shorthand; configure models.embed_api_url (or models.embed_url/models.embed_base_url) and models.embed_api_model instead.");
+            }
+            const rawEmbedBaseUrl = models.embed_url ?? models.embed_base_url ?? models.embed_api_url;
+            const hasEmbedBaseUrl = rawEmbedBaseUrl !== undefined && String(rawEmbedBaseUrl).trim() !== "";
+            const customDimension = hasOwn(models, "embed_dimension")
+                ? parseDimension(models.embed_dimension, "models.embed_dimension")
+                : undefined;
+            const embedApiModel = hasOwn(models, "embed_api_model")
+                ? requireModel(models.embed_api_model, "models.embed_api_model")
+                : undefined;
+            if (hasEmbedBaseUrl && embedApiModel !== undefined) {
+                return {
+                    canonical: parseEmbeddingBlock({
+                        provider: "openai",
+                        model: embedApiModel,
+                        ...(customDimension === undefined ? {} : { dimension: customDimension }),
+                        baseUrl: requireBaseUrl(rawEmbedBaseUrl, "models.embed_api_url"),
+                    }, defaultLocalModel, "models", false),
+                    source: "legacy-models",
+                };
+            }
+            if (hasEmbed || hasEmbedBaseUrl || embedApiModel !== undefined || customDimension !== undefined) {
+                return {
+                    canonical: Object.freeze({
+                        provider: "local",
+                        model: embedModel ?? defaultLocalModel,
+                        dimension: customDimension ?? null,
+                    }),
+                    source: "legacy-models",
+                };
+            }
+        }
+    }
+    if (options.dbConfig !== undefined) {
+        return {
+            canonical: parseEmbeddingBlock(options.dbConfig, defaultLocalModel, "database embedding config", true),
+            source: "database",
+        };
+    }
+    return {
+        canonical: Object.freeze({
+            provider: "local",
+            model: defaultLocalModel,
+            dimension: null,
+        }),
+        source: "local-default",
+    };
+}
+export function resolveEmbeddingConfig(options) {
+    const resolved = resolveSource(options);
+    const env = options.env ?? process.env;
+    const hasApiKey = typeof env.OPENAI_API_KEY === "string" && env.OPENAI_API_KEY.trim() !== "";
+    // For non-default endpoints (self-hosted / proxy), API key is optional
+    const isNonDefaultEndpoint = resolved.canonical.provider === "openai"
+        && resolved.canonical.baseUrl !== DEFAULT_OPENAI_BASE_URL;
+    const credentialAvailable = resolved.canonical.provider === "local"
+        || hasApiKey
+        || isNonDefaultEndpoint;
+    return Object.freeze({
+        canonical: resolved.canonical,
+        source: resolved.source,
+        credentialAvailable,
+        remoteRequestsEnabled: resolved.canonical.provider === "openai" && credentialAvailable,
+    });
+}
+export function resolveEmbeddingModelOverride(resolved, override) {
+    if (override === undefined)
+        return resolved.canonical.model;
+    const model = requireModel(override, "embedding model override");
+    if (resolved.canonical.provider === "openai" && model !== resolved.canonical.model) {
+        throw new EmbeddingConfigError(`OpenAI embedding model override must be ${resolved.canonical.model}.`);
+    }
+    return model;
+}
+export function readCanonicalEmbeddingConfig(db) {
+    try {
+        const row = db.prepare("SELECT value FROM store_config WHERE key = ?").get(EMBEDDING_CONFIG_DB_KEY);
+        if (row?.value === undefined)
+            return undefined;
+        if (typeof row.value !== "string") {
+            throw new EmbeddingConfigError("database embedding config must be stored as JSON text.");
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(row.value);
+        }
+        catch {
+            throw new EmbeddingConfigError("database embedding config contains invalid JSON.");
+        }
+        return parseEmbeddingBlock(parsed, "unused-for-canonical-config", "database embedding config", true);
+    }
+    catch (err) {
+        if (err instanceof EmbeddingConfigError)
+            throw err;
+        return undefined;
+    }
+}
+export function writeCanonicalEmbeddingConfig(db, config) {
+    const canonical = parseEmbeddingBlock(config, "unused-for-canonical-config", "canonical embedding config", true);
+    const newValue = JSON.stringify(canonical);
+    const existing = db.prepare(`SELECT value FROM store_config WHERE key = ?`).get(EMBEDDING_CONFIG_DB_KEY);
+    if (existing?.value === newValue)
+        return;
+    db.prepare(`
+    INSERT INTO store_config(key, value)
+    VALUES (?, ?)
+    ON CONFLICT(key) DO UPDATE SET value = excluded.value
+  `).run(EMBEDDING_CONFIG_DB_KEY, newValue);
+}

package/dist/embedding/identity.d.ts

@@ -0,0 +1,58 @@
+import type { Database } from "../db.js";
+export type EmbeddingBuildMode = "rebuild" | "resume";
+export type EmbeddingIndexStateStatus = "empty" | "building" | "partial" | "ready" | "incompatible" | "mismatch";
+export interface EmbeddingIdentity {
+    readonly fingerprint: string;
+    readonly providerId: string;
+    readonly model: string;
+    readonly dimension: number;
+    readonly remote: boolean;
+    readonly canonicalMaterial: string;
+}
+export interface EmbeddingBuildLease {
+    readonly fingerprint: string;
+    readonly ownerId: string;
+    readonly generation: number;
+    readonly leaseExpiresAt: number;
+    readonly mode: EmbeddingBuildMode;
+}
+export interface EmbeddingIndexState {
+    readonly status: EmbeddingIndexStateStatus;
+    readonly identity?: EmbeddingIdentity;
+    readonly ownerId?: string;
+    readonly generation?: number;
+    readonly leaseExpiresAt?: number;
+}
+export type EmbeddingIdentityStateErrorCode = "IDENTITY_MISMATCH" | "LEASE_BUSY" | "LEASE_LOST" | "INVALID_IDENTITY" | "INVALID_LEASE";
+export declare class EmbeddingIdentityStateError extends Error {
+    readonly code: EmbeddingIdentityStateErrorCode;
+    constructor(code: EmbeddingIdentityStateErrorCode, message: string);
+}
+export interface BeginEmbeddingBuildOptions {
+    ownerId: string;
+    now: number;
+    leaseMs: number;
+    allowDestructiveRebuild: boolean;
+    /** Force a same-identity global reset inside this transaction. */
+    forceRebuild?: boolean;
+    /** Remote identity changes require force independently from destructive permission. */
+    requireForceForIdentityChange?: boolean;
+    /** Runs under BEGIN IMMEDIATE before any identity state or vector data mutation. */
+    beforeMutation?: () => void;
+    /** Fault-injection/observability hook after vector-table preparation, still under the writer transaction. */
+    afterVectorTablePrepared?: () => void;
+}
+export declare function createEmbeddingIdentity(input: {
+    providerId: string;
+    model: string;
+    dimension: number;
+    remote: boolean;
+    canonicalMaterial: string;
+}): EmbeddingIdentity;
+export declare function ensureEmbeddingIdentitySchema(db: Database): void;
+export declare function readStoredEmbeddingIdentity(db: Database): EmbeddingIdentity | undefined;
+export declare function inspectEmbeddingIndexState(db: Database, expected: EmbeddingIdentity, now?: number): EmbeddingIndexState;
+export declare function beginEmbeddingBuild(db: Database, identity: EmbeddingIdentity, options: BeginEmbeddingBuildOptions): EmbeddingBuildLease;
+export declare function renewEmbeddingBuildLease(db: Database, lease: EmbeddingBuildLease, now: number, leaseMs: number): EmbeddingBuildLease;
+export declare function completeEmbeddingBuild(db: Database, lease: EmbeddingBuildLease, now?: number): void;
+export declare function abandonEmbeddingBuild(db: Database, lease: EmbeddingBuildLease, now?: number): void;