akm-cli 0.9.0-rc.1 → 0.9.0-rc.13

package/dist/commands/improve/run-context.js

@@ -0,0 +1,119 @@
+// 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/.
+/**
+ * `RunContext` — the shared, run-scoped carrier for the three improve verbs
+ * (revise = reflect, learn = extract/distill/inference, consolidate = the
+ * memory-tier ops; D17). WI-7.5–7.8 decompose the improve god-functions into
+ * named passes that thread a `RunContext` instead of long positional argument
+ * lists.
+ *
+ * ## The D6 read-once seam
+ *
+ * `readAsset` is a memoizing file-read seam whose memo is **NEVER run-wide**
+ * (D6 / top-risk #7: a run-wide memo would serve prep-time bytes after a mid-run
+ * write). The guarantee is structural here, not merely conventional:
+ *
+ *   - The **base** context returned by {@link createRunContext} has NO active
+ *     memo. `readAsset` on it always reads through to disk, so it can never go
+ *     stale — the safe default.
+ *   - {@link RunContext.withFreshAssetMemo} mints a sibling context that shares
+ *     every run-scoped carrier but owns a FRESH, empty memo. Memoization is
+ *     therefore opt-in per scope:
+ *       * prep's stage-body passes share ONE memo, forked only AFTER the
+ *         mutating pre-loop passes have written their ops to disk, then
+ *         discarded at stage end;
+ *       * reflect and distill each fork their own memo per verb invocation, so
+ *         their reads still happen at invoke time (not prep time).
+ *   - Within a memo scope, {@link RunContext.writeAsset} writes through to disk
+ *     AND refreshes the memo, and {@link RunContext.noteAssetWrite} drops a memo
+ *     entry for a path written out-of-band, so a subsequent `readAsset` of the
+ *     same path returns POST-write bytes (e.g. the distill in-loop salience
+ *     stamp at `distill.ts:816`).
+ *
+ * The contract is pinned by `tests/commands/improve/run-context.test.ts`.
+ *
+ * This module deliberately mints only the carrier + seam. Adoption at the verb
+ * call sites lands in WI-7.5 (reflect/distill), WI-7.6 (preparation), and
+ * WI-7.7 (akmImprove/extract). It does NOT change `EventsContext` shape and does
+ * NOT thread a db handle into `ProposalsContext` (D14).
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { resolveStashDir } from "../../core/common.js";
+import { chatCompletion } from "../../llm/client.js";
+/**
+ * Build a `RunContext` over the given carriers with the supplied memo (or `null`
+ * for the non-memoizing base context). Kept private so the only way to obtain a
+ * memoizing context is {@link RunContext.withFreshAssetMemo}.
+ */
+function buildRunContext(carriers, memo) {
+    const memoKey = (filePath) => path.resolve(filePath);
+    return {
+        stashDir: carriers.stashDir,
+        config: carriers.config,
+        eventsCtx: carriers.eventsCtx,
+        proposalsCtx: carriers.proposalsCtx,
+        chat: carriers.chat,
+        getLlmConfig: carriers.getLlmConfig,
+        sourceRun: carriers.sourceRun,
+        dryRun: carriers.dryRun,
+        signal: carriers.signal,
+        now: carriers.now,
+        readAsset(filePath) {
+            if (!memo)
+                return carriers.readFile(filePath);
+            const key = memoKey(filePath);
+            const cached = memo.get(key);
+            if (cached !== undefined)
+                return cached;
+            const bytes = carriers.readFile(filePath);
+            memo.set(key, bytes);
+            return bytes;
+        },
+        writeAsset(filePath, content) {
+            carriers.writeFile(filePath, content);
+            memo?.set(memoKey(filePath), content);
+        },
+        noteAssetWrite(filePath) {
+            memo?.delete(memoKey(filePath));
+        },
+        withFreshAssetMemo() {
+            return buildRunContext(carriers, new Map());
+        },
+    };
+}
+/**
+ * Create the base `RunContext` for an improve run. Its `readAsset` is
+ * non-memoizing (always fresh); call {@link RunContext.withFreshAssetMemo} to
+ * enter a memoized pass/invocation scope.
+ */
+export function createRunContext(init) {
+    const carriers = {
+        stashDir: init.stashDir,
+        config: init.config,
+        eventsCtx: init.eventsCtx,
+        proposalsCtx: init.proposalsCtx,
+        chat: init.chat ?? chatCompletion,
+        getLlmConfig: init.getLlmConfig,
+        sourceRun: init.sourceRun,
+        dryRun: init.dryRun,
+        signal: init.signal,
+        now: init.now ?? Date.now,
+        readFile: init.io?.readFile ?? ((filePath) => fs.readFileSync(filePath, "utf8")),
+        writeFile: init.io?.writeFile ?? ((filePath, content) => fs.writeFileSync(filePath, content, "utf8")),
+    };
+    return buildRunContext(carriers, null);
+}
+/**
+ * Resolve the run's stash directory at the improve builder boundary: the
+ * explicit `options.stashDir` when the caller passed one, else the ambient
+ * resolveStashDir() fallback. WI-9.10d: this is the SINGLE resolveStashDir
+ * call site on the improve path — the verb entries call THIS instead of
+ * resolveStashDir directly, so the ambient read lives only in the builder
+ * module. (The CLI-wide resolveStashDir sweep for non-improve commands is a
+ * deferred follow-on — see the chunk-9 ledger WI-9.10d entry.)
+ */
+export function resolveRunStashDir(explicitStashDir) {
+    return explicitStashDir ?? resolveStashDir();
+}

package/dist/commands/improve/salience.js

@@ -45,8 +45,10 @@
  *
  * @module salience
  */
-import { makeAssetRef } from "../../core/asset/asset-ref.js";
-import { getAllEntries, getUtilityScoresByIds } from "../../indexer/db/db.js";
+import path from "node:path";
+import { conceptIdFromTypeName } from "../../core/asset/resolve-ref.js";
+import { getAllEntries } from "../../storage/repositories/index-entries-repository.js";
+import { getUtilityScoresByIds } from "../../storage/repositories/index-utility-repository.js";
 import { WARM_START_CAP } from "./outcome-loop.js";
 // ── One day in ms ─────────────────────────────────────────────────────────────
 const DAY_MS = 86_400_000;
@@ -207,7 +209,7 @@ export function computeSalience(inputs) {
     // When `outcomeWeightEnabled` is true/absent (DEFAULT ON since the G2
     // saturation cap landed): use WS-2 weights (w_e=0.25, w_o=0.15, w_r=0.60)
     // so the prediction-error outcome signal actually shapes rankScore — this
-    // is the R1 loop-closure from docs/design/improve-self-learning-analysis.md.
+    // is the R1 loop-closure.
     //
     // When `outcomeWeightEnabled` is explicitly false (operator opt-out via
     // `improve.salience.outcomeWeightEnabled: false`): fall back to the WS-1
@@ -233,132 +235,21 @@ export function computeSalience(inputs) {
     const rankScore = Math.min(1, Math.max(0, rawRankScore));
     return { encoding, outcome, retrieval, rankScore, encodingSource };
 }
+// ── state.db persistence ─────────────────────────────────────────────────────
+//
+// The three sub-scores live in state.db::asset_salience. Raw SQL now lives in
+// storage/repositories/salience-repository.ts (#672 part 2) — extracted
+// verbatim, only relocated behind the repository boundary. Re-exported here so
+// existing importers of this module resolve unchanged. Migrations live in
+// state-db.ts (migration 009).
+export { getAllRankScores, getAssetSalience, getConsecutiveNoOps, recordNoOp, resetConsecutiveNoOps, upsertAssetSalience, } from "../../storage/repositories/salience-repository.js";
 /**
  * Does this row carry a genuine content-derived `encoding_salience` (#644)?
  *
- * Returns true when the provenance flag is `"content"`. For legacy rows
- * (`encoding_source === null`, written before migration 015) we apply a
- * conservative heuristic: treat the stored value as content-derived only when it
- * does NOT equal the pure type-weight stub for the asset's type — because before
- * the #644 fix every run overwrote real scores with the stub, a value that still
- * differs from the stub must have been content-written and never re-clobbered.
- * When the type cannot be determined (no `type` given) a null-provenance row is
- * treated as a stub (the safe default).
- */
-export function isContentEncodingRow(row, type) {
-    if (row.encoding_source === "content")
-        return true;
-    if (row.encoding_source === "type-stub")
-        return false;
-    // Legacy NULL provenance: differ-from-stub heuristic.
-    if (!type)
-        return false;
-    const stub = DEFAULT_TYPE_ENCODING_WEIGHTS[type] ?? DEFAULT_ENCODING_SALIENCE;
-    return Math.abs(row.encoding_salience - stub) > 1e-9;
-}
-/**
- * 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.
+ * Unknown provenance is not treated as content-derived.
  */
-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;
+export function isContentEncodingRow(row) {
+    return row.encoding_source === "content";
 }
 // ── Consolidation-selection dampener constants ────────────────────────────────
 //
@@ -424,15 +315,21 @@ export function buildRankChangeReport(oldRanks, newRanks, oldTopN = 200, forgett
  * @param indexDb - An open read-capable index database connection.
  * @param refs    - The set of asset refs to look up.
  */
-export function getLastUseMsByRef(indexDb, refs) {
+export function getLastUseMsByRef(indexDb, refs, stashDir) {
     const result = new Map();
     if (refs.length === 0)
         return result;
     const refSet = new Set(refs);
     const allEntries = getAllEntries(indexDb);
+    const selectedRoot = stashDir ? path.resolve(stashDir) : undefined;
     const idToRef = new Map();
     for (const indexed of allEntries) {
-        const ref = makeAssetRef(indexed.entry.type, indexed.entry.name);
+        if (selectedRoot && path.resolve(indexed.stashDir) !== selectedRoot)
+            continue;
+        // In-memory correlation key, NOT a durable write: it must match the caller's
+        // `refs` (the `ImproveEligibleRef.ref`, now the SHORT conceptId — Chunk-8
+        // WI-8.5c flipped the candidate-ref spelling to match the display flip).
+        const ref = conceptIdFromTypeName(indexed.entry.type, indexed.entry.name);
         if (refSet.has(ref))
             idToRef.set(indexed.id, ref);
     }

package/dist/commands/improve/session-asset.js

@@ -23,8 +23,9 @@
  */
 import fs from "node:fs";
 import path from "node:path";
+import { stashDirFor } from "../../core/asset/asset-placement.js";
 import { assembleAsset } from "../../core/asset/asset-serialize.js";
-import { TYPE_DIRS } from "../../core/asset/asset-spec.js";
+import { conceptIdFromTypeName } from "../../core/asset/resolve-ref.js";
 import { normalizeHarnessId } from "../../integrations/harnesses/index.js";
 /**
  * JSON Schema for the session-summary LLM call. Strict so providers that
@@ -218,7 +219,7 @@ export function buildSessionAssetContent(data, summary) {
 }
 /** Resolve `<stash>/sessions/<harness>/<session-id>.md`. */
 export function resolveSessionAssetPath(stashDir, harness, sessionId) {
-    const dir = TYPE_DIRS.session ?? "sessions";
+    const dir = stashDirFor("session") ?? "sessions";
     return path.join(stashDir, dir, normalizeHarnessId(harness), `${sessionId}.md`);
 }
 /**
@@ -242,7 +243,10 @@ export async function writeSessionAsset(data, stashDir, generate) {
     return {
         written: true,
         filePath,
-        ref: `session:${normalizeHarnessId(harness)}/${sessionId}`,
+        // Canonical 0.9.0 conceptId (`sessions/<harness>/<id>`, D-R3) — the same
+        // spelling the xrefs / usage-event readers now expect. Historical
+        // `session:<harness>/<id>` rows persist un-migrated and are tolerated.
+        ref: conceptIdFromTypeName("session", `${normalizeHarnessId(harness)}/${sessionId}`),
         logPath: data.ref.filePath,
     };
 }

package/dist/commands/improve/shared.js

@@ -1,10 +1,20 @@
 // 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 { getDefaultLlmConfig, getImproveProcessConfig } from "../../core/config/config.js";
-import { warn } from "../../core/warn.js";
-import { resolveImproveProcessRunnerFromProfile, runnerIsLlm } from "../../integrations/agent/runner.js";
-import { chatCompletion } from "../../llm/client.js";
+/**
+ * Small pure helpers shared across the improve command family. Extracted to
+ * delete byte-identical duplication that previously lived inline in the
+ * per-process passes (the whole-corpus synthesis pass removed in 0.9.0 and
+ * the procedural-compilation pass removed in 0.9.0). Keep this file free of
+ * I/O and of any improve-specific state — these are leaf utilities.
+ */
+/**
+ * Cap on how many prior rejected proposals for a ref are injected as
+ * Reflexion-style verbal-RL context so the LLM avoids regenerating refusals.
+ * Shared by both the revise (reflect) and learn (distill) verbs, which
+ * previously declared this constant independently.
+ */
+export const MAX_REJECTED_PROPOSALS = 3;
 /** Normalize an unknown thrown value to a human-readable message string. */
 export function errMessage(e) {
     return e instanceof Error ? e.message : String(e);
@@ -19,33 +29,3 @@ export function refSlug(ref) {
         .toLowerCase()
         .slice(0, 60);
 }
-/**
- * Resolve the production LLM seam for an improve process (`recombine` /
- * `procedural`). Returns a function that issues one bounded chatCompletion per
- * call, or `undefined` when no LLM is configured (the pass then makes no
- * calls). Previously copied verbatim in recombine.ts and procedural.ts.
- *
- * When `opts.activeProfile` is supplied, its per-process runner override wins
- * over the `default` profile so `akm improve --profile <name>` selects the
- * profile's model; absent falls back to `default`.
- */
-export function resolveImproveLlmFn(config, opts) {
-    const processConfig = getImproveProcessConfig(config, opts.processKey, opts.activeProfile);
-    const runnerSpec = resolveImproveProcessRunnerFromProfile(processConfig, config);
-    const llmConfig = runnerSpec && runnerIsLlm(runnerSpec) ? runnerSpec.connection : getDefaultLlmConfig(config);
-    if (!llmConfig)
-        return undefined;
-    return async (prompt) => {
-        const messages = [
-            { role: "system", content: opts.systemPrompt },
-            { role: "user", content: prompt },
-        ];
-        try {
-            return await chatCompletion(llmConfig, messages, { signal: opts.signal, enableThinking: false });
-        }
-        catch (e) {
-            warn(`${opts.tag} LLM call failed: ${String(e)}`);
-            return null;
-        }
-    };
-}

package/dist/commands/improve/source-identity.js

@@ -0,0 +1,28 @@
+// 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/.
+// ── Durable improve-state keys ───────────────────────────────────────────────
+//
+// Every improve ref uses the current grammar (a short conceptId), and the durable
+// state key is the resolved index entry's `item_ref` when the planner supplied
+// one, else the conceptId `ref` itself (`preparation.ts`
+// `salienceWriteKey`/`outcomeWriteKey` = `itemRef ?? ref`).
+/**
+ * The durable improve-state key for a ref with no resolved `item_ref` — the
+ * conceptId `ref` itself.
+ */
+export function durableImproveRef(ref) {
+    return ref;
+}
+/** Return the conceptId portion of a durable improve-state key. */
+export function bareImproveRef(ref) {
+    const boundary = ref.indexOf("//");
+    return boundary >= 0 ? ref.slice(boundary + 2) : ref;
+}
+/**
+ * The single durable improve-state key used by both readers and writers.
+ * Indexed entries use item_ref; direct or provenance-free refs use conceptId.
+ */
+export function improveStateReadRefs(ref, itemRef) {
+    return [itemRef ?? ref];
+}

package/dist/commands/improve/triage.js

@@ -14,7 +14,23 @@ const MARKER_RE = /\b(error|failed|fix(?:ed)?|root cause|turns out|because|decid
 const EDIT_COMMIT_RE = /\b(Edit|Write|MultiEdit|git commit|diff)\b/i;
 // A substantive turn is an assistant or tool turn whose text is non-trivial.
 const SUBSTANTIVE_MIN_CHARS = 40;
-export function scoreSessionTriage(data, minScore, options) {
+/**
+ * Pure heuristic scorer. Operates only on `data.events`. Each sub-signal is
+ * normalized to a small bounded contribution; `score` is their sum and
+ * `pass = score >= minScore`.
+ *
+ * Sub-signals:
+ *   - markers: presence of decision/outcome/error keywords across event text
+ *     (capped, narrative-lesson signal).
+ *   - toolDensity: bounded contribution from tool-use events.
+ *   - editCommit: bounded contribution from edit/write/commit events.
+ *   - substantiveRatio: scaled fraction of non-trivial assistant+tool turns,
+ *     filtering pure short Q&A.
+ *
+ * toolDensity + editCommit alone can clear DEFAULT_TRIAGE_MIN_SCORE so
+ * high-action / no-narrative sessions are KEPT.
+ */
+export function scoreSessionTriage(data, minScore) {
     const events = data.events;
     const total = events.length;
     // (a) markers — count word-bounded marker hits across all event text, capped.
@@ -57,18 +73,7 @@ export function scoreSessionTriage(data, minScore, options) {
     const subscores = { markers, toolDensity, editCommit, substantiveRatio };
     const score = markers + toolDensity + editCommit + substantiveRatio;
     // Base gate: score must clear the floor.
-    let pass = score >= minScore;
-    // #641 procedural-aware floor (opt-in, DEFAULT OFF).
-    // When enabled, a session that clears the score gate must ALSO have at least
-    // one narrative marker (markers >= 1) OR meaningful edit/commit signal
-    // (editCommit >= 0.5). Pure read-only Q&A sessions that pass only via
-    // toolDensity + substantiveRatio are rejected as low-signal.
-    if (pass && options?.proceduralAwareFloor === true) {
-        const hasProceduralSignal = markers >= 1 || editCommit >= 0.5;
-        if (!hasProceduralSignal) {
-            pass = false;
-        }
-    }
+    const pass = score >= minScore;
     return {
         pass,
         score,
@@ -78,7 +83,7 @@ export function scoreSessionTriage(data, minScore, options) {
 }
 /**
  * Resolve the effective triage config from the extract process config. Mirrors
- * the minContentChars / schemaSimilarity resolution style in akmExtract.
+ * the minContentChars resolution style in akmExtract.
  *
  * Default-off: `enabled` is FALSE unless `triage.enabled === true`. `minScore`
  * defaults to {@link DEFAULT_TRIAGE_MIN_SCORE}.
@@ -87,7 +92,5 @@ export function resolveTriageConfig(extractProcess) {
     const triage = extractProcess?.triage;
     const enabled = triage?.enabled === true;
     const minScore = typeof triage?.minScore === "number" ? triage.minScore : DEFAULT_TRIAGE_MIN_SCORE;
-    // #641: default-off — only true when explicitly set to true.
-    const proceduralAwareFloor = triage?.proceduralAwareFloor === true;
-    return { enabled, minScore, proceduralAwareFloor };
+    return { enabled, minScore };
 }