akm-cli 0.9.0-beta.9 → 0.9.0-rc.0

package/dist/storage/repositories/recombine-repository.js

@@ -0,0 +1,213 @@
+// 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/.
+/**
+ * Record an induction of a recombine hypothesis and return the new consecutive
+ * count. INSERT … ON CONFLICT increments the streak, but the `last_run` guard
+ * makes a repeated call within the SAME run idempotent (no double-increment if
+ * the same ref appears twice in one run). On insert the streak starts at 1.
+ */
+export function recordRecombineInduction(db, input) {
+    const row = db
+        .prepare(`
+      INSERT INTO recombine_hypotheses
+        (hypothesis_ref, signature, member_key, consecutive_count, first_seen_at, last_seen_at, last_run)
+      VALUES (?, ?, ?, 1, ?, ?, ?)
+      ON CONFLICT(hypothesis_ref) DO UPDATE SET
+        consecutive_count = consecutive_count + (CASE WHEN last_run IS excluded.last_run THEN 0 ELSE 1 END),
+        last_seen_at = excluded.last_seen_at,
+        last_run = excluded.last_run,
+        signature = excluded.signature,
+        member_key = excluded.member_key
+      RETURNING consecutive_count
+    `)
+        .get(input.hypothesisRef, input.signature, input.memberKey, input.seenAt, input.seenAt, input.run);
+    return row?.consecutive_count ?? 0;
+}
+/**
+ * #633 — find an existing pending (non-promoted) hypothesis row whose cluster
+ * is the SAME generalization as a newly-induced one, matched by SIGNATURE plus
+ * a Jaccard membership-overlap test, rather than an exact member-set hash.
+ *
+ * In a growing stash any added/removed memory changes the exact member set, so
+ * the ref hash (and member_key) shift every run → a fresh row at count=1 → the
+ * streak never reaches `confirmThreshold` and nothing ever promotes. Matching
+ * on overlap lets a drifting-but-stable cluster keep accumulating under one row.
+ *
+ * Returns the matched row with the HIGHEST overlap (ties broken by most-recent
+ * `last_seen_at`), or `undefined` when none clears `minOverlap`. Already-promoted
+ * rows are ignored so a confirmed lesson is not reopened by a later induction.
+ *
+ * @param memberKey  the candidate cluster's membership fingerprint
+ *                   (sorted member entryKeys joined by `|`).
+ * @param minOverlap Jaccard threshold in [0,1]; a candidate matches when
+ *                   |A∩B| / |A∪B| >= minOverlap.
+ */
+export function findMatchingRecombineHypothesis(db, input) {
+    const candidateMembers = new Set(input.memberKey.split("|").filter((m) => m.length > 0));
+    if (candidateMembers.size === 0)
+        return undefined;
+    const rows = db
+        .prepare("SELECT * FROM recombine_hypotheses WHERE signature = ? AND promoted_at IS NULL ORDER BY last_seen_at DESC")
+        .all(input.signature);
+    let best;
+    let bestOverlap = -1;
+    for (const row of rows) {
+        const rowMembers = row.member_key.split("|").filter((m) => m.length > 0);
+        if (rowMembers.length === 0)
+            continue;
+        let intersection = 0;
+        for (const m of rowMembers) {
+            if (candidateMembers.has(m))
+                intersection += 1;
+        }
+        const union = candidateMembers.size + rowMembers.length - intersection;
+        const overlap = union === 0 ? 0 : intersection / union;
+        // rows are ordered last_seen_at DESC, so a strict `>` keeps the most-recent
+        // row on ties.
+        if (overlap >= input.minOverlap && overlap > bestOverlap) {
+            best = row;
+            bestOverlap = overlap;
+        }
+    }
+    return best;
+}
+/**
+ * Fetch a single recombine hypothesis row, or `undefined` when the ref has
+ * never been induced. Normalizes bun:sqlite null → undefined like
+ * {@link getExtractedSession}.
+ */
+export function getRecombineHypothesis(db, hypothesisRef) {
+    const row = db
+        .prepare("SELECT * FROM recombine_hypotheses WHERE hypothesis_ref = ?")
+        .get(hypothesisRef);
+    return row ?? undefined;
+}
+/**
+ * Mark a hypothesis promoted: stamp `promoted_at` and reset the consecutive
+ * count to 0, so it must re-accumulate a full confirmation streak before it can
+ * promote again. The `promoted_at` non-null state is the double-promotion guard.
+ */
+export function markRecombineHypothesisPromoted(db, hypothesisRef, promotedAt) {
+    db.prepare("UPDATE recombine_hypotheses SET promoted_at = ?, consecutive_count = 0 WHERE hypothesis_ref = ?").run(promotedAt, hypothesisRef);
+}
+/**
+ * #658 — does any current-run cluster match this hypothesis row under the SAME
+ * signature + Jaccard-overlap rule used for re-induction? A match means the
+ * cluster genuinely re-formed this run (it was merely cap-displaced out of the
+ * processed top-`maxClustersPerRun` slice), so its streak must NOT be reset.
+ */
+function hypothesisMatchesAnyPresentCluster(row, presentClusters, minOverlap) {
+    const rowMembers = row.member_key.split("|").filter((m) => m.length > 0);
+    if (rowMembers.length === 0)
+        return false;
+    const rowSet = new Set(rowMembers);
+    for (const cluster of presentClusters) {
+        if (cluster.signature !== row.signature)
+            continue;
+        const clusterMembers = cluster.memberKey.split("|").filter((m) => m.length > 0);
+        if (clusterMembers.length === 0)
+            continue;
+        let intersection = 0;
+        for (const m of clusterMembers) {
+            if (rowSet.has(m))
+                intersection += 1;
+        }
+        const union = rowSet.size + clusterMembers.length - intersection;
+        const overlap = union === 0 ? 0 : intersection / union;
+        if (overlap >= minOverlap)
+            return true;
+    }
+    return false;
+}
+/**
+ * Decay-to-zero every NON-promoted hypothesis NOT re-induced in the current run.
+ *
+ * A generalization that stops being supported by the corpus has lost its
+ * confirmation streak, so we hard-reset `consecutive_count` to 0 (the
+ * alternative — `count - 1` floored at 0 — tolerates a single noisy run but
+ * blurs the "consecutive" semantics; hard-reset is the conservative choice).
+ *
+ * Only rows whose `hypothesis_ref` is NOT in `seenRefs` AND whose `last_run` is
+ * NOT the current run are decayed. Already-promoted rows are left alone.
+ *
+ * #658 — CAP-AWARE decay. The recombine pass only re-inducts (and thus marks
+ * `seen`) the top-`maxClustersPerRun` clusters, but a cluster genuinely
+ * re-forms every run even when it is displaced below that cap. Resetting such a
+ * row treats a SCHEDULING miss as a SUBSTANCE miss and traps the hypothesis
+ * below `confirmThreshold` forever. When `opts.presentClusters` is supplied, a
+ * row is SPARED from decay if it Jaccard-matches any present cluster (same
+ * signature, overlap >= `opts.minOverlap`) — i.e. its cluster re-formed this run
+ * but was cap-displaced. This does NOT advance the streak (only re-induction in
+ * the processed slice does that, via {@link recordRecombineInduction}), so the
+ * recurrence bar for promotion is unchanged; it only stops the cap from
+ * manufacturing artificial misses. Omitting `presentClusters` preserves the
+ * pre-#658 hard-reset-after-one-miss behaviour exactly.
+ *
+ * Returns the number of rows reset.
+ */
+export function decayUnseenRecombineHypotheses(db, currentRun, seenRefs, opts) {
+    // #658 — when cap-aware sparing is requested, fold the cap-displaced rows into
+    // the "seen" exclusion set: the underlying reset SQL already protects every
+    // ref it is given, so sparing == treating a spared row exactly like a seen
+    // row for this sweep (its count is left untouched, never advanced).
+    let effectiveSeen = seenRefs;
+    if (opts && opts.presentClusters.length > 0) {
+        const candidates = db
+            .prepare("SELECT hypothesis_ref, signature, member_key FROM recombine_hypotheses WHERE promoted_at IS NULL AND (last_run IS NULL OR last_run != ?) AND consecutive_count != 0")
+            .all(currentRun);
+        const seenSet = new Set(seenRefs);
+        for (const row of candidates) {
+            if (seenSet.has(row.hypothesis_ref))
+                continue;
+            if (hypothesisMatchesAnyPresentCluster(row, opts.presentClusters, opts.minOverlap)) {
+                seenSet.add(row.hypothesis_ref);
+            }
+        }
+        effectiveSeen = [...seenSet];
+    }
+    return decayUnseenRecombineHypothesesInner(db, currentRun, effectiveSeen);
+}
+/**
+ * The raw reset sweep shared by the cap-aware wrapper above. Resets every
+ * non-promoted row from a prior run whose ref is NOT in `seenRefs`. Kept private
+ * so the param-ceiling chunking logic lives in one place.
+ */
+function decayUnseenRecombineHypothesesInner(db, currentRun, seenRefs) {
+    // Reset every eligible row, then exclude the seen refs in chunks to respect
+    // the ~999 SQLite param ceiling. With no seen refs we reset all non-promoted
+    // rows from prior runs in a single statement.
+    if (seenRefs.length === 0) {
+        const res = db
+            .prepare("UPDATE recombine_hypotheses SET consecutive_count = 0 WHERE promoted_at IS NULL AND (last_run IS NULL OR last_run != ?) AND consecutive_count != 0")
+            .run(currentRun);
+        return Number(res.changes);
+    }
+    // A single NOT IN keeps the exclusion atomic (a chunked NOT IN would let a ref
+    // excluded by one chunk still be reset by another chunk's statement). The
+    // recombine pass caps RE-INDUCED clusters at `maxClustersPerRun` (a handful) —
+    // but with #658 cap-aware sparing the caller folds every cap-displaced
+    // (present-but-unprocessed) hypothesis into `effectiveSeen` too, so on a large
+    // stash `seenRefs` here can carry MANY spared refs, not just the handful that
+    // were processed. We cap defensively at ~900 (under SQLite's ~999 param
+    // ceiling): if `effectiveSeen` somehow exceeds it we fall back to resetting all
+    // eligible rows — which re-introduces the cap-displacement trap for THAT run
+    // (spared rows get decayed because the NOT IN protection is dropped). That is a
+    // rare, bounded degradation; a stash with >900 simultaneously-spared
+    // hypotheses is far beyond current scale.
+    if (seenRefs.length > 900) {
+        const res = db
+            .prepare("UPDATE recombine_hypotheses SET consecutive_count = 0 WHERE promoted_at IS NULL AND (last_run IS NULL OR last_run != ?) AND consecutive_count != 0")
+            .run(currentRun);
+        return Number(res.changes);
+    }
+    const placeholders = seenRefs.map(() => "?").join(",");
+    const res = db
+        .prepare(`UPDATE recombine_hypotheses SET consecutive_count = 0
+       WHERE promoted_at IS NULL
+         AND (last_run IS NULL OR last_run != ?)
+         AND consecutive_count != 0
+         AND hypothesis_ref NOT IN (${placeholders})`)
+        .run(currentRun, ...seenRefs);
+    return Number(res.changes);
+}

package/dist/storage/repositories/registry-cache.js

@@ -0,0 +1,93 @@
+// 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 { rethrowIfTestIsolationError } from "../../core/errors.js";
+import { closeDatabase, openIndexDatabase } from "../../indexer/db/db.js";
+import { getRegistryIndexCache, upsertRegistryIndexCache } from "./registry-index-cache-repository.js";
+/**
+ * RAII-style lifecycle helper for the registry cache DB. Opens the DB (treating
+ * a failed open exactly like the legacy fall-through: the bun-test isolation
+ * guard is re-thrown, any other failure yields `db = undefined`), runs `fn`,
+ * and guarantees the DB is closed in a `finally` after `fn` has fully settled
+ * (the await is required: the callbacks are async, and closing before they
+ * settle would tear the DB down mid-write).
+ */
+export async function withRegistryCacheDb(fn) {
+    let db;
+    try {
+        db = openIndexDatabase();
+    }
+    catch (err) {
+        // Never mask the bun-test isolation guard as "DB unavailable".
+        rethrowIfTestIsolationError(err);
+        db = undefined;
+    }
+    try {
+        return await fn(db);
+    }
+    finally {
+        if (db) {
+            try {
+                closeDatabase(db);
+            }
+            catch {
+                /* ignore */
+            }
+        }
+    }
+}
+/**
+ * Shared registry index-cache fetch template. Opens the cache DB, returns a
+ * fresh cache hit when present, otherwise fetches live (writing the result back
+ * to the cache best-effort), and falls back to a stale cache row when the fetch
+ * fails. Behaviour-preserving extraction of the logic previously duplicated in
+ * `skills-sh.ts` (`fetchSkills`) and `static-index.ts` (`loadIndex`).
+ */
+export async function fetchCachedJson(opts) {
+    const { cacheKey, ttlMs, parseCache, fetchFresh } = opts;
+    return withRegistryCacheDb(async (db) => {
+        // ── Step 1: Try DB cache (index.db) ─────────────────────────────────────
+        let dbCacheResult;
+        try {
+            if (db) {
+                dbCacheResult = getRegistryIndexCache(db, cacheKey, ttlMs);
+            }
+        }
+        catch (err) {
+            // Never mask the bun-test isolation guard as "DB unavailable" — see
+            // rethrowIfTestIsolationError in src/core/errors.ts. Without this, a
+            // leaky test silently gets a cold cache instead of the loud
+            // TEST_ISOLATION_MISSING failure the guard intends.
+            rethrowIfTestIsolationError(err);
+            // index.db read failed (pre-migration install or test env) — fall through
+        }
+        if (dbCacheResult) {
+            const cached = parseCache(dbCacheResult.indexJson, { stale: false });
+            if (cached !== undefined) {
+                return cached;
+            }
+        }
+        // ── Step 2: Fetch fresh ──────────────────────────────────────────────────
+        try {
+            const { value, cacheJson, cacheOpts } = await fetchFresh(db);
+            if (db) {
+                try {
+                    upsertRegistryIndexCache(db, cacheKey, cacheJson, cacheOpts);
+                }
+                catch {
+                    /* best-effort */
+                }
+            }
+            return value;
+        }
+        catch (err) {
+            // Fetch failed — use stale DB cache if available.
+            if (dbCacheResult) {
+                const stale = parseCache(dbCacheResult.indexJson, { stale: true });
+                if (stale !== undefined)
+                    return stale;
+            }
+            throw err;
+        }
+    });
+}

package/dist/storage/repositories/registry-index-cache-repository.js

@@ -0,0 +1,46 @@
+// 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/.
+/**
+ * Upsert a registry index cache entry in index.db.
+ *
+ * @param db          - Open index.db connection (from openDatabase / openExistingDatabase).
+ * @param registryUrl - Canonical URL of the registry (used as primary key).
+ * @param indexJson   - Serialised registry index document (JSON string).
+ * @param opts.etag        - HTTP ETag from the response (optional).
+ * @param opts.lastModified - HTTP Last-Modified from the response (optional).
+ */
+export function upsertRegistryIndexCache(db, registryUrl, indexJson, opts) {
+    db.prepare(`
+    INSERT INTO registry_index_cache (registry_url, fetched_at, etag, last_modified, index_json)
+    VALUES (?, ?, ?, ?, ?)
+    ON CONFLICT(registry_url) DO UPDATE SET
+      fetched_at    = excluded.fetched_at,
+      etag          = excluded.etag,
+      last_modified = excluded.last_modified,
+      index_json    = excluded.index_json
+  `).run(registryUrl, new Date().toISOString(), opts?.etag ?? null, opts?.lastModified ?? null, indexJson);
+}
+/**
+ * Look up a cached registry index entry from index.db.
+ * Returns undefined when not found or when the entry is older than `maxAgeMs`.
+ *
+ * TTL check: if `Date.now() - new Date(fetched_at).getTime() > maxAgeMs` the
+ * entry is considered a cache miss and undefined is returned.
+ *
+ * @param db          - Open index.db connection.
+ * @param registryUrl - Canonical URL of the registry (primary key).
+ * @param maxAgeMs    - Maximum age in milliseconds before the entry is stale (default: 1 hour).
+ */
+export function getRegistryIndexCache(db, registryUrl, maxAgeMs = 3_600_000 /* 1 hour */) {
+    const row = db
+        .prepare(`SELECT fetched_at, etag, last_modified, index_json
+       FROM registry_index_cache WHERE registry_url = ?`)
+        .get(registryUrl);
+    if (!row)
+        return undefined;
+    const fetchedAt = Date.parse(row.fetched_at);
+    if (Number.isNaN(fetchedAt) || Date.now() - fetchedAt > maxAgeMs)
+        return undefined;
+    return { indexJson: row.index_json, etag: row.etag, lastModified: row.last_modified };
+}

package/dist/storage/repositories/task-history-repository.js

@@ -0,0 +1,93 @@
+// 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/.
+/**
+ * Upsert a task history row.
+ */
+export function upsertTaskHistory(db, row) {
+    // INSERT OR IGNORE: if a run with the same (task_id, started_at) was already
+    // imported (e.g. by the migration script), skip it silently.
+    db.prepare(`
+    INSERT OR IGNORE INTO task_history
+      (task_id, status, started_at, completed_at, failed_at, log_path,
+       target_kind, target_ref, metadata_json)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `).run(row.task_id, row.status, row.started_at, row.completed_at ?? null, row.failed_at ?? null, row.log_path ?? null, row.target_kind ?? null, row.target_ref ?? null, row.metadata_json);
+}
+/**
+ * Look up a task history row by task_id. Returns undefined when not found.
+ */
+/**
+ * Return the most recent run for a given task_id, or undefined if no runs exist.
+ */
+export function getTaskHistory(db, taskId) {
+    return db
+        .prepare(`SELECT id, task_id, status, started_at, completed_at, failed_at, log_path,
+              target_kind, target_ref, metadata_json
+       FROM task_history WHERE task_id = ? ORDER BY started_at DESC LIMIT 1`)
+        .get(taskId);
+}
+/**
+ * Return all runs for a given task_id, newest first.
+ */
+export function getTaskHistoryRuns(db, taskId, limit = 50) {
+    return db
+        .prepare(`SELECT id, task_id, status, started_at, completed_at, failed_at, log_path,
+              target_kind, target_ref, metadata_json
+       FROM task_history WHERE task_id = ? ORDER BY started_at DESC LIMIT ?`)
+        .all(taskId, limit);
+}
+/**
+ * Query task history rows by started_at range and/or status.
+ */
+export function queryTaskHistory(db, options = {}) {
+    const conditions = [];
+    const params = [];
+    if (options.since) {
+        conditions.push("started_at >= ?");
+        params.push(options.since);
+    }
+    if (options.until) {
+        conditions.push("started_at <= ?");
+        params.push(options.until);
+    }
+    if (options.status) {
+        conditions.push("status = ?");
+        params.push(options.status);
+    }
+    if (options.targetKind) {
+        conditions.push("target_kind = ?");
+        params.push(options.targetKind);
+    }
+    if (options.targetRef) {
+        conditions.push("target_ref = ?");
+        params.push(options.targetRef);
+    }
+    const where = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
+    return db
+        .prepare(`SELECT task_id, status, started_at, completed_at, failed_at, log_path,
+              target_kind, target_ref, metadata_json
+       FROM task_history ${where} ORDER BY started_at DESC`)
+        .all(...params);
+}
+/**
+ * Read COMPLETED `akm-improve` task_history runs whose `started_at` falls in
+ * `[since, until)` (or `started_at >= since` when `until` is omitted), ordered
+ * oldest-first by `started_at`. Only rows with a non-null `completed_at` are
+ * returned (in-flight runs are excluded). The `task_id = 'akm-improve'`
+ * predicate is fixed because the only caller (commands/health.ts
+ * `loadTaskIntervals`) builds wall-time intervals for the improve cron task.
+ *
+ * Owns the SQL formerly inlined in commands/health.ts. Note the bound is
+ * EXCLUSIVE on the upper end (`started_at < ?`) — callers pass an already
+ * widened window; this helper does not widen.
+ *
+ * Connection-lifetime rule (WS5): `.all()` materializes a plain array before
+ * returning.
+ */
+export function queryCompletedTaskIntervals(db, since, until) {
+    const sql = until
+        ? "SELECT started_at, completed_at FROM task_history WHERE task_id = 'akm-improve' AND started_at >= ? AND started_at < ? AND completed_at IS NOT NULL ORDER BY started_at"
+        : "SELECT started_at, completed_at FROM task_history WHERE task_id = 'akm-improve' AND started_at >= ? AND completed_at IS NOT NULL ORDER BY started_at";
+    return (until ? db.prepare(sql).all(since, until) : db.prepare(sql).all(since));
+}

package/dist/storage/sqlite-pragmas.js

@@ -0,0 +1,146 @@
+// 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 SQLite PRAGMA application + journal-mode resolution (#628).
+ *
+ * Every AKM SQLite opener applies the same opening PRAGMAs: a journal mode, a
+ * 30 s busy_timeout, and (for most) foreign_keys = ON. Historically each opener
+ * hard-coded `PRAGMA journal_mode = WAL`. WAL is impossible on network
+ * filesystems (NFS/SMB) because its `-shm` shared-memory wal-index cannot be
+ * mmap'd over a network mount, so AKM could not run with its data dir on a
+ * network share.
+ *
+ * This module centralises that PRAGMA block behind {@link applyStandardPragmas}
+ * and makes the journal mode configurable via the `AKM_SQLITE_JOURNAL_MODE`
+ * env var (WAL | DELETE | TRUNCATE; default WAL = unchanged behaviour). When the
+ * mode is the WAL default and the data directory is detected to live on a
+ * network filesystem, it auto-falls-back to DELETE with a one-line warning.
+ *
+ * Boundary note: this is a PLAIN module, not a runtime-boundary file. It only
+ * does pure string work plus `db.exec()` (allowed everywhere). The single
+ * runtime primitive it needs — a filesystem-type probe (statfs) — lives in
+ * src/runtime.ts and is injected here, keeping the network-FS classifier a
+ * pure, unit-testable function.
+ *
+ * @module storage/sqlite-pragmas
+ */
+import { warn } from "../core/warn.js";
+import { statfsType } from "../runtime.js";
+const VALID_MODES = new Set(["WAL", "DELETE", "TRUNCATE"]);
+// One-shot warning guards so a misconfigured env var or a network-FS fallback
+// each emit AT MOST ONCE per process rather than on every db open.
+let warnedInvalid = false;
+let warnedNetworkFallback = false;
+/**
+ * Resolve a raw `AKM_SQLITE_JOURNAL_MODE` value to a canonical {@link JournalMode}.
+ *
+ * PURE and unit-testable: the raw string is passed in (not read from
+ * `process.env` here). Trims + uppercases; an empty/undefined value yields the
+ * WAL default; a recognised value yields its canonical form; any other
+ * non-empty value warns once and falls back to WAL. Never throws.
+ */
+export function resolveJournalMode(raw) {
+    if (raw === undefined)
+        return "WAL";
+    const normalized = raw.trim().toUpperCase();
+    if (normalized === "")
+        return "WAL";
+    if (VALID_MODES.has(normalized)) {
+        return normalized;
+    }
+    warnInvalidJournalModeOnce(raw);
+    return "WAL";
+}
+/**
+ * The single env-reading seam: resolve the configured journal mode from
+ * `process.env.AKM_SQLITE_JOURNAL_MODE`. Read at call time (per open) so tests
+ * that set the env per-case see the right value and we avoid stale-env flakes.
+ */
+export function resolveConfiguredJournalMode(env = process.env) {
+    return resolveJournalMode(env.AKM_SQLITE_JOURNAL_MODE);
+}
+function warnInvalidJournalModeOnce(raw) {
+    if (warnedInvalid)
+        return;
+    warnedInvalid = true;
+    warn(`[akm] invalid AKM_SQLITE_JOURNAL_MODE=${JSON.stringify(raw)} — using WAL (valid: WAL, DELETE, TRUNCATE)`);
+}
+// Known Linux f_type magic numbers for network filesystems. node's statfs
+// normalises `type` to this numeric f_type magic on all platforms.
+const FS_MAGIC_NFS = 0x6969; // 26985    — NFS
+const FS_MAGIC_SMB = 0x517b; // 20859    — older SMB_SUPER_MAGIC
+const FS_MAGIC_CIFS = 0xff534d42; // 4283649346 — SMB/CIFS
+const FS_MAGIC_SMB2 = 0xfe534d42; // 4267272514 — SMB2
+const FS_MAGIC_FUSE = 0x65735546; // 1702057286 — FUSE (sshfs + many network FUSE mounts)
+const NETWORK_FS_MAGICS = new Set([
+    FS_MAGIC_NFS,
+    FS_MAGIC_SMB,
+    FS_MAGIC_CIFS,
+    FS_MAGIC_SMB2,
+    // FUSE is a judgment call: it backs BOTH network mounts (sshfs) and local
+    // mounts (some encrypted/overlay FS). Treating it as network falls back to
+    // DELETE — conservative-but-safe (DELETE works everywhere; the only cost is
+    // losing WAL concurrency). An operator can always force WAL via the env var.
+    FS_MAGIC_FUSE,
+]);
+/**
+ * PURE classifier: is `fsType` a known network-filesystem magic number?
+ * Returns false for `undefined` (probe failed/unsupported) and for local
+ * magics (ext4 0xEF53, btrfs, xfs, tmpfs, apfs, …). Unit-testable with
+ * injected magic numbers — no real mount required.
+ */
+export function isNetworkFilesystem(fsType) {
+    if (fsType === undefined)
+        return false;
+    return NETWORK_FS_MAGICS.has(fsType);
+}
+/**
+ * Apply AKM's standard opening PRAGMAs to `db`, in order:
+ *   1. `journal_mode` = the configured mode (with WAL→DELETE network-FS fallback)
+ *   2. `busy_timeout = 30000`
+ *   3. `foreign_keys = ON`  (unless `opts.foreignKeys === false`)
+ *   4. `synchronous = FULL` (only in a rollback-journal mode — DELETE/TRUNCATE)
+ *
+ * Returns the effective {@link JournalMode} so callers/tests can assert it.
+ *
+ * `synchronous = FULL` is set explicitly only in DELETE/TRUNCATE so durability
+ * intent is clear: rollback journals need FULL for crash-durability across
+ * power loss, whereas WAL is durable at NORMAL. SQLite's default synchronous is
+ * already FULL when unset, so this never changes WAL-default behaviour — the
+ * WAL path emits no `synchronous` pragma, exactly as before.
+ */
+export function applyStandardPragmas(db, opts = {}) {
+    let mode = resolveConfiguredJournalMode(opts.env);
+    // Network-FS fallback only fires for the WAL default and only when we have a
+    // directory to probe. An explicitly-requested DELETE/TRUNCATE is never
+    // overridden, and a failed/unsupported probe (undefined) keeps WAL.
+    if (mode === "WAL" && opts.dataDir) {
+        const probe = opts.fsTypeProbe ?? statfsType;
+        if (isNetworkFilesystem(probe(opts.dataDir))) {
+            mode = "DELETE";
+            warnNetworkFallbackOnce(opts.dataDir);
+        }
+    }
+    // PRAGMAs must run before any DDL or DML. busy_timeout is applied FIRST so a
+    // journal-mode change that must reclaim a leftover `-wal` file (WAL→DELETE on
+    // reopen of an unclean WAL db, e.g. after a crash) can wait out a transient
+    // lock instead of failing immediately with SQLITE_BUSY. For the WAL default
+    // this is a no-op (WAL→WAL changes nothing), so byte-identical behaviour is
+    // preserved.
+    db.exec("PRAGMA busy_timeout = 30000");
+    db.exec(`PRAGMA journal_mode = ${mode}`);
+    if (opts.foreignKeys !== false) {
+        db.exec("PRAGMA foreign_keys = ON");
+    }
+    if (mode !== "WAL") {
+        db.exec("PRAGMA synchronous = FULL");
+    }
+    return mode;
+}
+function warnNetworkFallbackOnce(dataDir) {
+    if (warnedNetworkFallback)
+        return;
+    warnedNetworkFallback = true;
+    warn(`[akm] network filesystem detected at ${dataDir} — WAL unsupported, using DELETE journal mode`);
+}

package/dist/tasks/backends/cron.js

@@ -29,7 +29,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { ConfigError } from "../../core/errors.js";
 import { getTaskLogDir } from "../../core/paths.js";
-import { resolveAkmInvocation } from "../resolveAkmBin.js";
+import { resolveAkmInvocation } from "../resolve-akm-bin.js";
 import { parseSchedule, translateToCron } from "../schedule.js";
 const BEGIN = (id) => `# akm:task ${id} BEGIN`;
 const END = (id) => `# akm:task ${id} END`;

package/dist/tasks/backends/index.js

@@ -4,7 +4,14 @@
 import { CRON_BACKEND } from "./cron.js";
 import { LAUNCHD_BACKEND } from "./launchd.js";
 import { SCHTASKS_BACKEND } from "./schtasks.js";
+let backendsOverrides;
+/** TEST-ONLY. Swap backend selection; pass undefined to restore the real implementations. */
+export function _setBackendsForTests(fakes) {
+    backendsOverrides = fakes;
+}
 export function selectBackend(options = {}) {
+    if (backendsOverrides?.selectBackend)
+        return backendsOverrides.selectBackend(options);
     const platform = options.platform ?? process.platform;
     switch (platform) {
         case "win32":
@@ -16,6 +23,8 @@ export function selectBackend(options = {}) {
     }
 }
 export function backendNameForPlatform(platform = process.platform) {
+    if (backendsOverrides?.backendNameForPlatform)
+        return backendsOverrides.backendNameForPlatform(platform);
     if (platform === "win32")
         return "schtasks";
     if (platform === "darwin")

package/dist/tasks/backends/launchd.js

@@ -27,7 +27,7 @@ import path from "node:path";
 import launchdTemplate from "../../assets/backends/launchd-template.xml" with { type: "text" };
 import { ConfigError } from "../../core/errors.js";
 import { getTaskLogDir } from "../../core/paths.js";
-import { resolveAkmInvocation } from "../resolveAkmBin.js";
+import { resolveAkmInvocation } from "../resolve-akm-bin.js";
 import { parseSchedule, translateToLaunchd } from "../schedule.js";
 import { escapeXml, nodeExec, nodeFs } from "./exec-utils.js";
 export const LAUNCHD_LABEL_PREFIX = "com.akm.task.";

package/dist/tasks/backends/schtasks.js

@@ -35,7 +35,7 @@ import path from "node:path";
 import schtasksTemplate from "../../assets/backends/schtasks-template.xml" with { type: "text" };
 import { ConfigError } from "../../core/errors.js";
 import { getTaskLogDir } from "../../core/paths.js";
-import { resolveAkmInvocation } from "../resolveAkmBin.js";
+import { resolveAkmInvocation } from "../resolve-akm-bin.js";
 import { parseSchedule, translateToSchtasks } from "../schedule.js";
 import { escapeXml, nodeExec, nodeFs } from "./exec-utils.js";
 export const DEFAULT_FOLDER_PREFIX = "\\akm\\";

package/dist/tasks/{resolveAkmBin.js → resolve-akm-bin.js}

@@ -44,8 +44,8 @@ export function resolveAkmInvocation(options = {}) {
 /**
  * From the URL of a module inside `src/tasks/` figure out the CLI entry.
  *
- *   • dev      `…/src/tasks/resolveAkmBin.ts`   → `…/src/cli.ts`
- *   • build    `…/dist/tasks/resolveAkmBin.js`  → `…/dist/cli.js`
+ *   • dev      `…/src/tasks/resolve-akm-bin.ts`   → `…/src/cli.ts`
+ *   • build    `…/dist/tasks/resolve-akm-bin.js`  → `…/dist/cli.js`
  */
 function resolveCliEntry(moduleUrl) {
     let modulePath;