@untangle-code/cli 0.0.0-stage → 0.1.0

package/dist/cli/index-state.js

@@ -0,0 +1,852 @@
+/**
+ * Der lokale Indexzustand: welches Einbettungsprofil welchen Repo/Ref-Index
+ * gebaut hat.
+ *
+ * Seit Welle 9 ist das keine Singleton-Datei mehr. Eine physische
+ * Repository-Wurzel kann mehrere konfigurierte Repo-IDs, Refs und
+ * Einbettungsprofile tragen. Jeder dieser Zustaende liegt deshalb in einem
+ * eigenen, aus seiner kanonischen Identitaet gehashten Datensatz. Ein
+ * separater, generationsgebundener Pointer pro Repo/Ref bezeichnet das
+ * Profil des letzten gestarteten Laufs fuer `--embedder=auto`.
+ *
+ * `index-state.json` bleibt als lesbarer Migrations-Fallback erhalten. Sobald
+ * die Registry dieselbe logische Identitaet kennt, gewinnt jedoch immer ihr
+ * Datensatz; der Singleton wird dann nicht ein zweites Mal ausgegeben.
+ *
+ * Alle Dateinamen entstehen ausschliesslich aus SHA-256-Hashes. Registry und
+ * Datensaetze sind hart begrenzt. Korrupte, uebergrosse oder unbeschraenkte
+ * Registry-Inhalte werden nicht teilweise als gesund behandelt.
+ */
+import { createHash, randomUUID } from "node:crypto";
+import { constants as fsConstants } from "node:fs";
+import { lstat, mkdir, open, opendir, rename, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+export function indexStateAfterRun(input) {
+    const { generationId, corpusRevisionFingerprint, ...state } = input;
+    if (state.outcome === "failed" && generationId === null)
+        return null;
+    return {
+        ...state,
+        ...(generationId === null ? {} : { generationId }),
+        ...(state.outcome === "completed" && corpusRevisionFingerprint !== undefined
+            ? { corpusRevisionFingerprint }
+            : {}),
+    };
+}
+/** Alter Singleton-Name unterhalb von `.untangle/`. Nur noch Lesefallback. */
+export const INDEX_STATE_FILE = "index-state.json";
+export const INDEX_STATE_REGISTRY_DIR = "index-states-v1";
+export const INDEX_STATE_RECORDS_DIR = "records";
+export const INDEX_STATE_CURRENT_DIR = "current";
+/** Harte Ressourcenlimits fuer lokal kontrollierbare Registry-Lesevorgaenge. */
+export const MAX_INDEX_STATE_FILE_BYTES = 64 * 1024;
+export const MAX_INDEX_STATE_REGISTRY_ENTRIES = 512;
+const MAX_INDEX_STATE_FIELD_LENGTH = 8 * 1024;
+const HASH_FILE_PATTERN = /^[0-9a-f]{64}\.json$/u;
+const TEMP_FILE_PATTERN = /^[0-9a-f]{64}\.json\.[0-9a-f-]{36}\.tmp$/u;
+const READ_ONLY_NO_FOLLOW = fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW;
+/** `<repoRoot>/.untangle` — dasselbe Verzeichnis, das `untangle index` anlegt. */
+export function stateRootOf(repoRoot) {
+    return path.join(repoRoot, ".untangle");
+}
+/** Der alte Singleton-Pfad. Externe Hinweise und Migration duerfen ihn weiter nennen. */
+export function indexStatePath(stateRoot) {
+    return path.join(stateRoot, INDEX_STATE_FILE);
+}
+export function indexStateRecordKey(identity) {
+    return hashCanonical([
+        "untangle-index-state-record-v1",
+        identity.workspaceId,
+        identity.repoId,
+        identity.refId,
+        identity.embeddingProfileId,
+        ...storageIdentitySuffix(identity),
+    ]);
+}
+export function indexStateCurrentKey(identity) {
+    return hashCanonical([
+        "untangle-index-state-current-v1",
+        identity.workspaceId,
+        identity.repoId,
+        identity.refId,
+        ...storageIdentitySuffix(identity),
+    ]);
+}
+/** Preserve old Qdrant keys; embedded paths get independent publication namespaces. */
+function storageIdentitySuffix(identity) {
+    return identity.storageBackend === "lancedb" ? ["lancedb", identity.storeUrl ?? ""] : [];
+}
+/** Lock key shared by every profile publication for one repo/ref/backend pointer. */
+export function indexStateLockKey(identity) {
+    return `index-state:${indexStateCurrentKey(identity)}`;
+}
+export function indexStateRecordPath(stateRoot, identity) {
+    return path.join(stateRoot, INDEX_STATE_REGISTRY_DIR, INDEX_STATE_RECORDS_DIR, `${indexStateRecordKey(identity)}.json`);
+}
+export function indexStateCurrentPath(stateRoot, identity) {
+    return path.join(stateRoot, INDEX_STATE_REGISTRY_DIR, INDEX_STATE_CURRENT_DIR, `${indexStateCurrentKey(identity)}.json`);
+}
+/**
+ * Publiziert einen Registry-Datensatz und macht ihn zum aktuellen Profil des
+ * Repo/Ref-Paares. Beide Dateien werden einzeln atomar ersetzt. Der Aufrufer
+ * serialisiert die kurze Sequenz mit {@link indexStateLockKey}.
+ *
+ * Misslingt ein Teil, werden der neue Datensatz, der current-Pointer und ein
+ * passender Legacy-Fallback invalidiert. Damit kann ein neuer Lauf nie einen
+ * alten `completed`-Hinweis gesund aussehen lassen.
+ */
+export async function writeIndexState(stateRoot, state, options = {}) {
+    const recordTarget = indexStateRecordPath(stateRoot, state);
+    const serializedState = serializeRegistryState(state);
+    if (serializedState === null) {
+        const error = new Error("Registry index states require a valid generation-bound state.");
+        const invalidated = await invalidateAfterFailure(stateRoot, state, "unconditional", options);
+        return failedWrite(recordTarget, error, invalidated);
+    }
+    try {
+        await atomicWrite(recordTarget, serializedState, options.assertOwnership);
+    }
+    catch (error) {
+        const invalidated = await invalidateAfterFailure(stateRoot, state, "unconditional", options);
+        return failedWrite(recordTarget, error, invalidated);
+    }
+    const pointerTarget = indexStateCurrentPath(stateRoot, state);
+    const pointer = currentPointerFor(state);
+    try {
+        await atomicWrite(pointerTarget, `${JSON.stringify(pointer, null, 2)}\n`, options.assertOwnership);
+        return { ok: true, path: recordTarget };
+    }
+    catch (error) {
+        const invalidated = await invalidateAfterFailure(stateRoot, state, "unconditional", options);
+        return failedWrite(pointerTarget, error, invalidated);
+    }
+}
+/**
+ * Replaces exactly one `running` registry record while its generation still
+ * matches. The current pointer is deliberately not republished: if another
+ * profile became current while this run finished, a late terminal write may
+ * archive its own result but cannot steal `auto` routing back.
+ */
+export async function replaceRunningIndexState(stateRoot, terminalState, options = {}) {
+    const target = indexStateRecordPath(stateRoot, terminalState);
+    const current = await readExactRegistryRecord(target, terminalState);
+    if (current.kind === "absent") {
+        return { ok: true, path: target, superseded: true };
+    }
+    if (current.kind === "invalid") {
+        const invalidated = await invalidateAfterFailure(stateRoot, terminalState, "matching", options);
+        return {
+            ...failedWrite(target, new Error(current.message), invalidated),
+            superseded: false,
+        };
+    }
+    if (!isRunningStateFor(current.state, terminalState)) {
+        return { ok: true, path: target, superseded: true };
+    }
+    const serializedState = serializeRegistryState(terminalState);
+    if (serializedState === null) {
+        const error = new Error("Terminal registry states require the running generation identity.");
+        const invalidated = await invalidateAfterFailure(stateRoot, terminalState, "matching", options);
+        return { ...failedWrite(target, error, invalidated), superseded: false };
+    }
+    try {
+        await atomicWrite(target, serializedState, options.assertOwnership);
+        return { ok: true, path: target, superseded: false };
+    }
+    catch (error) {
+        const invalidated = await invalidateAfterFailure(stateRoot, terminalState, "matching", options);
+        return { ...failedWrite(target, error, invalidated), superseded: false };
+    }
+}
+function isRunningStateFor(current, terminal) {
+    return (current.outcome === "running" &&
+        terminal.outcome !== "running" &&
+        current.workspaceId === terminal.workspaceId &&
+        current.repoId === terminal.repoId &&
+        current.refId === terminal.refId &&
+        current.refName === terminal.refName &&
+        current.embedder === terminal.embedder &&
+        current.embeddingProfileId === terminal.embeddingProfileId &&
+        current.collection === terminal.collection &&
+        (current.storageBackend ?? "qdrant") === (terminal.storageBackend ?? "qdrant") &&
+        (current.storeUrl ?? current.qdrantUrl) === (terminal.storeUrl ?? terminal.qdrantUrl) &&
+        current.generationId !== undefined &&
+        current.generationId === terminal.generationId);
+}
+/**
+ * Compatibility reader for old callers. It returns a state only when exactly
+ * one current repo/ref state exists below this physical root; callers needing
+ * every context use {@link resolveIndexState}.
+ */
+export async function readIndexState(stateRoot) {
+    const registry = await readLocalRegistry(stateRoot);
+    if (registry.kind === "invalid")
+        return null;
+    const current = registry.entries.filter((entry) => entry.current);
+    return current.length === 1 ? (current[0]?.state ?? null) : null;
+}
+/** The parser remains public for legacy migration and focused tests. */
+export function parseIndexState(text) {
+    if (Buffer.byteLength(text, "utf8") > MAX_INDEX_STATE_FILE_BYTES)
+        return null;
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw))
+        return null;
+    const record = raw;
+    if (record["schemaVersion"] !== 1)
+        return null;
+    const embedder = record["embedder"];
+    if (embedder !== "service" && embedder !== "offline")
+        return null;
+    const outcome = record["outcome"];
+    if (outcome !== "running" &&
+        outcome !== "completed" &&
+        outcome !== "cancelled" &&
+        outcome !== "failed") {
+        return null;
+    }
+    const strings = [
+        "workspaceId",
+        "repoId",
+        "refId",
+        "refName",
+        "embeddingProfileId",
+        "collection",
+    ];
+    const values = {};
+    for (const key of strings) {
+        const value = record[key];
+        if (!isBoundedString(value))
+            return null;
+        values[key] = value;
+    }
+    const storage = parseStorageIdentity(record, true);
+    if (storage === null)
+        return null;
+    const generationId = record["generationId"];
+    if (generationId !== undefined && !isBoundedString(generationId))
+        return null;
+    const corpusRevisionFingerprint = record["corpusRevisionFingerprint"];
+    if (corpusRevisionFingerprint !== undefined &&
+        (typeof corpusRevisionFingerprint !== "string" ||
+            !/^[0-9a-f]{64}$/u.test(corpusRevisionFingerprint))) {
+        return null;
+    }
+    const indexedAt = record["indexedAt"];
+    const indexConfigFingerprint = record["indexConfigFingerprint"];
+    const lexicalTokenizerVersion = record["lexicalTokenizerVersion"];
+    if (indexedAt !== undefined &&
+        (typeof indexedAt !== "string" || !Number.isFinite(Date.parse(indexedAt))))
+        return null;
+    if (indexConfigFingerprint !== undefined &&
+        (typeof indexConfigFingerprint !== "string" || !/^[0-9a-f]{64}$/u.test(indexConfigFingerprint)))
+        return null;
+    if (lexicalTokenizerVersion !== undefined && !isBoundedString(lexicalTokenizerVersion))
+        return null;
+    return {
+        schemaVersion: 1,
+        workspaceId: values["workspaceId"],
+        repoId: values["repoId"],
+        refId: values["refId"],
+        refName: values["refName"],
+        embedder,
+        embeddingProfileId: values["embeddingProfileId"],
+        collection: values["collection"],
+        ...storage,
+        ...(generationId === undefined ? {} : { generationId }),
+        ...(corpusRevisionFingerprint === undefined ? {} : { corpusRevisionFingerprint }),
+        ...(indexedAt === undefined ? {} : { indexedAt }),
+        ...(indexConfigFingerprint === undefined ? {} : { indexConfigFingerprint }),
+        ...(lexicalTokenizerVersion === undefined ? {} : { lexicalTokenizerVersion }),
+        outcome,
+    };
+}
+/**
+ * Enumerates every bounded registry under the candidate physical roots.
+ * Roots are de-duplicated, records are not: one root can legitimately contain
+ * multiple repo IDs, refs and profiles.
+ */
+export async function resolveIndexState(candidateRoots, workspaceId, scope = {}) {
+    const collected = await collectScopedIndexStates(candidateRoots, workspaceId, scope);
+    collected.found.sort(compareFoundStates);
+    if (collected.diagnostics.length > 0) {
+        collected.diagnostics.sort((a, b) => compareText(a.path, b.path) || compareText(a.code, b.code));
+        return { kind: "invalid", diagnostics: collected.diagnostics, all: collected.found };
+    }
+    return resolveCollectedStates(collected.found);
+}
+async function collectScopedIndexStates(candidateRoots, workspaceId, scope) {
+    const selectedRepoIds = new Set(scope.repoIds ?? []);
+    const selectedRefs = new Set(scope.refs ?? []);
+    const seenRoots = new Set();
+    const found = [];
+    const diagnostics = [];
+    for (const candidateRoot of candidateRoots) {
+        const repoRoot = path.resolve(candidateRoot);
+        if (seenRoots.has(repoRoot))
+            continue;
+        seenRoots.add(repoRoot);
+        const registry = await readLocalRegistry(stateRootOf(repoRoot));
+        if (registry.kind === "invalid") {
+            diagnostics.push(...registry.diagnostics);
+            continue;
+        }
+        for (const entry of registry.entries) {
+            if (!stateMatchesScope(entry.state, workspaceId, selectedRepoIds, selectedRefs, scope))
+                continue;
+            found.push({ repoRoot, ...entry });
+        }
+    }
+    return { found, diagnostics };
+}
+function stateMatchesScope(state, workspaceId, selectedRepoIds, selectedRefs, scope) {
+    return (state.workspaceId === workspaceId &&
+        (scope.storageBackend === undefined ||
+            (state.storageBackend ?? "qdrant") === scope.storageBackend) &&
+        (scope.storeUrl === undefined || (state.storeUrl ?? state.qdrantUrl) === scope.storeUrl) &&
+        (selectedRepoIds.size === 0 || selectedRepoIds.has(state.repoId)) &&
+        (selectedRefs.size === 0 || selectedRefs.has(state.refId) || selectedRefs.has(state.refName)));
+}
+function resolveCollectedStates(found) {
+    if (found.length === 0)
+        return { kind: "none" };
+    const current = found.filter((entry) => entry.current);
+    if (current.length === 0) {
+        return {
+            kind: "invalid",
+            diagnostics: [
+                {
+                    code: "INDEX_STATE_CORRUPT",
+                    path: found[0]?.statePath ?? "(index-state registry)",
+                    message: "The selected registry states have no valid current pointer.",
+                },
+            ],
+            all: found,
+        };
+    }
+    const first = current[0];
+    if (current.some((entry) => entry.state.embedder !== first.state.embedder)) {
+        return { kind: "ambiguous", found: current, all: found };
+    }
+    return { kind: "resolved", embedder: first.state.embedder, found: first, current, all: found };
+}
+async function readLocalRegistry(stateRoot) {
+    const recordsDirectory = path.join(stateRoot, INDEX_STATE_REGISTRY_DIR, INDEX_STATE_RECORDS_DIR);
+    const currentDirectory = path.join(stateRoot, INDEX_STATE_REGISTRY_DIR, INDEX_STATE_CURRENT_DIR);
+    const recordsListing = await listRegistryFiles(recordsDirectory);
+    if (recordsListing.kind === "invalid")
+        return recordsListing;
+    const currentListing = await listRegistryFiles(currentDirectory);
+    if (currentListing.kind === "invalid")
+        return currentListing;
+    const recordRead = await readRegistryRecords(recordsListing.paths);
+    if (recordRead.kind === "invalid")
+        return recordRead;
+    const currentRead = await readCurrentPointers(currentListing.paths, recordRead.value);
+    if (currentRead.kind === "invalid")
+        return currentRead;
+    const missingPointer = firstRecordWithoutCurrent(recordRead.value, currentRead.value);
+    if (missingPointer !== null)
+        return missingPointer;
+    const entries = registryEntries(recordRead.value, currentRead.value);
+    const legacyMerge = await mergeLegacyState(stateRoot, recordRead.value, currentRead.value, entries);
+    if (legacyMerge !== null)
+        return legacyMerge;
+    entries.sort((a, b) => compareStateEntries(a, b));
+    return { kind: "valid", entries };
+}
+async function readRegistryRecords(paths) {
+    const records = new Map();
+    for (const recordPath of paths) {
+        const read = await readBoundedRegularFile(recordPath);
+        if (read.kind === "absent") {
+            return invalidRegistry(recordPath, "Registry record disappeared while being read.");
+        }
+        if (read.kind === "invalid")
+            return invalidFileRead(recordPath, read);
+        const state = parseIndexState(read.text);
+        if (state === null || state.generationId === undefined) {
+            return invalidRegistry(recordPath, "Registry record is invalid or has no generation.");
+        }
+        const key = indexStateRecordKey(state);
+        if (path.basename(recordPath) !== `${key}.json`) {
+            return invalidRegistry(recordPath, "Registry filename does not match the canonical identity.");
+        }
+        records.set(key, { state, statePath: recordPath });
+    }
+    return { kind: "valid", value: records };
+}
+async function readCurrentPointers(paths, records) {
+    const currentByGroup = new Map();
+    for (const pointerPath of paths) {
+        const read = await readBoundedRegularFile(pointerPath);
+        if (read.kind === "absent") {
+            return invalidRegistry(pointerPath, "Current pointer disappeared while being read.");
+        }
+        if (read.kind === "invalid")
+            return invalidFileRead(pointerPath, read);
+        const parsed = validateCurrentPointer(pointerPath, read.text, records, currentByGroup);
+        if (parsed.kind === "invalid")
+            return parsed;
+        currentByGroup.set(parsed.value.currentKey, parsed.value.recordKey);
+    }
+    return { kind: "valid", value: currentByGroup };
+}
+function validateCurrentPointer(pointerPath, text, records, currentByGroup) {
+    const pointer = parseCurrentPointer(text);
+    if (pointer === null)
+        return invalidRegistry(pointerPath, "Current pointer is invalid.");
+    const currentKey = indexStateCurrentKey(pointer);
+    if (path.basename(pointerPath) !== `${currentKey}.json`) {
+        return invalidRegistry(pointerPath, "Pointer filename does not match the repository/ref identity.");
+    }
+    const pointed = records.get(pointer.recordKey);
+    if (pointed === undefined || !pointerMatchesState(pointer, pointed.state)) {
+        return invalidRegistry(pointerPath, "Current pointer does not reference the same profile- and generation-bound record.");
+    }
+    if (currentByGroup.has(currentKey)) {
+        return invalidRegistry(pointerPath, "Repository/ref has more than one current pointer.");
+    }
+    return { kind: "valid", value: { currentKey, recordKey: pointer.recordKey } };
+}
+function firstRecordWithoutCurrent(records, currentByGroup) {
+    for (const { state, statePath } of records.values()) {
+        if (!currentByGroup.has(indexStateCurrentKey(state))) {
+            return invalidRegistry(statePath, "Registry record belongs to a repository/ref without a current pointer.");
+        }
+    }
+    return null;
+}
+function registryEntries(records, currentByGroup) {
+    return [...records.entries()].map(([recordKey, { state, statePath }]) => ({
+        state,
+        statePath,
+        source: "registry",
+        current: currentByGroup.get(indexStateCurrentKey(state)) === recordKey,
+    }));
+}
+async function mergeLegacyState(stateRoot, records, currentByGroup, entries) {
+    const legacyPath = indexStatePath(stateRoot);
+    const legacyRead = await readBoundedRegularFile(legacyPath);
+    if (legacyRead.kind === "absent")
+        return null;
+    if (legacyRead.kind === "invalid")
+        return invalidFileRead(legacyPath, legacyRead);
+    const legacyState = parseIndexState(legacyRead.text);
+    if (legacyState === null) {
+        return invalidRegistry(legacyPath, "Legacy index state is invalid.");
+    }
+    if (records.has(indexStateRecordKey(legacyState)))
+        return null;
+    entries.push({
+        state: legacyState,
+        statePath: legacyPath,
+        source: "legacy",
+        current: !currentByGroup.has(indexStateCurrentKey(legacyState)),
+    });
+    return null;
+}
+async function listRegistryFiles(directory) {
+    try {
+        const information = await lstat(directory);
+        if (!information.isDirectory()) {
+            return {
+                kind: "invalid",
+                diagnostics: [
+                    diagnostic("INDEX_STATE_CORRUPT", directory, "Registry directory is not a regular local directory."),
+                ],
+            };
+        }
+    }
+    catch (error) {
+        if (isNotFound(error))
+            return { kind: "valid", paths: [] };
+        return {
+            kind: "invalid",
+            diagnostics: [
+                diagnostic("INDEX_STATE_IO", directory, `Cannot inspect registry: ${errorText(error)}`),
+            ],
+        };
+    }
+    let handle;
+    try {
+        handle = await opendir(directory);
+    }
+    catch (error) {
+        if (isNotFound(error))
+            return { kind: "valid", paths: [] };
+        return {
+            kind: "invalid",
+            diagnostics: [
+                diagnostic("INDEX_STATE_IO", directory, `Cannot read registry: ${errorText(error)}`),
+            ],
+        };
+    }
+    const names = [];
+    try {
+        for await (const entry of handle) {
+            names.push(entry.name);
+            if (names.length > MAX_INDEX_STATE_REGISTRY_ENTRIES) {
+                return {
+                    kind: "invalid",
+                    diagnostics: [
+                        diagnostic("INDEX_STATE_UNBOUNDED", directory, `Registry contains more than ${String(MAX_INDEX_STATE_REGISTRY_ENTRIES)} Eintraege.`),
+                    ],
+                };
+            }
+            if (TEMP_FILE_PATTERN.test(entry.name) && entry.isFile())
+                continue;
+            if (!HASH_FILE_PATTERN.test(entry.name) || !entry.isFile()) {
+                return {
+                    kind: "invalid",
+                    diagnostics: [
+                        diagnostic("INDEX_STATE_CORRUPT", path.join(directory, entry.name), "Registry accepts only regular JSON records with canonical filenames."),
+                    ],
+                };
+            }
+        }
+    }
+    catch (error) {
+        return {
+            kind: "invalid",
+            diagnostics: [
+                diagnostic("INDEX_STATE_IO", directory, `Registry read failed: ${errorText(error)}`),
+            ],
+        };
+    }
+    finally {
+        await handle.close().catch(() => undefined);
+    }
+    return {
+        kind: "valid",
+        paths: names
+            .filter((name) => HASH_FILE_PATTERN.test(name))
+            .sort(compareText)
+            .map((name) => path.join(directory, name)),
+    };
+}
+async function readBoundedRegularFile(filePath) {
+    try {
+        const information = await lstat(filePath);
+        if (!information.isFile()) {
+            return { kind: "invalid", reason: "not_regular", message: "Path is not a regular file." };
+        }
+        if (information.size > MAX_INDEX_STATE_FILE_BYTES) {
+            return {
+                kind: "invalid",
+                reason: "oversized",
+                message: `File exceeds ${String(MAX_INDEX_STATE_FILE_BYTES)} Bytes.`,
+            };
+        }
+    }
+    catch (error) {
+        if (isNotFound(error))
+            return { kind: "absent" };
+        return { kind: "invalid", reason: "io", message: errorText(error) };
+    }
+    let handle;
+    try {
+        // `lstat` rejects an existing symlink; O_NOFOLLOW also closes the race in
+        // which that path is swapped between the check and open.
+        handle = await open(filePath, READ_ONLY_NO_FOLLOW);
+        const buffer = Buffer.alloc(MAX_INDEX_STATE_FILE_BYTES + 1);
+        let totalBytesRead = 0;
+        while (totalBytesRead < buffer.length) {
+            const { bytesRead } = await handle.read(buffer, totalBytesRead, buffer.length - totalBytesRead, totalBytesRead);
+            if (bytesRead === 0)
+                break;
+            totalBytesRead += bytesRead;
+        }
+        if (totalBytesRead > MAX_INDEX_STATE_FILE_BYTES) {
+            return {
+                kind: "invalid",
+                reason: "oversized",
+                message: `File exceeds ${String(MAX_INDEX_STATE_FILE_BYTES)} Bytes.`,
+            };
+        }
+        return { kind: "valid", text: buffer.subarray(0, totalBytesRead).toString("utf8") };
+    }
+    catch (error) {
+        if (isNotFound(error))
+            return { kind: "absent" };
+        return { kind: "invalid", reason: "io", message: errorText(error) };
+    }
+    finally {
+        await handle?.close().catch(() => undefined);
+    }
+}
+/** Embedded state identities must be canonical absolute local file URLs. */
+function isLocalStoreUrl(value) {
+    try {
+        const url = new URL(value);
+        return (url.protocol === "file:" &&
+            url.hostname === "" &&
+            url.search === "" &&
+            url.hash === "" &&
+            url.href === value &&
+            !url.pathname.includes("%00"));
+    }
+    catch {
+        return false;
+    }
+}
+function parseStorageIdentity(record, requireEndpoint) {
+    const backend = record["storageBackend"];
+    const storeUrl = record["storeUrl"];
+    const qdrantUrl = record["qdrantUrl"];
+    if (backend !== undefined && backend !== "qdrant" && backend !== "lancedb")
+        return null;
+    if (backend === "lancedb") {
+        if (!isBoundedString(storeUrl) || !isLocalStoreUrl(storeUrl))
+            return null;
+        if (qdrantUrl !== undefined)
+            return null;
+        return { storageBackend: "lancedb", storeUrl };
+    }
+    if (storeUrl !== undefined && (!isBoundedString(storeUrl) || storeUrl !== qdrantUrl))
+        return null;
+    if (requireEndpoint && !isBoundedString(qdrantUrl))
+        return null;
+    if (qdrantUrl !== undefined && !isBoundedString(qdrantUrl))
+        return null;
+    return {
+        ...(backend === undefined ? {} : { storageBackend: backend }),
+        ...(storeUrl === undefined ? {} : { storeUrl }),
+        ...(qdrantUrl === undefined ? {} : { qdrantUrl }),
+    };
+}
+function parseCurrentPointer(text) {
+    if (Buffer.byteLength(text, "utf8") > MAX_INDEX_STATE_FILE_BYTES)
+        return null;
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw))
+        return null;
+    const record = raw;
+    if (record["schemaVersion"] !== 1)
+        return null;
+    const storage = parseStorageIdentity(record, false);
+    if (storage === null)
+        return null;
+    const workspaceId = record["workspaceId"];
+    const repoId = record["repoId"];
+    const refId = record["refId"];
+    const embeddingProfileId = record["embeddingProfileId"];
+    const generationId = record["generationId"];
+    const recordKey = record["recordKey"];
+    if (!isBoundedString(workspaceId) ||
+        !isBoundedString(repoId) ||
+        !isBoundedString(refId) ||
+        !isBoundedString(embeddingProfileId) ||
+        !isBoundedString(generationId) ||
+        typeof recordKey !== "string" ||
+        !/^[0-9a-f]{64}$/u.test(recordKey)) {
+        return null;
+    }
+    return {
+        schemaVersion: 1,
+        ...storage,
+        workspaceId,
+        repoId,
+        refId,
+        embeddingProfileId,
+        generationId,
+        recordKey,
+    };
+}
+function currentPointerFor(state) {
+    if (state.generationId === undefined) {
+        throw new Error("A current pointer requires a generation id.");
+    }
+    return {
+        schemaVersion: 1,
+        workspaceId: state.workspaceId,
+        repoId: state.repoId,
+        refId: state.refId,
+        embeddingProfileId: state.embeddingProfileId,
+        generationId: state.generationId,
+        recordKey: indexStateRecordKey(state),
+        ...(state.storageBackend === "lancedb"
+            ? { storageBackend: "lancedb", storeUrl: state.storeUrl }
+            : {}),
+    };
+}
+function pointerMatchesState(pointer, state) {
+    return (pointer.workspaceId === state.workspaceId &&
+        pointer.repoId === state.repoId &&
+        pointer.refId === state.refId &&
+        pointer.embeddingProfileId === state.embeddingProfileId &&
+        pointer.generationId === state.generationId &&
+        pointer.recordKey === indexStateRecordKey(state) &&
+        indexStateCurrentKey(pointer) === indexStateCurrentKey(state));
+}
+async function readExactRegistryRecord(target, identity) {
+    const read = await readBoundedRegularFile(target);
+    if (read.kind === "absent")
+        return read;
+    if (read.kind === "invalid")
+        return { kind: "invalid", message: read.message };
+    const state = parseIndexState(read.text);
+    if (state === null ||
+        state.generationId === undefined ||
+        indexStateRecordKey(state) !== indexStateRecordKey(identity)) {
+        return { kind: "invalid", message: "Registry record does not match its key." };
+    }
+    return { kind: "valid", state };
+}
+async function atomicWrite(target, text, assertOwnership) {
+    await mkdir(path.dirname(target), { recursive: true, mode: 0o700 });
+    const temporary = `${target}.${randomUUID()}.tmp`;
+    try {
+        await writeFile(temporary, text, { encoding: "utf8", flag: "wx", mode: 0o600 });
+        await assertOwnership?.();
+        await rename(temporary, target);
+    }
+    catch (error) {
+        await rm(temporary, { force: true }).catch(() => undefined);
+        throw error;
+    }
+}
+function serializeRegistryState(state) {
+    if (state.generationId === undefined)
+        return null;
+    const text = `${JSON.stringify(state, null, 2)}\n`;
+    const parsed = parseIndexState(text);
+    if (parsed === null || parsed.generationId === undefined)
+        return null;
+    return text;
+}
+async function invalidateAfterFailure(stateRoot, state, pointerInvalidation, options) {
+    if (options.assertOwnership !== undefined) {
+        try {
+            // Never let a writer that already lost its lease remove a successor's
+            // record or pointer. The surviving running marker remains fail-closed.
+            await options.assertOwnership();
+        }
+        catch (error) {
+            return { ok: false, error };
+        }
+    }
+    return invalidatePublication(stateRoot, state, pointerInvalidation);
+}
+async function invalidatePublication(stateRoot, state, pointerInvalidation) {
+    const errors = [];
+    await removeAndCollect(indexStateRecordPath(stateRoot, state), errors);
+    await invalidateCurrentPointer(stateRoot, state, pointerInvalidation, errors);
+    await invalidateLegacyFallback(stateRoot, state, pointerInvalidation, errors);
+    return errors.length === 0 ? { ok: true } : { ok: false, error: errors[0] };
+}
+async function invalidateCurrentPointer(stateRoot, state, pointerInvalidation, errors) {
+    const pointerPath = indexStateCurrentPath(stateRoot, state);
+    if (pointerInvalidation === "unconditional") {
+        await removeAndCollect(pointerPath, errors);
+        return;
+    }
+    const pointerRead = await readBoundedRegularFile(pointerPath);
+    if (pointerRead.kind === "invalid") {
+        await removeAndCollect(pointerPath, errors);
+        return;
+    }
+    if (pointerRead.kind !== "valid")
+        return;
+    const pointer = parseCurrentPointer(pointerRead.text);
+    if (pointer === null || pointerIdentifiesState(pointer, state)) {
+        await removeAndCollect(pointerPath, errors);
+    }
+}
+function pointerIdentifiesState(pointer, state) {
+    return (pointer.recordKey === indexStateRecordKey(state) && pointer.generationId === state.generationId);
+}
+async function invalidateLegacyFallback(stateRoot, state, pointerInvalidation, errors) {
+    const legacyPath = indexStatePath(stateRoot);
+    const legacyRead = await readBoundedRegularFile(legacyPath);
+    if (legacyRead.kind !== "valid")
+        return;
+    const legacy = parseIndexState(legacyRead.text);
+    if (legacy !== null && legacyMustBeInvalidated(legacy, state, pointerInvalidation)) {
+        await removeAndCollect(legacyPath, errors);
+    }
+}
+function legacyMustBeInvalidated(legacy, state, pointerInvalidation) {
+    const sameGroup = indexStateCurrentKey(legacy) === indexStateCurrentKey(state);
+    return (sameGroup &&
+        (pointerInvalidation === "unconditional" ||
+            legacy.embeddingProfileId === state.embeddingProfileId));
+}
+async function removeAndCollect(target, errors) {
+    try {
+        await rm(target, { force: true });
+    }
+    catch (error) {
+        errors.push(error);
+    }
+}
+function failedWrite(target, error, invalidated) {
+    return {
+        ok: false,
+        error,
+        path: target,
+        previousStateInvalidated: invalidated.ok,
+        ...(invalidated.error === undefined ? {} : { invalidationError: invalidated.error }),
+    };
+}
+function invalidFileRead(filePath, read) {
+    return {
+        kind: "invalid",
+        diagnostics: [
+            diagnostic(read.reason === "oversized"
+                ? "INDEX_STATE_OVERSIZED"
+                : read.reason === "io"
+                    ? "INDEX_STATE_IO"
+                    : "INDEX_STATE_CORRUPT", filePath, read.message),
+        ],
+    };
+}
+function invalidRegistry(filePath, message) {
+    return {
+        kind: "invalid",
+        diagnostics: [diagnostic("INDEX_STATE_CORRUPT", filePath, message)],
+    };
+}
+function diagnostic(code, filePath, message) {
+    return { code, path: filePath, message };
+}
+function isBoundedString(value) {
+    return (typeof value === "string" && value.length > 0 && value.length <= MAX_INDEX_STATE_FIELD_LENGTH);
+}
+function hashCanonical(parts) {
+    return createHash("sha256").update(JSON.stringify(parts), "utf8").digest("hex");
+}
+function compareFoundStates(left, right) {
+    return compareText(left.repoRoot, right.repoRoot) || compareStateEntries(left, right);
+}
+function compareStateEntries(left, right) {
+    return (compareText(left.state.repoId, right.state.repoId) ||
+        compareText(left.state.refId, right.state.refId) ||
+        compareText(left.state.embeddingProfileId, right.state.embeddingProfileId) ||
+        compareText(left.statePath, right.statePath));
+}
+function compareText(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+function isNotFound(error) {
+    return (typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        error.code === "ENOENT");
+}
+function errorText(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+//# sourceMappingURL=index-state.js.map