agent-bober 0.17.1 → 0.18.0

package/dist/state/facts.js

@@ -0,0 +1,208 @@
+import { join } from "node:path";
+import { createHash } from "node:crypto";
+import Database from "better-sqlite3";
+import { z } from "zod";
+import { ensureDir } from "./helpers.js";
+import { memoryDir } from "./memory.js";
+// ── Re-exports from reconcile layer ──────────────────────────────────────
+// writeFact lives in reconcile.ts (to avoid a runtime import cycle) but is
+// re-exported here so consumers can import it from the facts module.
+export { writeFact } from "../orchestrator/memory/reconcile.js";
+// ── Schema ────────────────────────────────────────────────────────────
+/**
+ * Zod schema for a fact input — mirrors LessonEntrySchema in memory.ts.
+ * All timestamps are ISO 8601 strings; the store never reads the clock.
+ */
+export const FactSchema = z.object({
+    scope: z.string(),
+    subject: z.string().min(1),
+    predicate: z.string().min(1),
+    value: z.string().min(1),
+    confidence: z.number().min(0).max(1).default(1),
+    sourceRunId: z.string().nullable().default(null),
+    tValid: z.string().datetime(),
+    tCreated: z.string().datetime(),
+});
+// ── Deterministic id ──────────────────────────────────────────────────
+/**
+ * Derive a deterministic 16-char hex fact id from the fact signature.
+ * Mirrors lessonIdFromSignature in src/orchestrator/memory/distill.ts:88-99.
+ * Identical inputs always produce the same id — no wall-clock dependency.
+ */
+export function factId(scope, subject, predicate, value, tCreated) {
+    return createHash("sha256")
+        .update(`${scope}|${subject}|${predicate}|${value}|${tCreated}`)
+        .digest("hex")
+        .slice(0, 16);
+}
+// ── Path helpers ──────────────────────────────────────────────────────
+/**
+ * Resolve the absolute path to facts.db for the given project root and namespace.
+ * Uses the same memoryDir mapping rule as memory.ts (no duplication).
+ */
+export function factsDbPath(projectRoot, namespace) {
+    return join(memoryDir(projectRoot, namespace), "facts.db");
+}
+/**
+ * Ensure the directory that will hold the DB file exists.
+ * Must be called by the CLI handler before constructing a file-backed FactStore.
+ * Not needed for ':memory:' paths.
+ */
+export async function ensureFactsDir(projectRoot, namespace) {
+    await ensureDir(memoryDir(projectRoot, namespace));
+}
+function rowToRecord(row) {
+    return {
+        id: row.id,
+        scope: row.scope,
+        subject: row.subject,
+        predicate: row.predicate,
+        value: row.value,
+        confidence: row.confidence,
+        sourceRunId: row.source_run_id,
+        tValid: row.t_valid,
+        tInvalid: row.t_invalid,
+        tCreated: row.t_created,
+        tInvalidated: row.t_invalidated,
+    };
+}
+// ── FactStore ─────────────────────────────────────────────────────────
+/**
+ * Bi-temporal SQLite-backed fact store.
+ *
+ * PURE: Never calls Date.now() or new Date() — every timestamp is a parameter.
+ * Hidden behind this interface so the driver (better-sqlite3) is swappable.
+ *
+ * bober: in-memory or file-backed via better-sqlite3 (synchronous); swap for
+ * node:sqlite when engines.node is raised to >=22.5.
+ */
+export class FactStore {
+    db;
+    constructor(dbPath) {
+        this.db = new Database(dbPath);
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS semantic_facts (
+        id TEXT PRIMARY KEY,
+        scope TEXT NOT NULL,
+        subject TEXT NOT NULL,
+        predicate TEXT NOT NULL,
+        value TEXT NOT NULL,
+        confidence REAL NOT NULL,
+        source_run_id TEXT,
+        t_valid TEXT NOT NULL,
+        t_invalid TEXT,
+        t_created TEXT NOT NULL,
+        t_invalidated TEXT
+      );
+      CREATE INDEX IF NOT EXISTS idx_facts_sp ON semantic_facts(scope, subject, predicate);
+      CREATE INDEX IF NOT EXISTS idx_facts_active ON semantic_facts(scope, t_invalidated);
+    `);
+    }
+    /**
+     * Insert a new fact. Validates input with FactSchema and derives the
+     * deterministic id. Returns the persisted FactRecord.
+     */
+    insertFact(input) {
+        const result = FactSchema.safeParse(input);
+        if (!result.success) {
+            const issues = result.error.issues
+                .map((i) => `  - ${i.path.join(".")}: ${i.message}`)
+                .join("\n");
+            throw new Error(`Invalid fact input:\n${issues}`);
+        }
+        const data = result.data;
+        const id = factId(data.scope, data.subject, data.predicate, data.value, data.tCreated);
+        this.db
+            .prepare(`INSERT OR REPLACE INTO semantic_facts
+          (id, scope, subject, predicate, value, confidence, source_run_id, t_valid, t_invalid, t_created, t_invalidated)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, NULL, ?, NULL)`)
+            .run(id, data.scope, data.subject, data.predicate, data.value, data.confidence, data.sourceRunId, data.tValid, data.tCreated);
+        return {
+            id,
+            scope: data.scope,
+            subject: data.subject,
+            predicate: data.predicate,
+            value: data.value,
+            confidence: data.confidence,
+            sourceRunId: data.sourceRunId,
+            tValid: data.tValid,
+            tInvalid: null,
+            tCreated: data.tCreated,
+            tInvalidated: null,
+        };
+    }
+    /**
+     * Return all active (non-invalidated) facts matching the given scope.
+     * Optionally filtered by subject and/or predicate.
+     * Active = t_invalidated IS NULL.
+     */
+    getActiveFacts(scope, subject, predicate) {
+        if (subject !== undefined && predicate !== undefined) {
+            const rows = this.db
+                .prepare(`SELECT * FROM semantic_facts
+           WHERE scope = ? AND subject = ? AND predicate = ? AND t_invalidated IS NULL`)
+                .all(scope, subject, predicate);
+            return rows.map(rowToRecord);
+        }
+        if (subject !== undefined) {
+            const rows = this.db
+                .prepare(`SELECT * FROM semantic_facts
+           WHERE scope = ? AND subject = ? AND t_invalidated IS NULL`)
+                .all(scope, subject);
+            return rows.map(rowToRecord);
+        }
+        if (predicate !== undefined) {
+            const rows = this.db
+                .prepare(`SELECT * FROM semantic_facts
+           WHERE scope = ? AND predicate = ? AND t_invalidated IS NULL`)
+                .all(scope, predicate);
+            return rows.map(rowToRecord);
+        }
+        const rows = this.db
+            .prepare(`SELECT * FROM semantic_facts
+         WHERE scope = ? AND t_invalidated IS NULL`)
+            .all(scope);
+        return rows.map(rowToRecord);
+    }
+    /**
+     * Return a single fact by its id regardless of invalidation status.
+     * Returns null if not found.
+     */
+    getFact(id) {
+        const row = this.db
+            .prepare(`SELECT * FROM semantic_facts WHERE id = ?`)
+            .get(id);
+        return row ? rowToRecord(row) : null;
+    }
+    /**
+     * Soft-delete a fact by setting t_invalidated.
+     * Returns true if the fact was invalidated, false if it was already invalidated or not found.
+     * Never deletes rows.
+     */
+    invalidateFact(id, tInvalidated) {
+        const info = this.db
+            .prepare(`UPDATE semantic_facts
+         SET t_invalidated = ?
+         WHERE id = ? AND t_invalidated IS NULL`)
+            .run(tInvalidated, id);
+        return info.changes > 0;
+    }
+    /**
+     * Supersede a fact: set BOTH t_invalidated (record-time) AND t_invalid (world-time end).
+     * Used by reconcile on UPDATE to carry both bi-temporal closure fields.
+     * Returns true if the row was updated; false if not found or already invalidated.
+     */
+    supersedeFact(id, tInvalidated, tInvalid) {
+        const info = this.db
+            .prepare(`UPDATE semantic_facts
+         SET t_invalidated = ?, t_invalid = ?
+         WHERE id = ? AND t_invalidated IS NULL`)
+            .run(tInvalidated, tInvalid, id);
+        return info.changes > 0;
+    }
+    /** Close the underlying database connection. */
+    close() {
+        this.db.close();
+    }
+}
+//# sourceMappingURL=facts.js.map

package/dist/state/facts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"facts.js","sourceRoot":"","sources":["../../src/state/facts.ts"],"names":[],"mappings":"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"}

package/dist/state/guidance.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Validate that a runId is a safe path segment.
+ * Rejects empty strings, strings containing path separators (/ or \),
+ * strings containing '..', and absolute paths.
+ * This is a security guard: a malicious runId must never escape .bober/runs.
+ */
+export declare function safeSegment(runId: string): boolean;
+/**
+ * Check whether the run directory exists for the given runId.
+ * Returns false if not found — never throws.
+ * Mirrors approval-state.ts:pendingExists.
+ */
+export declare function hasRunDir(projectRoot: string, runId: string): Promise<boolean>;
+/**
+ * Append a guidance entry to .bober/runs/<runId>/guidance.jsonl.
+ *
+ * Security: validates runId is a safe path segment BEFORE building any path.
+ * Throws with a clear message if runId is unsafe (caller should surface to user).
+ *
+ * Existence: the run directory must already exist (guard with hasRunDir if
+ * you want an unknown-run check; appendGuidance itself creates the dir for
+ * robustness, but callers in chat-session.ts should guard first for UX).
+ */
+export declare function appendGuidance(projectRoot: string, runId: string, text: string): Promise<void>;
+/**
+ * Drain pending (unconsumed) guidance entries for a runId.
+ *
+ * Reads all lines, collects the text of entries where consumed !== true,
+ * then atomically rewrites the file with ALL entries marked consumed:true
+ * (temp-file + rename, mirrors run-state.ts:41-52).
+ *
+ * Returns the drained texts in order.
+ * Missing file → returns [] (never throws — safe to call on every pipeline sprint).
+ * Second drain → returns [] (all entries already marked consumed).
+ */
+export declare function drainGuidance(projectRoot: string, runId: string): Promise<string[]>;
+//# sourceMappingURL=guidance.d.ts.map

package/dist/state/guidance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guidance.d.ts","sourceRoot":"","sources":["../../src/state/guidance.ts"],"names":[],"mappings":"AAyCA;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CASlD;AAID;;;;GAIG;AACH,wBAAsB,SAAS,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAOpF;AAID;;;;;;;;;GASG;AACH,wBAAsB,cAAc,CAClC,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,IAAI,CAAC,CAcf;AAID;;;;;;;;;;GAUG;AACH,wBAAsB,aAAa,CACjC,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,MAAM,EAAE,CAAC,CA+CnB"}

package/dist/state/guidance.js

@@ -0,0 +1,144 @@
+// ── guidance.ts ───────────────────────────────────────────────────────
+//
+// Disk-persistence helpers for the runId-keyed guidance channel.
+//
+// Layout: .bober/runs/<runId>/guidance.jsonl
+// One JSON object per line: { ts: string, text: string, consumed: boolean }
+//
+// Every drain rewrite is atomic via temp-file + rename
+// (mirrors src/state/run-state.ts:41-52 atomic write pattern).
+import { readFile, writeFile, appendFile, rename, access } from "node:fs/promises";
+import { constants } from "node:fs";
+import { randomBytes } from "node:crypto";
+import { join } from "node:path";
+import { ensureDir } from "./helpers.js";
+// ── Path helpers ──────────────────────────────────────────────────────
+function runsRoot(projectRoot) {
+    return join(projectRoot, ".bober", "runs");
+}
+function runDir(projectRoot, runId) {
+    return join(runsRoot(projectRoot), runId);
+}
+function guidancePath(projectRoot, runId) {
+    return join(runDir(projectRoot, runId), "guidance.jsonl");
+}
+// ── Path-traversal guard ──────────────────────────────────────────────
+/**
+ * Validate that a runId is a safe path segment.
+ * Rejects empty strings, strings containing path separators (/ or \),
+ * strings containing '..', and absolute paths.
+ * This is a security guard: a malicious runId must never escape .bober/runs.
+ */
+export function safeSegment(runId) {
+    if (!runId)
+        return false;
+    if (runId.includes("/"))
+        return false;
+    if (runId.includes("\\"))
+        return false;
+    if (runId.includes(".."))
+        return false;
+    if (runId.startsWith("."))
+        return false;
+    // Reject if it looks like an absolute path (Unix or Windows)
+    if (runId.startsWith("/") || /^[A-Za-z]:[/\\]/.test(runId))
+        return false;
+    return true;
+}
+// ── Existence guard ───────────────────────────────────────────────────
+/**
+ * Check whether the run directory exists for the given runId.
+ * Returns false if not found — never throws.
+ * Mirrors approval-state.ts:pendingExists.
+ */
+export async function hasRunDir(projectRoot, runId) {
+    try {
+        await access(runDir(projectRoot, runId), constants.R_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+// ── Append ────────────────────────────────────────────────────────────
+/**
+ * Append a guidance entry to .bober/runs/<runId>/guidance.jsonl.
+ *
+ * Security: validates runId is a safe path segment BEFORE building any path.
+ * Throws with a clear message if runId is unsafe (caller should surface to user).
+ *
+ * Existence: the run directory must already exist (guard with hasRunDir if
+ * you want an unknown-run check; appendGuidance itself creates the dir for
+ * robustness, but callers in chat-session.ts should guard first for UX).
+ */
+export async function appendGuidance(projectRoot, runId, text) {
+    if (!safeSegment(runId)) {
+        throw new Error(`Invalid runId "${runId}": must be a safe path segment (no path separators, no '..').`);
+    }
+    await ensureDir(runDir(projectRoot, runId));
+    const entry = {
+        ts: new Date().toISOString(),
+        text,
+        consumed: false,
+    };
+    // appendFile is safe for JSONL: each call writes exactly one complete line.
+    await appendFile(guidancePath(projectRoot, runId), JSON.stringify(entry) + "\n", "utf-8");
+}
+// ── Drain ─────────────────────────────────────────────────────────────
+/**
+ * Drain pending (unconsumed) guidance entries for a runId.
+ *
+ * Reads all lines, collects the text of entries where consumed !== true,
+ * then atomically rewrites the file with ALL entries marked consumed:true
+ * (temp-file + rename, mirrors run-state.ts:41-52).
+ *
+ * Returns the drained texts in order.
+ * Missing file → returns [] (never throws — safe to call on every pipeline sprint).
+ * Second drain → returns [] (all entries already marked consumed).
+ */
+export async function drainGuidance(projectRoot, runId) {
+    const filePath = guidancePath(projectRoot, runId);
+    let raw;
+    try {
+        raw = await readFile(filePath, "utf-8");
+    }
+    catch {
+        // File does not exist or is unreadable — return empty (no-op)
+        return [];
+    }
+    const lines = raw.split("\n").filter((l) => l.trim() !== "");
+    if (lines.length === 0)
+        return [];
+    const entries = [];
+    const drained = [];
+    for (const line of lines) {
+        try {
+            const entry = JSON.parse(line);
+            if (entry.consumed !== true) {
+                drained.push(entry.text);
+            }
+            entries.push({ ...entry, consumed: true });
+        }
+        catch {
+            // Skip malformed lines — do not lose other entries
+        }
+    }
+    if (drained.length === 0) {
+        // Nothing unconsumed — still rewrite atomically to normalize the file
+        // (all entries stay consumed:true from previous drain)
+        const allConsumed = entries.map((e) => JSON.stringify(e)).join("\n") + "\n";
+        const rnd = randomBytes(4).toString("hex");
+        const tmp = `${filePath}.${process.pid}.${Date.now()}.${rnd}.tmp`;
+        await writeFile(tmp, allConsumed, { encoding: "utf-8", mode: 0o600 });
+        await rename(tmp, filePath);
+        return [];
+    }
+    // Atomically rewrite all entries as consumed
+    const rewritten = entries.map((e) => JSON.stringify(e)).join("\n") + "\n";
+    const rnd = randomBytes(4).toString("hex");
+    const tmp = `${filePath}.${process.pid}.${Date.now()}.${rnd}.tmp`;
+    await writeFile(tmp, rewritten, { encoding: "utf-8", mode: 0o600 });
+    await rename(tmp, filePath);
+    return drained;
+}
+//# sourceMappingURL=guidance.js.map

package/dist/state/guidance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"guidance.js","sourceRoot":"","sources":["../../src/state/guidance.ts"],"names":[],"mappings":"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"}

package/dist/state/history.d.ts

@@ -13,13 +13,13 @@ export declare const HistoryEntrySchema: z.ZodObject<{
     details: Record<string, unknown>;
     timestamp: string;
     event: string;
-    phase: "evaluating" | "failed" | "init" | "planning" | "curating" | "generating" | "rework" | "complete";
+    phase: "complete" | "failed" | "init" | "planning" | "curating" | "generating" | "evaluating" | "rework";
     sprintId?: string | undefined;
 }, {
     details: Record<string, unknown>;
     timestamp: string;
     event: string;
-    phase: "evaluating" | "failed" | "init" | "planning" | "curating" | "generating" | "rework" | "complete";
+    phase: "complete" | "failed" | "init" | "planning" | "curating" | "generating" | "evaluating" | "rework";
     sprintId?: string | undefined;
 }>;
 export type HistoryEntry = z.infer<typeof HistoryEntrySchema>;

package/dist/state/index.d.ts

@@ -1,4 +1,4 @@
-export { saveContract, loadContract, listContracts, updateContract, } from "./sprint-state.js";
+export { saveContract, loadContract, listContracts, updateContract, clearContractsForSpec, } from "./sprint-state.js";
 export { saveSpec, loadSpec, loadLatestSpec, listSpecs, } from "./plan-state.js";
 export { PhaseSchema, HistoryEntrySchema, type Phase, type HistoryEntry, appendHistory, loadHistory, loadRecentHistory, updateProgress, } from "./history.js";
 export { saveResearch, readResearch, listResearch, } from "./research-state.js";

package/dist/state/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/state/index.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,aAAa,EACb,cAAc,GACf,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,QAAQ,EACR,QAAQ,EACR,cAAc,EACd,SAAS,GACV,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAEL,WAAW,EACX,kBAAkB,EAElB,KAAK,KAAK,EACV,KAAK,YAAY,EAEjB,aAAa,EACb,WAAW,EACX,iBAAiB,EACjB,cAAc,GACf,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,YAAY,GACb,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,UAAU,EACV,UAAU,GACX,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,WAAW,EACX,WAAW,GACZ,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,OAAO,EACP,QAAQ,EACR,iBAAiB,GAClB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,aAAa,GACd,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,UAAU,EACV,UAAU,EACV,WAAW,GACZ,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,WAAW,EACX,WAAW,EACX,WAAW,EACX,oBAAoB,EACpB,YAAY,EACZ,YAAY,EACZ,aAAa,EACb,aAAa,EACb,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,kBAAkB,GACxB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,aAAa,EACb,YAAY,EACZ,iBAAiB,EACjB,qBAAqB,GACtB,MAAM,gBAAgB,CAAC;AAKxB;;;GAGG;AACH,wBAAsB,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAOvE"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/state/index.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,aAAa,EACb,cAAc,EACd,qBAAqB,GACtB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,QAAQ,EACR,QAAQ,EACR,cAAc,EACd,SAAS,GACV,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAEL,WAAW,EACX,kBAAkB,EAElB,KAAK,KAAK,EACV,KAAK,YAAY,EAEjB,aAAa,EACb,WAAW,EACX,iBAAiB,EACjB,cAAc,GACf,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,YAAY,GACb,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,UAAU,EACV,UAAU,GACX,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,WAAW,EACX,WAAW,GACZ,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,OAAO,EACP,QAAQ,EACR,iBAAiB,GAClB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,aAAa,GACd,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,UAAU,EACV,UAAU,EACV,WAAW,GACZ,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,WAAW,EACX,WAAW,EACX,WAAW,EACX,oBAAoB,EACpB,YAAY,EACZ,YAAY,EACZ,aAAa,EACb,aAAa,EACb,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,kBAAkB,GACxB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,aAAa,EACb,YAAY,EACZ,iBAAiB,EACjB,qBAAqB,GACtB,MAAM,gBAAgB,CAAC;AAKxB;;;GAGG;AACH,wBAAsB,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAOvE"}

package/dist/state/index.js

@@ -1,6 +1,6 @@
 import { join } from "node:path";
 import { ensureDir } from "./helpers.js";
-export { saveContract, loadContract, listContracts, updateContract, } from "./sprint-state.js";
+export { saveContract, loadContract, listContracts, updateContract, clearContractsForSpec, } from "./sprint-state.js";
 export { saveSpec, loadSpec, loadLatestSpec, listSpecs, } from "./plan-state.js";
 export { 
 // Zod schemas

package/dist/state/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/state/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAEzC,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,aAAa,EACb,cAAc,GACf,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,QAAQ,EACR,QAAQ,EACR,cAAc,EACd,SAAS,GACV,MAAM,iBAAiB,CAAC;AAEzB,OAAO;AACL,cAAc;AACd,WAAW,EACX,kBAAkB;AAIlB,YAAY;AACZ,aAAa,EACb,WAAW,EACX,iBAAiB,EACjB,cAAc,GACf,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,YAAY,GACb,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,UAAU,EACV,UAAU,GACX,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,WAAW,EACX,WAAW,GACZ,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,OAAO,EACP,QAAQ,EACR,iBAAiB,GAClB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,aAAa,GACd,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,UAAU,EACV,UAAU,EACV,WAAW,GACZ,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,WAAW,EACX,WAAW,EACX,WAAW,EACX,oBAAoB,EACpB,YAAY,EACZ,YAAY,EACZ,aAAa,EACb,aAAa,GAKd,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,aAAa,EACb,YAAY,EACZ,iBAAiB,EACjB,qBAAqB,GACtB,MAAM,gBAAgB,CAAC;AAExB,MAAM,SAAS,GAAG,QAAQ,CAAC;AAC3B,MAAM,OAAO,GAAG,CAAC,WAAW,EAAE,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,UAAU,EAAE,cAAc,EAAE,WAAW,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,EAAE,QAAQ,CAAU,CAAC;AAE1J;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,WAAmB;IACtD,MAAM,SAAS,GAAG,IAAI,CAAC,WAAW,EAAE,SAAS,CAAC,CAAC;IAC/C,MAAM,SAAS,CAAC,SAAS,CAAC,CAAC;IAE3B,KAAK,MAAM,GAAG,IAAI,OAAO,EAAE,CAAC;QAC1B,MAAM,SAAS,CAAC,IAAI,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC,CAAC;IACxC,CAAC;AACH,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/state/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAEzC,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,aAAa,EACb,cAAc,EACd,qBAAqB,GACtB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,QAAQ,EACR,QAAQ,EACR,cAAc,EACd,SAAS,GACV,MAAM,iBAAiB,CAAC;AAEzB,OAAO;AACL,cAAc;AACd,WAAW,EACX,kBAAkB;AAIlB,YAAY;AACZ,aAAa,EACb,WAAW,EACX,iBAAiB,EACjB,cAAc,GACf,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,YAAY,GACb,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,UAAU,EACV,UAAU,GACX,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,WAAW,EACX,WAAW,GACZ,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,OAAO,EACP,QAAQ,EACR,iBAAiB,GAClB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,aAAa,GACd,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,UAAU,EACV,UAAU,EACV,WAAW,GACZ,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,WAAW,EACX,WAAW,EACX,WAAW,EACX,oBAAoB,EACpB,YAAY,EACZ,YAAY,EACZ,aAAa,EACb,aAAa,GAKd,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,aAAa,EACb,YAAY,EACZ,iBAAiB,EACjB,qBAAqB,GACtB,MAAM,gBAAgB,CAAC;AAExB,MAAM,SAAS,GAAG,QAAQ,CAAC;AAC3B,MAAM,OAAO,GAAG,CAAC,WAAW,EAAE,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,UAAU,EAAE,cAAc,EAAE,WAAW,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,EAAE,QAAQ,CAAU,CAAC;AAE1J;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,WAAmB;IACtD,MAAM,SAAS,GAAG,IAAI,CAAC,WAAW,EAAE,SAAS,CAAC,CAAC;IAC/C,MAAM,SAAS,CAAC,SAAS,CAAC,CAAC;IAE3B,KAAK,MAAM,GAAG,IAAI,OAAO,EAAE,CAAC;QAC1B,MAAM,SAAS,CAAC,IAAI,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC,CAAC;IACxC,CAAC;AACH,CAAC"}

package/dist/state/memory.d.ts

@@ -1,4 +1,36 @@
 import { z } from "zod";
+/**
+ * Resolve the memory directory path for the given namespace.
+ *
+ * Mapping rule (centralized here — do NOT duplicate in callers):
+ *   namespace undefined | "" | "programming"  →  .bober/memory/       (current path, no subdir)
+ *   any other value                            →  .bober/memory/<ns>/
+ *
+ * The programming sentinel ("") comes from Sprint 1's built-in team (registry.ts:66).
+ * Values are constrained to ^[a-z0-9_-]+$ by the Sprint 1 schema regex, so no
+ * path-traversal sanitization is needed here (schema already guards config inputs).
+ */
+export declare function memoryDir(projectRoot: string, namespace?: string): string;
+export declare function lessonPath(projectRoot: string, lessonId: string, namespace?: string): string;
+export declare function indexPath(projectRoot: string, namespace?: string): string;
+export declare function quarantinePath(projectRoot: string, namespace?: string): string;
+/**
+ * Move lessonId lines from INDEX.md to QUARANTINE.md (line-level rewrite).
+ *
+ * - Reads INDEX.md and partitions non-blank lines: those whose second token
+ *   (the lessonId) is in `quarantinedIds` are moved; the rest stay.
+ * - Rewrites INDEX.md with the kept lines.
+ * - Appends the moved lines to QUARANTINE.md (creating it if absent) with a
+ *   deterministic provenance block: `<!-- quarantined: <reason> @ <now> -->`.
+ * - NEVER touches per-lesson <lessonId>.md files.
+ *
+ * @param projectRoot - Absolute project root containing .bober/
+ * @param quarantinedIds - Set of lessonIds to move out of INDEX.md
+ * @param reason - Human-readable reason (e.g. "decay" | "conflict")
+ * @param now - ISO 8601 wall-clock, injected by the CLI handler
+ * @param namespace - Optional memory namespace
+ */
+export declare function rewriteIndexForQuarantine(projectRoot: string, quarantinedIds: Set<string>, reason: string, now: string, namespace?: string): Promise<void>;
 export declare const LessonEntrySchema: z.ZodObject<{
     lessonId: z.ZodString;
     createdAt: z.ZodString;
@@ -9,21 +41,21 @@ export declare const LessonEntrySchema: z.ZodObject<{
     severity: z.ZodEnum<["info", "warn", "high"]>;
     sourceEntryRefs: z.ZodArray<z.ZodString, "many">;
 }, "strip", z.ZodTypeAny, {
-    severity: "info" | "high" | "warn";
-    summary: string;
-    category: string;
-    createdAt: string;
     lessonId: string;
+    createdAt: string;
+    category: string;
     tags: string[];
+    summary: string;
     occurrences: number;
+    severity: "info" | "warn" | "high";
     sourceEntryRefs: string[];
 }, {
-    severity: "info" | "high" | "warn";
-    summary: string;
-    category: string;
-    createdAt: string;
     lessonId: string;
+    createdAt: string;
+    category: string;
+    summary: string;
     occurrences: number;
+    severity: "info" | "warn" | "high";
     sourceEntryRefs: string[];
     tags?: string[] | undefined;
 }>;
@@ -42,7 +74,7 @@ export interface LessonIndexRecord {
  * Upserts exactly one INDEX.md line for this lessonId (replace if exists, else append).
  * Throws if the lesson fails schema validation (sourceEntryRefs must be non-empty).
  */
-export declare function appendLesson(projectRoot: string, lesson: LessonEntry): Promise<void>;
+export declare function appendLesson(projectRoot: string, lesson: LessonEntry, namespace?: string): Promise<void>;
 /**
  * Load at most `limit` lesson index records from INDEX.md.
  * Never opens individual lesson files — parses only INDEX.md.
@@ -50,11 +82,11 @@ export declare function appendLesson(projectRoot: string, lesson: LessonEntry):
  */
 export declare function loadLessonIndex(projectRoot: string, { limit }: {
     limit: number;
-}): Promise<LessonIndexRecord[]>;
+}, namespace?: string): Promise<LessonIndexRecord[]>;
 /**
  * Load a single lesson by ID from its <lessonId>.md file.
  * Parses front-matter and validates against LessonEntrySchema.
  * Throws a descriptive error if the file does not exist or fails validation.
  */
-export declare function loadLesson(projectRoot: string, lessonId: string): Promise<LessonEntry>;
+export declare function loadLesson(projectRoot: string, lessonId: string, namespace?: string): Promise<LessonEntry>;
 //# sourceMappingURL=memory.d.ts.map

package/dist/state/memory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../../src/state/memory.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AA0BxB,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;EAS5B,CAAC;AAEH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAE5D,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,cAAc,EAAE,MAAM,CAAC;CACxB;AA6ID;;;;;GAKG;AACH,wBAAsB,YAAY,CAChC,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,IAAI,CAAC,CAkCf;AAID;;;;GAIG;AACH,wBAAsB,eAAe,CACnC,WAAW,EAAE,MAAM,EACnB,EAAE,KAAK,EAAE,EAAE;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,GAC3B,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAoB9B;AAED;;;;GAIG;AACH,wBAAsB,UAAU,CAC9B,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,WAAW,CAAC,CAkCtB"}
+{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../../src/state/memory.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAaxB;;;;;;;;;;GAUG;AACH,wBAAgB,SAAS,CAAC,WAAW,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAKzE;AAID,wBAAgB,UAAU,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAE5F;AAED,wBAAgB,SAAS,CAAC,WAAW,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAEzE;AAED,wBAAgB,cAAc,CAAC,WAAW,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAE9E;AAID;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,yBAAyB,CAC7C,WAAW,EAAE,MAAM,EACnB,cAAc,EAAE,GAAG,CAAC,MAAM,CAAC,EAC3B,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,MAAM,EACX,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,IAAI,CAAC,CAoDf;AAID,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;EAS5B,CAAC;AAEH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAE5D,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,cAAc,EAAE,MAAM,CAAC;CACxB;AA6ID;;;;;GAKG;AACH,wBAAsB,YAAY,CAChC,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,WAAW,EACnB,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,IAAI,CAAC,CAkCf;AAID;;;;GAIG;AACH,wBAAsB,eAAe,CACnC,WAAW,EAAE,MAAM,EACnB,EAAE,KAAK,EAAE,EAAE;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,EAC5B,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAoB9B;AAED;;;;GAIG;AACH,wBAAsB,UAAU,CAC9B,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAChB,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,WAAW,CAAC,CAkCtB"}