akm-cli 0.9.16-alpha.1 → 0.9.16

package/dist/setup/semantic-assets.js

@@ -78,12 +78,12 @@ export async function prepareSemanticSearchAssets(config) {
             p.log.info("sqlite-vec is available for fast vector search.");
         }
         else {
-            p.log.info("sqlite-vec is not available. Semantic search will stay unavailable (keyword search still works) until the optional extension is installed.");
+            p.log.info("sqlite-vec is not available. Semantic search will use the JS fallback until the optional extension is installed.");
         }
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
-        p.log.warn(`Could not open the local database or check for sqlite-vec. Semantic search will stay unavailable. (${message})\n` +
+        p.log.warn(`Could not open the local database or check for sqlite-vec. Semantic search will use the JS fallback. (${message})\n` +
             "Check file permissions and available disk space in the cache directory, or run `akm index --full --verbose` to diagnose.");
     }
     finally {

package/dist/setup/setup.js

@@ -205,8 +205,8 @@ export function rebaseSetupChanges(original, desired, latest, pathParts = []) {
     }
     return result;
 }
-async function saveSetupConfig(original, desired, precommit) {
-    const result = await mutateConfigWithPrecommit((latest) => rebaseSetupChanges(original, desired, latest), precommit);
+async function saveSetupConfig(original, desired, precommit, options) {
+    const result = await mutateConfigWithPrecommit((latest) => rebaseSetupChanges(original, desired, latest), precommit, options);
     return { config: result.config, precommit: result.precommit };
 }
 /** Registry-managed bundles are not editable through setup's source picker. */
@@ -572,7 +572,7 @@ export async function runSetupWizard(opts) {
     const { config: savedConfig } = await saveSetupConfig(current, finalConfig, async () => {
         if (!opts?.noInit)
             await akmInit({ dir: stashDir, setDefault: true, persistConfig: false });
-    });
+    }, { persistTopLevelKeys: ["semanticSearchMode"] });
     // After config persistence, the task step reviews the plan and asks one
     // explicit confirmation before changing task files or scheduler state.
     // Non-interactive setup paths never reach this interactive-only step.

package/dist/setup/steps/connection.js

@@ -89,9 +89,8 @@ export async function stepOllama(current) {
             "  • qwen3-embedding-0.6b  — fast and lightweight (ollama pull qwen3-embedding-0.6b)",
             "  • qwen3-embedding-4b    — higher quality (ollama pull qwen3-embedding-4b)",
             "",
-            "akm index probes Ollama for this model's own context window and sends it as",
-            "num_ctx automatically — no config needed. To override, set",
-            "embedding.ollamaOptions.num_ctx explicitly.",
+            "For long documents (wiki pages, large files), set context length to avoid 400 errors:",
+            "  akm config set embedding.contextLength 8192",
         ].join("\n"), "Embedding tips");
     }
     // else: undefined → use built-in local

package/dist/setup/steps/tasks.js

@@ -8,9 +8,11 @@ import path from "node:path";
 import { parse as yamlParse, stringify as yamlStringify } from "yaml";
 import * as p from "../../cli/clack.js";
 import { akmTasksSync } from "../../commands/tasks/tasks.js";
-import { loadConfig } from "../../core/config/config.js";
+import { makeBundleRef } from "../../core/asset/asset-ref.js";
+import { loadConfig, mutateConfig } from "../../core/config/config.js";
 import { UsageError } from "../../core/errors.js";
 import { commitWriteTargetBoundary, deleteAssetFromSource, prepareWriteTargetForMutation, resolveWriteTarget, writeAssetToSource, } from "../../core/write-source.js";
+import { schedulerActivationSourceId, schedulerActivations } from "../../tasks/activation-config.js";
 import { backendNameForPlatform } from "../../tasks/backends/index.js";
 import { listEmbeddedTasks } from "../../tasks/embedded.js";
 import { parseSchedule } from "../../tasks/schedule.js";
@@ -71,34 +73,13 @@ export function detectServerDefault() {
 function normaliseTaskIdForMatch(raw) {
     return raw.trim().replace(/\.(yml|md)$/, "");
 }
-/**
- * Toggle a task source v4 file's enabled state via a full parse/render
- * round-trip (setup's own edits are infrequent and not comment-preservation-
- * sensitive, unlike `commands/tasks/tasks.ts`'s `setEnabledInYaml` line
- * splice). Broadcasts `enabled` across every `schedule[]` entry — the
- * closest v4 equivalent of v3's single document-level flag. `src` no longer
- * accepts a task v3 file at all (P4 §3.2) — `listSetupTaskDefinitions` below
- * already fails closed on one before this function is ever reached, so
- * there is no legacy `akm.enabled` shape left to handle here.
- */
-function setTaskEnabledInYaml(yaml, enabled) {
-    const document = yamlParse(yaml);
-    const schedule = document.schedule;
-    if (typeof schedule === "string") {
-        document.schedule = [{ cron: schedule, enabled }];
-    }
-    else if (Array.isArray(schedule) && schedule.length > 0) {
-        document.schedule = schedule.map((entry) => entry && typeof entry === "object" && !Array.isArray(entry) ? { ...entry, enabled } : entry);
-    }
-    else {
-        throw new UsageError("Task source v4 must declare a schedule before setup can change enabled state.");
-    }
-    return yamlStringify(document);
-}
 export function listSetupTaskDefinitions() {
     const config = loadConfig();
     const target = resolveWriteTarget(config, config.defaultBundle, { requireWritable: false });
     const taskDir = path.join(target.source.path, "tasks");
+    const enabledRefs = new Set(schedulerActivations(config)
+        .filter((activation) => activation.kind === "task")
+        .map((activation) => activation.ref));
     if (!fs.existsSync(taskDir))
         return [];
     const tasks = [];
@@ -121,10 +102,7 @@ export function listSetupTaskDefinitions() {
                 id,
                 schedule: schedules[0],
                 schedules: Object.freeze(schedules),
-                // task source v4 has no document-level enabled (P4-N6) — a task is
-                // considered enabled for review purposes when at least one of its
-                // schedule bindings will actually fire.
-                enabled: document.schedule.some((entry) => entry.enabled),
+                enabled: enabledRefs.has(makeBundleRef(target.source.name, `tasks/${id}`)),
                 ...(document.description !== undefined ? { description: document.description } : {}),
             });
         }
@@ -147,11 +125,11 @@ export async function prepareSetupTaskDefinitions(tasks, deps = {}) {
         const original = fs.existsSync(filePath) ? fs.readFileSync(filePath, "utf8") : undefined;
         let yaml;
         if (original !== undefined) {
-            yaml = setTaskEnabledInYaml(original, plan.enabled);
+            yaml = original;
         }
         else {
             const document = yamlParse(plan.task.yaml);
-            document.schedule = plan.enabled ? plan.schedule : [{ cron: plan.schedule, enabled: false }];
+            document.schedule = plan.schedule;
             yaml = yamlStringify(document);
         }
         const parsed = parseTaskSource({ yaml, filePath, workspaceRoot: target.source.path });
@@ -161,8 +139,6 @@ export async function prepareSetupTaskDefinitions(tasks, deps = {}) {
         return { filePath, original, yaml, ref: { type: "task", name: plan.task.id } };
     });
     const changed = prepared.filter((entry) => entry.original !== entry.yaml);
-    if (changed.length === 0)
-        return 0;
     const attempted = [];
     try {
         for (const entry of changed) {
@@ -199,6 +175,23 @@ export async function prepareSetupTaskDefinitions(tasks, deps = {}) {
         }
         throw error;
     }
+    const selected = new Set(tasks.filter((plan) => plan.enabled).map((plan) => makeBundleRef(target.source.name, `tasks/${plan.task.id}`)));
+    const managed = new Set(tasks.map((plan) => makeBundleRef(target.source.name, `tasks/${plan.task.id}`)));
+    mutateConfig((current) => {
+        const existing = schedulerActivations(current);
+        const next = existing.filter((activation) => activation.kind !== "task" || !managed.has(activation.ref));
+        const sourceId = schedulerActivationSourceId(current, target.source.name);
+        if (selected.size > 0 && !sourceId) {
+            throw new UsageError(`Cannot activate setup tasks from disabled bundle ${JSON.stringify(target.source.name)}.`);
+        }
+        for (const ref of selected) {
+            next.push({ kind: "task", ref, sourceId: sourceId });
+        }
+        next.sort((left, right) => left.ref.localeCompare(right.ref) || left.kind.localeCompare(right.kind));
+        if (JSON.stringify(existing) === JSON.stringify(next))
+            return current;
+        return { ...current, scheduler: { ...current.scheduler, enabled: next } };
+    });
     return changed.length;
 }
 const DEFAULT_SCHEDULED_TASKS_DEPS = {
@@ -212,9 +205,9 @@ export async function stepScheduledTasks(deps = DEFAULT_SCHEDULED_TASKS_DEPS, op
         return;
     }
     // ALL templates are offered, including ships-disabled ones (e.g. the
-    // manual-recovery catchup task): an unselected template is still PREPARED
-    // with `enabled: false`, so its YAML exists for `akm task run <id>` while
-    // nothing lands in the scheduler uncommented. Filtering on `task.enabled`
+    // manual-recovery catchup task): an unselected template is still PREPARED,
+    // so its YAML exists for `akm task run <id>` while its ref remains absent
+    // from local scheduler activation. Filtering on `task.enabled`
     // here would make ships-disabled templates invisible and unpreparable.
     const embedded = listEmbeddedTasks();
     if (embedded.length === 0)

package/dist/sources/providers/git-install.js

@@ -8,7 +8,7 @@ import path from "node:path";
 import { isWithin } from "../../core/common.js";
 import { UsageError } from "../../core/errors.js";
 import { getRegistryCacheDir } from "../../core/paths.js";
-import { parseRegistryRef, resolveRegistryArtifact, validateGitRef, validateGitUrl } from "../../registry/resolve.js";
+import { gitCredentialEnvironment, parseRegistryRef, resolveRegistryArtifact, validateGitRef, validateGitUrl, } from "../../registry/resolve.js";
 import { applyAkmIncludeConfig, buildInstallCacheDir, detectStashRoot, isDirectory } from "./provider-utils.js";
 /**
  * Shared subprocess wrapper for `git` invocations. Disables git's interactive
@@ -22,13 +22,16 @@ export function runGit(args, options) {
     });
 }
 /** Fetch and classify the current branch against its upstream without changing the worktree. */
-export function inspectGitUpstream(repoDir) {
+export function inspectGitUpstream(repoDir, credential) {
     const remotes = runGit(["-C", repoDir, "remote"]);
     if (remotes.status !== 0)
         throw new UsageError(`Cannot inspect Git remotes at ${repoDir}: ${remotes.stderr.trim()}`);
     if (!remotes.stdout.trim())
         return { hasRemote: false, ahead: 0, behind: 0 };
-    const fetch = runGit(["-C", repoDir, "fetch", "--prune"], { timeout: 120_000 });
+    const fetch = runGit(["-C", repoDir, "fetch", "--prune"], {
+        timeout: 120_000,
+        env: gitCredentialEnvironment(credential),
+    });
     if (fetch.status !== 0)
         throw new UsageError(`Cannot refresh Git target at ${repoDir}: ${fetch.stderr.trim()}`);
     const upstream = runGit(["-C", repoDir, "rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{u}"]);
@@ -160,10 +163,10 @@ async function doSyncGit(parsed, options) {
     validateGitUrl(parsed.url);
     if (parsed.requestedRef)
         validateGitRef(parsed.requestedRef);
-    const resolved = await resolveRegistryArtifact(parsed);
+    const resolved = await resolveRegistryArtifact(parsed, { gitCredential: options?.credential });
     const syncedAt = (options?.now ?? new Date()).toISOString();
     if (options?.writable && options.writableRoot) {
-        return syncExistingWritableCheckout(parsed, resolved, options.writableRoot, syncedAt, options.writableRequiredRoots);
+        return syncExistingWritableCheckout(parsed, resolved, options.writableRoot, syncedAt, options.writableRequiredRoots, options.credential);
     }
     const cacheRootDir = options?.cacheRootDir ?? getRegistryCacheDir();
     const cacheDir = buildInstallCacheDir(cacheRootDir, parsed.source, parsed.id, options?.writable ? "writable" : resolved.resolvedRevision);
@@ -178,7 +181,7 @@ async function doSyncGit(parsed, options) {
             if (installRoot !== provisionalBundleRoot) {
                 throw new UsageError("Writable Git installs do not support akm.include (package.json) filtered snapshots.");
             }
-            return syncExistingWritableCheckout(parsed, resolved, detectStashRoot(installRoot), syncedAt, options.writableRequiredRoots);
+            return syncExistingWritableCheckout(parsed, resolved, detectStashRoot(installRoot), syncedAt, options.writableRequiredRoots, options.credential);
         }
         try {
             if (options?.force) {
@@ -228,7 +231,10 @@ async function doSyncGit(parsed, options) {
             cloneArgs.push("--branch", parsed.requestedRef);
         }
         cloneArgs.push(parsed.url, cloneDir);
-        const cloneResult = runGit(cloneArgs, { timeout: 120_000 });
+        const cloneResult = runGit(cloneArgs, {
+            timeout: 120_000,
+            env: gitCredentialEnvironment(options?.credential),
+        });
         if (cloneResult.status !== 0) {
             throw new Error(classifyCloneFailure(parsed.url, cloneResult.stderr, cloneResult.error));
         }
@@ -292,7 +298,7 @@ async function doSyncGit(parsed, options) {
         syncedAt,
     };
 }
-export function syncExistingWritableCheckout(parsed, resolved, contentRoot, syncedAt, requiredRoots = []) {
+export function syncExistingWritableCheckout(parsed, resolved, contentRoot, syncedAt, requiredRoots = [], credential) {
     const root = path.resolve(contentRoot);
     const repoResult = runGit(["-C", root, "rev-parse", "--show-toplevel"]);
     if (repoResult.status !== 0 || !repoResult.stdout.trim()) {
@@ -324,7 +330,7 @@ export function syncExistingWritableCheckout(parsed, resolved, contentRoot, sync
     fetchArgs.push("origin");
     if (parsed.requestedRef)
         fetchArgs.push(parsed.requestedRef);
-    const fetch = runGit(fetchArgs, { timeout: 120_000 });
+    const fetch = runGit(fetchArgs, { timeout: 120_000, env: gitCredentialEnvironment(credential) });
     if (fetch.status !== 0) {
         throw new UsageError(`Writable Git install at ${root} could not fetch its expected origin; local work was preserved. ${fetch.stderr.trim()}`);
     }
@@ -403,7 +409,7 @@ export function syncExistingWritableCheckout(parsed, resolved, contentRoot, sync
         syncedAt,
     };
 }
-export function cloneRepo(cloneUrl, ref, destDir, writable = false) {
+export function cloneRepo(cloneUrl, ref, destDir, writable = false, credential) {
     // Stage the clone into a sibling temp dir so that a failed clone never
     // destroys a previously-valid destDir (e.g. when the remote is temporarily
     // unreachable and we have a valid cached copy).
@@ -414,7 +420,7 @@ export function cloneRepo(cloneUrl, ref, destDir, writable = false) {
     if (ref)
         args.push("--branch", ref);
     args.push(cloneUrl, tmpDir);
-    const result = runGit(args, { timeout: 120_000 });
+    const result = runGit(args, { timeout: 120_000, env: gitCredentialEnvironment(credential) });
     if (result.status !== 0) {
         // Clean up the (possibly partial) temp dir but leave destDir untouched.
         fs.rmSync(tmpDir, { recursive: true, force: true });

package/dist/sources/providers/git-provider.js

@@ -6,6 +6,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { akmAdapter } from "../../core/adapter/adapters/akm-adapter.js";
 import { stashDirNames } from "../../core/asset/asset-placement.js";
+import { resolveSecret } from "../../core/config/config.js";
 import { ConfigError, UsageError } from "../../core/errors.js";
 import { getRegistryIndexCacheDir } from "../../core/paths.js";
 import { validateGitUrl } from "../../registry/resolve.js";
@@ -41,7 +42,12 @@ export class GitSourceProvider {
         return this.#path;
     }
     async sync(options) {
-        await syncMirroredRepo(this.#config, { force: options?.force });
+        await syncMirroredRepo(this.#config, {
+            force: options?.force,
+            ...(this.#config.credential
+                ? { credential: resolveSecret(this.#config.credential, options?.secrets?.resolveSecret) }
+                : {}),
+        });
     }
 }
 /** Resolve the on-disk content directory for a configured git source. */
@@ -81,10 +87,10 @@ export async function ensureGitMirror(repo, cachePaths, options) {
             fs.mkdirSync(cachePaths.rootDir, { recursive: true });
             if (writable && fs.existsSync(path.join(cachePaths.repoDir, ".git"))) {
                 // Writable repo already cloned — pull instead of re-clone to preserve local changes
-                pullRepo(cachePaths.repoDir);
+                pullRepo(cachePaths.repoDir, options?.credential);
             }
             else {
-                cloneRepo(repo.cloneUrl, repo.ref, cachePaths.repoDir, writable);
+                cloneRepo(repo.cloneUrl, repo.ref, cachePaths.repoDir, writable, options?.credential);
             }
             // Touch index file to track freshness
             fs.writeFileSync(cachePaths.indexPath, "[]", { encoding: "utf8", mode: 0o600 });
@@ -106,6 +112,7 @@ export async function syncMirroredRepo(config, options) {
         requireRepoDir: true,
         writable: options?.writable ?? config.writable === true,
         force: options?.force,
+        credential: options?.credential,
     });
     const syncedAt = (options?.now ?? new Date()).toISOString();
     const contentDir = cachePaths.repoDir;
@@ -121,12 +128,12 @@ export async function syncMirroredRepo(config, options) {
         syncedAt,
     };
 }
-function pullRepo(repoDir) {
+function pullRepo(repoDir, credential) {
     const status = runGit(["-C", repoDir, "status", "--porcelain"]);
     if (status.status !== 0 || status.stdout.trim()) {
         throw new UsageError(`Writable Git source at ${repoDir} has uncommitted changes; refusing to update it.`);
     }
-    const relation = inspectGitUpstream(repoDir);
+    const relation = inspectGitUpstream(repoDir, credential);
     if (relation.behind > 0 && relation.upstream) {
         if (relation.ahead > 0) {
             throw new UsageError(`Writable Git source at ${repoDir} has unpushed commits; refusing to update it.`);

package/dist/sources/providers/git-stash.js

@@ -120,30 +120,44 @@ export function saveGitStash(name, message, writableOverride, options) {
     let managedContentRoot;
     if (name) {
         const config = loadConfig();
-        const stash = findGitStashByTarget(getSources(config), name);
+        const stash = findSyncStashByTarget(getSources(config), name);
         // NotFoundError (exit 1), not UsageError (exit 2): the argument is
         // well-formed, the bundle just isn't configured.
         if (!stash)
-            throw new NotFoundError(`No git bundle found with name "${name}"`, "SOURCE_NOT_FOUND");
-        if (stash.type !== "git") {
-            throw new UsageError(`Stash "${name}" is not a git stash (type: ${stash.type})`);
+            throw new NotFoundError(`No git-backed bundle found with name "${name}"`, "SOURCE_NOT_FOUND");
+        if (stash.enabled === false) {
+            throw new UsageError(`Bundle "${name}" is disabled and cannot be synced.`, "INVALID_FLAG_VALUE");
         }
-        const lockedRoot = lockContentRootFor(stash.name, stash.type);
-        if (lockedRoot) {
-            const topLevel = runGit(["-C", lockedRoot, "rev-parse", "--show-toplevel"]);
+        if (stash.type === "filesystem") {
+            if (!stash.path)
+                throw new UsageError(`Filesystem bundle "${name}" has no path configured.`);
+            const contentRoot = path.resolve(stash.path);
+            const topLevel = runGit(["-C", contentRoot, "rev-parse", "--show-toplevel"]);
             if (topLevel.status !== 0 || !topLevel.stdout.trim()) {
-                throw new UsageError(`Managed Git stash "${name}" is not a checkout at ${lockedRoot}`);
+                throw new UsageError(`Filesystem bundle "${name}" is not a Git working tree at ${contentRoot}.`);
             }
             repoDir = path.resolve(topLevel.stdout.trim());
-            managedContentRoot = path.resolve(lockedRoot);
+            managedContentRoot = contentRoot;
+            writable = stash.writable !== false;
         }
         else {
-            if (!stash.url)
-                throw new UsageError(`Stash "${name}" has no URL configured`);
-            const repo = parseGitRepoUrl(stash.url);
-            repoDir = getCachePaths(repo.canonicalUrl).repoDir;
+            const lockedRoot = lockContentRootFor(stash.name, stash.type);
+            if (lockedRoot) {
+                const topLevel = runGit(["-C", lockedRoot, "rev-parse", "--show-toplevel"]);
+                if (topLevel.status !== 0 || !topLevel.stdout.trim()) {
+                    throw new UsageError(`Managed Git stash "${name}" is not a checkout at ${lockedRoot}`);
+                }
+                repoDir = path.resolve(topLevel.stdout.trim());
+                managedContentRoot = path.resolve(lockedRoot);
+            }
+            else {
+                if (!stash.url)
+                    throw new UsageError(`Stash "${name}" has no URL configured`);
+                const repo = parseGitRepoUrl(stash.url);
+                repoDir = getCachePaths(repo.canonicalUrl).repoDir;
+            }
+            writable = stash.writable === true;
         }
-        writable = stash.writable === true;
     }
     else {
         // Honour an explicit primary-stash dir override (keeps the improve gate and
@@ -554,8 +568,16 @@ function createExactPathCommit(repoDir, options) {
         fs.rmSync(`${temporaryIndex}.lock`, { force: true });
     }
 }
-function findGitStashByTarget(stashes, target) {
-    return stashes.find((stash) => matchesGitStashTarget(stash, target));
+function findSyncStashByTarget(stashes, target) {
+    return stashes.find((stash) => {
+        if (stash.type === "git")
+            return matchesGitStashTarget(stash, target);
+        if (stash.type !== "filesystem")
+            return false;
+        if (stash.name === target || stash.path === target)
+            return true;
+        return stash.path !== undefined && path.resolve(stash.path) === path.resolve(target);
+    });
 }
 function matchesGitStashTarget(stash, target) {
     if (stash.type !== "git")

package/dist/sources/snapshot-fetchers/website-ingest.js

@@ -324,7 +324,7 @@ async function scrapeWebsiteToStash(startUrl, stashDir, options) {
 export async function fetchWebsiteMarkdownSnapshot(rawUrl, options) {
     const normalizedUrl = validateWebsiteInputUrl(rawUrl, { allowPrivateHosts: options?.allowPrivateHosts });
     const parsedUrl = new URL(normalizedUrl);
-    const allowPrivateHosts = await resolveAllowPrivateStartHost(parsedUrl, options?.allowPrivateHosts);
+    const allowPrivateHosts = await resolveAllowPrivateStartHost(parsedUrl, options?.allowPrivateHosts, options?.resolveHostname);
     const stashDir = resolveFetcherStashDir(options?.stashDir);
     const context = {
         stashDir: stashDir ?? "",
@@ -524,11 +524,11 @@ async function assertStartUrlAllowedByRobots(robots, start, rawStartUrl) {
  * before it ever reaches a guard, so this never extends trust to a host the
  * fetched content merely points at.
  */
-async function resolveAllowPrivateStartHost(start, requested) {
+async function resolveAllowPrivateStartHost(start, requested, resolveHostname) {
     if (requested)
         return true;
     try {
-        await assertResolvedHostAllowed(start.hostname);
+        await assertResolvedHostAllowed(start.hostname, { resolveHostname });
         return false;
     }
     catch {

package/dist/storage/repositories/embedding-salvage-repository.js

@@ -0,0 +1,184 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * `index.db` embedding salvage (#955) — a transient, self-emptying table
+ * that lets a full rebuild or an index-generation bump reuse vectors instead
+ * of re-embedding a corpus whose content did not change.
+ *
+ * Zero steady-state cost by design: this is NOT a second embedding cache.
+ * Rows are copied aside only at the moment they would otherwise be discarded
+ * wholesale — a full-index wipe (`persistDirRecords`) or a generation bump
+ * (`rebuildIncompatibleIndexGeneration`) — and are consumed by the very next
+ * embedding pass (`generateEmbeddingsForDb`). A pass that completes without
+ * abort or circuit-break purges whatever is left; an interrupted pass leaves
+ * the table for the next attempt to pick up.
+ *
+ * Reuse is keyed on `sha256(search_text)` plus the fingerprint the vector was
+ * generated under — a fingerprint mismatch or a single-byte content change
+ * both correctly fall through to a real provider call. `content_hash` is the
+ * PRIMARY KEY (not `(content_hash, fingerprint)`) so relabeling a whole
+ * generation's fingerprint after a canary "keep" verdict is one UPDATE, and a
+ * hash colliding across two discards simply keeps the most recent copy —
+ * salvage is a best-effort optimization, not a durable multi-generation
+ * archive.
+ */
+import { createHash } from "node:crypto";
+import { blobToEmbedding } from "./embeddings-repository.js";
+import { getMeta } from "./index-meta-repository.js";
+import { SQLITE_CHUNK_SIZE } from "./index-sql.js";
+/**
+ * Create the salvage table. Additive-only DDL: it carries no bearing on the
+ * `entries` generation fingerprint (`hasCanonicalEntrySchema`), so adding it
+ * does not require an index-generation bump.
+ */
+export function ensureEmbeddingSalvageTable(db) {
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS embedding_salvage (
+      content_hash TEXT PRIMARY KEY,
+      fingerprint  TEXT NOT NULL,
+      embedding    BLOB NOT NULL,
+      salvaged_at  TEXT NOT NULL
+    );
+  `);
+}
+/** The one hash function salvage writes and reuse lookups must agree on. */
+export function hashEmbeddableText(searchText) {
+    return createHash("sha256").update(searchText, "utf8").digest("hex");
+}
+function tableExists(db, name) {
+    return db.prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name=?").get(name) != null;
+}
+function tableHasColumn(db, table, column) {
+    const columns = db.prepare(`PRAGMA table_info(${table})`).all();
+    return columns.some((c) => c.name === column);
+}
+/**
+ * Copy every (hash of search_text, embedding) pair about to be discarded
+ * wholesale into `embedding_salvage`, tagged with the `embeddingFingerprint`
+ * the discarded vectors were generated under. The caller MUST run this
+ * inside the same transaction as the discard that follows it, so the copy
+ * and the delete commit or roll back together.
+ *
+ * Streams `entries JOIN embeddings` in id-ordered pages of
+ * {@link SQLITE_CHUNK_SIZE} instead of loading every row into memory before
+ * hashing anything — a full rebuild of a large stash otherwise held the
+ * entire corpus's search text and vectors in memory at once just to copy
+ * them aside (#955, field-report follow-up).
+ *
+ * A no-op (returns 0) when there is no stored `embeddingFingerprint` to tag
+ * rows with (nothing was ever verified against a provider, so there is
+ * nothing worth reusing later) or the generation being discarded predates
+ * the `entries.search_text` column or has no `embeddings` table at all — an
+ * older generation than that has nothing this can safely read.
+ */
+export function salvageEmbeddingsBeforeDiscard(db) {
+    const fingerprint = getMeta(db, "embeddingFingerprint");
+    if (!fingerprint)
+        return 0;
+    if (!tableExists(db, "entries") || !tableExists(db, "embeddings"))
+        return 0;
+    if (!tableHasColumn(db, "entries", "search_text"))
+        return 0;
+    const page = db.prepare("SELECT e.id AS id, e.search_text AS searchText, em.embedding AS embedding " +
+        "FROM entries e JOIN embeddings em ON em.id = e.id WHERE e.id > ? ORDER BY e.id LIMIT ?");
+    const insert = db.prepare("INSERT OR REPLACE INTO embedding_salvage (content_hash, fingerprint, embedding, salvaged_at) VALUES (?, ?, ?, ?)");
+    const salvagedAt = new Date().toISOString();
+    let lastId = 0;
+    let total = 0;
+    for (;;) {
+        const rows = page.all(lastId, SQLITE_CHUNK_SIZE);
+        if (rows.length === 0)
+            break;
+        for (const row of rows) {
+            insert.run(hashEmbeddableText(row.searchText), fingerprint, row.embedding, salvagedAt);
+        }
+        total += rows.length;
+        lastId = rows[rows.length - 1]?.id ?? lastId;
+        if (rows.length < SQLITE_CHUNK_SIZE)
+            break;
+    }
+    return total;
+}
+/**
+ * Remove every salvage row. Called after an embedding pass completes without
+ * abort or circuit-break (the salvaged generation has now either been reused
+ * or superseded), and by `--reembed` / a canary "rebuild" verdict (the
+ * salvaged vectors belong to a different model and are never reusable).
+ */
+export function purgeEmbeddingSalvage(db) {
+    db.exec("DELETE FROM embedding_salvage");
+}
+/**
+ * A canary "keep" verdict means the model did not actually change — only its
+ * fingerprint STRING did (e.g. a gateway rename). Salvage rows tagged with
+ * the old string are still valid vectors; rewrite them to the new string so
+ * they remain reusable instead of silently going stale.
+ */
+export function relabelEmbeddingSalvageFingerprint(db, fromFingerprint, toFingerprint) {
+    db.prepare("UPDATE embedding_salvage SET fingerprint = ? WHERE fingerprint = ?").run(toFingerprint, fromFingerprint);
+}
+/**
+ * Reuse salvaged vectors for `entries` whose `searchText` hash matches a
+ * salvage row tagged with the CURRENT `fingerprint` — never across
+ * fingerprints, and never when `search_text` differs by even one byte (the
+ * hash is exact-match only, by design). Matches are written via
+ * `writeReused` in chunks of {@link SQLITE_CHUNK_SIZE}, each its own
+ * transaction, mirroring the main pass's per-batch commit (#955) so an
+ * interruption partway through the reuse step keeps whatever already wrote.
+ *
+ * The steady state of every ordinary run is an EMPTY salvage table (nothing
+ * was just discarded), so this checks that first with one indexed lookup —
+ * `SELECT 1 ... LIMIT 1` — before hashing a single pending entry. Hashing
+ * every entry up front to look up a table that is empty 100% of the time
+ * outside a rebuild was pure wasted work on the common path (#955,
+ * field-report follow-up).
+ */
+export function reuseSalvagedEmbeddings(db, entries, fingerprint, writeReused) {
+    if (entries.length === 0)
+        return { reusedCount: 0, remaining: [] };
+    const anySalvageForFingerprint = db
+        .prepare("SELECT 1 FROM embedding_salvage WHERE fingerprint = ? LIMIT 1")
+        .get(fingerprint);
+    if (!anySalvageForFingerprint)
+        return { reusedCount: 0, remaining: [...entries] };
+    const hashes = entries.map((entry) => hashEmbeddableText(entry.searchText));
+    const salvageByHash = new Map();
+    const uniqueHashes = [...new Set(hashes)];
+    for (let offset = 0; offset < uniqueHashes.length; offset += SQLITE_CHUNK_SIZE) {
+        const chunk = uniqueHashes.slice(offset, offset + SQLITE_CHUNK_SIZE);
+        const placeholders = chunk.map(() => "?").join(",");
+        const rows = db
+            .prepare(`SELECT content_hash AS contentHash, embedding FROM embedding_salvage WHERE fingerprint = ? AND content_hash IN (${placeholders})`)
+            .all(fingerprint, ...chunk);
+        for (const row of rows)
+            salvageByHash.set(row.contentHash, row.embedding);
+    }
+    if (salvageByHash.size === 0)
+        return { reusedCount: 0, remaining: [...entries] };
+    let reusedCount = 0;
+    const remaining = [];
+    for (let offset = 0; offset < entries.length; offset += SQLITE_CHUNK_SIZE) {
+        const end = Math.min(offset + SQLITE_CHUNK_SIZE, entries.length);
+        const chunkMatches = [];
+        for (let i = offset; i < end; i++) {
+            const entry = entries[i];
+            const blob = salvageByHash.get(hashes[i]);
+            if (blob)
+                chunkMatches.push({ entry, blob });
+            else
+                remaining.push(entry);
+        }
+        if (chunkMatches.length === 0)
+            continue;
+        db.transaction(() => {
+            for (const { entry, blob } of chunkMatches) {
+                if (writeReused(entry, blobToEmbedding(blob)))
+                    reusedCount++;
+                else
+                    remaining.push(entry);
+            }
+        })();
+    }
+    return { reusedCount, remaining };
+}

package/dist/storage/repositories/index-connection.js

@@ -22,7 +22,7 @@ import { SQLITE_BUSY_TIMEOUT_MS } from "../sqlite-pragmas.js";
 import { openSqliteReadSnapshot, SqliteReadSnapshotUnavailableError } from "../sqlite-read-snapshot.js";
 import { CANONICAL_INDEX_DB_VERSION, classifyIndexGeneration, isCanonicalIndexGeneration } from "./index-entry-schema.js";
 import { ensureSchema } from "./index-schema.js";
-import { loadVecExtension } from "./index-vec-repository.js";
+import { loadVecExtension, warnIfVecMissing } from "./index-vec-repository.js";
 /**
  * Whether `error` is SQLite reporting on-disk corruption (`SQLITE_CORRUPT`,
  * "database disk image is malformed") rather than a permission, lock, or
@@ -54,6 +54,8 @@ export function openIndexDatabase(dbPath, options) {
             // ensureSchema from touching `index_meta.embeddingDim` at all.
             const resolvedDim = options?.embeddingDim ?? resolveConfiguredEmbeddingDim();
             ensureSchema(db, resolvedDim);
+            // Warn once at init if using JS fallback with many entries
+            warnIfVecMissing(db, { once: true });
         },
     };
     try {