@4da/mcp-server 4.6.1 → 4.6.3

package/dist/scheduler/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Scheduler composition (S4) — wire core + freshness + refreshers into one switchable unit.
+ *
+ * The whole scheduler is OFF unless explicitly enabled (fail-safe: an MCP server must never
+ * grow background network activity by surprise). Enabled, it registers every refresh unit on
+ * the cadence engine, starts the timers, and exposes a status view the server (or a future
+ * `scheduler_status` tool) can render: every unit, its cadence, and when it last ran.
+ */
+import { type SchedulerJobView } from "./core.js";
+export interface InitSchedulerOpts {
+    enabled: boolean;
+    pull: Record<string, () => Promise<void>>;
+    freshnessPath?: string;
+}
+export interface RunningScheduler {
+    started: boolean;
+    status(): SchedulerJobView[];
+    stop(): void;
+}
+export declare function initScheduler(opts: InitSchedulerOpts): RunningScheduler;
+//# sourceMappingURL=index.d.ts.map

package/dist/scheduler/index.js

@@ -0,0 +1,32 @@
+/**
+ * Scheduler composition (S4) — wire core + freshness + refreshers into one switchable unit.
+ *
+ * The whole scheduler is OFF unless explicitly enabled (fail-safe: an MCP server must never
+ * grow background network activity by surprise). Enabled, it registers every refresh unit on
+ * the cadence engine, starts the timers, and exposes a status view the server (or a future
+ * `scheduler_status` tool) can render: every unit, its cadence, and when it last ran.
+ */
+import { createScheduler } from "./core.js";
+import { createFreshness } from "./freshness.js";
+import { buildRefreshers } from "./refreshers.js";
+export function initScheduler(opts) {
+    if (!opts.enabled) {
+        return { started: false, status: () => [], stop: () => { } };
+    }
+    const freshness = createFreshness(opts.freshnessPath);
+    freshness.load();
+    const scheduler = createScheduler();
+    for (const unit of buildRefreshers({ pull: opts.pull, freshness })) {
+        scheduler.register(unit.name, unit.intervalMs, () => unit.run());
+    }
+    scheduler.start();
+    return {
+        started: true,
+        status: () => scheduler.jobs(),
+        stop: () => {
+            scheduler.stop();
+            freshness.save();
+        },
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/scheduler/refreshers.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Refresh adapters (S3) — wrap each named data pull into a schedulable refresh unit.
+ *
+ * Pure dependency injection: the pulls and the freshness sink are handed in, nothing is
+ * imported from the fetcher layer and nothing touches the network here. A refresh unit runs
+ * its pull and only THEN marks freshness — a failing pull rethrows and leaves the watermark
+ * untouched, so staleness stays honest.
+ */
+export interface RefreshDeps {
+    pull: Record<string, () => Promise<void>>;
+    freshness: {
+        markFresh(name: string, at?: number): void;
+    };
+}
+export interface RefreshUnit {
+    name: string;
+    intervalMs: number;
+    run(): Promise<void>;
+}
+export declare function buildRefreshers(deps: RefreshDeps): RefreshUnit[];
+//# sourceMappingURL=refreshers.d.ts.map

package/dist/scheduler/refreshers.js

@@ -0,0 +1,21 @@
+/**
+ * Refresh adapters (S3) — wrap each named data pull into a schedulable refresh unit.
+ *
+ * Pure dependency injection: the pulls and the freshness sink are handed in, nothing is
+ * imported from the fetcher layer and nothing touches the network here. A refresh unit runs
+ * its pull and only THEN marks freshness — a failing pull rethrows and leaves the watermark
+ * untouched, so staleness stays honest.
+ */
+/** Default cadence per refresh unit; callers can re-register with their own interval. */
+const DEFAULT_INTERVAL_MS = 15 * 60 * 1000; // 15 minutes — fresh enough for feed data, kind to upstreams
+export function buildRefreshers(deps) {
+    return Object.entries(deps.pull).map(([name, pull]) => ({
+        name,
+        intervalMs: DEFAULT_INTERVAL_MS,
+        async run() {
+            await pull(); // a throw propagates — freshness must NOT advance on a failed pull
+            deps.freshness.markFresh(name);
+        },
+    }));
+}
+//# sourceMappingURL=refreshers.js.map

package/dist/schemas/get-relevant-content.json

@@ -1,6 +1,6 @@
 {
   "name": "get_relevant_content",
-  "description": "Get filtered relevant content from 4DA's personalized feed.\n\nReturns content items that match the user's interests, tech stack, and learned preferences.\nItems are scored based on:\n- Explicit interests declared by the user\n- Tech stack and domains\n- ACE-detected context (recent files, projects, git activity)\n- Learned preferences from past interactions\n\nCall when the user asks what to read, what is relevant to them, or for content on a topic.",
+  "description": "Get filtered relevant content from 4DA's personalized feed.\n\nReturns content items that match the user's interests, tech stack, and learned preferences.\nItems are scored based on:\n- Explicit interests declared by the user\n- Tech stack and domains\n- ACE-detected context (recent files, projects, git activity)\n- Learned preferences from past interactions\n\nIMPORTANT for autonomous use: each item carries an `evidence_class` describing how it is grounded. The relevance_score float is NOT comparable across classes — gate actions on evidence_class, not the number:\n- \"osv_verified\": a security advisory matching one of the user's INSTALLED dependencies — safe to act on\n- \"dependency_grounded\": matched one of the user's declared dependencies — trustworthy\n- \"semantic_only\": topical/embedding relevance with NO dependency edge — surface to the human, verify before acting\n- \"keyword_heuristic\": standalone-mode keyword score (no Rust pipeline) — weakest signal\n\nCall when the user asks what to read, what is relevant to them, or for content on a topic.",
   "inputSchema": {
     "type": "object",
     "properties": {

package/dist/schemas/upgrade-planner.json

@@ -1,6 +1,6 @@
 {
   "name": "upgrade_planner",
-  "description": "Ranked upgrade recommendations for project dependencies. Combines vulnerability severity, deprecation status, and version distance to produce a prioritized upgrade plan.\n\nShows quick wins (safe patch/minor upgrades) separately from breaking changes (major version bumps). Call after dependency_health to plan your upgrade strategy.\n\nPrivacy: uses cached registry data. No additional network calls beyond what dependency_health already fetched.",
+  "description": "Ranked standalone upgrade recommendations for project dependencies — call before upgrading, adding, or auditing any dependency to pick the safest order. Combines vulnerability severity, deprecation status, and version distance into a prioritized plan.\n\nSplits recommendations three ways: quick wins (safe patch/minor upgrades), breaking changes (major version bumps), and transitive CVEs marked waiting_on_upstream (not declared in your manifest — the fix arrives via a parent package update or a lockfile refresh). Call dependency_health first for registry context and vulnerability_scan first for a CVE-aware plan; without a scan the output says it is CVE-blind.\n\nProvenance: standalone heuristic — a point-in-time plan from local lockfiles plus live registry/OSV lookups, not the 4DA desktop app's cross-project, version-confirmed plan.\n\nPrivacy: live mode may query public registries and OSV with package names and versions. It never sends source code.",
   "inputSchema": {
     "type": "object",
     "properties": {

package/dist/schemas/what-should-i-know.json

@@ -1,6 +1,6 @@
 {
   "name": "what_should_i_know",
-  "description": "Pre-task intelligence briefing. Given a task description and optional file paths, returns filtered advisories (security alerts, breaking changes), active decision windows, signal chains, relevant past decisions/memories, and a delegation assessment. Call this before starting any non-trivial task to get caught up on what matters.",
+  "description": "Pre-task intelligence briefing. Given a task description and optional file paths, returns filtered advisories (security alerts, breaking changes), active decision windows, signal chains, relevant past decisions/memories, and a delegation assessment. Call this before starting any non-trivial task to get caught up on what matters. If the task involves upgrading, adding, or auditing dependencies, follow with upgrade_planner for the ranked plan.",
   "inputSchema": {
     "type": "object",
     "properties": {

package/dist/tools/agent-memory.d.ts

@@ -90,5 +90,15 @@ export declare const agentMemoryTool: {
         required: string[];
     };
 };
-export declare function executeAgentMemory(db: FourDADatabase, params: AgentMemoryParams): object;
+/**
+ * The text embedded for a memory. Exported so every surface that embeds a memory
+ * row (this tool AND the what_should_i_know briefing) uses IDENTICAL text —
+ * otherwise they would write conflicting vectors into the shared
+ * agent_memory.embedding column.
+ */
+export declare function memoryEmbedText(row: {
+    subject: string;
+    content: string;
+}): string;
+export declare function executeAgentMemory(db: FourDADatabase, params: AgentMemoryParams): object | Promise<object>;
 //# sourceMappingURL=agent-memory.d.ts.map

package/dist/tools/agent-memory.js

@@ -5,6 +5,8 @@
  * Cross-agent persistent memory. What Claude Code learns, Cursor can access.
  * Enables AI agents to store and recall memories across sessions and tools.
  */
+import { rankRowsByRecall } from "./recall.js";
+import { getEmbeddingConfig, semanticScores, } from "../embeddings.js";
 // ============================================================================
 // Tool Definition
 // ============================================================================
@@ -81,6 +83,24 @@ export const agentMemoryTool = {
 const MAX_CONTENT_BYTES = 10 * 1024;
 /** Maximum entries per agent */
 const MAX_ENTRIES_PER_AGENT = 1000;
+/** Weighted text fields for lexical recall ranking (shared by lexical + hybrid paths). */
+const MEMORY_RECALL_FIELDS = [
+    { name: "subject", weight: 4, value: (row) => row.subject },
+    { name: "tags", weight: 3, value: (row) => row.context_tags },
+    { name: "content", weight: 2, value: (row) => row.content },
+    { name: "type", weight: 1, value: (row) => row.memory_type },
+];
+/** Blend weight for semantic cosine vs normalized lexical score in hybrid recall. */
+const SEMANTIC_BLEND = 0.65;
+/**
+ * The text embedded for a memory. Exported so every surface that embeds a memory
+ * row (this tool AND the what_should_i_know briefing) uses IDENTICAL text —
+ * otherwise they would write conflicting vectors into the shared
+ * agent_memory.embedding column.
+ */
+export function memoryEmbedText(row) {
+    return `${row.subject}\n${row.content}`;
+}
 // ============================================================================
 // Helpers
 // ============================================================================
@@ -92,12 +112,21 @@ function parseMemoryRow(row) {
         memory_type: row.memory_type,
         subject: row.subject,
         content: row.content,
-        context_tags: JSON.parse(row.context_tags || "[]"),
+        context_tags: parseStringList(row.context_tags),
         created_at: row.created_at,
         expires_at: row.expires_at,
         promoted_to_decision_id: row.promoted_to_decision_id,
     };
 }
+function parseStringList(json) {
+    try {
+        const parsed = JSON.parse(json || "[]");
+        return Array.isArray(parsed) ? parsed.map(String) : [];
+    }
+    catch {
+        return [];
+    }
+}
 // ============================================================================
 // Execute
 // ============================================================================
@@ -161,24 +190,28 @@ export function executeAgentMemory(db, params) {
                 return { error: "query is required for recall action" };
             }
             try {
-                const pattern = `%${params.query.toLowerCase()}%`;
                 let sql = `SELECT id, session_id, agent_type, memory_type, subject, content,
                           context_tags, created_at, expires_at, promoted_to_decision_id
                    FROM agent_memory
-                   WHERE (LOWER(subject) LIKE ? OR LOWER(context_tags) LIKE ?)
-                   AND (expires_at IS NULL OR expires_at > datetime('now'))`;
-                const sqlParams = [pattern, pattern];
+                   WHERE (expires_at IS NULL OR expires_at > datetime('now'))`;
+                const sqlParams = [];
                 if (params.filter_agent) {
                     sql += ` AND agent_type = ?`;
                     sqlParams.push(params.filter_agent);
                 }
                 sql += ` ORDER BY created_at DESC LIMIT ?`;
-                sqlParams.push(params.limit || 20);
+                sqlParams.push(MAX_ENTRIES_PER_AGENT);
                 const rows = rawDb.prepare(sql).all(...sqlParams);
-                return {
-                    memories: rows.map(parseMemoryRow),
-                    count: rows.length,
-                };
+                const limit = params.limit || 20;
+                // Optional semantic recall — only when an embedding provider is configured.
+                // Returns a Promise (dispatch awaits uniformly); every other path stays
+                // synchronous, so callers without a provider behave exactly as before.
+                const embedConfig = getEmbeddingConfig();
+                if (embedConfig) {
+                    return enhanceRecallWithSemantics(db, params.query, rows, limit, embedConfig);
+                }
+                const ranked = rankRowsByRecall(rows, params.query, MEMORY_RECALL_FIELDS, limit);
+                return lexicalRecallResult(ranked, rows.length);
             }
             catch (error) {
                 return {
@@ -196,7 +229,7 @@ export function executeAgentMemory(db, params) {
                 return { error: "tags array is required for recall_by_tags action" };
             }
             try {
-                // Build OR conditions for each tag
+                // Prefilter to entries whose tags literally contain ANY requested tag...
                 const conditions = params.tags.map(() => `LOWER(context_tags) LIKE ?`);
                 const tagParams = params.tags.map((t) => `%${t.toLowerCase()}%`);
                 const sql = `SELECT id, session_id, agent_type, memory_type, subject, content,
@@ -207,10 +240,23 @@ export function executeAgentMemory(db, params) {
                      ORDER BY created_at DESC LIMIT ?`;
                 const rows = rawDb
                     .prepare(sql)
-                    .all(...tagParams, params.limit || 20);
+                    .all(...tagParams, MAX_ENTRIES_PER_AGENT);
+                // ...then rank by relevance so the strongest tag/subject/content matches
+                // lead, returning the same shape as `recall` (matched_fields, recall_score).
+                const ranked = rankRowsByRecall(rows, params.tags.join(" "), [
+                    { name: "tags", weight: 4, value: (row) => row.context_tags },
+                    { name: "subject", weight: 2, value: (row) => row.subject },
+                    { name: "content", weight: 1, value: (row) => row.content },
+                ], params.limit || 20);
                 return {
-                    memories: rows.map(parseMemoryRow),
-                    count: rows.length,
+                    memories: ranked.map((item) => ({
+                        ...parseMemoryRow(item.row),
+                        matched_fields: item.matched_fields,
+                        recall_score: item.score,
+                    })),
+                    count: ranked.length,
+                    candidate_count: rows.length,
+                    recall_mode: "ranked_lexical",
                 };
             }
             catch (error) {
@@ -259,4 +305,64 @@ export function executeAgentMemory(db, params) {
             return { error: `Unknown action: ${params.action}` };
     }
 }
+/** Shape a lexical-only recall response (the default, provider-free path). */
+function lexicalRecallResult(ranked, candidateCount) {
+    return {
+        memories: ranked.map((item) => ({
+            ...parseMemoryRow(item.row),
+            matched_fields: item.matched_fields,
+            recall_score: item.score,
+        })),
+        count: ranked.length,
+        candidate_count: candidateCount,
+        recall_mode: "ranked_lexical",
+    };
+}
+/**
+ * Hybrid recall: blends alias-aware lexical scoring with cosine similarity over
+ * provider-backed embeddings. Embeddings are cached in the agent_memory table and
+ * backfilled lazily (capped per call). ANY failure to embed the query degrades to
+ * pure lexical recall, and recall_mode reports exactly which path produced the result.
+ */
+async function enhanceRecallWithSemantics(db, query, rows, limit, config) {
+    // Lexical baseline over ALL candidates — used for blending and as the fallback.
+    const lexical = rankRowsByRecall(rows, query, MEMORY_RECALL_FIELDS, rows.length);
+    const lexById = new Map();
+    for (const item of lexical)
+        lexById.set(item.row.id, item);
+    const maxLex = lexical.length ? lexical[0].score : 0;
+    const sem = await semanticScores(db, "agent_memory", query, rows.map((row) => ({ id: row.id, text: memoryEmbedText(row) })), config);
+    // Query could not be embedded -> the provider is effectively unavailable.
+    if (!sem.queryEmbedded) {
+        return {
+            ...lexicalRecallResult(lexical.slice(0, limit), rows.length),
+            semantic_note: "embedding provider unreachable — used lexical recall",
+        };
+    }
+    const blended = rows
+        .map((row) => {
+        const semantic = Math.max(0, sem.semanticById.get(row.id) ?? 0);
+        const lex = lexById.get(row.id);
+        const lexNorm = maxLex > 0 && lex ? lex.score / maxLex : 0;
+        const score = SEMANTIC_BLEND * semantic + (1 - SEMANTIC_BLEND) * lexNorm;
+        return { row, semantic, matched: lex?.matched_fields ?? [], score };
+    })
+        .filter((x) => x.score > 0)
+        .sort((a, b) => b.score - a.score)
+        .slice(0, limit);
+    return {
+        memories: blended.map((x) => ({
+            ...parseMemoryRow(x.row),
+            matched_fields: x.matched,
+            recall_score: Math.round(x.score * 1000) / 1000,
+            semantic_score: Math.round(x.semantic * 1000) / 1000,
+        })),
+        count: blended.length,
+        candidate_count: rows.length,
+        embedded_candidates: sem.embeddedCount,
+        newly_embedded: sem.newlyEmbedded,
+        embedding_model: sem.model,
+        recall_mode: sem.embeddedCount > 0 ? "hybrid" : "ranked_lexical",
+    };
+}
 //# sourceMappingURL=agent-memory.js.map

package/dist/tools/decision-enforcement.d.ts

@@ -4,6 +4,13 @@
  * The key tool AI agents call BEFORE suggesting major changes.
  * Checks if a technology or pattern aligns with the developer's active decisions.
  * Returns alignment status, relevant decisions, and any conflicts.
+ *
+ * Retrieval of "relevant decisions" is lexical by default and OPTIONALLY hybrid
+ * (semantic) when an embedding provider is configured — so a decision that is a
+ * paraphrase of the proposal surfaces even with no shared words. Hard conflict
+ * detection ("X was explicitly rejected") stays lexical/alias-aware so semantic
+ * similarity can never fabricate a grounded conflict; paraphrase risks are
+ * reported separately as `possible_conflicts`.
  */
 import type { FourDADatabase } from "../db.js";
 export interface CheckDecisionAlignmentParams {
@@ -24,13 +31,22 @@ interface DecisionConflict {
     subject: string;
     reason: string;
 }
+interface PossibleConflict {
+    decision_id: number;
+    subject: string;
+    similarity: number;
+    reason: string;
+}
 interface AlignmentResult {
     aligned: boolean;
     technology: string;
     relevant_decisions: RelevantDecision[];
     conflicts: DecisionConflict[];
+    /** Paraphrase risks: semantically close to a rejected alternative, not grounded. */
+    possible_conflicts: PossibleConflict[];
     confidence: number;
     recommendation: string;
+    recall_mode: "hybrid" | "ranked_lexical";
 }
 export declare const checkDecisionAlignmentTool: {
     name: string;
@@ -54,6 +70,6 @@ export declare const checkDecisionAlignmentTool: {
         required: string[];
     };
 };
-export declare function executeCheckDecisionAlignment(db: FourDADatabase, params: CheckDecisionAlignmentParams): AlignmentResult;
+export declare function executeCheckDecisionAlignment(db: FourDADatabase, params: CheckDecisionAlignmentParams): AlignmentResult | Promise<AlignmentResult>;
 export {};
 //# sourceMappingURL=decision-enforcement.d.ts.map

package/dist/tools/decision-enforcement.js

@@ -5,7 +5,17 @@
  * The key tool AI agents call BEFORE suggesting major changes.
  * Checks if a technology or pattern aligns with the developer's active decisions.
  * Returns alignment status, relevant decisions, and any conflicts.
+ *
+ * Retrieval of "relevant decisions" is lexical by default and OPTIONALLY hybrid
+ * (semantic) when an embedding provider is configured — so a decision that is a
+ * paraphrase of the proposal surfaces even with no shared words. Hard conflict
+ * detection ("X was explicitly rejected") stays lexical/alias-aware so semantic
+ * similarity can never fabricate a grounded conflict; paraphrase risks are
+ * reported separately as `possible_conflicts`.
  */
+import { matchesRecallQuery } from "./recall.js";
+import { getEmbeddingConfig } from "../embeddings.js";
+import { rankDecisionsLexical, hybridDecisionRecall, POSSIBLE_CONFLICT_THRESHOLD, } from "./decision-recall.js";
 // ============================================================================
 // Tool Definition
 // ============================================================================
@@ -34,100 +44,71 @@ export const checkDecisionAlignmentTool = {
 // ============================================================================
 // Helpers
 // ============================================================================
-/**
- * Search active decisions matching a given term against subject,
- * context_tags, and alternatives_rejected columns.
- */
-function searchActiveDecisions(rawDb, searchTerm) {
-    const pattern = `%${searchTerm.toLowerCase()}%`;
+/** Load active decisions (unranked); ranking/retrieval is layered on top. */
+function loadActiveDecisions(rawDb) {
     return rawDb
         .prepare(`SELECT id, decision_type, subject, decision, rationale,
               alternatives_rejected, context_tags, confidence,
               status, superseded_by, created_at, updated_at
        FROM developer_decisions
        WHERE status = 'active'
-         AND (LOWER(subject) LIKE ?
-           OR LOWER(context_tags) LIKE ?
-           OR LOWER(alternatives_rejected) LIKE ?)`)
-        .all(pattern, pattern, pattern);
+       ORDER BY updated_at DESC
+       LIMIT 500`)
+        .all();
+}
+function parseAlts(row) {
+    try {
+        return JSON.parse(row.alternatives_rejected || "[]");
+    }
+    catch {
+        return [];
+    }
 }
 /**
- * Classify a decision row's relationship to the queried technology.
+ * Classify a decision row's relationship to the queried technology. Hard
+ * conflicts require a literal/alias-aware match against rejected alternatives.
  */
 function classifyRelationship(row, tech) {
     const techLower = tech.toLowerCase();
-    const alts = JSON.parse(row.alternatives_rejected || "[]");
     // If the technology appears in rejected alternatives, it's a conflict
-    const isRejected = alts.some((alt) => alt.toLowerCase().includes(techLower));
+    const isRejected = parseAlts(row).some((alt) => matchesRecallQuery(alt, techLower));
     if (isRejected) {
         return "conflict";
     }
     // If the technology matches the decision subject, it's aligned
-    if (row.subject.toLowerCase().includes(techLower)) {
+    if (matchesRecallQuery(row.subject, techLower) ||
+        matchesRecallQuery(row.decision, techLower)) {
         return "aligned";
     }
     // Otherwise it's tangentially related
     return "related";
 }
-/**
- * Build a human-readable recommendation string.
- */
-function buildRecommendation(technology, conflicts, relevantCount) {
-    if (conflicts.length === 0) {
-        if (relevantCount === 0) {
-            return `No existing decisions found for '${technology}'. No conflicts detected — proceed with caution.`;
-        }
-        return `No conflicts found. Proceed with ${technology}.`;
+/** Build a human-readable recommendation string. */
+function buildRecommendation(technology, conflicts, relevantCount, possibleCount) {
+    if (conflicts.length > 0) {
+        const first = conflicts[0];
+        return (`CONFLICT: ${technology} was explicitly rejected. ` +
+            `Active decision: '${first.subject}' — ${first.reason}`);
     }
-    // Report the first (most relevant) conflict
-    const first = conflicts[0];
-    return (`CONFLICT: ${technology} was explicitly rejected. ` +
-        `Active decision: '${first.subject}' — ${first.reason}`);
-}
-// ============================================================================
-// Execute
-// ============================================================================
-export function executeCheckDecisionAlignment(db, params) {
-    const rawDb = db.getRawDb();
-    const { technology, pattern, context } = params;
-    // Collect all matching decision rows (deduplicated by id)
-    const seenIds = new Set();
-    const allRows = [];
-    try {
-        // Primary search: technology name
-        const techRows = searchActiveDecisions(rawDb, technology);
-        for (const row of techRows) {
-            if (!seenIds.has(row.id)) {
-                seenIds.add(row.id);
-                allRows.push(row);
-            }
-        }
-        // Secondary search: pattern (if provided)
-        if (pattern) {
-            const patternRows = searchActiveDecisions(rawDb, pattern);
-            for (const row of patternRows) {
-                if (!seenIds.has(row.id)) {
-                    seenIds.add(row.id);
-                    allRows.push(row);
-                }
-            }
-        }
+    if (possibleCount > 0) {
+        return (`No explicit conflict, but ${possibleCount} prior decision(s) are semantically ` +
+            `close to '${technology}' and rejected alternatives — review before proceeding.`);
     }
-    catch {
-        // Table may not exist yet — return a safe default
-        return {
-            aligned: true,
-            technology,
-            relevant_decisions: [],
-            conflicts: [],
-            confidence: 0.5,
-            recommendation: `No decision history available. The developer_decisions table may not exist yet. Proceed with ${technology}.`,
-        };
+    if (relevantCount === 0) {
+        return `No existing decisions found for '${technology}'. No conflicts detected — proceed with caution.`;
     }
-    // Classify each row
+    return `No conflicts found. Proceed with ${technology}.`;
+}
+/**
+ * Classify the retrieved decisions into aligned/conflict/related, derive hard and
+ * possible (paraphrase) conflicts, and assemble the alignment result. Shared by
+ * the lexical and hybrid retrieval paths.
+ */
+function assembleAlignment(params, rows, semanticById, recallMode) {
+    const { technology, pattern } = params;
     const relevantDecisions = [];
     const conflicts = [];
-    for (const row of allRows) {
+    for (const row of rows) {
         const relationship = classifyRelationship(row, technology);
         relevantDecisions.push({
             id: row.id,
@@ -138,8 +119,7 @@ export function executeCheckDecisionAlignment(db, params) {
             relationship,
         });
         if (relationship === "conflict") {
-            const alts = JSON.parse(row.alternatives_rejected || "[]");
-            const rejectedAlt = alts.find((alt) => alt.toLowerCase().includes(technology.toLowerCase()));
+            const rejectedAlt = parseAlts(row).find((alt) => matchesRecallQuery(alt, technology));
             conflicts.push({
                 decision_id: row.id,
                 subject: row.subject,
@@ -147,21 +127,17 @@ export function executeCheckDecisionAlignment(db, params) {
             });
         }
     }
-    // If pattern was provided but didn't surface via technology search,
-    // also check pattern against decision relationships
+    // Pattern rejected-alternative check (if a pattern was supplied separately).
     if (pattern) {
-        for (const row of allRows) {
-            const patternLower = pattern.toLowerCase();
-            const alts = JSON.parse(row.alternatives_rejected || "[]");
-            const patternRejected = alts.some((alt) => alt.toLowerCase().includes(patternLower));
-            if (patternRejected &&
-                !conflicts.some((c) => c.decision_id === row.id)) {
+        const patternLower = pattern.toLowerCase();
+        for (const row of rows) {
+            const patternRejected = parseAlts(row).some((alt) => matchesRecallQuery(alt, patternLower));
+            if (patternRejected && !conflicts.some((c) => c.decision_id === row.id)) {
                 conflicts.push({
                     decision_id: row.id,
                     subject: row.subject,
                     reason: `Pattern '${pattern}' was rejected in favor of '${row.decision}' (rationale: ${row.rationale || "none"})`,
                 });
-                // Update the relationship for this decision
                 const existing = relevantDecisions.find((d) => d.id === row.id);
                 if (existing && existing.relationship !== "conflict") {
                     existing.relationship = "conflict";
@@ -169,17 +145,69 @@ export function executeCheckDecisionAlignment(db, params) {
             }
         }
     }
+    // Possible (paraphrase) conflicts: semantically close to a decision that rejected
+    // alternatives, but NOT a literal match. Advisory only — never flips `aligned`.
+    const possibleConflicts = [];
+    for (const row of rows) {
+        const sim = semanticById.get(row.id) ?? 0;
+        if (sim < POSSIBLE_CONFLICT_THRESHOLD)
+            continue;
+        const alts = parseAlts(row);
+        if (alts.length === 0)
+            continue;
+        if (conflicts.some((c) => c.decision_id === row.id))
+            continue;
+        possibleConflicts.push({
+            decision_id: row.id,
+            subject: row.subject,
+            similarity: Math.round(sim * 1000) / 1000,
+            reason: `'${technology}' is semantically close (${Math.round(sim * 100)}%) to a decision that rejected: ${alts.join(", ")}. Review before proceeding.`,
+        });
+    }
     const maxConfidence = relevantDecisions.length > 0
         ? Math.max(...relevantDecisions.map((d) => d.confidence))
         : 0.5;
-    const recommendation = buildRecommendation(technology, conflicts, relevantDecisions.length);
     return {
         aligned: conflicts.length === 0,
         technology,
         relevant_decisions: relevantDecisions,
         conflicts,
+        possible_conflicts: possibleConflicts,
         confidence: maxConfidence,
-        recommendation,
+        recommendation: buildRecommendation(technology, conflicts, relevantDecisions.length, possibleConflicts.length),
+        recall_mode: recallMode,
     };
 }
+// ============================================================================
+// Execute
+// ============================================================================
+export function executeCheckDecisionAlignment(db, params) {
+    const rawDb = db.getRawDb();
+    let candidates;
+    try {
+        candidates = loadActiveDecisions(rawDb);
+    }
+    catch {
+        // developer_decisions table may not exist yet — safe default.
+        return {
+            aligned: true,
+            technology: params.technology,
+            relevant_decisions: [],
+            conflicts: [],
+            possible_conflicts: [],
+            confidence: 0.5,
+            recommendation: `No decision history available. The developer_decisions table may not exist yet. Proceed with ${params.technology}.`,
+            recall_mode: "ranked_lexical",
+        };
+    }
+    const query = [params.technology, params.pattern].filter(Boolean).join(" ");
+    const config = getEmbeddingConfig();
+    // No provider -> synchronous lexical retrieval (classic behaviour).
+    if (!config) {
+        const rows = rankDecisionsLexical(candidates, query, 50);
+        return assembleAlignment(params, rows, new Map(), "ranked_lexical");
+    }
+    // Provider configured -> hybrid retrieval (returns a Promise; dispatch awaits).
+    return hybridDecisionRecall(db, query, candidates, 50, config).then(({ ranked, semanticById, recall_mode }) => assembleAlignment(params, ranked, semanticById, recall_mode));
+}
 //# sourceMappingURL=decision-enforcement.js.map