akm-cli 0.9.17-alpha.2 → 0.9.17-alpha.4

package/dist/commands/improve/salience.js

@@ -4,71 +4,25 @@
 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;
-// ── Recency decay half-life (mirrors the proactive-maintenance prototype) ─────
 const RECENCY_HALFLIFE_DAYS = 21;
-// ── Recency-floor half-life (R4 — SHY-style continuous downscaling) ──────────
-//
-// The recency floor itself decays on this (much longer) half-life so an
-// unreviewed-forever asset keeps drifting down instead of parking at the 0.1
-// floor. This replaces the deleted homeostatic demotion pass (which was
-// default-off and self-undoing — every salience recompute clobbered it);
-// folding the decay into the always-applied recency term makes it persist by
-// construction. At 180 days the floor halves; a 1-year-stale asset sits at
-// ~0.025 instead of 0.1.
+/**
+ * The recency floor itself halves every 180 days, so an asset nobody uses keeps
+ * drifting down instead of parking at the floor.
+ */
 const RECENCY_FLOOR_HALFLIFE_DAYS = 180;
-// Absolute epsilon under the decaying floor. Keeps the frequency term ordinal
-// for assets whose last-use timestamp is unknown (utility_scores has no
-// last_used_at) — without it their retrieval salience collapses to exactly 0
-// and frequency ordering is lost for maintenance selection.
+/** Keeps frequency ordinal for assets whose last use is unknown. */
 const RECENCY_EPSILON = 0.01;
-// ── Size proxy floor (avoids log10(0)) ────────────────────────────────────────
 const SIZE_FLOOR_BYTES = 200;
-// ── Projection weights ────────────────────────────────────────────────────────
-//
-// These constants are the DEFAULT ranking weights (R1 loop closure). Operators
-// can opt back out to the WS-1 parity weights (w_e=0.30, w_r=0.70, w_o=0) via
-// `improve.salience.outcomeWeightEnabled: false`.
-//
-// WS-2 split (w_e=0.25, w_o=0.15, w_r=0.60, sum = 1.0):
-// [exp] Expert recommendation: encoding should be moderate so a type-importance
-// stub does not completely dominate; retrieval should be strong since it directly
-// measures use; outcome provides a quality signal proportional to usefulness.
-//
-// Re-tune via the Part-V measurement protocol if the throughput/quality gate
-// shows regression after enabling the outcome weight.
-export const W_ENCODING = 0.25; // WS-2 target encoding weight (w_e)
-export const W_OUTCOME = 0.15; // WS-2 target outcome weight (w_o)
-export const W_RETRIEVAL = 0.6; // WS-2 target retrieval weight (w_r)
-// Compile-time guard: weights must sum to 1.0 (±ε). The TS initializer runs
-// at module load, not build time, so this acts as a startup assertion.
-if (Math.abs(W_ENCODING + W_OUTCOME + W_RETRIEVAL - 1.0) > 1e-9) {
-    throw new Error(`salience.ts: W_ENCODING + W_OUTCOME + W_RETRIEVAL must equal 1.0 (got ${W_ENCODING + W_OUTCOME + W_RETRIEVAL})`);
-}
-// ── WS-1 parity weights ───────────────────────────────────────────────────────
-//
-// These constants reflect the WS-1 parity weights used when the operator
-// explicitly opts out (`outcomeWeightEnabled: false`). They preserve the
-// WS-1 two-way split (w_e=0.30, w_r=0.70) with w_o=0 so outcome does not
-// affect rankScore in the opt-out mode.
-//
-// Named here (rather than inline literals in the else branch) so a future
-// re-tune has a single source of truth and the sum-to-1 guard below catches
-// any accidental mis-edit.
-export const W_ENCODING_PARITY = 0.3; // WS-1 parity encoding weight
-export const W_OUTCOME_PARITY = 0; // WS-1 parity outcome weight (0 = disabled)
-export const W_RETRIEVAL_PARITY = 0.7; // WS-1 parity retrieval weight
-// Startup guard: parity triple must also sum to 1.0 (±ε).
-if (Math.abs(W_ENCODING_PARITY + W_OUTCOME_PARITY + W_RETRIEVAL_PARITY - 1.0) > 1e-9) {
-    throw new Error(`salience.ts: W_ENCODING_PARITY + W_OUTCOME_PARITY + W_RETRIEVAL_PARITY must equal 1.0 (got ${W_ENCODING_PARITY + W_OUTCOME_PARITY + W_RETRIEVAL_PARITY})`);
-}
-// ── Type-importance fallback weights (#608 landed) ────────────────────────────
-//
-// The real encoding salience estimator is `scoreEncodingSalience` in
-// `encoding-salience.ts` (#608). These weights are the fallback used when
-// `SalienceInputs.encodingSalience` is absent (pre-#608 assets without a
-// frontmatter `salience:` field or a state.db row seeded by distill).
+/** Default weights: the outcome term is on (opt out with `improve.salience.outcomeWeightEnabled: false`). */
+export const W_ENCODING = 0.25;
+export const W_OUTCOME = 0.15;
+export const W_RETRIEVAL = 0.6;
+/** Weights with the outcome term off. */
+export const W_ENCODING_PARITY = 0.3;
+export const W_OUTCOME_PARITY = 0;
+export const W_RETRIEVAL_PARITY = 0.7;
+/** Encoding salience by type, for assets with no content-derived score yet. */
 export const DEFAULT_TYPE_ENCODING_WEIGHTS = Object.freeze({
     skill: 0.9,
     agent: 0.9,
@@ -79,218 +33,78 @@ export const DEFAULT_TYPE_ENCODING_WEIGHTS = Object.freeze({
     script: 0.6,
     memory: 0.5,
 });
-/** Default encoding salience for types not in the table above. */
 export const DEFAULT_ENCODING_SALIENCE = 0.5;
-// ── Core computation ─────────────────────────────────────────────────────────
-/**
- * Compute the salience vector for one asset.
- *
- * Pure function — no I/O. All inputs are pre-fetched by the caller.
- */
+const clamp01 = (value) => Math.min(1, Math.max(0, value));
+/** The salience vector for one asset (pure). */
 export function computeSalience(inputs) {
     const now = inputs.now ?? Date.now();
-    // ── Encoding salience ────────────────────────────────────────────────────────
-    //
-    // When `inputs.encodingSalience` is provided (computed by `scoreEncodingSalience`
-    // in encoding-salience.ts at extract/distill time, #608), use it directly.
-    // Fall back to the type-importance stub only when the caller has not yet
-    // computed a content-based score (e.g. on older assets before the first
-    // staleness refresh runs).
     const encodingSource = inputs.encodingSalience !== undefined ? "content" : "type-stub";
     const encoding = inputs.encodingSalience !== undefined
-        ? Math.min(1, Math.max(0, inputs.encodingSalience))
+        ? clamp01(inputs.encodingSalience)
         : (DEFAULT_TYPE_ENCODING_WEIGHTS[inputs.type] ?? DEFAULT_ENCODING_SALIENCE);
-    // ── Outcome salience (WS-2 active) ────────────────────────────────────────
-    //
-    // When `inputs.outcomeSalience` is provided (WS-2 has populated asset_outcome
-    // for this ref), use it directly — it has already been normalised by
-    // `outcomeScoreToSalience` in outcome-loop.ts (value in [DIVERSITY_FLOOR, 1]).
-    //
-    // When absent (new asset, no WS-2 row yet): fall back to the warm-start seed
-    // from `utilityScore` clipped to [0, WARM_START_CAP], matching the seed
-    // value that `updateAssetOutcome` writes on first row creation. This ensures
-    // `outcomeSalience` is non-zero at launch for assets with utility history
-    // (avoiding the starvation problem described in the plan §WS-2 warm start).
-    let outcome;
-    if (inputs.outcomeSalience !== undefined) {
-        // Direct pass-through — caller already normalised via outcomeScoreToSalience.
-        outcome = Math.min(1, Math.max(0, inputs.outcomeSalience));
-    }
-    else {
-        // Warm-start fallback: clip utility to [0, WARM_START_CAP] so the
-        // outcomeSalience term contributes a modest non-zero baseline.
-        outcome = Math.min(WARM_START_CAP, Math.max(0, inputs.utilityScore ?? 0));
-    }
-    // ── Retrieval salience ─────────────────────────────────────────────────────
-    //
-    // Formula: log(1 + freq) × recencyDecay
-    //   log(1+freq): sub-linear frequency term (same as proactive-maintenance prototype).
-    //   recencyDecay: max(ε, 0.1·0.5^(useAgeDays/180) + 0.5^(useAgeDays/21)) —
-    //     the fast term halves every 21 days; the 0.1 floor itself halves every
-    //     180 days (R4: SHY-style continuous downscaling — an unreviewed-forever
-    //     asset keeps drifting down instead of parking at the floor). The ε=0.01
-    //     epsilon keeps the frequency term ordinal for unknown-last-use assets.
-    //     lastUseMs=0/undefined → useAgeDays=9999 → recencyDecay=ε.
-    //
-    // The recency term is MANDATORY (plan requirement §WS-1 step 2). Without it
-    // retrievalSalience degenerates to a non-decaying frequency count. This
-    // always-applied decay replaces the deleted homeostatic demotion pass.
+    // Without an outcome row, utility (capped) seeds the outcome term — the same
+    // seed the first outcome row gets — so it is not zero at launch.
+    const outcome = inputs.outcomeSalience !== undefined
+        ? clamp01(inputs.outcomeSalience)
+        : Math.min(WARM_START_CAP, Math.max(0, inputs.utilityScore ?? 0));
+    // log(1 + freq) × recency, where recency halves every 21 days above a floor
+    // that itself halves every 180 days; soft-capped to [0, 1).
     const lastUseMs = inputs.lastUseMs ?? 0;
     const useAgeDays = lastUseMs > 0 ? (now - lastUseMs) / DAY_MS : 9999;
     const recencyDecay = Math.max(RECENCY_EPSILON, 0.1 * 0.5 ** (useAgeDays / RECENCY_FLOOR_HALFLIFE_DAYS) + 0.5 ** (useAgeDays / RECENCY_HALFLIFE_DAYS));
     const rawRetrieval = Math.log(1 + inputs.retrievalFreq) * recencyDecay;
-    // ── Size penalty ─────────────────────────────────────────────────────────────
-    // 1/log10(size): larger assets are slightly deprioritized (same as proactive prototype).
-    const sizeProxy = Math.max(SIZE_FLOOR_BYTES, inputs.sizeBytes ?? 0);
-    const sizePenalty = 1 / Math.log10(sizeProxy);
-    // ── Projection → rankScore ────────────────────────────────────────────────
-    //
-    // Raw projection may be > 1 (log retrieval terms can exceed 1 for high freq + fresh use).
-    // Normalize by the theoretical maximum of the retrieval component:
-    //   max retrievalRaw = log(1 + Infinity) × (0.1 + 1.0) = Infinity, so we
-    //   cap instead — rankScore is clamped to [0,1] after applying the size penalty.
-    //
-    // Normalization approach: we scale the combined linear sum to [0,1] by clamping,
-    // after applying the size penalty. The encoding term is already in [0,1]; the
-    // retrieval term is open-ended but bounded in practice by log(1+N)×1.1 where N
-    // is the retrieval count. We normalize `retrieval` to [0,1] using a soft cap:
-    //   retrieval_normalized = rawRetrieval / (rawRetrieval + 1)
-    // which asymptotes to 1 and equals 0.5 at rawRetrieval=1. This is the same
-    // formula used for MemRL utility updates.
     const retrieval = rawRetrieval / (rawRetrieval + 1);
-    // ── Weight selection (R1 — outcome loop closed by default) ───────────────
-    //
-    // 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.
-    //
-    // When `outcomeWeightEnabled` is explicitly false (operator opt-out via
-    // `improve.salience.outcomeWeightEnabled: false`): fall back to the WS-1
-    // parity weights (w_e=0.30, w_r=0.70, w_o=0). The `outcome` sub-score is
-    // still computed and stored for observability in that mode.
-    let we;
-    let wo;
-    let wr;
-    if (inputs.outcomeWeightEnabled !== false) {
-        // WS-2 active (default): three-way split.
-        we = W_ENCODING; // 0.25
-        wo = W_OUTCOME; // 0.15
-        wr = W_RETRIEVAL; // 0.60
-    }
-    else {
-        // WS-1 parity (opt-out): w_o=0, redistribute to WS-1 proportions.
-        // Original WS-1 split was w_e=0.30, w_r=0.70.
-        we = W_ENCODING_PARITY;
-        wo = W_OUTCOME_PARITY;
-        wr = W_RETRIEVAL_PARITY;
-    }
-    const rawRankScore = (we * encoding + wo * outcome + wr * retrieval) * sizePenalty;
-    const rankScore = Math.min(1, Math.max(0, rawRankScore));
+    // Larger assets rank slightly lower.
+    const sizePenalty = 1 / Math.log10(Math.max(SIZE_FLOOR_BYTES, inputs.sizeBytes ?? 0));
+    const [we, wo, wr] = inputs.outcomeWeightEnabled !== false
+        ? [W_ENCODING, W_OUTCOME, W_RETRIEVAL]
+        : [W_ENCODING_PARITY, W_OUTCOME_PARITY, W_RETRIEVAL_PARITY];
+    const rankScore = clamp01((we * encoding + wo * outcome + wr * retrieval) * sizePenalty);
     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)?
- *
- * Unknown provenance is not treated as content-derived.
- */
+/** Whether a stored row's encoding salience is content-derived (unknown provenance is not). */
 export function isContentEncodingRow(row) {
     return row.encoding_source === "content";
 }
-// ── Consolidation-selection dampener constants ────────────────────────────────
-//
-// Assets with consecutive_no_ops >= THRESHOLD are deprioritised in the
-// SELECTION ORDER only. The persisted rank_score is intentionally left
-// unchanged so stable assets remain fully retrievable by other callers.
-//
-// Tuning guidance:
-//   THRESHOLD — how many consecutive no-op runs before dampening kicks in.
-//               3 means "skipped three times in a row", which signals the
-//               LLM consistently has nothing to say about this asset.
-//   FACTOR    — multiplicative penalty on the effective selection score.
-//               0.5 halves the apparent score so a dampened asset sorts
-//               after any peer with >= half its rankScore.
-export const SALIENCE_NO_OP_DAMPEN_THRESHOLD = 3;
-export const SALIENCE_NO_OP_DAMPEN_FACTOR = 0.5;
 /**
- * Emit the forgetting-safety rank-change distribution report.
- *
- * Compares the provided `newRanks` (Map<ref, position (1-indexed)>) against
- * the provided `oldRanks` and flags refs that were in the old top-200 but
- * are now below position 500 as "forgetting candidates".
- *
- * Caller is responsible for computing old/new rank positions before and after
- * the WS-1 formula cutover. Called once at cutover, not every run.
- *
- * @param oldRanks - Map<ref, 1-indexed rank position> under the OLD formula.
- * @param newRanks - Map<ref, 1-indexed rank position> under the NEW formula.
- * @param oldTopN  - Assets in old top-N to guard (default: 200).
- * @param forgettingThreshold - New rank position below which a fall is flagged (default: 500).
+ * Consolidation selection only: an asset whose last three runs were no-ops
+ * sorts at half its score. The stored rank is untouched.
  */
+export const SALIENCE_NO_OP_DAMPEN_THRESHOLD = 3;
+export const SALIENCE_NO_OP_DAMPEN_FACTOR = 0.5;
+/** Forgetting safety: compare 1-indexed rank positions between two rankings. */
 export function buildRankChangeReport(oldRanks, newRanks, oldTopN = 200, forgettingThreshold = 500) {
     const allChanges = [];
-    const forgettingCandidates = [];
     for (const [ref, oldRank] of oldRanks) {
         const newRank = newRanks.get(ref);
-        if (newRank === undefined)
-            continue; // ref not in new ranking
-        const rankDelta = newRank - oldRank; // positive = fell in rank
-        allChanges.push({ ref, oldRank, newRank, rankDelta });
-        if (oldRank <= oldTopN && newRank > forgettingThreshold) {
-            forgettingCandidates.push({ ref, oldRank, newRank, rankDelta });
-        }
+        if (newRank !== undefined)
+            allChanges.push({ ref, oldRank, newRank, rankDelta: newRank - oldRank });
     }
-    // Sort by magnitude of rank drop (most dramatic first).
-    forgettingCandidates.sort((a, b) => b.rankDelta - a.rankDelta);
+    const forgettingCandidates = allChanges
+        .filter((c) => c.oldRank <= oldTopN && c.newRank > forgettingThreshold)
+        .sort((a, b) => b.rankDelta - a.rankDelta);
     return { forgettingCandidates, allChanges };
 }
-// ── Last-use timestamp lookup helper ─────────────────────────────────────────
-//
-// Wraps the index DB query to retrieve the last-retrieval timestamp per ref,
-// so callers do not need to import the raw db helpers directly. Returns a Map
-// keyed by the same ref strings passed in.
-//
-// Source: `utility_scores.last_used_at` (ISO-8601 string) joined to entries
-// via entry_id. WS-2 may later supersede this with `asset_outcome.last_retrieved_at`.
-/**
- * Build a Map<ref, lastUseMs> from the index database's utility_scores table.
- *
- * Returns only refs that have a non-null `last_used_at`. Refs absent from the
- * map should be treated as never retrieved (lastUseMs = 0).
- *
- * @param indexDb - An open read-capable index database connection.
- * @param candidates - Planned refs carrying their canonical durable item_ref.
- */
+/** `ref → last retrieval (ms)` from the index's utility scores; absent means never retrieved. */
 export function getLastUseMsByRef(indexDb, candidates) {
     const result = new Map();
     if (candidates.length === 0)
         return result;
     const refByItemRef = new Map(candidates.flatMap((candidate) => (candidate.itemRef ? [[candidate.itemRef, candidate.ref]] : [])));
-    const allEntries = getAllEntries(indexDb);
     const idToRef = new Map();
-    for (const indexed of allEntries) {
+    for (const indexed of getAllEntries(indexDb)) {
         const ref = refByItemRef.get(indexed.itemRef);
         if (ref)
             idToRef.set(indexed.id, ref);
     }
-    const ids = [...idToRef.keys()];
-    if (ids.length === 0)
+    if (idToRef.size === 0)
         return result;
-    const { global: scores } = getUtilityScoresByIds(indexDb, ids);
+    const scores = getUtilityScoresByIds(indexDb, [...idToRef.keys()]);
     for (const [id, row] of scores) {
         const ref = idToRef.get(id);
-        if (!ref)
-            continue;
         const lastUsedAt = row.lastUsedAt;
-        if (!lastUsedAt)
+        if (!ref || !lastUsedAt)
             continue;
         const ms = typeof lastUsedAt === "number" ? lastUsedAt : Date.parse(lastUsedAt);
         if (ms > 0)

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

@@ -2,37 +2,18 @@
 // 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/.
 /**
- * Session asset generation for the `extract` pass (#561).
- *
- * After the extractor distills memory proposals from a session, it ALSO writes
- * the session itself to the stash as a first-class `session` asset so any agent
- * — on any harness — can discover prior work via `akm search` / `akm curate`.
- *
- * Design constraints (see #561):
- *   - ADDITIVE + FAIL-OPEN + CONFIG-GATED. Disabled (or no LLM provider) →
- *     extract behaves EXACTLY as before. Nothing is written.
- *   - The LLM summary call routes through the injectable {@link SessionSummaryGenerator}
- *     seam so tests never touch a real provider, and so production wraps the
- *     call in the existing `tryLlmFeature` fail-open pattern.
- *   - The `log_path` + `access` frontmatter fields are the durable correlation
- *     key — they survive index rebuilds (the body is re-derived from disk).
- *
- * The asset is written to `sessions/<harness>/<session-id>.md`; the registered
- * `session` asset type (see `asset-spec.ts`) makes the normal index pass pick it
- * up for FTS + vector search with no special-casing.
+ * Session assets (#561): besides its memory proposals, extract writes each
+ * session to `sessions/<harness>/<session-id>.md` as a searchable `session`
+ * asset. Additive and fail-open — no summary means nothing is written — and
+ * `log_path` + `access` in the frontmatter tell any agent how to read the raw log.
  */
 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 { conceptIdFromTypeName } from "../../core/asset/resolve-ref.js";
+import { parseEmbeddedJsonResponse } from "../../core/parse.js";
 import { recordWrittenPath } from "../../core/write-provenance.js";
-/**
- * JSON Schema for the session-summary LLM call. Strict so providers that
- * support schema enforcement constrain the output upstream; the parser only
- * has to handle the happy path. `additionalProperties: false` drops any
- * hallucinated keys before parsing.
- */
 export const SESSION_SUMMARY_JSON_SCHEMA = {
     type: "object",
     required: ["summary", "key_topics"],
@@ -43,11 +24,7 @@ export const SESSION_SUMMARY_JSON_SCHEMA = {
         tags: { type: "array", items: { type: "string" } },
     },
 };
-/**
- * Render a compact transcript snippet from session events for the summary
- * prompt. Mirrors the extract transcript format but caps total length so the
- * summary prompt stays bounded regardless of session size.
- */
+/** The transcript for the summary prompt, capped at `maxChars`. */
 function renderTranscriptForSummary(events, maxChars = 12_000) {
     if (events.length === 0)
         return "(empty — no events)";
@@ -66,11 +43,6 @@ function renderTranscriptForSummary(events, maxChars = 12_000) {
     }
     return lines.join("\n\n") || "(empty — no textual events)";
 }
-/**
- * Build the user prompt for the session-summary LLM call. Pure — no IO. The
- * model is asked for a dense 2–4 sentence summary plus key topics, optimised
- * for semantic search recall.
- */
 export function buildSessionSummaryPrompt(data) {
     const ref = data.ref;
     const startedAt = isoOrUndefined(ref.startedAt) ?? "unknown";
@@ -92,33 +64,13 @@ export function buildSessionSummaryPrompt(data) {
         'Respond as JSON: {"summary": string, "key_topics": string[], "tags"?: string[]}.',
     ].join("\n");
 }
-/**
- * Parse the session-summary LLM response into a {@link SessionSummaryResult}.
- * Defensive: tolerates prose preamble/postamble around the JSON, and returns
- * `undefined` when nothing usable parses (fail-open: no asset is written).
- */
+/** The summary JSON, tolerating prose around it; `undefined` when nothing usable parses. */
 export function parseSessionSummary(raw) {
     if (!raw || raw.trim().length === 0)
         return undefined;
-    let parsed;
-    try {
-        parsed = JSON.parse(raw);
-    }
-    catch {
-        const start = raw.indexOf("{");
-        const end = raw.lastIndexOf("}");
-        if (start === -1 || end <= start)
-            return undefined;
-        try {
-            parsed = JSON.parse(raw.slice(start, end + 1));
-        }
-        catch {
-            return undefined;
-        }
-    }
-    if (!parsed || typeof parsed !== "object")
+    const obj = parseEmbeddedJsonResponse(raw);
+    if (!obj || typeof obj !== "object" || Array.isArray(obj))
         return undefined;
-    const obj = parsed;
     const summary = typeof obj.summary === "string" ? obj.summary.trim() : "";
     if (summary.length === 0)
         return undefined;
@@ -130,62 +82,40 @@ export function parseSessionSummary(raw) {
         : undefined;
     return { summary, keyTopics, ...(tags && tags.length > 0 ? { tags } : {}) };
 }
-/**
- * Decide whether a session is long enough to index. `minDurationMinutes <= 0`
- * disables the gate. When either timestamp is missing we DON'T gate it out —
- * fail-open toward indexing, since a missing timestamp is not evidence of a
- * trivial session.
- */
+/** Long enough to index (`<= 0` disables; a missing timestamp is no evidence of a trivial session). */
 export function sessionMeetsDurationGate(data, minDurationMinutes) {
     if (!Number.isFinite(minDurationMinutes) || minDurationMinutes <= 0)
         return true;
     const { startedAt, endedAt } = data.ref;
     if (typeof startedAt !== "number" || typeof endedAt !== "number")
         return true;
-    const durationMinutes = (endedAt - startedAt) / 60_000;
-    return durationMinutes >= minDurationMinutes;
+    return (endedAt - startedAt) / 60_000 >= minDurationMinutes;
 }
-/**
- * Build per-harness `access` instructions for reading the raw session log.
- *
- * Documented convention (#561, checklist item "Document `access` field
- * convention per harness"): the string tells a downstream agent exactly how to
- * read and parse the source at `log_path`. New harnesses fall back to a generic
- * `cat <log_path>` hint for file-backed logs.
- */
+/** How an agent reads and parses the raw log at `log_path`, per harness (`cat` otherwise). */
 export function buildSessionAccessInstructions(harness, logPath, sessionId) {
-    const canonical = harness;
-    if (canonical === "claude") {
+    if (harness === "claude") {
         return [
             `Read with: cat ${logPath}`,
             `Parse messages: jq -r 'select(.type=="message") | .message.content[]? | select(.type=="text") | .text' ${logPath}`,
         ].join("\n");
     }
-    if (canonical === "opencode") {
+    if (harness === "opencode") {
         return [
             `Open the SQLite database at ${JSON.stringify(logPath)} in read-only mode.`,
             "Query: SELECT m.data, p.data FROM message AS m JOIN part AS p ON p.message_id = m.id WHERE m.session_id = ? AND p.session_id = ? ORDER BY m.time_created, p.time_created;",
             `Bind both parameters to ${JSON.stringify(sessionId)}.`,
         ].join("\n");
     }
-    // Generic fallback — file-backed logs are always readable with cat.
     return `Read with: cat ${logPath}`;
 }
-/** ISO-8601 (UTC) from a ms-epoch, or undefined when absent/non-finite. */
 function isoOrUndefined(ms) {
     return typeof ms === "number" && Number.isFinite(ms) ? new Date(ms).toISOString() : undefined;
 }
 /** Default session-name slug: `<harness>-session-<yyyy-mm-dd>-<shortId>`. */
 export function buildSessionAssetName(harness, sessionId, startedAtMs) {
-    const canonical = harness;
-    const datePart = isoOrUndefined(startedAtMs)?.slice(0, 10) ?? "unknown-date";
-    const shortId = sessionId.slice(0, 8);
-    return `${canonical}-session-${datePart}-${shortId}`;
+    return `${harness}-session-${isoOrUndefined(startedAtMs)?.slice(0, 10) ?? "unknown-date"}-${sessionId.slice(0, 8)}`;
 }
-/**
- * Assemble the full session asset (frontmatter + `## Summary` / `## Key topics`).
- * Pure — no IO. Returns the serialized markdown string.
- */
+/** The session asset: frontmatter plus `## Summary` and `## Key topics`. */
 export function buildSessionAssetContent(data, summary) {
     const ref = data.ref;
     const harness = ref.harness;
@@ -213,8 +143,7 @@ export function buildSessionAssetContent(data, summary) {
         .map((t) => `- ${t.trim()}`)
         .join("\n");
     const body = `## Summary\n\n${summary.summary.trim()}\n\n## Key topics\n\n${topics || "- (none extracted)"}\n`;
-    // `description` is duplicated into frontmatter so the metadata pass surfaces
-    // it without re-reading the body — matches how other content types behave.
+    // The summary doubles as the description, as for other types.
     const content = assembleAsset({ ...frontmatter, description: summary.summary.trim() }, body);
     return { name, frontmatter, content };
 }
@@ -223,13 +152,7 @@ export function resolveSessionAssetPath(stashDir, harness, sessionId) {
     const dir = stashDirFor("session") ?? "sessions";
     return path.join(stashDir, dir, harness, `${sessionId}.md`);
 }
-/**
- * Generate (via the injected summarizer) and write a session asset to the stash.
- *
- * FAIL-OPEN: when the summarizer returns `undefined` (disabled / no LLM /
- * error), NOTHING is written and `{ written: false }` is returned. Any write
- * error is swallowed by the caller — session indexing must NEVER break extract.
- */
+/** Summarize and write a session asset; nothing without a summary. The caller swallows write errors. */
 export async function writeSessionAsset(data, stashDir, generate) {
     const summary = await generate(data);
     if (!summary?.summary || summary.summary.trim().length === 0) {
@@ -241,15 +164,11 @@ export async function writeSessionAsset(data, stashDir, generate) {
     const filePath = resolveSessionAssetPath(stashDir, harness, sessionId);
     fs.mkdirSync(path.dirname(filePath), { recursive: true });
     fs.writeFileSync(filePath, content, "utf8");
-    // #652: extract's session asset is written outside the proposal queue —
-    // journal it so the run's auto-sync stages it as one of its own writes.
+    // Written outside the proposal queue: journal it so auto-sync commits it (#652).
     recordWrittenPath(filePath);
     return {
         written: true,
         filePath,
-        // 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", `${harness}/${sessionId}`),
         logPath: data.ref.filePath,
     };