akm-cli 0.9.0-rc.4 → 0.9.0-rc.6

package/dist/core/fs-txn.js

@@ -0,0 +1,316 @@
+// 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/.
+/**
+ * The ONE durable filesystem-transaction engine (plan §2.2 / §4.5, Chunk 6
+ * WI-6.3). Replaces the three (+1) per-domain journal engines — proposal
+ * accept/revert, proposal reject, mv, consolidate — with a single journal
+ * home, journal format, fsync discipline, phase runner, and recovery scanner.
+ *
+ * ## Journal home
+ *
+ * `getDataDir()/txn/<rootNs24>/<transactionId>/journal.json`, namespaced by
+ * the sha256 of the resolved root the transaction mutates. Every legacy home
+ * (`proposal-transactions/`, `proposal-rejections/`, in-stash
+ * `.akm/mv-transactions/`, in-stash `consolidate-journal.json`) collapses
+ * onto this one.
+ *
+ * ## Phase model
+ *
+ * Each transaction KIND declares its ordered phase vocabulary and a commit
+ * point. A journal found at a phase strictly BEFORE the commit point rolls
+ * BACK (the batch never happened); at or after it rolls FORWARD (the kind's
+ * `finalize` resumes idempotently from the recorded phase). Phase writes are
+ * durable: tmp + fsync + rename + parent-dir fsync — the exact discipline
+ * every legacy engine used, now in one place.
+ *
+ * ## Kind handlers
+ *
+ * Domain logic (what the files are, how to roll back, which DB/index/event
+ * steps finalize) stays with the domain: each kind registers a
+ * {@link TxnKindHandler}. The engine owns discovery, safety fencing, journal
+ * I/O, ordering, and cleanup. Recovery entry points call
+ * {@link recoverTxnsForRoot} (after importing the domain registrar so the
+ * kinds are registered).
+ *
+ * ## Crash-window test seam
+ *
+ * `_setTxnMutationHookForTests` replaces the per-engine hooks; domain code
+ * fires named points through {@link txnMutationHook} exactly where the legacy
+ * engines fired theirs, so the subprocess crash runners re-key mechanically.
+ */
+import { createHash, randomUUID } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { getDataDir } from "./paths.js";
+import { warn } from "./warn.js";
+// ── Registry ─────────────────────────────────────────────────────────────────
+const kinds = new Map();
+/**
+ * Register (or replace) the handler for a transaction kind. Handlers are
+ * stored payload-erased; beginTxn/recovery re-associate `P` via the kind tag.
+ */
+export function registerTxnKind(kind, handler) {
+    kinds.set(kind, handler);
+}
+function requireKind(kind) {
+    const handler = kinds.get(kind);
+    if (!handler)
+        throw new Error(`No transaction handler registered for kind "${kind}".`);
+    return handler;
+}
+// ── Test seam ────────────────────────────────────────────────────────────────
+let mutationHookForTests;
+/** TEST-ONLY crash-window hook used by subprocess recovery tests. */
+export function _setTxnMutationHookForTests(hook) {
+    mutationHookForTests = hook;
+}
+/** Fire a named crash-window point (no-op outside tests). */
+export function txnMutationHook(point) {
+    mutationHookForTests?.(point);
+}
+// ── Durable file I/O primitives (shared fsync discipline) ────────────────────
+export function txnHash(content) {
+    return createHash("sha256").update(content).digest("hex");
+}
+export function txnFileHash(filePath) {
+    return txnHash(fs.readFileSync(filePath));
+}
+export function fsyncTxnFile(filePath) {
+    const fd = fs.openSync(filePath, "r");
+    try {
+        fs.fsyncSync(fd);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+export function fsyncTxnDir(dirPath) {
+    try {
+        fsyncTxnFile(dirPath);
+    }
+    catch {
+        // Directory fsync is unavailable on some platforms.
+    }
+}
+/** Durably write `content` to `filePath` (tmp + fsync + rename + dir fsync). */
+export function writeTxnFileDurably(filePath, content, mode = 0o600) {
+    const tempPath = `${filePath}.tmp`;
+    fs.writeFileSync(tempPath, content, { mode });
+    fsyncTxnFile(tempPath);
+    fs.renameSync(tempPath, filePath);
+    fsyncTxnDir(path.dirname(filePath));
+}
+// ── Journal home / discovery ─────────────────────────────────────────────────
+/**
+ * Canonical spelling of a transaction root: realpath when the root exists
+ * (so symlinked spellings — e.g. a stash reached through macOS /tmp — hash
+ * to the SAME namespace and bind-compare equal), resolved otherwise.
+ */
+export function canonicalTxnRoot(root) {
+    try {
+        return fs.realpathSync(path.resolve(root));
+    }
+    catch {
+        return path.resolve(root);
+    }
+}
+/** Namespace directory for all transactions mutating `root`. */
+export function txnNamespaceDir(root) {
+    const ns = txnHash(canonicalTxnRoot(root)).slice(0, 24);
+    return path.join(getDataDir(), "txn", ns);
+}
+/** Mint a transaction id ahead of {@link beginTxn} (see its `transactionId`). */
+export function mintTxnId() {
+    return randomUUID();
+}
+/** The directory a transaction with `transactionId` on `root` will own. */
+export function txnDirFor(root, transactionId) {
+    return path.join(txnNamespaceDir(root), transactionId);
+}
+function writeJournal(txn) {
+    writeTxnFileDurably(txn.journalPath, `${JSON.stringify(txn.journal, null, 2)}\n`);
+}
+/** Durably record `phase` on the journal, then mirror it in memory. */
+export function advanceTxn(txn, phase) {
+    const handler = requireKind(txn.journal.kind);
+    if (!handler.phases.includes(phase)) {
+        throw new Error(`Unknown phase "${phase}" for transaction kind "${txn.journal.kind}".`);
+    }
+    const next = { ...txn.journal, phase };
+    writeTxnFileDurably(txn.journalPath, `${JSON.stringify(next, null, 2)}\n`);
+    txn.journal.phase = phase;
+}
+/**
+ * Open a new transaction: mint the id, create its directory, and durably
+ * write the journal at the kind's initial phase. The caller stages sidecar
+ * files under `txn.dir` and then applies/finalizes through the kind handler.
+ */
+export function beginTxn(args) {
+    const handler = requireKind(args.kind);
+    const transactionId = args.transactionId ?? randomUUID();
+    if (!/^[A-Za-z0-9._-]+$/.test(transactionId) || transactionId === "." || transactionId === "..") {
+        throw new Error(`Invalid transaction id "${transactionId}" — must be a plain path segment.`);
+    }
+    const dir = path.join(txnNamespaceDir(args.root), transactionId);
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const journal = {
+        version: 1,
+        kind: args.kind,
+        phase: handler.phases[0],
+        transactionId,
+        root: canonicalTxnRoot(args.root),
+        changes: args.changes,
+        decidedAt: args.decidedAt ?? new Date().toISOString(),
+        payload: args.payload,
+    };
+    const txn = { journal, journalPath: path.join(dir, "journal.json"), dir };
+    writeJournal(txn);
+    return txn;
+}
+/** Remove a transaction directory (and its namespace dir when empty). */
+export function cleanupTxn(dir) {
+    try {
+        fs.rmSync(dir, { recursive: true, force: true });
+        try {
+            fs.rmdirSync(path.dirname(dir));
+        }
+        catch {
+            // Other transactions may still exist in the namespace.
+        }
+        return null;
+    }
+    catch (error) {
+        const message = `transaction committed but cleanup failed at ${dir}: ${error instanceof Error ? error.message : String(error)}`;
+        warn(`[txn] ${message}`);
+        return message;
+    }
+}
+/**
+ * Sweep a transaction directory that has NO journal — but only when it is
+ * demonstrably stale. All kinds share one namespace per root, so a scanner
+ * may encounter a SIBLING transaction inside `beginTxn`'s mkdir→journal
+ * window; a grace period keeps the sweep from racing it. Returns true when
+ * the directory was removed.
+ */
+export function sweepJournallessTxnDir(dir, graceMs = 300_000) {
+    try {
+        const age = Date.now() - fs.statSync(dir).mtimeMs;
+        if (age < graceMs)
+            return false;
+        fs.rmSync(dir, { recursive: true, force: true });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** True when `candidate` is inside `root` (both resolved). */
+export function isWithinTxnRoot(candidate, root) {
+    const rel = path.relative(path.resolve(root), path.resolve(candidate));
+    return rel !== "" && !rel.startsWith("..") && !path.isAbsolute(rel);
+}
+function readJournal(journalPath) {
+    let journal;
+    try {
+        journal = JSON.parse(fs.readFileSync(journalPath, "utf8"));
+    }
+    catch (error) {
+        throw new Error(`Cannot read transaction journal at ${journalPath}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (journal.version !== 1 || typeof journal.kind !== "string" || typeof journal.phase !== "string") {
+        throw new Error(`Refusing unsafe transaction journal at ${journalPath}.`);
+    }
+    return journal;
+}
+/** Engine-level safety fences shared by every kind. */
+function fenceJournal(journal, txnDir, root, journalPath) {
+    if (canonicalTxnRoot(journal.root) !== canonicalTxnRoot(root)) {
+        throw new Error(`Refusing transaction journal bound to a different root at ${journalPath}.`);
+    }
+    const handler = requireKind(journal.kind);
+    if (!handler.phases.includes(journal.phase)) {
+        throw new Error(`Refusing transaction journal with unknown phase "${journal.phase}" at ${journalPath}.`);
+    }
+    for (const change of journal.changes) {
+        if (typeof change.path !== "string" || !isWithinTxnRoot(change.path, root)) {
+            throw new Error(`Refusing transaction journal touching paths outside its root at ${journalPath}.`);
+        }
+    }
+    handler.validate?.(journal, txnDir, root);
+}
+/** True when `journal.phase` is at or after the kind's commit point. */
+export function isCommittedPhase(journal) {
+    const handler = requireKind(journal.kind);
+    return handler.phases.indexOf(journal.phase) >= handler.phases.indexOf(handler.commitPhase);
+}
+/**
+ * Recover every interrupted transaction under `root`'s namespace: journals
+ * before their kind's commit point roll BACK; the rest roll FORWARD through
+ * the kind's `finalize`. Fully-finalized directories are swept. The domain
+ * registrar (which registers the kinds) must be imported by the caller.
+ *
+ * `filter` optionally narrows recovery (e.g. one kind, one proposal id).
+ */
+export async function recoverTxnsForRoot(root, filter) {
+    const nsDir = txnNamespaceDir(root);
+    const recovered = [];
+    if (!fs.existsSync(nsDir))
+        return recovered;
+    for (const entry of fs.readdirSync(nsDir, { withFileTypes: true })) {
+        if (!entry.isDirectory())
+            continue;
+        const dir = path.join(nsDir, entry.name);
+        const journalPath = path.join(dir, "journal.json");
+        if (!fs.existsSync(journalPath)) {
+            sweepJournallessTxnDir(dir);
+            continue;
+        }
+        const journal = readJournal(journalPath);
+        if (filter && !filter(journal))
+            continue;
+        fenceJournal(journal, dir, root, journalPath);
+        const handler = requireKind(journal.kind);
+        const txn = { journal, journalPath, dir };
+        const terminal = handler.phases[handler.phases.length - 1];
+        if (!isCommittedPhase(journal)) {
+            await handler.rollback(txn);
+        }
+        else if (journal.phase !== terminal) {
+            await handler.finalize(txn);
+        }
+        recovered.push(journal);
+        cleanupTxn(dir);
+    }
+    return recovered;
+}
+/**
+ * Enumerate (without recovering) every journal across ALL namespaces that
+ * matches `predicate`. Used by stash-scoped recovery entry points that don't
+ * know which roots their interrupted transactions were bound to.
+ */
+export function listTxnJournals(predicate) {
+    const home = path.join(getDataDir(), "txn");
+    const matches = [];
+    if (!fs.existsSync(home))
+        return matches;
+    for (const ns of fs.readdirSync(home, { withFileTypes: true })) {
+        if (!ns.isDirectory())
+            continue;
+        const nsDir = path.join(home, ns.name);
+        for (const entry of fs.readdirSync(nsDir, { withFileTypes: true })) {
+            if (!entry.isDirectory())
+                continue;
+            const journalPath = path.join(nsDir, entry.name, "journal.json");
+            if (!fs.existsSync(journalPath))
+                continue;
+            // Unreadable/invalid journals fail LOUDLY: a caller deciding what to
+            // recover must never silently overlook a damaged journal (it may fence
+            // an interrupted, irreversible mutation).
+            const journal = readJournal(journalPath);
+            if (predicate(journal))
+                matches.push(journal);
+        }
+    }
+    return matches;
+}

package/dist/core/git-message.js

@@ -0,0 +1,59 @@
+// 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/.
+/**
+ * Leaf util for sanitizing git commit messages.
+ *
+ * Split out of `core/write-source.ts` so that `sources/providers/git-stash.ts`
+ * (which `core/write-source.ts` imports `getCachePaths`/`listGitChangedPaths`/
+ * `parseGitRepoUrl`/`saveGitStash` from, via the `sources/providers/git`
+ * barrel, by value) does not need to import back into `write-source.ts` just
+ * for this helper — that back-edge was a 3-file static-graph cycle
+ * (write-source.ts → git.ts → git-stash.ts → write-source.ts; chunk 9 WI-9.8
+ * KILL 6 sever). `write-source.ts` re-exports `sanitizeCommitMessage` so
+ * existing import sites are unaffected.
+ */
+/**
+ * Maximum length of a sanitized git commit message. Git itself imposes no
+ * fixed limit, but message strings come from refs and `--message` flags that
+ * can be supplied by users or upstream config. A 4096-char clamp keeps audit
+ * trails readable and prevents pathological payloads from bloating the log
+ * stream a downstream consumer parses.
+ */
+const COMMIT_MESSAGE_MAX_LENGTH = 4096;
+/**
+ * Sanitize a string before passing it as `git commit -m <message>`.
+ *
+ * Defenses, in order:
+ *   1. Strip NUL bytes (`\0`) — git rejects them anyway, but we never want
+ *      them in argv.
+ *   2. Replace any CR/LF (`\r`, `\n`) and other ASCII control chars with a
+ *      single space. This collapses newline-injection attempts that would
+ *      otherwise turn a single-line commit subject into a forged trailer
+ *      block.
+ *   3. Collapse runs of whitespace into a single space and trim.
+ *   4. Clamp to {@link COMMIT_MESSAGE_MAX_LENGTH} characters.
+ *
+ * If the result is empty after sanitization the caller should substitute a
+ * default — this helper returns `""` rather than throwing because not every
+ * callsite has a sensible "invalid input" exit code, and "empty" is a
+ * recoverable signal.
+ */
+export function sanitizeCommitMessage(input) {
+    if (typeof input !== "string")
+        return "";
+    // 1. Strip NULs outright.
+    let out = input.replace(/\0/g, "");
+    // 2. Replace CR/LF + other C0 control characters (0x00-0x1F, 0x7F) with a
+    //    space. Tab (0x09) is included intentionally — commit subjects should
+    //    be a single visual line.
+    // biome-ignore lint/suspicious/noControlCharactersInRegex: intentional sanitization
+    out = out.replace(/[\x00-\x1F\x7F]/g, " ");
+    // 3. Collapse whitespace runs and trim.
+    out = out.replace(/\s+/g, " ").trim();
+    // 4. Clamp length.
+    if (out.length > COMMIT_MESSAGE_MAX_LENGTH) {
+        out = out.slice(0, COMMIT_MESSAGE_MAX_LENGTH).trimEnd();
+    }
+    return out;
+}

package/dist/core/improve-result.js

@@ -37,6 +37,7 @@ const COMMON_FIELDS = [
     "gateAutoAcceptFailedCount",
     "triage",
     "proactiveMaintenance",
+    // Retired producers still exist in the persisted 90-day improve-run ledger.
     "recombination",
     "proceduralCompilation",
     "cycleMetrics",
@@ -44,7 +45,13 @@ const COMMON_FIELDS = [
     "sync",
     "terminated",
 ];
-const V1_FIELDS = new Set([...COMMON_FIELDS, "profile", "profileFilteredRefs", "stalenessDetection"]);
+const V1_FIELDS = new Set([
+    ...COMMON_FIELDS,
+    "profile",
+    "profileFilteredRefs",
+    "stalenessDetection",
+    "executionLogCandidates",
+]);
 const V2_FIELDS = new Set([...COMMON_FIELDS, "strategy", "strategyFilteredRefs"]);
 const STALENESS_DETECTION_FIELDS = new Set([
     "considered",
@@ -131,6 +138,7 @@ function validateCommon(value) {
         "extract",
         "coverageGaps",
         "deadUrls",
+        "executionLogCandidates",
     ]) {
         if (value[field] !== undefined && !Array.isArray(value[field]))
             fail(`${field} must be an array`);

package/dist/core/logs-db.js

@@ -9,7 +9,7 @@
  * The strategic direction (stop scattering data across files/folders) means
  * every NEW log consumer queries this database; the per-run text file written
  * by the task runner is retained only as a transitional tail for humans —
- * see docs/technical/logs-audit.md for the full producer audit.
+ * per the #579 logs audit of every producer.
  *
  * ## Why a separate database from state.db
  *

package/dist/core/maintenance-barrier.js

@@ -47,6 +47,22 @@ export function withMaintenanceStartBarrier(run) {
         release();
     }
 }
+/** Run while holding the start barrier, or return undefined when it is busy. */
+export function tryWithMaintenanceStartBarrier(run) {
+    if (heldBarrierContext.getStore()?.active)
+        return run();
+    const release = tryAcquireMaintenanceBarrier();
+    if (!release)
+        return undefined;
+    const ownership = { active: true };
+    try {
+        return heldBarrierContext.run(ownership, run);
+    }
+    finally {
+        ownership.active = false;
+        release();
+    }
+}
 async function acquireMaintenanceBarrierAsync() {
     const deadline = Date.now() + 5_000;
     while (true) {