akm-cli 0.9.0-beta.9 → 0.9.0-rc.0

package/dist/commands/improve/eligibility.js

@@ -0,0 +1,434 @@
+// 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/.
+import fs from "node:fs";
+import path from "node:path";
+import { makeAssetRef, parseAssetRef } from "../../core/asset/asset-ref.js";
+import { parseFrontmatter } from "../../core/asset/frontmatter.js";
+import { isAssetType } from "../../core/common.js";
+import { NotFoundError, rethrowIfTestIsolationError, UsageError } from "../../core/errors.js";
+import { readEvents } from "../../core/events.js";
+import { closeDatabase, getAllEntries, getUtilityScoresByIds, openExistingDatabase } from "../../indexer/db/db.js";
+import { getWritableStashDirs, resolveSourceEntries } from "../../indexer/search/search-source.js";
+import { resolveAssetPath } from "../../indexer/walk/path-resolver.js";
+import { isDistillRefusedInputType } from "./distill.js";
+import { isProfileFilteredForAllPasses } from "./improve-profiles.js";
+// Eligibility / candidate-selection predicates for improve. Free functions
+// (no akmImprove closure state) extracted from improve.ts to shrink the
+// orchestrator and make candidate selection independently testable.
+export function resolveImproveScope(scope) {
+    const trimmed = scope?.trim();
+    if (!trimmed)
+        return { mode: "all" };
+    try {
+        parseAssetRef(trimmed);
+        return { mode: "ref", value: trimmed };
+    }
+    catch {
+        if (!isAssetType(trimmed)) {
+            throw new UsageError(`Unknown asset type: "${trimmed}". Valid types: memory, knowledge, skill, lesson, workflow, agent, command, script, wiki, env, secret, task.\n` +
+                `If you passed --format to akm improve, that flag is not supported — use it with akm search or akm show instead.`, "INVALID_FLAG_VALUE");
+        }
+        return { mode: "type", value: trimmed };
+    }
+}
+/**
+ * Dedupe a list of eligible refs by `ref`, preserving first-seen order. Used to
+ * merge the three eligibility sources (feedback-signal, P0-A high-retrieval,
+ * Layer-2 proactive-maintenance) without admitting a ref into the loop twice.
+ */
+export function dedupeRefs(refs) {
+    const seen = new Set();
+    const out = [];
+    for (const r of refs) {
+        if (seen.has(r.ref))
+            continue;
+        seen.add(r.ref);
+        out.push(r);
+    }
+    return out;
+}
+export async function collectEligibleRefs(scope, stashDir, improveProfile) {
+    if (scope.mode === "ref" && scope.value) {
+        const parsed = parseAssetRef(scope.value);
+        const writableDirs = new Set(getWritableStashDirs(stashDir).map((dir) => path.resolve(dir)));
+        const filePath = await findAssetFilePath(scope.value, stashDir, writableDirs);
+        if (!filePath) {
+            return {
+                plannedRefs: [],
+                memorySummary: { eligible: 0, derived: 0 },
+                profileFilteredRefs: [],
+            };
+        }
+        return {
+            plannedRefs: [{ ref: scope.value, reason: "scope-ref", filePath }],
+            memorySummary: {
+                eligible: parsed.type === "memory" ? 1 : 0,
+                derived: parsed.type === "memory" && parsed.name.endsWith(".derived") ? 1 : 0,
+            },
+            profileFilteredRefs: [],
+        };
+    }
+    let sources;
+    try {
+        sources = resolveSourceEntries(stashDir);
+    }
+    catch {
+        return { plannedRefs: [], memorySummary: { eligible: 0, derived: 0 }, profileFilteredRefs: [] };
+    }
+    if (sources.length === 0) {
+        return { plannedRefs: [], memorySummary: { eligible: 0, derived: 0 }, profileFilteredRefs: [] };
+    }
+    // Only operate on writable sources — never mutate read-only registry caches
+    // or remote stashes that the user did not mark writable.
+    let writableDirs;
+    try {
+        writableDirs = getWritableStashDirs(stashDir);
+    }
+    catch {
+        writableDirs = sources.slice(0, 1).map((s) => s.path); // fallback: primary only
+    }
+    const writableDirSet = new Set(writableDirs.map((d) => path.resolve(d)));
+    let db;
+    try {
+        db = openExistingDatabase();
+        const entries = getAllEntries(db, scope.mode === "type" ? scope.value : undefined).filter((indexed) => {
+            // First apply the existing stashDir-scope filter (no-op when stashDir is unset).
+            if (!isEntryInScope(indexed.stashDir, indexed.filePath, stashDir))
+                return false;
+            // Then restrict to writable sources only.
+            return isEntryInWritableSource(indexed.stashDir, indexed.filePath, writableDirSet);
+        });
+        const planned = new Map();
+        const profileFiltered = new Map();
+        let memoryEligible = 0;
+        let memoryDerived = 0;
+        for (const indexed of entries) {
+            const ref = makeAssetRef(indexed.entry.type, indexed.entry.name);
+            const isDerived = indexed.entry.name.endsWith(".derived");
+            // `.derived` memories are LLM-inferred and intentionally skip reflect
+            // (see the synthetic `derived-memory-reflect-skipped` branch in the
+            // improve loop). Enqueueing them here just produced one synthetic skip
+            // per derived memory per hour with no real work — pure churn observed
+            // 2026-05-21: 11 derived refs re-planned every hour during idle periods.
+            // The cleanup phase (analyzeMemoryCleanup) inspects derived memories
+            // independently of `plannedRefs`, so dropping them here loses nothing.
+            if (!isDerived && !planned.has(ref) && !profileFiltered.has(ref)) {
+                // 2026-05-27: extend the .derived precedent to profile-incompatible
+                // refs. If every per-ref pass (reflect + distill) on the active
+                // profile would refuse this ref, drop it from `plannedRefs`. The
+                // caller emits `improve_skipped { reason: profile_filtered_all_passes }`
+                // once `eventsCtx` is available so the audit trail is preserved in a
+                // single event per ref instead of 2× synthetic actions per run.
+                // Background: see /tmp/akm-health-investigations/planner-profile-metrics-deep-analysis.md
+                if (improveProfile && isProfileFilteredForAllPasses(ref, improveProfile)) {
+                    profileFiltered.set(ref, {
+                        ref,
+                        reason: "profile_filtered_all_passes",
+                        filePath: indexed.filePath,
+                    });
+                }
+                else {
+                    planned.set(ref, {
+                        ref,
+                        reason: scope.mode === "type" ? "scope-type" : indexed.entry.type === "memory" ? "memory-cleanup" : "scope-type",
+                        filePath: indexed.filePath,
+                    });
+                }
+            }
+            if (indexed.entry.type === "memory") {
+                memoryEligible += 1;
+                if (isDerived)
+                    memoryDerived += 1;
+            }
+        }
+        return {
+            plannedRefs: [...planned.values()],
+            memorySummary: { eligible: memoryEligible, derived: memoryDerived },
+            profileFilteredRefs: [...profileFiltered.values()],
+        };
+    }
+    catch (error) {
+        // The bun-test isolation guard must never be downgraded to "empty plan".
+        rethrowIfTestIsolationError(error);
+        if (error instanceof NotFoundError || error instanceof Error) {
+            return { plannedRefs: [], memorySummary: { eligible: 0, derived: 0 }, profileFilteredRefs: [] };
+        }
+        throw error;
+    }
+    finally {
+        if (db)
+            closeDatabase(db);
+    }
+}
+export function isEntryInScope(entryStashDir, filePath, stashDir) {
+    if (!stashDir)
+        return true;
+    const resolvedEntryStashDir = path.resolve(entryStashDir);
+    const resolvedFilePath = path.resolve(filePath);
+    const resolvedScopeStashDir = path.resolve(stashDir);
+    return (resolvedEntryStashDir === resolvedScopeStashDir ||
+        resolvedEntryStashDir.startsWith(`${resolvedScopeStashDir}${path.sep}`) ||
+        resolvedFilePath.startsWith(`${resolvedScopeStashDir}${path.sep}`));
+}
+/**
+ * Return true when the indexed entry belongs to one of the writable source
+ * directories. Entries from read-only registry caches or remote stashes that
+ * the user has not marked writable must never enter the improve/distill loop.
+ */
+export function isEntryInWritableSource(entryStashDir, filePath, writableDirSet) {
+    const resolvedEntryStashDir = path.resolve(entryStashDir);
+    const resolvedFilePath = path.resolve(filePath);
+    for (const writableDir of writableDirSet) {
+        if (resolvedEntryStashDir === writableDir ||
+            resolvedEntryStashDir.startsWith(`${writableDir}${path.sep}`) ||
+            resolvedFilePath.startsWith(`${writableDir}${path.sep}`)) {
+            return true;
+        }
+    }
+    return false;
+}
+export function memoryCleanupParentRef(scope, stashDir) {
+    if (scope.mode !== "ref" || !scope.value)
+        return undefined;
+    const parsed = parseAssetRef(scope.value);
+    if (parsed.type !== "memory")
+        return undefined;
+    if (!parsed.name.endsWith(".derived"))
+        return scope.value;
+    const sources = resolveSourceEntries(stashDir);
+    for (const source of sources) {
+        const candidate = path.join(source.path, "memories", `${parsed.name}.md`);
+        if (!fs.existsSync(candidate))
+            continue;
+        const raw = fs.readFileSync(candidate, "utf8");
+        const fm = parseFrontmatter(raw).data;
+        const sourceRef = typeof fm.source === "string" ? fm.source : undefined;
+        if (sourceRef) {
+            try {
+                const parent = parseAssetRef(sourceRef.trim());
+                if (parent.type === "memory")
+                    return makeAssetRef(parent.type, parent.name);
+            }
+            catch { }
+        }
+    }
+    return makeAssetRef("memory", parsed.name.slice(0, -".derived".length));
+}
+export function isLessonCandidate(ref) {
+    // Only lesson assets need lesson-schema validation (description + when_to_use).
+    // Memories have their own distill path via shouldDistillMemoryRef.
+    // All other types go through reflect, not distill.
+    return parseAssetRef(ref).type === "lesson";
+}
+/**
+ * Planner-side check: should this ref enter the distill queue?
+ *
+ * Distill produces lessons from non-lesson sources. Two cases are eligible:
+ *
+ *   1. Memory refs that pass {@link shouldDistillMemoryRef} (the existing
+ *      memory→lesson/knowledge promotion path).
+ *
+ * Refs whose `type` is in {@link DISTILL_REFUSED_INPUT_TYPES} (currently
+ * `lesson:*`) are explicitly excluded — distill refuses them at runtime and
+ * queuing them just produces a no-op `skipped` outcome per ref per hour. That
+ * planner waste was the bug fixed in commit
+ * fix(improve): drop distill-refused types from planner.
+ *
+ * Note: prior to this fix the gate used `isLessonCandidate(ref)` directly,
+ * which was true *only* for `lesson:*` refs — exactly the set distill refuses.
+ * The result: every hourly run re-queued the same lesson refs, the same skip
+ * message returned, and no work was ever done. See
+ * `tests/commands/improve-distill-planner-skip-lessons.test.ts`.
+ */
+export function isDistillCandidateRef(ref, stashDir) {
+    const parsed = parseAssetRef(ref);
+    if (isDistillRefusedInputType(parsed.type))
+        return false;
+    return shouldDistillMemoryRef(ref, stashDir);
+}
+export function shouldDistillMemoryRef(ref, stashDir) {
+    const parsed = parseAssetRef(ref);
+    if (parsed.type !== "memory")
+        return false;
+    const sources = resolveSourceEntries(stashDir);
+    for (const source of sources) {
+        const candidate = `${source.path}/memories/${parsed.name}.md`;
+        if (!fs.existsSync(candidate))
+            continue;
+        const raw = fs.readFileSync(candidate, "utf8");
+        const fm = parseFrontmatter(raw).data;
+        const quality = typeof fm.quality === "string" ? fm.quality : undefined;
+        if (quality === "proposed")
+            return false;
+        return !parsed.name.endsWith(".derived");
+    }
+    return !parsed.name.endsWith(".derived");
+}
+// ── Signal-delta eligibility helpers (0.8.0) ────────────────────────────────
+//
+// The 0.8.0 redesign replaced flat time-based cooldowns for reflect/distill
+// with a *signal-delta* gate: a ref is re-eligible iff new feedback has
+// landed since the last proposal was generated for it. These helpers build
+// the two timestamp maps the gate needs in bulk, so the planner avoids
+// N+1 queries across the full postCleanupRefs set.
+/**
+ * Latest feedback event timestamp per ref in the active window. Reads all
+ * `feedback` events newer than `sinceIso` in one query and indexes by ref,
+ * keeping the maximum `ts` per ref.
+ *
+ * Only events with a meaningful payload count as "signal" — `metadata.signal`
+ * (positive/negative) OR `metadata.note` (a free-form annotation). Empty
+ * metadata events are ignored so a stray `akm feedback <ref>` invocation
+ * without a flag doesn't trigger downstream re-processing.
+ */
+export function buildLatestFeedbackTsMap(refs, sinceIso) {
+    const out = new Map();
+    if (refs.length === 0)
+        return out;
+    const refSet = new Set(refs);
+    const { events } = readEvents({ type: "feedback", since: sinceIso });
+    for (const e of events) {
+        const ref = e.ref;
+        if (!ref || !refSet.has(ref))
+            continue;
+        const meta = e.metadata;
+        const hasSignal = meta !== undefined && (typeof meta.signal === "string" || typeof meta.note === "string");
+        if (!hasSignal)
+            continue;
+        const ts = e.ts ?? "";
+        if (ts > (out.get(ref) ?? ""))
+            out.set(ref, ts);
+    }
+    return out;
+}
+/**
+ * Latest proposal timestamp per input-ref, filtered by source ('reflect' or
+ * 'distill'). Reads the corresponding `*_invoked` events from state.db —
+ * these events are emitted at proposal creation time and carry the *input*
+ * asset ref (memory:foo, skill:bar, etc.) directly. We use them rather than
+ * `listProposals` because distill proposals are keyed by the derived
+ * lesson/knowledge ref, not the source memory — joining back through the
+ * payload would be fragile.
+ */
+export function buildLatestProposalTsMap(refs, source) {
+    const out = new Map();
+    if (refs.length === 0)
+        return out;
+    const refSet = new Set(refs);
+    const eventType = source === "reflect" ? "reflect_invoked" : "distill_invoked";
+    const { events } = readEvents({ type: eventType });
+    for (const e of events) {
+        const ref = e.ref;
+        if (!ref || !refSet.has(ref))
+            continue;
+        // For distill_invoked we only count attempts that produced (or attempted
+        // to produce) a real proposal — config_disabled / parse-error outcomes
+        // should not move the signal-delta cursor forward.
+        if (eventType === "distill_invoked") {
+            const outcome = e.metadata?.outcome;
+            if (outcome !== "queued" && outcome !== "skipped" && outcome !== "validation_failed")
+                continue;
+        }
+        const ts = e.ts ?? "";
+        if (ts > (out.get(ref) ?? ""))
+            out.set(ref, ts);
+    }
+    return out;
+}
+/**
+ * Signal-delta eligibility predicate.
+ *
+ * True iff `latestFeedback[ref]` is defined AND either no prior proposal
+ * exists for this (ref, source) OR `latestFeedback[ref] > lastProposal[ref]`.
+ *
+ * Refs with no feedback signal at all are ineligible by definition — the
+ * high-retrieval fallback path (see `noFeedbackCandidates` later in the
+ * planner) handles never-touched-but-frequently-read assets separately.
+ */
+export function isSignalDeltaEligible(ref, latestFeedback, lastProposal) {
+    const fb = latestFeedback.get(ref);
+    if (!fb)
+        return false;
+    const lp = lastProposal.get(ref);
+    if (!lp)
+        return true;
+    return fb > lp;
+}
+/**
+ * H7 (#566): cooperative budget watchdog with a captured, RAII-cleared hard-kill.
+ *
+ * When the wall-clock budget expires, `onExhausted` (normally an
+ * `AbortController.abort`) signals cooperative cancellation so the run can drain
+ * its in-flight log/`state.db` flush and unwind naturally. A second hard-kill
+ * timer is then armed as a watchdog: it only `exit(0)`s if the drain itself
+ * overruns `hardKillGraceMs`, preventing the process from outliving the task
+ * timeout window (lock-cascade fix).
+ *
+ * Both timers are captured; the returned dispose() clears whichever is still
+ * pending. Callers invoke it from a `finally`, so a *clean* drain reaches the
+ * `finally` and cancels the pending hard-kill before it can fire — the previous
+ * detached `setTimeout(() => process.exit(0), 5000)` always fired, truncating a
+ * clean flush. The hard-kill timer is `unref()`-ed so it never keeps the event
+ * loop alive on its own: once the run drains it exits with its own code, not the
+ * forced 0.
+ *
+ * Dependencies are injectable purely so the concurrency-sensitive timing
+ * contract can be exercised deterministically in unit tests.
+ */
+export function shouldAnalyzeMemoryCleanup(scope, eligibleMemories, primaryStashDir) {
+    if (!primaryStashDir || eligibleMemories === 0)
+        return false;
+    if (scope.mode === "all")
+        return true;
+    if (scope.mode === "type")
+        return scope.value === "memory";
+    if (!scope.value)
+        return false;
+    return parseAssetRef(scope.value).type === "memory";
+}
+export function buildUtilityMap(refs) {
+    const map = new Map();
+    if (refs.length === 0)
+        return map;
+    const refSet = new Set(refs.map((r) => r.ref));
+    let db;
+    try {
+        db = openExistingDatabase();
+        const allDbEntries = getAllEntries(db);
+        const idToRef = new Map();
+        for (const indexed of allDbEntries) {
+            const ref = makeAssetRef(indexed.entry.type, indexed.entry.name);
+            if (refSet.has(ref))
+                idToRef.set(indexed.id, ref);
+        }
+        const ids = [...idToRef.keys()];
+        if (ids.length > 0) {
+            const { global: scores } = getUtilityScoresByIds(db, ids);
+            for (const [id, score] of scores) {
+                const ref = idToRef.get(id);
+                if (ref)
+                    map.set(ref, score.utility);
+            }
+        }
+    }
+    catch (err) {
+        rethrowIfTestIsolationError(err);
+        // best-effort: if DB unavailable, all utilities default to 0
+    }
+    finally {
+        if (db)
+            closeDatabase(db);
+    }
+    return map;
+}
+export async function findAssetFilePath(ref, stashDir, writableDirSet) {
+    return resolveAssetPath(ref, {
+        stashDir,
+        mode: "disk-only",
+        writableDirSet,
+        directoryIndexNames: ["SKILL.md"],
+        preserveDirectNameFallback: true,
+        honorOrigin: false,
+    });
+}

package/dist/commands/improve/encoding-salience.js

@@ -0,0 +1,205 @@
+// 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/.
+/**
+ * Encoding-time salience scoring for issue #608.
+ *
+ * Pure module — no I/O. All inputs are pre-fetched by the caller.
+ * Implements the three-signal model: novelty × 0.40 + magnitude × 0.35 +
+ * predictionError × 0.25, clamped to [0, 1].
+ */
+// ── Weights ────────────────────────────────────────────────────────────────────
+const W_NOVELTY = 0.4;
+const W_MAGNITUDE = 0.35;
+const W_PREDICTION_ERROR = 0.25;
+// Guard: weights must sum to 1.0 (consistent with the pattern in salience.ts).
+// This check fires at module load and catches any future re-tuning mistakes.
+if (Math.abs(W_NOVELTY + W_MAGNITUDE + W_PREDICTION_ERROR - 1.0) > 1e-9) {
+    throw new Error(`encoding-salience.ts: sub-signal weights must sum to 1.0 (got ${W_NOVELTY + W_MAGNITUDE + W_PREDICTION_ERROR})`);
+}
+// ── Novelty type floors ────────────────────────────────────────────────────────
+const TYPE_NOVELTY_FLOOR = Object.freeze({
+    skill: 0.8,
+    agent: 0.8,
+    memory: 0.4,
+});
+const DEFAULT_NOVELTY_FLOOR = 0.5;
+// ── Magnitude keyword sets ──────────────────────────────────────────────────────
+const SEVERITY_BUCKET = new Set(["error", "critical", "warning", "incident", "regression"]);
+// Note: "fails" and "urgent" are from the spec's initial keyword list and are included
+// here as strong constraint signals, even though the spec's final bucket table omits them.
+const CONSTRAINT_BUCKET = new Set(["must", "never", "always", "blocked", "breaking", "deprecated", "fails", "urgent"]);
+const ALL_MAGNITUDE_KEYWORDS = new Set([...SEVERITY_BUCKET, ...CONSTRAINT_BUCKET]);
+// Number of distinct keyword matches to reach full magnitude score.
+const MAGNITUDE_FULL_SCORE_THRESHOLD = 4;
+// Single-bucket magnitude cap: when only one semantic bucket matches.
+const MAGNITUDE_SINGLE_BUCKET_CAP = 0.5;
+// ── Stop-words (excluded from bigram tokenization) ────────────────────────────
+const STOP_WORDS = new Set([
+    "a",
+    "an",
+    "the",
+    "and",
+    "or",
+    "but",
+    "in",
+    "on",
+    "at",
+    "to",
+    "for",
+    "of",
+    "with",
+    "by",
+    "from",
+    "as",
+    "is",
+    "it",
+    "its",
+    "be",
+    "are",
+    "was",
+    "were",
+    "has",
+    "have",
+    "had",
+    "do",
+    "does",
+    "did",
+    "not",
+    "this",
+    "that",
+    "these",
+    "those",
+    "i",
+    "we",
+    "you",
+    "he",
+    "she",
+    "they",
+    "my",
+    "our",
+    "your",
+    "his",
+    "her",
+    "their",
+    "can",
+    "will",
+    "would",
+    "should",
+    "could",
+    "may",
+    "might",
+    "shall",
+    "so",
+    "if",
+    "then",
+    "than",
+    "when",
+    "while",
+    "what",
+    "which",
+    "who",
+    "how",
+    "no",
+    "any",
+    "all",
+    "more",
+    "also",
+]);
+// ── Tokenization helpers ──────────────────────────────────────────────────────
+/**
+ * Tokenize text into lowercase words, splitting on whitespace and punctuation,
+ * dropping stop-words. Used for body bigram extraction (novelty signal).
+ */
+function tokenizeBody(text) {
+    return text
+        .toLowerCase()
+        .split(/[\s\p{P}\p{S}\-_/]+/u)
+        .filter((t) => t.length > 1 && !STOP_WORDS.has(t));
+}
+/**
+ * Tokenize a ref name or tag into lowercase words without stop-word filtering.
+ * Ref names are identifiers, not prose — all tokens are significant.
+ */
+function tokenizeRef(ref) {
+    return ref
+        .toLowerCase()
+        .split(/[\s\p{P}\p{S}\-_/]+/u)
+        .filter((t) => t.length > 0);
+}
+/**
+ * Generate all consecutive bigrams from an array of tokens.
+ * Returns them as "token1 token2" strings.
+ */
+function bigrams(tokens) {
+    const result = [];
+    for (let i = 0; i < tokens.length - 1; i++) {
+        result.push(`${tokens[i]} ${tokens[i + 1]}`);
+    }
+    return result;
+}
+/**
+ * Build the existing-ref vocabulary: a Set of bigrams derived from tokenizing
+ * the provided ref names (and tags). Pass this to `scoreEncodingSalience` as
+ * `existingRefVocabulary` so the novelty signal can measure how much of the
+ * asset body is already represented in the stash vocabulary.
+ */
+export function buildRefVocabulary(refs) {
+    const vocab = new Set();
+    for (const ref of refs) {
+        const tokens = tokenizeRef(ref);
+        for (const bg of bigrams(tokens)) {
+            vocab.add(bg);
+        }
+    }
+    return vocab;
+}
+// ── Sub-signal computations ────────────────────────────────────────────────────
+function computeNovelty(body, type, vocab) {
+    const tokens = tokenizeBody(body);
+    const bgs = bigrams(tokens);
+    const floor = TYPE_NOVELTY_FLOOR[type] ?? DEFAULT_NOVELTY_FLOOR;
+    if (bgs.length === 0)
+        return floor;
+    const novelCount = bgs.filter((bg) => !vocab.has(bg)).length;
+    const bigramNoveltyFraction = novelCount / bgs.length;
+    return Math.max(floor, bigramNoveltyFraction);
+}
+function computeMagnitude(body) {
+    const lowerBody = body.toLowerCase();
+    // Split on word boundaries to avoid partial matches (e.g. "errors" matching "error").
+    const words = new Set(lowerBody.split(/\W+/).filter((w) => w.length > 0));
+    const matched = [...ALL_MAGNITUDE_KEYWORDS].filter((kw) => words.has(kw));
+    if (matched.length === 0)
+        return 0;
+    const distinctCount = matched.length;
+    const rawMagnitude = Math.min(1.0, distinctCount / MAGNITUDE_FULL_SCORE_THRESHOLD);
+    // Require at least one match from each bucket to lift the single-bucket cap.
+    const hasSeverity = matched.some((kw) => SEVERITY_BUCKET.has(kw));
+    const hasConstraint = matched.some((kw) => CONSTRAINT_BUCKET.has(kw));
+    if (hasSeverity && hasConstraint)
+        return rawMagnitude;
+    return Math.min(rawMagnitude, MAGNITUDE_SINGLE_BUCKET_CAP);
+}
+function computePredictionError(revisionCount) {
+    if (revisionCount === 0)
+        return 1.0;
+    return 1 / (1 + Math.log(1 + revisionCount));
+}
+// ── Main export ────────────────────────────────────────────────────────────────
+/**
+ * Compute the encoding-time salience score for an asset.
+ *
+ * Three sub-signals:
+ *   novelty (0.40) — how much of the body is absent from the stash vocabulary.
+ *   magnitude (0.35) — presence of severity/constraint keywords.
+ *   predictionError (0.25) — surprise: high for new assets, decays with revisions.
+ */
+export function scoreEncodingSalience(inputs) {
+    const novelty = computeNovelty(inputs.body, inputs.type, inputs.existingRefVocabulary);
+    const magnitude = computeMagnitude(inputs.body);
+    const predictionError = computePredictionError(inputs.revisionCount);
+    const raw = W_NOVELTY * novelty + W_MAGNITUDE * magnitude + W_PREDICTION_ERROR * predictionError;
+    const score = Math.min(1, Math.max(0, raw));
+    return { score, novelty, magnitude, predictionError };
+}