akm-cli 0.9.0-rc.8 → 0.9.0

package/dist/storage/repositories/proposals-repository.js

@@ -1,6 +1,17 @@
 // 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/.
+/**
+ * Repository for the state.db `proposals` table. Extracted verbatim from
+ * core/state-db.ts — queries and row-mapping unchanged, only relocated behind
+ * the repository boundary. Re-exported by core/state-db.ts so existing importers
+ * resolve.
+ *
+ * @module proposals-repository
+ */
+import path from "node:path";
+import { stashDirFor } from "../../core/asset/asset-placement.js";
+import { bundleRefToString, isBundleSlug, parseBundleRef } from "../../core/asset/asset-ref.js";
 /** Serialize `Proposal.changes` for `metadata_json` (see {@link StoredFileChange}). */
 function changesToStored(changes) {
     return changes.map((c, i) => ({
@@ -11,42 +22,277 @@ function changesToStored(changes) {
 }
 /**
  * Reconstruct `Proposal.changes` from `metadata_json.changes` + the `content`
- * column. Legacy rows (persisted before the envelope existed) synthesize one
- * `update` entry with an empty `path` sentinel (resolve from the ref instead).
+ * column.
  */
 function storedToChanges(stored, content) {
     if (!Array.isArray(stored) || stored.length === 0) {
-        return [{ path: "", after: content, op: "update" }];
+        throw new Error("Proposal metadata is missing changes.");
+    }
+    return stored.map((value, i) => {
+        if (typeof value !== "object" || value === null)
+            throw new Error("Proposal metadata has invalid changes.");
+        const c = value;
+        if (typeof c.path !== "string" ||
+            (c.op !== "create" && c.op !== "update" && c.op !== "delete") ||
+            (c.after !== undefined && typeof c.after !== "string") ||
+            (c.op === "delete" && c.after !== undefined) ||
+            (i > 0 && c.op !== "delete" && typeof c.after !== "string")) {
+            throw new Error("Proposal metadata has invalid changes.");
+        }
+        return {
+            path: c.path,
+            op: c.op,
+            ...(i === 0 ? (c.op === "delete" ? {} : { after: content }) : c.after !== undefined ? { after: c.after } : {}),
+        };
+    });
+}
+function currentProposalRef(ref, requireQualified = false) {
+    let parsed;
+    try {
+        parsed = parseBundleRef(ref);
+    }
+    catch (error) {
+        throw new Error(`Proposal row has an invalid current ref: ${ref}`, { cause: error });
+    }
+    const colon = parsed.conceptId.indexOf(":");
+    if (colon > 0 && stashDirFor(parsed.conceptId.slice(0, colon)) !== undefined) {
+        throw new Error(`Proposal row has an invalid current ref: ${ref}`);
+    }
+    if (parsed.fragment !== undefined)
+        throw new Error(`Proposal row ref contains a fragment: ${ref}`);
+    if (requireQualified && parsed.bundle === undefined)
+        throw new Error(`Proposal ref is not bundle-qualified: ${ref}`);
+    const canonical = bundleRefToString(parsed);
+    if (canonical !== ref)
+        throw new Error(`Proposal row ref is not canonical: ${ref}`);
+    return canonical;
+}
+function currentProposalTarget(value) {
+    if (typeof value !== "object" || value === null)
+        throw new Error("Proposal metadata is missing proposedTarget.");
+    const target = value;
+    if (typeof target.source !== "string" ||
+        !isBundleSlug(target.source) ||
+        typeof target.root !== "string" ||
+        !path.isAbsolute(target.root)) {
+        throw new Error("Proposal metadata has an invalid proposedTarget.");
+    }
+    return { source: target.source, root: path.resolve(target.root) };
+}
+function invalidPresentField(name) {
+    throw new Error(`Proposal metadata has an invalid ${name}.`);
+}
+const GATE_OUTCOMES = {
+    "auto-accepted": true,
+    deferred: true,
+    staged: true,
+    "auto-rejected": true,
+};
+function validatePresentMetadata(meta) {
+    const stringFields = ["sourceRun", "beforeHash", "backupContent"];
+    for (const field of stringFields) {
+        if (Object.hasOwn(meta, field) && typeof meta[field] !== "string")
+            invalidPresentField(field);
+    }
+    if (Object.hasOwn(meta, "confidence") &&
+        (typeof meta.confidence !== "number" ||
+            !Number.isFinite(meta.confidence) ||
+            meta.confidence < 0 ||
+            meta.confidence > 1)) {
+        invalidPresentField("confidence");
+    }
+    if (Object.hasOwn(meta, "review")) {
+        const review = meta.review;
+        if (typeof review !== "object" ||
+            review === null ||
+            (review.outcome !== "accepted" && review.outcome !== "rejected") ||
+            typeof review.decidedAt !== "string" ||
+            (review.reason !== undefined && typeof review.reason !== "string")) {
+            invalidPresentField("review");
+        }
+    }
+    if (Object.hasOwn(meta, "gateDecision")) {
+        const gate = meta.gateDecision;
+        if (typeof gate !== "object" ||
+            gate === null ||
+            typeof gate.outcome !== "string" ||
+            !Object.hasOwn(GATE_OUTCOMES, gate.outcome) ||
+            typeof gate.reason !== "string" ||
+            typeof gate.decidedAt !== "string" ||
+            (gate.measured !== undefined && (typeof gate.measured !== "number" || !Number.isFinite(gate.measured))) ||
+            (gate.contentHash !== undefined && typeof gate.contentHash !== "string") ||
+            (gate.gate !== undefined && typeof gate.gate !== "string")) {
+            invalidPresentField("gateDecision");
+        }
+        if (gate.thresholds !== undefined) {
+            const thresholds = gate.thresholds;
+            if (typeof thresholds !== "object" ||
+                thresholds === null ||
+                [thresholds.maxDiffLines, thresholds.minContentLines].some((value) => value !== undefined && (typeof value !== "number" || !Number.isFinite(value)))) {
+                invalidPresentField("gateDecision");
+            }
+        }
+    }
+    if (Object.hasOwn(meta, "acceptedTarget")) {
+        const target = meta.acceptedTarget;
+        if (typeof target !== "object" ||
+            target === null ||
+            typeof target.source !== "string" ||
+            !isBundleSlug(target.source) ||
+            typeof target.root !== "string" ||
+            !path.isAbsolute(target.root) ||
+            typeof target.path !== "string" ||
+            !path.isAbsolute(target.path) ||
+            typeof target.contentHash !== "string") {
+            invalidPresentField("acceptedTarget");
+        }
+    }
+    if (Object.hasOwn(meta, "eligibilitySource") && typeof meta.eligibilitySource !== "string") {
+        invalidPresentField("eligibilitySource");
     }
-    return stored.map((c, i) => ({
-        path: typeof c.path === "string" ? c.path : "",
-        op: c.op === "create" || c.op === "delete" ? c.op : "update",
-        ...(i === 0 ? (c.op === "delete" ? {} : { after: content }) : c.after !== undefined ? { after: c.after } : {}),
-    }));
 }
 /**
  * Convert a raw `ProposalRow` to the public `Proposal` shape.
  */
 export function proposalRowToProposal(row) {
+    if (!["pending", "accepted", "rejected", "reverted"].includes(row.status)) {
+        throw new Error(`Proposal row has invalid status: ${row.status}`);
+    }
     let frontmatter;
-    if (row.frontmatter_json) {
+    if (row.frontmatter_json !== null) {
         try {
-            frontmatter = JSON.parse(row.frontmatter_json);
+            const parsed = JSON.parse(row.frontmatter_json);
+            if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+                throw new Error("Proposal frontmatter_json must contain an object.");
+            }
+            frontmatter = parsed;
         }
-        catch {
-            /* ignore corrupt frontmatter JSON */
+        catch (error) {
+            throw new Error("Proposal row has invalid frontmatter_json.", { cause: error });
         }
     }
     let meta = {};
     try {
-        meta = JSON.parse(row.metadata_json);
+        const parsed = JSON.parse(row.metadata_json);
+        if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+            throw new Error("Proposal metadata_json must contain an object.");
+        }
+        meta = parsed;
+    }
+    catch (error) {
+        throw new Error("Proposal row has invalid metadata_json.", { cause: error });
+    }
+    validatePresentMetadata(meta);
+    const changes = Object.hasOwn(meta, "changes")
+        ? storedToChanges(meta.changes, row.content)
+        : [{ path: "", op: "update", after: row.content }];
+    const proposedTarget = Object.hasOwn(meta, "proposedTarget") ? currentProposalTarget(meta.proposedTarget) : undefined;
+    return {
+        id: row.id,
+        ref: currentProposalRef(row.ref),
+        status: row.status,
+        source: row.source,
+        ...(typeof meta.sourceRun === "string" ? { sourceRun: meta.sourceRun } : {}),
+        createdAt: row.created_at,
+        updatedAt: row.updated_at,
+        payload: {
+            content: row.content,
+            ...(frontmatter !== undefined ? { frontmatter } : {}),
+        },
+        changes,
+        ...(proposedTarget !== undefined ? { proposedTarget } : {}),
+        ...(typeof meta.beforeHash === "string" ? { beforeHash: meta.beforeHash } : {}),
+        ...(meta.review !== undefined ? { review: meta.review } : {}),
+        ...(typeof meta.confidence === "number" ? { confidence: meta.confidence } : {}),
+        ...(meta.gateDecision !== undefined ? { gateDecision: meta.gateDecision } : {}),
+        ...(typeof meta.backupContent === "string" ? { backupContent: meta.backupContent } : {}),
+        ...(meta.acceptedTarget !== undefined ? { acceptedTarget: meta.acceptedTarget } : {}),
+        ...(typeof meta.eligibilitySource === "string"
+            ? { eligibilitySource: meta.eligibilitySource }
+            : {}),
+    };
+}
+/**
+ * Lenient counterpart to {@link proposalRowToProposal} for the terminal-status
+ * (reject/archive) read paths (repository.ts `archiveProposal` /
+ * `rejectProposalDurably`). Those paths must succeed even on legacy rows
+ * minted before a field was required — e.g. 0.8-era rows missing
+ * `proposedTarget` and/or carrying empty/missing `changes[].path` metadata —
+ * so an operator can reject them instead of resorting to manual SQL.
+ *
+ * Per-field decode failures are swallowed: the offending field degrades to a
+ * safe placeholder (matching the strict decoder's own "no changes recorded"
+ * fallback) and the failure is appended to `decodeWarnings` instead of
+ * throwing. `id` / `status` / timestamps / `source` are trusted verbatim (the
+ * schema guarantees they're non-null strings). The strict decoder remains the
+ * default everywhere else, including every other read of a `pending` or
+ * `accepted` proposal (accept/revert must keep failing exactly as today on a
+ * malformed row).
+ */
+export function proposalRowToProposalLenient(row) {
+    const warnings = [];
+    let meta = {};
+    try {
+        const parsed = JSON.parse(row.metadata_json);
+        if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+            throw new Error("metadata_json must contain an object.");
+        }
+        meta = parsed;
+        validatePresentMetadata(meta);
+    }
+    catch (error) {
+        warnings.push(`metadata_json is invalid (${error instanceof Error ? error.message : String(error)}); optional fields dropped.`);
+        meta = {};
+    }
+    let frontmatter;
+    if (row.frontmatter_json !== null) {
+        try {
+            const parsed = JSON.parse(row.frontmatter_json);
+            if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+                throw new Error("frontmatter_json must contain an object.");
+            }
+            frontmatter = parsed;
+        }
+        catch (error) {
+            warnings.push(`frontmatter_json is invalid (${error instanceof Error ? error.message : String(error)}); frontmatter dropped.`);
+        }
+    }
+    let ref;
+    try {
+        ref = currentProposalRef(row.ref);
+    }
+    catch (error) {
+        warnings.push(`ref is invalid (${error instanceof Error ? error.message : String(error)}); keeping the raw stored value.`);
+        ref = row.ref;
+    }
+    let changes;
+    try {
+        changes = Object.hasOwn(meta, "changes")
+            ? storedToChanges(meta.changes, row.content)
+            : [{ path: "", op: "update", after: row.content }];
+    }
+    catch (error) {
+        warnings.push(`changes metadata is invalid (${error instanceof Error ? error.message : String(error)}); degraded to a single placeholder change.`);
+        changes = [{ path: "", op: "update", after: row.content }];
+    }
+    let proposedTarget;
+    if (Object.hasOwn(meta, "proposedTarget")) {
+        try {
+            proposedTarget = currentProposalTarget(meta.proposedTarget);
+        }
+        catch (error) {
+            warnings.push(`proposedTarget is invalid (${error instanceof Error ? error.message : String(error)}); omitted.`);
+        }
     }
-    catch {
-        /* ignore */
+    else {
+        warnings.push("proposedTarget is missing (pre-WI-6.2 legacy row).");
+    }
+    if (!["pending", "accepted", "rejected", "reverted"].includes(row.status)) {
+        warnings.push(`status "${row.status}" is not a recognized value.`);
     }
     return {
         id: row.id,
-        ref: row.ref,
+        ref,
         status: row.status,
         source: row.source,
         ...(typeof meta.sourceRun === "string" ? { sourceRun: meta.sourceRun } : {}),
@@ -56,19 +302,18 @@ export function proposalRowToProposal(row) {
             content: row.content,
             ...(frontmatter !== undefined ? { frontmatter } : {}),
         },
-        changes: storedToChanges(meta.changes, row.content),
+        changes,
+        ...(proposedTarget !== undefined ? { proposedTarget } : {}),
         ...(typeof meta.beforeHash === "string" ? { beforeHash: meta.beforeHash } : {}),
         ...(meta.review !== undefined ? { review: meta.review } : {}),
         ...(typeof meta.confidence === "number" ? { confidence: meta.confidence } : {}),
         ...(meta.gateDecision !== undefined ? { gateDecision: meta.gateDecision } : {}),
         ...(typeof meta.backupContent === "string" ? { backupContent: meta.backupContent } : {}),
-        ...(typeof meta.acceptedContentHash === "string" ? { acceptedContentHash: meta.acceptedContentHash } : {}),
         ...(meta.acceptedTarget !== undefined ? { acceptedTarget: meta.acceptedTarget } : {}),
-        ...(meta.legacyAcceptedTargetDerived === true ? { legacyAcceptedTargetDerived: true } : {}),
-        ...(meta.legacyAcceptedAssetWasAbsent === true ? { legacyAcceptedAssetWasAbsent: true } : {}),
         ...(typeof meta.eligibilitySource === "string"
             ? { eligibilitySource: meta.eligibilitySource }
             : {}),
+        ...(warnings.length > 0 ? { decodeWarnings: warnings } : {}),
     };
 }
 /**
@@ -78,15 +323,17 @@ export function proposalRowToProposal(row) {
 export function proposalToRowValues(proposal, stashDir) {
     // Fields that have no dedicated column live in metadata_json.
     const metaObj = {};
-    // Legacy filesystem proposal.json objects (pre-envelope, imported by the
-    // migrator's proposal-fs-import.ts) reach this mapper without `changes` at
-    // runtime despite the type — or, if hand-edited, with a malformed value.
-    // Synthesize the same sentinel entry the read path uses rather than letting
-    // one corrupt legacy file abort a whole import batch.
-    const safeChanges = Array.isArray(proposal.changes)
-        ? proposal.changes.filter((c) => typeof c === "object" && c !== null)
-        : undefined;
-    metaObj.changes = changesToStored(safeChanges && safeChanges.length > 0 ? safeChanges : [{ path: "", after: proposal.payload.content, op: "update" }]);
+    if (!Array.isArray(proposal.changes) || proposal.changes.length === 0) {
+        throw new Error(`Proposal ${proposal.id} has no file changes.`);
+    }
+    if (proposal.changes.some((change) => typeof change.path !== "string" ||
+        change.path.length === 0 ||
+        !["create", "update", "delete"].includes(change.op) ||
+        (change.op === "delete" ? change.after !== undefined : typeof change.after !== "string"))) {
+        throw new Error(`Proposal ${proposal.id} has invalid file changes.`);
+    }
+    metaObj.changes = changesToStored(proposal.changes);
+    metaObj.proposedTarget = currentProposalTarget(proposal.proposedTarget);
     if (proposal.beforeHash !== undefined)
         metaObj.beforeHash = proposal.beforeHash;
     if (proposal.sourceRun !== undefined)
@@ -99,22 +346,15 @@ export function proposalToRowValues(proposal, stashDir) {
         metaObj.gateDecision = proposal.gateDecision;
     if (proposal.backupContent !== undefined)
         metaObj.backupContent = proposal.backupContent;
-    if (proposal.acceptedContentHash !== undefined)
-        metaObj.acceptedContentHash = proposal.acceptedContentHash;
     if (proposal.acceptedTarget !== undefined)
         metaObj.acceptedTarget = proposal.acceptedTarget;
-    if (proposal.legacyAcceptedTargetDerived !== undefined) {
-        metaObj.legacyAcceptedTargetDerived = proposal.legacyAcceptedTargetDerived;
-    }
-    if (proposal.legacyAcceptedAssetWasAbsent !== undefined) {
-        metaObj.legacyAcceptedAssetWasAbsent = proposal.legacyAcceptedAssetWasAbsent;
-    }
     if (proposal.eligibilitySource !== undefined)
         metaObj.eligibilitySource = proposal.eligibilitySource;
+    validatePresentMetadata(metaObj);
     return {
         id: proposal.id,
         stash_dir: stashDir,
-        ref: proposal.ref,
+        ref: currentProposalRef(proposal.ref, true),
         status: proposal.status,
         source: proposal.source,
         created_at: proposal.createdAt,
@@ -173,7 +413,12 @@ export function listStateProposals(db, options = {}) {
               content, frontmatter_json, metadata_json
        FROM proposals ${where} ORDER BY created_at ASC, rowid ASC`)
         .all(...params);
-    return rows.map(proposalRowToProposal);
+    // Archived rows (accepted/rejected/reverted) decode leniently so a
+    // terminal-status row that was rejected via the lenient path (or predates
+    // a required field) remains listable — a strict throw here would defeat
+    // the point of tolerating it at reject/archive time. Pending rows keep the
+    // strict decoder; nothing about the live queue changes here.
+    return rows.map((row) => (row.status === "pending" ? proposalRowToProposal(row) : proposalRowToProposalLenient(row)));
 }
 /**
  * Look up a single proposal by id, optionally scoped to one stash root.
@@ -186,6 +431,18 @@ export function getStateProposal(db, id, stashDir) {
     const row = (stashDir ? db.prepare(sql).get(id, stashDir) : db.prepare(sql).get(id));
     return row ? proposalRowToProposal(row) : undefined;
 }
+/**
+ * Lenient counterpart to {@link getStateProposal} — used ONLY by the
+ * terminal-status (reject/archive) read paths in repository.ts that must
+ * tolerate a malformed row (see {@link proposalRowToProposalLenient}).
+ */
+export function getStateProposalLenient(db, id, stashDir) {
+    const sql = `SELECT id, stash_dir, ref, status, source, created_at, updated_at,
+              content, frontmatter_json, metadata_json
+       FROM proposals WHERE id = ?${stashDir ? " AND stash_dir = ?" : ""}`;
+    const row = (stashDir ? db.prepare(sql).get(id, stashDir) : db.prepare(sql).get(id));
+    return row ? proposalRowToProposalLenient(row) : undefined;
+}
 /**
  * Find PENDING proposal ids in one stash whose id starts with `idPrefix`.
  * Backs the UUID-prefix form of `akm proposal show/accept/... <prefix>` —
@@ -203,23 +460,3 @@ export function listStateProposalIdsByPrefix(db, stashDir, idPrefix) {
         .all(stashDir, `${escaped}%`);
     return rows.map((r) => r.id);
 }
-/**
- * Insert a proposal row ONLY when the id is not already present (used by the
- * one-time legacy filesystem import in the migrator —
- * `src/migrate/legacy/proposal-fs-import.ts` — so a re-run never clobbers rows
- * that have since been mutated through the canonical store, and re-walking the
- * still-on-disk legacy files is idempotent). Returns true when a row was
- * inserted.
- */
-export function insertProposalIfAbsent(db, proposal, stashDir) {
-    const v = proposalToRowValues(proposal, stashDir);
-    const result = db
-        .prepare(`
-      INSERT OR IGNORE INTO proposals
-        (id, stash_dir, ref, status, source, created_at, updated_at, content, frontmatter_json, metadata_json)
-      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-    `)
-        .run(v.id, v.stash_dir, v.ref, v.status, v.source, v.created_at, v.updated_at, v.content, v.frontmatter_json, v.metadata_json);
-    const changes = result.changes ?? 0;
-    return Number(changes) > 0;
-}

package/dist/storage/repositories/registry-cache.js

@@ -2,6 +2,7 @@
 // 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/.
 import { rethrowIfTestIsolationError } from "../../core/errors.js";
+import { warn } from "../../core/warn.js";
 import { closeDatabase, openIndexDatabase } from "./index-connection.js";
 import { getRegistryIndexCache, upsertRegistryIndexCache } from "./registry-index-cache-repository.js";
 /**
@@ -87,6 +88,24 @@ export async function fetchCachedJson(opts) {
                 if (stale !== undefined)
                     return stale;
             }
+            // No in-TTL row — consult the cache PAST its TTL before giving up
+            // (§24.2 "Durability" gate): a briefly unreachable registry should
+            // degrade to the last-known index, loudly, not hard-fail the command.
+            try {
+                const expiredRow = db ? getRegistryIndexCache(db, cacheKey, Number.POSITIVE_INFINITY) : undefined;
+                if (expiredRow) {
+                    const stale = parseCache(expiredRow.indexJson, { stale: true });
+                    if (stale !== undefined) {
+                        warn(`Registry fetch failed (${err instanceof Error ? err.message : String(err)}); ` +
+                            "serving the last cached index, which is past its refresh interval.");
+                        return stale;
+                    }
+                }
+            }
+            catch (cacheErr) {
+                rethrowIfTestIsolationError(cacheErr);
+                // cache read failed — fall through to the original fetch error
+            }
             throw err;
         }
     });

package/dist/storage/repositories/salience-repository.js

@@ -0,0 +1,172 @@
+// 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/.
+/**
+ * Upsert salience scores for one asset into state.db.
+ *
+ * Idempotent: safe to call every run; updates the outcome / retrieval / rank
+ * columns on conflict.
+ *
+ * #644 — encoding provenance guard: the `encoding_salience` + `encoding_source`
+ * columns are NOT lowered from a real content-derived score to a type-weight
+ * stub. When the stored row is `encoding_source = 'content'` and the incoming
+ * vector is a `type-stub` fallback, the stored encoding score and its provenance
+ * are preserved (only the other sub-scores and `rank_score` advance). A `content`
+ * write always wins; a `type-stub` write only seeds a row that has no content
+ * score yet. This stops the improve loop's type-weight fallback re-asserting the
+ * stub over a distill-written score on every run.
+ *
+ * NOTE: when the guard preserves the stored encoding score, the incoming
+ * `vector.rankScore` (computed from the stub encoding) is still written. Callers
+ * that want the rank_score to reflect the preserved content score should pass the
+ * stored content score back in as `inputs.encodingSalience` to `computeSalience`
+ * — which the improve loop does. The guard here is the defensive backstop.
+ */
+export function upsertAssetSalience(db, ref, vector, now) {
+    const ts = now ?? Date.now();
+    db.prepare(`INSERT INTO asset_salience
+       (asset_ref, encoding_salience, outcome_salience, retrieval_salience, rank_score, consecutive_no_ops, updated_at, encoding_source)
+     VALUES (?, ?, ?, ?, ?, 0, ?, ?)
+     ON CONFLICT(asset_ref) DO UPDATE SET
+       -- #644: never lower a real content-derived score to a type-weight stub.
+       -- Keep the stored encoding score + provenance when the stored row is
+       -- 'content' and the incoming write is a 'type-stub' fallback.
+       encoding_salience  = CASE
+         WHEN asset_salience.encoding_source = 'content' AND excluded.encoding_source = 'type-stub'
+           THEN asset_salience.encoding_salience
+           ELSE excluded.encoding_salience
+       END,
+       encoding_source    = CASE
+         WHEN asset_salience.encoding_source = 'content' AND excluded.encoding_source = 'type-stub'
+           THEN asset_salience.encoding_source
+           ELSE excluded.encoding_source
+       END,
+       outcome_salience   = excluded.outcome_salience,
+       retrieval_salience = excluded.retrieval_salience,
+       rank_score         = excluded.rank_score,
+       updated_at         = excluded.updated_at`).run(ref, vector.encoding, vector.outcome, vector.retrieval, vector.rankScore, ts, vector.encodingSource ?? "type-stub");
+}
+/**
+ * Load the salience row for one asset, or undefined if not yet computed.
+ */
+export function getAssetSalience(db, ref) {
+    const row = db
+        .prepare(`SELECT asset_ref, encoding_salience, outcome_salience, retrieval_salience,
+              rank_score, consecutive_no_ops, updated_at, encoding_source
+       FROM asset_salience WHERE asset_ref = ?`)
+        .get(ref);
+    // Bun SQLite returns null (not undefined) when no row found.
+    return row == null ? undefined : row;
+}
+/**
+ * Load ALL rank scores from the asset_salience table (full-stash query).
+ *
+ * Used by the forgetting-safety report (plan §WS-1 step 7) to compute stash-wide
+ * rank positions rather than pool-relative positions. Returns an empty Map when the
+ * table is empty (first WS-1 run = no pre-existing rows).
+ *
+ * Order is unspecified; callers must sort before assigning 1-indexed positions.
+ */
+export function getAllRankScores(db) {
+    const rows = db.prepare("SELECT asset_ref, rank_score FROM asset_salience").all();
+    const result = new Map();
+    for (const row of rows) {
+        result.set(row.asset_ref, row.rank_score);
+    }
+    return result;
+}
+// ── Plasticity helpers ────────────────────────────────────────────────────────
+/**
+ * Increment `consecutive_no_ops` for an asset. Called after a no-op reflect/distill.
+ * Has NO effect on `rank_score` — the plasticity counter only dampens consolidation
+ * selection, not retrieval ranking. See plan §WS-1 step 8.
+ *
+ * Invariant: recordNoOp must never originate rank_score semantics. If the asset has
+ * no salience row yet (persistence's best-effort try/catch may have swallowed an
+ * error), we do nothing — a no-op counter is meaningless without a rank_score row,
+ * and a synthetic INSERT would fabricate a rank_score=0 entry that could produce
+ * false catastrophic-forgetting signals in buildRankChangeReport.
+ */
+export function recordNoOp(db, ref) {
+    db.prepare(`UPDATE asset_salience SET consecutive_no_ops = consecutive_no_ops + 1, updated_at = ? WHERE asset_ref = ?`).run(Date.now(), ref);
+    // If changes === 0 the asset has no salience row yet — leave the table unchanged.
+}
+/**
+ * Reset `consecutive_no_ops` to 0 when an asset produces an accepted change.
+ * Call after a successful proposal acceptance or detected mutation.
+ */
+export function resetConsecutiveNoOps(db, ref) {
+    db.prepare(`UPDATE asset_salience SET consecutive_no_ops = 0, updated_at = ? WHERE asset_ref = ?`).run(Date.now(), ref);
+}
+/**
+ * Return the `consecutive_no_ops` count for one asset. 0 when unknown.
+ */
+export function getConsecutiveNoOps(db, ref) {
+    const row = db.prepare(`SELECT consecutive_no_ops FROM asset_salience WHERE asset_ref = ?`).get(ref);
+    return row?.consecutive_no_ops ?? 0;
+}
+// ── New in #672 part 2 ────────────────────────────────────────────────────────
+/**
+ * Load the `retrieval_salience` column for the top `limit` assets ordered by
+ * `rank_score` descending.
+ *
+ * Absorbs the health read formerly inlined in `commands/health/metrics.ts`
+ * (`computeDegradationMetrics`'s corpus-diversity Gini calculation) — same
+ * query, now parameterised on `limit` instead of a hardcoded 100. This is new
+ * behavior (a named, parameterised repository entry point), not a verbatim
+ * move; callers that need fail-open behaviour on a missing table (pre-WS-1
+ * installs) must wrap the call in their own try/catch, matching the existing
+ * call site.
+ */
+export function getTopRetrievalSalience(db, limit) {
+    return db
+        .prepare(`SELECT retrieval_salience FROM asset_salience ORDER BY rank_score DESC LIMIT ?`)
+        .all(limit);
+}
+/** List every `asset_salience` ref with its current `missing_since` marker. */
+export function listAssetSalienceMissingState(db) {
+    return db.prepare(`SELECT asset_ref, missing_since FROM asset_salience`).all();
+}
+/**
+ * Stamp `missing_since = now` for the given refs, but ONLY where it is
+ * currently NULL — a ref already stamped keeps its original timestamp so the
+ * grace window measures from first sighting, not last. Refs with no row at
+ * all are silently skipped (0 rows affected). Returns the number of rows
+ * actually stamped.
+ */
+export function stampAssetSalienceMissing(db, refs, now) {
+    if (refs.length === 0)
+        return 0;
+    const stmt = db.prepare(`UPDATE asset_salience SET missing_since = ? WHERE asset_ref = ? AND missing_since IS NULL`);
+    let changed = 0;
+    for (const ref of refs)
+        changed += Number(stmt.run(now, ref).changes);
+    return changed;
+}
+/**
+ * Clear `missing_since` for refs that resolved again. Returns the number of
+ * rows actually cleared.
+ */
+export function clearAssetSalienceMissing(db, refs) {
+    if (refs.length === 0)
+        return 0;
+    const stmt = db.prepare(`UPDATE asset_salience SET missing_since = NULL WHERE asset_ref = ? AND missing_since IS NOT NULL`);
+    let changed = 0;
+    for (const ref of refs)
+        changed += Number(stmt.run(ref).changes);
+    return changed;
+}
+/**
+ * Delete `asset_salience` rows whose `missing_since` is older than
+ * `cutoffMs`. A single DELETE — SQLite runs it as one implicit transaction.
+ * Returns the number of rows deleted.
+ */
+export function deleteAssetSalienceMissingBefore(db, cutoffMs) {
+    return Number(db.prepare(`DELETE FROM asset_salience WHERE missing_since IS NOT NULL AND missing_since < ?`).run(cutoffMs)
+        .changes);
+}
+/** Count `asset_salience` rows currently marked missing (the live backlog size). */
+export function countAssetSalienceMissing(db) {
+    const row = db.prepare(`SELECT COUNT(*) AS n FROM asset_salience WHERE missing_since IS NOT NULL`).get();
+    return row.n;
+}