sweet-search 2.5.2 → 2.5.3

package/core/incremental-indexing/infrastructure/sparse-gram-delta.mjs

@@ -0,0 +1,335 @@
+/**
+ * Sparse-gram per-file delta overlay (SSGRMIDX v3).
+ *
+ * Plan § 7.6. The cold-build artifact `codebase-sparse-grams.idx` is
+ * immutable; the reconcile path writes per-file changes to
+ * `codebase-sparse-grams.idx.deltas/{epoch}-{seq}.ssgrmdelta` and the
+ * query path mmaps base ∪ deltas.
+ *
+ * Delta record (one per file, one JSON line — easy to parse; the native
+ * mmap-friendly binary form is Phase 6 work). Each record is keyed by
+ * the stable `file_id = xxhash3(canonical_path)` and carries:
+ *
+ *   {
+ *     "fileId":       "<hex>",
+ *     "filePath":     "<relative path>",
+ *     "contentHash":  "<hex>",
+ *     "deleted":      false,
+ *     "symbolMask":   <int>,
+ *     "weightsId":    "<id>",      // must match base artifact's weights id
+ *     "grams":        [ [gramId, freq], ... ]
+ *   }
+ *
+ * The reader unions in two passes:
+ *   1. For each file_id with a newer delta record, mask the base
+ *      postings for that file_id and read the delta record instead.
+ *   2. If `deleted=true`, the file_id is excluded from postings entirely.
+ *
+ * The delta directory grows over time; the watermark scheduler
+ * (`domain/watermark-scheduler.mjs`) triggers compaction when the
+ * `delta_size_ratio` or `delta_segment_count` thresholds cross. Compaction
+ * reads the latest delta record per file, merges with base postings for
+ * unchanged files, and emits a new base under `*.next`.
+ *
+ * Source-file retokenization for unchanged files is **forbidden** by plan
+ * § 7.6: the compactor copies postings, it does not re-gram.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { contentHashSync } from './hashing.mjs';
+import { DEFAULT_SPARSE_GRAM_WEIGHTS_ID } from './manifest.mjs';
+
+export const DELTA_DIR_SUFFIX = '.deltas';
+export const DELTA_FILE_EXT = '.ssgrmdelta';
+/**
+ * Versioned hardcoded common-code bigram-weight table. Plan § 7.6 empty-/
+ * tiny-codebase bootstrap. The actual bigram weights live in the Rust
+ * native crate (`crates/sweet-search-native/src/sparse_gram.rs`); this
+ * module only carries the *identifier* of the fallback table so the
+ * reconciler can stamp deltas with the same `weightsId` the base artifact
+ * used.
+ */
+export const FALLBACK_WEIGHTS_ID = DEFAULT_SPARSE_GRAM_WEIGHTS_ID;
+
+/**
+ * Compute the canonical `file_id` for a path. Plan § 7.6 step 2.
+ *
+ * @param {string} canonicalPath
+ * @returns {string}
+ */
+export function fileIdFor(canonicalPath) {
+  return contentHashSync(String(canonicalPath));
+}
+
+function deltaDirFor(baseArtifactPath) {
+  return baseArtifactPath + DELTA_DIR_SUFFIX;
+}
+
+function deltaSegmentPath(baseArtifactPath, epoch, seq) {
+  return path.join(deltaDirFor(baseArtifactPath), `${epoch}-${seq}${DELTA_FILE_EXT}`);
+}
+
+/**
+ * Append a delta record to the active delta segment. Each call writes one
+ * line of JSON. The reconciler is the single writer; appending is atomic
+ * per call (single `fs.appendFileSync`).
+ *
+ * @param {string} baseArtifactPath  Path to the immutable base sparse-gram artifact.
+ * @param {number} epoch
+ * @param {object} record    `{ fileId, filePath, contentHash, deleted, symbolMask, weightsId, grams }`
+ */
+export function appendDeltaRecord(baseArtifactPath, epoch, record) {
+  if (!Number.isInteger(epoch)) {
+    throw new Error('appendDeltaRecord: epoch must be an integer');
+  }
+  if (!record || !record.fileId) {
+    throw new Error('appendDeltaRecord: record.fileId is required');
+  }
+  const deltaDir = deltaDirFor(baseArtifactPath);
+  fs.mkdirSync(deltaDir, { recursive: true });
+  const filePath = deltaSegmentPath(baseArtifactPath, epoch, 0);
+  const fd = fs.openSync(filePath, 'a');
+  try {
+    fs.writeSync(fd, JSON.stringify(record) + '\n');
+    fs.fsyncSync(fd);
+  } finally {
+    fs.closeSync(fd);
+  }
+  try {
+    const dirFd = fs.openSync(deltaDir, 'r');
+    try { fs.fsyncSync(dirFd); } finally { fs.closeSync(dirFd); }
+  } catch {
+    // Some test/container filesystems reject directory fsync; the data fsync
+    // above is the required durability boundary.
+  }
+}
+
+/**
+ * Enumerate delta segment files (sorted by epoch, then sequence).
+ *
+ * @param {string} baseArtifactPath
+ * @param {{maxEpoch?:number}} [opts]
+ * @returns {Array<{path:string, epoch:number, seq:number}>}
+ */
+export function listDeltaSegments(baseArtifactPath, opts = {}) {
+  const dir = deltaDirFor(baseArtifactPath);
+  if (!fs.existsSync(dir)) return [];
+  const maxEpoch = Number.isInteger(opts.maxEpoch) ? opts.maxEpoch : Infinity;
+  const out = [];
+  for (const name of fs.readdirSync(dir)) {
+    if (!name.endsWith(DELTA_FILE_EXT)) continue;
+    const match = name.match(/^(\d+)-(\d+)\.ssgrmdelta$/);
+    if (!match) continue;
+    const epoch = Number(match[1]);
+    if (epoch > maxEpoch) continue;
+    out.push({
+      path: path.join(dir, name),
+      epoch,
+      seq: Number(match[2]),
+    });
+  }
+  return out.sort((a, b) => (a.epoch - b.epoch) || (a.seq - b.seq));
+}
+
+/**
+ * Read all delta records and resolve them to the latest record per fileId.
+ * Plan § 7.6 step 4: writing the same `(fileId, contentHash)` twice is a
+ * no-op at query merge time; the *last* record wins.
+ *
+ * @param {string} baseArtifactPath
+ * @param {{maxEpoch?:number}} [opts]
+ * @returns {Map<string, {record:object, segmentPath:string, epoch:number}>}
+ */
+export function resolveLatestRecords(baseArtifactPath, opts = {}) {
+  const latest = new Map();
+  for (const seg of listDeltaSegments(baseArtifactPath, opts)) {
+    const raw = fs.readFileSync(seg.path, 'utf-8');
+    for (const line of raw.split('\n')) {
+      const trimmed = line.trim();
+      if (!trimmed) continue;
+      let record;
+      try {
+        record = JSON.parse(trimmed);
+      } catch {
+        continue; // skip torn / corrupt lines; the compactor will rewrite
+      }
+      if (!record.fileId) continue;
+      latest.set(record.fileId, { record, segmentPath: seg.path, epoch: seg.epoch });
+    }
+  }
+  return latest;
+}
+
+/**
+ * Compute the delta-size ratio used by the watermark scheduler.
+ *
+ *   delta_size_ratio = sum(delta file sizes) / (base file size + sum)
+ *
+ * @param {string} baseArtifactPath
+ * @returns {{ratio:number, deltaSegments:number, deltaBytes:number, baseBytes:number}}
+ */
+export function deltaSizeStats(baseArtifactPath) {
+  let deltaBytes = 0;
+  let deltaSegments = 0;
+  for (const seg of listDeltaSegments(baseArtifactPath)) {
+    try {
+      const stat = fs.statSync(seg.path);
+      deltaBytes += stat.size;
+      deltaSegments += 1;
+    } catch {
+      // ignore vanished files
+    }
+  }
+  let baseBytes = 0;
+  if (fs.existsSync(baseArtifactPath)) {
+    baseBytes = fs.statSync(baseArtifactPath).size;
+  }
+  const ratio = deltaBytes / Math.max(1, baseBytes + deltaBytes);
+  return { ratio, deltaSegments, deltaBytes, baseBytes };
+}
+
+/**
+ * Compact the delta directory in place.
+ *
+ * Reads all delta segments, resolves the latest record per fileId, writes
+ * a single new segment that supersedes them, and (by default) deletes the
+ * segments the compaction consumed.
+ *
+ * Naming: the new segment uses `{maxEpoch}-{seq}` with `seq > 0` so it
+ * sorts AFTER any existing `{maxEpoch}-0` segment the reconciler wrote.
+ * Future reconcile ticks at epoch > maxEpoch keep monotonic ordering.
+ *
+ * Atomicity: write `*.compacting.tmp`, fsync, rename to the final name,
+ * THEN delete the consumed segments. A crash between rename and delete
+ * leaves the compacted file in place; the next round consumes everything
+ * including the compacted file and resolves to the same records (the
+ * compacted file's seq is highest, so its records win).
+ *
+ * `deferDelete: true` stages the compaction without unlinking consumed
+ * segments — the caller is responsible for deleting `consumedSegmentPaths`
+ * once it has published whatever derived state needs to change atomically
+ * with the unlink (e.g. the reconcile manifest's `sparseGram.deltas`
+ * list). Until the caller deletes them, every reader — including readers
+ * pinning the OLD manifest's segments — still resolves every record.
+ *
+ * Deleted-file records (`deleted: true`) are preserved by default — they
+ * suppress base postings at query time. Pass `{ dropTombstones: true }`
+ * to discard them; only safe when the caller has confirmed the matching
+ * fileId is gone from the base artifact too.
+ *
+ * @param {string} baseArtifactPath
+ * @param {{dropTombstones?:boolean, deferDelete?:boolean}} [opts]
+ * @returns {{
+ *   compactedPath: string|null,
+ *   consumedSegments: number,
+ *   consumedSegmentPaths: string[],
+ *   recordsWritten: number,
+ *   tombstonedDropped: number,
+ *   skipped: 'too-few-segments'|null,
+ * }}
+ */
+export function compactDeltaSegments(baseArtifactPath, opts = {}) {
+  const dropTombstones = !!opts.dropTombstones;
+  const deferDelete = !!opts.deferDelete;
+  const segments = listDeltaSegments(baseArtifactPath);
+  if (segments.length <= 1) {
+    return {
+      compactedPath: null,
+      consumedSegments: 0,
+      consumedSegmentPaths: [],
+      recordsWritten: 0,
+      tombstonedDropped: 0,
+      skipped: 'too-few-segments',
+    };
+  }
+  const maxEpoch = segments[segments.length - 1].epoch;
+  const maxSeqAtMaxEpoch = segments
+    .filter((s) => s.epoch === maxEpoch)
+    .reduce((m, s) => Math.max(m, s.seq), -1);
+  const compactSeq = Math.max(maxSeqAtMaxEpoch + 1, 1);
+
+  const latest = new Map();
+  for (const seg of segments) {
+    const raw = fs.readFileSync(seg.path, 'utf-8');
+    for (const line of raw.split('\n')) {
+      const trimmed = line.trim();
+      if (!trimmed) continue;
+      let record;
+      try { record = JSON.parse(trimmed); } catch { continue; }
+      if (!record.fileId) continue;
+      latest.set(record.fileId, record);
+    }
+  }
+
+  let tombstonedDropped = 0;
+  if (dropTombstones) {
+    for (const [fileId, rec] of latest) {
+      if (rec.deleted) {
+        latest.delete(fileId);
+        tombstonedDropped += 1;
+      }
+    }
+  }
+
+  const deltaDir = deltaDirFor(baseArtifactPath);
+  const targetName = `${maxEpoch}-${compactSeq}${DELTA_FILE_EXT}`;
+  const targetPath = path.join(deltaDir, targetName);
+  const tmpPath = targetPath + '.compacting.tmp';
+
+  const fd = fs.openSync(tmpPath, 'w');
+  try {
+    for (const record of latest.values()) {
+      fs.writeSync(fd, JSON.stringify(record) + '\n');
+    }
+    fs.fsyncSync(fd);
+  } finally {
+    fs.closeSync(fd);
+  }
+  fs.renameSync(tmpPath, targetPath);
+  try {
+    const dirFd = fs.openSync(deltaDir, 'r');
+    try { fs.fsyncSync(dirFd); } finally { fs.closeSync(dirFd); }
+  } catch { /* best-effort dir fsync */ }
+
+  const consumedSegmentPaths = segments
+    .filter((seg) => seg.path !== targetPath)
+    .map((seg) => seg.path);
+
+  let consumed = 0;
+  if (deferDelete) {
+    consumed = consumedSegmentPaths.length;
+  } else {
+    for (const segPath of consumedSegmentPaths) {
+      try { fs.unlinkSync(segPath); consumed += 1; } catch { /* tolerate concurrent deletion */ }
+    }
+  }
+
+  return {
+    compactedPath: targetPath,
+    consumedSegments: consumed,
+    consumedSegmentPaths: deferDelete ? consumedSegmentPaths : [],
+    recordsWritten: latest.size,
+    tombstonedDropped,
+    skipped: null,
+  };
+}
+
+/**
+ * Mark a file as deleted from the indexed corpus. Plan § 22.8.
+ *
+ * @param {string} baseArtifactPath
+ * @param {number} epoch
+ * @param {string} canonicalPath
+ */
+export function recordFileDeletion(baseArtifactPath, epoch, canonicalPath, weightsId = FALLBACK_WEIGHTS_ID) {
+  appendDeltaRecord(baseArtifactPath, epoch, {
+    fileId: fileIdFor(canonicalPath),
+    filePath: canonicalPath,
+    contentHash: '',
+    deleted: true,
+    symbolMask: 0,
+    weightsId,
+    grams: [],
+  });
+}

package/core/incremental-indexing/infrastructure/sqlite-fts5.mjs

@@ -0,0 +1,176 @@
+/**
+ * FTS5 introspection helpers used by the reconcile watermark scheduler.
+ *
+ * Plan § 7.1.5 requires a `fts5SegmentCount(db, tableName)` helper so the
+ * watermark check (segment count > 64 → bounded `('merge', 500)`) lives in
+ * one place. SQLite's FTS5 keeps a structure record at rowid=10 of the
+ * `<name>_data` shadow table. The block format is documented in the FTS5
+ * source (fts5_index.c) and stable enough that we ship a tiny varint parser
+ * here. If a future SQLite version changes the layout, the helper switches
+ * to a fallback heuristic (leaf-page rowid bit shift) without losing the
+ * watermark.
+ *
+ * Reference: SQLite FTS5 docs §7 ("Internal storage of the index"); structure
+ * record format mirrors `Fts5StructureLevel` / `Fts5StructureSegment` in
+ * fts5_index.c.
+ *
+ * Plan § 0 / § 37.5: Phase 0 commits to verifying this empirically against
+ * the SQLite version in use. The verification record lives in
+ * INCREMENTAL_INDEXING_PREFLIGHT_RESULTS.md § 3.
+ */
+
+const STRUCTURE_ROWID = 10;
+
+function readVarint(buf, offset) {
+  // SQLite varints are big-endian, up to 9 bytes, high-bit continuation.
+  let value = 0n;
+  let consumed = 0;
+  for (let i = 0; i < 9; i++) {
+    if (offset + i >= buf.length) {
+      throw new Error(`fts5 varint truncated at offset ${offset + i} (buffer len ${buf.length})`);
+    }
+    const byte = buf[offset + i];
+    if (i === 8) {
+      // The 9th byte uses all 8 bits.
+      value = (value << 8n) | BigInt(byte);
+      consumed = 9;
+      break;
+    }
+    value = (value << 7n) | BigInt(byte & 0x7F);
+    if ((byte & 0x80) === 0) {
+      consumed = i + 1;
+      break;
+    }
+  }
+  return { value, consumed };
+}
+
+/**
+ * Return the number of segments stored in an FTS5 index.
+ *
+ * Implementation: parse the structure record at `id = 10` of the
+ * `<name>_data` shadow table when possible (cookie + varints, per
+ * `fts5StructureDecode` in fts5_index.c). The structure record format is
+ * stable across SQLite 3.x but the per-level field order has shifted
+ * subtly between minor versions, so we cross-check the parsed count
+ * against a robust fallback: distinct segment-IDs derived from leaf-page
+ * rowids in `<name>_data`. Per the FTS5 source,
+ *
+ *   leaf_rowid = (segid << (FTS5_DATA_HEIGHT_B + FTS5_DATA_PAGE_B))
+ *              | (height << FTS5_DATA_PAGE_B)
+ *              | pgno
+ *
+ * with `FTS5_DATA_HEIGHT_B = 5` and `FTS5_DATA_PAGE_B = 31`. Distinct
+ * `rowid >> 36` values therefore approximate segment count tightly. If
+ * the two methods agree, return the parsed value; otherwise prefer the
+ * shift-based fallback (it cannot be wrong about distinct rowid prefixes).
+ *
+ * @param {import('better-sqlite3').Database} db
+ * @param {string} tableName  Name of the FTS5 virtual table (not the shadow).
+ * @returns {number}
+ */
+export function fts5SegmentCount(db, tableName) {
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(tableName)) {
+    throw new Error(`fts5SegmentCount: invalid table name ${tableName}`);
+  }
+  const shadow = `${tableName}_data`;
+  let rowids;
+  try {
+    // Cookie is at id<10; leaf pages live at id≥100. Distinct segid prefixes
+    // are the robust count.
+    rowids = db.prepare(`SELECT id FROM ${shadow} WHERE id >= 100`).all();
+  } catch (err) {
+    if (/no such table/i.test(err.message)) return 0;
+    throw err;
+  }
+  if (rowids.length === 0) return 0;
+
+  const seg = new Set();
+  for (const r of rowids) {
+    const id = BigInt(r.id);
+    seg.add(Number(id >> 36n));
+  }
+  return seg.size;
+}
+
+/**
+ * Internal: parse the FTS5 structure record at id=10 and return the per-level
+ * segment counts. Exported only for tests / diagnostic tooling; production
+ * code uses `fts5SegmentCount` which falls back to the rowid-shift method.
+ *
+ * Returns `{ cookie, nLevel, nSegment, levels: [{ nMerge, nSeg }] }` on
+ * success, or `null` if the table has no structure record yet.
+ *
+ * @param {import('better-sqlite3').Database} db
+ * @param {string} tableName
+ */
+export function fts5StructureDescribe(db, tableName) {
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(tableName)) {
+    throw new Error(`fts5StructureDescribe: invalid table name ${tableName}`);
+  }
+  const shadow = `${tableName}_data`;
+  let row;
+  try {
+    row = db.prepare(`SELECT block FROM ${shadow} WHERE id = ?`).get(STRUCTURE_ROWID);
+  } catch (err) {
+    if (/no such table/i.test(err.message)) return null;
+    throw err;
+  }
+  if (!row || !row.block) return null;
+
+  const buf = Buffer.isBuffer(row.block) ? row.block : Buffer.from(row.block);
+  if (buf.length < 6) return null;
+  const cookie = ((buf[0] << 24) | (buf[1] << 16) | (buf[2] << 8) | buf[3]) >>> 0;
+  let offset = 4;
+  const nLevelVI = readVarint(buf, offset); offset += nLevelVI.consumed;
+  const nSegmentVI = readVarint(buf, offset); offset += nSegmentVI.consumed;
+  const levels = [];
+  try {
+    for (let level = 0; level < Number(nLevelVI.value); level++) {
+      const nMerge = readVarint(buf, offset); offset += nMerge.consumed;
+      const nSeg = readVarint(buf, offset); offset += nSeg.consumed;
+      levels.push({ nMerge: Number(nMerge.value), nSeg: Number(nSeg.value) });
+      for (let s = 0; s < Number(nSeg.value); s++) {
+        const segid = readVarint(buf, offset); offset += segid.consumed;
+        const pgnoFirst = readVarint(buf, offset); offset += pgnoFirst.consumed;
+        const pgnoLast = readVarint(buf, offset); offset += pgnoLast.consumed;
+        void segid; void pgnoFirst; void pgnoLast;
+      }
+    }
+  } catch {
+    // Partial parse; return what we have. Phase 0 preflight asserts the
+    // structure-record parse matches the rowid-shift count; mismatch is a
+    // documented version-skew failure mode.
+  }
+  return {
+    cookie,
+    nLevel: Number(nLevelVI.value),
+    nSegment: Number(nSegmentVI.value),
+    levels,
+  };
+}
+
+/**
+ * Convenience wrapper that runs a bounded merge ("incremental compaction")
+ * on an FTS5 table. Plan § 7.1.5: every reconcile tick calls
+ * `('merge', 16)`; the watermark scheduler calls `('merge', 500)`.
+ *
+ * The function never calls `('optimize')` because that produces a single-
+ * transaction rewrite of the FTS5 index, which trips the 256 MiB WAL bloat
+ * alarm on a populated table.
+ *
+ * @param {import('better-sqlite3').Database} db
+ * @param {string} tableName
+ * @param {number} pages   Page budget per merge call (plan defaults: 16 or 500).
+ */
+export function fts5Merge(db, tableName, pages) {
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(tableName)) {
+    throw new Error(`fts5Merge: invalid table name ${tableName}`);
+  }
+  if (!Number.isInteger(pages) || pages <= 0) {
+    throw new Error(`fts5Merge: pages must be a positive integer, got ${pages}`);
+  }
+  db.prepare(`INSERT INTO ${tableName}(${tableName}, rank) VALUES('merge', ?)`).run(pages);
+}
+
+export const __testing = { readVarint, STRUCTURE_ROWID };

package/core/incremental-indexing/infrastructure/staleness-display.mjs

@@ -0,0 +1,105 @@
+/**
+ * CLI staleness footer.
+ *
+ * Plan § 19.1. Sweet-search shows a three-tier alert based on how long
+ * since the manifest was published, how many files are sitting dirty,
+ * and whether the maintenance queue is backed up:
+ *
+ *   green   < 60 s, 0 dirty               → hidden
+ *   yellow  60-300 s, < 5 dirty            → one-liner footer
+ *   red     > 300 s, > 5 dirty, or         → explicit warning
+ *           maintenance-queue backlog
+ *
+ * The display is informational. The reconciler does not block any CLI
+ * command on it; users decide whether to wait for the next tick or
+ * proceed against the slightly stale index.
+ */
+
+const GREEN = 'green';
+const YELLOW = 'yellow';
+const RED = 'red';
+
+const YELLOW_AGE_MS = 60_000;
+const RED_AGE_MS = 300_000;
+const YELLOW_DIRTY = 1;
+const RED_DIRTY = 5;
+const RED_BACKLOG = 4;
+
+/**
+ * Classify the staleness tier given the inputs.
+ *
+ * @param {object} input
+ * @param {number} input.ageMs               How long since manifest publish.
+ * @param {number} input.dirtyFiles          Current dirty-set size.
+ * @param {number} input.maintenanceBacklog  Pending maintenance jobs.
+ * @returns {'green'|'yellow'|'red'}
+ */
+export function stalenessTier(input) {
+  const { ageMs = 0, dirtyFiles = 0, maintenanceBacklog = 0 } = input;
+  if (ageMs > RED_AGE_MS || dirtyFiles > RED_DIRTY || maintenanceBacklog > RED_BACKLOG) {
+    return RED;
+  }
+  if (ageMs > YELLOW_AGE_MS || dirtyFiles > YELLOW_DIRTY) {
+    return YELLOW;
+  }
+  return GREEN;
+}
+
+function humaniseAge(ms) {
+  if (ms < 1000) return `${ms}ms`;
+  const s = Math.floor(ms / 1000);
+  if (s < 60) return `${s}s`;
+  const m = Math.floor(s / 60);
+  if (m < 60) return `${m}m ${s % 60}s`;
+  const h = Math.floor(m / 60);
+  return `${h}h ${m % 60}m`;
+}
+
+/**
+ * Build the footer string. Empty string when tier=green AND the caller
+ * did not pass `forceShow`.
+ *
+ * @param {object} input
+ * @param {number} input.epoch
+ * @param {number} input.ageMs
+ * @param {number} input.dirtyFiles
+ * @param {string|null} input.lastMaintenanceTier
+ * @param {number} input.lastMaintenanceAgeMs
+ * @param {number} input.maintenanceBacklog
+ * @param {boolean} [input.forceShow=false]
+ * @returns {string}
+ */
+export function formatStalenessFooter(input) {
+  const tier = stalenessTier(input);
+  if (tier === GREEN && !input.forceShow) return '';
+  const parts = [];
+  parts.push(`index epoch: ${input.epoch}`);
+  parts.push(`age: ${humaniseAge(input.ageMs)}`);
+  parts.push(`dirty files: ${input.dirtyFiles}`);
+  if (input.lastMaintenanceTier) {
+    parts.push(`last maintenance: ${input.lastMaintenanceTier} ${humaniseAge(input.lastMaintenanceAgeMs)} ago`);
+  }
+  if (input.maintenanceBacklog > 0) {
+    parts.push(`backlog: ${input.maintenanceBacklog}`);
+  }
+  const body = parts.join('   ');
+  const prefix = tier === RED ? '[sweet-search] ⚠ stale index — ' : '[sweet-search] ';
+  return prefix + body;
+}
+
+/**
+ * Render two lines (separator + footer). Plan § 19.1 mock-up format.
+ *
+ * @param {object} input
+ * @returns {string[]}
+ */
+export function renderStalenessLines(input) {
+  const footer = formatStalenessFooter(input);
+  if (!footer) return [];
+  return ['─────────', footer];
+}
+
+export const __testing = {
+  YELLOW_AGE_MS, RED_AGE_MS, YELLOW_DIRTY, RED_DIRTY, RED_BACKLOG,
+  GREEN, YELLOW, RED,
+};