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

package/dist/commands/improve/collapse-detector.js

@@ -1,432 +0,0 @@
-// 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/.
-/**
- * R5 — Longitudinal collapse detector
- * (docs/architecture/specs/improve-collapse-churn-detector-design.md).
- *
- * Detects the measured collapse failure mode of LLM-consolidated memory
- * stores: repeated merges destroy information — canary retrieval recall
- * downtrends, distinct-content entropy downtrends, or the store shrinks
- * while generation counts rise.
- *
- * The CHURN alert class described in the design doc was removed: production
- * never threaded a real accepted-change-volume signal in (the value was a
- * hardcoded 0 from the 0.9.0 confidence-gate deletion onward), so the alert
- * could never fire. See the design doc's status note for the removal
- * rationale. `improve_cycle_metrics.accepted_actions` stays in the schema and
- * is written as 0 because deployed `state.db` files already contain it and
- * removing it would be a destructive schema change.
- *
- * Hard invariants: deterministic only (FTS BM25 + hashing — never an LLM,
- * never an embedding model); bounded storage (< 2 KB per qualifying cycle,
- * 365-day retention); fail-open (an error warns and skips, never breaks an
- * improve run); runs only on cycles where consolidate did work.
- *
- * Observe-only in v1: alerts land in `improve_cycle_metrics.alerts_json`, the
- * events log (`collapse_detector_alert`), and the `akm health` advisory —
- * nothing is ever blocked.
- *
- * @module collapse-detector
- */
-import { randomBytes } from "node:crypto";
-import { parseBundleRef } from "../../core/asset/asset-ref.js";
-import { conceptIdFromTypeName } from "../../core/asset/resolve-ref.js";
-import { getImproveProcessConfig } from "../../core/config/config.js";
-import { appendEvent } from "../../core/events.js";
-import { withStateDb } from "../../core/state-db.js";
-import { warn } from "../../core/warn.js";
-import { deactivateCanarySet, getActiveCanaries, getCanariesBySetId, insertCanaries, insertCycleMetrics, listActiveCanarySetIds, queryRecentCycleMetrics, } from "../../storage/repositories/canaries-repository.js";
-import { closeDatabase, openExistingDatabase } from "../../storage/repositories/index-connection.js";
-import { getAllEntries } from "../../storage/repositories/index-entries-repository.js";
-import { searchFts } from "../../storage/repositories/index-fts-repository.js";
-import { computeBigramDiversity, DEFAULT_MAX_GENERATION } from "./anti-collapse.js";
-import { getAllRankScores } from "./salience.js";
-// ── Defaults (mirrored in config-schema.ts ImproveCollapseDetectorSchema) ────
-export const DEFAULT_CANARY_COUNT = 40; // owner-approved 30–50 range
-export const DEFAULT_CANARY_K = 10;
-export const DEFAULT_WINDOW_CYCLES = 5;
-export const DEFAULT_RECALL_DROP_THRESHOLD = 0.15;
-export const DEFAULT_ENTROPY_DROP_THRESHOLD = 0.05;
-export const DEFAULT_RETENTION_DAYS = 365;
-/** Deterministic bigram-diversity sample cap (cost bound at 10k assets). */
-const DIVERSITY_SAMPLE_CAP = 2000;
-/**
- * Minimum merge-floor violations in one cycle before the advisory alert fires.
- * The specificity floor is deliberately strict (Phase-1 tuning pending), so a
- * couple of borderline merges per cycle must not flip `akm health` to warn —
- * that alert fatigue would drown the real collapse signals.
- */
-const MERGE_FLOOR_ALERT_MIN = 3;
-/** The learning-store types the detector measures. */
-const LEARNING_TYPES = new Set(["memory", "lesson", "knowledge"]);
-// ── Canary set ────────────────────────────────────────────────────────────────
-/** Deterministic query string for one anchor entry: name tokens + top tags + description head. */
-function buildCanaryQuery(entry) {
-    const nameTokens = entry.entry.name.split(/[-_/.]+/).filter((t) => t.length > 1);
-    const tags = (entry.entry.tags ?? []).slice(0, 3);
-    const descriptionHead = (entry.entry.description ?? "").split(/\s+/).slice(0, 6);
-    const parts = [...nameTokens, ...tags, ...descriptionHead].filter((t) => t.length > 0);
-    return [...new Set(parts)].join(" ");
-}
-/** Build the mint candidate list (deterministic given index + salience tables). */
-function buildMintList(stateDb, entries, cfg) {
-    const canaryCount = cfg.canaryCount ?? DEFAULT_CANARY_COUNT;
-    const rankScores = getAllRankScores(stateDb);
-    // Chunk-8 WI-8.5c: the canary anchor + salience correlation both key on the
-    // SHORT conceptId (`<stash-subdir>/<name>`, D-R2) — the same spelling the
-    // improve candidate refs and content xrefs now carry (post WI-8.5a).
-    const candidates = entries
-        .filter((e) => LEARNING_TYPES.has(e.entry.type))
-        .map((e) => {
-        const ref = conceptIdFromTypeName(e.entry.type, e.entry.name);
-        return { e, ref, score: rankScores.get(ref) ?? 0 };
-    })
-        .sort((a, b) => b.score - a.score || (a.ref < b.ref ? -1 : 1));
-    // Type-stratified top slice: ⅓ per learning type, backfill from global order.
-    const perType = Math.ceil(canaryCount / 3);
-    const picked = new Map();
-    for (const type of LEARNING_TYPES) {
-        let taken = 0;
-        for (const c of candidates) {
-            if (taken >= perType || picked.size >= canaryCount)
-                break;
-            if (c.e.entry.type === type && !picked.has(c.ref)) {
-                picked.set(c.ref, c);
-                taken++;
-            }
-        }
-    }
-    for (const c of candidates) {
-        if (picked.size >= canaryCount)
-            break;
-        if (!picked.has(c.ref))
-            picked.set(c.ref, c);
-    }
-    return [...picked.values()]
-        .map((c) => ({ anchorRef: c.ref, query: buildCanaryQuery(c.e) }))
-        .filter((c) => c.query.length > 0);
-}
-/** Collision-safe mint token (same-millisecond mints happen in tests + concurrent runs). */
-function newCanarySetId() {
-    return `canary-${Date.now().toString(36)}-${randomBytes(2).toString("hex")}`;
-}
-/**
- * Mint (or return) the active canary set. Deterministic given the index +
- * salience tables: rank the three learning types by `asset_salience.rank_score`
- * (fallback 0, tie-broken by ref), take a type-stratified top slice
- * (⅓ per type, backfilled from the global ranking when a type is short).
- *
- * Returns `null` when the index has no mintable learning entries — a cycle
- * with no canary set is NOT recorded (a fresh unused set id every cycle would
- * mean the trend window never fills and recall reads as a fake 0).
- *
- * NEVER auto-refreshes: once minted the set is frozen until an explicit
- * `bun scripts/refresh-canary-set.ts --refresh` — silent re-baselining is how
- * a slow collapse hides. Rows are read back BY OUR OWN set id (never "newest
- * active") so a concurrent mint in another process cannot relabel this run's
- * metrics.
- */
-export function ensureCanarySet(stateDb, indexDb, cfg, preloadedEntries) {
-    const existing = getActiveCanaries(stateDb);
-    if (existing.length > 0) {
-        return { canarySetId: existing[0].canary_set_id, canaries: existing };
-    }
-    const minted = buildMintList(stateDb, preloadedEntries ?? getAllEntries(indexDb), cfg);
-    if (minted.length === 0)
-        return null;
-    const canarySetId = newCanarySetId();
-    insertCanaries(stateDb, canarySetId, minted);
-    return { canarySetId, canaries: getCanariesBySetId(stateDb, canarySetId) };
-}
-/**
- * Explicit canary re-mint (the ONLY refresh path —
- * `bun scripts/refresh-canary-set.ts --refresh`). Mint-first, deactivate-after:
- * when the index is empty or unreadable the current baseline is left untouched
- * instead of destroyed. Deactivates ALL other active sets (not just the
- * newest) so stragglers from an interrupted refresh can never resurrect.
- */
-export function refreshCanarySet(stateDb, indexDb, cfg) {
-    const minted = buildMintList(stateDb, getAllEntries(indexDb), cfg);
-    if (minted.length === 0)
-        return null; // nothing mintable — keep the old baseline
-    const canarySetId = newCanarySetId();
-    insertCanaries(stateDb, canarySetId, minted);
-    for (const oldSetId of listActiveCanarySetIds(stateDb)) {
-        if (oldSetId !== canarySetId)
-            deactivateCanarySet(stateDb, oldSetId);
-    }
-    return { canarySetId, canaries: getCanariesBySetId(stateDb, canarySetId) };
-}
-// ── Cycle metrics ─────────────────────────────────────────────────────────────
-/**
- * Name-free content fingerprint text for entropy metrics. The indexed
- * search_text EMBEDS the (unique) entry name, which would pin the
- * distinct-content ratio at 1.0 forever; convergence shows up in the
- * description/tags/heading fields, so those are what get hashed. Bounded body
- * content is searchable but deliberately excluded from this fingerprint: the
- * detector measures the structured surface generic merged assets converge on.
- */
-function contentFingerprint(entry) {
-    const parts = [entry.description ?? "", (entry.tags ?? []).join(" "), (entry.toc ?? []).map((h) => h.text).join(" ")];
-    return parts.filter((t) => t.length > 0).join(" ");
-}
-/** FNV-1a 64-bit over lowercased whitespace-collapsed text (distinct-content hashing). */
-export function normHash(text) {
-    const normalized = text.toLowerCase().replace(/\s+/g, " ").trim();
-    let hash = 0xcbf29ce484222325n;
-    const prime = 0x100000001b3n;
-    for (let i = 0; i < normalized.length; i++) {
-        hash ^= BigInt(normalized.charCodeAt(i));
-        hash = (hash * prime) & 0xffffffffffffffffn;
-    }
-    return hash.toString(16);
-}
-/**
- * Score one canary against the live index, merge-following via canonical
- * `xrefs`. A hit is the anchor ref itself or any returned entry whose
- * provenance contains the anchor.
- * Returns the 0-based rank of the first hit, or -1.
- */
-function scoreCanary(indexDb, canary, k) {
-    const results = searchFts(indexDb, canary.query, k);
-    const anchorConceptId = canaryConceptId(canary.anchor_ref);
-    for (let i = 0; i < Math.min(results.length, k); i++) {
-        const r = results[i];
-        // Persisted canaries may be fully qualified after a state migration while
-        // index refs and xrefs remain short conceptIds. Compare identity, not display
-        // spelling, so migration alone cannot collapse recall to zero.
-        const ref = conceptIdFromTypeName(r.entry.type, r.entry.name);
-        if (ref === anchorConceptId)
-            return i;
-        const provenance = r.entry.xrefs ?? [];
-        if (provenance.some((sourceRef) => canaryConceptId(sourceRef) === anchorConceptId))
-            return i;
-    }
-    return -1;
-}
-function canaryConceptId(ref) {
-    try {
-        return parseBundleRef(ref).conceptId;
-    }
-    catch {
-        return ref;
-    }
-}
-/**
- * Compute one qualifying cycle's store-health snapshot. One `entries` scan +
- * `canaryCount` FTS queries; no LLM, no embedding model, no filesystem reads.
- * Returns `null` when no canary set exists AND none is mintable (empty index)
- * — such a cycle is not measurable and must not be recorded.
- */
-export function computeCycleMetrics(stateDb, indexDb, args) {
-    const k = args.cfg.k ?? DEFAULT_CANARY_K;
-    const maxGeneration = args.maxGeneration ?? DEFAULT_MAX_GENERATION;
-    // Single entries scan — shared by the canary mint (if one is needed) and
-    // the store-shape metrics below.
-    const all = getAllEntries(indexDb);
-    const canarySet = ensureCanarySet(stateDb, indexDb, args.cfg, all);
-    if (canarySet === null)
-        return null;
-    const { canarySetId, canaries } = canarySet;
-    // ── Canary retrieval metrics ───────────────────────────────────────────────
-    const ranks = [];
-    let recallSum = 0;
-    let ndcgSum = 0;
-    let mrrSum = 0;
-    for (const canary of canaries) {
-        const rank = scoreCanary(indexDb, canary, k);
-        ranks.push([canary.id, rank]);
-        if (rank >= 0) {
-            recallSum += 1;
-            mrrSum += 1 / (rank + 1);
-            // Single-relevant nDCG@k closed form: ideal DCG is 1, so the score is
-            // just the discount at the hit rank.
-            ndcgSum += 1 / Math.log2(rank + 2);
-        }
-    }
-    const n = Math.max(1, canaries.length);
-    // ── Store-shape metrics (same single entries scan) ────────────────────────
-    const byType = new Map();
-    const contentHashes = new Set();
-    let learningTotal = 0;
-    let overGeneration = 0;
-    const learningTexts = [];
-    for (const e of all) {
-        byType.set(e.entry.type, (byType.get(e.entry.type) ?? 0) + 1);
-        if (!LEARNING_TYPES.has(e.entry.type))
-            continue;
-        learningTotal++;
-        const fingerprint = contentFingerprint(e.entry);
-        contentHashes.add(normHash(fingerprint));
-        if ((e.entry.generation ?? 0) > maxGeneration)
-            overGeneration++;
-        learningTexts.push({ key: e.itemRef, text: fingerprint });
-    }
-    // Deterministic diversity sample: sort by item ref, take every ⌈N/cap⌉-th row.
-    learningTexts.sort((a, b) => (a.key < b.key ? -1 : 1));
-    const step = Math.max(1, Math.ceil(learningTexts.length / DIVERSITY_SAMPLE_CAP));
-    let diversitySum = 0;
-    let diversityCount = 0;
-    for (let i = 0; i < learningTexts.length; i += step) {
-        diversitySum += computeBigramDiversity(learningTexts[i].text);
-        diversityCount++;
-    }
-    return {
-        run_id: args.runId,
-        ts: (args.now ?? new Date()).toISOString(),
-        pass: args.pass,
-        canary_set_id: canarySetId,
-        mean_recall: recallSum / n,
-        mean_ndcg: ndcgSum / n,
-        mean_mrr: mrrSum / n,
-        canary_ranks_json: JSON.stringify(ranks),
-        store_total: learningTotal,
-        store_by_type_json: JSON.stringify(Object.fromEntries([...byType.entries()].sort())),
-        distinct_content_ratio: learningTotal === 0 ? 1 : contentHashes.size / learningTotal,
-        mean_bigram_diversity: diversityCount === 0 ? 1 : diversitySum / diversityCount,
-        over_generation_count: overGeneration,
-        // Always 0 — the CHURN alert this fed was removed. The column is NOT NULL
-        // in a released migration body, so it is written rather than dropped.
-        accepted_actions: 0,
-        merge_floor_violations: args.mergeFloorViolations,
-        alerts_json: "[]",
-    };
-}
-// ── Alert evaluation (pure) ───────────────────────────────────────────────────
-function median(values) {
-    if (values.length === 0)
-        return Number.NaN;
-    const sorted = [...values].sort((a, b) => a - b);
-    const mid = Math.floor(sorted.length / 2);
-    return sorted.length % 2 === 0 ? (sorted[mid - 1] + sorted[mid]) / 2 : sorted[mid];
-}
-/**
- * Evaluate the §1 alert definitions. PURE — history rows (oldest-first, NOT
- * including `current`) plus the current row in, alerts out. A window shorter
- * than `windowCycles` never fires (no baseline yet); the merge-floor advisory
- * is per-cycle and fires regardless of window depth.
- */
-export function evaluateCollapseAlerts(history, current, cfg) {
-    const alerts = [];
-    // MERGE-FLOOR advisory: per-cycle, window-independent. Gated on a minimum
-    // count — the specificity floor is deliberately strict pre-tuning, and one
-    // or two borderline merges per cycle must not generate alert fatigue.
-    if (current.merge_floor_violations >= MERGE_FLOOR_ALERT_MIN) {
-        alerts.push({
-            kind: "merge-floor",
-            detail: `${current.merge_floor_violations} merge(s) failed the information floor this cycle (provenance shrank or specificity below threshold)`,
-            metrics: { mergeFloorViolations: current.merge_floor_violations },
-        });
-    }
-    const W = cfg.windowCycles ?? DEFAULT_WINDOW_CYCLES;
-    const hist = history.slice(-W);
-    if (hist.length < W)
-        return alerts; // no baseline yet
-    // Window is non-empty here: `windowCycles` is schema-bounded to ≥2 (default 5),
-    // so `hist.length >= W >= 2`. `windowStart` is the oldest row in the window.
-    const windowStart = hist[0];
-    const recallDrop = cfg.recallDropThreshold ?? DEFAULT_RECALL_DROP_THRESHOLD;
-    const entropyDrop = cfg.entropyDropThreshold ?? DEFAULT_ENTROPY_DROP_THRESHOLD;
-    // COLLAPSE 1 — canary recall drop vs window median (median, not previous
-    // cycle, so one noisy cycle can neither fire nor mask the alert).
-    const medianRecall = median(hist.map((h) => h.mean_recall));
-    if (current.mean_recall <= medianRecall - recallDrop) {
-        alerts.push({
-            kind: "collapse-recall",
-            detail: `mean canary recall ${current.mean_recall.toFixed(3)} dropped ≥${recallDrop} below the ${W}-cycle median ${medianRecall.toFixed(3)}`,
-            metrics: { currentRecall: current.mean_recall, medianRecall, threshold: recallDrop },
-        });
-    }
-    // COLLAPSE 2 — monotonic distinct-content-ratio decline over the window.
-    const series = [...hist.map((h) => h.distinct_content_ratio), current.distinct_content_ratio];
-    const monotonicNonIncreasing = series.every((v, i) => i === 0 || v <= series[i - 1]);
-    const totalDecline = windowStart.distinct_content_ratio - current.distinct_content_ratio;
-    if (monotonicNonIncreasing && totalDecline >= entropyDrop) {
-        alerts.push({
-            kind: "collapse-entropy",
-            detail: `distinct-content ratio declined monotonically by ${totalDecline.toFixed(3)} (≥${entropyDrop}) over ${W} cycles — store content is converging`,
-            metrics: {
-                windowStart: windowStart.distinct_content_ratio,
-                current: current.distinct_content_ratio,
-                decline: totalDecline,
-            },
-        });
-    }
-    // COLLAPSE 3 — store shrinking BECAUSE of re-merging (not deletion hygiene).
-    const maxStore = Math.max(...hist.map((h) => h.store_total));
-    if (current.store_total < 0.8 * maxStore && current.over_generation_count > windowStart.over_generation_count) {
-        alerts.push({
-            kind: "collapse-shrink",
-            detail: `store shrank >20% (${current.store_total} vs window max ${maxStore}) while over-generation count rose (${windowStart.over_generation_count} → ${current.over_generation_count})`,
-            metrics: {
-                storeTotal: current.store_total,
-                windowMax: maxStore,
-                overGeneration: current.over_generation_count,
-            },
-        });
-    }
-    return alerts;
-}
-// ── Orchestrator ─────────────────────────────────────────────────────────────
-/**
- * Run the detector for one qualifying cycle: ensure canaries → compute →
- * evaluate against stored history → persist the row → append one
- * `collapse_detector_alert` event per fired alert. FAIL-OPEN: any error warns
- * and returns undefined — an improve run is never broken by its own
- * instrumentation.
- */
-export function runCollapseDetector(args) {
-    const cfg = args.config.improve?.collapseDetector ?? {};
-    if (cfg.enabled === false)
-        return undefined;
-    try {
-        let indexDb;
-        try {
-            indexDb = openExistingDatabase(args.indexDbPath);
-            const db = indexDb;
-            // Over-generation threshold mirrors the guard actually in effect —
-            // reading the same config key keeps the two aligned when tuned.
-            const antiCollapse = getImproveProcessConfig("consolidate", args.improveProfile)?.antiCollapse;
-            const maxGeneration = antiCollapse?.maxGeneration ?? DEFAULT_MAX_GENERATION;
-            return withStateDb((stateDb) => {
-                const row = computeCycleMetrics(stateDb, db, {
-                    runId: args.runId,
-                    pass: args.pass,
-                    mergeFloorViolations: args.mergeFloorViolations,
-                    cfg,
-                    maxGeneration,
-                });
-                if (row === null)
-                    return undefined; // empty index — nothing to measure
-                const windowCycles = cfg.windowCycles ?? DEFAULT_WINDOW_CYCLES;
-                const history = queryRecentCycleMetrics(stateDb, row.canary_set_id, windowCycles);
-                const alerts = evaluateCollapseAlerts(history, row, cfg);
-                row.alerts_json = JSON.stringify(alerts.map((a) => a.kind));
-                insertCycleMetrics(stateDb, row);
-                for (const alert of alerts) {
-                    appendEvent({
-                        eventType: "collapse_detector_alert",
-                        ref: undefined,
-                        metadata: {
-                            kind: alert.kind,
-                            detail: alert.detail,
-                            metrics: alert.metrics,
-                            canarySetId: row.canary_set_id,
-                            runId: args.runId,
-                        },
-                    }, args.eventsCtx);
-                }
-                return row;
-            }, { path: args.eventsCtx?.dbPath, borrowed: args.eventsCtx?.db });
-        }
-        finally {
-            if (indexDb)
-                closeDatabase(indexDb);
-        }
-    }
-    catch (err) {
-        warn(`[collapse-detector] skipped (fail-open): ${err instanceof Error ? err.message : String(err)}`);
-        return undefined;
-    }
-}

package/dist/commands/improve/consolidate/eligibility.js

@@ -1,48 +0,0 @@
-// 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/.
-// Eligibility / safety predicates for consolidate: "may we touch this memory?"
-// One reason to change — the policy for what consolidate is allowed to act on.
-import fs from "node:fs";
-import { parseFrontmatter } from "../../../core/asset/frontmatter.js";
-import { hasHotCaptureMode } from "../../proposal/validators/proposal-quality-validators.js";
-export function isConsolidationEligibleMemoryName(name) {
-    return !name.endsWith(".derived");
-}
-/**
- * Returns true when the memory file has `captureMode: hot` in its frontmatter.
- *
- * Hot memories are USER-EXPLICIT (written via `akm remember` on the hot path).
- * The consolidate LLM is forbidden from deleting or auto-merging them — the
- * user wrote them on purpose and only the user can decide to retire them.
- *
- * Reads the file once per check; consolidate runs against ~10 memories per
- * chunk so the IO cost is trivial. Returns false on any read/parse error
- * (fail-safe: an unreadable or unparseable file is treated as HOT — protected
- * — because a deletion shield must not fail open; a missing file is not-hot).
- *
- * Defends against four observed defect classes (see
- * `memories/akm-improve-critical-review-2026-05-20`):
- *   - LLM marks a memory contradicted then deletes (dangling contradictedBy)
- *   - LLM merges two unrelated memories sharing a topic keyword
- *   - LLM judges a recent durable design memo as "redundant"
- *   - Cascade deletes (LLM uses ref:X as `contradictedBy` for ref:Y then deletes both)
- */
-export function isHotCapturedMemory(filePath) {
-    if (!fs.existsSync(filePath))
-        return false;
-    try {
-        const content = fs.readFileSync(filePath, "utf8");
-        const parsed = parseFrontmatter(content);
-        return hasHotCaptureMode(parsed.data);
-    }
-    catch {
-        // Fail CLOSED. This predicate is a deletion shield: "hot" memories are
-        // protected from consolidate's merge/delete. Returning false on a read or
-        // parse failure marked exactly the memories we could not inspect as fair
-        // game — the one direction a protection check must never fail. A missing
-        // file stays false (nothing to protect); an unreadable one is protected
-        // until someone can actually read it.
-        return true;
-    }
-}

package/dist/commands/improve/consolidate/merge.js

@@ -1,146 +0,0 @@
-// 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/.
-// R12a: merge/delete/contradict are no longer requested (see
-// CONSOLIDATE_PLAN_JSON_SCHEMA / consolidate-system.md) — only promote is
-// ever executed. An op of one of those retired shapes — e.g. from a model
-// that ignores the schema — is rejected here so it degrades to the generic
-// "skipping invalid operation" warning in the chunk-judge loop rather than
-// being treated as an actionable (if advisory) plan entry.
-export function isValidOp(op) {
-    if (typeof op !== "object" || op === null)
-        return false;
-    const o = op;
-    if (o.op === "promote") {
-        return typeof o.ref === "string" && typeof o.knowledgeRef === "string";
-    }
-    return false;
-}
-export function mergePlans(chunks, knownRefs) {
-    const mergeOps = new Map();
-    const deleteOps = new Map();
-    const promoteOps = new Map();
-    // C-3 / #382: contradict ops keyed by `ref|contradictedByRef` to deduplicate.
-    const contradictOps = new Map();
-    const warnings = [];
-    for (const chunk of chunks) {
-        for (const op of chunk) {
-            if (op.op === "merge") {
-                // Drop ops whose primary the LLM hallucinated (not in the loaded memory
-                // pool). Without this guard, a hallucinated primary flows all the way to
-                // Phase B where !memoryByRef.has(primary) fires and charges every real
-                // secondary with merge_primary_missing — masking LLM hallucinations as
-                // filter regressions in health metrics.
-                if (knownRefs && !knownRefs.has(op.primary)) {
-                    warnings.push(`mergePlans: primary ${op.primary} not in loaded memory pool (LLM hallucination) — dropping op before execution.`);
-                    // Use a dedicated skip reason so dashboards can distinguish
-                    // hallucinated primaries from stale-DB regressions.
-                    // Secondaries are real refs; they are NOT charged here — they remain
-                    // available for other ops to claim.
-                    continue;
-                }
-                // Filter hallucinated secondaries while preserving real ones.
-                let mergeOp = op;
-                if (knownRefs) {
-                    const filteredSecondaries = op.secondaries.filter((sec) => {
-                        if (!knownRefs.has(sec)) {
-                            warnings.push(`mergePlans: secondary ${sec} not in loaded memory pool (LLM hallucination) — dropping from op.`);
-                            return false;
-                        }
-                        return true;
-                    });
-                    if (filteredSecondaries.length !== op.secondaries.length) {
-                        mergeOp = { ...op, secondaries: filteredSecondaries };
-                    }
-                }
-                if (mergeOp.secondaries.length > 1) {
-                    warnings.push(`Merge: ${mergeOp.primary} proposed multiple secondaries; retaining one secondary for review.`);
-                    mergeOp = { ...mergeOp, secondaries: mergeOp.secondaries.slice(0, 1) };
-                }
-                // merge wins over delete
-                if (deleteOps.has(mergeOp.primary)) {
-                    deleteOps.delete(mergeOp.primary);
-                }
-                for (const sec of mergeOp.secondaries) {
-                    if (deleteOps.has(sec))
-                        deleteOps.delete(sec);
-                }
-                mergeOps.set(mergeOp.primary, mergeOp);
-            }
-            else if (op.op === "delete") {
-                // merge and promote both win over delete. A promote is non-destructive
-                // (creates a proposal) but the source memory is counted in `promoted`;
-                // if a delete also fires, the ref lands in both `promoted` and
-                // `skipReasons`, breaking the invariant by +1.
-                if (!mergeOps.has(op.ref) && !promoteOps.has(op.ref)) {
-                    deleteOps.set(op.ref, op);
-                }
-            }
-            else if (op.op === "promote") {
-                // C-2 / #381: when both a promote and a merge target the same ref,
-                // queue the promote FIRST rather than discarding it. The promote op
-                // routes through createProposal (the human-gated proposal queue), so
-                // it is non-destructive. The merge follows after the proposal is
-                // created. This preserves the human reviewer's ability to inspect the
-                // promotion before the source memory is merged/deleted.
-                // AGM K*8 — retain the maximally informative consistent subset.
-                promoteOps.set(op.ref, op);
-            }
-            else if (op.op === "contradict") {
-                // Deduplicate by ref+contradictedByRef pair.
-                const key = `${op.ref}|${op.contradictedByRef}`;
-                if (!contradictOps.has(key)) {
-                    contradictOps.set(key, op);
-                }
-            }
-        }
-    }
-    // Second pass: enforce merge-wins-over-delete and deduplicate secondaries.
-    //
-    // 1. Delete/secondary ordering bug: the per-chunk loop removes delete ops
-    //    for secondaries that were already in deleteOps, but misses the case
-    //    where the delete chunk came first. A full sweep here fixes both orders.
-    //
-    // 2. Cross-merge secondary dedup: if ref A is a secondary in two merge ops,
-    //    only the first (insertion-order) retains it. Without this, a successful
-    //    merge credits A to mergedSecondaries and a later merge's emitMerge-
-    //    FailureSkips also charges A to skipReasons — double-counting A while
-    //    processed has it only once.
-    //
-    // 3. Primary-as-secondary dedup: if ref A is a primary in one merge op and
-    //    a secondary in another, remove A from the secondary list. Both merges
-    //    would otherwise claim A (merged++ for A, then mergedSecondaries++ for A)
-    //    breaking the invariant the same way.
-    // Also remove delete ops for any ref claimed by a promote op (handles the
-    // case where the delete chunk appeared before the promote chunk).
-    for (const ref of promoteOps.keys()) {
-        deleteOps.delete(ref);
-    }
-    const claimedSecondaries = new Set();
-    for (const mergeOp of mergeOps.values()) {
-        deleteOps.delete(mergeOp.primary);
-        mergeOp.secondaries = mergeOp.secondaries.filter((sec) => {
-            if (mergeOps.has(sec)) {
-                warnings.push(`Merge: secondary ${sec} is also a merge primary — removing from secondary list to avoid double-count.`);
-                return false;
-            }
-            if (claimedSecondaries.has(sec)) {
-                warnings.push(`Merge: secondary ${sec} appears in multiple merge ops — retaining in first op only.`);
-                return false;
-            }
-            claimedSecondaries.add(sec);
-            deleteOps.delete(sec);
-            return true;
-        });
-    }
-    // C-2 / #381: promote ops are ordered BEFORE merge ops so that the
-    // human-gated proposal queue entry is created before any destructive merge.
-    // Phase B processes ops in array order, so promote executes first.
-    const ops = [
-        ...promoteOps.values(),
-        ...mergeOps.values(),
-        ...deleteOps.values(),
-        ...contradictOps.values(),
-    ];
-    return { ops, warnings };
-}