@jaimevalasek/aioson 1.16.0 → 1.17.3

package/src/neural-chain-git-ingest.js

@@ -0,0 +1,280 @@
+'use strict';
+
+/**
+ * Neural Chain — git co-edit ingest helper.
+ *
+ * Implements the `git_co_edit` edge source for `chain_edges`. Co-edit pairs
+ * are derived from `git log --pretty=format:%H|%cI --name-only -n N HEAD`
+ * bounded to the last DEFAULT_MAX_COMMITS commits, filtered to the last
+ * WINDOW_DAYS days, with `.aioson/` framework state excluded and mega-commits
+ * (> MAX_FILES_PER_COMMIT files) skipped to bound the N² pair explosion.
+ *
+ * Confidence per BR-NC-01: `min(1.0, count / CONFIDENCE_SATURATION)`.
+ * Hard cap per BR-NC-08: HARD_CAP_PER_NODE active edges per source_path; oldest
+ * by `last_seen_at` is archived (`end_at = now`) before inserting beyond cap.
+ *
+ * EC-NC-06 (no git history): `runGitIngest` returns `{skipped: true,
+ * reason: 'insufficient_history'}` when `git rev-list --count HEAD` < MIN.
+ *
+ * Idempotent: re-running with the same commit window produces the same active
+ * state (UPSERT on the partial UNIQUE index over active rows).
+ *
+ * Two directional rows are stored per co-edit pair (A→B and B→A) to keep
+ * `chain:audit WHERE source_path = X` queries direct without UNION ALL.
+ *
+ * Internal representation: `Map<source_path, Map<target_path, { count, lastSeen }>>`.
+ * Nested map avoids string-separator ambiguity (file paths may contain any
+ * character including spaces and NUL bytes).
+ */
+
+const fs = require('node:fs');
+const { isUnsafePath } = require('./neural-chain-sanitize');
+const path = require('node:path');
+const { execSync } = require('node:child_process');
+
+const DEFAULT_MAX_COMMITS = 1000;
+const CONFIDENCE_SATURATION = 10;
+const WINDOW_DAYS = 90;
+const MAX_FILES_PER_COMMIT = 50;
+const HARD_CAP_PER_NODE = 10000;
+const MIN_COMMITS_FOR_INGEST = 50;
+const GIT_LOG_MAX_BUFFER = 32 * 1024 * 1024;
+
+function parseGitLog(rawLog) {
+  const commits = [];
+  if (!rawLog || typeof rawLog !== 'string') return commits;
+
+  const lines = rawLog.split(/\r?\n/);
+  let current = null;
+  const headerPattern = /^([0-9a-f]{7,40})\|(.+)$/;
+
+  for (const rawLine of lines) {
+    const line = rawLine.replace(/\s+$/, '');
+    if (!line) {
+      if (current) {
+        commits.push(current);
+        current = null;
+      }
+      continue;
+    }
+
+    const headerMatch = line.match(headerPattern);
+    if (headerMatch) {
+      if (current) commits.push(current);
+      current = {
+        commit_hash: headerMatch[1],
+        committer_date_iso: headerMatch[2],
+        files: []
+      };
+    } else if (current) {
+      current.files.push(line);
+    }
+  }
+  if (current) commits.push(current);
+  return commits;
+}
+
+function bumpPair(bySource, source, target, isoDate) {
+  let inner = bySource.get(source);
+  if (!inner) {
+    inner = new Map();
+    bySource.set(source, inner);
+  }
+  const existing = inner.get(target);
+  if (existing) {
+    existing.count += 1;
+    if (isoDate > existing.lastSeen) existing.lastSeen = isoDate;
+  } else {
+    inner.set(target, { count: 1, lastSeen: isoDate });
+  }
+}
+
+function computeCoEditPairs(commits, { now = new Date() } = {}) {
+  const cutoff = new Date(now.getTime() - WINDOW_DAYS * 24 * 60 * 60 * 1000);
+  const bySource = new Map();
+
+  for (const commit of commits) {
+    const commitDate = new Date(commit.committer_date_iso);
+    if (Number.isNaN(commitDate.getTime()) || commitDate < cutoff) continue;
+
+    // Exclude framework state churn — .aioson/* changes every agent session.
+    // SF-NC-01/02 Layer B — also reject unsafe paths (control chars, oversize,
+    // empty). POSIX allows LF in filenames; git records them as-is. Without
+    // this filter, a crafted commit history could feed the noise-file
+    // injection vector identified in @pentester SF-NC-01.
+    const files = commit.files.filter(
+      (f) =>
+        f &&
+        !f.startsWith('.aioson/') &&
+        !f.startsWith('.aioson\\') &&
+        !isUnsafePath(f)
+    );
+    if (files.length < 2 || files.length > MAX_FILES_PER_COMMIT) continue;
+
+    for (let i = 0; i < files.length; i++) {
+      for (let j = 0; j < files.length; j++) {
+        if (i === j) continue;
+        bumpPair(bySource, files[i], files[j], commit.committer_date_iso);
+      }
+    }
+  }
+
+  return bySource;
+}
+
+function ingestGitCoEditEdges({ db, pairs, now = new Date() }) {
+  if (!db || typeof db.prepare !== 'function') {
+    throw new Error('ingestGitCoEditEdges requires an open better-sqlite3 db handle');
+  }
+
+  const nowIso = now.toISOString();
+  const stats = { upserted: 0, archived: 0, capped_inserts: 0 };
+
+  const upsertStmt = db.prepare(`
+    INSERT INTO chain_edges (source_path, target_path, edge_type, confidence, start_at, last_seen_at, hit_count)
+    VALUES (?, ?, 'git_co_edit', ?, ?, ?, ?)
+    ON CONFLICT(source_path, target_path, edge_type) WHERE end_at IS NULL
+    DO UPDATE SET
+      confidence = excluded.confidence,
+      last_seen_at = excluded.last_seen_at,
+      hit_count = excluded.hit_count
+  `);
+
+  const countActiveStmt = db.prepare(`
+    SELECT count(*) AS c FROM chain_edges
+    WHERE source_path = ? AND end_at IS NULL
+  `);
+
+  const findExistingStmt = db.prepare(`
+    SELECT id FROM chain_edges
+    WHERE source_path = ? AND target_path = ? AND edge_type = 'git_co_edit' AND end_at IS NULL
+  `);
+
+  const findOldestStmt = db.prepare(`
+    SELECT id FROM chain_edges
+    WHERE source_path = ? AND end_at IS NULL
+    ORDER BY last_seen_at ASC LIMIT 1
+  `);
+
+  const archiveStmt = db.prepare(`UPDATE chain_edges SET end_at = ? WHERE id = ?`);
+
+  // Flatten nested Map<source, Map<target, {count, lastSeen}>> into items.
+  const items = [];
+  for (const [source, inner] of pairs.entries()) {
+    if (!inner || typeof inner.entries !== 'function') continue;
+    for (const [target, value] of inner.entries()) {
+      items.push({ source, target, count: value.count, lastSeen: value.lastSeen });
+    }
+  }
+
+  const tx = db.transaction((arr) => {
+    for (const item of arr) {
+      const confidence = Math.min(1.0, item.count / CONFIDENCE_SATURATION);
+
+      // BR-NC-08 hard cap — only enforce when inserting a NEW edge for this source.
+      // Existing-edge updates (re-ingest) don't grow the active set.
+      const existingRow = findExistingStmt.get(item.source, item.target);
+      if (!existingRow) {
+        const { c: activeCount } = countActiveStmt.get(item.source);
+        if (activeCount >= HARD_CAP_PER_NODE) {
+          const oldest = findOldestStmt.get(item.source);
+          if (oldest) {
+            archiveStmt.run(nowIso, oldest.id);
+            stats.archived += 1;
+            stats.capped_inserts += 1;
+          }
+        }
+      }
+
+      upsertStmt.run(item.source, item.target, confidence, nowIso, item.lastSeen, item.count);
+      stats.upserted += 1;
+    }
+  });
+
+  tx(items);
+  return stats;
+}
+
+function getCommitCount(projectDir) {
+  try {
+    const output = execSync('git rev-list --count HEAD', {
+      cwd: projectDir,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe']
+    });
+    const n = parseInt(output.trim(), 10);
+    return Number.isFinite(n) ? n : 0;
+  } catch (_) {
+    return -1;
+  }
+}
+
+function fetchGitLog(projectDir, maxCommits) {
+  return execSync(
+    `git log --pretty=format:%H|%cI --name-only -n ${Number(maxCommits)} HEAD`,
+    {
+      cwd: projectDir,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+      maxBuffer: GIT_LOG_MAX_BUFFER
+    }
+  );
+}
+
+function runGitIngest({
+  db,
+  projectDir,
+  maxCommits = DEFAULT_MAX_COMMITS,
+  now = new Date(),
+  fetchLog = fetchGitLog
+} = {}) {
+  if (!projectDir) {
+    return { skipped: true, reason: 'missing_project_dir' };
+  }
+  if (!fs.existsSync(path.join(projectDir, '.git'))) {
+    return { skipped: true, reason: 'no_git_repo' };
+  }
+
+  const commitCount = getCommitCount(projectDir);
+  if (commitCount < 0) {
+    return { skipped: true, reason: 'git_unavailable' };
+  }
+  if (commitCount < MIN_COMMITS_FOR_INGEST) {
+    return { skipped: true, reason: 'insufficient_history', commit_count: commitCount };
+  }
+
+  let rawLog;
+  try {
+    rawLog = fetchLog(projectDir, maxCommits);
+  } catch (err) {
+    return { skipped: true, reason: 'git_log_failed', error: err && err.message ? err.message : String(err) };
+  }
+
+  const commits = parseGitLog(rawLog);
+  const pairs = computeCoEditPairs(commits, { now });
+  const stats = ingestGitCoEditEdges({ db, pairs, now });
+
+  let pairsCount = 0;
+  for (const inner of pairs.values()) pairsCount += inner.size;
+
+  return {
+    skipped: false,
+    commit_count: commitCount,
+    commits_parsed: commits.length,
+    pairs_computed: pairsCount,
+    ...stats
+  };
+}
+
+module.exports = {
+  parseGitLog,
+  computeCoEditPairs,
+  ingestGitCoEditEdges,
+  runGitIngest,
+  DEFAULT_MAX_COMMITS,
+  CONFIDENCE_SATURATION,
+  WINDOW_DAYS,
+  MAX_FILES_PER_COMMIT,
+  HARD_CAP_PER_NODE,
+  MIN_COMMITS_FOR_INGEST
+};

package/src/neural-chain-migration.js

@@ -0,0 +1,61 @@
+'use strict';
+
+/**
+ * Neural Chain feature — Phase 1 schema migration.
+ *
+ * Adds chain_edges table + 3 indexes to .aioson/runtime/aios.sqlite per
+ * requirements-neural-chain.md § New entities and fields.
+ *
+ * Idempotent (IF NOT EXISTS guards on every step). Safe to call on every
+ * openRuntimeDb invocation. The 4 statements are all O(1) probes when the
+ * schema already exists, so no PRAGMA user_version sentinel is used —
+ * coordination with the existing learning-loop migration's user_version=3
+ * would require a shared versioning table (deferred until multiple features
+ * need migrations).
+ *
+ * Schema invariants enforced here:
+ *   - edge_type ∈ {'git_co_edit', 'agent_event'}     (BR-NC-01 sources)
+ *   - 0.0 ≤ confidence ≤ 1.0                          (BR-NC-01 formula range)
+ *   - hit_count > 0                                   (BR-NC-07 ingest semantics)
+ *   - source_path, target_path, edge_type uniqueness  (active rows only,
+ *     allowing archive flow per BR-NC-08 hard cap enforcement)
+ *
+ * Invariants enforced by application code, not schema:
+ *   - validity-window discipline (start_at always set; end_at NULL in M1)
+ *   - hard cap 10k per source_path node (audit at ingest time)
+ *   - confidence formula and combination (max not sum)
+ */
+
+const STEPS = [
+  `CREATE TABLE IF NOT EXISTS chain_edges (
+     id INTEGER PRIMARY KEY AUTOINCREMENT,
+     source_path TEXT NOT NULL,
+     target_path TEXT NOT NULL,
+     edge_type TEXT NOT NULL CHECK (edge_type IN ('git_co_edit', 'agent_event')),
+     confidence REAL NOT NULL CHECK (confidence >= 0.0 AND confidence <= 1.0),
+     start_at TEXT NOT NULL,
+     end_at TEXT,
+     hit_count INTEGER NOT NULL DEFAULT 1 CHECK (hit_count > 0),
+     last_seen_at TEXT NOT NULL,
+     metadata TEXT
+   )`,
+  `CREATE INDEX IF NOT EXISTS idx_chain_edges_source
+     ON chain_edges(source_path, end_at)`,
+  `CREATE INDEX IF NOT EXISTS idx_chain_edges_target
+     ON chain_edges(target_path, end_at)`,
+  `CREATE UNIQUE INDEX IF NOT EXISTS uniq_chain_active
+     ON chain_edges(source_path, target_path, edge_type)
+     WHERE end_at IS NULL`
+];
+
+function runMigration(db) {
+  if (!db || typeof db.exec !== 'function') {
+    throw new Error('runMigration requires an open better-sqlite3 database handle');
+  }
+
+  for (const stmt of STEPS) {
+    db.exec(stmt);
+  }
+}
+
+module.exports = { runMigration };

package/src/neural-chain-noise-file.js

@@ -0,0 +1,332 @@
+'use strict';
+
+/**
+ * Neural Chain — noise file write / lazy lifecycle (BR-NC-06).
+ *
+ * Produces `.aioson/context/noises/{feature-slug}-{YYYYMMDD-HHMM}.md` with a
+ * YAML frontmatter + body of markdown checkboxes. One file per session in
+ * `guarded` autonomy mode (other modes deferred to Slice 6 threshold rules).
+ *
+ * Lifecycle:
+ *   writeNoiseFile()              — create file with `- [ ]` items.
+ *   readNoiseFileAndRecompute()   — re-parse, count `- [x]`, surface stats.
+ *   maybeDeleteNoiseFile()        — unlink when no pending items remain.
+ *
+ * No file watcher — recompute is lazy, triggered by callers (chain:audit,
+ * @neo activation, agent_done hook). Idempotent unlink covers EC-NC-10.
+ * Item granularity is file-level only (M1 BR-NC-09); `:symbol` deferred to V2.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { isUnsafePath } = require('./neural-chain-sanitize');
+
+const NOISE_DIR_REL = path.join('.aioson', 'context', 'noises');
+
+function formatTimestamp(date) {
+  const yyyy = date.getUTCFullYear();
+  const mm = String(date.getUTCMonth() + 1).padStart(2, '0');
+  const dd = String(date.getUTCDate()).padStart(2, '0');
+  const hh = String(date.getUTCHours()).padStart(2, '0');
+  const min = String(date.getUTCMinutes()).padStart(2, '0');
+  return `${yyyy}${mm}${dd}-${hh}${min}`;
+}
+
+function sanitizeSlug(slug) {
+  if (slug === null || slug === undefined) return 'unspecified';
+  const s = String(slug)
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9-]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+  return s || 'unspecified';
+}
+
+function buildNoiseFilePath({ targetDir, featureSlug, now }) {
+  if (!targetDir || typeof targetDir !== 'string') {
+    throw new Error('buildNoiseFilePath requires targetDir');
+  }
+  const slug = sanitizeSlug(featureSlug);
+  const ts = formatTimestamp(now instanceof Date ? now : new Date());
+  return path.join(targetDir, NOISE_DIR_REL, `${slug}-${ts}.md`);
+}
+
+function serializeItem(item) {
+  const conf =
+    typeof item.confidence === 'number' && Number.isFinite(item.confidence)
+      ? item.confidence.toFixed(2)
+      : String(item.confidence ?? '0.00');
+  const sourceTag = item.source_file ? ` (source: ${item.source_file})` : '';
+  // BR-NC-03: classifier (Slice 6) tags items with `[AUTO-FIXABLE]` or
+  // `[AUTO-FIXABLE-BEST-EFFORT]` so the next agent session can execute them
+  // mechanically per BR-NC-04 handoff TODO contract.
+  const markerTag = item.marker ? ` [${item.marker}]` : '';
+  return `- [ ]${markerTag} ${item.target_path} — ${item.edge_type} ${conf}${sourceTag}`;
+}
+
+function buildContent({ slug, editAtIso, autonomyMode, sourceFiles, items }) {
+  const fm = [
+    '---',
+    `slug: ${slug}`,
+    `edit_at: ${editAtIso}`,
+    `autonomy_mode: ${autonomyMode}`,
+    `source_files: ${JSON.stringify(sourceFiles)}`,
+    `total_items: ${items.length}`,
+    `resolved_items: 0`,
+    '---'
+  ].join('\n');
+  const heading = '\n\n# Neural Chain — Impact Audit\n';
+  const intro =
+    '\nThe edits in this session may have impact on the files listed below. Tick each item once verified or addressed; this file is deleted automatically once all items are resolved.\n';
+  const body =
+    items.length === 0
+      ? '\n*No impacts detected.*\n'
+      : '\n' + items.map(serializeItem).join('\n') + '\n';
+  return fm + heading + intro + body;
+}
+
+function flattenAudits(audits) {
+  const items = [];
+  const sourceFilesSet = new Set();
+  let rejectedCount = 0;
+  for (const audit of audits || []) {
+    if (!audit) continue;
+    // SF-NC-01 Layer A — skip the audit's source_file from the frontmatter
+    // source_files list when it's unsafe (control chars / too long / empty).
+    // Defense in depth: even if Layer B (ingest) is bypassed, the noise
+    // file body must never carry attacker-controlled newlines.
+    if (audit.source_file && !isUnsafePath(audit.source_file)) {
+      sourceFilesSet.add(audit.source_file);
+    }
+    if (!Array.isArray(audit.impacts)) continue;
+    for (const impact of audit.impacts) {
+      if (!impact || !impact.target_path) continue;
+      const targetPath = String(impact.target_path);
+      // SF-NC-01 Layer A — drop the entire item when target_path is unsafe.
+      // The whole row is poisoned; rendering even a sanitized stub leaves the
+      // injection vector partially open. Telemetry-counting the rejection
+      // lives at Layer B (ingest); here we silently filter to keep the
+      // noise file shape coherent.
+      if (isUnsafePath(targetPath)) {
+        rejectedCount += 1;
+        continue;
+      }
+      const sourceFile = audit.source_file && !isUnsafePath(audit.source_file)
+        ? audit.source_file
+        : null;
+      items.push({
+        target_path: targetPath,
+        source_file: sourceFile,
+        edge_type: impact.edge_type ? String(impact.edge_type) : 'unknown',
+        confidence:
+          typeof impact.confidence === 'number' && Number.isFinite(impact.confidence)
+            ? impact.confidence
+            : 0,
+        // Slice 6: classifier may attach `marker` to impacts before passing
+        // them in (BR-NC-02/03). Pass through verbatim — flatten does not
+        // re-classify.
+        marker: impact.marker || null
+      });
+    }
+  }
+  return { items, sourceFiles: Array.from(sourceFilesSet), rejected: rejectedCount };
+}
+
+function writeNoiseFile({
+  targetDir,
+  featureSlug,
+  audits,
+  autonomyMode = 'guarded',
+  now = new Date()
+}) {
+  if (!targetDir || typeof targetDir !== 'string') {
+    throw new Error('writeNoiseFile requires targetDir');
+  }
+  const stamp = now instanceof Date ? now : new Date();
+  const { items, sourceFiles } = flattenAudits(audits);
+  const slug = sanitizeSlug(featureSlug);
+  const filePath = buildNoiseFilePath({ targetDir, featureSlug, now: stamp });
+
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+
+  const content = buildContent({
+    slug,
+    editAtIso: stamp.toISOString(),
+    autonomyMode,
+    sourceFiles,
+    items
+  });
+
+  fs.writeFileSync(filePath, content, 'utf8');
+
+  return {
+    path: filePath,
+    slug,
+    items,
+    total_items: items.length,
+    source_files: sourceFiles
+  };
+}
+
+function parseFrontmatter(text) {
+  if (!text.startsWith('---\n') && !text.startsWith('---\r\n')) {
+    return { ok: false, reason: 'missing_frontmatter', data: null, bodyOffset: 0 };
+  }
+  const lines = text.split(/\r?\n/);
+  let closing = -1;
+  for (let i = 1; i < lines.length; i += 1) {
+    if (lines[i].trim() === '---') {
+      closing = i;
+      break;
+    }
+  }
+  if (closing === -1) {
+    return { ok: false, reason: 'unclosed_frontmatter', data: null, bodyOffset: 0 };
+  }
+
+  const data = {};
+  for (let i = 1; i < closing; i += 1) {
+    const line = lines[i];
+    if (!line.trim() || line.trim().startsWith('#')) continue;
+    const m = line.match(/^([a-zA-Z0-9_]+)\s*:\s*(.*)$/);
+    if (!m) {
+      return {
+        ok: false,
+        reason: 'invalid_line',
+        data: null,
+        bodyOffset: 0,
+        badLine: line
+      };
+    }
+    const key = m[1];
+    const raw = m[2].trim();
+    let val;
+    if (raw === '') {
+      val = '';
+    } else if (raw.startsWith('[') && raw.endsWith(']')) {
+      try {
+        val = JSON.parse(raw);
+      } catch {
+        val = [];
+      }
+    } else if (
+      (raw.startsWith('"') && raw.endsWith('"')) ||
+      (raw.startsWith("'") && raw.endsWith("'"))
+    ) {
+      val = raw.slice(1, -1);
+    } else if (raw === 'true') {
+      val = true;
+    } else if (raw === 'false') {
+      val = false;
+    } else if (/^-?\d+$/.test(raw)) {
+      val = Number(raw);
+    } else if (/^-?\d+\.\d+$/.test(raw)) {
+      val = Number(raw);
+    } else {
+      val = raw;
+    }
+    data[key] = val;
+  }
+
+  const headerText = lines.slice(0, closing + 1).join('\n') + '\n';
+  return { ok: true, data, bodyOffset: headerText.length };
+}
+
+function parseItems(body) {
+  const items = [];
+  const lines = body.split(/\r?\n/);
+  // Optional marker bracket between checkbox and target_path, e.g.:
+  //   - [ ] [AUTO-FIXABLE] src/foo.js — git_co_edit 0.80
+  //   - [x] src/bar.js — agent_event 0.50
+  const re = /^- \[([ xX])\](?: \[([A-Z][A-Z0-9_-]*)\])? (.+?)(?: — (.+))?$/;
+  for (const line of lines) {
+    const m = re.exec(line);
+    if (!m) continue;
+    items.push({
+      checked: m[1] === 'x' || m[1] === 'X',
+      marker: m[2] || null,
+      target_path: m[3].trim(),
+      motivo: m[4] ? m[4].trim() : ''
+    });
+  }
+  return items;
+}
+
+function readNoiseFileAndRecompute({ path: filePath }) {
+  if (!filePath || typeof filePath !== 'string') {
+    throw new Error('readNoiseFileAndRecompute requires path');
+  }
+  let text;
+  try {
+    text = fs.readFileSync(filePath, 'utf8');
+  } catch (err) {
+    if (err && err.code === 'ENOENT') {
+      return {
+        exists: false,
+        frontmatter: null,
+        frontmatterOk: false,
+        frontmatterReason: 'not_found',
+        items: [],
+        allResolved: false,
+        pendingCount: 0,
+        resolvedCount: 0
+      };
+    }
+    throw err;
+  }
+
+  const fm = parseFrontmatter(text);
+  // EC-NC-09: corrupted frontmatter still allows body parsing — readable items preserved.
+  const body = fm.ok ? text.slice(fm.bodyOffset) : text;
+  const items = parseItems(body);
+  const resolved = items.filter((i) => i.checked).length;
+  const pending = items.length - resolved;
+
+  const frontmatter = fm.ok ? { ...fm.data, resolved_items: resolved } : null;
+
+  return {
+    exists: true,
+    frontmatter,
+    frontmatterOk: fm.ok,
+    frontmatterReason: fm.ok ? null : fm.reason,
+    items,
+    allResolved: items.length > 0 && pending === 0,
+    pendingCount: pending,
+    resolvedCount: resolved
+  };
+}
+
+function maybeDeleteNoiseFile({ path: filePath }) {
+  const r = readNoiseFileAndRecompute({ path: filePath });
+  if (!r.exists) {
+    return { deleted: false, reason: 'not_found' };
+  }
+  if (r.pendingCount === 0) {
+    try {
+      fs.unlinkSync(filePath);
+      return {
+        deleted: true,
+        reason: r.items.length === 0 ? 'no_items' : 'all_resolved'
+      };
+    } catch (err) {
+      // EC-NC-10: race between recompute and unlink — idempotent return.
+      if (err && err.code === 'ENOENT') {
+        return { deleted: false, reason: 'already_deleted' };
+      }
+      throw err;
+    }
+  }
+  return { deleted: false, reason: 'pending_items', pendingCount: r.pendingCount };
+}
+
+module.exports = {
+  writeNoiseFile,
+  readNoiseFileAndRecompute,
+  maybeDeleteNoiseFile,
+  buildNoiseFilePath,
+  sanitizeSlug,
+  formatTimestamp,
+  parseFrontmatter,
+  parseItems,
+  NOISE_DIR_REL
+};