agent-recall-core 3.4.31 → 3.4.35

package/dist/helpers/blind-spots.js

@@ -0,0 +1,205 @@
+/**
+ * blind-spots.ts — auto-derive the user's behavioral profile from accumulated
+ * corrections (Wave 5, Decision #8).
+ *
+ * Memory becoming understanding: corrections are not one input among many —
+ * their ACCUMULATION reveals recurring tendencies ("Blind Spots") the system can
+ * warn about BEFORE the user has to correct again. This module is the pure
+ * derivation step; persistence lives in storage/blind-spots-store.ts and the
+ * prediction lives in tools-logic/predict-correction.ts.
+ *
+ * Reuses `extractKeywords` + `cleanRule` from the alignment-patterns grammar —
+ * does NOT fork the matching grammar (clustering must agree with watch_for).
+ * Pure, no LLM, no IO.
+ */
+import { extractKeywords } from "./auto-name.js";
+import { cleanRule } from "./alignment-patterns.js";
+import { tokenize, overlap } from "../tools-logic/check-action.js";
+import { semanticSimilarity, blindSpotConcepts } from "./semantic-match.js";
+const P0_RE = /\bnever\b|\balways\b|\bdon'?t\b|\bdo not\b|\bmust not\b|\bforbid\b|\bprohibit\b/i;
+/** Default exact trigger-keyword overlap floor for a blind spot to fire (Loop 3 path). */
+export const BLIND_SPOT_MIN_OVERLAP = 2;
+/**
+ * Default LOCAL semantic-similarity floor (Loop 5). When exact keyword overlap is
+ * below {@link BLIND_SPOT_MIN_OVERLAP}, a blind spot still fires if the situation
+ * is semantically similar to its concept text at or above this threshold.
+ *
+ * TUNED on the real ~/.agent-recall corpus (scripts/eval/predict-loo.mjs --both):
+ * the keyword baseline fires 0/13 (0% recall). The local semantic path lifts that
+ * to 2/13 (15.4% recall) at this threshold while the false-positive rate on
+ * unrelated NEGATIVE pairs stays exactly 0% (0/22). This is the HIGHEST-recall
+ * point with zero FP — the conservative choice. The next step down (0.19) reaches
+ * 3/13 (23.1%) but at 4.5% FP, and FP climbs to 22.7% by 0.14; recall gains that
+ * also fire on unrelated pairs are noise, so we hold the zero-FP line. On the
+ * controlled zero-overlap paraphrase instrument (scripts/eval/paraphrase-
+ * robustness.mjs) this threshold fires 100% (vs 0% for the keyword path), proving
+ * the path is genuinely semantic, not lexical luck.
+ */
+export const BLIND_SPOT_SEMANTIC_THRESHOLD = 0.20;
+/**
+ * Decide whether a free-text SITUATION resembles a blind spot — the single
+ * matching grammar shared by predict-correction.ts and the LOO eval, so both
+ * score identically (no fork).
+ *
+ * FLOOR: exact trigger-keyword overlap >= minOverlap (the Loop 3 path, unchanged).
+ * WIDEN: when the floor fails, a LOCAL semantic-similarity score (stemming +
+ * concept map + char-trigram cosine over the blind spot's tendency/example/triggers)
+ * at or above semanticThreshold fires the risk. NO API key, NO network.
+ */
+export function matchesBlindSpot(situation, bs, minOverlap = BLIND_SPOT_MIN_OVERLAP, semanticThreshold = BLIND_SPOT_SEMANTIC_THRESHOLD) {
+    const sitTokens = tokenize(situation);
+    const triggerSet = new Set((bs.trigger_keywords ?? []).map((k) => k.toLowerCase()));
+    const matched = overlap(sitTokens, triggerSet);
+    if (matched.length >= minOverlap) {
+        return { fired: true, via: "keyword", matched, semanticScore: 0 };
+    }
+    const semanticScore = semanticSimilarity(situation, blindSpotConcepts(bs));
+    if (semanticScore >= semanticThreshold) {
+        return { fired: true, via: "semantic", matched, semanticScore };
+    }
+    return { fired: false, via: null, matched, semanticScore };
+}
+/** Number of cleaned keywords to extract per signal for clustering. */
+const KW_PER_SIGNAL = 4;
+/** A non-P0 cluster needs this much keyword overlap to bind. */
+const MIN_SHARED_KEYWORDS = 2;
+function normalizeCorrection(c) {
+    const rule = cleanRule(c.rule ?? "");
+    return {
+        rule,
+        severity: c.severity === "p0" ? "p0" : "p1",
+        keywords: extractKeywords(rule, KW_PER_SIGNAL),
+        date: c.date ?? "",
+        recurrence: c.recurrence_count ?? 0,
+    };
+}
+/**
+ * Alignment-log entries carry the raw correction in `corrections: string[]`
+ * and/or `delta` (Was:/Correction: format). Both flow through `cleanRule`.
+ */
+function normalizeAlignment(a) {
+    const out = [];
+    const raws = [...(a.corrections ?? [])];
+    if (a.delta)
+        raws.push(a.delta);
+    for (const raw of raws) {
+        const rule = cleanRule(raw);
+        if (!rule || rule.length < 4)
+            continue;
+        out.push({
+            rule,
+            severity: P0_RE.test(rule) ? "p0" : "p1",
+            keywords: extractKeywords(rule, KW_PER_SIGNAL),
+            date: a.date ?? "",
+            recurrence: 0,
+        });
+    }
+    return out;
+}
+/** Count how many keywords two signals share (substring-tolerant, mirrors check.ts). */
+function sharedKeywords(a, b) {
+    const hits = new Set();
+    for (const k of a) {
+        if (b.some((bk) => bk === k || bk.includes(k) || k.includes(bk)))
+            hits.add(k);
+    }
+    return [...hits];
+}
+/**
+ * Cluster correction + alignment signals into Blind Spots.
+ *
+ * Clustering rule: greedily seed clusters from the strongest signals; a signal
+ * joins a cluster when it shares ≥2 keywords with the seed (≥1 if either is P0).
+ * A lone P0 signal still produces a Blind Spot (the >=1-if-P0 rule) — P0
+ * corrections are too important to need three repetitions before warning.
+ */
+export function deriveBlindSpots(corrections, alignmentLog) {
+    const signals = [];
+    for (const c of corrections ?? []) {
+        if (c.active === false)
+            continue;
+        const s = normalizeCorrection(c);
+        if (s.keywords.length === 0)
+            continue;
+        signals.push(s);
+    }
+    for (const a of alignmentLog ?? []) {
+        for (const s of normalizeAlignment(a)) {
+            if (s.keywords.length === 0)
+                continue;
+            signals.push(s);
+        }
+    }
+    // Seed order: P0 first, then by recurrence, then by keyword richness — so the
+    // strongest tendency anchors its cluster's signature.
+    const ordered = [...signals].sort((x, y) => {
+        if (x.severity !== y.severity)
+            return x.severity === "p0" ? -1 : 1;
+        if (y.recurrence !== x.recurrence)
+            return y.recurrence - x.recurrence;
+        return y.keywords.length - x.keywords.length;
+    });
+    const used = new Set();
+    const clusters = [];
+    for (let i = 0; i < ordered.length; i++) {
+        if (used.has(i))
+            continue;
+        const seed = ordered[i];
+        const cluster = [seed];
+        used.add(i);
+        for (let j = i + 1; j < ordered.length; j++) {
+            if (used.has(j))
+                continue;
+            const cand = ordered[j];
+            const shared = sharedKeywords(seed.keywords, cand.keywords);
+            const threshold = seed.severity === "p0" || cand.severity === "p0" ? 1 : MIN_SHARED_KEYWORDS;
+            if (shared.length >= threshold) {
+                cluster.push(cand);
+                used.add(j);
+            }
+        }
+        clusters.push(cluster);
+    }
+    const blindSpots = [];
+    for (const cluster of clusters) {
+        const seed = cluster[0];
+        const isP0 = cluster.some((s) => s.severity === "p0");
+        // Non-P0 clusters need ≥2 members to count as a tendency; a single P0 counts.
+        if (!isP0 && cluster.length < 2)
+            continue;
+        // Trigger keywords = keywords shared by the largest share of the cluster.
+        const kwCount = new Map();
+        for (const s of cluster) {
+            for (const k of new Set(s.keywords))
+                kwCount.set(k, (kwCount.get(k) ?? 0) + 1);
+        }
+        const triggerKeywords = [...kwCount.entries()]
+            .filter(([, n]) => n >= 2 || cluster.length === 1)
+            .sort((a, b) => b[1] - a[1])
+            .map(([k]) => k)
+            .slice(0, 5);
+        // Fall back to the seed's own keywords if nothing was shared by ≥2 members
+        // (happens for a lone P0). Guarantee at least the seed keywords surface.
+        const finalKeywords = triggerKeywords.length > 0 ? triggerKeywords : seed.keywords.slice(0, 3);
+        const lastSeen = cluster.reduce((acc, s) => (s.date > acc ? s.date : acc), "");
+        blindSpots.push({
+            tendency: seed.rule,
+            evidence_count: cluster.length,
+            severity: isP0 ? "p0" : "p1",
+            trigger_keywords: finalKeywords,
+            example_rule: seed.rule,
+            last_seen: lastSeen,
+        });
+    }
+    // Strongest evidence first; P0 outranks P1 on a tie.
+    blindSpots.sort((a, b) => {
+        if (a.severity !== b.severity)
+            return a.severity === "p0" ? -1 : 1;
+        return b.evidence_count - a.evidence_count;
+    });
+    return {
+        derived_at: new Date().toISOString(),
+        blind_spots: blindSpots,
+    };
+}
+//# sourceMappingURL=blind-spots.js.map

package/dist/helpers/blind-spots.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"blind-spots.js","sourceRoot":"","sources":["../../src/helpers/blind-spots.ts"],"names":[],"mappings":"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"}

package/dist/helpers/conflict-scan.d.ts

@@ -23,6 +23,16 @@ export interface ConflictScanResult {
     hasConflict: boolean;
     matches: ConflictMatch[];
 }
+/** Extract semver-style version tokens: "1.2.3", "v1.2.3", "version 1.2.3" */
+export declare function extractVersionTokens(text: string): Map<string, string>;
+/** Return [statusWord, category] pairs found in text. */
+export declare function extractStatusTokens(text: string): Map<string, string>;
+/**
+ * Extract key-value pairs from patterns like:
+ *   "status: blocked", "version is 3.4.1", "env = production"
+ * Returns a Map<normalised_key, value>.
+ */
+export declare function extractKVTokens(text: string): Map<string, string>;
 /**
  * Scan existing memories for conflicts with newContent.
  *

package/dist/helpers/conflict-scan.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"conflict-scan.d.ts","sourceRoot":"","sources":["../../src/helpers/conflict-scan.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAQH,MAAM,WAAW,aAAa;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,EAAE,MAAM,CAAC;IACrB,iBAAiB,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAC7D;AAED,MAAM,WAAW,kBAAkB;IACjC,WAAW,EAAE,OAAO,CAAC;IACrB,OAAO,EAAE,aAAa,EAAE,CAAC;CAC1B;AA+ED;;;;;;;GAOG;AACH,wBAAsB,gBAAgB,CACpC,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,GAAG,SAAS,GAC1B,OAAO,CAAC,kBAAkB,CAAC,CA6F7B;AAMD;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,aAAa,EAAE,EACxB,OAAO,EAAE,MAAM,GAAG,SAAS,GAC1B,MAAM,CAeR"}
+{"version":3,"file":"conflict-scan.d.ts","sourceRoot":"","sources":["../../src/helpers/conflict-scan.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAQH,MAAM,WAAW,aAAa;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,EAAE,MAAM,CAAC;IACrB,iBAAiB,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAC7D;AAED,MAAM,WAAW,kBAAkB;IACjC,WAAW,EAAE,OAAO,CAAC;IACrB,OAAO,EAAE,aAAa,EAAE,CAAC;CAC1B;AAMD,8EAA8E;AAC9E,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAYtE;AAWD,yDAAyD;AACzD,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAUrE;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAyBjE;AAMD;;;;;;;GAOG;AACH,wBAAsB,gBAAgB,CACpC,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,GAAG,SAAS,GAC1B,OAAO,CAAC,kBAAkB,CAAC,CA6F7B;AAMD;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,aAAa,EAAE,EACxB,OAAO,EAAE,MAAM,GAAG,SAAS,GAC1B,MAAM,CAeR"}

package/dist/helpers/conflict-scan.js

@@ -14,7 +14,7 @@ import { smartRecall } from "../tools-logic/smart-recall.js";
 // Token extractors
 // ---------------------------------------------------------------------------
 /** Extract semver-style version tokens: "1.2.3", "v1.2.3", "version 1.2.3" */
-function extractVersionTokens(text) {
+export function extractVersionTokens(text) {
     const result = new Map();
     // Capture the word/context before the version number as the key
     const pattern = /(\w[\w.-]{0,30})\s*(?:v|@|version\s+)?(\d+\.\d+\.\d+)/gi;
@@ -36,7 +36,7 @@ const STATUS_WORD_MAP = {
     pending: "pending",
 };
 /** Return [statusWord, category] pairs found in text. */
-function extractStatusTokens(text) {
+export function extractStatusTokens(text) {
     const result = new Map();
     const lower = text.toLowerCase();
     for (const [word, category] of Object.entries(STATUS_WORD_MAP)) {
@@ -52,7 +52,7 @@ function extractStatusTokens(text) {
  *   "status: blocked", "version is 3.4.1", "env = production"
  * Returns a Map<normalised_key, value>.
  */
-function extractKVTokens(text) {
+export function extractKVTokens(text) {
     const result = new Map();
     // "key: value" or "key = value"
     const colonEq = /\b([\w][\w -]{0,30})\s*[:=]\s*([^\s,;.!?\n]{1,50})/g;

package/dist/helpers/conflict-scan.js.map

@@ -1 +1 @@
-{"version":3,"file":"conflict-scan.js","sourceRoot":"","sources":["../../src/helpers/conflict-scan.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"conflict-scan.js","sourceRoot":"","sources":["../../src/helpers/conflict-scan.ts"],"names":[],"mappings":"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"}

package/dist/helpers/semantic-match.d.ts

@@ -0,0 +1,82 @@
+/**
+ * semantic-match.ts — LOCAL, zero-key, zero-network semantic similarity (Loop 5).
+ *
+ * WHY THIS EXISTS — Loop 3 measured the keyword predictor at an honest 0/13 on
+ * the real corpus: of the 13 predictable corrections, 11 had ZERO lead-in↔trigger
+ * token overlap and the other 2 maxed at 1 (below the MIN_OVERLAP=2 floor). The
+ * relationship between a situation ("renaming the npm package and the README")
+ * and the resolution it will provoke ("Rename everything to Novada Proxy") is
+ * SEMANTIC, not lexical — different surface words, same concept.
+ *
+ * This module restores AgentRecall's local-by-default identity: NO OPENAI_API_KEY,
+ * NO network, NO per-call LLM. It bridges vocabularies with three cheap, pure
+ * signals over the situation text vs a blind-spot's trigger keywords:
+ *
+ *   1. LIGHT STEMMING — collapse morphology (publish/published/publishing,
+ *      rename/renaming, customer/customers) so inflected forms match.
+ *   2. SYNONYM / CONCEPT EXPANSION — a small built-in map keyed to the recurring
+ *      AgentRecall domains (publish↔ship↔release, secret↔key↔token↔credential,
+ *      name↔rename↔naming, approval↔permission, codex↔sonnet↔agent). This is the
+ *      actual bridge between a situation's verbs and a resolution's nouns.
+ *   3. CHARACTER-TRIGRAM COSINE — fuzzy overlap that catches shared roots and
+ *      near-spellings even when whole stems differ.
+ *
+ * The combined score is `max(stemmed token-set cosine, char-trigram cosine)`
+ * over the SYNONYM-EXPANDED stem sets — a value in [0,1]. Callers compare it to a
+ * threshold to decide whether a risk fires.
+ *
+ * Pure, deterministic, no IO. The heavy lifting (set construction) is O(tokens);
+ * any precompute a caller wants belongs at write/consolidation time, not here.
+ */
+/**
+ * Stem a single lowercased token. Applies the first matching suffix rule, then a
+ * light "double consonant" fixup so e.g. `renam` (from `renaming`) collapses with
+ * `rename` by re-adding a trailing `e` when the stem ends in a consonant cluster
+ * that commonly drops an `e`. Deterministic and dependency-free.
+ */
+export declare function stem(token: string): string;
+/** Stem every token in a set, returning a new stemmed set. */
+export declare function stemSet(tokens: Set<string>): Set<string>;
+/**
+ * Canonicalize a stemmed token set into CONCEPT space: every token that belongs
+ * to a synonym group is REPLACED by its shared concept token (`__concept_<g>`);
+ * tokens with no concept pass through unchanged. Collapsing synonyms onto one
+ * shared dimension (rather than appending a marker alongside the surface stems)
+ * is what lets "publish package npm" and "ship release registry" overlap
+ * meaningfully — both reduce to the same `__concept_0`, so the cosine sees a real
+ * shared term instead of a diluted one. That is the semantic bridge.
+ */
+export declare function expandConcepts(stems: Set<string>): Set<string>;
+/** Set-cosine over two token sets (binary term vectors): |A∩B| / sqrt(|A|·|B|). */
+export declare function setCosine(a: Set<string>, b: Set<string>): number;
+/** Character trigrams of a token set's joined text (fuzzy root/near-spelling overlap). */
+export declare function charTrigrams(tokens: Set<string>): Set<string>;
+/**
+ * The local semantic similarity in [0,1] between a SITUATION text and a
+ * blind-spot's matching MATERIAL (free text: its tendency / example rule and its
+ * trigger keywords joined together). Both sides are tokenized with the production
+ * grammar, stemmed, and concept-expanded; the score is the MAX of the expanded
+ * token-set cosine and the character-trigram cosine. Pure and deterministic.
+ *
+ * Passing the blind spot's full text (not just its sparse trigger_keywords) is
+ * what gives the semantic path material to work with — Loop 3's diagnostic showed
+ * trigger_keywords are frequently EMPTY for the predictable cases, so matching on
+ * keywords alone reproduces the 0/13. The richer text is the seed rule the
+ * correction was about, which DOES carry concept-bearing words.
+ *
+ * @param situation       free-text plan / lead-in (the situation the agent is in)
+ * @param blindSpotText   the blind spot's tendency / example_rule + trigger keywords
+ */
+export declare function semanticSimilarity(situation: string, blindSpotText: string): number;
+/**
+ * Build the semantic matching MATERIAL for a blind spot: its concept-bearing
+ * tendency / example rule text plus its trigger keywords, joined into one string.
+ * Centralizes what "the blind spot's text" means so production code and the LOO
+ * harness score the SAME way (no fork — the harness imports this).
+ */
+export declare function blindSpotConcepts(bs: {
+    tendency?: string;
+    example_rule?: string;
+    trigger_keywords?: string[];
+}): string;
+//# sourceMappingURL=semantic-match.d.ts.map

package/dist/helpers/semantic-match.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"semantic-match.d.ts","sourceRoot":"","sources":["../../src/helpers/semantic-match.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAsCH;;;;;GAKG;AACH,wBAAgB,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAqB1C;AAED,8DAA8D;AAC9D,wBAAgB,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,GAAG,CAAC,MAAM,CAAC,CAIxD;AAmDD;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,GAAG,CAAC,MAAM,CAAC,CAO9D;AAMD,mFAAmF;AACnF,wBAAgB,SAAS,CAAC,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,MAAM,CAMhE;AAED,0FAA0F;AAC1F,wBAAgB,YAAY,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,GAAG,CAAC,MAAM,CAAC,CAO7D;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,MAAM,CAenF;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,EAAE,EAAE;IACpC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;CAC7B,GAAG,MAAM,CAGT"}

package/dist/helpers/semantic-match.js

@@ -0,0 +1,229 @@
+/**
+ * semantic-match.ts — LOCAL, zero-key, zero-network semantic similarity (Loop 5).
+ *
+ * WHY THIS EXISTS — Loop 3 measured the keyword predictor at an honest 0/13 on
+ * the real corpus: of the 13 predictable corrections, 11 had ZERO lead-in↔trigger
+ * token overlap and the other 2 maxed at 1 (below the MIN_OVERLAP=2 floor). The
+ * relationship between a situation ("renaming the npm package and the README")
+ * and the resolution it will provoke ("Rename everything to Novada Proxy") is
+ * SEMANTIC, not lexical — different surface words, same concept.
+ *
+ * This module restores AgentRecall's local-by-default identity: NO OPENAI_API_KEY,
+ * NO network, NO per-call LLM. It bridges vocabularies with three cheap, pure
+ * signals over the situation text vs a blind-spot's trigger keywords:
+ *
+ *   1. LIGHT STEMMING — collapse morphology (publish/published/publishing,
+ *      rename/renaming, customer/customers) so inflected forms match.
+ *   2. SYNONYM / CONCEPT EXPANSION — a small built-in map keyed to the recurring
+ *      AgentRecall domains (publish↔ship↔release, secret↔key↔token↔credential,
+ *      name↔rename↔naming, approval↔permission, codex↔sonnet↔agent). This is the
+ *      actual bridge between a situation's verbs and a resolution's nouns.
+ *   3. CHARACTER-TRIGRAM COSINE — fuzzy overlap that catches shared roots and
+ *      near-spellings even when whole stems differ.
+ *
+ * The combined score is `max(stemmed token-set cosine, char-trigram cosine)`
+ * over the SYNONYM-EXPANDED stem sets — a value in [0,1]. Callers compare it to a
+ * threshold to decide whether a risk fires.
+ *
+ * Pure, deterministic, no IO. The heavy lifting (set construction) is O(tokens);
+ * any precompute a caller wants belongs at write/consolidation time, not here.
+ */
+import { tokenize } from "../tools-logic/check-action.js";
+// ───────────────────────────────────────────────────────────────────────────
+// Light Porter-ish stemming — strips common English suffixes. NOT a full Porter
+// stemmer (no library dependency); just enough to collapse the inflections that
+// actually appear in corrections. Order matters: longest/most-specific first.
+// ───────────────────────────────────────────────────────────────────────────
+/** Suffix rules applied in order; first match wins. Each only fires above a min stem length. */
+const STEM_RULES = [
+    { suffix: "ization", minLen: 9, replace: "ize" }, // tokenization -> tokenize
+    { suffix: "iveness", minLen: 9 },
+    { suffix: "fulness", minLen: 9 },
+    { suffix: "ousness", minLen: 9 },
+    { suffix: " ", minLen: 99 }, // (never; placeholder kept out of hot path)
+    { suffix: " ", minLen: 99 },
+    { suffix: "ements", minLen: 8 },
+    { suffix: "ables", minLen: 7 },
+    { suffix: " ", minLen: 99 },
+    { suffix: "ement", minLen: 7 },
+    { suffix: "ation", minLen: 7, replace: "ate" }, // deprecation -> deprecate
+    { suffix: "ingly", minLen: 7 },
+    { suffix: "edly", minLen: 6 },
+    { suffix: "ings", minLen: 6 }, // renamings -> renam (then -> rename via 'e' add below) — handled by 'ing'
+    { suffix: "ies", minLen: 5, replace: "y" }, // dependencies -> dependency
+    { suffix: "ied", minLen: 5, replace: "y" },
+    { suffix: "ing", minLen: 5 }, // renaming -> renam ; publishing -> publish
+    { suffix: "ers", minLen: 5 }, // builders -> build
+    { suffix: "er", minLen: 5 }, // builder -> build (guarded by len so 'user' stays)
+    { suffix: "ses", minLen: 5 }, // accesses -> acces -> (handled)
+    { suffix: "es", minLen: 4 }, // changes -> chang ; aliases -> alias (len-guarded)
+    { suffix: "ed", minLen: 4 }, // renamed -> renam ; changed -> chang
+    { suffix: "ly", minLen: 5 }, // explicitly -> explicit
+    { suffix: "s", minLen: 4 }, // customers -> customer ; tokens -> token
+];
+/**
+ * Stem a single lowercased token. Applies the first matching suffix rule, then a
+ * light "double consonant" fixup so e.g. `renam` (from `renaming`) collapses with
+ * `rename` by re-adding a trailing `e` when the stem ends in a consonant cluster
+ * that commonly drops an `e`. Deterministic and dependency-free.
+ */
+export function stem(token) {
+    let t = token;
+    for (const rule of STEM_RULES) {
+        if (rule.minLen >= 99)
+            continue;
+        if (t.length >= rule.minLen && t.endsWith(rule.suffix)) {
+            t = t.slice(0, t.length - rule.suffix.length) + (rule.replace ?? "");
+            break;
+        }
+    }
+    // Collapse a doubled trailing consonant (running -> runn -> run).
+    if (t.length > 3 && /([^aeiou])\1$/.test(t))
+        t = t.slice(0, -1);
+    // Re-add a dropped silent 'e' for common verb stems so the -ing/-ed form and the
+    // bare form converge (renam->rename, declar->declare). Only when the stem ends in
+    // a consonant preceded by a vowel-consonant and is a plausible verb root length.
+    if (t.length >= 4 && /[bcdfgklmnprstvz]$/.test(t) && /[aeiou][^aeiou]$/.test(t)) {
+        // heuristic: nam->name, renam->rename, declar->declare. Add 'e' to canonicalize.
+        // Guarded against words that should stay bare by only firing for endings that
+        // frequently dropped an 'e' before -ing/-ed (a small, deterministic allowlist).
+        if (/(?:am|ar|at|iz|ut|os|us|iv|ac|ic|ag|ap|ip|op|ur)$/.test(t))
+            t = t + "e";
+    }
+    return t;
+}
+/** Stem every token in a set, returning a new stemmed set. */
+export function stemSet(tokens) {
+    const out = new Set();
+    for (const t of tokens)
+        out.add(stem(t));
+    return out;
+}
+// ───────────────────────────────────────────────────────────────────────────
+// Synonym / concept groups — the bridge between situation verbs and resolution
+// nouns. Each group is a set of STEMS that should be treated as the same concept.
+// Kept small and domain-grounded (the AgentRecall correction corpus): publishing,
+// naming, secrets, approval, agents, products/memory. Adding a group widens
+// recall; a too-broad group risks false positives, so groups stay tight.
+// ───────────────────────────────────────────────────────────────────────────
+const SYNONYM_GROUPS = [
+    // ship / release / deploy / publish — the most common situation→correction bridge.
+    ["publish", "ship", "release", "deploy", "push", "launch", "npm", "version",
+        "bump", "registry", "rollout", "roll", "artifact"],
+    // naming / rename / identity-of-a-thing.
+    ["name", "rename", "naming", "title", "label", "brand", "rebrand", "heading",
+        "docs", "readme"],
+    // secrets / credentials / keys.
+    ["secret", "key", "token", "credential", "api-key", "apikey", "auth",
+        "password", "vault"],
+    // permission / approval / gating.
+    ["approval", "approve", "permission", "permit", "gate", "consent", "confirm",
+        "explicit"],
+    // agents / models / orchestration (codex/sonnet/opus context).
+    ["codex", "sonnet", "opus", "agent", "subagent", "sub-agent", "orchestrate",
+        "model", "prompt", "instruction"],
+    // customer / user / buyer.
+    ["customer", "user", "buyer", "client", "visitor"],
+    // memory / understanding / recall (the product itself).
+    ["memory", "understand", "recall", "remember", "knowledge", "context"],
+    // compliance / safety / risk.
+    ["compliance", "compliant", "safety", "safe", "risk", "secure", "security"],
+    // build / scratch / reuse.
+    ["build", "create", "make", "implement", "scratch", "reuse", "port", "offer",
+        "product"],
+    // email / contact / inbox.
+    ["email", "inbox", "contact", "mail", "alias"],
+    // price / cost / margin / economics.
+    ["cost", "margin", "price", "pricing", "economics", "spread", "basis", "expose"],
+    // config / settings / store / environment.
+    ["config", "settings", "store", "environment", "env", "live", "production"],
+    // detail / thorough / explicit-text.
+    ["detailed", "thorough", "detail", "explicit", "verbose"],
+];
+/** stem -> canonical concept id (index into SYNONYM_GROUPS). Built once at module load. */
+const CONCEPT_OF = new Map();
+for (let g = 0; g < SYNONYM_GROUPS.length; g++) {
+    for (const w of SYNONYM_GROUPS[g])
+        CONCEPT_OF.set(stem(w), g);
+}
+/**
+ * Canonicalize a stemmed token set into CONCEPT space: every token that belongs
+ * to a synonym group is REPLACED by its shared concept token (`__concept_<g>`);
+ * tokens with no concept pass through unchanged. Collapsing synonyms onto one
+ * shared dimension (rather than appending a marker alongside the surface stems)
+ * is what lets "publish package npm" and "ship release registry" overlap
+ * meaningfully — both reduce to the same `__concept_0`, so the cosine sees a real
+ * shared term instead of a diluted one. That is the semantic bridge.
+ */
+export function expandConcepts(stems) {
+    const out = new Set();
+    for (const t of stems) {
+        const g = CONCEPT_OF.get(t);
+        out.add(g !== undefined ? `__concept_${g}` : t);
+    }
+    return out;
+}
+// ───────────────────────────────────────────────────────────────────────────
+// Cosine similarities
+// ───────────────────────────────────────────────────────────────────────────
+/** Set-cosine over two token sets (binary term vectors): |A∩B| / sqrt(|A|·|B|). */
+export function setCosine(a, b) {
+    if (a.size === 0 || b.size === 0)
+        return 0;
+    let inter = 0;
+    const [small, large] = a.size <= b.size ? [a, b] : [b, a];
+    for (const t of small)
+        if (large.has(t))
+            inter++;
+    return inter / Math.sqrt(a.size * b.size);
+}
+/** Character trigrams of a token set's joined text (fuzzy root/near-spelling overlap). */
+export function charTrigrams(tokens) {
+    const out = new Set();
+    for (const tok of tokens) {
+        const s = `  ${tok} `;
+        for (let i = 0; i + 3 <= s.length; i++)
+            out.add(s.slice(i, i + 3));
+    }
+    return out;
+}
+/**
+ * The local semantic similarity in [0,1] between a SITUATION text and a
+ * blind-spot's matching MATERIAL (free text: its tendency / example rule and its
+ * trigger keywords joined together). Both sides are tokenized with the production
+ * grammar, stemmed, and concept-expanded; the score is the MAX of the expanded
+ * token-set cosine and the character-trigram cosine. Pure and deterministic.
+ *
+ * Passing the blind spot's full text (not just its sparse trigger_keywords) is
+ * what gives the semantic path material to work with — Loop 3's diagnostic showed
+ * trigger_keywords are frequently EMPTY for the predictable cases, so matching on
+ * keywords alone reproduces the 0/13. The richer text is the seed rule the
+ * correction was about, which DOES carry concept-bearing words.
+ *
+ * @param situation       free-text plan / lead-in (the situation the agent is in)
+ * @param blindSpotText   the blind spot's tendency / example_rule + trigger keywords
+ */
+export function semanticSimilarity(situation, blindSpotText) {
+    const sitTokens = tokenize(situation);
+    const bsTokens = tokenize(blindSpotText);
+    if (sitTokens.size === 0 || bsTokens.size === 0)
+        return 0;
+    const sitStem = stemSet(sitTokens);
+    const bsStem = stemSet(bsTokens);
+    const sitExp = expandConcepts(sitStem);
+    const bsExp = expandConcepts(bsStem);
+    const tokenCos = setCosine(sitExp, bsExp);
+    const triCos = setCosine(charTrigrams(sitStem), charTrigrams(bsStem));
+    return Math.max(tokenCos, triCos);
+}
+/**
+ * Build the semantic matching MATERIAL for a blind spot: its concept-bearing
+ * tendency / example rule text plus its trigger keywords, joined into one string.
+ * Centralizes what "the blind spot's text" means so production code and the LOO
+ * harness score the SAME way (no fork — the harness imports this).
+ */
+export function blindSpotConcepts(bs) {
+    const parts = [bs.tendency ?? "", bs.example_rule ?? "", ...(bs.trigger_keywords ?? [])];
+    return parts.filter(Boolean).join(" ");
+}
+//# sourceMappingURL=semantic-match.js.map

package/dist/helpers/semantic-match.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"semantic-match.js","sourceRoot":"","sources":["../../src/helpers/semantic-match.ts"],"names":[],"mappings":"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"}