akm-cli 0.9.5 → 0.9.6

package/dist/indexer/indexer.js

@@ -27,7 +27,6 @@ import { upsertUtilityScore } from "../storage/repositories/index-utility-reposi
 import { getEmbeddingCount, isVecAvailable, isVecFastPathReady, warnIfVecMissing, } from "../storage/repositories/index-vec-repository.js";
 import { assertIndexedWorkflowSourceIdentity, WorkflowSourceIdentityError } from "../workflows/source-files.js";
 import { deleteStoredGraph } from "./db/graph-db.js";
-import { withIndexWriterLease } from "./index-writer-lock.js";
 import { deriveEntryProvenance, deriveInstallations } from "./installations.js";
 import { indexedPathMatchesOwner, resolveAdapterConceptOwner, } from "./lookup/adapter-concept-owner.js";
 import { generateEmbeddingsForDb } from "./materialize-embeddings.js";
@@ -35,7 +34,6 @@ import { canUseIncrementalSkip, computeDirFingerprint, getCachedZeroRowDirState,
 import { isEnrichmentComplete, isWorkflowSkipWarning } from "./passes/metadata.js";
 import { drainDirDocuments } from "./scan/drain-dir.js";
 import { buildSearchText } from "./search/search-fields.js";
-import { clearSemanticStatus, deriveSemanticProviderFingerprint, writeSemanticStatus } from "./search/semantic-status.js";
 import { purgeOldUsageEvents } from "./usage/usage-events.js";
 import { walkStashFlatWithStatus } from "./walk/walker.js";
 function collectLoweringNotices(target, notices) {
@@ -265,27 +263,6 @@ async function runFinalizePhase(ctx, deferredUpdateTransaction) {
     const semanticEntryCount = getEmbeddableEntryCount(db);
     onProgress({ phase: "finalize", message: "Verifying semantic search state." });
     const verification = verifyIndexState(db, config, semanticEntryCount, embeddingResult);
-    const persistSemanticStatus = () => {
-        if (config.semanticSearchMode === "off") {
-            clearSemanticStatus();
-            return;
-        }
-        writeSemanticStatus({
-            status: verification.semanticStatus === "disabled" ? "pending" : verification.semanticStatus,
-            ...(embeddingResult.reason ? { reason: embeddingResult.reason } : {}),
-            ...(embeddingResult.message ? { message: embeddingResult.message } : {}),
-            providerFingerprint: deriveSemanticProviderFingerprint(config.embedding),
-            lastCheckedAt: new Date().toISOString(),
-            entryCount: verification.entryCount,
-            embeddingCount: verification.embeddingCount,
-        });
-    };
-    if (deferredUpdateTransaction) {
-        deferredUpdateTransaction.afterCommit = persistSemanticStatus;
-    }
-    else {
-        persistSemanticStatus();
-    }
     onProgress({ phase: "verify", message: verification.message });
     // Store verification result and totalEntries on ctx for the caller to use
     ctx.verification = verification;
@@ -492,20 +469,7 @@ async function akmIndexReal(options) {
             "Pass `akm index --clean --dry-run`, or drop `--dry-run` to run a real index.", "INVALID_FLAG_VALUE", "Run `akm index --clean --dry-run` to preview, or `akm index --clean` to apply.");
     }
     const requestedAt = Date.now();
-    let acquiredAt = requestedAt;
-    return withIndexWriterLease({
-        purpose: "akm-index",
-        signal: options?.signal,
-        onWait: ({ waitedMs }) => {
-            options?.onProgress?.({
-                phase: "preflight",
-                message: `Waiting for index writer lease (${Math.round(waitedMs / 1000)}s elapsed).`,
-            });
-        },
-        onAcquired: ({ waitedMs }) => {
-            acquiredAt = requestedAt + waitedMs;
-        },
-    }, async () => {
+    return (async () => {
         const stashDir = options.stashDir;
         const onProgress = options?.onProgress ?? (() => { });
         const signal = options?.signal;
@@ -644,7 +608,6 @@ async function akmIndexReal(options) {
                     finalizeMs: timing.tFinalizeEnd - timing.tFinalizeStart,
                     cleanMs: clean ? cleanEnd - cleanStart : 0,
                     preflightMs: timing.t0 - requestedAt,
-                    leaseWaitMs: acquiredAt - requestedAt,
                     sourceCacheMs: sourceCacheEnd - sourceCacheStart,
                     endToEndMs: Date.now() - requestedAt,
                 },
@@ -658,7 +621,7 @@ async function akmIndexReal(options) {
             if (!borrowedUpdateDb)
                 closeDatabase(db);
         }
-    });
+    })();
 }
 function buildIndexedSourceOwners(sources) {
     const installations = deriveInstallations([...sources]);

package/dist/indexer/materialize-embeddings.js

@@ -3,11 +3,25 @@
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import { isVerbose, warn, warnVerbose } from "../core/warn.js";
 import { embedBatch } from "../llm/embedder.js";
-import { estimateTokenCount } from "../llm/embedders/remote.js";
+import { DETERMINISTIC_EMBED_MODEL_ID, isDeterministicEmbedEnabled } from "../llm/embedders/deterministic.js";
+import { DEFAULT_LOCAL_MODEL } from "../llm/embedders/local.js";
+import { buildTokenBoundedBatches, DEFAULT_REMOTE_BATCH_SIZE, DEFAULT_TOKEN_BUDGET, estimateTokenCount, hasRemoteEndpoint, } from "../llm/embedders/remote.js";
 import { getEmbeddableEntryCount } from "../storage/repositories/index-entries-repository.js";
 import { deleteMeta, getMeta, setMeta } from "../storage/repositories/index-meta-repository.js";
-import { getAllEntriesForEmbedding, getEmbeddingCount, isVecAvailable, isVecFastPathComplete, isVecFastPathReady, purgeEmbeddings, setVecFastPathReady, upsertEmbedding, } from "../storage/repositories/index-vec-repository.js";
-import { classifySemanticFailure, clearSemanticStatus, deriveSemanticProviderFingerprint, writeSemanticStatus, } from "./search/semantic-status.js";
+import { getAllEntriesForEmbedding, getEmbeddingCount, isVecFastPathComplete, isVecFastPathReady, purgeEmbeddings, setVecFastPathReady, upsertEmbedding, } from "../storage/repositories/index-vec-repository.js";
+/** Identifies the embedding provider+model+dimension a stored vector was generated with. */
+export function deriveSemanticProviderFingerprint(embedding) {
+    if (isDeterministicEmbedEnabled()) {
+        return `deterministic:${DETERMINISTIC_EMBED_MODEL_ID}`;
+    }
+    if (embedding?.endpoint) {
+        // Fingerprint keys on vector identity only (model + dimension). The endpoint
+        // is transport/routing and has no bearing on vector compatibility, so moving
+        // the same model+dimension to a different host must not force a full re-embed.
+        return `remote:${embedding.model}|${embedding.dimension ?? "default"}`;
+    }
+    return `local:${embedding?.localModel ?? DEFAULT_LOCAL_MODEL}`;
+}
 function throwIfAborted(signal) {
     if (signal?.aborted) {
         throw signal.reason instanceof Error ? signal.reason : new Error("index interrupted");
@@ -17,7 +31,7 @@ export async function generateEmbeddingsForDb(db, config, onProgress, signal, en
     throwIfAborted(signal);
     if (config.semanticSearchMode === "off") {
         onProgress({ phase: "embeddings", message: "Semantic search disabled; skipping embeddings." });
-        return { success: false, reason: "index-missing", message: "Semantic search is disabled." };
+        return { success: false, message: "Semantic search is disabled." };
     }
     // A targeted call starts from an already-published generation. Preserve its
     // trust decision in O(1): successful writes for the changed IDs keep a
@@ -48,14 +62,35 @@ export async function generateEmbeddingsForDb(db, config, onProgress, signal, en
         });
         const texts = allEntries.map((entry) => entry.searchText);
         if (isVerbose()) {
-            const EMBED_BATCH_SIZE = 100;
-            const totalBatches = Math.ceil(texts.length / EMBED_BATCH_SIZE);
-            for (const [i, entry] of allEntries.entries()) {
-                const batchNum = Math.floor(i / EMBED_BATCH_SIZE) + 1;
-                const chars = entry.searchText.length;
-                const tokens = estimateTokenCount(entry.searchText);
-                const ref = entry.itemRef;
-                warnVerbose(`[embed] ${ref} (${chars} chars, est. ${tokens} tokens) → batch ${batchNum}/${totalBatches}`);
+            // Mirror RemoteEmbedder's actual token-bounded batching (#874) so this
+            // log reflects the real request grouping rather than a fixed count of
+            // 100 that no longer matches what gets sent over the wire. Local runs
+            // don't batch by size at all (LocalEmbedder chunks by a fixed count
+            // for inference throughput only, never fails/skips), so there's
+            // nothing meaningful to report per-batch for them.
+            if (hasRemoteEndpoint(config.embedding ?? {})) {
+                const tokenBudget = config.embedding?.maxTokens ?? config.embedding?.contextLength ?? DEFAULT_TOKEN_BUDGET;
+                const maxCount = config.embedding?.batchSize ?? DEFAULT_REMOTE_BATCH_SIZE;
+                const batches = buildTokenBoundedBatches(texts, tokenBudget, maxCount);
+                const batchNumberByIndex = new Map();
+                batches.forEach((batch, batchIdx) => {
+                    for (const i of batch.indices)
+                        batchNumberByIndex.set(i, batchIdx + 1);
+                });
+                for (const [i, entry] of allEntries.entries()) {
+                    const chars = entry.searchText.length;
+                    const tokens = estimateTokenCount(entry.searchText);
+                    const batch = batches[batchNumberByIndex.get(i) - 1];
+                    const label = batch?.oversized
+                        ? "oversized (skipped)"
+                        : `batch ${batchNumberByIndex.get(i)}/${batches.length}`;
+                    warnVerbose(`[embed] ${entry.itemRef} (${chars} chars, est. ${tokens} tokens) → ${label}`);
+                }
+            }
+            else {
+                for (const entry of allEntries) {
+                    warnVerbose(`[embed] ${entry.itemRef} (${entry.searchText.length} chars, est. ${estimateTokenCount(entry.searchText)} tokens)`);
+                }
             }
         }
         let heartbeatTimer;
@@ -66,17 +101,24 @@ export async function generateEmbeddingsForDb(db, config, onProgress, signal, en
                     message: `Still generating embeddings for ${allEntries.length} entr${allEntries.length === 1 ? "y" : "ies"}; waiting on embedding provider.`,
                 });
             }, 15000);
-            const embeddings = await embedBatch(texts, config.embedding, signal);
+            // A failing sub-batch or an oversized document is SKIPPED by embedBatch,
+            // not thrown (#874) — collect what couldn't be embedded and why, so a
+            // few bad documents don't discard every other entry's embedding.
+            const skips = [];
+            const embeddings = await embedBatch(texts, config.embedding, signal, (skip) => skips.push(skip));
             throwIfAborted(signal);
             let storedCount = 0;
             let skippedCount = 0;
+            let embedFailedCount = 0;
             let vecFailedCount = 0;
             let vecUnavailableCount = 0;
             db.transaction(() => {
                 for (const [i, entry] of allEntries.entries()) {
                     const embedding = embeddings[i];
-                    if (!embedding)
-                        throw new Error(`Embedding provider returned no vector for ${entry.itemRef}.`);
+                    if (!embedding) {
+                        embedFailedCount++;
+                        continue;
+                    }
                     const result = upsertEmbedding(db, entry.id, embedding);
                     if (result.stored)
                         storedCount++;
@@ -91,6 +133,14 @@ export async function generateEmbeddingsForDb(db, config, onProgress, signal, en
             if (skippedCount > 0) {
                 warn(`[embed] ${skippedCount} embedding${skippedCount === 1 ? "" : "s"} skipped (entry deleted between queue and write)`);
             }
+            if (embedFailedCount > 0) {
+                const detail = skips
+                    .slice(0, 20)
+                    .map((skip) => `  - ${allEntries[skip.index]?.itemRef ?? skip.index} (${skip.reason}): ${skip.message}`)
+                    .join("\n");
+                const more = skips.length > 20 ? `\n  ...and ${skips.length - 20} more` : "";
+                warn(`[embed] ${embedFailedCount} embedding${embedFailedCount === 1 ? "" : "s"} could not be generated and ${embedFailedCount === 1 ? "was" : "were"} skipped:\n${detail}${more}`);
+            }
             const vecGenerationComplete = targetEntryIds === undefined ? isVecFastPathComplete(db) : vecFastPathWasReady;
             setVecFastPathReady(db, vecFailedCount === 0 && vecUnavailableCount === 0 && vecGenerationComplete);
             if (vecFailedCount > 0) {
@@ -103,6 +153,19 @@ export async function generateEmbeddingsForDb(db, config, onProgress, signal, en
                 message: `Stored ${storedCount} embedding${storedCount === 1 ? "" : "s"}.`,
             });
             setMeta(db, "embeddingFingerprint", currentFingerprint);
+            // Only a total failure (nothing at all embedded, despite having entries
+            // to embed) turns into a phase failure. Any partial success — the vast
+            // majority of a large bundle embedding fine around a handful of skips —
+            // must not discard what DID get stored (#874).
+            if (storedCount === 0 && embedFailedCount > 0) {
+                const firstMessage = skips[0]?.message ?? "All embeddings failed.";
+                // #873 removed the persisted semantic verdict, so there is no failure
+                // class to record — just report what happened on this run.
+                return {
+                    success: false,
+                    message: `All ${embedFailedCount} embedding batch(es) failed: ${firstMessage}`,
+                };
+            }
             return { success: true, vecInsertFailures: vecFailedCount };
         }
         finally {
@@ -116,40 +179,21 @@ export async function generateEmbeddingsForDb(db, config, onProgress, signal, en
         onProgress({ phase: "embeddings", message: `Embedding generation failed: ${message}` });
         return {
             success: false,
-            reason: classifySemanticFailure(message),
             message: `Semantic search verification failed: ${message}`,
         };
     }
 }
-/** Publish the canonical semantic health snapshot after a targeted mutation. */
-export function publishTargetedSemanticStatus(db, config, result) {
+/**
+ * Update the `hasEmbeddings` DB fact after a targeted mutation, from the
+ * index's actual current embedding coverage — read fresh, not cached.
+ */
+export function publishTargetedEmbeddingMeta(db, config) {
     if (config.semanticSearchMode === "off") {
-        clearSemanticStatus();
         setMeta(db, "hasEmbeddings", "0");
         return;
     }
     const entryCount = getEmbeddableEntryCount(db);
     const embeddingCount = getEmbeddingCount(db);
-    let status;
-    if (entryCount === 0)
-        status = "pending";
-    else if (embeddingCount >= entryCount)
-        status = isVecAvailable(db) && isVecFastPathReady(db) ? "ready-vec" : "ready-js";
-    else
-        status = "blocked";
-    setMeta(db, "hasEmbeddings", status === "ready-js" || status === "ready-vec" ? "1" : "0");
-    writeSemanticStatus({
-        status,
-        ...(status === "blocked" ? { reason: result.reason ?? "index-failed" } : {}),
-        ...(status === "blocked"
-            ? {
-                message: result.message ??
-                    `Semantic search verification failed (${embeddingCount}/${entryCount} embeddings available).`,
-            }
-            : {}),
-        providerFingerprint: deriveSemanticProviderFingerprint(config.embedding),
-        lastCheckedAt: new Date().toISOString(),
-        entryCount,
-        embeddingCount,
-    });
+    const ready = entryCount > 0 && embeddingCount >= entryCount;
+    setMeta(db, "hasEmbeddings", ready ? "1" : "0");
 }

package/dist/indexer/search/db-search.js

@@ -26,7 +26,7 @@ import { assertIndexPathReadable, closeDatabase, openExistingDatabase, } from ".
 import { getAllEntries, getBaseBeliefStatesForDerivedTwins, getEntryById, getEntryCount, getPositiveFeedbackCountsByIds, } from "../../storage/repositories/index-entries-repository.js";
 import { searchFts } from "../../storage/repositories/index-fts-repository.js";
 import { getMeta } from "../../storage/repositories/index-meta-repository.js";
-import { searchVec } from "../../storage/repositories/index-vec-repository.js";
+import { getEmbeddingCount, searchVec } from "../../storage/repositories/index-vec-repository.js";
 import { getCurrentWorkflowScopeKey } from "../../workflows/authoring/scope-key.js";
 import { ensureIndex } from "../ensure-index.js";
 import { collectGraphRelatedHit, loadGraphBoostContext } from "../graph/graph-boost.js";
@@ -38,7 +38,6 @@ import { typeBoostFor } from "./ranking-contributors.js";
 import { attachSearchHitAttribution, copySearchHitAttribution, getSearchHitAttribution } from "./search-attribution.js";
 import { enrichSearchHit } from "./search-hit-enrichers.js";
 import { buildEditHint, findSourceForPath, isEditable } from "./search-source.js";
-import { deriveSemanticProviderFingerprint, getEffectiveSemanticStatus, isSemanticRuntimeReady, readSemanticStatus, } from "./semantic-status.js";
 /**
  * Age past which search surfaces a "run akm index" hint. Reads serve the
  * existing index as-is (freshness is the writers' job — `indexWrittenAssets`
@@ -126,49 +125,14 @@ export async function searchLocal(input) {
     const disableScopedUtility = input.disableScopedUtility === true;
     const rendererRegistry = input.rendererRegistry ?? defaultRendererRegistry;
     const allSourceDirs = sources.map((s) => s.path);
-    const rawStatus = readSemanticStatus();
-    const semanticStatus = getEffectiveSemanticStatus(config, rawStatus);
     const warnings = [];
-    if (config.semanticSearchMode === "auto" && semanticStatus === "pending") {
-        const currentFingerprint = deriveSemanticProviderFingerprint(config.embedding);
-        if (rawStatus && rawStatus.providerFingerprint !== currentFingerprint) {
-            warnings.push("Embedding config changed. Run 'akm index --full' to rebuild the semantic index with the new provider.");
-        }
-        else if (!hasConfiguredEmbeddingProvider(config)) {
-            // #480: when semantic mode is `auto` but no embedding provider is
-            // configured (e.g. `akm setup --yes` ran without picking one), telling
-            // the user to "run akm setup" is misleading — they just did. Surface
-            // the actual remediation: configure an embedding endpoint OR switch
-            // semanticSearchMode to `off` to silence the warning.
-            warnings.push("Semantic search is enabled (semanticSearchMode='auto') but no embedding provider is configured. " +
-                'Either: (a) `akm config set embedding \'{"endpoint":"...","model":"..."}\'`, or ' +
-                "(b) `akm config set semanticSearchMode off` to use keyword-only search.");
-        }
-        else {
-            warnings.push("Semantic search is pending verification. Run 'akm index --full' to build the semantic index now, or wait for the next background index pass.");
-        }
-    }
-    if (config.semanticSearchMode === "auto" && semanticStatus === "blocked") {
-        if (!hasConfiguredEmbeddingProvider(config)) {
-            // F7/A2: same predicate as the `pending` branch above (#480) — a
-            // `blocked` status can outlive the provider config that produced it
-            // (e.g. the embedding config was later unset). This is not a fault;
-            // there is simply nothing configured to use.
-            warnings.push("Semantic search is enabled (semanticSearchMode='auto') but no embedding provider is configured. " +
-                'Either: (a) `akm config set embedding \'{"endpoint":"...","model":"..."}\'`, or ' +
-                "(b) `akm config set semanticSearchMode off` to use keyword-only search.");
-        }
-        else {
-            // F7/A2: surface the ACTUAL diagnostic instead of one fixed generic
-            // string. `rawStatus.reason`/`rawStatus.message` record why the
-            // semantic backend failed (auth, network, a stuck local-model
-            // download, …) — read at `readSemanticStatus()` above and, before
-            // this fix, discarded here in favor of a message that never varied.
-            const detail = rawStatus?.message ?? (rawStatus?.reason ? `reason: ${rawStatus.reason}` : undefined);
-            warnings.push(`Semantic search is blocked${detail ? ` (${detail})` : ""}. Using keyword search until the semantic ` +
-                "backend is healthy again. Run 'akm index --full' to retry, or " +
-                "`akm config set semanticSearchMode off` to silence this warning.");
-        }
+    // Semantic search is attempted fresh on every query (see `tryVecScores`);
+    // there is no cached readiness verdict to consult here. The only thing
+    // worth flagging ahead of the attempt is a config that can never succeed.
+    if (config.semanticSearchMode === "auto" && !hasConfiguredEmbeddingProvider(config)) {
+        warnings.push("Semantic search is enabled (semanticSearchMode='auto') but no embedding provider is configured. " +
+            'Either: (a) `akm config set embedding \'{"endpoint":"...","model":"..."}\'`, or ' +
+            "(b) `akm config set semanticSearchMode off` to use keyword-only search.");
     }
     // Bootstrap-only: builds the index inline when it cannot serve this stash.
     // Content freshness is the writers' job (indexWrittenAssets + full runs);
@@ -662,11 +626,14 @@ function matchBeliefFilter(beliefState, filter) {
 }
 // ── Vector scorer ───────────────────────────────────────────────────────────
 async function tryVecScores(db, query, k, config) {
-    const semanticStatus = getEffectiveSemanticStatus(config, readSemanticStatus());
-    if (!isSemanticRuntimeReady(semanticStatus))
+    if (config.semanticSearchMode === "off")
         return { scores: null };
-    const hasEmbeddings = getMeta(db, "hasEmbeddings");
-    if (hasEmbeddings !== "1")
+    // A real-time completeness fact, not a cached verdict: skip the network
+    // round trip only when the index has never embedded anything. A PARTIAL
+    // failure (some entries embedded, one write degraded) still attempts —
+    // and if the endpoint is genuinely down, the failure surfaces as a live
+    // `semanticWarning` below instead of silently skipping with no signal.
+    if (getEmbeddingCount(db) === 0)
         return { scores: null };
     try {
         const { embed } = await import("../../llm/embedder.js");

package/dist/indexer/search/ranking-contributors.js

@@ -490,31 +490,6 @@ export const salienceRankingContributor = {
 // comment. Do not add it back here without a config gate + a measured
 // curate-golden-bench delta justifying it.
 export const defaultUtilityRankingContributors = [utilityRankingContributor];
-/**
- * EVAL/DEBUG ONLY — remove named ranking contributors from a list.
- *
- * Driven by the `AKM_ABLATE_CONTRIBUTORS` env var (comma-separated contributor
- * `name`s). A no-op — returns the input list unchanged (same reference) — when
- * the env value is unset/empty, so production ranking is never affected unless
- * the operator opts in. Its sole purpose is per-contributor ablation for the
- * curate ablation harness (`scripts/akm-eval/`): run the same fixture with and without a contributor
- * and diff the ranked results to measure whether that contributor is load-bearing.
- *
- * NOTE (from the 2026-06 ablation analysis): a contributor's ablation delta is only observable
- * in the UNSATURATED score regime — once entries saturate at the `displayScore`
- * ceiling their contributor deltas are absorbed and ablation reads Δ=0.
- */
-export function applyContributorAblation(contributors, ablateEnv) {
-    if (!ablateEnv)
-        return contributors;
-    const ablated = new Set(ablateEnv
-        .split(",")
-        .map((s) => s.trim())
-        .filter(Boolean));
-    if (ablated.size === 0)
-        return contributors;
-    return contributors.filter((c) => !ablated.has(c.name));
-}
 export function applyScoreContributors(item, ctx, contributors = defaultRankingContributors) {
     let boostSum = 0;
     for (const contributor of contributors) {

package/dist/indexer/search/ranking.js

@@ -3,7 +3,7 @@
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import { getUtilityScoresByIds } from "../../storage/repositories/index-utility-repository.js";
 import { buildLexicalQueryPlan } from "./fts-query.js";
-import { applyBeliefStateScoreCeiling, applyContributorAblation, applyScoreContributors, applyUtilityContributors, defaultRankingContributors, defaultUtilityRankingContributors, } from "./ranking-contributors.js";
+import { applyBeliefStateScoreCeiling, applyScoreContributors, applyUtilityContributors, defaultRankingContributors, defaultUtilityRankingContributors, } from "./ranking-contributors.js";
 export function normalizeFtsScores(results) {
     const ftsScoreMap = new Map();
     if (results.length === 0)
@@ -75,18 +75,8 @@ export function applyRankingRules(options) {
         graphContext: options.graphContext,
         projectContext: options.projectContext,
     };
-    // Eval/debug only: lets the ablation harness drop named contributors to
-    // measure their effect. Resolved once per query; a no-op (full lists) when
-    // unset — see applyContributorAblation. C9: DI via
-    // `options.ablateContributors` is now the primary path (see the field's
-    // doc comment on RankEntriesOptions); AKM_ABLATE_CONTRIBUTORS is a
-    // temporary fallback for the one caller that cannot yet thread the option
-    // through (see that doc comment for why).
-    const ablateEnv = options.ablateContributors ?? process.env.AKM_ABLATE_CONTRIBUTORS;
-    const activeScoreContributors = applyContributorAblation(defaultRankingContributors, ablateEnv);
-    const activeUtilityContributors = applyContributorAblation(defaultUtilityRankingContributors, ablateEnv);
     for (const item of options.items) {
-        applyScoreContributors(item, rankingContext, activeScoreContributors);
+        applyScoreContributors(item, rankingContext, defaultRankingContributors);
     }
     const { global: utilScoresMap, scoped: scopedUtilScoresMap } = getUtilityScoresByIds(options.db, options.items.map((item) => item.id), options.scopeKey);
     // R2 / #692 — salience-ranking is not in defaultUtilityRankingContributors
@@ -104,7 +94,7 @@ export function applyRankingRules(options) {
         salienceRankScores,
     };
     for (const item of options.items) {
-        applyUtilityContributors(item, utilityContext, activeUtilityContributors);
+        applyUtilityContributors(item, utilityContext, defaultUtilityRankingContributors);
         applyRelaxedLexicalScoreCeiling(item, queryTokens);
         // SPEC-5: demoting belief states (superseded/contradicted/archived/
         // deprecated) cap the FINAL score. The additive belief penalty inside the

package/dist/integrations/agent/builder-shared.js

@@ -1,35 +1,10 @@
 // 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/.
-/**
- * Shared agent-command-builder types and helpers (#563).
- *
- * Extracted from `agent/builders.ts` so per-harness builders (e.g.
- * `harnesses/claude/agent-builder.ts`) can depend on the common
- * types/validation WITHOUT creating an import cycle back through
- * `builders.ts` (which imports the per-harness builders into its registry).
- * This module is a dependency-graph LEAF for the builder subsystem.
- *
- * Behaviour-preserving: the type shapes and helper bodies are unchanged from
- * their previous home in `builders.ts`.
- */
-import { UsageError } from "../../core/errors.js";
 /** Models reaching a harness have already crossed the single model-map boundary. */
 export function resolveDispatchModel(request, _profile, _platform) {
     return request.model;
 }
-/**
- * Guard against values that start with `--`, which would be mis-interpreted as
- * CLI flags by the spawned process when used as flag values (model, systemPrompt).
- * Bun.spawn uses array argv so there is no shell injection, but a `--`-prefixed
- * value passed as the argument to `--model` or `--system-prompt` can still
- * confuse the CLI parser of the target process.
- */
-export function assertNotFlag(value, field) {
-    if (value?.trimStart().startsWith("--")) {
-        throw new UsageError(`${field} must not start with "--": ${JSON.stringify(value.slice(0, 60))}`, "INVALID_FLAG_VALUE");
-    }
-}
 /**
  * Normalize a toolPolicy value to a comma-separated string suitable for a
  * CLI flag. Structured policy objects are JSON-serialized.

package/dist/integrations/agent/model-map.js

@@ -5,7 +5,7 @@ import { randomBytes } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { MAX_CONFIG_FILE_BYTES, readTextFileDescriptorWithLimit, writeFileAtomic } from "../../core/common.js";
+import { writeFileAtomic } from "../../core/common.js";
 import { ENGINE_NAME_PATTERN_SOURCE } from "../../core/config/engine-semantics.js";
 import { ConfigError, UsageError } from "../../core/errors.js";
 import { getConfigDir } from "../../core/paths.js";
@@ -21,9 +21,6 @@ import { cloneExecutionJsonObject } from "../../execution/json.js";
  * provider mappings.
  */
 export const MODEL_MAP_VERSION = 1;
-export const MODEL_MAP_MAX_BYTES = MAX_CONFIG_FILE_BYTES;
-export const MODEL_MAP_MAX_DEPTH = 64;
-export const MODEL_MAP_MAX_NODES = 100_000;
 let standaloneInstalledModelMapText;
 const ENGINE_KEY_PATTERN = new RegExp(ENGINE_NAME_PATTERN_SOURCE);
 const ALIAS_KEY_PATTERN = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
@@ -92,62 +89,8 @@ function parseProfileLayer(value, source, jsonPath) {
     }
     return Object.freeze(out);
 }
-/**
- * Bound nesting before JSON.parse or any recursive durable-JSON clone runs.
- * Brackets inside strings are ignored, including escaped quote sequences.
- */
-function assertJsonDepthBudget(text, source) {
-    let depth = 0;
-    let inString = false;
-    let escaped = false;
-    for (const character of text) {
-        if (inString) {
-            if (escaped)
-                escaped = false;
-            else if (character === "\\")
-                escaped = true;
-            else if (character === '"')
-                inString = false;
-            continue;
-        }
-        if (character === '"') {
-            inString = true;
-            continue;
-        }
-        if (character === "{" || character === "[") {
-            depth += 1;
-            if (depth > MODEL_MAP_MAX_DEPTH) {
-                invalid(source, "$", `JSON nesting exceeds the ${MODEL_MAP_MAX_DEPTH}-level limit`);
-            }
-        }
-        else if (character === "}" || character === "]") {
-            depth -= 1;
-        }
-    }
-}
-/** Iterative node budget, deliberately completed before recursive inference cloning. */
-function assertJsonNodeBudget(value, source) {
-    const pending = [value];
-    let count = 0;
-    while (pending.length > 0) {
-        const current = pending.pop();
-        count += 1;
-        if (count > MODEL_MAP_MAX_NODES) {
-            invalid(source, "$", `JSON value exceeds the ${MODEL_MAP_MAX_NODES}-node limit`);
-        }
-        if (current !== null && typeof current === "object") {
-            const children = Array.isArray(current) ? current : Object.values(current);
-            for (const child of children)
-                pending.push(child);
-        }
-    }
-}
 /** Parse one installed or user layer. Partial structured profiles are valid at this stage. */
 export function parseModelMapLayer(text, source) {
-    if (Buffer.byteLength(text, "utf8") > MODEL_MAP_MAX_BYTES) {
-        invalid(source, "$", `document exceeds the ${MODEL_MAP_MAX_BYTES}-byte limit`);
-    }
-    assertJsonDepthBudget(text, source);
     let parsed;
     try {
         parsed = JSON.parse(text);
@@ -155,7 +98,6 @@ export function parseModelMapLayer(text, source) {
     catch {
         invalid(source, "$", "invalid JSON syntax");
     }
-    assertJsonNodeBudget(parsed, source);
     const root = requireRecord(parsed, source, "$");
     assertOnlyKeys(root, ["version", "aliases"], source, "$");
     if (root.version !== MODEL_MAP_VERSION) {
@@ -314,7 +256,7 @@ function readModelMapFile(filePath, label, optional) {
         if (!sameFileIdentity(linkStat, openedStat)) {
             throw new ConfigError(`${label} changed while it was being opened: ${filePath}.`, "INVALID_CONFIG_FILE", "Retry after ensuring no other process is replacing models.json.");
         }
-        const text = readTextFileDescriptorWithLimit(fd, MODEL_MAP_MAX_BYTES, label, filePath);
+        const text = fs.readFileSync(fd, "utf8");
         fs.closeSync(fd);
         fd = undefined;
         return text;

package/dist/integrations/harnesses/aider/agent-builder.js

@@ -67,7 +67,7 @@
  * name without any further wiring. The registry entry also declares
  * `structuredOutput: "none"` alongside it (`./index.ts`).
  */
-import { assertNotFlag, resolveDispatchModel, } from "../../agent/builder-shared.js";
+import { resolveDispatchModel } from "../../agent/builder-shared.js";
 import { createAgentRequestLowerer } from "../../agent/request-lowering.js";
 /** Canonical harness/platform id used for model-alias resolution. */
 export const AIDER_PLATFORM = "aider";
@@ -103,8 +103,6 @@ export const aiderBuilder = {
         outputSchema: true,
     }),
     build(profile, req) {
-        assertNotFlag(req.systemPrompt, "systemPrompt");
-        assertNotFlag(req.model, "model");
         const args = [...profile.args];
         if (req.model) {
             const resolved = resolveDispatchModel(req, profile, AIDER_PLATFORM);

package/dist/integrations/harnesses/amazonq/agent-builder.js

@@ -32,7 +32,7 @@
  * - **systemPrompt** — `q chat` has no system-prompt flag (persona/context
  *   comes from Q's own agent config files), so the system prompt is folded
  *   into the positional payload ahead of the task prompt, separated by a
- *   blank line. `assertNotFlag` still guards it.
+ *   blank line.
  * - **schema** — the matrix places Q in the NO-structured-output tier
  *   ("via prompt+validate": *(none documented)* — there is no `--json` or
  *   `--output-format` to ask for). The JSON Schema is therefore passed
@@ -62,7 +62,7 @@
  * pattern `local-runner`, structuredOutput `none` — is declared alongside it
  * (`./index.ts`).
  */
-import { assertNotFlag, resolveDispatchModel, } from "../../agent/builder-shared.js";
+import { resolveDispatchModel } from "../../agent/builder-shared.js";
 import { createAgentRequestLowerer } from "../../agent/request-lowering.js";
 /** Canonical harness/platform id used for model-alias resolution. */
 export const AMAZONQ_PLATFORM = "amazonq";
@@ -116,8 +116,6 @@ export const amazonqBuilder = {
         outputSchema: true,
     }),
     build(profile, req) {
-        assertNotFlag(req.systemPrompt, "systemPrompt");
-        assertNotFlag(req.model, "model");
         // Built-in q profiles would ship `args: []`; headless dispatch is the
         // `chat` subcommand. Don't double it when a user profile already pins it.
         const extra = profile.args[0] === "chat" ? profile.args.slice(1) : [...profile.args];
@@ -129,9 +127,6 @@ export const amazonqBuilder = {
             // flags: dropping a restriction must never widen to --trust-all-tools.
             const entries = toolPolicyEntries(req.tools);
             if (entries !== undefined) {
-                for (const tool of entries) {
-                    assertNotFlag(tool, "tools entry");
-                }
                 // Q's documented allowlist form is equals-joined and comma-separated
                 // (`--trust-tools=fs_read,fs_write`); an empty list trusts no tools.
                 args.push(`--trust-tools=${entries.join(",")}`);