agent-recall-core 3.4.30 → 3.4.35

package/dist/tools-logic/predict-correction.d.ts

@@ -0,0 +1,47 @@
+/**
+ * predict-correction.ts — the north-star: anticipate a correction BEFORE the
+ * user makes it (Wave 5, Decision #8).
+ *
+ * Given a plan, overlap its tokens against the corrections-derived Blind-Spots
+ * profile. A fired risk means "this plan resembles a tendency you have been
+ * corrected on" — pushed as an EARLY prior at session_start / check(), not a
+ * RAG fact pulled late. Synchronous (Decision #3 — retrieval is a function, no
+ * spawned per-call agent). Reuses the exported tokenize/overlap grammar from
+ * check-action (Wave 4) — does NOT fork it.
+ */
+export interface PredictCorrectionInput {
+    /** The plan / action / goal text to evaluate. */
+    plan: string;
+    project?: string;
+}
+export interface PredictedRisk {
+    /** The tendency this plan resembles. */
+    tendency: string;
+    /** Normalized risk score for this single tendency (0–1). */
+    score: number;
+    /** The plan tokens that matched the tendency's trigger keywords. */
+    matched: string[];
+    /** Correction id this risk is anchored to (for outcome instrumentation). */
+    correction_id?: string;
+    severity: "p0" | "p1";
+}
+export interface PredictCorrectionResult {
+    /** High-threshold-first likelihood band. */
+    likelihood: "high" | "medium" | "low";
+    /** Top fired risks (capped). */
+    top_risks: PredictedRisk[];
+    /** Blind-spot tendencies that matched (for orientation display). */
+    matched_blind_spots: string[];
+    /** A single actionable guard line the agent can act on, or null. */
+    suggested_guard: string | null;
+}
+/**
+ * LOCAL semantic-similarity floor for a risk to fire when the keyword path does
+ * NOT (Loop 5). Re-exported from blind-spots.ts (the single matching grammar) so
+ * production and the LOO eval share ONE threshold. Tuned on the real corpus to
+ * balance recall against false positives on unrelated pairs. No API key, no
+ * network — pure stemming + concept map + char-trigram cosine.
+ */
+export declare const SEMANTIC_THRESHOLD = 0.2;
+export declare function predictCorrection(input: PredictCorrectionInput): Promise<PredictCorrectionResult>;
+//# sourceMappingURL=predict-correction.d.ts.map

package/dist/tools-logic/predict-correction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"predict-correction.d.ts","sourceRoot":"","sources":["../../src/tools-logic/predict-correction.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAQH,MAAM,WAAW,sBAAsB;IACrC,iDAAiD;IACjD,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,aAAa;IAC5B,wCAAwC;IACxC,QAAQ,EAAE,MAAM,CAAC;IACjB,4DAA4D;IAC5D,KAAK,EAAE,MAAM,CAAC;IACd,oEAAoE;IACpE,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,4EAA4E;IAC5E,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,IAAI,GAAG,IAAI,CAAC;CACvB;AAED,MAAM,WAAW,uBAAuB;IACtC,4CAA4C;IAC5C,UAAU,EAAE,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;IACtC,gCAAgC;IAChC,SAAS,EAAE,aAAa,EAAE,CAAC;IAC3B,oEAAoE;IACpE,mBAAmB,EAAE,MAAM,EAAE,CAAC;IAC9B,oEAAoE;IACpE,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC;AAID;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,MAAgC,CAAC;AAyBhE,wBAAsB,iBAAiB,CACrC,KAAK,EAAE,sBAAsB,GAC5B,OAAO,CAAC,uBAAuB,CAAC,CAgGlC"}

package/dist/tools-logic/predict-correction.js

@@ -0,0 +1,137 @@
+/**
+ * predict-correction.ts — the north-star: anticipate a correction BEFORE the
+ * user makes it (Wave 5, Decision #8).
+ *
+ * Given a plan, overlap its tokens against the corrections-derived Blind-Spots
+ * profile. A fired risk means "this plan resembles a tendency you have been
+ * corrected on" — pushed as an EARLY prior at session_start / check(), not a
+ * RAG fact pulled late. Synchronous (Decision #3 — retrieval is a function, no
+ * spawned per-call agent). Reuses the exported tokenize/overlap grammar from
+ * check-action (Wave 4) — does NOT fork it.
+ */
+import { resolveProject } from "../storage/project.js";
+import { tokenize, overlap } from "./check-action.js";
+import { readBlindSpots, recomputeBlindSpots } from "../storage/blind-spots-store.js";
+import { readActiveCorrections, recordOutcome } from "../storage/corrections.js";
+import { matchesBlindSpot, BLIND_SPOT_SEMANTIC_THRESHOLD } from "../helpers/blind-spots.js";
+/** Minimum trigger-keyword overlap for a risk to fire (strict — mirrors prior-builder). */
+const MIN_OVERLAP = 2;
+/**
+ * LOCAL semantic-similarity floor for a risk to fire when the keyword path does
+ * NOT (Loop 5). Re-exported from blind-spots.ts (the single matching grammar) so
+ * production and the LOO eval share ONE threshold. Tuned on the real corpus to
+ * balance recall against false positives on unrelated pairs. No API key, no
+ * network — pure stemming + concept map + char-trigram cosine.
+ */
+export const SEMANTIC_THRESHOLD = BLIND_SPOT_SEMANTIC_THRESHOLD;
+/** Likelihood band thresholds — HIGH-THRESHOLD-FIRST ternary. */
+const HIGH_BAND = 0.6;
+const MEDIUM_BAND = 0.3;
+const MAX_RISKS = 3;
+/**
+ * Find the active correction backing a blind spot — by trigger-keyword overlap
+ * against its rule. Used to anchor the recurrence/predict_precision weight and
+ * the `predicted` outcome to a concrete record.
+ */
+function matchingCorrection(bs, corrections) {
+    const triggerSet = new Set(bs.trigger_keywords.map((k) => k.toLowerCase()));
+    let best;
+    for (const c of corrections) {
+        const ruleTokens = tokenize(`${c.rule} ${(c.tags ?? []).join(" ")}`);
+        const n = overlap(ruleTokens, triggerSet).length;
+        if (n >= 1 && (!best || n > best.n))
+            best = { rec: c, n };
+    }
+    return best?.rec;
+}
+export async function predictCorrection(input) {
+    const empty = {
+        likelihood: "low",
+        top_risks: [],
+        matched_blind_spots: [],
+        suggested_guard: null,
+    };
+    const plan = (input.plan ?? "").trim();
+    if (!plan)
+        return empty;
+    const slug = await resolveProject(input.project);
+    // Load profile; lazily recompute if missing (no spawned agent — synchronous).
+    let profile = readBlindSpots(slug);
+    if (!profile) {
+        try {
+            profile = recomputeBlindSpots(slug);
+        }
+        catch {
+            profile = null;
+        }
+    }
+    if (!profile || profile.blind_spots.length === 0)
+        return empty;
+    const corrections = readActiveCorrections(slug);
+    const planTokens = tokenize(plan);
+    if (planTokens.size === 0)
+        return empty;
+    const risks = [];
+    for (const bs of profile.blind_spots) {
+        // FLOOR keyword overlap + WIDEN local semantic similarity — the SINGLE shared
+        // matching grammar (helpers/blind-spots.ts). Keyword path is the floor; the
+        // semantic path strictly ADDS recall, with NO API key and NO network.
+        const m = matchesBlindSpot(plan, bs, MIN_OVERLAP, SEMANTIC_THRESHOLD);
+        if (!m.fired)
+            continue;
+        const corr = matchingCorrection(bs, corrections);
+        const recurrence = corr?.recurrence_count ?? 0;
+        const predictPrecision = corr?.predict_precision ?? 0;
+        // Keyword hits score on matched-token count; a semantic-only hit scores on its
+        // similarity (mapped onto a comparable scale, ~MIN_OVERLAP-equivalent) so a
+        // strong lexical match still outranks a borderline semantic one.
+        const baseMatch = m.via === "keyword" ? m.matched.length : MIN_OVERLAP * m.semanticScore;
+        // Weighted overlap: more matched triggers + P0 severity + observed recurrence
+        // + a track record of accurate predictions all raise the score.
+        const raw = baseMatch *
+            (bs.severity === "p0" ? 1.5 : 1) *
+            (1 + 0.2 * recurrence) *
+            (1 + 0.5 * predictPrecision);
+        risks.push({
+            tendency: bs.tendency,
+            score: raw,
+            matched: m.via === "keyword" ? m.matched : [`~semantic:${m.semanticScore.toFixed(2)}`],
+            correction_id: corr?.id,
+            severity: bs.severity,
+        });
+    }
+    if (risks.length === 0)
+        return empty;
+    risks.sort((a, b) => b.score - a.score);
+    // Normalize the strongest risk against the plan's token count so a longer
+    // plan with one match doesn't inflate. Cap each risk's normalized score at 1.
+    const denom = Math.max(planTokens.size, 3);
+    const normalize = (s) => Math.min(1, s / denom);
+    const topScore = normalize(risks[0].score);
+    // HIGH-THRESHOLD-FIRST ternary (Done-Definition #3).
+    const likelihood = topScore >= HIGH_BAND ? "high" : topScore >= MEDIUM_BAND ? "medium" : "low";
+    const topRisks = risks.slice(0, MAX_RISKS).map((r) => ({ ...r, score: Math.round(normalize(r.score) * 1000) / 1000 }));
+    // Instrument the predict-the-correction loop: each fired risk that anchors to
+    // a real correction records a `predicted` outcome. Best-effort — never throw.
+    const at = new Date().toISOString();
+    for (const r of topRisks) {
+        if (!r.correction_id)
+            continue;
+        try {
+            recordOutcome({ correction_id: r.correction_id, project: slug, kind: "predicted", at });
+        }
+        catch {
+            // instrumentation must never break prediction
+        }
+    }
+    const guard = topRisks.length > 0
+        ? `Likely correction: ${topRisks[0].tendency}. Reconcile before proceeding (matched: ${topRisks[0].matched.join(", ")}).`
+        : null;
+    return {
+        likelihood,
+        top_risks: topRisks,
+        matched_blind_spots: topRisks.map((r) => r.tendency),
+        suggested_guard: guard,
+    };
+}
+//# sourceMappingURL=predict-correction.js.map

package/dist/tools-logic/predict-correction.js.map

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

package/dist/tools-logic/prior-builder.d.ts

@@ -0,0 +1,27 @@
+/**
+ * prior-builder.ts — the "push a calibrated prior EARLY" half of the Bridge (Wave 4).
+ *
+ * hook-ambient fires before the agent reasons. Instead of only surfacing a fact
+ * list pulled late, we push a correction-derived PRIOR above it: "this resembles
+ * a past correction — check before proceeding." Memory becoming understanding.
+ *
+ * Pure + exported so it is unit-testable WITHOUT spawning the CLI. The CLI passes
+ * in the prompt, the project's P0 corrections, and the awareness blind-spots.
+ *
+ * Overlap gate starts STRICT (>=2 content tokens) to avoid noise (Risk #8). The
+ * tokenizer/overlap grammar is REUSED from check-action.ts — do not fork it.
+ */
+/** Minimal shape of a correction the prior-builder needs. */
+export interface PriorCorrection {
+    id?: string;
+    rule: string;
+    severity?: string;
+    tags?: string[];
+}
+/**
+ * Build the early-prior lines for a prompt.
+ * Corrections fire a hard "resembles a past correction" instinct; blind-spots
+ * fire a softer "tends to" nudge. Corrections take precedence.
+ */
+export declare function buildPriors(prompt: string, corrections: PriorCorrection[], blindSpots: string[]): string[];
+//# sourceMappingURL=prior-builder.d.ts.map

package/dist/tools-logic/prior-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prior-builder.d.ts","sourceRoot":"","sources":["../../src/tools-logic/prior-builder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,6DAA6D;AAC7D,MAAM,WAAW,eAAe;IAC9B,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB;AAOD;;;;GAIG;AACH,wBAAgB,WAAW,CACzB,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,eAAe,EAAE,EAC9B,UAAU,EAAE,MAAM,EAAE,GACnB,MAAM,EAAE,CAkCV"}

package/dist/tools-logic/prior-builder.js

@@ -0,0 +1,57 @@
+/**
+ * prior-builder.ts — the "push a calibrated prior EARLY" half of the Bridge (Wave 4).
+ *
+ * hook-ambient fires before the agent reasons. Instead of only surfacing a fact
+ * list pulled late, we push a correction-derived PRIOR above it: "this resembles
+ * a past correction — check before proceeding." Memory becoming understanding.
+ *
+ * Pure + exported so it is unit-testable WITHOUT spawning the CLI. The CLI passes
+ * in the prompt, the project's P0 corrections, and the awareness blind-spots.
+ *
+ * Overlap gate starts STRICT (>=2 content tokens) to avoid noise (Risk #8). The
+ * tokenizer/overlap grammar is REUSED from check-action.ts — do not fork it.
+ */
+import { tokenize, overlap } from "./check-action.js";
+/** Minimum content-token overlap for a correction prior to fire (strict). */
+const MIN_OVERLAP = 2;
+/** Max priors emitted (kept tiny — these sit above the fact list). */
+const MAX_PRIORS = 2;
+/**
+ * Build the early-prior lines for a prompt.
+ * Corrections fire a hard "resembles a past correction" instinct; blind-spots
+ * fire a softer "tends to" nudge. Corrections take precedence.
+ */
+export function buildPriors(prompt, corrections, blindSpots) {
+    const out = [];
+    if (!prompt || !prompt.trim())
+        return out;
+    const promptTokens = tokenize(prompt);
+    if (promptTokens.size === 0)
+        return out;
+    // 1. Correction priors (authoritative ground truth — strongest signal).
+    for (const c of corrections ?? []) {
+        if (out.length >= MAX_PRIORS)
+            break;
+        if (!c || !c.rule)
+            continue;
+        const ruleTokens = tokenize(`${c.rule} ${(c.tags ?? []).join(" ")}`);
+        const matched = overlap(promptTokens, ruleTokens);
+        if (matched.length >= MIN_OVERLAP) {
+            out.push(`⚠ [AgentRecall instinct] Resembles a past correction — ${c.rule.trim()}. Check before proceeding.`);
+        }
+    }
+    // 2. Blind-spot priors (softer — derived tendency, not a hard rule).
+    for (const bs of blindSpots ?? []) {
+        if (out.length >= MAX_PRIORS)
+            break;
+        if (!bs || !bs.trim())
+            continue;
+        const bsTokens = tokenize(bs);
+        const matched = overlap(promptTokens, bsTokens);
+        if (matched.length >= MIN_OVERLAP) {
+            out.push(`⚠ [AgentRecall] Watch a known tendency — ${bs.trim()}.`);
+        }
+    }
+    return out.slice(0, MAX_PRIORS);
+}
+//# sourceMappingURL=prior-builder.js.map

package/dist/tools-logic/prior-builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prior-builder.js","sourceRoot":"","sources":["../../src/tools-logic/prior-builder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAUtD,6EAA6E;AAC7E,MAAM,WAAW,GAAG,CAAC,CAAC;AACtB,sEAAsE;AACtE,MAAM,UAAU,GAAG,CAAC,CAAC;AAErB;;;;GAIG;AACH,MAAM,UAAU,WAAW,CACzB,MAAc,EACd,WAA8B,EAC9B,UAAoB;IAEpB,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,IAAI,CAAC,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE;QAAE,OAAO,GAAG,CAAC;IAE1C,MAAM,YAAY,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC;IACtC,IAAI,YAAY,CAAC,IAAI,KAAK,CAAC;QAAE,OAAO,GAAG,CAAC;IAExC,wEAAwE;IACxE,KAAK,MAAM,CAAC,IAAI,WAAW,IAAI,EAAE,EAAE,CAAC;QAClC,IAAI,GAAG,CAAC,MAAM,IAAI,UAAU;YAAE,MAAM;QACpC,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI;YAAE,SAAS;QAC5B,MAAM,UAAU,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACrE,MAAM,OAAO,GAAG,OAAO,CAAC,YAAY,EAAE,UAAU,CAAC,CAAC;QAClD,IAAI,OAAO,CAAC,MAAM,IAAI,WAAW,EAAE,CAAC;YAClC,GAAG,CAAC,IAAI,CACN,0DAA0D,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,4BAA4B,CACpG,CAAC;QACJ,CAAC;IACH,CAAC;IAED,qEAAqE;IACrE,KAAK,MAAM,EAAE,IAAI,UAAU,IAAI,EAAE,EAAE,CAAC;QAClC,IAAI,GAAG,CAAC,MAAM,IAAI,UAAU;YAAE,MAAM;QACpC,IAAI,CAAC,EAAE,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE;YAAE,SAAS;QAChC,MAAM,QAAQ,GAAG,QAAQ,CAAC,EAAE,CAAC,CAAC;QAC9B,MAAM,OAAO,GAAG,OAAO,CAAC,YAAY,EAAE,QAAQ,CAAC,CAAC;QAChD,IAAI,OAAO,CAAC,MAAM,IAAI,WAAW,EAAE,CAAC;YAClC,GAAG,CAAC,IAAI,CACN,4CAA4C,EAAE,CAAC,IAAI,EAAE,GAAG,CACzD,CAAC;QACJ,CAAC;IACH,CAAC;IAED,OAAO,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC;AAClC,CAAC"}

package/dist/tools-logic/recognition-builder.d.ts

@@ -0,0 +1,116 @@
+/**
+ * recognition.ts — Loop 4 north-star: REAL-TIME RECOGNITION at session start.
+ *
+ * When a session opens, the agent must instantly know FOUR things from LOCAL
+ * data only — zero network, no Supabase, no LLM on the hot path, deterministic:
+ *
+ *   1. WHO            — identity / role (from palace/identity.ts + owner)
+ *   2. CAN_DO         — capabilities (palace/skills + capability-bearing corrections)
+ *   3. PROJECT        — project + progress (status board + journal + palace state)
+ *   4. PERSON         — "what kind of person" = blind-spots profile rendered as
+ *                       tendencies-to-watch, WITH an explicit low-confidence caveat
+ *                       (Loop 3 measured this profile at 0/13 predictive — surface,
+ *                       never over-claim).
+ *
+ * This module ASSEMBLES existing stores — it does NOT rebuild them. Every read
+ * is a pure, synchronous filesystem read of already-derived artifacts. The
+ * payload is deterministically ordered so the same on-disk state yields a
+ * byte-identical JSON across repeated runs (no timestamps, no Date.now in the
+ * output — those would break determinism and aren't part of "recognition").
+ *
+ * Honesty law: WHO is `'unknown'` when no identity card exists. We NEVER infer
+ * or fabricate a persona. CAN_DO and PERSON are honestly empty when nothing is
+ * known.
+ */
+/** Field 1 — WHO is in front of the agent. `name` is `'unknown'` when no identity card exists. */
+export interface RecognitionWho {
+    /** Identity name / project label, or the literal string `'unknown'`. */
+    name: string;
+    /** One-line role / intention from the identity card, or `null`. NEVER fabricated. */
+    role: string | null;
+    /** Project owner (filesystem source path or owner marker), or `null`. */
+    owner: string | null;
+    /** True when no identity.md (or only a template stub) exists — `name` is `'unknown'`. */
+    unknown: boolean;
+}
+/** Field 2 — WHAT THEY CAN DO. Honestly empty when nothing is known. */
+export interface RecognitionCapabilities {
+    /** Declared skills (procedural memory), deterministically ordered by slug. */
+    skills: Array<{
+        slug: string;
+        name: string;
+        topic: string;
+        triggers: string[];
+    }>;
+    /**
+     * Capability / permission signals surfaced from corrections — rules whose text
+     * reads as a standing tool/permission constraint (e.g. "never push without
+     * approval"). Deterministically ordered by severity then id.
+     */
+    permissions: Array<{
+        id: string;
+        rule: string;
+        severity: "p0" | "p1";
+    }>;
+}
+/** Field 3 — PROJECT + PROGRESS. A one-glance "what this is and where it stands". */
+export interface RecognitionProject {
+    slug: string;
+    /** Latest journal date (YYYY-MM-DD), or `null` when no journal exists. */
+    last_journal_date: string | null;
+    /** Coarse status board bucket derived from journal freshness. */
+    status: "needs-you" | "backlog" | "stale" | "empty";
+    /** Latest `## Next` trajectory line, trimmed, or `null`. */
+    trajectory: string | null;
+    /** Active palace rooms (top by salience), deterministically ordered. */
+    rooms: Array<{
+        name: string;
+        salience: number;
+        stale: boolean;
+    }>;
+}
+/**
+ * Field 4 — WHAT KIND OF PERSON. The blind-spots profile rendered as tendencies
+ * to watch. ALWAYS carries `caveat` — the profile measured 0/13 predictive on
+ * real data (Loop 3), so recognition surfaces it but must NOT over-claim it.
+ */
+export interface RecognitionPerson {
+    /** Tendencies to watch, deterministically ordered by severity then evidence. */
+    tendencies: Array<{
+        tendency: string;
+        severity: "p0" | "p1";
+        evidence_count: number;
+    }>;
+    /** Mandatory low-confidence caveat. Present whether or not tendencies is empty. */
+    caveat: string;
+}
+export interface RecognitionPayload {
+    who: RecognitionWho;
+    can_do: RecognitionCapabilities;
+    project: RecognitionProject;
+    person: RecognitionPerson;
+}
+export interface BuildRecognitionOptions {
+    /** Cap on skills surfaced (default 8). */
+    maxSkills?: number;
+    /** Cap on capability/permission corrections surfaced (default 5). */
+    maxPermissions?: number;
+    /** Cap on rooms surfaced (default 3). */
+    maxRooms?: number;
+    /** Cap on person tendencies surfaced (default 3). */
+    maxTendencies?: number;
+}
+/**
+ * The mandatory low-confidence caveat for the person profile. Loop 3's
+ * leave-one-out eval measured the blind-spots profile at 0/13 predictive on real
+ * corrections, so it is surfaced for orientation only — never as validated truth.
+ */
+export declare const PERSON_LOW_CONFIDENCE_CAVEAT = "low-confidence: derived tendencies, measured 0/13 predictive on real data (Loop 3) \u2014 orientation only, not validated.";
+/**
+ * Assemble the real-time recognition payload for a project from LOCAL stores
+ * only. Synchronous, deterministic, zero-network. Caller must have already
+ * resolved `project` to a concrete slug (this function does not auto-detect, so
+ * it never shells out to git — keeping the hot path pure and fast).
+ */
+export declare function buildRecognition(project: string, opts?: BuildRecognitionOptions): RecognitionPayload;
+//# sourceMappingURL=recognition-builder.d.ts.map

package/dist/tools-logic/recognition-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recognition-builder.d.ts","sourceRoot":"","sources":["../../src/tools-logic/recognition-builder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAeH,kGAAkG;AAClG,MAAM,WAAW,cAAc;IAC7B,wEAAwE;IACxE,IAAI,EAAE,MAAM,CAAC;IACb,qFAAqF;IACrF,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,yEAAyE;IACzE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,yFAAyF;IACzF,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,wEAAwE;AACxE,MAAM,WAAW,uBAAuB;IACtC,8EAA8E;IAC9E,MAAM,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC,CAAC;IACjF;;;;OAIG;IACH,WAAW,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,IAAI,GAAG,IAAI,CAAA;KAAE,CAAC,CAAC;CACzE;AAED,qFAAqF;AACrF,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,0EAA0E;IAC1E,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,iEAAiE;IACjE,MAAM,EAAE,WAAW,GAAG,SAAS,GAAG,OAAO,GAAG,OAAO,CAAC;IACpD,4DAA4D;IAC5D,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,wEAAwE;IACxE,KAAK,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;CAClE;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,gFAAgF;IAChF,UAAU,EAAE,KAAK,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,IAAI,GAAG,IAAI,CAAC;QAAC,cAAc,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACvF,mFAAmF;IACnF,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,kBAAkB;IACjC,GAAG,EAAE,cAAc,CAAC;IACpB,MAAM,EAAE,uBAAuB,CAAC;IAChC,OAAO,EAAE,kBAAkB,CAAC;IAC5B,MAAM,EAAE,iBAAiB,CAAC;CAC3B;AAED,MAAM,WAAW,uBAAuB;IACtC,0CAA0C;IAC1C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,qEAAqE;IACrE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,yCAAyC;IACzC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,qDAAqD;IACrD,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAID;;;;GAIG;AACH,eAAO,MAAM,4BAA4B,+HACgF,CAAC;AAiP1H;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,uBAA4B,GAAG,kBAAkB,CAYxG"}