akm-cli 0.9.16 → 0.9.17-alpha.10

package/dist/commands/improve/outcome-loop.js

@@ -2,85 +2,37 @@
 // 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 { getAllAssetOutcomes, getAssetOutcome, getOutcomeScoresByRef, upsertAssetOutcome, } from "../../storage/repositories/outcome-repository.js";
-// ── Constants ─────────────────────────────────────────────────────────────────
-/**
- * EMA decay factor for the expected-retrieval rolling mean (α).
- * New expected = α × new_count + (1−α) × old_expected.
- * At α = 0.3 the window is ≈ 3 cycles.
- */
+/** EMA factor for both the score and the expected retrieval delta (≈ a 3-cycle window). */
 export const OUTCOME_EMA_ALPHA = 0.3;
-/**
- * Warm-start cap: the maximum `outcome_score` a brand-new row can be seeded with
- * (from the utility EMA). Prevents a `[0,1]`-range utility value from generating
- * a score that the first negative delta could catastrophically invert. Clipped to
- * the maximum plausible first differential update: `max(0, 1 − 0) = 1`, so cap
- * at a modest 0.3 to avoid spurious rank-flip on first cycle.
- */
+/** The most a new row can be seeded with, so the first negative delta cannot flip the rank. */
 export const WARM_START_CAP = 0.3;
-/**
- * Penalty cap: the minimum outcome_score is capped at this value so a single
- * very-negative run can't send the score to −∞.
- */
 export const OUTCOME_SCORE_MIN = -1.0;
-/**
- * Saturation ceiling: the maximum outcome_score. Biological RPE saturates —
- * a fully predicted reward produces zero response, not an ever-growing one —
- * so a long-lived popular asset must not accrue unbounded outcome mass that
- * would dominate ranking once the outcome weight is enabled (analysis G2).
- * 1.5 comfortably exceeds the max plausible single-cycle raw update while
- * keeping the normalised outcomeSalience spread meaningful.
- */
+/** Saturation: a long-popular asset must not accrue unbounded outcome mass. */
 export const OUTCOME_SCORE_MAX = 1.5;
-/**
- * Diversity floor: `outcomeSalience` for any asset is at least this fraction
- * of the maximum observed `outcome_score` in the table, so rare-but-correct
- * assets cannot be permanently outcompeted. 0 = disabled (pure competition).
- */
+/** `outcomeSalience` never drops below this fraction of the stash-wide maximum. */
 export const DIVERSITY_FLOOR_FRACTION = 0.1;
-/**
- * Project the next outcome values without touching storage. Dry planning and
- * the live writer both call this function, so rank inputs cannot drift merely
- * because one caller persists the projection and the other does not.
- */
+export { getAllAssetOutcomes, getAssetOutcome, getOutcomeScoresByRef };
+/** The next outcome values, without storage — dry planning and the writer share it. */
 export function projectAssetOutcome(existing, inputs) {
-    const valence = inputs.valence ?? 0;
-    const isNewRow = existing === undefined;
-    let outcomeScore;
-    let expectedRetrievalRate;
-    if (isNewRow) {
-        const seedScore = Math.min(WARM_START_CAP, Math.max(0, inputs.utilityScore ?? 0));
-        outcomeScore = seedScore;
-        expectedRetrievalRate = 0;
+    if (existing === undefined) {
+        return {
+            outcomeScore: Math.min(WARM_START_CAP, Math.max(0, inputs.utilityScore ?? 0)),
+            expectedRetrievalRate: 0,
+            isNewRow: true,
+        };
     }
-    else {
-        const retrievalDelta = Math.max(0, inputs.currentRetrievalCount - existing.retrieval_count);
-        const expectedDelta = existing.expected_retrieval_rate;
-        const predictionError = retrievalDelta - expectedDelta;
-        expectedRetrievalRate =
-            OUTCOME_EMA_ALPHA * retrievalDelta + (1 - OUTCOME_EMA_ALPHA) * existing.expected_retrieval_rate;
-        const rawUpdate = predictionError + valence;
-        const newScore = OUTCOME_EMA_ALPHA * rawUpdate + (1 - OUTCOME_EMA_ALPHA) * existing.outcome_score;
-        outcomeScore = Math.min(OUTCOME_SCORE_MAX, Math.max(OUTCOME_SCORE_MIN, newScore));
-    }
-    return { outcomeScore, expectedRetrievalRate, isNewRow };
+    const retrievalDelta = Math.max(0, inputs.currentRetrievalCount - existing.retrieval_count);
+    const rawUpdate = retrievalDelta - existing.expected_retrieval_rate + (inputs.valence ?? 0);
+    const newScore = OUTCOME_EMA_ALPHA * rawUpdate + (1 - OUTCOME_EMA_ALPHA) * existing.outcome_score;
+    return {
+        outcomeScore: Math.min(OUTCOME_SCORE_MAX, Math.max(OUTCOME_SCORE_MIN, newScore)),
+        expectedRetrievalRate: OUTCOME_EMA_ALPHA * retrievalDelta + (1 - OUTCOME_EMA_ALPHA) * existing.expected_retrieval_rate,
+        isNewRow: false,
+    };
 }
-/**
- * Upsert one asset's outcome row.
- *
- * On first call for a ref (no prior row): warm-starts from `utilityScore`.
- * On subsequent calls: applies the differential update formula.
- *
- * Returns the resulting `outcome_score` so the caller can pass it to
- * `computeSalience` without a second read.
- */
+/** Upsert one asset's outcome row; returns the score for the salience vector. */
 export function updateAssetOutcome(db, inputs) {
-    const now = inputs.now ?? Date.now();
-    const existing = getAssetOutcome(db, inputs.ref);
-    const projection = projectAssetOutcome(existing, inputs);
-    // Upsert the row. See `upsertAssetOutcome` in
-    // storage/repositories/outcome-repository.ts (#672 part 2) for the SQL text
-    // and the `review_pressure` omission rationale — this call site is
-    // unchanged in intent, just no longer inline.
+    const projection = projectAssetOutcome(getAssetOutcome(db, inputs.ref), inputs);
     upsertAssetOutcome(db, {
         ref: inputs.ref,
         lastRetrievedAt: inputs.lastRetrievedAt,
@@ -89,97 +41,17 @@ export function updateAssetOutcome(db, inputs) {
         negativeFeedbackCount: inputs.negativeFeedbackCount,
         acceptedChangeCount: inputs.acceptedChangeCount,
         outcomeScore: projection.outcomeScore,
-        updatedAt: now,
+        updatedAt: inputs.now ?? Date.now(),
     });
     return { outcomeScore: projection.outcomeScore, isNewRow: projection.isNewRow };
 }
-// ── Reader ────────────────────────────────────────────────────────────────────
-//
-// getAssetOutcome / getAllAssetOutcomes / getOutcomeScoresByRef moved verbatim
-// to storage/repositories/outcome-repository.ts (#672 part 2) — re-exported
-// here so existing importers of this module resolve unchanged.
-export { getAllAssetOutcomes, getAssetOutcome, getOutcomeScoresByRef };
-// ── outcomeSalience projection ────────────────────────────────────────────────
 /**
- * Convert a raw `outcome_score` (differential, may be negative) to a
- * `outcomeSalience` value in [0, 1] suitable for use in the salience projection.
- *
- * Approach:
- *   1. Clip negative scores to 0 (a negative outcome just means "below expected",
- *      not "irrelevant"; it should not harm the base retrieval/encoding ranking).
- *   2. Apply the diversity floor so rare-but-correct assets always retain a
- *      minimum `outcomeSalience` relative to the stash-wide maximum.
- *   3. Normalise by `maxScore` (the stash-wide max outcome_score) so the term
- *      lives in [0, 1]. When maxScore ≤ 0 (all seeds, nothing observed yet),
- *      return the floor (or 0 if DIVERSITY_FLOOR_FRACTION = 0).
- *
- * @param outcomeScore - Raw outcome_score from asset_outcome.
- * @param maxScore     - Maximum outcome_score across ALL rows (≥ 0 after clip).
- *                       Callers must compute this once per batch and pass it in.
+ * A raw outcome score as salience in [0, 1]: negatives clip to 0 (below
+ * expected is not irrelevant), normalized by the stash-wide maximum, never
+ * below the diversity floor.
  */
 export function outcomeScoreToSalience(outcomeScore, maxScore) {
-    const clipped = Math.max(0, outcomeScore);
-    if (maxScore <= 0) {
-        // No positive scores observed yet — return diversity floor.
+    if (maxScore <= 0)
         return DIVERSITY_FLOOR_FRACTION;
-    }
-    const normalised = clipped / maxScore;
-    // Apply diversity floor.
-    return Math.max(DIVERSITY_FLOOR_FRACTION, normalised);
-}
-// ── Proxy-adequacy tripwire ───────────────────────────────────────────────────
-/**
- * Dead-proxy threshold: |corr| below this means outcome_score carries no
- * information about improvement need (pure noise).
- */
-export const PROXY_DEAD_CORR_THRESHOLD = 0.1;
-/**
- * Minimum sample size before the dead-proxy check fires. Below this, a
- * near-zero correlation is indistinguishable from small-sample noise.
- */
-export const PROXY_DEAD_MIN_N = 500;
-/**
- * Compute `corr(outcome_score, accepted_change_rate)` across all asset_outcome
- * rows. Returns `{correlation: NaN, n, isInverted: false}` when there is
- * insufficient data (fewer than 3 rows or zero variance in either variable).
- *
- * A NEGATIVE correlation means: assets with a HIGH outcome_score have a LOW
- * accepted_change_rate — i.e. the assets the proxy rates as "doing well"
- * (frequently retrieved) are precisely the ones that rarely yield an accepted
- * improvement. That inverts the proxy: high outcome_score ≠ "doing well", so the
- * coarse retrieval-delta signal is no longer trustworthy and the 0.10+ rich
- * signal is due. (`isInverted = correlation < -0.3`.)
- */
-export function computeProxyAdequacy(rows) {
-    const n = rows.length;
-    if (n < 3)
-        return { correlation: Number.NaN, n, isInverted: false, isDead: false };
-    // accepted_change_rate per row.
-    const xs = rows.map((r) => r.outcome_score);
-    const ys = rows.map((r) => r.accepted_change_count / Math.max(1, r.retrieval_count));
-    const meanX = xs.reduce((a, b) => a + b, 0) / n;
-    const meanY = ys.reduce((a, b) => a + b, 0) / n;
-    let covXY = 0;
-    let varX = 0;
-    let varY = 0;
-    for (let i = 0; i < n; i++) {
-        const dx = xs[i] - meanX;
-        const dy = ys[i] - meanY;
-        covXY += dx * dy;
-        varX += dx * dx;
-        varY += dy * dy;
-    }
-    covXY /= n;
-    varX /= n;
-    varY /= n;
-    const denom = Math.sqrt(varX) * Math.sqrt(varY);
-    if (denom < 1e-12)
-        return { correlation: Number.NaN, n, isInverted: false, isDead: false };
-    const correlation = covXY / denom;
-    // Inverted proxy: negative correlation between outcome and accepted_change_rate
-    // means high-outcome assets are also high-need — the opposite of "useful".
-    const isInverted = correlation < -0.3;
-    // Dead proxy: near-zero correlation at scale — the score is noise.
-    const isDead = n >= PROXY_DEAD_MIN_N && Math.abs(correlation) < PROXY_DEAD_CORR_THRESHOLD;
-    return { correlation, n, isInverted, isDead };
+    return Math.max(DIVERSITY_FLOOR_FRACTION, Math.max(0, outcomeScore) / maxScore);
 }

package/dist/commands/improve/planner.js

@@ -42,10 +42,7 @@ export function projectMemoryCleanup(input) {
         },
     };
 }
-/**
- * Apply the final global cap to an already-ranked candidate snapshot.
- * Replay remains additive to the ordinary cap, matching the live #610 rule.
- */
+/** Apply the final global cap to an already-ranked candidate snapshot. */
 export function selectEffectiveImproveRefs(args) {
     const distillOnlySet = new Set(args.distillOnlyRefs.map((entry) => entry.ref));
     const reflectAndDistill = args.rankedRefs.filter((entry) => !distillOnlySet.has(entry.ref));
@@ -53,10 +50,7 @@ export function selectEffectiveImproveRefs(args) {
     // Preserve the established live ordering: ordinary reflect-path refs first,
     // then distill-only refs, with the rank order stable inside each partition.
     const allLoopRefs = [...reflectAndDistill, ...distillOnly];
-    const replay = allLoopRefs.filter((entry) => entry.eligibilitySource === "replay");
-    const ordinary = allLoopRefs.filter((entry) => entry.eligibilitySource !== "replay");
-    const selectedOrdinary = args.limit === undefined ? ordinary : ordinary.slice(0, args.limit);
-    const loopRefs = [...selectedOrdinary, ...replay.slice(0, args.replayBudget)];
+    const loopRefs = args.limit === undefined ? allLoopRefs : allLoopRefs.slice(0, args.limit);
     return {
         loopRefs,
         distillOnlyRefs: distillOnly,
@@ -82,8 +76,9 @@ export function buildImproveExecutionPlan(input) {
         limits: {
             configured: { ...input.configuredLimits },
             ...(input.effectiveLimit !== undefined ? { effective: input.effectiveLimit } : {}),
-            additiveReplayAllowance: input.replayBudget,
-            ...(input.effectiveLimit !== undefined ? { totalCeiling: input.effectiveLimit + input.replayBudget } : {}),
+            // The replay lane is gone; the published plan keeps a zero allowance.
+            additiveReplayAllowance: 0,
+            ...(input.effectiveLimit !== undefined ? { totalCeiling: input.effectiveLimit } : {}),
         },
         gates: input.gates.map((gate) => ({ ...gate })),
         effectiveRefs,
@@ -119,11 +114,6 @@ export function buildImproveExecutionPlan(input) {
                 wouldRun: input.stageConfig.extract.enabled,
                 reason: input.stageConfig.extract.reason,
             },
-            {
-                name: "graph-extraction",
-                wouldRun: input.stageConfig.graphExtraction.enabled,
-                reason: input.stageConfig.graphExtraction.reason,
-            },
             {
                 name: "memory-inference",
                 wouldRun: input.stageConfig.memoryInference.enabled,