akm-cli 0.9.1 → 0.9.2-alpha.2

package/dist/commands/improve/memory/memory-contradiction-detect.js

@@ -38,10 +38,9 @@ import path from "node:path";
 import contradictionJudgeTemplate from "../../../assets/prompts/contradiction-judge.md" with { type: "text" };
 import { mutateFrontmatter, parseFrontmatter } from "../../../core/asset/frontmatter.js";
 import { parseEmbeddedJsonResponse } from "../../../core/parse.js";
-import { getDefaultLlmConfig } from "../../../integrations/agent/engine-resolution.js";
-import { materializeLlmRunnerConnection, resolveImproveProcessRunner } from "../../../integrations/agent/runner.js";
-import { chatCompletion } from "../../../llm/client.js";
-import { callStructured } from "../../../llm/structured-call.js";
+import { disposeLoweredExecutionDispatchLease } from "../../../integrations/agent/execution-lowering.js";
+import { callStructured, preflightStructuredLlmRunner } from "../../../llm/structured-call.js";
+import { resolveImproveLlmExecution } from "../execution.js";
 import { isDerivedMemory, memoryIdentityRef, resolveParentRef } from "./derived-ref.js";
 // ── Constants ────────────────────────────────────────────────────────────────
 /**
@@ -153,23 +152,30 @@ function pickContradictionLoser(a, b) {
  *
  * @param stashDir - Root stash directory.
  * @param config   - Loaded AKM config (used to access LLM settings).
- * @param chat     - Optional chat seam for testing (defaults to chatCompletion).
+ * @param chat     - Optional test-only chat seam.
  */
-export async function detectAndWriteContradictions(stashDir, config, chat = chatCompletion, strategy, resolvedLlmConfig) {
+export async function detectAndWriteContradictions(stashDir, config, chat, strategy, resolvedRunner) {
     const result = {
         familiesExamined: 0,
         pairsChecked: 0,
         edgesWritten: 0,
         warnings: [],
     };
-    const contradictionLlm = resolvedLlmConfig === null
-        ? undefined
-        : (resolvedLlmConfig ??
-            (() => {
-                const runner = resolveImproveProcessRunner(strategy, "consolidate", config);
-                return runner ? materializeLlmRunnerConnection(runner) : getDefaultLlmConfig(config);
-            })());
-    if (!contradictionLlm)
+    if (!(strategy?.processes?.consolidate?.contradictionDetection?.enabled ?? false))
+        return result;
+    const noticesByKey = new Map();
+    const resolvedExecution = resolvedRunner === undefined
+        ? resolveImproveLlmExecution({
+            config,
+            profile: strategy,
+            process: strategy?.processes?.consolidate,
+            processName: "memory-contradiction-detection",
+        })
+        : null;
+    for (const notice of resolvedExecution?.notices ?? [])
+        noticesByKey.set(JSON.stringify(notice), notice);
+    const contradictionRunner = resolvedRunner === null ? undefined : (resolvedRunner ?? resolvedExecution?.runner);
+    if (!contradictionRunner)
         return result;
     // Collect derived memories grouped by parent.
     const memoriesDir = path.join(stashDir, "memories");
@@ -208,7 +214,7 @@ export async function detectAndWriteContradictions(stashDir, config, chat = chat
         family.push(entry);
         byParent.set(parentRef, family);
     }
-    let totalPairsChecked = 0;
+    const candidatePairs = [];
     for (const [, family] of byParent) {
         if (family.length < 2)
             continue;
@@ -219,7 +225,7 @@ export async function detectAndWriteContradictions(stashDir, config, chat = chat
         result.familiesExamined++;
         for (let i = 0; i < family.length - 1; i++) {
             for (let j = i + 1; j < family.length; j++) {
-                if (totalPairsChecked >= MAX_PAIRS_PER_RUN)
+                if (candidatePairs.length >= MAX_PAIRS_PER_RUN)
                     break;
                 const a = family[i];
                 const b = family[j];
@@ -237,58 +243,76 @@ export async function detectAndWriteContradictions(stashDir, config, chat = chat
                 const loserCB = Array.isArray(loserData.contradictedBy) ? loserData.contradictedBy : [];
                 if (loserCB.includes(winnerRef))
                     continue;
-                const prompt = buildContradictionJudgePrompt(a, b);
-                const judgeResult = await callStructured({
-                    feature: "memory_contradiction_detection",
-                    akmConfig: config,
-                    // Resolver-less key: the strategy decision IS the gate (default-off).
-                    enabled: strategy?.processes?.consolidate?.contradictionDetection?.enabled ?? false,
-                    config: contradictionLlm,
-                    messages: [
-                        { role: "system", content: "Return only valid JSON. No prose." },
-                        { role: "user", content: prompt },
-                    ],
-                    request: { chat },
-                    parse: (raw) => raw ?? null,
-                    // A transport throw used to escape the gated fn into the gate's
-                    // catch and take the null fallback ("skip"); onError reproduces it.
-                    onError: () => null,
-                    fallback: null, // null means "skip" — gate disabled or LLM call failed.
-                });
-                totalPairsChecked++;
-                result.pairsChecked++;
-                if (!judgeResult)
-                    continue; // Feature gate disabled or LLM call failed.
-                let parsed = null;
-                try {
-                    parsed = parseEmbeddedJsonResponse(judgeResult);
-                }
-                catch {
-                    result.warnings.push(`Could not parse contradiction judge response for pair ${a.ref} / ${b.ref}`);
-                    continue;
-                }
-                if (!parsed?.contradicts)
-                    continue;
-                const confidence = typeof parsed.confidence === "number" ? parsed.confidence : 0;
-                if (confidence < CONTRADICT_CONFIDENCE_THRESHOLD) {
-                    result.warnings.push(`Pair ${a.ref} / ${b.ref}: confidence ${confidence.toFixed(2)} below ${CONTRADICT_CONFIDENCE_THRESHOLD} threshold — skipped.`);
-                    continue;
-                }
-                // Write a SINGLE directed contradiction edge: the losing (older) memory
-                // gets `contradictedBy` pointing to the winner. A mutual A↔B pair forms
-                // a 2-cycle that the SCC resolver refreshes back to active, erasing the
-                // contradiction every run (see pickContradictionLoser).
-                try {
-                    const wrote = writeContradictedByEdge(loser.filePath, winnerRef);
-                    result.edgesWritten += wrote ? 1 : 0;
-                }
-                catch (err) {
-                    result.warnings.push(`Failed to write contradiction edge ${loser.ref} -> ${winnerRef}: ${err instanceof Error ? err.message : String(err)}`);
-                }
+                candidatePairs.push({ a, b, loser, winnerRef });
             }
-            if (totalPairsChecked >= MAX_PAIRS_PER_RUN)
+            if (candidatePairs.length >= MAX_PAIRS_PER_RUN)
                 break;
         }
     }
-    return result;
+    if (candidatePairs.length === 0) {
+        const notices = Object.freeze([...noticesByKey.values()]);
+        return notices.length > 0 ? { ...result, notices } : result;
+    }
+    const dispatchLease = await preflightStructuredLlmRunner(contradictionRunner);
+    try {
+        for (const { a, b, loser, winnerRef } of candidatePairs) {
+            const prompt = buildContradictionJudgePrompt(a, b);
+            const judgeResult = await callStructured({
+                feature: "memory_contradiction_detection",
+                akmConfig: config,
+                // Resolver-less key: the strategy decision IS the gate (default-off).
+                enabled: true,
+                runner: contradictionRunner,
+                lease: dispatchLease,
+                messages: [
+                    { role: "system", content: "Return only valid JSON. No prose." },
+                    { role: "user", content: prompt },
+                ],
+                ...(chat ? { request: { chat } } : {}),
+                onNotices: (notices) => {
+                    for (const notice of notices)
+                        noticesByKey.set(JSON.stringify(notice), notice);
+                },
+                parse: (raw) => raw ?? null,
+                // A transport throw used to escape the gated fn into the gate's
+                // catch and take the null fallback ("skip"); onError reproduces it.
+                onError: () => null,
+                fallback: null, // null means "skip" — gate disabled or LLM call failed.
+            });
+            result.pairsChecked++;
+            if (!judgeResult)
+                continue; // Feature gate disabled or LLM call failed.
+            let parsed = null;
+            try {
+                parsed = parseEmbeddedJsonResponse(judgeResult);
+            }
+            catch {
+                result.warnings.push(`Could not parse contradiction judge response for pair ${a.ref} / ${b.ref}`);
+                continue;
+            }
+            if (!parsed?.contradicts)
+                continue;
+            const confidence = typeof parsed.confidence === "number" ? parsed.confidence : 0;
+            if (confidence < CONTRADICT_CONFIDENCE_THRESHOLD) {
+                result.warnings.push(`Pair ${a.ref} / ${b.ref}: confidence ${confidence.toFixed(2)} below ${CONTRADICT_CONFIDENCE_THRESHOLD} threshold — skipped.`);
+                continue;
+            }
+            // Write a SINGLE directed contradiction edge: the losing (older) memory
+            // gets `contradictedBy` pointing to the winner. A mutual A↔B pair forms
+            // a 2-cycle that the SCC resolver refreshes back to active, erasing the
+            // contradiction every run (see pickContradictionLoser).
+            try {
+                const wrote = writeContradictedByEdge(loser.filePath, winnerRef);
+                result.edgesWritten += wrote ? 1 : 0;
+            }
+            catch (err) {
+                result.warnings.push(`Failed to write contradiction edge ${loser.ref} -> ${winnerRef}: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+    }
+    finally {
+        disposeLoweredExecutionDispatchLease(dispatchLease);
+    }
+    const notices = Object.freeze([...noticesByKey.values()]);
+    return notices.length > 0 ? { ...result, notices } : result;
 }

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

@@ -44,61 +44,45 @@ export const OUTCOME_SCORE_MAX = 1.5;
  */
 export const DIVERSITY_FLOOR_FRACTION = 0.1;
 /**
- * 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.
+ * 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 function updateAssetOutcome(db, inputs) {
-    const now = inputs.now ?? Date.now();
+export function projectAssetOutcome(existing, inputs) {
     const valence = inputs.valence ?? 0;
-    // Fetch existing row (or undefined for first insert).
-    const existing = getAssetOutcome(db, inputs.ref);
     const isNewRow = existing === undefined;
     let outcomeScore;
     let expectedRetrievalRate;
     if (isNewRow) {
-        // ── Warm-start ─────────────────────────────────────────────────────────
-        // Seed from utility EMA, clipped to [0, WARM_START_CAP].
-        // The warm-start is a non-negative seed; the first real differential update
-        // will adjust it up or down from there.
         const seedScore = Math.min(WARM_START_CAP, Math.max(0, inputs.utilityScore ?? 0));
         outcomeScore = seedScore;
-        // Seed expected_retrieval_rate = 0 (no delta history yet).
-        // Seeding with currentRetrievalCount would produce a large spurious negative
-        // prediction error on the first real cycle (delta ≪ cumulative count).
         expectedRetrievalRate = 0;
     }
     else {
-        // ── Differential update ────────────────────────────────────────────────
-        //
-        // retrieval_delta = current − stored (non-negative — we never go backwards)
         const retrievalDelta = Math.max(0, inputs.currentRetrievalCount - existing.retrieval_count);
-        // Differential prediction-error term:
-        // outcome = (retrieval_delta − expected_delta) + valence
-        //
-        // Prediction error is computed against the PRIOR stored EMA (before folding
-        // in this cycle's observation), so the current delta cannot leak into its own
-        // expectation. Negative values are intentional — they signal below-average cycles.
         const expectedDelta = existing.expected_retrieval_rate;
         const predictionError = retrievalDelta - expectedDelta;
-        // Advance the EMA over the OBSERVED delta (not the cumulative count).
-        // expected' = α × delta + (1−α) × prior_expected
         expectedRetrievalRate =
             OUTCOME_EMA_ALPHA * retrievalDelta + (1 - OUTCOME_EMA_ALPHA) * existing.expected_retrieval_rate;
-        // Running sum (EMA approach): new score = α × update + (1−α) × old
-        // so the score tracks the moving signal, not the cumulative sum.
         const rawUpdate = predictionError + valence;
         const newScore = OUTCOME_EMA_ALPHA * rawUpdate + (1 - OUTCOME_EMA_ALPHA) * existing.outcome_score;
-        // Clip to [OUTCOME_SCORE_MIN, OUTCOME_SCORE_MAX] — the ceiling is the RPE
-        // saturation analog (G2): without it, long-lived popular assets accumulate
-        // unbounded positive mass and would dominate rank_score when outcome weight
-        // is enabled.
         outcomeScore = Math.min(OUTCOME_SCORE_MAX, Math.max(OUTCOME_SCORE_MIN, newScore));
     }
+    return { outcomeScore, expectedRetrievalRate, isNewRow };
+}
+/**
+ * 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.
+ */
+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
@@ -107,13 +91,13 @@ export function updateAssetOutcome(db, inputs) {
         ref: inputs.ref,
         lastRetrievedAt: inputs.lastRetrievedAt,
         retrievalCount: inputs.currentRetrievalCount,
-        expectedRetrievalRate,
+        expectedRetrievalRate: projection.expectedRetrievalRate,
         negativeFeedbackCount: inputs.negativeFeedbackCount,
         acceptedChangeCount: inputs.acceptedChangeCount,
-        outcomeScore,
+        outcomeScore: projection.outcomeScore,
         updatedAt: now,
     });
-    return { outcomeScore, isNewRow };
+    return { outcomeScore: projection.outcomeScore, isNewRow: projection.isNewRow };
 }
 // ── Reader ────────────────────────────────────────────────────────────────────
 //

package/dist/commands/improve/planner.js

@@ -0,0 +1,134 @@
+// 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/.
+/**
+ * Pure improve planning projections.
+ *
+ * Filesystem/database snapshot collection stays in `preparation.ts`; this leaf
+ * receives immutable values and is shared by dry preview and live execution.
+ * Keeping the limit/lane projection here prevents the two entry paths from
+ * independently reconstructing "what would run".
+ */
+import { conceptIdFromTypeName } from "../../core/asset/resolve-ref.js";
+import { parseMemoryName } from "./memory/derived-ref.js";
+function canonicalMemoryConceptRef(ref) {
+    const name = parseMemoryName(ref);
+    return name === undefined ? undefined : conceptIdFromTypeName("memory", name);
+}
+/**
+ * Project the refs that survive memory cleanup from either the planned archive
+ * candidates (dry estimate) or the archives that actually succeeded (live
+ * execution). Cleanup records use the legacy `memory:<name>` identity channel,
+ * while improve candidates use canonical `memories/<name>` concept refs, so
+ * both sides are normalized before comparison.
+ */
+export function projectMemoryCleanup(input) {
+    const cleanupRefs = input.allowApply ? (input.mode === "estimate" ? input.candidateRefs : input.archivedRefs) : [];
+    const removed = new Set(cleanupRefs.map(canonicalMemoryConceptRef).filter((ref) => ref !== undefined));
+    const postCleanupRefs = input.plannedRefs.filter((entry) => {
+        const canonical = canonicalMemoryConceptRef(entry.ref);
+        return canonical === undefined || !removed.has(canonical);
+    });
+    return {
+        postCleanupRefs,
+        gate: {
+            name: "cleanup",
+            removed: input.plannedRefs.length - postCleanupRefs.length,
+            reason: !input.allowApply
+                ? "memory cleanup archive application is autonomy-gated"
+                : input.mode === "estimate"
+                    ? "would be archived by memory cleanup"
+                    : "archived by memory cleanup",
+        },
+    };
+}
+/**
+ * Apply the final global cap to an already-ranked candidate snapshot.
+ * Replay remains additive to the ordinary cap, matching the live #610 rule.
+ */
+export function selectEffectiveImproveRefs(args) {
+    const distillOnlySet = new Set(args.distillOnlyRefs.map((entry) => entry.ref));
+    const reflectAndDistill = args.rankedRefs.filter((entry) => !distillOnlySet.has(entry.ref));
+    const distillOnly = args.rankedRefs.filter((entry) => distillOnlySet.has(entry.ref));
+    // 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)];
+    return {
+        loopRefs,
+        distillOnlyRefs: distillOnly,
+        limitRemoved: allLoopRefs.length - loopRefs.length,
+    };
+}
+/** Build the stable public plan DTO from one invocation's selector observation. */
+export function buildImproveExecutionPlan(input) {
+    const effectiveRefs = input.effectiveRefs.map((entry) => ({
+        ref: entry.ref,
+        lane: input.distillOnlyRefs.has(entry.ref) ? "distill-only" : (entry.eligibilitySource ?? "unknown"),
+        reason: entry.reason,
+    }));
+    return {
+        mode: input.dryRun ? "estimate" : "execution",
+        dispatch: !input.dryRun,
+        snapshot: { ...input.snapshot },
+        candidates: {
+            rawInScope: input.rawInScope,
+            selected: input.selectedRefs.length,
+            effective: effectiveRefs.length,
+        },
+        limits: {
+            configured: { ...input.configuredLimits },
+            ...(input.effectiveLimit !== undefined ? { effective: input.effectiveLimit } : {}),
+            additiveReplayAllowance: input.replayBudget,
+            ...(input.effectiveLimit !== undefined ? { totalCeiling: input.effectiveLimit + input.replayBudget } : {}),
+        },
+        gates: input.gates.map((gate) => ({ ...gate })),
+        effectiveRefs,
+        ...(input.proactive
+            ? {
+                proactive: {
+                    ...input.proactive,
+                    configured: { ...input.proactive.configured },
+                    effective: { ...input.proactive.effective },
+                    selectedRefs: [...input.proactive.selectedRefs],
+                },
+            }
+            : {}),
+        consolidation: {
+            ...input.consolidation,
+            configured: { ...input.consolidation.configured },
+            effective: { ...input.consolidation.effective },
+            gates: {
+                profile: { ...input.consolidation.gates.profile },
+                minimumPool: { ...input.consolidation.gates.minimumPool },
+                delta: { ...input.consolidation.gates.delta },
+            },
+        },
+        stages: [
+            {
+                name: "consolidation",
+                wouldRun: input.consolidation.wouldRun,
+                reason: input.consolidation.reason,
+            },
+            {
+                name: "extract",
+                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,
+                reason: input.stageConfig.memoryInference.reason,
+            },
+        ],
+        triage: { ...input.triage },
+    };
+}