akm-cli 0.9.16 → 0.9.17-alpha.10

package/dist/commands/improve/retrieval-gate.js

@@ -0,0 +1,127 @@
+// 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/.
+/**
+ * The retrieval regression gate (#722): a reflect rewrite of an existing asset
+ * must not grade lower on the queries that actually retrieved it.
+ *
+ * Measured before it was built: of 60 accepted reflect rewrites judged against
+ * their own queries, 14 graded lower (23%, 95% CI 14–35%) and 12 higher. The
+ * old and new content are graded one query at a time, blind, with the
+ * retrieval-eval judge's prompt (kappa 0.83 against human grades) and its
+ * document shape: type, ref, name, description and the first 1,500 characters
+ * of the body.
+ */
+import relevanceJudgePrompt from "../../assets/prompts/retrieval-relevance-judge.md" with { type: "text" };
+import { parseFrontmatter } from "../../core/asset/frontmatter.js";
+import { parseRefInput } from "../../core/asset/resolve-ref.js";
+import { nonTaskInput } from "../../core/non-task-input.js";
+import { parseEmbeddedJsonResponse } from "../../core/parse.js";
+import { listRetrievalQueries } from "../../indexer/usage/usage-events.js";
+import { readLedgerDb, stripBundle } from "./ledger.js";
+import { callStage } from "./stage.js";
+/** Queries graded per rewrite, as measured. */
+const MAX_QUERIES = 5;
+/** The retrieval suite treats a longer input as a paste, not a query; the measurement did the same. */
+const MAX_QUERY_CHARS = 2000;
+/** The judge sees this much of the body, as in the retrieval eval. */
+const MAX_DOC_CHARS = 1500;
+const GRADE_SCHEMA = {
+    type: "object",
+    required: ["grade", "reason"],
+    additionalProperties: false,
+    properties: { grade: { type: "integer", minimum: 0, maximum: 3 }, reason: { type: "string" } },
+};
+/** Up to five distinct task queries, in the given order, whitespace collapsed. */
+export function usableRetrievalQueries(raw) {
+    const out = [];
+    for (const text of raw) {
+        const query = text.replace(/\s+/g, " ").trim();
+        if (!query || query.length > MAX_QUERY_CHARS || nonTaskInput(query) || out.includes(query))
+            continue;
+        out.push(query);
+        if (out.length === MAX_QUERIES)
+            break;
+    }
+    return out;
+}
+/** The asset's own retrieval queries from the usage log (none when state.db cannot be read). */
+export function loadRetrievalQueries(access, ref) {
+    try {
+        return usableRetrievalQueries(readLedgerDb(access, (db) => listRetrievalQueries(db, stripBundle(ref))) ?? []);
+    }
+    catch {
+        return [];
+    }
+}
+function judgeDocument(ref, raw) {
+    const conceptId = stripBundle(ref);
+    const parsed = parseRefInput(conceptId);
+    const { data, content } = parseFrontmatter(raw);
+    const text = content
+        .replace(/\n{3,}/g, "\n\n")
+        .trim()
+        .slice(0, MAX_DOC_CHARS);
+    const name = typeof data.name === "string" && data.name ? data.name : parsed.name;
+    const description = typeof data.description === "string" ? data.description : "";
+    return [
+        "Candidate asset:",
+        `Type: ${parsed.type}`,
+        `Ref: ${conceptId}`,
+        `Name: ${name}`,
+        `Description: ${description}`,
+        "",
+        "Content:",
+        text,
+    ].join("\n");
+}
+/**
+ * Grade `before` and `after` on each query; refuse the rewrite when the new
+ * content's mean grade is lower. Fails closed, like the quality judge: a grade
+ * that cannot be obtained refuses the rewrite.
+ */
+export async function runRetrievalRegressionGate(args) {
+    if (args.queries.length === 0)
+        return { pass: true, queries: 0, reason: "no retrieval queries to compare on" };
+    const documents = { old: judgeDocument(args.ref, args.before), new: judgeDocument(args.ref, args.after) };
+    const totals = { old: 0, new: 0 };
+    for (const query of args.queries) {
+        for (const version of ["old", "new"]) {
+            const outcome = await callStage({
+                feature: "proposal_quality_gate",
+                runner: args.runner,
+                system: relevanceJudgePrompt.trim(),
+                prompt: `Query: ${query}\n\n${documents[version]}`,
+                request: {
+                    enableThinking: false,
+                    temperature: 0,
+                    responseSchema: GRADE_SCHEMA,
+                    ...(args.timeoutMs !== undefined ? { timeoutMs: args.timeoutMs } : {}),
+                    ...(args.signal ? { signal: args.signal } : {}),
+                    ...(args.chat ? { chat: args.chat } : {}),
+                },
+                ...(args.onNotices ? { onNotices: args.onNotices } : {}),
+            });
+            const grade = outcome.ok ? parseEmbeddedJsonResponse(outcome.raw)?.grade : undefined;
+            if (typeof grade !== "number" || !Number.isInteger(grade) || grade < 0 || grade > 3) {
+                return {
+                    pass: false,
+                    queries: args.queries.length,
+                    reason: `retrieval check could not grade the ${version} content${outcome.ok ? "" : ` (${outcome.reason})`}`,
+                };
+            }
+            totals[version] += grade;
+        }
+    }
+    const oldMean = totals.old / args.queries.length;
+    const newMean = totals.new / args.queries.length;
+    const pass = newMean >= oldMean;
+    const grades = `${oldMean.toFixed(2)} -> ${newMean.toFixed(2)} over ${args.queries.length} retrieval ${args.queries.length === 1 ? "query" : "queries"}`;
+    return {
+        pass,
+        queries: args.queries.length,
+        oldMean,
+        newMean,
+        reason: pass ? `retrieval grade ${grades}` : `retrieval regression: grade ${grades}`,
+    };
+}

package/dist/commands/improve/retrieval-scope.js

@@ -0,0 +1,92 @@
+// 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/.
+/**
+ * What improve may rework (#986): an asset that retrieval returned inside the
+ * usage window, or newly captured material no improve stage has processed.
+ *
+ * Fresh feedback and an explicit `--scope <ref>` are usage evidence of their
+ * own, so the signal-delta and scope lanes need no check. The fallback lanes
+ * (proactive maintenance, high salience) and consolidation pick assets
+ * without such evidence, so they pick only inside this scope.
+ */
+import fs from "node:fs";
+import { daysToMs } from "../../core/common.js";
+import { warn } from "../../core/warn.js";
+import { listUsedEntryRefs, USAGE_EVENT_RETENTION_DAYS } from "../../indexer/usage/usage-events.js";
+import { listImproveLedgerRows } from "../../storage/repositories/improve-ledger-repository.js";
+import { listProposalRefSources } from "../../storage/repositories/proposals-repository.js";
+import { PAIR_PASS_LEDGER_SOURCE, readLedgerDb, stripBundle } from "./ledger.js";
+/**
+ * Ledger and proposal sources that bring material in. Every other source is an
+ * improve stage reworking an asset (reflect, distill, consolidate, schema repair).
+ */
+const CAPTURE_SOURCES = new Set(["extract", "propose", "remember", "import"]);
+/**
+ * Load the scope from state.db. The window is the usage log's retention: the
+ * log keeps nothing older, and anything shorter would drop assets read less
+ * often than the window. A `.derived` hit counts for its parent memory, whose
+ * facts it carries. `undefined` (every asset eligible, as before #986) only
+ * when state.db cannot be read.
+ */
+export function loadRetrievalScope(access, stashDir) {
+    const sinceMs = Date.now() - daysToMs(USAGE_EVENT_RETENTION_DAYS);
+    const used = new Set();
+    const processed = new Set();
+    try {
+        readLedgerDb(access, (db) => {
+            for (const entryRef of listUsedEntryRefs(db, new Date(sinceMs).toISOString())) {
+                const conceptId = stripBundle(entryRef);
+                used.add(conceptId);
+                if (conceptId.endsWith(".derived"))
+                    used.add(conceptId.slice(0, -".derived".length));
+            }
+            if (!stashDir)
+                return;
+            // Blocker 1 (second review round): a pair-pass ledger row must NOT mark
+            // an asset "processed" — unlike every other stage, the pair pass judges
+            // material against its NEIGHBOURS, not on its own merits, so its own
+            // attempt is not usage evidence the fallback lanes (proactive,
+            // high-salience) or promotion retries should be starved by. Left in
+            // the ledger for the pair pass's OWN eligibility
+            // (selectInitiators reads content_hash directly, never this scope).
+            // Proposal rows are untouched: a MINTED retire proposal is real
+            // evidence something happened to the asset.
+            for (const row of listImproveLedgerRows(db, stashDir)) {
+                if (row.source === PAIR_PASS_LEDGER_SOURCE)
+                    continue;
+                if (!CAPTURE_SOURCES.has(row.source))
+                    processed.add(stripBundle(row.ref));
+            }
+            for (const row of listProposalRefSources(db, stashDir)) {
+                if (!CAPTURE_SOURCES.has(row.source))
+                    processed.add(stripBundle(row.ref));
+            }
+        });
+    }
+    catch (error) {
+        warn(`[improve] usage history unreadable, so every asset stays eligible: ${error instanceof Error ? error.message : String(error)}`);
+        return undefined;
+    }
+    return { used, processed, sinceMs };
+}
+/**
+ * Whether improve may rework `ref` (whose file is `filePath`) under `scope`. An
+ * unprocessed asset whose file cannot be read is left to the disk check that
+ * follows, which reports it as missing.
+ */
+export function isInRetrievalScope(scope, ref, filePath) {
+    if (!scope)
+        return true;
+    const conceptId = stripBundle(ref);
+    if (scope.used.has(conceptId))
+        return true;
+    if (scope.processed.has(conceptId))
+        return false;
+    try {
+        return filePath === undefined || fs.statSync(filePath).mtimeMs >= scope.sinceMs;
+    }
+    catch {
+        return true;
+    }
+}

package/dist/commands/improve/salience.js

@@ -4,71 +4,25 @@
 import { getAllEntries } from "../../storage/repositories/index-entries-repository.js";
 import { getUtilityScoresByIds } from "../../storage/repositories/index-utility-repository.js";
 import { WARM_START_CAP } from "./outcome-loop.js";
-// ── One day in ms ─────────────────────────────────────────────────────────────
 const DAY_MS = 86_400_000;
-// ── Recency decay half-life (mirrors the proactive-maintenance prototype) ─────
 const RECENCY_HALFLIFE_DAYS = 21;
-// ── Recency-floor half-life (R4 — SHY-style continuous downscaling) ──────────
-//
-// The recency floor itself decays on this (much longer) half-life so an
-// unreviewed-forever asset keeps drifting down instead of parking at the 0.1
-// floor. This replaces the deleted homeostatic demotion pass (which was
-// default-off and self-undoing — every salience recompute clobbered it);
-// folding the decay into the always-applied recency term makes it persist by
-// construction. At 180 days the floor halves; a 1-year-stale asset sits at
-// ~0.025 instead of 0.1.
+/**
+ * The recency floor itself halves every 180 days, so an asset nobody uses keeps
+ * drifting down instead of parking at the floor.
+ */
 const RECENCY_FLOOR_HALFLIFE_DAYS = 180;
-// Absolute epsilon under the decaying floor. Keeps the frequency term ordinal
-// for assets whose last-use timestamp is unknown (utility_scores has no
-// last_used_at) — without it their retrieval salience collapses to exactly 0
-// and frequency ordering is lost for maintenance selection.
+/** Keeps frequency ordinal for assets whose last use is unknown. */
 const RECENCY_EPSILON = 0.01;
-// ── Size proxy floor (avoids log10(0)) ────────────────────────────────────────
 const SIZE_FLOOR_BYTES = 200;
-// ── Projection weights ────────────────────────────────────────────────────────
-//
-// These constants are the DEFAULT ranking weights (R1 loop closure). Operators
-// can opt back out to the WS-1 parity weights (w_e=0.30, w_r=0.70, w_o=0) via
-// `improve.salience.outcomeWeightEnabled: false`.
-//
-// WS-2 split (w_e=0.25, w_o=0.15, w_r=0.60, sum = 1.0):
-// [exp] Expert recommendation: encoding should be moderate so a type-importance
-// stub does not completely dominate; retrieval should be strong since it directly
-// measures use; outcome provides a quality signal proportional to usefulness.
-//
-// Re-tune via the Part-V measurement protocol if the throughput/quality gate
-// shows regression after enabling the outcome weight.
-export const W_ENCODING = 0.25; // WS-2 target encoding weight (w_e)
-export const W_OUTCOME = 0.15; // WS-2 target outcome weight (w_o)
-export const W_RETRIEVAL = 0.6; // WS-2 target retrieval weight (w_r)
-// Compile-time guard: weights must sum to 1.0 (±ε). The TS initializer runs
-// at module load, not build time, so this acts as a startup assertion.
-if (Math.abs(W_ENCODING + W_OUTCOME + W_RETRIEVAL - 1.0) > 1e-9) {
-    throw new Error(`salience.ts: W_ENCODING + W_OUTCOME + W_RETRIEVAL must equal 1.0 (got ${W_ENCODING + W_OUTCOME + W_RETRIEVAL})`);
-}
-// ── WS-1 parity weights ───────────────────────────────────────────────────────
-//
-// These constants reflect the WS-1 parity weights used when the operator
-// explicitly opts out (`outcomeWeightEnabled: false`). They preserve the
-// WS-1 two-way split (w_e=0.30, w_r=0.70) with w_o=0 so outcome does not
-// affect rankScore in the opt-out mode.
-//
-// Named here (rather than inline literals in the else branch) so a future
-// re-tune has a single source of truth and the sum-to-1 guard below catches
-// any accidental mis-edit.
-export const W_ENCODING_PARITY = 0.3; // WS-1 parity encoding weight
-export const W_OUTCOME_PARITY = 0; // WS-1 parity outcome weight (0 = disabled)
-export const W_RETRIEVAL_PARITY = 0.7; // WS-1 parity retrieval weight
-// Startup guard: parity triple must also sum to 1.0 (±ε).
-if (Math.abs(W_ENCODING_PARITY + W_OUTCOME_PARITY + W_RETRIEVAL_PARITY - 1.0) > 1e-9) {
-    throw new Error(`salience.ts: W_ENCODING_PARITY + W_OUTCOME_PARITY + W_RETRIEVAL_PARITY must equal 1.0 (got ${W_ENCODING_PARITY + W_OUTCOME_PARITY + W_RETRIEVAL_PARITY})`);
-}
-// ── Type-importance fallback weights (#608 landed) ────────────────────────────
-//
-// The real encoding salience estimator is `scoreEncodingSalience` in
-// `encoding-salience.ts` (#608). These weights are the fallback used when
-// `SalienceInputs.encodingSalience` is absent (pre-#608 assets without a
-// frontmatter `salience:` field or a state.db row seeded by distill).
+/** Default weights: the outcome term is on (opt out with `improve.salience.outcomeWeightEnabled: false`). */
+export const W_ENCODING = 0.25;
+export const W_OUTCOME = 0.15;
+export const W_RETRIEVAL = 0.6;
+/** Weights with the outcome term off. */
+export const W_ENCODING_PARITY = 0.3;
+export const W_OUTCOME_PARITY = 0;
+export const W_RETRIEVAL_PARITY = 0.7;
+/** Encoding salience by type, for assets with no content-derived score yet. */
 export const DEFAULT_TYPE_ENCODING_WEIGHTS = Object.freeze({
     skill: 0.9,
     agent: 0.9,
@@ -79,218 +33,65 @@ export const DEFAULT_TYPE_ENCODING_WEIGHTS = Object.freeze({
     script: 0.6,
     memory: 0.5,
 });
-/** Default encoding salience for types not in the table above. */
 export const DEFAULT_ENCODING_SALIENCE = 0.5;
-// ── Core computation ─────────────────────────────────────────────────────────
-/**
- * Compute the salience vector for one asset.
- *
- * Pure function — no I/O. All inputs are pre-fetched by the caller.
- */
+const clamp01 = (value) => Math.min(1, Math.max(0, value));
+/** The salience vector for one asset (pure). */
 export function computeSalience(inputs) {
     const now = inputs.now ?? Date.now();
-    // ── Encoding salience ────────────────────────────────────────────────────────
-    //
-    // When `inputs.encodingSalience` is provided (computed by `scoreEncodingSalience`
-    // in encoding-salience.ts at extract/distill time, #608), use it directly.
-    // Fall back to the type-importance stub only when the caller has not yet
-    // computed a content-based score (e.g. on older assets before the first
-    // staleness refresh runs).
     const encodingSource = inputs.encodingSalience !== undefined ? "content" : "type-stub";
     const encoding = inputs.encodingSalience !== undefined
-        ? Math.min(1, Math.max(0, inputs.encodingSalience))
+        ? clamp01(inputs.encodingSalience)
         : (DEFAULT_TYPE_ENCODING_WEIGHTS[inputs.type] ?? DEFAULT_ENCODING_SALIENCE);
-    // ── Outcome salience (WS-2 active) ────────────────────────────────────────
-    //
-    // When `inputs.outcomeSalience` is provided (WS-2 has populated asset_outcome
-    // for this ref), use it directly — it has already been normalised by
-    // `outcomeScoreToSalience` in outcome-loop.ts (value in [DIVERSITY_FLOOR, 1]).
-    //
-    // When absent (new asset, no WS-2 row yet): fall back to the warm-start seed
-    // from `utilityScore` clipped to [0, WARM_START_CAP], matching the seed
-    // value that `updateAssetOutcome` writes on first row creation. This ensures
-    // `outcomeSalience` is non-zero at launch for assets with utility history
-    // (avoiding the starvation problem described in the plan §WS-2 warm start).
-    let outcome;
-    if (inputs.outcomeSalience !== undefined) {
-        // Direct pass-through — caller already normalised via outcomeScoreToSalience.
-        outcome = Math.min(1, Math.max(0, inputs.outcomeSalience));
-    }
-    else {
-        // Warm-start fallback: clip utility to [0, WARM_START_CAP] so the
-        // outcomeSalience term contributes a modest non-zero baseline.
-        outcome = Math.min(WARM_START_CAP, Math.max(0, inputs.utilityScore ?? 0));
-    }
-    // ── Retrieval salience ─────────────────────────────────────────────────────
-    //
-    // Formula: log(1 + freq) × recencyDecay
-    //   log(1+freq): sub-linear frequency term (same as proactive-maintenance prototype).
-    //   recencyDecay: max(ε, 0.1·0.5^(useAgeDays/180) + 0.5^(useAgeDays/21)) —
-    //     the fast term halves every 21 days; the 0.1 floor itself halves every
-    //     180 days (R4: SHY-style continuous downscaling — an unreviewed-forever
-    //     asset keeps drifting down instead of parking at the floor). The ε=0.01
-    //     epsilon keeps the frequency term ordinal for unknown-last-use assets.
-    //     lastUseMs=0/undefined → useAgeDays=9999 → recencyDecay=ε.
-    //
-    // The recency term is MANDATORY (plan requirement §WS-1 step 2). Without it
-    // retrievalSalience degenerates to a non-decaying frequency count. This
-    // always-applied decay replaces the deleted homeostatic demotion pass.
+    // Without an outcome row, utility (capped) seeds the outcome term — the same
+    // seed the first outcome row gets — so it is not zero at launch.
+    const outcome = inputs.outcomeSalience !== undefined
+        ? clamp01(inputs.outcomeSalience)
+        : Math.min(WARM_START_CAP, Math.max(0, inputs.utilityScore ?? 0));
+    // log(1 + freq) × recency, where recency halves every 21 days above a floor
+    // that itself halves every 180 days; soft-capped to [0, 1).
     const lastUseMs = inputs.lastUseMs ?? 0;
     const useAgeDays = lastUseMs > 0 ? (now - lastUseMs) / DAY_MS : 9999;
     const recencyDecay = Math.max(RECENCY_EPSILON, 0.1 * 0.5 ** (useAgeDays / RECENCY_FLOOR_HALFLIFE_DAYS) + 0.5 ** (useAgeDays / RECENCY_HALFLIFE_DAYS));
     const rawRetrieval = Math.log(1 + inputs.retrievalFreq) * recencyDecay;
-    // ── Size penalty ─────────────────────────────────────────────────────────────
-    // 1/log10(size): larger assets are slightly deprioritized (same as proactive prototype).
-    const sizeProxy = Math.max(SIZE_FLOOR_BYTES, inputs.sizeBytes ?? 0);
-    const sizePenalty = 1 / Math.log10(sizeProxy);
-    // ── Projection → rankScore ────────────────────────────────────────────────
-    //
-    // Raw projection may be > 1 (log retrieval terms can exceed 1 for high freq + fresh use).
-    // Normalize by the theoretical maximum of the retrieval component:
-    //   max retrievalRaw = log(1 + Infinity) × (0.1 + 1.0) = Infinity, so we
-    //   cap instead — rankScore is clamped to [0,1] after applying the size penalty.
-    //
-    // Normalization approach: we scale the combined linear sum to [0,1] by clamping,
-    // after applying the size penalty. The encoding term is already in [0,1]; the
-    // retrieval term is open-ended but bounded in practice by log(1+N)×1.1 where N
-    // is the retrieval count. We normalize `retrieval` to [0,1] using a soft cap:
-    //   retrieval_normalized = rawRetrieval / (rawRetrieval + 1)
-    // which asymptotes to 1 and equals 0.5 at rawRetrieval=1. This is the same
-    // formula used for MemRL utility updates.
     const retrieval = rawRetrieval / (rawRetrieval + 1);
-    // ── Weight selection (R1 — outcome loop closed by default) ───────────────
-    //
-    // When `outcomeWeightEnabled` is true/absent (DEFAULT ON since the G2
-    // saturation cap landed): use WS-2 weights (w_e=0.25, w_o=0.15, w_r=0.60)
-    // so the prediction-error outcome signal actually shapes rankScore — this
-    // is the R1 loop-closure.
-    //
-    // When `outcomeWeightEnabled` is explicitly false (operator opt-out via
-    // `improve.salience.outcomeWeightEnabled: false`): fall back to the WS-1
-    // parity weights (w_e=0.30, w_r=0.70, w_o=0). The `outcome` sub-score is
-    // still computed and stored for observability in that mode.
-    let we;
-    let wo;
-    let wr;
-    if (inputs.outcomeWeightEnabled !== false) {
-        // WS-2 active (default): three-way split.
-        we = W_ENCODING; // 0.25
-        wo = W_OUTCOME; // 0.15
-        wr = W_RETRIEVAL; // 0.60
-    }
-    else {
-        // WS-1 parity (opt-out): w_o=0, redistribute to WS-1 proportions.
-        // Original WS-1 split was w_e=0.30, w_r=0.70.
-        we = W_ENCODING_PARITY;
-        wo = W_OUTCOME_PARITY;
-        wr = W_RETRIEVAL_PARITY;
-    }
-    const rawRankScore = (we * encoding + wo * outcome + wr * retrieval) * sizePenalty;
-    const rankScore = Math.min(1, Math.max(0, rawRankScore));
+    // Larger assets rank slightly lower.
+    const sizePenalty = 1 / Math.log10(Math.max(SIZE_FLOOR_BYTES, inputs.sizeBytes ?? 0));
+    const [we, wo, wr] = inputs.outcomeWeightEnabled !== false
+        ? [W_ENCODING, W_OUTCOME, W_RETRIEVAL]
+        : [W_ENCODING_PARITY, W_OUTCOME_PARITY, W_RETRIEVAL_PARITY];
+    const rankScore = clamp01((we * encoding + wo * outcome + wr * retrieval) * sizePenalty);
     return { encoding, outcome, retrieval, rankScore, encodingSource };
 }
-// ── state.db persistence ─────────────────────────────────────────────────────
-//
-// The three sub-scores live in state.db::asset_salience. Raw SQL now lives in
-// storage/repositories/salience-repository.ts (#672 part 2) — extracted
-// verbatim, only relocated behind the repository boundary. Re-exported here so
-// existing importers of this module resolve unchanged. Migrations live in
-// state-db.ts (migration 009).
-export { getAllRankScores, getAssetSalience, getConsecutiveNoOps, recordNoOp, resetConsecutiveNoOps, upsertAssetSalience, } from "../../storage/repositories/salience-repository.js";
-/**
- * Does this row carry a genuine content-derived `encoding_salience` (#644)?
- *
- * Unknown provenance is not treated as content-derived.
- */
+export { getAssetSalience, getConsecutiveNoOps, recordNoOp, resetConsecutiveNoOps, upsertAssetSalience, } from "../../storage/repositories/salience-repository.js";
+/** Whether a stored row's encoding salience is content-derived (unknown provenance is not). */
 export function isContentEncodingRow(row) {
     return row.encoding_source === "content";
 }
-// ── Consolidation-selection dampener constants ────────────────────────────────
-//
-// Assets with consecutive_no_ops >= THRESHOLD are deprioritised in the
-// SELECTION ORDER only. The persisted rank_score is intentionally left
-// unchanged so stable assets remain fully retrievable by other callers.
-//
-// Tuning guidance:
-//   THRESHOLD — how many consecutive no-op runs before dampening kicks in.
-//               3 means "skipped three times in a row", which signals the
-//               LLM consistently has nothing to say about this asset.
-//   FACTOR    — multiplicative penalty on the effective selection score.
-//               0.5 halves the apparent score so a dampened asset sorts
-//               after any peer with >= half its rankScore.
-export const SALIENCE_NO_OP_DAMPEN_THRESHOLD = 3;
-export const SALIENCE_NO_OP_DAMPEN_FACTOR = 0.5;
-/**
- * Emit the forgetting-safety rank-change distribution report.
- *
- * Compares the provided `newRanks` (Map<ref, position (1-indexed)>) against
- * the provided `oldRanks` and flags refs that were in the old top-200 but
- * are now below position 500 as "forgetting candidates".
- *
- * Caller is responsible for computing old/new rank positions before and after
- * the WS-1 formula cutover. Called once at cutover, not every run.
- *
- * @param oldRanks - Map<ref, 1-indexed rank position> under the OLD formula.
- * @param newRanks - Map<ref, 1-indexed rank position> under the NEW formula.
- * @param oldTopN  - Assets in old top-N to guard (default: 200).
- * @param forgettingThreshold - New rank position below which a fall is flagged (default: 500).
- */
-export function buildRankChangeReport(oldRanks, newRanks, oldTopN = 200, forgettingThreshold = 500) {
-    const allChanges = [];
-    const forgettingCandidates = [];
-    for (const [ref, oldRank] of oldRanks) {
-        const newRank = newRanks.get(ref);
-        if (newRank === undefined)
-            continue; // ref not in new ranking
-        const rankDelta = newRank - oldRank; // positive = fell in rank
-        allChanges.push({ ref, oldRank, newRank, rankDelta });
-        if (oldRank <= oldTopN && newRank > forgettingThreshold) {
-            forgettingCandidates.push({ ref, oldRank, newRank, rankDelta });
-        }
-    }
-    // Sort by magnitude of rank drop (most dramatic first).
-    forgettingCandidates.sort((a, b) => b.rankDelta - a.rankDelta);
-    return { forgettingCandidates, allChanges };
-}
-// ── Last-use timestamp lookup helper ─────────────────────────────────────────
-//
-// Wraps the index DB query to retrieve the last-retrieval timestamp per ref,
-// so callers do not need to import the raw db helpers directly. Returns a Map
-// keyed by the same ref strings passed in.
-//
-// Source: `utility_scores.last_used_at` (ISO-8601 string) joined to entries
-// via entry_id. WS-2 may later supersede this with `asset_outcome.last_retrieved_at`.
 /**
- * Build a Map<ref, lastUseMs> from the index database's utility_scores table.
- *
- * Returns only refs that have a non-null `last_used_at`. Refs absent from the
- * map should be treated as never retrieved (lastUseMs = 0).
- *
- * @param indexDb - An open read-capable index database connection.
- * @param candidates - Planned refs carrying their canonical durable item_ref.
+ * Consolidation selection only: an asset whose last three runs were no-ops
+ * sorts at half its score. The stored rank is untouched.
  */
+export const SALIENCE_NO_OP_DAMPEN_THRESHOLD = 3;
+export const SALIENCE_NO_OP_DAMPEN_FACTOR = 0.5;
+/** `ref → last retrieval (ms)` from the index's utility scores; absent means never retrieved. */
 export function getLastUseMsByRef(indexDb, candidates) {
     const result = new Map();
     if (candidates.length === 0)
         return result;
     const refByItemRef = new Map(candidates.flatMap((candidate) => (candidate.itemRef ? [[candidate.itemRef, candidate.ref]] : [])));
-    const allEntries = getAllEntries(indexDb);
     const idToRef = new Map();
-    for (const indexed of allEntries) {
+    for (const indexed of getAllEntries(indexDb)) {
         const ref = refByItemRef.get(indexed.itemRef);
         if (ref)
             idToRef.set(indexed.id, ref);
     }
-    const ids = [...idToRef.keys()];
-    if (ids.length === 0)
+    if (idToRef.size === 0)
         return result;
-    const { global: scores } = getUtilityScoresByIds(indexDb, ids);
+    const scores = getUtilityScoresByIds(indexDb, [...idToRef.keys()]);
     for (const [id, row] of scores) {
         const ref = idToRef.get(id);
-        if (!ref)
-            continue;
         const lastUsedAt = row.lastUsedAt;
-        if (!lastUsedAt)
+        if (!ref || !lastUsedAt)
             continue;
         const ms = typeof lastUsedAt === "number" ? lastUsedAt : Date.parse(lastUsedAt);
         if (ms > 0)