@geraldmaron/construct 1.0.21 → 1.0.24

package/lib/document-export.mjs

@@ -0,0 +1,124 @@
+/**
+ * lib/document-export.mjs — markdown → PDF / DOCX / HTML export via external
+ * binaries (Pandoc + Typst), per ADR-0024.
+ *
+ * Bound to system-binary tooling discovered at runtime, never bundled in core
+ * (ADR-0001 zero-npm-core; ADR-0014 optional-capability pattern). Both engines
+ * are spawned as separate processes — Pandoc isolates its GPLv2+ licence at
+ * the process boundary; Typst is the Apache-2.0 PDF engine driven through
+ * Pandoc's `--pdf-engine=typst` flag, so a single Pandoc invocation produces
+ * every target format the contract supports.
+ *
+ * detect(format) reports availability without spawning the engine for real.
+ * exportMarkdown({ inputPath, outputPath, format, env }) spawns the engine and
+ * returns a structured result. Both surface actionable "install X" guidance
+ * when a required binary is absent; neither throws on missing tooling.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+export const EXPORT_FORMATS = ['pdf', 'docx', 'html'];
+
+const FORMAT_ENGINES = {
+  pdf: { engine: 'pandoc', pdfEngine: 'typst', extraBinaries: ['typst'] },
+  docx: { engine: 'pandoc', pdfEngine: null, extraBinaries: [] },
+  html: { engine: 'pandoc', pdfEngine: null, extraBinaries: [] },
+};
+
+function whichBin(name, env = process.env) {
+  const cmd = process.platform === 'win32' ? 'where' : 'which';
+  const result = spawnSync(cmd, [name], { encoding: 'utf8', env });
+  if (result.status !== 0) return null;
+  const first = (result.stdout || '').trim().split('\n')[0];
+  return first || null;
+}
+
+function binVersion(name, args = ['--version'], env = process.env) {
+  const r = spawnSync(name, args, { encoding: 'utf8', env });
+  if (r.status !== 0) return null;
+  const line = (r.stdout || '').trim().split('\n')[0];
+  return line || null;
+}
+
+function installHint(name) {
+  if (name === 'pandoc') return 'Install pandoc to enable document export (e.g. `brew install pandoc` on macOS, `apt install pandoc` on Debian/Ubuntu, or https://pandoc.org/installing.html).';
+  if (name === 'typst') return 'Install typst to enable PDF export via Pandoc (`brew install typst` on macOS, https://github.com/typst/typst/releases for binaries).';
+  return `Install ${name} to enable this export format.`;
+}
+
+// detect returns the same structure regardless of format so callers can render
+// availability uniformly. `present` is the single boolean a caller should gate
+// on; `missing` enumerates the binaries to install when present is false.
+
+export function detect(format, env = process.env) {
+  const config = FORMAT_ENGINES[format];
+  if (!config) return { ok: false, format, present: false, missing: [], message: `Unsupported format: ${format}. Supported: ${EXPORT_FORMATS.join(', ')}.` };
+  const required = [config.engine, ...(config.extraBinaries || [])];
+  const status = required.map((name) => ({ name, path: whichBin(name, env), version: null }));
+  for (const s of status) if (s.path) s.version = binVersion(s.name, ['--version'], env);
+  const missing = status.filter((s) => !s.path).map((s) => s.name);
+  return {
+    ok: true,
+    format,
+    present: missing.length === 0,
+    binaries: status,
+    missing,
+    message: missing.length === 0
+      ? `Ready: ${status.map((s) => `${s.name} (${s.version?.split(' ').slice(0, 2).join(' ') ?? 'unknown'})`).join(', ')}`
+      : missing.map(installHint).join(' '),
+  };
+}
+
+function defaultOutputPath(inputPath, format) {
+  const parsed = path.parse(inputPath);
+  return path.join(parsed.dir, `${parsed.name}.${format}`);
+}
+
+// exportMarkdown is the single contract callers depend on (CLI / MCP / SDK).
+// Returns { ok, format, inputPath, outputPath, engine, missing?, message }.
+// ok=false with a populated `missing` means a required binary is absent — the
+// caller surfaces `message` (which carries the install hint) instead of
+// retrying or crashing.
+
+export function exportMarkdown({ inputPath, outputPath, format, env = process.env, spawnFn = spawnSync } = {}) {
+  if (!inputPath) return { ok: false, format, message: 'exportMarkdown: inputPath is required.' };
+  if (!EXPORT_FORMATS.includes(format)) return { ok: false, format, inputPath, message: `Unsupported format: ${format}. Supported: ${EXPORT_FORMATS.join(', ')}.` };
+  if (!fs.existsSync(inputPath)) return { ok: false, format, inputPath, message: `exportMarkdown: input does not exist: ${inputPath}` };
+
+  const detection = detect(format, env);
+  if (!detection.present) {
+    return { ok: false, format, inputPath, missing: detection.missing, message: detection.message };
+  }
+
+  const config = FORMAT_ENGINES[format];
+  const target = outputPath || defaultOutputPath(inputPath, format);
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+
+  const args = ['-f', 'markdown', '-o', target, '--standalone'];
+  if (config.pdfEngine) args.push(`--pdf-engine=${config.pdfEngine}`);
+  args.push(inputPath);
+
+  const result = spawnFn(config.engine, args, { encoding: 'utf8', env });
+  if (result.status !== 0) {
+    return {
+      ok: false,
+      format,
+      inputPath,
+      outputPath: target,
+      engine: config.engine,
+      message: `Export failed (${config.engine} exit ${result.status}): ${(result.stderr || result.stdout || '').trim().slice(0, 400)}`,
+    };
+  }
+
+  return {
+    ok: true,
+    format,
+    inputPath,
+    outputPath: target,
+    engine: config.engine,
+    pdfEngine: config.pdfEngine,
+    message: `Wrote ${path.relative(process.cwd(), target)}`,
+  };
+}

package/lib/embed/daemon.mjs

@@ -1077,7 +1077,7 @@ this.#scheduler.register(
                 method: 'POST',
                 headers: {
                   Authorization: `Bearer ${orKey}`, 'content-type': 'application/json',
-                  'HTTP-Referer': 'https://github.com/construct',
+                  'HTTP-Referer': 'https://github.com/geraldmaron/construct',
                 },
                 body: JSON.stringify({
                   model: modelId.replace(/^openrouter\//, ''),

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,
@@ -296,17 +299,22 @@ export class InboxWatcher {
   #rootDir;
   #env;
   #cwd;
+  #prepareIntakeFn;
 
   /**
    * @param {object} opts
    * @param {string} opts.rootDir - Root dir for observation store + state file
    * @param {object} [opts.env]   - Env override (default: process.env)
    * @param {string} [opts.cwd]   - Working dir for ingest output (default: rootDir)
+   * @param {Function} [opts.prepareIntakeFn] - Override for prepareIntakeForIngestedFile
+   *   (test seam): receives the same args; returns null/throws to simulate a failed
+   *   packet creation so tests can assert the manifest-gate behavior (construct-k4bg).
    */
-  constructor({ rootDir, env = process.env, cwd } = {}) {
+  constructor({ rootDir, env = process.env, cwd, prepareIntakeFn } = {}) {
     this.#rootDir = rootDir;
     this.#env = env;
     this.#cwd = cwd ?? rootDir;
+    this.#prepareIntakeFn = prepareIntakeFn ?? prepareIntakeForIngestedFile;
   }
 
   /**
@@ -409,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,
@@ -423,13 +431,15 @@ export class InboxWatcher {
               extractedText,
             });
 
-            // Queue an intake packet so the agent can triage the new
-            // signal against the existing corpus. Failure here is
-            // non-fatal — ingest already succeeded; the queue is a
-            // best-effort handoff, not the ingestion's source of truth.
+            // Queue an intake packet so the agent can triage the new signal
+            // against the existing corpus. Failure here is non-fatal — ingest
+            // already succeeded; the queue is a best-effort handoff, not the
+            // ingestion's source of truth.
+
             let intakeId = null;
+            let intakeFailed = false;
             try {
-              const intakeResult = await prepareIntakeForIngestedFile({
+              const intakeResult = await this.#prepareIntakeFn({
                 rootDir: this.#rootDir,
                 ingestedFile: {
                   sourcePath: candidate.path,
@@ -441,7 +451,9 @@ export class InboxWatcher {
                 env: this.#env,
               });
               intakeId = intakeResult?.id || null;
+              if (!intakeId) intakeFailed = true;
             } catch (err) {
+              intakeFailed = true;
               if (this.#env.CONSTRUCT_DEBUG_INTAKE === '1') {
                 process.stderr.write(`[inbox] intake queue write failed for ${candidate.path}: ${err.message}\n`);
               }
@@ -449,7 +461,14 @@ export class InboxWatcher {
 
             state[key] = { mtimeMs: candidate.mtimeMs, processedAt: new Date().toISOString(), outputPath: fileResult.outputPath };
 
-            if (manifestEnabled && candidateSha) {
+            // The dedup manifest entry is the signal that `construct intake
+            // process` uses to skip already-handled files. Recording it when
+            // packet creation failed strands the file: explicit `intake process`
+            // reports "skipped (unchanged)" while `intake list` is empty, with
+            // no path back. Record only on a successful intake id so a failed
+            // auto-ingest stays retriable via the explicit path (construct-k4bg).
+
+            if (manifestEnabled && candidateSha && intakeId && !intakeFailed) {
               try {
                 recordFile(this.#rootDir, candidateSha, {
                   sourcePath: candidate.path,
@@ -462,6 +481,8 @@ export class InboxWatcher {
                   process.stderr.write(`[inbox] manifest record failed for ${candidate.path}: ${err.message}\n`);
                 }
               }
+            } else if (manifestEnabled && intakeFailed) {
+              process.stderr.write(`[inbox] ${candidate.path}: ingest succeeded but intake-packet creation failed; rerun \`construct intake process\` to retry.\n`);
             }
 
             processed.push({ path: candidate.path, outputPath: fileResult.outputPath, docsPath, characters: fileResult.characters, knowledgeSubdir, intakeId, dedupHash: candidateSha });

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(() => {}));
-}