agent-bober 0.17.0 → 0.18.0

package/dist/orchestrator/memory/fact-retrieve.js

@@ -0,0 +1,117 @@
+/**
+ * PURE deterministic, STORE-ONLY retrieval of relevant project facts for the planner.
+ *
+ * Opens the FactStore once, reads active facts for the requested scope, then
+ * performs all ranking in memory (pure). Mirrors the retrieve.ts pattern for lessons.
+ *
+ * PURE beyond the single store open/read/close — no network, no Date.now(), no LLM.
+ */
+import { FactStore, factsDbPath, ensureFactsDir } from "../../state/facts.js";
+// ── Constants ─────────────────────────────────────────────────────────
+/** Default number of facts to return. */
+const DEFAULT_TOP_K = 5;
+/** Default character budget for the serialized planner block. */
+const DEFAULT_CHAR_BUDGET = 1200;
+// ── Helpers ───────────────────────────────────────────────────────────
+/**
+ * Tokenize a string into lowercase alphanumeric tokens.
+ * COPIED verbatim from retrieve.ts:30-35 (not exported there).
+ * Splits on any non-alphanumeric character and filters empty tokens.
+ */
+function tokenize(s) {
+    return s
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter((t) => t.length > 0);
+}
+/**
+ * Score a FactRecord against a set of lowercased keyword tokens.
+ * Counts shared tokens across subject, predicate, and value.
+ * Returns 0 if there is no overlap.
+ */
+function scoreFact(record, keywordTokens) {
+    if (keywordTokens.size === 0)
+        return 0;
+    const recordTokens = new Set([
+        ...tokenize(record.subject),
+        ...tokenize(record.predicate),
+        ...tokenize(record.value),
+    ]);
+    let count = 0;
+    for (const t of keywordTokens) {
+        if (recordTokens.has(t)) {
+            count++;
+        }
+    }
+    return count;
+}
+// ── Core ──────────────────────────────────────────────────────────────
+/**
+ * Load and rank at most `topK` active facts from the store that are relevant
+ * to the given `keywords` and `scope`.
+ *
+ * ONE store open/read/close, then pure ranking. Scope isolation is enforced by
+ * the SQL WHERE clause in FactStore.getActiveFacts(scope) — facts in scope A
+ * NEVER surface when querying scope B.
+ *
+ * Scoring: deterministic token-overlap between lowercased keyword tokens and
+ * each record's subject + predicate + value tokens.
+ * Sort: score DESC, then id ASC (byte-stable tiebreak, mirrors retrieve.ts:103).
+ *
+ * Design note: when keywords is empty, keywordTokens.size === 0, scoreFact
+ * returns 0 for all records, and the score > 0 filter yields an empty result.
+ * This matches retrieve.ts behaviour. Project facts are few and always written
+ * with known predicates, so callers should pass relevant keywords (e.g. from
+ * the user prompt) to surface them.
+ *
+ * @param projectRoot - Absolute path to the project root containing .bober/
+ * @param scope       - Fact scope (e.g. "" for default/programming team)
+ * @param keywords    - Keywords to rank against (e.g. from the user prompt)
+ * @param options     - topK cap and optional namespace (selects DB file location)
+ */
+export async function retrieveRelevantFacts(projectRoot, scope, keywords, { topK = DEFAULT_TOP_K, namespace, } = {}) {
+    await ensureFactsDir(projectRoot, namespace);
+    const store = new FactStore(factsDbPath(projectRoot, namespace));
+    try {
+        // Scope-isolated by SQL WHERE scope = ? AND t_invalidated IS NULL
+        const records = store.getActiveFacts(scope);
+        const keywordTokens = new Set(keywords.flatMap(tokenize));
+        const scored = records
+            .map((r) => ({ r, score: scoreFact(r, keywordTokens) }))
+            .filter((x) => x.score > 0); // non-matching keyword → empty (mirrors retrieve.ts:96)
+        // Sort: score DESC, then id ASC (byte-stable final tiebreak)
+        scored.sort((a, b) => b.score - a.score || // 1. token overlap (DOMINANT)
+            a.r.id.localeCompare(b.r.id));
+        return scored.slice(0, topK).map((x) => x.r);
+    }
+    finally {
+        store.close();
+    }
+}
+/**
+ * Render a compact planner context block from an array of FactRecord values.
+ *
+ * Mirrors serializeLessonsForPlanner (retrieve.ts:122-144):
+ *   - Empty input → ""
+ *   - Header line + one "- subject/predicate: value" line per fact
+ *   - Hard charBudget slice (output length is GUARANTEED ≤ charBudget)
+ *
+ * @param records    - Already-ranked records (from retrieveRelevantFacts)
+ * @param options    - charBudget: hard character limit (default DEFAULT_CHAR_BUDGET)
+ * @returns Compact string block, at most charBudget characters
+ */
+export function serializeFactsForContext(records, { charBudget = DEFAULT_CHAR_BUDGET } = {}) {
+    if (records.length === 0) {
+        return "";
+    }
+    const lines = [
+        "## Project facts (durable semantic memory)",
+        "",
+        ...records.map((r) => `- ${r.subject}/${r.predicate}: ${r.value}`),
+        "",
+    ];
+    const block = lines.join("\n");
+    // Hard truncation to charBudget (sc-5-5 guarantee — never exceed budget)
+    return block.slice(0, charBudget);
+}
+//# sourceMappingURL=fact-retrieve.js.map

package/dist/orchestrator/memory/fact-retrieve.js.map

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

package/dist/orchestrator/memory/hygiene.d.ts

@@ -0,0 +1,66 @@
+/**
+ * PURE deterministic lesson hygiene: decay-based pruning + conflict quarantine.
+ *
+ * PURE — the clock is never read here; `now` is injected by the CLI handler
+ * (mirrors reconcileFact's { now } pattern at reconcile.ts:54). Operates
+ * ONLY on the fields each record carries; the CLI assembles recency input (createdAt)
+ * by reading per-lesson files and passing it in via PrunableLesson.createdAt.
+ *
+ * Conflict detection: DETERMINISTIC — two lessons sharing the same contradiction key
+ * (category root + discriminator tag) with opposing polarity markers are BOTH moved
+ * to quarantine. No LLM.
+ *
+ * Decay: lessons below `minOccurrences` that are also older than `maxAgeMs` are
+ * quarantined. Missing createdAt is treated as "maximally stale" (decays immediately
+ * when occurrences are below threshold), which is conservative and documented here
+ * as a deliberate choice — prefer to quarantine an unknown-age low-occurrence lesson
+ * rather than silently keep it forever.
+ */
+import type { LessonIndexRecord } from "../../state/memory.js";
+/** Default age threshold for decay: 30 days in milliseconds. */
+export declare const THIRTY_DAYS_MS: number;
+/** A LessonIndexRecord enriched with CLI-derived recency proxy (ISO createdAt). */
+export interface PrunableLesson extends LessonIndexRecord {
+    /** ISO 8601 createdAt, assembled by the CLI from the per-lesson .md file. May be absent. */
+    createdAt?: string;
+}
+export interface PruneOptions {
+    /** Injected ISO wall-clock — NEVER read inside this module. */
+    now: string;
+    /**
+     * Lessons with occurrences strictly below this value AND older than maxAgeMs
+     * are quarantined as decayed. Default: 2.
+     */
+    minOccurrences?: number;
+    /**
+     * Age threshold in milliseconds. A lesson is considered stale when
+     * (now - createdAt) > maxAgeMs. Default: 30 days.
+     */
+    maxAgeMs?: number;
+}
+export interface PruneResult {
+    /** Lessons retained in INDEX.md. Sorted by lessonId ASC for byte-stability. */
+    kept: PrunableLesson[];
+    /** Lessons to be moved to QUARANTINE.md. Sorted by lessonId ASC for byte-stability. */
+    quarantined: PrunableLesson[];
+}
+/**
+ * Partition lessons into kept vs. quarantined.
+ *
+ * Phase 1 (conflict detection): identifies deterministically contradictory pairs.
+ *   A pair is contradictory when both records share the same contradiction key
+ *   (category root + discriminator tag) AND carry opposing polarity markers
+ *   (one "keep"-marked, one "avoid"-marked). BOTH are quarantined.
+ *
+ * Phase 2 (decay): for remaining records, quarantines those below `minOccurrences`
+ *   that are also stale (createdAt older than maxAgeMs, or createdAt absent).
+ *
+ * Both output arrays are sorted by lessonId ASC for byte-identical repeated runs.
+ *
+ * @param records - Enriched lesson records (with optional createdAt from CLI)
+ * @param opts.now - ISO 8601 wall-clock, injected — never read inside
+ * @param opts.minOccurrences - Below-threshold occurrence count (default 2)
+ * @param opts.maxAgeMs - Staleness threshold in ms (default 30 days)
+ */
+export declare function pruneLessons(records: PrunableLesson[], { now, minOccurrences, maxAgeMs }: PruneOptions): PruneResult;
+//# sourceMappingURL=hygiene.d.ts.map

package/dist/orchestrator/memory/hygiene.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hygiene.d.ts","sourceRoot":"","sources":["../../../src/orchestrator/memory/hygiene.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAI/D,gEAAgE;AAChE,eAAO,MAAM,cAAc,QAA2B,CAAC;AAQvD,mFAAmF;AACnF,MAAM,WAAW,cAAe,SAAQ,iBAAiB;IACvD,4FAA4F;IAC5F,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,YAAY;IAC3B,+DAA+D;IAC/D,GAAG,EAAE,MAAM,CAAC;IACZ;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,WAAW;IAC1B,+EAA+E;IAC/E,IAAI,EAAE,cAAc,EAAE,CAAC;IACvB,uFAAuF;IACvF,WAAW,EAAE,cAAc,EAAE,CAAC;CAC/B;AAkDD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,cAAc,EAAE,EACzB,EAAE,GAAG,EAAE,cAAkB,EAAE,QAAyB,EAAE,EAAE,YAAY,GACnE,WAAW,CAsEb"}

package/dist/orchestrator/memory/hygiene.js

@@ -0,0 +1,153 @@
+/**
+ * PURE deterministic lesson hygiene: decay-based pruning + conflict quarantine.
+ *
+ * PURE — the clock is never read here; `now` is injected by the CLI handler
+ * (mirrors reconcileFact's { now } pattern at reconcile.ts:54). Operates
+ * ONLY on the fields each record carries; the CLI assembles recency input (createdAt)
+ * by reading per-lesson files and passing it in via PrunableLesson.createdAt.
+ *
+ * Conflict detection: DETERMINISTIC — two lessons sharing the same contradiction key
+ * (category root + discriminator tag) with opposing polarity markers are BOTH moved
+ * to quarantine. No LLM.
+ *
+ * Decay: lessons below `minOccurrences` that are also older than `maxAgeMs` are
+ * quarantined. Missing createdAt is treated as "maximally stale" (decays immediately
+ * when occurrences are below threshold), which is conservative and documented here
+ * as a deliberate choice — prefer to quarantine an unknown-age low-occurrence lesson
+ * rather than silently keep it forever.
+ */
+// ── Constants ────────────────────────────────────────────────────────────────
+/** Default age threshold for decay: 30 days in milliseconds. */
+export const THIRTY_DAYS_MS = 30 * 24 * 60 * 60 * 1000;
+/** Polarity markers for conflict detection (keep vs. avoid). */
+const KEEP_MARKERS = new Set(["keep", "stable", "pass", "trusted"]);
+const AVOID_MARKERS = new Set(["avoid", "fragile", "fail", "untrusted"]);
+// ── Helpers ──────────────────────────────────────────────────────────────────
+/**
+ * Derive the category root from a category string (substring before the first ":").
+ * e.g. "eval-strategy-failure:unit-test" → "eval-strategy-failure"
+ *      "sprint-rework" → "sprint-rework"
+ */
+function categoryRoot(category) {
+    const idx = category.indexOf(":");
+    return idx === -1 ? category : category.slice(0, idx);
+}
+/**
+ * Extract the first discriminator tag from a tag list.
+ * Priority: sprintId: > strategy: > verificationMethod:
+ * Falls back to the first tag present, or empty string.
+ */
+function discriminatorTag(tags) {
+    for (const prefix of ["sprintId:", "strategy:", "verificationMethod:"]) {
+        const found = tags.find((t) => t.startsWith(prefix));
+        if (found !== undefined)
+            return found;
+    }
+    return tags[0] ?? "";
+}
+/**
+ * Extract the polarity marker from a tag list.
+ * Returns "keep", "avoid", or "neutral" based on the first matching tag.
+ */
+function polarityOf(tags) {
+    for (const tag of tags) {
+        const bare = tag.toLowerCase();
+        if (KEEP_MARKERS.has(bare))
+            return "keep";
+        if (AVOID_MARKERS.has(bare))
+            return "avoid";
+    }
+    return "neutral";
+}
+/**
+ * Build the contradiction key for conflict detection.
+ * Two records with the same key and opposing polarity (keep vs. avoid) are conflicts.
+ */
+function contradictionKey(record) {
+    return `${categoryRoot(record.category)}|${discriminatorTag(record.tags)}`;
+}
+// ── Core ─────────────────────────────────────────────────────────────────────
+/**
+ * Partition lessons into kept vs. quarantined.
+ *
+ * Phase 1 (conflict detection): identifies deterministically contradictory pairs.
+ *   A pair is contradictory when both records share the same contradiction key
+ *   (category root + discriminator tag) AND carry opposing polarity markers
+ *   (one "keep"-marked, one "avoid"-marked). BOTH are quarantined.
+ *
+ * Phase 2 (decay): for remaining records, quarantines those below `minOccurrences`
+ *   that are also stale (createdAt older than maxAgeMs, or createdAt absent).
+ *
+ * Both output arrays are sorted by lessonId ASC for byte-identical repeated runs.
+ *
+ * @param records - Enriched lesson records (with optional createdAt from CLI)
+ * @param opts.now - ISO 8601 wall-clock, injected — never read inside
+ * @param opts.minOccurrences - Below-threshold occurrence count (default 2)
+ * @param opts.maxAgeMs - Staleness threshold in ms (default 30 days)
+ */
+export function pruneLessons(records, { now, minOccurrences = 2, maxAgeMs = THIRTY_DAYS_MS }) {
+    const nowMs = Date.parse(now);
+    // ── Phase 1: conflict detection ─────────────────────────────────────────
+    // Group by contradiction key, collecting polarity.
+    const byKey = new Map();
+    for (const rec of records) {
+        const key = contradictionKey(rec);
+        let bucket = byKey.get(key);
+        if (bucket === undefined) {
+            bucket = { keeps: [], avoids: [] };
+            byKey.set(key, bucket);
+        }
+        const polarity = polarityOf(rec.tags);
+        if (polarity === "keep") {
+            bucket.keeps.push(rec);
+        }
+        else if (polarity === "avoid") {
+            bucket.avoids.push(rec);
+        }
+        // "neutral" polarity: the record is bucketed but will not trigger a conflict on its own
+    }
+    // A conflict fires when a key has BOTH keep-marked AND avoid-marked records.
+    const conflictIds = new Set();
+    for (const [, bucket] of byKey) {
+        if (bucket.keeps.length > 0 && bucket.avoids.length > 0) {
+            for (const r of [...bucket.keeps, ...bucket.avoids]) {
+                conflictIds.add(r.lessonId);
+            }
+        }
+    }
+    // ── Phase 2: decay ───────────────────────────────────────────────────────
+    const decayIds = new Set();
+    for (const rec of records) {
+        if (conflictIds.has(rec.lessonId))
+            continue; // already quarantined by conflict
+        if (rec.occurrences >= minOccurrences)
+            continue; // well-established, keep
+        // Below minOccurrences: quarantine if stale (or no age info → maximally stale).
+        if (rec.createdAt === undefined) {
+            // No age info = unknown = treat as maximally stale → quarantine
+            decayIds.add(rec.lessonId);
+            continue;
+        }
+        const ageMs = nowMs - Date.parse(rec.createdAt);
+        if (ageMs > maxAgeMs) {
+            decayIds.add(rec.lessonId);
+        }
+    }
+    // ── Partition ────────────────────────────────────────────────────────────
+    const quarantinedSet = new Set([...conflictIds, ...decayIds]);
+    const kept = [];
+    const quarantined = [];
+    for (const rec of records) {
+        if (quarantinedSet.has(rec.lessonId)) {
+            quarantined.push(rec);
+        }
+        else {
+            kept.push(rec);
+        }
+    }
+    // Sort both arrays by lessonId for deterministic, byte-identical output.
+    kept.sort((a, b) => a.lessonId.localeCompare(b.lessonId));
+    quarantined.sort((a, b) => a.lessonId.localeCompare(b.lessonId));
+    return { kept, quarantined };
+}
+//# sourceMappingURL=hygiene.js.map

package/dist/orchestrator/memory/hygiene.js.map

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

package/dist/orchestrator/memory/reconcile.d.ts

@@ -0,0 +1,47 @@
+/**
+ * PURE deterministic reconcile-on-write for semantic facts.
+ *
+ * PURE — never reads the clock (now is injected), never calls createClient,
+ * no network access, no Date.now(), no side effects beyond the injected store.
+ * The injected FactJudge is the ONLY async/LLM surface and is consulted ONLY
+ * on a deterministic normalized-key collision (the ambiguity branch).
+ * Exact-match NOOP/UPDATE/ADD never touch the judge or the network.
+ */
+import type { FactStore, FactInput } from "../../state/facts.js";
+import type { FactJudge } from "./fact-judge.js";
+export type ReconcileAction = "add" | "update" | "delete" | "noop";
+/**
+ * Reconcile an incoming fact against the active state in the store.
+ *
+ * Algorithm:
+ * 1. Query getActiveFacts(scope, subject, predicate) — exact key, active-only.
+ * 2. Exact match with SAME value → NOOP.
+ * 3. Exact match with DIFFERENT value → UPDATE:
+ *    supersedeFact(old.id, now, incoming.tValid) then insertFact(incoming).
+ * 4. No exact match → AMBIGUITY check via normalizeKey over all active facts in scope.
+ *    a. Collision AND judge provided → judge.resolve(incoming, candidate) → apply.
+ *    b. Collision but NO judge → deterministic ADD fallback.
+ *    c. No collision → ADD.
+ * 5. DELETE = supersedeFact(candidate.id, now, incoming.tValid) without inserting incoming.
+ *
+ * @param store - The FactStore to read from and write to.
+ * @param incoming - The incoming fact input (validated by insertFact on the ADD path).
+ * @param opts.judge - Optional LLM-backed judge for ambiguity resolution.
+ * @param opts.now - ISO 8601 wall-clock timestamp (record-time); NEVER read inside.
+ */
+export declare function reconcileFact(store: FactStore, incoming: FactInput, { judge, now }: {
+    judge?: FactJudge;
+    now: string;
+}): Promise<ReconcileAction>;
+/**
+ * Reconcile-then-write a fact. Wall-clock `now` is injected by the caller —
+ * this function never reads the clock (mirrors the store's purity contract).
+ *
+ * The `judge` is optional; when absent the exact-match UPDATE/NOOP paths run
+ * deterministically and ambiguous collisions fall back to ADD.
+ */
+export declare function writeFact(store: FactStore, incoming: FactInput, opts: {
+    judge?: FactJudge;
+    now: string;
+}): Promise<ReconcileAction>;
+//# sourceMappingURL=reconcile.d.ts.map

package/dist/orchestrator/memory/reconcile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reconcile.d.ts","sourceRoot":"","sources":["../../../src/orchestrator/memory/reconcile.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACjE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAIjD,MAAM,MAAM,eAAe,GAAG,KAAK,GAAG,QAAQ,GAAG,QAAQ,GAAG,MAAM,CAAC;AAgBnE;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,aAAa,CACjC,KAAK,EAAE,SAAS,EAChB,QAAQ,EAAE,SAAS,EACnB,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE;IAAE,KAAK,CAAC,EAAE,SAAS,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GACjD,OAAO,CAAC,eAAe,CAAC,CA8C1B;AAwCD;;;;;;GAMG;AACH,wBAAsB,SAAS,CAC7B,KAAK,EAAE,SAAS,EAChB,QAAQ,EAAE,SAAS,EACnB,IAAI,EAAE;IAAE,KAAK,CAAC,EAAE,SAAS,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GACvC,OAAO,CAAC,eAAe,CAAC,CAE1B"}

package/dist/orchestrator/memory/reconcile.js

@@ -0,0 +1,116 @@
+/**
+ * PURE deterministic reconcile-on-write for semantic facts.
+ *
+ * PURE — never reads the clock (now is injected), never calls createClient,
+ * no network access, no Date.now(), no side effects beyond the injected store.
+ * The injected FactJudge is the ONLY async/LLM surface and is consulted ONLY
+ * on a deterministic normalized-key collision (the ambiguity branch).
+ * Exact-match NOOP/UPDATE/ADD never touch the judge or the network.
+ */
+// ── Helpers ──────────────────────────────────────────────────────────────
+/**
+ * Normalize a subject+predicate pair into a collision key.
+ * Lowercase + strip non-alphanumeric characters — mirrors tokenize() in retrieve.ts:30-35.
+ * Private to this module; do not import from retrieve.ts (it is not exported).
+ */
+function normalizeKey(subject, predicate) {
+    const norm = (s) => s.toLowerCase().replace(/[^a-z0-9]+/g, "");
+    return `${norm(subject)}|${norm(predicate)}`;
+}
+// ── Core ──────────────────────────────────────────────────────────────────
+/**
+ * Reconcile an incoming fact against the active state in the store.
+ *
+ * Algorithm:
+ * 1. Query getActiveFacts(scope, subject, predicate) — exact key, active-only.
+ * 2. Exact match with SAME value → NOOP.
+ * 3. Exact match with DIFFERENT value → UPDATE:
+ *    supersedeFact(old.id, now, incoming.tValid) then insertFact(incoming).
+ * 4. No exact match → AMBIGUITY check via normalizeKey over all active facts in scope.
+ *    a. Collision AND judge provided → judge.resolve(incoming, candidate) → apply.
+ *    b. Collision but NO judge → deterministic ADD fallback.
+ *    c. No collision → ADD.
+ * 5. DELETE = supersedeFact(candidate.id, now, incoming.tValid) without inserting incoming.
+ *
+ * @param store - The FactStore to read from and write to.
+ * @param incoming - The incoming fact input (validated by insertFact on the ADD path).
+ * @param opts.judge - Optional LLM-backed judge for ambiguity resolution.
+ * @param opts.now - ISO 8601 wall-clock timestamp (record-time); NEVER read inside.
+ */
+export async function reconcileFact(store, incoming, { judge, now }) {
+    // ── Step 1: Exact-key lookup (active only) ────────────────────────────
+    const exactMatches = store.getActiveFacts(incoming.scope, incoming.subject, incoming.predicate);
+    // ── Step 2: Same value → NOOP ─────────────────────────────────────────
+    if (exactMatches.length > 0) {
+        const same = exactMatches.find((r) => r.value === incoming.value);
+        if (same !== undefined) {
+            return "noop";
+        }
+        // ── Step 3: Different value → UPDATE (supersede) ─────────────────────
+        // Supersede every matching active row (normally only one, but be safe).
+        for (const old of exactMatches) {
+            // Set BOTH t_invalid (world-time = incoming tValid) AND t_invalidated (record-time = now)
+            store.supersedeFact(old.id, now, incoming.tValid);
+        }
+        store.insertFact(incoming);
+        return "update";
+    }
+    // ── Step 4: No exact match → Ambiguity check ─────────────────────────
+    const incomingKey = normalizeKey(incoming.subject, incoming.predicate);
+    const allActive = store.getActiveFacts(incoming.scope);
+    const candidate = allActive.find((r) => normalizeKey(r.subject, r.predicate) === incomingKey);
+    if (candidate !== undefined) {
+        // ── Step 4a: Collision AND judge → delegate ───────────────────────
+        if (judge !== undefined) {
+            const action = await judge.resolve(incoming, candidate);
+            return applyJudgeDecision(store, incoming, candidate, action, now);
+        }
+        // ── Step 4b: Collision but NO judge → deterministic ADD fallback ──
+        store.insertFact(incoming);
+        return "add";
+    }
+    // ── Step 4c: No collision → ADD ───────────────────────────────────────
+    store.insertFact(incoming);
+    return "add";
+}
+/**
+ * Apply a judge's decision to the store.
+ * DELETE = supersede candidate only; no insertFact.
+ */
+function applyJudgeDecision(store, incoming, candidate, action, now) {
+    switch (action) {
+        case "add":
+            store.insertFact(incoming);
+            return "add";
+        case "update":
+            store.supersedeFact(candidate.id, now, incoming.tValid);
+            store.insertFact(incoming);
+            return "update";
+        case "delete":
+            store.supersedeFact(candidate.id, now, incoming.tValid);
+            return "delete";
+        case "noop":
+            return "noop";
+        default: {
+            // Exhaustive check — if judge returns unknown action, fall back to ADD
+            store.insertFact(incoming);
+            return "add";
+        }
+    }
+}
+// ── writeFact ─────────────────────────────────────────────────────────────
+//
+// Thin wrapper that calls reconcileFact. Lives here (not in facts.ts) to
+// avoid a state→orchestrator import cycle at runtime.
+// The CLI and future consumers import writeFact from this module.
+/**
+ * Reconcile-then-write a fact. Wall-clock `now` is injected by the caller —
+ * this function never reads the clock (mirrors the store's purity contract).
+ *
+ * The `judge` is optional; when absent the exact-match UPDATE/NOOP paths run
+ * deterministically and ambiguous collisions fall back to ADD.
+ */
+export async function writeFact(store, incoming, opts) {
+    return reconcileFact(store, incoming, opts);
+}
+//# sourceMappingURL=reconcile.js.map

package/dist/orchestrator/memory/reconcile.js.map

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

package/dist/orchestrator/memory/retrieve.d.ts

@@ -12,8 +12,9 @@ import type { LessonIndexRecord } from "../../state/memory.js";
  * to the given `keywords`.
  *
  * Scoring is deterministic token-overlap between the lowercased keyword tokens
- * and each record's tags + category + summarySnippet. Ties break by lessonId
- * (ASC lexicographic) for byte-stable output.
+ * and each record's tags + category + summarySnippet. When overlap scores tie,
+ * records with higher occurrences rank above lower-occurrence records.
+ * Final tiebreak is by lessonId ASC (lexicographic) for byte-stable output.
  *
  * A non-matching keyword set (no overlap with any record) yields an empty result.
  *
@@ -22,9 +23,10 @@ import type { LessonIndexRecord } from "../../state/memory.js";
  * @param options     - topK cap (default 5) and optional charBudget (ignored here; passed to serializer)
  * @returns At most topK records sorted by relevance (descending), then lessonId (ascending)
  */
-export declare function retrieveRelevantLessons(projectRoot: string, keywords: string[], { topK, charBudget: _charBudget, }?: {
+export declare function retrieveRelevantLessons(projectRoot: string, keywords: string[], { topK, charBudget: _charBudget, namespace, }?: {
     topK?: number;
     charBudget?: number;
+    namespace?: string;
 }): Promise<LessonIndexRecord[]>;
 /**
  * Render a compact planner context block from an array of LessonIndexRecord values.

package/dist/orchestrator/memory/retrieve.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"retrieve.d.ts","sourceRoot":"","sources":["../../../src/orchestrator/memory/retrieve.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAsD/D;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,uBAAuB,CAC3C,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAAE,EAClB,EACE,IAAoB,EACpB,UAAU,EAAE,WAAW,GACxB,GAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAO,GAC7C,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAe9B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,iBAAiB,EAAE,EAC5B,EAAE,UAAgC,EAAE,GAAE;IAAE,UAAU,CAAC,EAAE,MAAM,CAAA;CAAO,GACjE,MAAM,CAmBR"}
+{"version":3,"file":"retrieve.d.ts","sourceRoot":"","sources":["../../../src/orchestrator/memory/retrieve.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAsD/D;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,uBAAuB,CAC3C,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAAE,EAClB,EACE,IAAoB,EACpB,UAAU,EAAE,WAAW,EACvB,SAAS,GACV,GAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAO,GACjE,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAkB9B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,iBAAiB,EAAE,EAC5B,EAAE,UAAgC,EAAE,GAAE;IAAE,UAAU,CAAC,EAAE,MAAM,CAAA;CAAO,GACjE,MAAM,CAmBR"}

package/dist/orchestrator/memory/retrieve.js

@@ -52,8 +52,9 @@ function scoreRecord(record, keywordTokens) {
  * to the given `keywords`.
  *
  * Scoring is deterministic token-overlap between the lowercased keyword tokens
- * and each record's tags + category + summarySnippet. Ties break by lessonId
- * (ASC lexicographic) for byte-stable output.
+ * and each record's tags + category + summarySnippet. When overlap scores tie,
+ * records with higher occurrences rank above lower-occurrence records.
+ * Final tiebreak is by lessonId ASC (lexicographic) for byte-stable output.
  *
  * A non-matching keyword set (no overlap with any record) yields an empty result.
  *
@@ -62,14 +63,16 @@ function scoreRecord(record, keywordTokens) {
  * @param options     - topK cap (default 5) and optional charBudget (ignored here; passed to serializer)
  * @returns At most topK records sorted by relevance (descending), then lessonId (ascending)
  */
-export async function retrieveRelevantLessons(projectRoot, keywords, { topK = DEFAULT_TOP_K, charBudget: _charBudget, } = {}) {
-    const records = await loadLessonIndex(projectRoot, { limit: INDEX_LOAD_LIMIT });
+export async function retrieveRelevantLessons(projectRoot, keywords, { topK = DEFAULT_TOP_K, charBudget: _charBudget, namespace, } = {}) {
+    const records = await loadLessonIndex(projectRoot, { limit: INDEX_LOAD_LIMIT }, namespace);
     const keywordTokens = new Set(keywords.flatMap(tokenize));
     const scored = records
         .map((r) => ({ r, score: scoreRecord(r, keywordTokens) }))
         .filter((x) => x.score > 0); // C1: non-matching keyword -> empty
-    // Sort: score DESC, then lessonId ASC for stable tiebreak
-    scored.sort((a, b) => b.score - a.score || a.r.lessonId.localeCompare(b.r.lessonId));
+    // Sort: score DESC, then occurrences DESC (tiebreak booster), then lessonId ASC (byte-stable)
+    scored.sort((a, b) => b.score - a.score || // 1. token overlap (DOMINANT)
+        b.r.occurrences - a.r.occurrences || // 2. higher occurrences win on ties (sc-3-2)
+        a.r.lessonId.localeCompare(b.r.lessonId));
     return scored.slice(0, topK).map((x) => x.r);
 }
 /**

package/dist/orchestrator/memory/retrieve.js.map

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