brainclaw 1.9.1 → 1.10.0

package/dist/core/code-map/lock.js

@@ -0,0 +1,210 @@
+/**
+ * Code Map per-project lock (spec §5.8 + §6 rule 1).
+ *
+ * Distinct from the generic advisory lock in `src/core/lock.ts` because the
+ * Code Map lock carries rich metadata (owner_agent, pid, operation, scope,
+ * heartbeat_at, stale_after_ms) and implements operator-free abandoned-lock
+ * auto-recovery. It follows the same discipline as `withLock`:
+ *
+ *  - exclusive create with the `wx` open flag — creating an already-existing
+ *    lock must NOT truncate it;
+ *  - heartbeat refresh during a long operation;
+ *  - only a *live* lock blocks; an *abandoned* lock (dead pid OR stale
+ *    heartbeat, with no store file changed since) is reclaimed via an
+ *    atomic-rename takeover, logging the prior owner's metadata.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { writeFileAtomic } from '../io.js';
+import { logger } from '../logger.js';
+import { CODE_MAP_SCHEMA_VERSION, CodeLockSchema } from './types.js';
+import { codeMapDir, lockPath } from './paths.js';
+/** Default lock validity window before a silent owner is treated as abandoned. */
+export const DEFAULT_STALE_AFTER_MS = 60_000;
+function defaultIsPidAlive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function readLock(p) {
+    try {
+        const raw = fs.readFileSync(p, 'utf-8');
+        const parsed = CodeLockSchema.safeParse(JSON.parse(raw));
+        return parsed.success ? parsed.data : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Most recent mtime of any file under the store dir (excluding the lock itself). */
+function latestStoreMtimeMs(storeDir, lockFile) {
+    let latest = 0;
+    const walk = (dir) => {
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            const full = path.join(dir, entry.name);
+            if (full === lockFile)
+                continue;
+            if (entry.isDirectory()) {
+                walk(full);
+                continue;
+            }
+            // Ignore non-authoritative litter: writeFileAtomic temp files and the
+            // advisory lock-of-the-lock it creates. They are not store content and
+            // must not falsely register as "the store changed after the heartbeat"
+            // (which would wrongly block an otherwise-valid abandoned-lock reclaim).
+            const name = entry.name;
+            if (name.endsWith('.tmp') || name.endsWith('.lock'))
+                continue;
+            try {
+                const m = fs.statSync(full).mtimeMs;
+                if (m > latest)
+                    latest = m;
+            }
+            catch {
+                /* skip */
+            }
+        }
+    };
+    walk(storeDir);
+    return latest;
+}
+/**
+ * Evaluate the spec §5.8 abandoned conditions:
+ *  - the owner `pid` is no longer alive (definitive — the writer is gone), OR
+ *  - `heartbeat_at` is older than `stale_after_ms` AND no file under the store
+ *    changed after the last heartbeat (a silent-but-alive pid might still be
+ *    mid-operation, so the store-change guard protects only this path).
+ *
+ * IMPORTANT: the store-change guard must NOT gate the dead-pid path. A process
+ * that crashed mid-refresh after writing a shard (store mtime > heartbeat) is
+ * still definitively dead; gating it would freeze Code Map until an operator
+ * intervened, violating the operator-free crash-recovery guarantee (§6 rule 1,
+ * §12.3).
+ */
+export function isLockAbandoned(existing, opts) {
+    const pidDead = !opts.isPidAlive(existing.pid);
+    // Dead owner → reclaim unconditionally. No live writer can exist.
+    if (pidDead)
+        return true;
+    const heartbeatMs = Date.parse(existing.heartbeat_at);
+    const heartbeatStale = Number.isFinite(heartbeatMs) && opts.now - heartbeatMs > existing.stale_after_ms;
+    if (!heartbeatStale)
+        return false;
+    // Stale heartbeat but the pid is (or appears) alive: if the store changed
+    // after the last heartbeat, a writer may still be mid-operation despite an
+    // old heartbeat timestamp — do not reclaim.
+    const latestChange = latestStoreMtimeMs(opts.storeDir, opts.lockFile);
+    if (latestChange > heartbeatMs)
+        return false;
+    return true;
+}
+function buildLock(input, nowMs) {
+    const iso = new Date(nowMs).toISOString();
+    return CodeLockSchema.parse({
+        schema_version: CODE_MAP_SCHEMA_VERSION,
+        lock_id: `lock_${crypto.randomBytes(8).toString('hex')}`,
+        project_id: input.projectId ?? null,
+        worktree_id: input.worktreeId ?? null,
+        owner_agent: input.ownerAgent ?? null,
+        owner_agent_id: input.ownerAgentId ?? null,
+        pid: process.pid,
+        operation: input.operation ?? 'refresh',
+        scope: input.scope ?? 'changed',
+        created_at: iso,
+        heartbeat_at: iso,
+        stale_after_ms: input.staleAfterMs ?? DEFAULT_STALE_AFTER_MS,
+    });
+}
+/**
+ * Acquire the Code Map lock. Returns a handle on success, or `null` when a
+ * *live* lock is held by another owner.
+ *
+ * Exclusive-create path: `open(...'wx')` fails with EEXIST if a lock already
+ * exists, which guarantees we never truncate a competitor's live lock.
+ */
+export function acquireCodeLock(input = {}) {
+    const isPidAlive = input.isPidAlive ?? defaultIsPidAlive;
+    const now = input.now ?? Date.now;
+    const storeDir = codeMapDir(input.cwd, input.preferredDirName);
+    const lockFile = lockPath(input.cwd, input.preferredDirName);
+    if (!fs.existsSync(storeDir))
+        fs.mkdirSync(storeDir, { recursive: true });
+    const lock = buildLock(input, now());
+    const serialized = JSON.stringify(lock, null, 2);
+    // 1. Exclusive create. 'wx' never truncates an existing file (spec §6 rule 1).
+    try {
+        fs.writeFileSync(lockFile, serialized, { encoding: 'utf-8', flag: 'wx' });
+        return { lock, lockPath: lockFile };
+    }
+    catch (err) {
+        const code = err instanceof Error && 'code' in err ? err.code : undefined;
+        if (code !== 'EEXIST' && code !== 'EPERM' && code !== 'EACCES')
+            throw err;
+    }
+    // 2. A lock exists — read it and evaluate abandonment.
+    const existing = readLock(lockFile);
+    if (!existing) {
+        // Unreadable/corrupt lock — treat as abandoned and take over atomically.
+        writeFileAtomic(lockFile, serialized);
+        logger.debug(`code-map lock: reclaimed unreadable lock at ${lockFile}`);
+        return { lock, lockPath: lockFile };
+    }
+    // Re-entrant: same process already owns it -> refresh heartbeat, reuse.
+    if (existing.pid === process.pid) {
+        const refreshed = { ...existing, heartbeat_at: new Date(now()).toISOString() };
+        writeFileAtomic(lockFile, JSON.stringify(refreshed, null, 2));
+        return { lock: refreshed, lockPath: lockFile };
+    }
+    const abandoned = isLockAbandoned(existing, { now: now(), isPidAlive, storeDir, lockFile });
+    if (!abandoned) {
+        // Live lock blocks.
+        return null;
+    }
+    // 3. Abandoned takeover via atomic rename (writeFileAtomic does temp+rename
+    // with EPERM/EBUSY backoff — the NTFS-safe path).
+    writeFileAtomic(lockFile, serialized);
+    logger.debug(`code-map lock: reclaimed abandoned lock (prior owner agent=${existing.owner_agent ?? 'unknown'} ` +
+        `pid=${existing.pid} operation=${existing.operation} heartbeat_at=${existing.heartbeat_at})`);
+    return { lock, lockPath: lockFile };
+}
+/** Refresh the heartbeat on a held lock (spec §6 rule 2 — at least every 10s). */
+export function heartbeatCodeLock(handle, now = Date.now) {
+    const current = readLock(handle.lockPath);
+    // Only refresh if we still own it (pid match).
+    if (!current || current.pid !== process.pid)
+        return handle;
+    const refreshed = { ...current, heartbeat_at: new Date(now()).toISOString() };
+    writeFileAtomic(handle.lockPath, JSON.stringify(refreshed, null, 2));
+    return { lock: refreshed, lockPath: handle.lockPath };
+}
+/** Release a held lock. Only removes the file if this process still owns it. */
+export function releaseCodeLock(handle) {
+    const current = readLock(handle.lockPath);
+    if (current && current.pid !== process.pid)
+        return; // someone reclaimed it; leave it.
+    try {
+        fs.unlinkSync(handle.lockPath);
+    }
+    catch {
+        /* already gone */
+    }
+}
+/** Read the current lock, if any (for status / doctor). */
+export function readCodeLock(cwd, preferredDirName) {
+    return readLock(lockPath(cwd, preferredDirName));
+}
+//# sourceMappingURL=lock.js.map

package/dist/core/code-map/materialized.js

@@ -0,0 +1,51 @@
+/**
+ * Materialized JSONL cache (spec §4, §6 rule 5).
+ *
+ * nodes.v1.jsonl + edges.v1.jsonl are REBUILDABLE outputs with deterministic
+ * ordering. They exist for inspection / export / bulk scans only — queries must
+ * never depend on them. They are ignored by project generated-ignore rules by
+ * default, so they should not be committed.
+ */
+import fs from 'node:fs';
+import { writeFileAtomic } from '../io.js';
+import { materializedDir, materializedNodesPath, materializedEdgesPath } from './paths.js';
+function ensureDir(dir) {
+    if (!fs.existsSync(dir))
+        fs.mkdirSync(dir, { recursive: true });
+}
+/** Deterministic node ordering: by path, then id. */
+function orderedNodes(shards) {
+    const ordered = [...shards].sort((a, b) => a.path.localeCompare(b.path));
+    const out = [];
+    for (const shard of ordered) {
+        const nodes = [...shard.nodes].sort((a, b) => a.id.localeCompare(b.id));
+        out.push(...nodes);
+    }
+    return out;
+}
+/** Deterministic edge ordering: by from, to, kind, id. */
+function orderedEdges(shards) {
+    const ordered = [...shards].sort((a, b) => a.path.localeCompare(b.path));
+    const out = [];
+    for (const shard of ordered) {
+        const edges = [...shard.edges].sort((a, b) => a.from.localeCompare(b.from) ||
+            a.to.localeCompare(b.to) ||
+            a.kind.localeCompare(b.kind) ||
+            a.id.localeCompare(b.id));
+        out.push(...edges);
+    }
+    return out;
+}
+function toJsonl(rows) {
+    return rows.map((r) => JSON.stringify(r)).join('\n') + (rows.length > 0 ? '\n' : '');
+}
+/**
+ * Rebuild both materialized JSONL files from shards, atomically. Safe to call
+ * after every refresh; cheap relative to parsing.
+ */
+export function rebuildMaterialized(shards, cwd, preferredDirName) {
+    ensureDir(materializedDir(cwd, preferredDirName));
+    writeFileAtomic(materializedNodesPath(cwd, preferredDirName), toJsonl(orderedNodes(shards)));
+    writeFileAtomic(materializedEdgesPath(cwd, preferredDirName), toJsonl(orderedEdges(shards)));
+}
+//# sourceMappingURL=materialized.js.map

package/dist/core/code-map/memory-reader.js

@@ -0,0 +1,59 @@
+/**
+ * Default brainclaw-memory reader for Code Map `brief()` related-memory
+ * attachment (spec §11).
+ *
+ * This is the production wiring of the `MemoryReader` seam declared in
+ * query.ts. It reuses the canonical entity read path (`listEntities`) — the
+ * same one `bclaw_find`/`bclaw_context` use — so related-memory attachment sees
+ * exactly the decisions/traps/constraints/plans an agent would see elsewhere,
+ * with no duplicated store logic.
+ *
+ * The seam is deliberately injectable: tests construct `RelatedMemoryItem[]`
+ * directly instead of standing up a full entity store, and the backend can swap
+ * this for a cross-project or budget-bounded reader later without touching the
+ * ranking logic in query.ts.
+ */
+import { listEntities } from '../entity-operations.js';
+/** Entity kinds carrying path/tag context useful to a code-scope brief (spec §11). */
+const MEMORY_ENTITY_KINDS = ['decision', 'trap', 'constraint', 'plan'];
+function coerceTags(raw) {
+    if (Array.isArray(raw))
+        return raw.filter((t) => typeof t === 'string');
+    return [];
+}
+function coercePaths(raw) {
+    if (Array.isArray(raw))
+        return raw.filter((p) => typeof p === 'string');
+    return [];
+}
+function toRelatedMemoryItem(kind, item) {
+    return {
+        id: typeof item.id === 'string' ? item.id : '',
+        kind,
+        text: typeof item.text === 'string' ? item.text : '',
+        tags: coerceTags(item.tags),
+        related_paths: coercePaths(item.related_paths),
+    };
+}
+/**
+ * Production `MemoryReader`: read decisions/traps/constraints/plans for the
+ * project at `ctx.cwd` via the canonical entity read path. Best-effort — a read
+ * failure for one kind never breaks a brief; it simply contributes no memory.
+ */
+export const defaultMemoryReader = (ctx) => {
+    const cwd = ctx.cwd ?? process.cwd();
+    const out = [];
+    for (const kind of MEMORY_ENTITY_KINDS) {
+        try {
+            const result = listEntities(kind, cwd, { includeLegacy: true });
+            for (const raw of result.items) {
+                out.push(toRelatedMemoryItem(kind, raw));
+            }
+        }
+        catch {
+            // best-effort: a brief never fails because one memory kind couldn't load.
+        }
+    }
+    return out;
+};
+//# sourceMappingURL=memory-reader.js.map

package/dist/core/code-map/paths.js

@@ -0,0 +1,53 @@
+/**
+ * Code Map store layout path helpers (spec §4).
+ *
+ * All paths are relative to `<project>/.brainclaw/code/`. The store root is
+ * derived from the Brainclaw memory dir convention (`.brainclaw/`).
+ */
+import path from 'node:path';
+import { MEMORY_DIR } from '../io.js';
+import { shardPrefix } from './ids.js';
+/** Subdirectory under `.brainclaw/` that holds the Code Map store. */
+export const CODE_MAP_SUBDIR = 'code';
+/** Absolute path to `<project>/.brainclaw/code/`. */
+export function codeMapDir(cwd = process.cwd(), preferredDirName) {
+    return path.join(cwd, preferredDirName ?? MEMORY_DIR, CODE_MAP_SUBDIR);
+}
+export function manifestPath(cwd, preferredDirName) {
+    return path.join(codeMapDir(cwd, preferredDirName), 'manifest.json');
+}
+export function profilerPath(cwd, preferredDirName) {
+    return path.join(codeMapDir(cwd, preferredDirName), 'profiler.json');
+}
+export function lockPath(cwd, preferredDirName) {
+    return path.join(codeMapDir(cwd, preferredDirName), '.lock');
+}
+export function filesDir(cwd, preferredDirName) {
+    return path.join(codeMapDir(cwd, preferredDirName), 'files');
+}
+/** Absolute path to a per-file shard: files/<prefix>/<file_id>.json. */
+export function shardPath(fileIdHash, cwd, preferredDirName) {
+    return path.join(filesDir(cwd, preferredDirName), shardPrefix(fileIdHash), `${fileIdHash}.json`);
+}
+export function indexesDir(cwd, preferredDirName) {
+    return path.join(codeMapDir(cwd, preferredDirName), 'indexes');
+}
+export function symbolsIndexPath(cwd, preferredDirName) {
+    return path.join(indexesDir(cwd, preferredDirName), 'index.symbols.v1.json');
+}
+export function importsIndexPath(cwd, preferredDirName) {
+    return path.join(indexesDir(cwd, preferredDirName), 'index.imports.v1.json');
+}
+export function resolutionIndexPath(cwd, preferredDirName) {
+    return path.join(indexesDir(cwd, preferredDirName), 'index.resolution.v1.json');
+}
+export function materializedDir(cwd, preferredDirName) {
+    return path.join(codeMapDir(cwd, preferredDirName), 'materialized');
+}
+export function materializedNodesPath(cwd, preferredDirName) {
+    return path.join(materializedDir(cwd, preferredDirName), 'nodes.v1.jsonl');
+}
+export function materializedEdgesPath(cwd, preferredDirName) {
+    return path.join(materializedDir(cwd, preferredDirName), 'edges.v1.jsonl');
+}
+//# sourceMappingURL=paths.js.map