akm-cli 0.7.5 → 0.8.0-rc.6

package/dist/core/errors.js

@@ -1,30 +1,19 @@
-/**
- * Typed error classes for structured exit code classification.
- *
- * - ConfigError  -> exit 78  (configuration / environment problems)
- * - UsageError   -> exit 2   (bad CLI arguments or invalid input)
- * - NotFoundError -> exit 1  (requested resource missing)
- *
- * Each error carries a machine-readable `code` field. Codes are stable
- * identifiers safe to consume from scripts and JSON output. Existing throw
- * sites without an explicit code receive a default code per error class so
- * older call sites continue to compile and behave unchanged.
- *
- * Each error also exposes a `hint()` method returning an actionable hint
- * string (or `undefined`). Hints can be supplied at construction time or
- * derived from the error `code` via the per-class default mapping below.
- * The CLI surfaces this via `error.hint()` rather than message-regex parsing.
- */
+// 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/.
 /**
  * Default hint for each ConfigError code. Keep these short, actionable, and
  * imperative. Returning undefined means "no canned hint".
  */
 const CONFIG_HINTS = {
-    STASH_DIR_NOT_FOUND: "Run `akm init` to create the default stash, or set stashDir in your config.",
+    STASH_DIR_NOT_FOUND: "Run `akm setup` to create and configure your stash, or set stashDir in your config.",
     STASH_DIR_NOT_A_DIRECTORY: "The configured stashDir exists but isn't a directory. Update stashDir to point at a folder.",
     STASH_DIR_UNREADABLE: "Check the path exists and your user has read permission, or update stashDir.",
     EMBEDDING_NOT_CONFIGURED: 'Run `akm config set embedding \'{"endpoint":"...","model":"..."}\'` to enable embeddings.',
-    LLM_NOT_CONFIGURED: 'Run `akm config set llm \'{"endpoint":"...","model":"..."}\'` to configure the LLM.',
+    LLM_NOT_CONFIGURED: 'Run `akm setup` or `akm config set profiles.llm.default \'{"endpoint":"...","model":"..."}\' to configure an LLM profile.',
+    TEST_ISOLATION_MISSING: "Under bun test, when AKM_STASH_DIR is set you MUST also set XDG_DATA_HOME (or AKM_DATA_DIR) and XDG_STATE_HOME (or AKM_STATE_DIR) to temp directories so the test does not touch the developer's real ~/.local/share/akm or ~/.local/state/akm.",
+    SETUP_TMP_STASH_REFUSED: "Use a persistent directory, or set AKM_FORCE_SETUP_TMP_STASH=1 to opt in to a sandboxed setup (setup also pre-sets AKM_STASH_DIR so config and cache writes auto-isolate into $stashDir/.akm/ — host config is preserved).",
+    UNSAFE_STASH_DIR: "Choose a path inside your home directory (e.g. ~/akm) or another empty workspace. The stash directory cannot be the filesystem root, your home directory itself, or a sensitive system path like /etc, /var, ~/.config, or ~/.ssh.",
 };
 /** Default hint for each UsageError code. */
 const USAGE_HINTS = {
@@ -92,3 +81,35 @@ export class NotFoundError extends Error {
         return this._hint ?? NOT_FOUND_HINTS[this.code];
     }
 }
+/**
+ * Test-isolation guard helper.
+ *
+ * `src/core/paths.ts` throws `ConfigError("TEST_ISOLATION_MISSING")` under
+ * `bun test` when `AKM_STASH_DIR` is set without a paired data-dir or
+ * state-dir override. That throw must never be swallowed by best-effort
+ * catches around DB/data-dir operations — otherwise the guard's loud failure
+ * silently degrades into a "no result" outcome (cold cache, missing snapshot,
+ * etc.) and the underlying test leak goes undetected.
+ *
+ * Call `rethrowIfTestIsolationError(err)` from any catch block that returns
+ * a fallback value (null, [], empty result) after touching DB or data-dir
+ * paths. It re-throws when the caught error is the guard violation, otherwise
+ * does nothing so the existing benign-fallback path can proceed unchanged.
+ *
+ * Usage:
+ *   try {
+ *     const db = openDatabase();
+ *     // ...
+ *   } catch (err) {
+ *     rethrowIfTestIsolationError(err);
+ *     // existing benign-fallback handling
+ *   }
+ */
+export function isTestIsolationError(err) {
+    return err instanceof ConfigError && err.code === "TEST_ISOLATION_MISSING";
+}
+export function rethrowIfTestIsolationError(err) {
+    if (isTestIsolationError(err)) {
+        throw err;
+    }
+}

package/dist/core/events.js

@@ -1,47 +1,28 @@
-/**
- * Append-only events stream — `events.jsonl` (#204).
- *
- * Every mutating CLI verb funnels through `appendEvent` so external
- * observers (sync, replication, audit, dashboards) can react to stash
- * changes by tailing a single file. The file is plain newline-delimited
- * JSON; each line is a self-contained event envelope.
- *
- * The helper is the only thing in akm that writes to events.jsonl. It
- * accepts injectable `now()` and `path` so tests can pin time and use a
- * tmpdir without any global mutation.
- *
- * Format (each line):
- *   { "schemaVersion": 1, "id": <number>, "ts": "<ISO>",
- *     "eventType": "<verb>", "ref"?: "<asset-ref>", ... }
- *
- * - `id` is a monotonic integer per file. We use the file's pre-write
- *   byte length as a durable cursor for `--since` (stable across processes
- *   because every appender holds an O_APPEND write). Callers can also pass
- *   a string ISO timestamp to `--since` and we filter by `ts >= since`.
- * - `ts` is ISO-8601 (UTC, millisecond precision).
- *
- * The event `id` is derived at read time (line index) — the file itself
- * is the source of truth, so the writer never has to coordinate with a
- * counter. Tail consumers can persist a byte offset (durable cursor).
- */
-import fs from "node:fs";
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import path from "node:path";
-import { getCacheDir } from "./paths";
+import { rethrowIfTestIsolationError } from "./errors";
+import { getDataDir } from "./paths";
+import { insertEvent, openStateDatabase, readStateEvents } from "./state-db";
+import { error } from "./warn";
 /**
- * Default events.jsonl location: `<cacheDir>/events.jsonl`.
- *
- * Env-isolation caveat: `getCacheDir()` reads `XDG_CACHE_HOME` at the time of
- * each call. Two cooperating processes (e.g. one writing events, one tailing)
- * MUST inherit the same `XDG_CACHE_HOME` or they will read/write different
- * `events.jsonl` files. This is the same env-isolation behaviour as the rest
- * of akm — config, indexes, and caches all key off XDG paths — so set
- * `XDG_CACHE_HOME` consistently across processes that share the events bus.
+ * Legacy events.jsonl path — used only by the migration script
+ * (`scripts/migrate-storage.ts`) to import existing event history into
+ * state.db. No events are written here by akm v0.9+.
  */
 export function getEventsPath() {
-    return path.join(getCacheDir(), "events.jsonl");
+    return path.join(getDataDir(), "events.jsonl");
 }
-function resolvePath(ctx) {
-    return ctx?.filePath ?? getEventsPath();
+/**
+ * Resolve the state.db path from context:
+ *   1. `ctx.dbPath` — explicit override (test seam)
+ *   2. default      — `<dataDir>/state.db`
+ */
+function resolveDbPath(ctx) {
+    if (ctx?.dbPath)
+        return ctx.dbPath;
+    return path.join(getDataDir(), "state.db");
 }
 function resolveNow(ctx) {
     return ctx?.now ?? Date.now;
@@ -50,129 +31,101 @@ function resolveNow(ctx) {
  * Append a single event. Best-effort: a write failure is logged once to
  * stderr but never propagates — observability must not break mutation.
  *
- * The id field is intentionally omitted on write (the line index is the
- * id; the reader assigns it). Keeping it off the wire avoids a coordination
- * step between concurrent appenders.
+ * Events are written exclusively to the `events` table in `state.db`.
+ *
+ * I1: when `ctx.db` is provided (a pre-opened long-lived connection), the
+ * function writes directly to that handle without opening or closing the DB.
+ * This eliminates per-event open/migrate/close overhead for high-frequency
+ * callers such as `akmImprove`.
  */
 export function appendEvent(input, ctx) {
-    const filePath = resolvePath(ctx);
     const now = resolveNow(ctx);
     const ts = new Date(now()).toISOString();
-    const envelope = {
-        schemaVersion: 1,
-        ts,
-        eventType: input.eventType,
-        ...(input.ref !== undefined ? { ref: input.ref } : {}),
-        ...(input.metadata !== undefined ? { metadata: input.metadata } : {}),
-    };
-    const line = `${JSON.stringify(envelope)}\n`;
+    // Fast path: caller provided a long-lived connection — use it directly.
+    if (ctx?.db) {
+        try {
+            insertEvent(ctx.db, {
+                eventType: input.eventType,
+                ts,
+                ref: input.ref,
+                metadata: input.metadata,
+            });
+        }
+        catch (err) {
+            error(`akm: appendEvent failed: ${String(err)}`);
+        }
+        return;
+    }
+    // Default path: open, insert, close.
+    const dbPath = resolveDbPath(ctx);
     try {
-        fs.mkdirSync(path.dirname(filePath), { recursive: true });
-        // O_APPEND guarantees atomic appends ≤ PIPE_BUF (4 KiB on Linux); our
-        // events are well under that ceiling, so concurrent processes can write
-        // safely without locking. `appendFileSync` opens with `'a'` which sets
-        // O_APPEND.
-        fs.appendFileSync(filePath, line, { encoding: "utf8" });
+        const db = openStateDatabase(dbPath);
+        try {
+            insertEvent(db, {
+                eventType: input.eventType,
+                ts,
+                ref: input.ref,
+                metadata: input.metadata,
+            });
+        }
+        finally {
+            db.close();
+        }
     }
     catch (err) {
+        // Never mask the bun-test isolation guard as a silent "events failed".
+        rethrowIfTestIsolationError(err);
         // Best-effort: events stream failures must not break the mutating verb.
         // Surface once to stderr so operators can diagnose.
-        const message = err instanceof Error ? err.message : String(err);
-        process.stderr.write(`akm: events.jsonl append failed (${message})\n`);
+        error(`akm: appendEvent failed: ${String(err)}`);
     }
 }
 /**
  * Read all events matching the filter. Returns a `nextOffset` that callers
- * can persist between processes for monotonic resumption — `sinceOffset`
- * is the durable cursor referenced in the acceptance criteria.
+ * can persist between processes for monotonic resumption.
  */
 export function readEvents(options = {}, ctx) {
-    const filePath = resolvePath(ctx);
-    if (!fs.existsSync(filePath)) {
-        return { events: [], nextOffset: 0 };
+    const dbPath = resolveDbPath(ctx);
+    let db;
+    try {
+        db = openStateDatabase(dbPath);
     }
-    const stat = fs.statSync(filePath);
-    const startOffset = options.sinceOffset && options.sinceOffset > 0 ? options.sinceOffset : 0;
-    if (startOffset >= stat.size) {
-        return { events: [], nextOffset: stat.size };
+    catch (err) {
+        // Never mask the bun-test isolation guard as "no events".
+        rethrowIfTestIsolationError(err);
+        // DB does not exist yet or cannot be opened — return empty result.
+        return { events: [], nextOffset: 0 };
     }
-    const fd = fs.openSync(filePath, "r");
     try {
-        const length = stat.size - startOffset;
-        const buf = Buffer.alloc(length);
-        fs.readSync(fd, buf, 0, length, startOffset);
-        const text = buf.toString("utf8");
-        const events = parseEventLines(text, options, startOffset);
-        return { events, nextOffset: stat.size };
+        const { events: rawEvents, nextId } = readStateEvents(db, {
+            sinceId: options.sinceOffset,
+            since: options.since,
+            type: options.type,
+            ref: options.ref,
+        });
+        // Apply tag filters in application code (same as the old JSONL implementation).
+        const events = rawEvents.filter((envelope) => {
+            const tags = envelope.metadata?.tags ?? [];
+            if (options.excludeTags?.some((t) => tags.includes(t)))
+                return false;
+            if (options.includeTags && !options.includeTags.every((t) => tags.includes(t)))
+                return false;
+            return true;
+        });
+        return { events, nextOffset: nextId };
     }
     finally {
-        fs.closeSync(fd);
+        db.close();
     }
 }
-function parseEventLines(text, options, startOffset) {
-    // Each line that ends with \n is a complete event. A trailing partial
-    // line (no terminating \n) is ignored — the next read will pick it up
-    // once it is fully written.
-    const out = [];
-    let lineStart = 0;
-    // The envelope id is the 1-based line index across the whole file. We
-    // approximate that here as the line index from the start of the read
-    // window plus a synthetic offset — for callers using `--since`, the
-    // absolute id is less useful than the byte cursor anyway. To keep ids
-    // monotonic across reads we use absolute byte position as a stable
-    // surrogate identifier.
-    for (let i = 0; i < text.length; i += 1) {
-        if (text.charCodeAt(i) !== 10 /* \n */)
-            continue;
-        const line = text.slice(lineStart, i);
-        const absStart = startOffset + lineStart;
-        lineStart = i + 1;
-        if (!line.trim())
-            continue;
-        let parsed;
-        try {
-            parsed = JSON.parse(line);
-        }
-        catch {
-            // Skip malformed lines — better than crashing the read pipeline.
-            continue;
-        }
-        const envelope = {
-            schemaVersion: 1,
-            id: absStart,
-            ts: typeof parsed.ts === "string" ? parsed.ts : "",
-            eventType: typeof parsed.eventType === "string" ? parsed.eventType : "unknown",
-            ...(typeof parsed.ref === "string" ? { ref: parsed.ref } : {}),
-            ...(parsed.metadata !== undefined ? { metadata: parsed.metadata } : {}),
-        };
-        if (!matchesFilter(envelope, options))
-            continue;
-        out.push(envelope);
-    }
-    return out;
-}
-function matchesFilter(envelope, options) {
-    if (options.type && envelope.eventType !== options.type)
-        return false;
-    if (options.ref && envelope.ref !== options.ref)
-        return false;
-    if (options.since && envelope.ts && envelope.ts < options.since)
-        return false;
-    const tags = envelope.metadata?.tags ?? [];
-    if (options.excludeTags?.some((t) => tags.includes(t)))
-        return false;
-    if (options.includeTags && !options.includeTags.every((t) => tags.includes(t)))
-        return false;
-    return true;
-}
 /**
- * Follow events.jsonl. Polls at `intervalMs` (default 75ms) and emits
- * every new event to `onEvent`. Resolves when `signal` aborts, when
+ * Follow the events table in state.db. Polls at `intervalMs` (default 75ms)
+ * and emits every new event to `onEvent`. Resolves when `signal` aborts, when
  * `maxEvents` events have been observed, or when `maxDurationMs` elapses.
  *
- * The polling cursor is byte-offset based, so concurrent writers cannot
- * cause skips: between two reads we always pick up everything appended
- * since the last `nextOffset`.
+ * The polling cursor is a monotonic SQLite rowid so concurrent writers cannot
+ * cause skips: between two reads we always pick up everything inserted since
+ * the last `nextOffset`.
  */
 export async function tailEvents(options = {}, ctx) {
     const intervalMs = options.intervalMs ?? 75;
@@ -223,7 +176,7 @@ export async function tailEvents(options = {}, ctx) {
                 cursor = result.nextOffset;
                 for (const event of result.events) {
                     // Apply --since filter inside the polling loop too — the cursor is
-                    // byte-offset so it can hand us events the user filtered out.
+                    // rowid-based so it can hand us events the user filtered out.
                     if (options.since && event.ts && event.ts < options.since)
                         continue;
                     collected.push(event);

package/dist/core/file-lock.js

@@ -0,0 +1,104 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+import fs from "node:fs";
+import { isProcessAlive } from "./common";
+/**
+ * Atomically create a sentinel at `lockPath` with `payload` as the body.
+ * Returns true if we now own the lock, false if a sentinel already
+ * exists (EEXIST). Throws any other error (permissions, missing parent
+ * dir, etc.) — callers must ensure the parent directory exists.
+ *
+ * `payload` is typically `String(process.pid)` for the simple cases or
+ * a small JSON envelope for callers that want richer metadata
+ * (improve.ts records pid + startedAt so audit can correlate runs).
+ */
+export function tryAcquireLockSync(lockPath, payload) {
+    try {
+        fs.writeFileSync(lockPath, payload, { flag: "wx" });
+        return true;
+    }
+    catch (err) {
+        if (err.code === "EEXIST")
+            return false;
+        throw err;
+    }
+}
+/**
+ * Inspect an existing sentinel at `lockPath` without modifying it.
+ * Returns:
+ *   - `absent` if the file does not exist.
+ *   - `stale` if the file is present but should be reclaimed (the holding
+ *     PID is dead, the content is unparseable, or the lock has exceeded
+ *     `staleAfterMs`). Includes the failure reason so callers can log it.
+ *   - `held` if the lock has a live holder and is not yet age-expired.
+ *
+ * Does NOT remove the file. Callers decide recovery policy.
+ */
+export function probeLock(lockPath, opts) {
+    let rawContent;
+    let ageMs;
+    try {
+        rawContent = fs.readFileSync(lockPath, "utf8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return { state: "absent" };
+        return { state: "stale", reason: "unreadable" };
+    }
+    try {
+        const stat = fs.statSync(lockPath);
+        ageMs = Date.now() - stat.mtimeMs;
+    }
+    catch {
+        // Stat failed even though read succeeded — race-y removal in flight.
+        return { state: "stale", reason: "unreadable", rawContent };
+    }
+    const holderPid = extractHolderPid(rawContent);
+    if (holderPid === undefined) {
+        return { state: "stale", reason: "invalid_pid", ageMs, rawContent };
+    }
+    if (!isProcessAlive(holderPid)) {
+        return { state: "stale", reason: "pid_dead", holderPid, ageMs, rawContent };
+    }
+    if (opts?.staleAfterMs !== undefined && ageMs > opts.staleAfterMs) {
+        return { state: "stale", reason: "age_exceeded", holderPid, ageMs, rawContent };
+    }
+    return { state: "held", holderPid, ageMs, rawContent };
+}
+/**
+ * Remove a lock file. Idempotent — silently ignores ENOENT. Used both to
+ * reclaim stale locks (after probeLock returns `state: "stale"`) and to
+ * release locks we own (after a successful tryAcquireLockSync).
+ */
+export function releaseLock(lockPath) {
+    try {
+        fs.unlinkSync(lockPath);
+    }
+    catch {
+        // Sentinel already gone — fine.
+    }
+}
+/**
+ * Extract a PID from a sentinel body. Accepts the two shapes used across
+ * the codebase: a bare numeric string (config-io, vault, lockfile) and
+ * a JSON object with a `pid` field (improve). Returns undefined when the
+ * body is unparseable or yields a non-positive integer.
+ */
+function extractHolderPid(content) {
+    const trimmed = content.trim();
+    if (!trimmed)
+        return undefined;
+    if (trimmed.startsWith("{")) {
+        try {
+            const parsed = JSON.parse(trimmed);
+            const pid = typeof parsed.pid === "number" ? parsed.pid : Number.NaN;
+            return Number.isInteger(pid) && pid > 0 ? pid : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    const pid = Number.parseInt(trimmed, 10);
+    return Number.isInteger(pid) && pid > 0 ? pid : undefined;
+}

package/dist/core/frontmatter.js

@@ -1,3 +1,6 @@
+// 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/.
 /**
  * Shared frontmatter parsing utilities.
  *
@@ -150,9 +153,3 @@ export function parseYamlScalar(value) {
     }
     return value;
 }
-/**
- * Coerce an unknown value to a trimmed string, or return undefined if empty/non-string.
- */
-export function toStringOrUndefined(value) {
-    return typeof value === "string" && value.trim() ? value : undefined;
-}

package/dist/core/lesson-lint.js

@@ -1,3 +1,6 @@
+// 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/.
 /**
  * Deterministic frontmatter lint for `lesson` assets (v1 spec §13).
  *

package/dist/core/markdown.js

@@ -1,3 +1,6 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import { parseFrontmatter } from "./frontmatter";
 // ── Parsing ─────────────────────────────────────────────────────────────────
 export function parseMarkdownToc(content) {
@@ -75,3 +78,20 @@ export function formatToc(toc) {
     parts.push(`\n${toc.totalLines} lines total`);
     return parts.join("\n");
 }
+// ── Fence stripping ──────────────────────────────────────────────────────────
+/**
+ * Best-effort fence stripping. Strips `<think>` reasoning blocks emitted by
+ * local LLMs (e.g. Qwen3) before the content, which otherwise breaks YAML
+ * frontmatter detection. Only strips outer triple-fence pairs — leaves inner
+ * code blocks intact.
+ */
+export function stripMarkdownFences(raw) {
+    const stripped = raw
+        .trim()
+        .replace(/<think>[\s\S]*?<\/think>/gi, "")
+        .trim();
+    const fence = stripped.match(/^```(?:markdown|md)?\s*\n([\s\S]*?)\n```\s*$/i);
+    if (fence)
+        return fence[1].trim();
+    return stripped;
+}

package/dist/core/memory-belief.js

@@ -0,0 +1,62 @@
+// 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/.
+/**
+ * Shared memory belief-state machinery (C-3 / #382).
+ *
+ * Extracted from `memory-improve.ts` so both `akmConsolidate` and
+ * `analyzeMemoryCleanup` can emit `MemoryBeliefTransitionLogRecord` entries
+ * through a unified state-transition model.
+ *
+ * # Design
+ *
+ * The 4-state belief lifecycle (active → superseded | contradicted → archived)
+ * was previously encoded only in `memory-improve.ts`. `akmConsolidate` used a
+ * flat merge/delete/promote model with no belief states, causing the two engines
+ * to diverge. This module:
+ *
+ *   1. Re-exports the belief-state types from `memory-improve.ts` so callers
+ *      can import from one canonical location.
+ *   2. Provides `writeContradictEdge` — a shared primitive that both engines
+ *      use when an LLM (or heuristic) identifies a contradiction between two
+ *      memories. This is the bridge between `akmConsolidate`'s LLM-detected
+ *      contradictions and `resolveFamilyContradictions`' SCC resolver.
+ *
+ * # References
+ *
+ * - Zep / Graphiti (arXiv:2501.13956 §3) — unified belief-revision pipeline
+ * - MemOS (arXiv:2507.03724) — formal archive/merge/transition with shared state model
+ */
+import fs from "node:fs";
+import { assembleAsset } from "./asset-serialize";
+import { parseFrontmatter } from "./frontmatter";
+// ── Contradiction edge writer ─────────────────────────────────────────────────
+/**
+ * Write `contradictedBy` and `beliefState: contradicted` edges to a memory
+ * file's frontmatter (C-3 / #382).
+ *
+ * This is the shared primitive used by:
+ *   - `akmConsolidate` when its LLM plan includes a `contradict` op
+ *   - `memory-contradiction-detect.ts` for the M-1 automated contradiction pass
+ *   - `resolveFamilyContradictions` in `memory-improve.ts` for SCC resolution
+ *
+ * Idempotent: if the `contradictedByRef` is already in `contradictedBy`,
+ * the file is not rewritten.
+ *
+ * @param filePath          - Absolute path to the memory markdown file.
+ * @param contradictedByRef - The ref that contradicts this memory.
+ */
+export function writeContradictEdge(filePath, contradictedByRef) {
+    const raw = fs.readFileSync(filePath, "utf8");
+    const parsed = parseFrontmatter(raw);
+    const existing = Array.isArray(parsed.data.contradictedBy) ? parsed.data.contradictedBy : [];
+    if (existing.includes(contradictedByRef))
+        return; // Already written — idempotent.
+    const nextContradictedBy = [...new Set([...existing, contradictedByRef])].sort();
+    const nextFrontmatter = {
+        ...parsed.data,
+        contradictedBy: nextContradictedBy,
+        beliefState: "contradicted",
+    };
+    fs.writeFileSync(filePath, assembleAsset(nextFrontmatter, parsed.content), "utf8");
+}