@geraldmaron/construct 1.0.23 → 1.1.0

package/lib/document-extract.mjs

@@ -107,6 +107,11 @@ function run(command, args) {
 }
 
 function commandExists(command) {
+  // Test seam: a comma-separated deny-list forces a command to read as absent,
+  // so the cross-platform fallbacks (e.g. RTF stripping without macOS textutil)
+  // are reachable on any host.
+  const denied = (process.env.CONSTRUCT_EXTRACT_NO_COMMANDS || '').split(',').map((s) => s.trim()).filter(Boolean);
+  if (denied.includes(command)) return false;
   const checker = process.platform === 'win32' ? 'where' : 'which';
   return spawnSync(checker, [command], { stdio: 'ignore' }).status === 0;
 }
@@ -216,16 +221,38 @@ function extractZipDocument(filePath, extension) {
   return { text, method: 'zip-xml', droppedInfo, structured: null };
 }
 
-function extractRichText(filePath) {
-  if (!commandExists('textutil')) {
-    throw new Error('textutil not available for rich-text extraction');
+// Minimal RTF-to-text: strip control words, groups, and escapes. RTF is a
+// text format, so this works everywhere; it is the cross-platform fallback when
+// textutil (macOS only) is absent. Lossy on complex documents, but never throws.
+export function rtfToText(raw) {
+  let s = String(raw);
+  s = s.replace(/\{(?:\\\*)?\\(?:fonttbl|colortbl|stylesheet|info|pict|object)[\s\S]*?\}/gi, '');
+  s = s.replace(/\\u(-?\d+)\s?\??/g, (_, n) => (Number(n) >= 0 ? String.fromCharCode(Number(n)) : ''));
+  s = s.replace(/\\'([0-9a-fA-F]{2})/g, (_, h) => String.fromCharCode(parseInt(h, 16)));
+  s = s.replace(/\\par[d]?\b/g, '\n').replace(/\\line\b/g, '\n').replace(/\\tab\b/g, '\t');
+  s = s.replace(/\\[a-zA-Z]+-?\d* ?/g, '');
+  s = s.replace(/\\([{}\\])/g, '$1');
+  return s.replace(/[{}]/g, '');
+}
+
+function extractRichText(filePath, extension) {
+  if (commandExists('textutil')) {
+    return {
+      text: normalizeText(run('textutil', ['-convert', 'txt', '-stdout', filePath])),
+      method: 'textutil',
+      droppedInfo: [],
+      structured: null,
+    };
   }
-  return {
-    text: normalizeText(run('textutil', ['-convert', 'txt', '-stdout', filePath])),
-    method: 'textutil',
-    droppedInfo: [],
-    structured: null,
-  };
+  if (extension === '.rtf') {
+    return {
+      text: normalizeText(rtfToText(readFileSync(filePath, 'utf8'))),
+      method: 'rtf-strip',
+      droppedInfo: [],
+      structured: null,
+    };
+  }
+  throw new Error('textutil not available for rich-text extraction');
 }
 
 function extractPdfWithPdftotext(filePath) {
@@ -660,7 +687,7 @@ export function extractDocumentText(filePath, { maxChars = null } = {}) {
   } else if (ZIP_DOCUMENT_EXTS.has(extension)) {
     extracted = extractZipDocument(resolvedPath, extension);
   } else if (RICH_TEXT_EXTS.has(extension)) {
-    extracted = extractRichText(resolvedPath);
+    extracted = extractRichText(resolvedPath, extension);
   } else if (MDLS_DOCUMENT_EXTS.has(extension) && process.platform === 'darwin' && commandExists('mdls')) {
     extracted = { text: extractWithMdls(resolvedPath), method: 'mdls', droppedInfo: [], structured: null };
   } else if (EMAIL_DOCUMENT_EXTS.has(extension)) {

package/lib/document-ingest.mjs

@@ -8,7 +8,7 @@
  * and records the selected strategy/model in the returned `ingestion` block.
  */
 import { existsSync, mkdirSync, readdirSync, statSync, writeFileSync } from 'node:fs';
-import { basename, dirname, extname, isAbsolute, join, parse, relative, resolve } from 'node:path';
+import { basename, dirname, extname, isAbsolute, join, parse, relative, resolve, sep } from 'node:path';
 import { extractDocumentText, extractDocumentTextAsync, extractDocumentMetadata, isExtractableDocumentPath } from './document-extract.mjs';
 import { syncFileStateToSql } from './storage/sync.mjs';
 import { stampFrontmatter } from './doc-stamp.mjs';
@@ -16,6 +16,7 @@ import { KNOWLEDGE_ROOT, KNOWLEDGE_SUBDIRS } from './knowledge/layout.mjs';
 import { loadProjectConfig } from './config/project-config.mjs';
 import { resolveIngestStrategy, INGEST_STRATEGIES, INGEST_ORCHESTRATION_STRATEGIES } from './ingest/strategy.mjs';
 import { extractViaProvider } from './ingest/provider-extract.mjs';
+import { extractViaDoclingRemote } from './ingest/docling-remote.mjs';
 
 const DEFAULT_TARGET_DIR = '.cx/knowledge/internal';
 
@@ -56,6 +57,31 @@ function nextAvailablePath(targetPath) {
   }
 }
 
+// docling embeds figures as base64 `data:` URIs in the markdown so no pixel data
+// is lost in transit. Write each to an assets/ directory beside the output file
+// and rewrite the reference to a relative path, so the markdown stays small and
+// the images are real files an editor or viewer can open — replacing the bare
+// `<!-- image -->` placeholder docling emits by default.
+
+export function externalizeEmbeddedImages(markdown, { mdPath }) {
+  if (!markdown || !markdown.includes('data:image/')) return { markdown, assets: [] };
+  const assetsRel = `assets/${basename(mdPath, '.md')}`;
+  const assetsDir = join(dirname(mdPath), assetsRel.split('/').join(sep));
+  const assets = [];
+  let index = 0;
+  const re = /!\[([^\]]*)\]\(\s*data:image\/([a-zA-Z0-9.+-]+);base64,([A-Za-z0-9+/=\s]+?)\s*\)/g;
+  const out = markdown.replace(re, (_match, alt, type, b64) => {
+    index += 1;
+    const ext = type.toLowerCase() === 'jpeg' ? 'jpg' : type.toLowerCase().replace(/[^a-z0-9]/g, '') || 'png';
+    const fileName = `image-${index}.${ext}`;
+    if (!existsSync(assetsDir)) mkdirSync(assetsDir, { recursive: true });
+    writeFileSync(join(assetsDir, fileName), Buffer.from(b64.replace(/\s+/g, ''), 'base64'));
+    assets.push(join(assetsDir, fileName));
+    return `![${alt || `image ${index}`}](${assetsRel}/${fileName})`;
+  });
+  return { markdown: out, assets };
+}
+
 function renderMarkdown({ sourcePath, extractedAt, title, extractionMethod, characters, truncated, text, outputPath, cwd, metadata }) {
   const relSource = relative(cwd, sourcePath) || basename(sourcePath);
   const relOutput = relative(cwd, outputPath) || basename(outputPath);
@@ -126,17 +152,74 @@ function resolveOutputPath(sourcePath, { cwd, outputPath, outputDir, target }) {
   return join(resolvedDir, `${basename(sourcePath)}.md`);
 }
 
+// The high-fidelity (docling) path provisions a Python venv and downloads ML
+// models on first use, then runs layout inference on the document — any of which
+// can stall (a large PDF, a slow model download) or fail. Without a bound the
+// caller hangs: the CLI never returns, and the ingest_document MCP tool blocks
+// until the client times out and surfaces an opaque error. Bound the whole
+// docling attempt and fall back to the legacy extractor so ingest always returns
+// a usable result, with the fallback recorded in droppedInfo. Override the bound
+// with CONSTRUCT_DOCLING_TIMEOUT_MS (0 disables the timeout).
+
+const DOCLING_TIMEOUT_MS = (() => {
+  const raw = Number(process.env.CONSTRUCT_DOCLING_TIMEOUT_MS);
+  return Number.isFinite(raw) && raw >= 0 ? raw : 600_000;
+})();
+
+export function withTimeout(promise, ms, onTimeoutMessage) {
+  if (!ms) return promise;
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => reject(Object.assign(new Error(onTimeoutMessage), { code: 'DOCLING_TIMEOUT' })), ms);
+    promise.then((v) => { clearTimeout(timer); resolve(v); }, (e) => { clearTimeout(timer); reject(e); });
+  });
+}
+
+/**
+ * Run the high-fidelity (docling) extractor with a bound, falling back to the
+ * legacy extractor on timeout or any failure so a caller never hangs. The
+ * extractor functions are injectable for testing; production uses the real
+ * docling-async and legacy-sync extractors.
+ */
+export async function extractWithDoclingFallback(sourcePath, {
+  maxChars = null,
+  timeoutMs = DOCLING_TIMEOUT_MS,
+  asyncExtract = extractDocumentTextAsync,
+  syncExtract = extractDocumentText,
+} = {}) {
+  try {
+    return await withTimeout(
+      asyncExtract(sourcePath, { maxChars }),
+      timeoutMs,
+      `docling extraction exceeded ${Math.round(timeoutMs / 1000)}s`,
+    );
+  } catch (err) {
+    const legacy = syncExtract(sourcePath, { maxChars });
+    legacy.droppedInfo = [
+      ...(legacy.droppedInfo ?? []),
+      {
+        kind: 'docling-fallback',
+        count: 1,
+        reason: `High-fidelity (docling) extraction failed or timed out (${err.message}); used the legacy extractor. Re-run after \`construct install --with-docling\`, or pass --legacy-extractor to skip docling.`,
+        recoverable: true,
+      },
+    ];
+    return legacy;
+  }
+}
+
 function extractViaAdapter(sourcePath, { highFidelity, maxChars }) {
   return highFidelity
-    ? extractDocumentTextAsync(sourcePath, { maxChars })
+    ? extractWithDoclingFallback(sourcePath, { maxChars })
     : extractDocumentText(sourcePath, { maxChars });
 }
 
 async function extractWithStrategy(sourcePath, { strategy, fallback, model, provider, highFidelity, maxChars, env }) {
-  const primary = strategy === 'provider' ? 'provider' : 'adapter';
+  const primary = strategy === 'provider' || strategy === 'docling-remote' ? strategy : 'adapter';
   const run = (mode) => (mode === 'provider'
     ? extractViaProvider({ filePath: sourcePath, model, provider, maxChars, env })
-    : extractViaAdapter(sourcePath, { highFidelity, maxChars }));
+    : mode === 'docling-remote'
+      ? extractViaDoclingRemote({ filePath: sourcePath, maxChars, env })
+      : extractViaAdapter(sourcePath, { highFidelity, maxChars }));
 
   try {
     const extracted = await run(primary);
@@ -207,6 +290,7 @@ export async function ingestDocuments(inputPaths, {
     const finalPath = nextAvailablePath(targetPath);
     const extractedAt = new Date().toISOString();
     const title = metadata?.title || formatTitle(sourcePath);
+    const { markdown: bodyText, assets: imageAssets } = externalizeEmbeddedImages(extracted.text, { mdPath: finalPath });
     const markdown = renderMarkdown({
       sourcePath,
       extractedAt,
@@ -214,7 +298,7 @@ export async function ingestDocuments(inputPaths, {
       extractionMethod: extracted.extractionMethod,
       characters: extracted.characters,
       truncated: extracted.truncated,
-      text: extracted.text,
+      text: bodyText,
       outputPath: finalPath,
       cwd,
       metadata,
@@ -229,6 +313,7 @@ export async function ingestDocuments(inputPaths, {
       characters: extracted.characters,
       droppedInfo: extracted.droppedInfo ?? [],
       structured: extracted.structured ?? null,
+      images: imageAssets.map((p) => relative(cwd, p)),
       metadata: { title, authors: metadata?.authors || [], dates: metadata?.dates || {} },
     });
   }

package/lib/embed/inbox.mjs

@@ -241,7 +241,7 @@ function inferFileClassification(filePath) {
  * Summary = first non-empty line of extracted text (≤120 chars).
  * Content = first 1500 chars of extracted text for RAG searchability.
  */
-function recordInboxObservation(rootDir, { sourcePath, outputPath, characters, extractedText, category, knowledgeSubdir }) {
+async function recordInboxObservation(rootDir, { sourcePath, outputPath, characters, extractedText, category, knowledgeSubdir }) {
   const lines = (extractedText ?? '').split('\n').map((l) => l.trim()).filter(Boolean);
   const firstLine = (lines[0] ?? '').slice(0, 120);
   const filename = sourcePath.split('/').pop();
@@ -251,7 +251,10 @@ function recordInboxObservation(rootDir, { sourcePath, outputPath, characters, e
   const content = (extractedText ?? '').slice(0, 1500);
   const tags = ['inbox', 'ingested-doc', category, `knowledge:${knowledgeSubdir}`];
 
-  addObservation(rootDir, {
+  // Await the write so callers (poll) know ingestion is complete. Fire-and-
+  // forget here let the LanceDB write outlive poll() and race the caller's
+  // teardown, surfacing as "ENOTEMPTY: directory not empty" on .cx cleanup.
+  await addObservation(rootDir, {
     role: 'construct',
     category,
     summary,
@@ -414,7 +417,7 @@ export class InboxWatcher {
             const droppedInfo = fileResult.droppedInfo ?? [];
             writeExtractionWarning({ sourcePath: candidate.path, droppedInfo });
 
-            recordInboxObservation(this.#rootDir, {
+            await recordInboxObservation(this.#rootDir, {
               sourcePath: candidate.path,
               outputPath: fileResult.outputPath,
               characters: fileResult.characters,

package/lib/embed/recommendation-store.mjs

@@ -7,25 +7,12 @@
  * dismissal, automatic suppression after 7 days, and re-surfacing when
  * new signals arrive.
  *
- * Storage (solo mode):
+ * Construct now uses embedded LanceDB for vectors; recommendations
+ * remain filesystem-primary for simplicity and Git-backed collaboration.
+ *
+ * Storage:
  *   ~/.cx/intake/recommendations.jsonl — append-only log
  *   ~/.cx/intake/recommendations-index.json — fast lookup by id
- *
- * Storage (team/enterprise mode — DATABASE_URL configured):
- *   construct_recommendations table in Postgres (see db/schema/004_recommendations.sql)
- *   JSONL store is also written as a local backup.
- *
- * Prioritization formula:
- *   score = (signalCount * 2) + (customerImpact * 3) + (recencyBonus) + (strategicBonus)
- *   P0: score >= 10, P1: >= 7, P2: >= 4, P3: < 4
- *
- * Enrichment state machine: every new record starts with state: 'raw'. The
- * enrichment loop (subscriber to recommendation.generated, lifecycle event
- * emitted from createRecommendation on the new-record path only) transitions
- * raw → enriching → enriched | enrichment_failed and writes enrichedAt /
- * enrichedBy / framingNotes back to the index. Dedup-update path does not
- * re-emit so a steady drip of signals against the same recommendation does
- * not retrigger enrichment.
  */
 
 import { existsSync, readFileSync, writeFileSync, mkdirSync, appendFileSync } from 'node:fs';
@@ -33,8 +20,6 @@ import { join } from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { emitBestEffort } from '../roles/event-bus.mjs';
 import { cxDir } from '../paths.mjs';
-import { hasSqlStore } from '../storage/sql-store.mjs';
-import { createSqlClient } from '../storage/backend.mjs';
 
 const DEFAULT_SUPPRESS_DAYS = 7;
 const SUPERSEDE_WITHIN_HOURS = 72;
@@ -90,7 +75,6 @@ function priorityTier(score) {
 
 /**
  * Compute a dedup key from recommendation properties.
- * Two recommendations with the same dedup key are considered identical.
  */
 function dedupKey(type, title) {
   return `${type}::${title.toLowerCase().replace(/[^a-z0-9]+/g, '-').slice(0, 60)}`;
@@ -98,20 +82,6 @@ function dedupKey(type, title) {
 
 /**
  * Create a recommendation.
- *
- * @param {object} opts
- * @param {string} opts.type - 'prd' | 'adr' | 'rfc' | 'runbook' | 'postmortem'
- * @param {string} opts.title - Human-readable title
- * @param {string} opts.reason - Why this is being recommended
- * @param {number} [opts.signalCount=1] - Number of signals triggering this
- * @param {number} [opts.customerImpact=0] - 0-3: how many customers affected
- * @param {number} [opts.recencyBonus=0] - 0-3: how recent the signals are
- * @param {number} [opts.strategicBonus=0] - 0-3: strategic alignment
- * @param {string[]} [opts.sourceSignalIds] - IDs of intake signals that triggered this
- * @param {string} [opts.lane] - Docs lane this belongs to
- * @param {string} [opts.project] - Project name (defaults to CX_PROJECT or 'default')
- * @param {object} [opts.env] - Environment (defaults to process.env)
- * @returns {{ id: string, dedupKey: string, priority: string, score: number }}
  */
 export function createRecommendation({ type, title, reason, signalCount = 1, customerImpact = 0, recencyBonus = 0, strategicBonus = 0, sourceSignalIds = [], lane, project, env }) {
   if (!type || !title) throw new Error('type and title are required');
@@ -120,11 +90,9 @@ export function createRecommendation({ type, title, reason, signalCount = 1, cus
   const key = dedupKey(type, title);
   const index = readIndex();
 
-  // Check if already exists (dedup)
   if (index[key]) {
     const existing = index[key];
     if (!existing.supersededAt) {
-      // Update existing — increment signal count, extend dates
       const updated = {
         ...existing,
         lastSeen: new Date().toISOString(),
@@ -140,12 +108,8 @@ export function createRecommendation({ type, title, reason, signalCount = 1, cus
       index[key] = updated;
       writeIndex(index);
 
-      const result = { id: existing.id, dedupKey: key, priority: updated.priority, score, existing: true, updatedAt: updated.lastSeen };
-      createRecommendationPgBestEffort(updated, project, env);
-      return result;
+      return { id: existing.id, dedupKey: key, priority: updated.priority, score, existing: true, updatedAt: updated.lastSeen };
     }
-    // Existing was dismissed — create new instance with new signals
-    // (superseded recommendations can be revived with fresh signals)
   }
 
   const id = `rec-${randomUUID().slice(0, 8)}`;
@@ -175,19 +139,11 @@ export function createRecommendation({ type, title, reason, signalCount = 1, cus
     enrichedBy: null,
   };
 
-  // Append to log
   appendFileSync(recommendationPaths().logFile, JSON.stringify(rec) + '\n', 'utf8');
 
-  // Update index
   index[key] = rec;
   writeIndex(index);
 
-  createRecommendationPgBestEffort(rec, project, env);
-
-  // Surfaces the new recommendation as a lifecycle event so the enrichment
-  // loop (and any project-bound subscribers in .cx/specialists/) can route
-  // the matched specialist's contract chain against it.
-
   emitBestEffort('recommendation.generated', {
     project: project || '',
     summary: `${rec.type}: ${rec.title}`,
@@ -203,23 +159,10 @@ export function createRecommendation({ type, title, reason, signalCount = 1, cus
   return { id, dedupKey: key, priority: rec.priority, score, existing: false };
 }
 
-/**
- * Compute prioritization score.
- * score = (signalCount * 2) + (customerImpact * 3) + (recencyBonus) + (strategicBonus)
- */
 function computeScore({ signalCount = 1, customerImpact = 0, recencyBonus = 0, strategicBonus = 0 }) {
   return (signalCount * 2) + (customerImpact * 3) + (recencyBonus) + (strategicBonus);
 }
 
-/**
- * Dismiss a recommendation (suppress permanently or for N days).
- *
- * @param {string} dedupKey - Dedup key
- * @param {object} [opts]
- * @param {string} [opts.reason] - Why dismissed
- * @param {number} [opts.suppressDays] - Days to suppress (default: forever)
- * @returns {{ success: boolean }}
- */
 export function dismissRecommendation(dedupKey, { reason = 'manually dismissed', suppressDays } = {}) {
   const index = readIndex();
   if (!index[dedupKey]) {
@@ -239,13 +182,6 @@ export function dismissRecommendation(dedupKey, { reason = 'manually dismissed',
   return { success: true };
 }
 
-/**
- * Supersede a recommendation (mark as superseded by a newer one).
- *
- * @param {string} dedupKey - Existing recommendation to supersede
- * @param {string} supersedingId - ID of the recommendation that replaces it
- * @returns {{ success: boolean }}
- */
 export function supersedeRecommendation(dedupKey, supersedingId) {
   const index = readIndex();
   if (!index[dedupKey]) {
@@ -263,41 +199,17 @@ export function supersedeRecommendation(dedupKey, supersedingId) {
 }
 
 /**
- * List active (non-dismissed, non-superseded) recommendations.
- *
- * In team/enterprise mode (DATABASE_URL configured), reads from Postgres when
- * the project has rows. Falls back to JSONL index.
- *
- * @param {object} [opts]
- * @param {string} [opts.type] - Filter by type
- * @param {string} [opts.priority] - Filter by priority (P0, P1, etc.)
- * @param {number} [opts.limit=20]
- * @param {string} [opts.project] - Project name (defaults to CX_PROJECT or 'default')
- * @param {object} [opts.env] - Environment (defaults to process.env)
- * @returns {Array<object>}
+ * List active recommendations (filesystem-only).
  */
 export function listActiveRecommendations({ type, priority, limit = 20, project, env } = {}) {
-  if (hasSqlStore(env)) {
-    return listActiveRecommendationsPgWithFallback({ type, priority, limit, project, env });
-  }
-  return listActiveRecommendationsFile({ type, priority, limit });
-}
-
-/**
- * File-based active recommendations list.
- */
-function listActiveRecommendationsFile({ type, priority, limit = 20 } = {}) {
   const index = readIndex();
   const now = new Date();
   let results = Object.values(index).filter(rec => {
-    // Skip dismissed (unless temporary suppress and still active)
     if (rec.dismissedAt) {
       if (rec.suppressedUntil && new Date(rec.suppressedUntil) > now) return false;
       if (!rec.suppressedUntil) return false;
     }
-    // Skip superseded
     if (rec.supersededAt) return false;
-    // Skip suppressed
     if (rec.suppressedUntil && new Date(rec.suppressedUntil) > now) return false;
     return true;
   });
@@ -310,34 +222,6 @@ function listActiveRecommendationsFile({ type, priority, limit = 20 } = {}) {
     .slice(0, limit);
 }
 
-/**
- * Attempt Postgres read, fall back to file synchronously.
- * Returns a Promise so callers using await get Postgres data; callers not
- * using await get the file-based results via the sync fallback.
- */
-function listActiveRecommendationsPgWithFallback({ type, priority, limit, project, env }) {
-  const resolvedProject = project || (env || process.env).CX_PROJECT || 'default';
-  const client = createSqlClient(env);
-
-  return listActiveRecommendationsPg(resolvedProject, { type, priority, limit }, client)
-    .then(rows => {
-      client.end({ timeout: 5 }).catch(() => {});
-      if (rows.length > 0) return rows;
-      return listActiveRecommendationsFile({ type, priority, limit });
-    })
-    .catch(() => {
-      client.end({ timeout: 5 }).catch(() => {});
-      return listActiveRecommendationsFile({ type, priority, limit });
-    });
-}
-
-/**
- * Auto-suppress recommendations that have been active for DEFAULT_SUPPRESS_DAYS
- * without new signals, or that were superseded more than SUPERSEDE_WITHIN_HOURS ago.
- * Call from docs-lifecycle or a scheduled daemon job.
- *
- * @returns {number} Number of recommendations suppressed
- */
 export function autoSuppressStale() {
   const index = readIndex();
   const now = Date.now();
@@ -346,7 +230,6 @@ export function autoSuppressStale() {
   for (const [key, rec] of Object.entries(index)) {
     if (rec.dismissedAt || rec.supersededAt) continue;
 
-    // Suppress if lastSeen is older than DEFAULT_SUPPRESS_DAYS
     const lastSeen = new Date(rec.lastSeen || rec.firstSeen).getTime();
     const ageDays = (now - lastSeen) / (24 * 60 * 60 * 1000);
     if (ageDays > DEFAULT_SUPPRESS_DAYS) {
@@ -359,7 +242,6 @@ export function autoSuppressStale() {
       continue;
     }
 
-    // Suppress superseded older than threshold
     if (rec.supersededAt) {
       const supersededAt = new Date(rec.supersededAt).getTime();
       if ((now - supersededAt) > SUPERSEDE_WITHIN_HOURS * 60 * 60 * 1000) {
@@ -377,15 +259,6 @@ export function autoSuppressStale() {
   return suppressed;
 }
 
-/**
- * Revive a recommendation from dismissal with new signals.
- *
- * @param {string} dedupKey
- * @param {object} newSignals
- * @param {number} [newSignals.signalCount=1]
- * @param {string[]} [newSignals.sourceSignalIds]
- * @returns {{ success: boolean }}
- */
 export function reviveRecommendation(dedupKey, { signalCount = 1, sourceSignalIds = [] } = {}) {
   const index = readIndex();
   if (!index[dedupKey]) {
@@ -397,7 +270,7 @@ export function reviveRecommendation(dedupKey, { signalCount = 1, sourceSignalId
   const score = computeScore({
     signalCount: updatedSignalCount,
     customerImpact: existing.customerImpact || 0,
-    recencyBonus: 3, // recent signals get max recency bonus
+    recencyBonus: 3,
     strategicBonus: existing.strategicBonus || 0,
   });
 
@@ -418,11 +291,6 @@ export function reviveRecommendation(dedupKey, { signalCount = 1, sourceSignalId
   return { success: true };
 }
 
-/**
- * Get store statistics.
- *
- * @returns {{ total: number, active: number, dismissed: number, superseded: number, byPriority: object }}
- */
 export function recommendationStats() {
   const index = readIndex();
   const entries = Object.values(index);
@@ -446,13 +314,6 @@ export function recommendationStats() {
   };
 }
 
-/**
- * Check if a recommendation with the given dedup key is active.
- *
- * @param {string} type
- * @param {string} title
- * @returns {{ active: boolean, existing: object|null }}
- */
 export function isRecommendationActive(type, title) {
   const key = dedupKey(type, title);
   const index = readIndex();
@@ -461,146 +322,3 @@ export function isRecommendationActive(type, title) {
   if (rec.dismissedAt || rec.supersededAt) return { active: false, existing: rec };
   return { active: true, existing: rec };
 }
-
-// ---------------------------------------------------------------------------
-// Postgres backend — team/enterprise mode only
-// ---------------------------------------------------------------------------
-
-/**
- * Upsert a recommendation into construct_recommendations.
- * On conflict (project, dedup_key) update all mutable fields.
- *
- * @param {object} rec - Recommendation object (camelCase)
- * @param {string} project
- * @param {object} client - postgres.js SQL client
- */
-export async function createRecommendationPg(rec, project, client) {
-  await client`
-    insert into construct_recommendations (
-      id, project, dedup_key, type, title, reason, lane,
-      signal_count, total_signal_count,
-      customer_impact, recency_bonus, strategic_bonus,
-      score, priority, source_signal_ids,
-      first_seen, last_seen,
-      dismissed_at, dismiss_reason,
-      superseded_at, superseded_by_id,
-      suppressed_until, suppress_reason,
-      updated_at
-    ) values (
-      ${rec.id}, ${project}, ${rec.dedupKey || dedupKey(rec.type, rec.title)}, ${rec.type}, ${rec.title},
-      ${rec.reason ?? null}, ${rec.lane ?? null},
-      ${rec.signalCount ?? 1}, ${rec.totalSignalCount ?? 1},
-      ${rec.customerImpact ?? 0}, ${rec.recencyBonus ?? 0}, ${rec.strategicBonus ?? 0},
-      ${rec.score ?? 0}, ${rec.priority ?? 'P3'},
-      ${JSON.stringify(rec.sourceSignalIds ?? [])}::jsonb,
-      ${rec.firstSeen ?? new Date().toISOString()}, ${rec.lastSeen ?? new Date().toISOString()},
-      ${rec.dismissedAt ?? null}, ${rec.dismissReason ?? null},
-      ${rec.supersededAt ?? null}, ${rec.supersededById ?? null},
-      ${rec.suppressedUntil ?? null}, ${rec.suppressReason ?? null},
-      now()
-    )
-    on conflict (project, dedup_key) do update set
-      signal_count        = excluded.signal_count,
-      total_signal_count  = excluded.total_signal_count,
-      customer_impact     = excluded.customer_impact,
-      recency_bonus       = excluded.recency_bonus,
-      strategic_bonus     = excluded.strategic_bonus,
-      score               = excluded.score,
-      priority            = excluded.priority,
-      source_signal_ids   = excluded.source_signal_ids,
-      last_seen           = excluded.last_seen,
-      dismissed_at        = excluded.dismissed_at,
-      dismiss_reason      = excluded.dismiss_reason,
-      superseded_at       = excluded.superseded_at,
-      superseded_by_id    = excluded.superseded_by_id,
-      suppressed_until    = excluded.suppressed_until,
-      suppress_reason     = excluded.suppress_reason,
-      updated_at          = now()
-  `;
-}
-
-/**
- * Query active recommendations from Postgres for a project.
- *
- * @param {string} project
- * @param {object} [opts]
- * @param {string} [opts.type]
- * @param {string} [opts.priority]
- * @param {number} [opts.limit=20]
- * @param {object} client - postgres.js SQL client
- * @returns {Promise<Array<object>>}
- */
-export async function listActiveRecommendationsPg(project, { type, priority, limit = 20 } = {}, client) {
-  const rows = await client`
-    select *
-    from construct_recommendations
-    where project = ${project}
-      and dismissed_at is null
-      and superseded_at is null
-      and (suppressed_until is null or suppressed_until <= now())
-      ${type ? client`and type = ${type}` : client``}
-      ${priority ? client`and priority = ${priority}` : client``}
-    order by score desc
-    limit ${limit}
-  `;
-
-  return rows.map(row => ({
-    id: row.id,
-    type: row.type,
-    title: row.title,
-    reason: row.reason,
-    lane: row.lane,
-    signalCount: row.signal_count,
-    totalSignalCount: row.total_signal_count,
-    customerImpact: row.customer_impact,
-    recencyBonus: row.recency_bonus,
-    strategicBonus: row.strategic_bonus,
-    score: row.score,
-    priority: row.priority,
-    sourceSignalIds: row.source_signal_ids ?? [],
-    firstSeen: row.first_seen instanceof Date ? row.first_seen.toISOString() : row.first_seen,
-    lastSeen: row.last_seen instanceof Date ? row.last_seen.toISOString() : row.last_seen,
-    dismissedAt: row.dismissed_at,
-    supersededAt: row.superseded_at,
-    suppressedUntil: row.suppressed_until,
-  }));
-}
-
-/**
- * Dismiss a recommendation in Postgres.
- *
- * @param {string} dedupKeyValue
- * @param {string} project
- * @param {object} [opts]
- * @param {string} [opts.reason]
- * @param {number} [opts.suppressDays]
- * @param {object} client - postgres.js SQL client
- */
-export async function dismissRecommendationPg(dedupKeyValue, project, { reason = 'manually dismissed', suppressDays } = {}, client) {
-  const suppressedUntil = suppressDays
-    ? new Date(Date.now() + suppressDays * 24 * 60 * 60 * 1000).toISOString()
-    : null;
-
-  await client`
-    update construct_recommendations
-    set
-      dismissed_at    = now(),
-      dismiss_reason  = ${reason},
-      suppressed_until = ${suppressedUntil},
-      updated_at      = now()
-    where project = ${project}
-      and dedup_key = ${dedupKeyValue}
-  `;
-}
-
-/**
- * Fire-and-forget Postgres upsert — never throws, never blocks the caller.
- */
-function createRecommendationPgBestEffort(rec, project, env) {
-  if (!hasSqlStore(env)) return;
-  const resolvedProject = project || (env || process.env).CX_PROJECT || 'default';
-  const client = createSqlClient(env);
-  createRecommendationPg(rec, resolvedProject, client)
-    .catch(() => {})
-    .finally(() => client.end({ timeout: 5 }).catch(() => {}));
-}