akm-cli 0.9.0-beta.45 → 0.9.0-beta.47

package/dist/assets/wiki/ingest-workflow-template.md

@@ -6,20 +6,27 @@ Schema: {{SCHEMA_PATH}}
 Follow these steps. akm commands handle the invariants; use your native
 Read/Write/Edit tools for page edits.
 
+This workflow is for ingesting sources that are ALREADY present under
+`{{WIKI_DIR}}/raw/`. Do not ask the user for a source unless the raw queue is
+empty and the caller explicitly asked for interactive ingest.
+
 1. **Read the schema.** Open `{{SCHEMA_PATH}}`. It defines the voice, page
    kinds, contradiction policy, and any wiki-specific conventions. Do not
    skip this step even on familiar wikis — the schema may have changed.
 
-2. **File the source under `raw/`.**
+2. **Discover the pending raw queue.**
    ```sh
-   akm wiki stash {{WIKI_NAME}} <path-or-url-to-source>
-   # or: cat <source> | akm wiki stash {{WIKI_NAME}} -
+   akm wiki lint {{WIKI_NAME}}
    ```
-   Returns `{ slug, path, ref }`. The raw copy is immutable — never edit it.
+   Focus on `uncited-raw` findings: those raw files exist under `raw/` but are
+   not yet cited by any authored page. Treat each `uncited-raw` finding as a
+   pending ingest item. If there are no `uncited-raw` findings, exit cleanly
+   after a final `akm index` + `akm wiki lint {{WIKI_NAME}}` verification.
 
-3. **Find related existing pages.**
+3. **For each pending raw file, read the source and find related pages.**
+   Open the raw file directly from `{{WIKI_DIR}}/raw/`, then search:
    ```sh
-   akm wiki search {{WIKI_NAME}} "<key terms from the source>"
+   akm wiki search {{WIKI_NAME}} "<key terms from the raw source>"
    ```
    Read the top hits with `akm show wiki:{{WIKI_NAME}}/<page>`. Use
    `akm show wiki:{{WIKI_NAME}}/<page> toc` for large pages.
@@ -39,8 +46,8 @@ Read/Write/Edit tools for page edits.
 6. **Update xrefs both ways.** If page A now xrefs page B, page B must xref
    page A. `akm wiki lint {{WIKI_NAME}}` will flag violations.
 
-7. **Append to `log.md`.** One entry per ingest: date, source slug, one-line
-   summary, refs to created/edited pages. Newest at the top.
+7. **Append to `log.md`.** One entry per ingested raw source: date, raw slug,
+   one-line summary, refs to created/edited pages. Newest at the top.
 
 8. **Regenerate the index + verify.**
    ```sh
@@ -50,5 +57,5 @@ Read/Write/Edit tools for page edits.
    Resolve any lint findings before calling the ingest done.
 
 That's it. `akm` never calls an LLM — reasoning is your job; it just owns
-the invariants (raw immutability, unique slugs, ref validation, index
-regeneration, structural lint).
+the invariants (raw immutability, ref validation, index regeneration,
+structural lint).

package/dist/cli/shared.js

@@ -15,6 +15,7 @@ import { getOutputMode } from "../output/context.js";
 import { DEFAULT_TEMPLATE, deliverRendered, escapeHtml, renderHtml, resolveTemplatePath } from "../output/html-render.js";
 import { shapeForCommand } from "../output/shapes.js";
 import { formatPlain, outputJsonl } from "../output/text.js";
+import { hasSubcommand } from "./parse-args.js";
 // ── Exit codes ───────────────────────────────────────────────────────────────
 /**
  * Canonical process exit-code table for the akm CLI. Single source of truth —
@@ -111,6 +112,33 @@ export function defineJsonCommand(def) {
         run: (context) => runWithJsonErrors(() => run(context)),
     });
 }
+/**
+ * Define a citty subcommand-group command (env, secret, proposal, tasks, wiki,
+ * graph, …) that shares one wiring shape: a `subCommands` map, a routing set
+ * DERIVED from that map's keys (so the set can never silently desync from the
+ * registered subcommands), and a default body that fires ONLY for the bare
+ * group invocation — citty still runs the group body after dispatching a
+ * subcommand, so the shared guard short-circuits when `args._[0]` names a
+ * registered subcommand.
+ *
+ * The `defaultRun` body is wrapped in `runWithJsonErrors`, so it emits a
+ * byte-identical JSON error envelope on throw — exactly the per-site
+ * `run() { return runWithJsonErrors(() => { if (hasSubcommand(...)) return; … }); }`
+ * boilerplate this replaces.
+ */
+export function defineGroupCommand(def) {
+    const subcommandSet = new Set(Object.keys(def.subCommands));
+    return defineCommand({
+        meta: def.meta,
+        ...(def.args ? { args: def.args } : {}),
+        subCommands: def.subCommands,
+        run: (context) => runWithJsonErrors(() => {
+            if (hasSubcommand(context.args, subcommandSet))
+                return;
+            return def.defaultRun(context);
+        }),
+    });
+}
 /**
  * Render a command result according to the active output mode
  * (json/jsonl/yaml/text/md/html). When `--output <path>` is set, the rendered

package/dist/cli.js

@@ -77,7 +77,7 @@ import { registryCommand } from "./commands/registry-cli.js";
 import { addCommand } from "./commands/sources/add-cli.js";
 import { renderMigrationHelp } from "./commands/sources/migration-help.js";
 import { cloneCommand, historyCommand, listCommand, removeCommand, syncCommand, updateCommand, upgradeCommand, } from "./commands/sources/sources-cli.js";
-import { dbCommand, importKnowledgeCommand, indexCommand, infoCommand, initCommand, } from "./commands/sources/stash-cli.js";
+import { importKnowledgeCommand, indexCommand, infoCommand, initCommand } from "./commands/sources/stash-cli.js";
 import { tasksCommand } from "./commands/tasks/tasks-cli.js";
 import { wikiCommand } from "./commands/wiki-cli.js";
 import { workflowCommand } from "./commands/workflow-cli.js";
@@ -486,7 +486,6 @@ export const main = defineCommand({
         health: healthCommand,
         info: infoCommand,
         graph: graphCommand,
-        db: dbCommand,
         add: addCommand,
         list: listCommand,
         remove: removeCommand,

package/dist/commands/env/env-cli.js

@@ -19,8 +19,8 @@ import { spawnSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
 import { defineCommand } from "citty";
-import { getStringArg, hasSubcommand } from "../../cli/parse-args.js";
-import { output, runWithJsonErrors } from "../../cli/shared.js";
+import { getStringArg } from "../../cli/parse-args.js";
+import { defineGroupCommand, output, runWithJsonErrors } from "../../cli/shared.js";
 import { assertFlatAssetName, combineCreatePath, normalizeCreateSubPath } from "../../core/asset/asset-create.js";
 import { deriveCanonicalAssetName, resolveAssetPathFromName } from "../../core/asset/asset-spec.js";
 import { isWithin, writeFileAtomic } from "../../core/common.js";
@@ -499,31 +499,23 @@ const envUnsetCommand = defineCommand({
         });
     },
 });
-// Single source of truth: the routing set is derived from the subCommands keys
-// (M10) so adding a subcommand can never silently desync from `hasSubcommand`.
-const envSubCommands = {
-    list: envListCommand,
-    path: envPathCommand,
-    export: envExportCommand,
-    run: envRunCommand,
-    create: envCreateCommand,
-    set: envSetCommand,
-    unset: envUnsetCommand,
-    remove: envRemoveCommand,
-};
-const ENV_SUBCOMMAND_SET = new Set(Object.keys(envSubCommands));
-export const envCommand = defineCommand({
+export const envCommand = defineGroupCommand({
     meta: {
         name: "env",
         description: "Manage `.env` files — a group of related CONFIGURATION values for an app or service (URLs, flags, plus any credentials it needs), loaded together. Values may or may not be sensitive; akm protects them all the same (key names visible, values never in structured output). For a single sensitive value used on its own (an auth token, key, or cert), use `akm secret`.",
     },
-    subCommands: envSubCommands,
-    run({ args }) {
-        return runWithJsonErrors(async () => {
-            if (hasSubcommand(args, ENV_SUBCOMMAND_SET))
-                return;
-            const { listKeys } = await import("./env.js");
-            output("env-list", { envs: listEnvsRecursive(listKeys) });
-        });
+    subCommands: {
+        list: envListCommand,
+        path: envPathCommand,
+        export: envExportCommand,
+        run: envRunCommand,
+        create: envCreateCommand,
+        set: envSetCommand,
+        unset: envUnsetCommand,
+        remove: envRemoveCommand,
+    },
+    async defaultRun() {
+        const { listKeys } = await import("./env.js");
+        output("env-list", { envs: listEnvsRecursive(listKeys) });
     },
 });

package/dist/commands/env/secret-cli.js

@@ -19,8 +19,8 @@ import { spawnSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
 import { defineCommand } from "citty";
-import { getStringArg, hasSubcommand } from "../../cli/parse-args.js";
-import { output, runWithJsonErrors } from "../../cli/shared.js";
+import { getStringArg } from "../../cli/parse-args.js";
+import { defineGroupCommand, output, runWithJsonErrors } from "../../cli/shared.js";
 import { deriveCanonicalAssetName } from "../../core/asset/asset-spec.js";
 import { loadConfig } from "../../core/config/config.js";
 import { makeSecretRef, resolveSecretPath } from "../../core/env-secret-ref.js";
@@ -233,27 +233,19 @@ const secretRemoveCommand = defineCommand({
         });
     },
 });
-// Single source of truth: the routing set is derived from the subCommands keys
-// (M10) so adding a subcommand can never silently desync from `hasSubcommand`.
-const secretSubCommands = {
-    list: secretListCommand,
-    path: secretPathCommand,
-    run: secretRunCommand,
-    set: secretSetCommand,
-    remove: secretRemoveCommand,
-};
-const SECRET_SUBCOMMAND_SET = new Set(Object.keys(secretSubCommands));
-export const secretCommand = defineCommand({
+export const secretCommand = defineGroupCommand({
     meta: {
         name: "secret",
         description: "Manage secrets — a single sensitive value used on its own for authentication (an API token, a PEM private key, a TLS cert), one value per file. Names are visible; the file contents are the value and never appear in structured output. For a group of related configuration loaded together, use `akm env`.",
     },
-    subCommands: secretSubCommands,
-    run({ args }) {
-        return runWithJsonErrors(async () => {
-            if (hasSubcommand(args, SECRET_SUBCOMMAND_SET))
-                return;
-            output("secret-list", { secrets: listSecretsRecursive() });
-        });
+    subCommands: {
+        list: secretListCommand,
+        path: secretPathCommand,
+        run: secretRunCommand,
+        set: secretSetCommand,
+        remove: secretRemoveCommand,
+    },
+    defaultRun() {
+        output("secret-list", { secrets: listSecretsRecursive() });
     },
 });

package/dist/commands/graph/graph-cli.js

@@ -9,12 +9,9 @@
  * same JSON envelope (stdout/stderr/exit-code) as the inline `runWithJsonErrors`
  * form it replaces.
  */
-import { defineCommand } from "citty";
-import { hasSubcommand, parsePositiveIntFlag } from "../../cli/parse-args.js";
-import { defineJsonCommand, output, runWithJsonErrors } from "../../cli/shared.js";
+import { parsePositiveIntFlag } from "../../cli/parse-args.js";
+import { defineGroupCommand, defineJsonCommand, output } from "../../cli/shared.js";
 import { akmGraphEntities, akmGraphEntity, akmGraphExport, akmGraphOrphans, akmGraphRelated, akmGraphRelations, akmGraphSummary, akmGraphUpdate, } from "./graph.js";
-// Single source of truth: the routing set is derived from the subCommands keys
-// (M10) so adding a subcommand can never silently desync from `hasSubcommand`.
 const graphSubCommands = {
     summary: defineJsonCommand({
         meta: { name: "summary", description: "Show entity-graph counts and quality telemetry" },
@@ -118,15 +115,10 @@ const graphSubCommands = {
         },
     }),
 };
-const GRAPH_SUBCOMMAND_SET = new Set(Object.keys(graphSubCommands));
-export const graphCommand = defineCommand({
+export const graphCommand = defineGroupCommand({
     meta: { name: "graph", description: "Inspect the indexed entity graph stored in SQLite" },
     subCommands: graphSubCommands,
-    run({ args }) {
-        return runWithJsonErrors(() => {
-            if (hasSubcommand(args, GRAPH_SUBCOMMAND_SET))
-                return;
-            output("graph-summary", akmGraphSummary());
-        });
+    defaultRun() {
+        output("graph-summary", akmGraphSummary());
     },
 });

package/dist/commands/graph/graph.js

@@ -8,7 +8,7 @@ import { loadConfig } from "../../core/config/config.js";
 import { NotFoundError, UsageError } from "../../core/errors.js";
 import { getDbPath } from "../../core/paths.js";
 import { warn } from "../../core/warn.js";
-import { closeDatabase, findEntryIdByRef, getEntryById, getEntryRefRowsForStashRoot, openDatabase, openExistingDatabase, } from "../../indexer/db/db.js";
+import { closeDatabase, findEntryIdByRef, getEntryById, getEntryRefRowsForStashRoot, openExistingDatabase, openIndexDatabase, } from "../../indexer/db/db.js";
 import { loadStoredGraphSnapshot } from "../../indexer/db/graph-db.js";
 import { listRelatedPathsForFile } from "../../indexer/graph/graph-boost.js";
 import { runGraphExtractionPass } from "../../indexer/graph/graph-extraction.js";
@@ -385,7 +385,7 @@ export async function akmGraphUpdate(options) {
             let db;
             const resolvedPaths = new Set();
             try {
-                db = openDatabase(dbPath);
+                db = openIndexDatabase(dbPath);
                 for (const ref of options.refs) {
                     const trimmed = ref.trim();
                     if (!trimmed)
@@ -426,7 +426,7 @@ export async function akmGraphUpdate(options) {
         let db;
         const startMs = Date.now();
         try {
-            db = openDatabase(getDbPath());
+            db = openIndexDatabase(getDbPath());
             const onProgress = (event) => {
                 if (!event.currentPath)
                     return;

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

@@ -0,0 +1,141 @@
+// 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/.
+// Chunk sizing + per-chunk prompt assembly for consolidate. Pure token math and
+// prompt-string construction over MemoryEntry inputs — no LLM call, no embedder,
+// no orchestrator coupling.
+import fs from "node:fs";
+import { parseFrontmatter } from "../../../core/asset/frontmatter.js";
+import { cacheHash } from "../dedup.js";
+/**
+ * Conservative chars-per-token estimate used when computing prompt budgets.
+ * English text averages roughly 4 chars/token for most LLM tokenizers. We use
+ * 3 to stay conservative (shorter tokens = more tokens per char).
+ */
+const CHARS_PER_TOKEN = 3;
+/**
+ * Overhead budget reserved for the system prompt, chunk header lines, and per-
+ * memory metadata lines (name, description, tags, separator). Measured at
+ * roughly 600 chars for the system prompt + ~100 chars of header + ~50 chars
+ * per memory × chunk size.  We round up to 2 000 tokens to leave room for the
+ * model's own output.
+ */
+const PROMPT_OVERHEAD_TOKENS = 2_000;
+/**
+ * Default effective token budget used when the default LLM profile's
+ * `contextLength` is not set. This is intentionally conservative (4 096)
+ * rather than being set to the model's actual context window, because:
+ *
+ *   - When the agent path is used, the agent CLI (e.g. opencode)
+ *     prepends its own large system prompt + conversation history before
+ *     forwarding to the model. That overhead easily consumes 30K+ tokens on
+ *     a model with a 16K context window, leaving very little room for
+ *     chunk content.
+ *   - When the HTTP path is used (an LLM profile is selected), only the akm
+ *     system prompt and user prompt are sent, so the budget can be set to the
+ *     model's actual context length via profiles.llm[defaults.llm].contextLength.
+ *
+ * Set profiles.llm[defaults.llm].contextLength in your config file to the
+ * model's actual context window to allow larger chunks on the HTTP path.
+ */
+export const DEFAULT_CONTEXT_LENGTH_TOKENS = 4_096;
+/**
+ * Given the model's context window and the per-memory body truncation limit,
+ * return the maximum number of memories that can safely fit in one chunk
+ * without the prompt overflowing the context window.
+ *
+ * The formula is:
+ *   usableTokens = contextLength - PROMPT_OVERHEAD_TOKENS
+ *   tokensPerMemory = ceil(bodyTruncation / CHARS_PER_TOKEN)
+ *   chunkSize = floor(usableTokens / tokensPerMemory)
+ *
+ * Result is clamped between 1 and 50 to avoid degenerate values.
+ *
+ * @param contextLength - Model context window in tokens.
+ * @param bodyTruncation - Max chars per memory body included in the prompt.
+ * @param maxChunkSize - Optional override for the hardcoded cap of 50 (1–50).
+ */
+export function computeSafeChunkSize(contextLength, bodyTruncation, maxChunkSize) {
+    const usableTokens = Math.max(contextLength - PROMPT_OVERHEAD_TOKENS, 0);
+    const tokensPerMemory = Math.max(Math.ceil(bodyTruncation / CHARS_PER_TOKEN), 1);
+    const raw = Math.floor(usableTokens / tokensPerMemory);
+    return Math.max(1, Math.min(maxChunkSize ?? 50, raw));
+}
+/**
+ * Build the per-chunk user prompt fed to the consolidate LLM.
+ *
+ * Each memory is annotated with two flags that drive the system-prompt
+ * rules at lines 181-186:
+ *   - `(captureMode: hot)` — user-explicit memory; system prompt rule 2
+ *     forbids proposing delete. ~60 wasted LLM verdicts/4h on this user's
+ *     stack before this annotation.
+ *   - `(already queued)` — the memory's body hash matches a pending
+ *     consolidate proposal; system prompt rule 3 forbids proposing
+ *     promote/merge/contradict. ~107/4h before this annotation.
+ *
+ * Both annotations are visible to the LLM. `pendingProposalBodyHashes`
+ * is precomputed once per run by `loadPendingConsolidateProposalHashes`
+ * so the cost stays O(memories) inside the chunk loop.
+ */
+export function buildChunkPrompt(sourceName, memories, chunkIndex, totalChunks, bodyTruncation, pendingProposalBodyHashes = new Set(), standardsContext = "") {
+    const start = memories[0] ? `memory:${memories[0].name}` : "";
+    const end = memories[memories.length - 1] ? `memory:${memories[memories.length - 1].name}` : "";
+    const annotationsByIndex = [];
+    const hotRefs = [];
+    for (const m of memories) {
+        let body = "";
+        try {
+            body = fs.readFileSync(m.filePath, "utf8");
+        }
+        catch {
+            body = "(unreadable)";
+        }
+        const parsed = parseFrontmatter(body);
+        const isHot = parsed.data.captureMode === "hot";
+        // Use cacheHash (case-preserving stripped body) to match the domain used
+        // by loadPendingConsolidateProposalHashes and the body-embedding cache.
+        const bodyHash = cacheHash(body);
+        const isAlreadyQueued = pendingProposalBodyHashes.has(bodyHash);
+        annotationsByIndex.push({ isHot, isAlreadyQueued, body });
+        if (isHot)
+            hotRefs.push(`memory:${m.name}`);
+    }
+    const lines = [
+        `Source: ${sourceName}`,
+        `Chunk ${chunkIndex + 1} of ${totalChunks}, memories ${start}–${end}:`,
+        "",
+    ];
+    if (standardsContext.trim()) {
+        lines.push("Standards to follow (the rulebook for this target):");
+        lines.push(standardsContext.trim());
+        lines.push("");
+    }
+    // Top-of-prompt protection block for hot refs. Neutral phrasing — avoid
+    // op-words like "promote", "merge", "contradict" so the model doesn't
+    // accidentally treat the warning as a hint to use that op elsewhere
+    // (variant B leaked the word "contradict" into the control sample
+    // during the diagnostic).
+    if (hotRefs.length > 0) {
+        lines.push("⛔ DO NOT propose any `delete` operation for these refs — they are user-explicit (captureMode: hot) and the downstream guard refuses them regardless. Proposing delete for any of these only wastes tokens.");
+        for (const ref of hotRefs)
+            lines.push(`  - ${ref}`);
+        lines.push("");
+    }
+    for (let i = 0; i < memories.length; i++) {
+        const m = memories[i];
+        const { isHot, isAlreadyQueued, body } = annotationsByIndex[i];
+        const annotations = [];
+        if (isHot)
+            annotations.push("captureMode: hot");
+        if (isAlreadyQueued)
+            annotations.push("already queued");
+        const annotationSuffix = annotations.length > 0 ? ` (${annotations.join("; ")})` : "";
+        lines.push(`[${i + 1}] memory:${m.name}${annotationSuffix}`);
+        lines.push(`Description: ${m.description || "(none)"}`);
+        lines.push(`Tags: ${m.tags.length > 0 ? m.tags.join(", ") : "(none)"}`);
+        lines.push("---");
+        lines.push(body.slice(0, bodyTruncation));
+        lines.push("");
+    }
+    return lines.join("\n");
+}

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

@@ -0,0 +1,64 @@
+// 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 unparseable file is treated as not-hot, but the broader
+ * consolidate flow already guards against unparseable memories elsewhere).
+ *
+ * Defends against four observed defect classes (see
+ * `memory: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) {
+    try {
+        if (!fs.existsSync(filePath))
+            return false;
+        const content = fs.readFileSync(filePath, "utf8");
+        const parsed = parseFrontmatter(content);
+        return hasHotCaptureMode(parsed.data);
+    }
+    catch {
+        return false;
+    }
+}
+export function consolidateGuardStatus(filePath) {
+    if (!fs.existsSync(filePath))
+        return "missing";
+    let content;
+    try {
+        content = fs.readFileSync(filePath, "utf8");
+    }
+    catch {
+        return "unparseable";
+    }
+    let parsed;
+    try {
+        parsed = parseFrontmatter(content);
+    }
+    catch {
+        return "unparseable";
+    }
+    const data = parsed.data;
+    if (!data || Object.keys(data).length === 0)
+        return "unparseable";
+    return hasHotCaptureMode(data) ? "hot" : "safe";
+}

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

@@ -0,0 +1,145 @@
+// 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/.
+export function isValidOp(op) {
+    if (typeof op !== "object" || op === null)
+        return false;
+    const o = op;
+    if (o.op === "merge") {
+        return typeof o.primary === "string" && Array.isArray(o.secondaries);
+    }
+    if (o.op === "delete") {
+        return typeof o.ref === "string";
+    }
+    if (o.op === "promote") {
+        return typeof o.ref === "string" && typeof o.knowledgeRef === "string";
+    }
+    if (o.op === "contradict") {
+        return typeof o.ref === "string" && typeof o.contradictedByRef === "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 };
+                    }
+                }
+                // 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 };
+}