agent-recall-core 3.4.30 → 3.4.35

package/dist/relevance/injector.js

@@ -1,121 +0,0 @@
-/**
- * Injector — formats Surfacer Candidates as an "added context" block the host
- * hook can echo into the agent's context (v3.5.0 P-B, spec §4 "Judge" + §5).
- *
- * Contract:
- *   • Pure function. Zero fs, zero network — Surfacer already did the I/O.
- *   • Empty candidates → returns "" (silence is precision; the hook MUST emit
- *     nothing in this case so the agent's context stays clean — see spec §6).
- *   • One bullet per candidate, capped at ~140 chars total per line so the
- *     injected block never blows past a few hundred tokens even at K=3.
- *   • Title-render uses [source] (palace shows palace/<room>) and includes
- *     the Surfacer's `why` clause so the model knows WHY this surfaced and
- *     can decide whether to act on it.
- *
- * Output shape (verbatim — host hook copy-pastes this into stdout):
- *
- *   <agent-recall-context>
- *   Possibly relevant prior memory (use if it helps, ignore otherwise):
- *   • [palace/goals] Rate limiting in Stripe — must use idempotency keys (why: matches palace/goals)
- *   • [journal] 2026-06-12 — Stripe webhook signature verification gotcha (why: matched recent journal 2026-06-12)
- *   </agent-recall-context>
- *
- * Worker done-definition self-check:
- *   (1) Error path: candidates is null/undefined → coerce to [] before any
- *       work. Each candidate field is `?? ""` so undefined never throws.
- *   (2) No global binaries — pure node, no shell-outs, no deps.
- *   (3) Threshold/ternary ordering — only branch is `length === 0 ? '' : block`,
- *       short-circuit-on-empty first.
- *   (4) No time-of-day logic; nothing TZ-sensitive.
- */
-/** Hard cap per bullet line. ~140 chars keeps the K=3 block under ~500 chars. */
-const LINE_MAX_CHARS = 140;
-/** Width budget left over for the title+why after the "• [tag] " prefix. */
-const TITLE_MAX_CHARS = 80;
-const WHY_MAX_CHARS = 60;
-/**
- * Build the bracket-tag prefix shown at the head of each bullet.
- * palace candidates carry their room (`palace/goals`); others fall back to
- * just the source kind.
- */
-function tagOf(c) {
-    if (c.source === "palace" && c.room)
-        return `palace/${c.room}`;
-    return c.source;
-}
-/**
- * Truncate without splitting mid-codepoint. We only handle BMP here; the
- * Surfacer's snippets are already char-capped, so this is the second-line
- * defense (Injector's caller could in theory pass a fresh Candidate with a
- * longer title — be tolerant).
- */
-function truncate(s, n) {
-    if (!s)
-        return "";
-    if (s.length <= n)
-        return s;
-    return s.slice(0, n);
-}
-/**
- * Render one Candidate as a single bullet line, capped to LINE_MAX_CHARS.
- *
- * Format: `• [<tag>] <title> (why: <why>)`
- *
- * If the assembled line exceeds LINE_MAX_CHARS we re-trim the title (the
- * most variable field) until the whole line fits. The `[tag]` prefix and
- * the `why:` clause are short and information-dense, so they survive
- * intact at the expense of the title's tail.
- */
-export function formatCandidate(c) {
-    const tag = tagOf(c);
-    const why = truncate((c.why ?? "").trim(), WHY_MAX_CHARS);
-    let title = truncate((c.title ?? "").trim(), TITLE_MAX_CHARS);
-    // Static parts of the line. `• [tag] ` + ` (why: <why>)` is fixed once
-    // tag/why are known; only the title is elastic.
-    const prefix = `• [${tag}] `;
-    const suffix = why ? ` (why: ${why})` : "";
-    const budget = LINE_MAX_CHARS - prefix.length - suffix.length;
-    if (budget <= 0) {
-        // Pathological case: tag + why already > LINE_MAX_CHARS. Drop the why
-        // clause to recover space; the bracket-tag is the more important signal.
-        return truncate(`${prefix}${title}`, LINE_MAX_CHARS);
-    }
-    if (title.length > budget) {
-        title = title.slice(0, Math.max(0, budget - 1)) + "…";
-    }
-    const line = `${prefix}${title}${suffix}`;
-    // Final guard — the budget math above should make this a no-op, but a
-    // bug in the truncate path must NEVER produce a line that breaks the
-    // host's stdout framing. Cap unconditionally.
-    return truncate(line, LINE_MAX_CHARS);
-}
-/**
- * Format a list of Candidates for the host hook to inject.
- *
- * Empty input → empty string. This is load-bearing — the hook in the host
- * is wired to echo our stdout verbatim, so an empty string keeps the
- * agent's context clean (silence is precision, spec §6).
- */
-export function formatForHook(candidates) {
-    // Error path #1: null/undefined input — coerce, do not throw.
-    const list = Array.isArray(candidates) ? candidates : [];
-    if (list.length === 0)
-        return "";
-    const lines = [];
-    for (const c of list) {
-        // Skip malformed candidates rather than throwing — Surfacer's contract is
-        // strict but defensive code here costs nothing.
-        if (!c || typeof c !== "object")
-            continue;
-        lines.push(formatCandidate(c));
-    }
-    if (lines.length === 0)
-        return "";
-    return [
-        "<agent-recall-context>",
-        "Possibly relevant prior memory (use if it helps, ignore otherwise):",
-        ...lines,
-        "</agent-recall-context>",
-    ].join("\n");
-}
-//# sourceMappingURL=injector.js.map

package/dist/relevance/injector.js.map

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

package/dist/relevance/precision.d.ts

@@ -1,109 +0,0 @@
-/**
- * Precision meter — `injection_precision = used / injected`
- * (v3.5.0 P-C, Ambient Relevance Loop, spec §5 + §6 "Precision guardrail").
- *
- * Purpose: this is the north-star metric that proves "intelligence, not
- * storage." Of the memories AgentRecall surfaces (`injected`), how many
- * does the agent actually act on (`used`)? A falling number is the
- * early-warning that the Surfacer threshold is mis-tuned (noise > signal).
- *
- * Storage shape — append-only JSONL, one file per kind, per project:
- *
- *   ~/.agent-recall/projects/<slug>/_precision/injections.jsonl
- *   ~/.agent-recall/projects/<slug>/_precision/usages.jsonl
- *
- * Design contract:
- *   • `recordInjection`/`recordUsage` are fire-and-forget — they NEVER
- *     throw. Losing a measurement line is acceptable; killing a user turn
- *     is not. Errors are swallowed silently (mirrors stager.ts).
- *   • `getPrecisionKPI` is tolerant of malformed lines (skipped, not
- *     fatal), missing files (treated as empty), and missing fields.
- *   • `precision` is **null** (not NaN) when `injected === 0` — the
- *     dashboard can render "—" instead of "NaN%".
- *   • `precision` is clamped to `[0, 1]` via `Math.min(1, used / injected)`
- *     (matches the existing pattern in storage/corrections.ts:373 — under
- *     data corruption / duplicate-usage events, the raw ratio can exceed
- *     1.0, which is nonsense as a "precision" metric).
- *   • `per_source` groups by the prefix of `candidate_id` before ':'
- *     (e.g. `palace:room:slug` → bucket `palace`). Unprefixed ids land in
- *     the `unknown` bucket so they're still visible.
- *
- * Worker done-definition self-check:
- *   (1) error paths: `readJsonl` returns [] on read failure, JSON.parse
- *       wrapped in try/catch per line; recordInjection/Usage's outer
- *       try/catch swallows fs errors.
- *   (2) no global binaries — pure node:fs/path/crypto, no shell-outs.
- *   (3) ternary ordering — only branch is `injected > 0 ? clamp : null`,
- *       null is the explicit zero-denominator case.
- *   (4) time logic — `cutoff` is computed in ms-since-epoch from `Date.now()`
- *       which is TZ-agnostic; `ts` strings are ISO-8601 (also TZ-agnostic).
- *       No local-date filename is used here so no TZ bug surface.
- */
-export interface InjectionEvent {
-    /** ISO-8601 timestamp of when the candidates were surfaced. */
-    ts: string;
-    /** Candidate ids that the Surfacer pushed into the agent's context this turn. */
-    candidate_ids: string[];
-    /** sha256(user_message + assistant_response) — links to UsageEvent.turn_hash. */
-    turn_hash: string;
-}
-export interface UsageEvent {
-    /** ISO-8601 timestamp of when the usage was detected. */
-    ts: string;
-    /** The id of the candidate that the agent acted on. */
-    candidate_id: string;
-    /** Turn this candidate was used in — joins back to InjectionEvent.turn_hash. */
-    turn_hash: string;
-    /** Brief reason (e.g. "title appeared in assistant output"). */
-    evidence: string;
-}
-export interface PrecisionKPI {
-    /** Window the KPI was computed over (days). */
-    window_days: number;
-    /** Total candidates surfaced (sum of candidate_ids.length across injections). */
-    injected: number;
-    /** Total candidates the agent used (one row per used candidate). */
-    used: number;
-    /**
-     * `used / injected`, clamped to `[0, 1]`. **null** when `injected === 0`
-     * (NaN MUST NOT appear — the dashboard treats null as "no data yet").
-     */
-    precision: number | null;
-    /** Breakdown by candidate-id source prefix (palace / journal / …). */
-    per_source: Record<string, {
-        injected: number;
-        used: number;
-    }>;
-}
-/**
- * Append one injection event to `_precision/injections.jsonl`.
- *
- * NEVER THROWS. Mirrors `stage()` — the read/write loop continues
- * regardless of fs errors. Losing a measurement is acceptable; killing a
- * user turn is not.
- */
-export declare function recordInjection(project: string, ev: InjectionEvent): void;
-/**
- * Append one usage event to `_precision/usages.jsonl`.
- *
- * NEVER THROWS. One row per used candidate; the caller is expected to
- * dedupe at the detection layer (one usage row per (turn_hash, candidate_id)).
- */
-export declare function recordUsage(project: string, ev: UsageEvent): void;
-/**
- * Compute the precision KPI over the trailing `windowDays` (default 14).
- *
- * Algorithm (spec §6):
- *   • cutoff = now - windowDays * 86400_000 ms
- *   • injected = Σ ev.candidate_ids.length over injections with ts ≥ cutoff
- *   • used     = count of usage rows with ts ≥ cutoff
- *   • precision = injected > 0 ? Math.min(1, used / injected) : null
- *   • per_source = { <prefix>: { injected, used } } grouped by id-prefix
- *
- * Invariants:
- *   • `precision` is never NaN; it is either a finite number in [0, 1] or null.
- *   • Malformed jsonl lines are tolerated (skipped by `readJsonl`).
- *   • Empty project → injected=0, used=0, precision=null, per_source={}.
- */
-export declare function getPrecisionKPI(project: string, windowDays?: number): PrecisionKPI;
-//# sourceMappingURL=precision.d.ts.map

package/dist/relevance/precision.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"precision.d.ts","sourceRoot":"","sources":["../../src/relevance/precision.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAaH,MAAM,WAAW,cAAc;IAC7B,+DAA+D;IAC/D,EAAE,EAAE,MAAM,CAAC;IACX,iFAAiF;IACjF,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,iFAAiF;IACjF,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,UAAU;IACzB,yDAAyD;IACzD,EAAE,EAAE,MAAM,CAAC;IACX,uDAAuD;IACvD,YAAY,EAAE,MAAM,CAAC;IACrB,gFAAgF;IAChF,SAAS,EAAE,MAAM,CAAC;IAClB,gEAAgE;IAChE,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,YAAY;IAC3B,+CAA+C;IAC/C,WAAW,EAAE,MAAM,CAAC;IACpB,iFAAiF;IACjF,QAAQ,EAAE,MAAM,CAAC;IACjB,oEAAoE;IACpE,IAAI,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,sEAAsE;IACtE,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAChE;AAoGD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,cAAc,GAAG,IAAI,CAiBzE;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,UAAU,GAAG,IAAI,CAiBjE;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,YAAY,CA+DlF"}

package/dist/relevance/precision.js

@@ -1,279 +0,0 @@
-/**
- * Precision meter — `injection_precision = used / injected`
- * (v3.5.0 P-C, Ambient Relevance Loop, spec §5 + §6 "Precision guardrail").
- *
- * Purpose: this is the north-star metric that proves "intelligence, not
- * storage." Of the memories AgentRecall surfaces (`injected`), how many
- * does the agent actually act on (`used`)? A falling number is the
- * early-warning that the Surfacer threshold is mis-tuned (noise > signal).
- *
- * Storage shape — append-only JSONL, one file per kind, per project:
- *
- *   ~/.agent-recall/projects/<slug>/_precision/injections.jsonl
- *   ~/.agent-recall/projects/<slug>/_precision/usages.jsonl
- *
- * Design contract:
- *   • `recordInjection`/`recordUsage` are fire-and-forget — they NEVER
- *     throw. Losing a measurement line is acceptable; killing a user turn
- *     is not. Errors are swallowed silently (mirrors stager.ts).
- *   • `getPrecisionKPI` is tolerant of malformed lines (skipped, not
- *     fatal), missing files (treated as empty), and missing fields.
- *   • `precision` is **null** (not NaN) when `injected === 0` — the
- *     dashboard can render "—" instead of "NaN%".
- *   • `precision` is clamped to `[0, 1]` via `Math.min(1, used / injected)`
- *     (matches the existing pattern in storage/corrections.ts:373 — under
- *     data corruption / duplicate-usage events, the raw ratio can exceed
- *     1.0, which is nonsense as a "precision" metric).
- *   • `per_source` groups by the prefix of `candidate_id` before ':'
- *     (e.g. `palace:room:slug` → bucket `palace`). Unprefixed ids land in
- *     the `unknown` bucket so they're still visible.
- *
- * Worker done-definition self-check:
- *   (1) error paths: `readJsonl` returns [] on read failure, JSON.parse
- *       wrapped in try/catch per line; recordInjection/Usage's outer
- *       try/catch swallows fs errors.
- *   (2) no global binaries — pure node:fs/path/crypto, no shell-outs.
- *   (3) ternary ordering — only branch is `injected > 0 ? clamp : null`,
- *       null is the explicit zero-denominator case.
- *   (4) time logic — `cutoff` is computed in ms-since-epoch from `Date.now()`
- *       which is TZ-agnostic; `ts` strings are ISO-8601 (also TZ-agnostic).
- *       No local-date filename is used here so no TZ bug surface.
- */
-import * as fs from "node:fs";
-import * as path from "node:path";
-import { sanitizeProject } from "../storage/paths.js";
-import { ensureDir } from "../storage/fs-utils.js";
-import { getRoot } from "../types.js";
-// ---------------------------------------------------------------------------
-// Internal helpers
-// ---------------------------------------------------------------------------
-/** Resolve the per-project precision directory. Mirrors stager's `_staging/` convention. */
-function precisionDir(project) {
-    const safe = sanitizeProject(project);
-    return path.join(getRoot(), "projects", safe, "_precision");
-}
-function injectionsPath(project) {
-    return path.join(precisionDir(project), "injections.jsonl");
-}
-function usagesPath(project) {
-    return path.join(precisionDir(project), "usages.jsonl");
-}
-/**
- * Parse a JSONL file. Bad lines (truncated writes, manual edits) are
- * silently skipped — never throws. Missing file → empty array.
- *
- * Generic over the row shape; caller is responsible for narrowing.
- */
-function readJsonl(filePath) {
-    if (!fs.existsSync(filePath))
-        return [];
-    let raw;
-    try {
-        raw = fs.readFileSync(filePath, "utf-8");
-    }
-    catch {
-        return [];
-    }
-    const out = [];
-    const lines = raw.split("\n");
-    for (const line of lines) {
-        const trimmed = line.trim();
-        if (!trimmed)
-            continue;
-        try {
-            out.push(JSON.parse(trimmed));
-        }
-        catch {
-            // Malformed line — skip, never throw.
-        }
-    }
-    return out;
-}
-/**
- * Append one row to a JSONL file. Wraps the `fs.appendFileSync` call so
- * the public recorders can swallow fs errors at the boundary.
- */
-function appendJsonl(filePath, row) {
-    ensureDir(path.dirname(filePath));
-    fs.appendFileSync(filePath, JSON.stringify(row) + "\n", "utf-8");
-}
-/**
- * Extract the source prefix from a candidate id.
- * `palace:room:slug` → `palace`. Unprefixed → `unknown`.
- */
-function sourceOf(candidateId) {
-    if (typeof candidateId !== "string" || candidateId.length === 0)
-        return "unknown";
-    const idx = candidateId.indexOf(":");
-    if (idx <= 0)
-        return "unknown";
-    return candidateId.slice(0, idx);
-}
-/**
- * Narrow an unknown value to `InjectionEvent` shape (defensive — JSONL may
- * have been edited by hand). Returns null on miss.
- */
-function asInjectionEvent(v) {
-    if (!v || typeof v !== "object")
-        return null;
-    const o = v;
-    if (typeof o.ts !== "string")
-        return null;
-    if (!Array.isArray(o.candidate_ids))
-        return null;
-    if (typeof o.turn_hash !== "string")
-        return null;
-    const cids = o.candidate_ids.filter((c) => typeof c === "string");
-    return { ts: o.ts, candidate_ids: cids, turn_hash: o.turn_hash };
-}
-function asUsageEvent(v) {
-    if (!v || typeof v !== "object")
-        return null;
-    const o = v;
-    if (typeof o.ts !== "string")
-        return null;
-    if (typeof o.candidate_id !== "string")
-        return null;
-    if (typeof o.turn_hash !== "string")
-        return null;
-    return {
-        ts: o.ts,
-        candidate_id: o.candidate_id,
-        turn_hash: o.turn_hash,
-        evidence: typeof o.evidence === "string" ? o.evidence : "",
-    };
-}
-// ---------------------------------------------------------------------------
-// Public API
-// ---------------------------------------------------------------------------
-/**
- * Append one injection event to `_precision/injections.jsonl`.
- *
- * NEVER THROWS. Mirrors `stage()` — the read/write loop continues
- * regardless of fs errors. Losing a measurement is acceptable; killing a
- * user turn is not.
- */
-export function recordInjection(project, ev) {
-    try {
-        if (!ev || typeof ev !== "object")
-            return;
-        const safe = {
-            ts: typeof ev.ts === "string" && ev.ts.length > 0
-                ? ev.ts
-                : new Date().toISOString(),
-            candidate_ids: Array.isArray(ev.candidate_ids)
-                ? ev.candidate_ids.filter((c) => typeof c === "string")
-                : [],
-            turn_hash: typeof ev.turn_hash === "string" ? ev.turn_hash : "",
-        };
-        appendJsonl(injectionsPath(project), safe);
-    }
-    catch {
-        // Swallow — see contract above.
-    }
-}
-/**
- * Append one usage event to `_precision/usages.jsonl`.
- *
- * NEVER THROWS. One row per used candidate; the caller is expected to
- * dedupe at the detection layer (one usage row per (turn_hash, candidate_id)).
- */
-export function recordUsage(project, ev) {
-    try {
-        if (!ev || typeof ev !== "object")
-            return;
-        const safe = {
-            ts: typeof ev.ts === "string" && ev.ts.length > 0
-                ? ev.ts
-                : new Date().toISOString(),
-            candidate_id: typeof ev.candidate_id === "string" ? ev.candidate_id : "",
-            turn_hash: typeof ev.turn_hash === "string" ? ev.turn_hash : "",
-            evidence: typeof ev.evidence === "string" ? ev.evidence : "",
-        };
-        if (!safe.candidate_id)
-            return; // can't bucket without an id
-        appendJsonl(usagesPath(project), safe);
-    }
-    catch {
-        // Swallow.
-    }
-}
-/**
- * Compute the precision KPI over the trailing `windowDays` (default 14).
- *
- * Algorithm (spec §6):
- *   • cutoff = now - windowDays * 86400_000 ms
- *   • injected = Σ ev.candidate_ids.length over injections with ts ≥ cutoff
- *   • used     = count of usage rows with ts ≥ cutoff
- *   • precision = injected > 0 ? Math.min(1, used / injected) : null
- *   • per_source = { <prefix>: { injected, used } } grouped by id-prefix
- *
- * Invariants:
- *   • `precision` is never NaN; it is either a finite number in [0, 1] or null.
- *   • Malformed jsonl lines are tolerated (skipped by `readJsonl`).
- *   • Empty project → injected=0, used=0, precision=null, per_source={}.
- */
-export function getPrecisionKPI(project, windowDays) {
-    const days = typeof windowDays === "number" && Number.isFinite(windowDays) && windowDays > 0
-        ? windowDays
-        : 14;
-    const cutoffMs = Date.now() - days * 86400_000;
-    const rawInjections = readJsonl(injectionsPath(project));
-    const rawUsages = readJsonl(usagesPath(project));
-    const injections = [];
-    for (const r of rawInjections) {
-        const ev = asInjectionEvent(r);
-        if (!ev)
-            continue;
-        const t = Date.parse(ev.ts);
-        if (!Number.isFinite(t))
-            continue; // unparseable ts → skip
-        if (t < cutoffMs)
-            continue;
-        injections.push(ev);
-    }
-    const usages = [];
-    for (const r of rawUsages) {
-        const ev = asUsageEvent(r);
-        if (!ev)
-            continue;
-        const t = Date.parse(ev.ts);
-        if (!Number.isFinite(t))
-            continue;
-        if (t < cutoffMs)
-            continue;
-        usages.push(ev);
-    }
-    let injected = 0;
-    const perSource = {};
-    for (const ev of injections) {
-        for (const cid of ev.candidate_ids) {
-            injected++;
-            const src = sourceOf(cid);
-            if (!perSource[src])
-                perSource[src] = { injected: 0, used: 0 };
-            perSource[src].injected++;
-        }
-    }
-    const used = usages.length;
-    for (const ev of usages) {
-        const src = sourceOf(ev.candidate_id);
-        if (!perSource[src])
-            perSource[src] = { injected: 0, used: 0 };
-        perSource[src].used++;
-    }
-    // Clamp [0, 1]: data corruption (duplicate usages, late-arriving rows after
-    // injections were rotated out, etc.) can push raw used/injected above 1.0.
-    // Matches storage/corrections.ts:373 — "150% precision" is nonsense.
-    // null (not NaN) is the explicit zero-denominator case so the dashboard
-    // can render "—" rather than "NaN%".
-    const precision = injected > 0 ? Math.min(1, used / injected) : null;
-    return {
-        window_days: days,
-        injected,
-        used,
-        precision,
-        per_source: perSource,
-    };
-}
-//# sourceMappingURL=precision.js.map

package/dist/relevance/precision.js.map

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

package/dist/relevance/promoter.d.ts

@@ -1,60 +0,0 @@
-/**
- * Promoter — curates the staging buffer into the palace/journal at session
- * boundaries (v3.5.0 P-A, spec §4 "Promote", §5).
- *
- * Flow:
- *   1. Read up to N most-recent staged exchanges via `readStaging`.
- *   2. Apply a pure-function durability heuristic — `isDurableSignal` — to
- *      drop chitchat, single-word turns, tool-only exchanges.
- *   3. Dedupe survivors against the project's recent journal titles
- *      (`tooSimilarToExistingJournal`, threshold 0.7).
- *   4. Write the survivors via the existing `journalWrite` tool, then clear
- *      the staging file up to the newest promoted timestamp.
- *
- * Design notes:
- *   • The heuristic is intentionally cheap and pure. It is the FIRST pass —
- *     the in-room model (called separately by `sessionEndReflect`) is the
- *     true fine-grain judge. Here we just trim the obvious noise.
- *   • `opts.dryRun` runs the whole pipeline without writing the journal or
- *     clearing staging — used by tests and the dashboard preview.
- *   • Threshold ordering inside `isDurableSignal` is high-confidence first
- *     (explicit markers) then weaker signals (length + lexical proxy)
- *     (worker done-def rule 3).
- */
-import { type StagedExchange } from "./stager.js";
-export interface PromoteResult {
-    promoted: number;
-    skipped: number;
-    /** Counters keyed by reason for downstream dashboards and tests. */
-    reasons: Record<string, number>;
-}
-export interface PromoteOptions {
-    /** When true, runs the heuristic + dedup but writes nothing. */
-    dryRun?: boolean;
-}
-/**
- * Decide whether a staged exchange carries a durable signal.
- *
- * Returns TRUE on any of:
- *   1. Explicit marker (`decision`, `bug`, `gotcha`, …).
- *   2. Correction shape (`no … wrong`, `actually`, `correction`, `the right way`).
- *   3. Contains a wikilink or fenced code block (durable artifact).
- *   4. Length ≥ 120 chars AND has both an "important word" and an action verb
- *      (noun-verb proxy — catches substantive sentences).
- *
- * Returns FALSE for chitchat ("ok", "thanks"), single-sentence questions,
- * and tool-only turns (no user/assistant text).
- */
-export declare function isDurableSignal(e: StagedExchange): boolean;
-/**
- * Promote durable staged exchanges into the journal.
- *
- * Idempotent within a session: once promoted, the corresponding staging
- * entries are cleared (only the newest-promoted timestamp is used as the
- * `beforeTs` cursor, so any post-promote stage() calls survive).
- *
- * `opts.dryRun = true` runs the full pipeline (incl. dedup) but writes
- * nothing and clears nothing. Useful for tests and dashboard previews.
- */
-export declare function promote(project: string, opts?: PromoteOptions): Promise<PromoteResult>;
-//# sourceMappingURL=promoter.d.ts.map

package/dist/relevance/promoter.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"promoter.d.ts","sourceRoot":"","sources":["../../src/relevance/promoter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAIH,OAAO,EAA4B,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AAoC5E,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,oEAAoE;IACpE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC;AAED,MAAM,WAAW,cAAc;IAC7B,gEAAgE;IAChE,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAMD;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,cAAc,GAAG,OAAO,CAmB1D;AAqFD;;;;;;;;;GASG;AACH,wBAAsB,OAAO,CAC3B,OAAO,EAAE,MAAM,EACf,IAAI,GAAE,cAAmB,GACxB,OAAO,CAAC,aAAa,CAAC,CA+JxB"}