akm-cli 0.9.16 → 0.9.17-alpha.10

package/dist/indexer/index-rebuild-lock.js

@@ -20,7 +20,6 @@
  * no-stale-age-window rationale.
  */
 import { releaseLock } from "../core/file-lock.js";
-import { tryWithMaintenanceStartBarrier, withMaintenanceStartBarrier } from "../core/maintenance-barrier.js";
 import { getIndexRebuildLockPath } from "../core/paths.js";
 import { formatLockHolderPid, tryAcquireRunLock } from "../core/run-lock.js";
 import { warn, warnVerbose } from "../core/warn.js";
@@ -49,21 +48,14 @@ export function tryAcquireIndexRebuildLock(skipIfLocked) {
                 `(${info.reason}); that process is no longer running.`);
         },
     });
+    const result = acquire();
+    if (result.state === "acquired")
+        return result;
     if (skipIfLocked) {
-        const result = tryWithMaintenanceStartBarrier(acquire);
-        if (!result) {
-            warn("[index] maintenance barrier held; skipping (--skip-if-locked)");
-            return { state: "skipped", holder: { pid: null, startedAt: null, launcherPid: null } };
-        }
-        if (result.state === "acquired")
-            return result;
         warn(`[index] another index run holds the lock (PID ${formatLockHolderPid(result.holder)}, started ${result.holder.startedAt}); ` +
             "skipping (--skip-if-locked)");
         return { state: "skipped", holder: result.holder };
     }
-    const result = withMaintenanceStartBarrier(acquire);
-    if (result.state === "acquired")
-        return result;
     warn(`[index] another index run is active (pid ${formatLockHolderPid(result.holder)}, started ${result.holder.startedAt}); ` +
         "this run will contend with it — pass --skip-if-locked for scheduled runs");
     return { state: "contended", holder: result.holder };

package/dist/indexer/index-writer-lock.js

@@ -25,8 +25,8 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 import fs from "node:fs";
 import path from "node:path";
+import { TransientError } from "../core/errors.js";
 import { createLockPayload, probeLock, reclaimStaleLock, releaseLock, tryAcquireLockSync, } from "../core/file-lock.js";
-import { tryAcquireMaintenanceBarrier } from "../core/maintenance-barrier.js";
 import { getDbPath, getIndexWriterLockPath } from "../core/paths.js";
 import { warn } from "../core/warn.js";
 import { sleepSync } from "../runtime.js";
@@ -92,21 +92,12 @@ function createLease(lockPath, ownership) {
 }
 function tryAcquireAssetMutationLease(lockPath, purpose) {
     while (true) {
-        const releaseBarrier = tryAcquireMaintenanceBarrier();
-        if (!releaseBarrier)
+        const ownership = tryAcquireLockSync(lockPath, buildPayload(purpose));
+        if (ownership)
+            return createLease(lockPath, ownership);
+        const probe = probeLock(lockPath);
+        if (probe.state !== "stale" || !reclaimStaleLock(lockPath, probe))
             return undefined;
-        try {
-            const ownership = tryAcquireLockSync(lockPath, buildPayload(purpose));
-            if (ownership)
-                return createLease(lockPath, ownership);
-            // No `staleAfterMs`: only a verifiably dead holder is ever reclaimed.
-            const probe = probeLock(lockPath);
-            if (probe.state !== "stale" || !reclaimStaleLock(lockPath, probe))
-                return undefined;
-        }
-        finally {
-            releaseBarrier();
-        }
     }
 }
 export async function acquireAssetMutationLease(options) {
@@ -129,7 +120,7 @@ export async function acquireAssetMutationLease(options) {
         // attempt, so a caller with maxWaitMs:0 still gets one chance at a free lock
         // instead of throwing before it ever tries.
         if (maxWaitMs >= 0 && Date.now() - startedAt >= maxWaitMs) {
-            throw new Error(`timed out waiting for asset mutation lease for ${options.purpose}`);
+            throw new TransientError(`timed out waiting for asset mutation lease for ${options.purpose}`, "ASSET_MUTATION_LEASE_HELD");
         }
         const waitedMs = Date.now() - startedAt;
         if (waitedMs - lastWaitNoticeMs >= 15000) {
@@ -180,7 +171,7 @@ export function withAssetMutationLeaseSync(purpose, run) {
             if (!lease) {
                 const waitedMs = Date.now() - startedAt;
                 if (waitedMs >= maxWaitMs) {
-                    throw new Error(`timed out waiting for asset mutation lease for ${purpose}`);
+                    throw new TransientError(`timed out waiting for asset mutation lease for ${purpose}`, "ASSET_MUTATION_LEASE_HELD");
                 }
                 // #956: the sync path used to wait up to 10 minutes with zero
                 // progress feedback. Mirror the async path's 15s onWait cadence, but

package/dist/indexer/index-written-assets.js

@@ -15,9 +15,8 @@
  * This is NOT a general reindex. It upserts exactly the files the caller just
  * wrote: frontmatter/metadata via the shared matcher pipeline, the canonical
  * row with its transactionally owned FTS projection, and vectors for changed
- * entry IDs when semantic search is enabled. Index-time LLM passes, graph
- * extraction, `builtAt`, and the per-dir walk cache remain full-index
- * responsibilities.
+ * entry IDs when semantic search is enabled. `builtAt` and the per-dir walk
+ * cache remain full-index responsibilities.
  */
 import fs from "node:fs";
 import path from "node:path";
@@ -33,9 +32,8 @@ import { closeDatabase, openExistingDatabase } from "../storage/repositories/ind
 import { deleteEntriesByIds, getEntryCount, upsertEntry } from "../storage/repositories/index-entries-repository.js";
 import { deriveEntryProvenance, deriveInstallations } from "./installations.js";
 import { generateEmbeddingsForDb, publishTargetedEmbeddingMeta } from "./materialize-embeddings.js";
-import { getMarkdownFragmentContent, hasMarkdownFragmentContent, setMarkdownFragmentContent, } from "./passes/metadata.js";
+import { withFileSize } from "./passes/metadata.js";
 import { drainDirDocuments } from "./scan/drain-dir.js";
-import { buildSearchText } from "./search/search-fields.js";
 import { buildFileContext } from "./walk/file-context.js";
 /**
  * Busy-timeout (ms) for write-path index upserts. A real write — unlike the
@@ -66,161 +64,150 @@ export const WRITE_PATH_INDEX_BUSY_TIMEOUT_MS = 5_000;
  */
 export async function indexWrittenAssets(stashDir, filePaths, options = {}) {
     try {
-        return await (async () => {
-            // #956: a live `akm index` rebuild holds index.db under one long
-            // transaction (persistDirRecords), which this fast path's own 5s
-            // busy_timeout would just contend with pointlessly. Interactive
-            // commands (remember, import, extract session assets) must never wait
-            // on it — skip the inline upsert/embedding entirely; the write itself
-            // (file + commit) has already succeeded by the time this runs, and the
-            // rebuild in progress will pick up the change on its own.
-            const rebuildProbe = probeLock(getIndexRebuildLockPath());
-            if (rebuildProbe.state === "held") {
-                // #956: name the launcher pid alongside the holder pid when known —
-                // every process listing and task log shows the launcher's pid, not
-                // the bun/node child's.
-                const holderLabel = formatLockHolderPid({
-                    pid: rebuildProbe.holderPid,
-                    launcherPid: rebuildProbe.launcherPid ?? null,
-                });
-                warn(`index rebuild in progress (pid ${holderLabel}); the next index pass will index ${filePaths.join(", ")}`);
-                return true;
-            }
-            const dbPath = getDbPath();
-            // `true` here means "the index is in the state the caller expects" — and
-            // `acceptProposal` advances its journal to `index-finalized` on the
-            // strength of it. Only a genuinely ABSENT index earns that answer: an
-            // index we cannot read has NOT been updated, so it falls through to
-            // `openExistingDatabase` and surfaces as the honest `false` (#791).
-            if (isPathAbsent(dbPath))
-                return true;
-            // The full walk never descends into dot-directories (for example `.meta/`)
-            // — mirror that dot-segment skip here so this fast path indexes exactly
-            // what a full run would. Sensitive/
-            // infra abstention is the adapter's job now (see the `akmAdapter` note
-            // below), not a path pre-filter.
-            const files = filePaths.filter((f) => {
-                const rel = path.relative(stashDir, f);
-                return !rel.split(/[\\/]+/).some((segment) => segment.startsWith("."));
+        // #956: a live `akm index` rebuild holds index.db under one long
+        // transaction (persistDirRecords), which this fast path's own 5s
+        // busy_timeout would just contend with pointlessly. Interactive
+        // commands (remember, import, extract session assets) must never wait
+        // on it — skip the inline upsert/embedding entirely; the write itself
+        // (file + commit) has already succeeded by the time this runs, and the
+        // rebuild in progress will pick up the change on its own.
+        const rebuildProbe = probeLock(getIndexRebuildLockPath());
+        if (rebuildProbe.state === "held") {
+            // #956: name the launcher pid alongside the holder pid when known —
+            // every process listing and task log shows the launcher's pid, not
+            // the bun/node child's.
+            const holderLabel = formatLockHolderPid({
+                pid: rebuildProbe.holderPid,
+                launcherPid: rebuildProbe.launcherPid ?? null,
             });
-            if (files.length === 0)
-                return true;
-            // Generate metadata BEFORE opening the DB so the write window stays
-            // short. One drain call per file keeps the entry↔path pairing exact and
-            // reuses the full-index recognize engine (F4a M-core-2 item 5): broken
-            // workflows drop, valid workflow docs are cached for the side-table upsert.
-            const component = deriveInstallations([
-                { path: stashDir, writable: true, ...(options.bundleId ? { registryId: options.bundleId } : {}) },
-            ])[0]?.components[0];
-            if (!component)
-                throw new Error(`Could not derive bundle provenance for ${stashDir}`);
-            const pairs = [];
-            const unindexable = new Set();
-            const rejectedConceptIds = new Set();
-            for (const file of files) {
-                if (!fs.existsSync(file)) {
-                    let authoredDanglingSymlink = false;
-                    try {
-                        authoredDanglingSymlink = fs.lstatSync(file).isSymbolicLink();
-                    }
-                    catch {
-                        // A genuinely absent path has no source identity to preflight.
-                    }
-                    if (!authoredDanglingSymlink) {
-                        unindexable.add(file);
-                        continue;
-                    }
+            warn(`index rebuild in progress (pid ${holderLabel}); the next index pass will index ${filePaths.join(", ")}`);
+            return true;
+        }
+        const dbPath = getDbPath();
+        // `true` here means "the index is in the state the caller expects" — and
+        // `acceptProposal` advances its journal to `index-finalized` on the
+        // strength of it. Only a genuinely ABSENT index earns that answer: an
+        // index we cannot read has NOT been updated, so it falls through to
+        // `openExistingDatabase` and surfaces as the honest `false` (#791).
+        if (isPathAbsent(dbPath))
+            return true;
+        // The full walk never descends into dot-directories (for example `.meta/`)
+        // — mirror that dot-segment skip here so this fast path indexes exactly
+        // what a full run would. Sensitive/
+        // infra abstention is the adapter's job now (see the `akmAdapter` note
+        // below), not a path pre-filter.
+        const files = filePaths.filter((f) => {
+            const rel = path.relative(stashDir, f);
+            return !rel.split(/[\\/]+/).some((segment) => segment.startsWith("."));
+        });
+        if (files.length === 0)
+            return true;
+        // Generate metadata BEFORE opening the DB so the write window stays
+        // short. One drain call per file keeps the entry↔path pairing exact and
+        // reuses the full-index recognize engine (F4a M-core-2 item 5): broken
+        // workflows drop, valid workflow docs are cached for the side-table upsert.
+        const component = deriveInstallations([
+            { path: stashDir, writable: true, ...(options.bundleId ? { registryId: options.bundleId } : {}) },
+        ])[0]?.components[0];
+        if (!component)
+            throw new Error(`Could not derive bundle provenance for ${stashDir}`);
+        const pairs = [];
+        const unindexable = new Set();
+        const rejectedConceptIds = new Set();
+        for (const file of files) {
+            if (!fs.existsSync(file)) {
+                let authoredDanglingSymlink = false;
+                try {
+                    authoredDanglingSymlink = fs.lstatSync(file).isSymbolicLink();
+                }
+                catch {
+                    // A genuinely absent path has no source identity to preflight.
                 }
-                const ctx = buildFileContext(stashDir, file);
-                // Hardcoded `akmAdapter` on purpose (owner ruling 2026-07-21): this
-                // write-path fast path only ever runs for assets a first-class akm
-                // mutation command just wrote into a managed akm source, so the akm
-                // adapter is always the right recognizer here — no per-component
-                // dispatch needed.
-                const drained = drainDirDocuments(akmAdapter, component, [ctx]);
-                for (const rejectedPath of drained.rejectedPaths)
-                    unindexable.add(rejectedPath);
-                for (const conceptId of drained.rejectedConceptIds)
-                    rejectedConceptIds.add(conceptId);
-                const entry = drained.entries[0];
-                // A broken workflow drains to zero entries and is treated as
-                // unindexable; valid peer sources have already compiled to source IR.
-                const conceptId = drained.conceptIdByFile.get(ctx.absPath);
-                if (entry && conceptId)
-                    pairs.push({ file, entry, conceptId, contentHash: drained.hashByFile.get(ctx.absPath) });
-                else
+                if (!authoredDanglingSymlink) {
                     unindexable.add(file);
-            }
-            const db = openExistingDatabase(dbPath);
-            try {
-                db.exec(`PRAGMA busy_timeout = ${WRITE_PATH_INDEX_BUSY_TIMEOUT_MS}`);
-                if (getEntryCount(db) === 0)
-                    return true;
-                const targetEntryIds = new Set();
-                let mutated = false;
-                db.transaction(() => {
-                    const unindexableEntryIds = new Set();
-                    for (const file of unindexable) {
-                        const rows = db
-                            .prepare(`SELECT id FROM entries
-                  WHERE file_path = ?
-                    AND bundle_id = ?
-                    AND adapter_id = ?`)
-                            .all(file, component.id, component.adapter);
-                        for (const row of rows)
-                            unindexableEntryIds.add(row.id);
-                    }
-                    for (const conceptId of rejectedConceptIds) {
-                        const itemRef = `${component.id}//${conceptId}`;
-                        const rows = db
-                            .prepare(`SELECT id FROM entries
-                  WHERE bundle_id = ? AND adapter_id = ?
-                    AND type = 'workflow'
-                    AND (concept_id = ? OR item_ref = ?)`)
-                            .all(component.id, component.adapter, conceptId, itemRef);
-                        for (const row of rows)
-                            unindexableEntryIds.add(row.id);
-                    }
-                    deleteEntriesByIds(db, [...unindexableEntryIds]);
-                    mutated ||= unindexableEntryIds.size > 0;
-                    for (const { file, entry, conceptId, contentHash } of pairs) {
-                        let entryWithSize = entry;
-                        try {
-                            entryWithSize = { ...entry, fileSize: fs.statSync(file).size };
-                            if (hasMarkdownFragmentContent(entry)) {
-                                setMarkdownFragmentContent(entryWithSize, getMarkdownFragmentContent(entry));
-                            }
-                        }
-                        catch {
-                            // stat raced a delete — index without the size, like the full walk does.
-                        }
-                        // Real provenance (F4a M-core-2 item 5): populate item_ref/content_hash
-                        // via the SAME derivation the full-index writer uses, so a write-path
-                        // row is never a NULL-item_ref straggler.
-                        const provenance = deriveEntryProvenance({ bundleId: component.id, componentId: component.id, adapterId: component.adapter }, entry.type, entry.name, conceptId);
-                        // A materialized file has one current owner. If a targeted write is
-                        // the ownership handoff (for example an explicitly named bundle
-                        // replacing an earlier path-derived bootstrap identity), remove the
-                        // superseded physical-path row before publishing the canonical ref.
-                        const supersededIds = db
-                            .prepare("SELECT id FROM entries WHERE file_path = ? AND item_ref <> ?")
-                            .all(file, provenance.itemRef);
-                        deleteEntriesByIds(db, supersededIds.map((row) => row.id));
-                        targetEntryIds.add(upsertEntry(db, file, entryWithSize, buildSearchText(entry), provenance, contentHash));
-                        mutated = true;
-                    }
-                })();
-                if (mutated) {
-                    const config = loadConfig();
-                    await generateEmbeddingsForDb(db, config, () => { }, undefined, [...targetEntryIds]);
-                    publishTargetedEmbeddingMeta(db, config);
+                    continue;
                 }
             }
-            finally {
-                closeDatabase(db);
+            const ctx = buildFileContext(stashDir, file);
+            // Hardcoded `akmAdapter` on purpose (owner ruling 2026-07-21): this
+            // write-path fast path only ever runs for assets a first-class akm
+            // mutation command just wrote into a managed akm source, so the akm
+            // adapter is always the right recognizer here — no per-component
+            // dispatch needed.
+            const drained = drainDirDocuments(akmAdapter, component, [ctx]);
+            for (const rejectedPath of drained.rejectedPaths)
+                unindexable.add(rejectedPath);
+            for (const conceptId of drained.rejectedConceptIds)
+                rejectedConceptIds.add(conceptId);
+            const entry = drained.entries[0];
+            // A broken workflow drains to zero entries and is treated as
+            // unindexable; valid peer sources have already compiled to source IR.
+            const conceptId = drained.conceptIdByFile.get(ctx.absPath);
+            if (entry && conceptId)
+                pairs.push({ file, entry, conceptId, contentHash: drained.hashByFile.get(ctx.absPath) });
+            else
+                unindexable.add(file);
+        }
+        const db = openExistingDatabase(dbPath);
+        try {
+            db.exec(`PRAGMA busy_timeout = ${WRITE_PATH_INDEX_BUSY_TIMEOUT_MS}`);
+            if (getEntryCount(db) === 0)
+                return true;
+            const targetEntryIds = new Set();
+            let mutated = false;
+            db.transaction(() => {
+                const unindexableEntryIds = new Set();
+                for (const file of unindexable) {
+                    const rows = db
+                        .prepare(`SELECT id FROM entries
+                WHERE file_path = ?
+                  AND bundle_id = ?
+                  AND adapter_id = ?`)
+                        .all(file, component.id, component.adapter);
+                    for (const row of rows)
+                        unindexableEntryIds.add(row.id);
+                }
+                for (const conceptId of rejectedConceptIds) {
+                    const itemRef = `${component.id}//${conceptId}`;
+                    const rows = db
+                        .prepare(`SELECT id FROM entries
+                WHERE bundle_id = ? AND adapter_id = ?
+                  AND type = 'workflow'
+                  AND (concept_id = ? OR item_ref = ?)`)
+                        .all(component.id, component.adapter, conceptId, itemRef);
+                    for (const row of rows)
+                        unindexableEntryIds.add(row.id);
+                }
+                deleteEntriesByIds(db, [...unindexableEntryIds]);
+                mutated ||= unindexableEntryIds.size > 0;
+                for (const { file, entry, conceptId, contentHash } of pairs) {
+                    const entryWithSize = withFileSize(entry, file);
+                    // Real provenance (F4a M-core-2 item 5): populate item_ref/content_hash
+                    // via the SAME derivation the full-index writer uses, so a write-path
+                    // row is never a NULL-item_ref straggler.
+                    const provenance = deriveEntryProvenance({ bundleId: component.id, componentId: component.id, adapterId: component.adapter }, entry.type, entry.name, conceptId);
+                    // A materialized file has one current owner. If a targeted write is
+                    // the ownership handoff (for example an explicitly named bundle
+                    // replacing an earlier path-derived bootstrap identity), remove the
+                    // superseded physical-path row before publishing the canonical ref.
+                    const supersededIds = db
+                        .prepare("SELECT id FROM entries WHERE file_path = ? AND item_ref <> ?")
+                        .all(file, provenance.itemRef);
+                    deleteEntriesByIds(db, supersededIds.map((row) => row.id));
+                    targetEntryIds.add(upsertEntry(db, file, entryWithSize, provenance, contentHash));
+                    mutated = true;
+                }
+            })();
+            if (mutated) {
+                const config = loadConfig();
+                await generateEmbeddingsForDb(db, config, () => { }, undefined, [...targetEntryIds]);
+                publishTargetedEmbeddingMeta(db, config);
             }
-            return true;
-        })();
+        }
+        finally {
+            closeDatabase(db);
+        }
+        return true;
     }
     catch (error) {
         // A permission fault is the one failure the next full index will NOT heal,