@ijfw/memory-server 1.5.1 → 1.5.3

package/src/memory/reader.js

@@ -22,7 +22,8 @@ const PREVIEW_CHARS = 300;
 /** Parse YAML-style frontmatter (key: value lines between --- fences). */
 function parseFrontmatter(raw) {
   const fm = { title: null, description: null, type: null };
-  const m  = raw.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  const stripped = String(raw).replace(/^/, '').replace(/^\s+/, '');
+  const m  = stripped.match(/^---\r?\n([\s\S]*?)\r?\n---/);
   if (!m) return fm;
   for (const line of m[1].split('\n')) {
     const kv = line.match(/^(\w+):\s*(.+)/);

package/src/memory/search.js

@@ -346,6 +346,108 @@ function rowCount(db) {
   }
 }
 
+// --- Structured provenance helpers -----------------------------------------
+
+/**
+ * Convert a raw FTS row + fileBySource map to a structured provenance object.
+ * Used when opts.format === 'structured'.
+ *
+ * Fields that aren't computed in the existing pipeline are returned as
+ * null / 0 rather than introducing new compute work (Task 28 spec).
+ *
+ * @param {object} row  - raw DB row from searchFts5
+ * @param {Map}    fileBySource
+ * @param {string} rawQuery  - original user query (for whyMatched extraction)
+ * @param {object} db        - open DB handle (for backlink count query)
+ * @returns {object}
+ */
+function ftsRowToStructured(row, fileBySource, rawQuery, db) {
+  const src = row.source || '';
+  const meta = fileBySource.get(src) || null;
+  const source = (meta && meta.path) || src;
+  const text = String(row.body || '');
+  const snip = text.slice(0, 200).replace(/\s+/g, ' ').trim();
+
+  // confidence: bm25 rank is negative (more negative = better). Convert to 0..1.
+  // rank returned from searchFts5 can be 0 or negative; we use the same
+  // score formula as ftsRowToResult (100 - rank) but normalise to 0..1 by
+  // clamping to [0, 100] and dividing.
+  const rawRank = Number(row.rank || 0);
+  const scoreRaw = 100 - rawRank;         // same as ftsRowToResult
+  const confidence = Math.min(1, Math.max(0, scoreRaw / 100));
+
+  // ageDays: created_at is unix ms
+  const createdAt = Number(row.created_at || 0);
+  const ageDays = createdAt > 0
+    ? Math.max(0, (Date.now() - createdAt) / 86400000)
+    : 0;
+
+  // decayFactor: not yet computed in pipeline — return null per spec
+  const decayFactor = null;
+
+  // whyMatched: tokenise the raw query into distinct non-trivial terms
+  const whyMatched = rawQuery
+    .trim()
+    .split(/\s+/)
+    .map(t => t.replace(/['"*()]/g, '').toLowerCase())
+    .filter(t => t.length > 0);
+
+  // backlinkCount: count rows in memory_links where to_target matches source
+  let backlinkCount = 0;
+  if (db && row.id != null) {
+    try {
+      const idStr = String(row.id);
+      const r = db.prepare(
+        'SELECT COUNT(*) AS n FROM memory_links WHERE to_target = ?'
+      ).get(idStr);
+      backlinkCount = r ? Number(r.n) : 0;
+    } catch { /* memory_links may not exist in older dbs */ }
+  }
+
+  return {
+    source,
+    anchor: null,
+    snippet: snip,
+    confidence,
+    ageDays,
+    decayFactor,
+    whyMatched,
+    backlinkCount,
+  };
+}
+
+/**
+ * Convert a hot-linear result to a structured provenance object.
+ * Linear results lack a DB row id so backlinkCount is always 0.
+ *
+ * @param {object} result  - from searchLinear
+ * @param {string} rawQuery
+ * @returns {object}
+ */
+function linearResultToStructured(result, rawQuery) {
+  const scoreRaw = Number(result.score || 0);
+  // Hot-linear score is titleMatches*3 + bodyMatches; normalise loosely to 0..1
+  // by capping at 50 matches (arbitrary but safe)
+  const confidence = Math.min(1, scoreRaw / 50);
+
+  const whyMatched = rawQuery
+    .trim()
+    .split(/\s+/)
+    .map(t => t.replace(/['"*()]/g, '').toLowerCase())
+    .filter(t => t.length > 0);
+
+  return {
+    source: result.path || result.relpath || '',
+    anchor: null,
+    snippet: result.snippet || '',
+    confidence,
+    ageDays: 0,
+    decayFactor: null,
+    whyMatched,
+    backlinkCount: 0,
+  };
+}
+
 // --- Public API -------------------------------------------------------------
 
 /**
@@ -365,30 +467,41 @@ function rowCount(db) {
  *   the hot-linear fallback is unfiltered (D1 does not yet write tier
  *   metadata into the markdown surface).
  *
+ * format option (Task 28 — structured provenance):
+ *   opts.format === 'structured' returns an Array of provenance objects:
+ *     [{source, anchor, snippet, confidence, ageDays, decayFactor,
+ *       whyMatched, backlinkCount}]
+ *   Default (no format) returns Array<{path,relpath,title,snippet,score,
+ *   tier_semantic}> — byte-identical to pre-Task-28 behaviour.
+ *
  * @param {string} q
  * @param {Array<{path,relpath,title,preview}>} files
  * @param {number} limit
  * @param {object|undefined} options
- * @returns {Array<{path,relpath,title,snippet,score,tier_semantic}>}
+ * @returns {Array<{path,relpath,title,snippet,score,tier_semantic}>|Array<provenance>}
  */
 export function searchMemory(q, files, limit = MAX_RESULTS, options) {
   if (!q || !q.trim() || !files || files.length === 0) return [];
 
-  // Normalise options. Allow undefined / { tier_semantic, include_stale } /
-  // a bare string (treated as the tier_semantic value) for ergonomic call
-  // sites. include_stale defaults to false -- D4 GA-B2 retrieval guard.
+  // Normalise options. Allow undefined / { tier_semantic, include_stale,
+  // format } / a bare string (treated as the tier_semantic value) for
+  // ergonomic call sites. include_stale defaults to false -- D4 GA-B2
+  // retrieval guard. format === 'structured' enables Task-28 provenance.
   let tier_semantic;
   let include_stale = false;
+  let format;
   if (typeof options === 'string') {
     tier_semantic = options;
   } else if (options && typeof options === 'object') {
     tier_semantic = options.tier_semantic;
     include_stale = options.include_stale === true;
+    format = options.format;
   }
 
   const { expanded, synonym_matches, applied } = expandQuery(q);
 
   let warmHits = null;
+  let warmRawRows = null;  // preserved for structured format (Task 28)
   let warmEmpty = false;
   let db = null;
 
@@ -424,6 +537,11 @@ export function searchMemory(q, files, limit = MAX_RESULTS, options) {
             if (f.relpath) fileBySource.set(f.relpath, f);
             if (f.path) fileBySource.set(f.path, f);
           }
+          if (format === 'structured') {
+            // Task 28: map raw rows to provenance objects while db is still open
+            // (backlinkCount query needs the handle)
+            warmRawRows = rows.map(r => ftsRowToStructured(r, fileBySource, q, db));
+          }
           warmHits = rows.map(r => ftsRowToResult(r, fileBySource));
         } else {
           warmEmpty = true;
@@ -432,31 +550,41 @@ export function searchMemory(q, files, limit = MAX_RESULTS, options) {
     }
   } catch {
     warmHits = null;
+    warmRawRows = null;
   } finally {
     if (db) { try { db.close(); } catch { /* ignore */ } }
   }
 
   let results;
   if (warmHits && warmHits.length > 0) {
-    results = warmHits.slice(0, limit);
+    results = format === 'structured'
+      ? warmRawRows.slice(0, limit)
+      : warmHits.slice(0, limit);
   } else if (tier_semantic) {
     // Tier filter active and warm tier has no matches -- the hot-linear
     // tier doesn't carry tier metadata so it can't honour the filter.
     // Returning [] here keeps the contract honest ("only matching tier").
     results = [];
   } else {
-    results = searchLinear(q, files, limit);
+    const linearResults = searchLinear(q, files, limit);
+    results = format === 'structured'
+      ? linearResults.map(r => linearResultToStructured(r, q))
+      : linearResults;
   }
 
-  Object.defineProperty(results, 'synonym_matches', {
-    value: applied ? synonym_matches : {},
-    enumerable: false,
-  });
-  Object.defineProperty(results, 'tier', {
-    value: warmHits && warmHits.length > 0
-      ? 'warm-fts5'
-      : (warmEmpty ? 'hot-linear-empty-fts5' : 'hot-linear'),
-    enumerable: false,
-  });
+  // Structured results are plain arrays — no non-enumerable decorations needed.
+  // Legacy path: attach non-enumerable metadata as before (byte-identical).
+  if (format !== 'structured') {
+    Object.defineProperty(results, 'synonym_matches', {
+      value: applied ? synonym_matches : {},
+      enumerable: false,
+    });
+    Object.defineProperty(results, 'tier', {
+      value: warmHits && warmHits.length > 0
+        ? 'warm-fts5'
+        : (warmEmpty ? 'hot-linear-empty-fts5' : 'hot-linear'),
+      enumerable: false,
+    });
+  }
   return results;
 }

package/src/memory/temporal.js

@@ -333,7 +333,13 @@ export function storeFactBitemporal(db, fact, now) {
     const factId = insertFact(db, f, t);
     return { invalidated, factId };
   });
-  const r = txn(fact, ts);
+  // F2.7: .immediate() issues BEGIN IMMEDIATE — see brain-handler conflict.resolve.
+  // Sister writers (conflict.resolve) hold IMMEDIATE locks; if we ran DEFERRED here
+  // we would hit SQLITE_BUSY when upgrading SHARED→RESERVED on the first write
+  // inside the txn body and the user's memory write would silently drop (or
+  // throw SQLITE_BUSY at the caller). Lock-mode alignment with sister writers
+  // is what makes the cross-connection contract honest.
+  const r = txn.immediate(fact, ts);
   return { invalidated: r.invalidated, factId: r.factId, deduped: false };
 }
 
@@ -513,6 +519,38 @@ export function applyDecayToFacts(rows, now, options = {}) {
   });
 }
 
+/**
+ * getHistoryWindow -- bounded slice of facts about (subject[, predicate]) for
+ * the wiki compiler's "history" section. Returns at most `limit` rows ordered
+ * by valid_from DESC. When rollupOlder is true and rows.length === limit,
+ * also returns an `older` rollup of facts beyond the window so the wiki page
+ * can show "Older: 55 events between 2024-03-01 and 2025-06-30" without
+ * bloating the page.
+ *
+ * Trident F-B2 protection: prevents page-bloat for hot subjects with hundreds
+ * of facts.
+ */
+export function getHistoryWindow(db, subject, predicate, { limit = 50, since = null, rollupOlder = true } = {}) {
+  const params = [subject];
+  let where = 'subject = ?';
+  if (predicate != null) { where += ' AND predicate = ?'; params.push(predicate); }
+  if (since) { where += ' AND valid_from >= ?'; params.push(since); }
+  const rows = db.prepare(
+    `SELECT id, predicate, object, valid_from, valid_to, memory_id, source, confidence
+     FROM facts WHERE ${where} ORDER BY valid_from DESC LIMIT ?`
+  ).all(...params, limit);
+  let older = null;
+  if (rollupOlder && rows.length === limit) {
+    const earliest = rows[rows.length - 1].valid_from;
+    const r = db.prepare(
+      `SELECT COUNT(*) AS count, MIN(valid_from) AS fromIso, MAX(valid_from) AS toIso
+       FROM facts WHERE ${where} AND valid_from < ?`
+    ).get(...params, earliest);
+    if (r.count > 0) older = r;
+  }
+  return { rows, older };
+}
+
 export default {
   openTemporalDb,
   openTemporalDbSync,
@@ -524,6 +562,7 @@ export default {
   getHistory,
   getAllFactsWithWindows,
   applyDecayToFacts,
+  getHistoryWindow,
   DECAY_HALFLIFE_DAYS,
   DECAY_HALFLIFE_SESSION_DAYS,
 };

package/src/orchestrator/agents-md-blackboard.js

@@ -46,12 +46,17 @@
  * AGENTS.md hiccup — see `wave-state.js#checkpointWave`).
  */
 
-import { join } from 'node:path';
+import { join, resolve as pathResolve, dirname as pathDirname } from 'node:path';
 
 import { withFsLock, lockPathFor } from '../fs-lock.js';
 import { readWaveState } from './wave-state.js';
 import { mergeFile, MergeBlockAwareError } from './merge-block-aware.js';
 import { query } from './state-sdk.js';
+import {
+  selectDisciplineTemplate,
+  detectProjectTypeFromRepo,
+} from './discipline-selector.js';
+import { validateSafeRepoPath } from '../brain/path-guard.js';
 
 /**
  * Render the BLACKBOARD marker-block payload from a wave's STATE.md
@@ -93,8 +98,21 @@ export async function populateBlackboardBlock(waveId, projectRoot) {
   const state = await readWaveState(waveId, projectRoot);
   if (!state) return { ok: false, reason: 'no-state' };
 
+  // Defense-in-depth: refuse to operate at a filesystem root (e.g. '/' on
+  // POSIX, 'C:\\' on Windows). validateSafeRepoPath alone accepts these
+  // because '/AGENTS.md' is technically "inside" '/'; OS permissions would
+  // then catch the actual write, but the failure mode would be 'merge-error'
+  // not 'unsafe-path'. We want a clean structured rejection upstream of any
+  // I/O attempt. Test at integration/test-discipline-integration.js:189.
+  const resolvedRoot = pathResolve(projectRoot || '.');
+  if (resolvedRoot === pathDirname(resolvedRoot)) {
+    return { ok: false, reason: 'unsafe-path', error: 'projectRoot is a filesystem root' };
+  }
+
   const payload = renderBlackboardPayload(waveId, state);
   const agentsMdPath = join(projectRoot, 'AGENTS.md');
+  const guard = validateSafeRepoPath(projectRoot, agentsMdPath);
+  if (!guard.ok) return { ok: false, reason: 'unsafe-path', error: guard.error };
   const lockPath = lockPathFor(agentsMdPath);
 
   let mergeResult;
@@ -150,3 +168,98 @@ export async function populateBlackboardBlock(waveId, projectRoot) {
 
   return { ok: true };
 }
+
+/**
+ * Populate the DISCIPLINE marker block in `<projectRoot>/AGENTS.md` with the
+ * project-appropriate discipline template body. Held under the §3 #8 AGENTS.md
+ * lock; in-process (no spawn). Best-effort SDK event emit after lock release.
+ *
+ * If `projectType` is not supplied, `detectProjectTypeFromRepo(projectRoot)`
+ * is called to infer it. For `unknown` / `mixed` types the DISCIPLINE block
+ * is written with an empty body (marker present, body empty) -- this is the
+ * correct state, not an error.
+ *
+ * Return shapes:
+ *   `{ ok: true }`                               -- wrote AGENTS.md
+ *   `{ ok: false, reason: 'merge-error', error }` -- merger threw
+ *   `{ ok: false, reason: 'template-missing', error }` -- template file absent
+ *
+ * @param {string} projectRoot
+ * @param {string} [projectType]  optional; inferred when absent
+ * @param {{waveId?: string}} [opts]  optional; waveId defaults to 'system'
+ * @returns {Promise<{ok: boolean, reason?: string, error?: string}>}
+ */
+export async function populateDisciplineBlock(projectRoot, projectType, opts = {}) {
+  const waveId = opts.waveId || 'system';
+  const type = projectType !== undefined && projectType !== null
+    ? String(projectType)
+    : detectProjectTypeFromRepo(projectRoot);
+
+  let content;
+  try {
+    content = selectDisciplineTemplate(type);
+  } catch (err) {
+    return {
+      ok: false,
+      reason: 'template-missing',
+      error: String(err.message || err),
+    };
+  }
+
+  // Defense-in-depth: same filesystem-root rejection as populateBlackboardBlock.
+  const resolvedRoot = pathResolve(projectRoot || '.');
+  if (resolvedRoot === pathDirname(resolvedRoot)) {
+    return { ok: false, reason: 'unsafe-path', error: 'projectRoot is a filesystem root' };
+  }
+
+  const agentsMdPath = join(projectRoot, 'AGENTS.md');
+  const guard = validateSafeRepoPath(projectRoot, agentsMdPath);
+  if (!guard.ok) return { ok: false, reason: 'unsafe-path', error: guard.error };
+  const lockPath = lockPathFor(agentsMdPath);
+
+  let mergeResult;
+  let mergeError = null;
+  try {
+    mergeResult = await withFsLock(lockPath, async () => mergeFile(
+      agentsMdPath,
+      [{ block: 'DISCIPLINE', content }],
+    ));
+  } catch (err) {
+    mergeError = err;
+  }
+
+  if (mergeError) {
+    const code = mergeError instanceof MergeBlockAwareError ? mergeError.code : null;
+    return {
+      ok: false,
+      reason: code === 'ERR_TEMPLATE_MISSING' ? 'template-missing' : 'merge-error',
+      error: String(mergeError.message || mergeError),
+    };
+  }
+
+  // SDK-routed observability event -- fire-and-forget AFTER lock release.
+  // Mirrors the agents-md.blackboard.set emit pattern above.
+  try {
+    await query('event.emit', {
+      subagentId: 'parent',
+      waveId,
+      eventType: 'agents-md.discipline.set',
+      data: {
+        path: mergeResult?.path ?? agentsMdPath,
+        bytes: mergeResult?.bytes ?? 0,
+        seeded: !!mergeResult?.seeded,
+        project_type: type,
+      },
+      dedupKey: `agents-md.discipline.set:${waveId}:${type}`,
+    }, { projectRoot, subagentId: 'parent' });
+  } catch {
+    // Observability is best-effort; never demote a successful AGENTS.md
+    // rewrite because the event tap had a hiccup.
+  }
+
+  // Forward noop flag from the short-circuit so callers can detect idempotent
+  // calls (5B-L2-05). When mergeResult.noop is true the file was unchanged.
+  const result = { ok: true };
+  if (mergeResult?.noop) result.noop = true;
+  return result;
+}