@co-engram/core 0.1.0

package/dist/observability/audit-log.js.map

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

package/dist/observability/effectiveness-tracker.d.ts

@@ -0,0 +1,162 @@
+/**
+ * 有效性追踪器（Effectiveness Tracker）
+ *
+ * 管理 retrieve_hit 后的观察窗口,自动判定 retrieve_effective / retrieve_inconclusive。
+ *
+ * 流程:
+ *   1. engram_search 命中 → openWindow(engramId, kind, query)
+ *   2. 在窗口期内调 reinforceEngram → closeAsEffective(engramId)
+ *   3. light maintenance 阶段 → sweepExpired() 把超时窗口标记为 inconclusive
+ *
+ * 窗口长度按 engram kind 区分:
+ *   - observation: 6h
+ *   - fact:        24h(默认)
+ *   - pattern:     48h
+ *   - procedure:   48h
+ *   - hypothesis:  7d
+ * 多 kind(engram.kinds) 取最长。
+ *
+ * 存储格式: $DATA_ROOT/.co-engram/observation-windows.jsonl
+ * 落盘原因: 进程重启不丢窗口;多 host 实例(Claude Code + OpenClaw)共享状态。
+ *
+ * 派生接口:
+ *   - effectiveness(engramId) → EffectivenessReport
+ *     本 tracker 提供 hits/effective/inconclusive(从 windows 文件派生),
+ *     contradicted 从注入的 auditLog 派生。
+ *
+ * @module @co-engram/core/observability
+ */
+import type { EngramKind } from "../types/engram.js";
+import type { AuditLog } from "./audit-log.js";
+/** kind → 窗口长度(毫秒) */
+export declare const DEFAULT_EFFECTIVENESS_WINDOWS: Readonly<Record<EngramKind, number>>;
+/** 默认的最少命中次数门槛 */
+export declare const DEFAULT_MIN_HITS = 3;
+/** 某 engram 的有效率统计 */
+export interface EffectivenessReport {
+    /** retrieve_hit 总次数(从 windows 文件读所有状态记录计数) */
+    readonly hits: number;
+    /** retrieve_effective 次数(从 windows 读 closed_by_reinforce) */
+    readonly effective: number;
+    /** retrieve_inconclusive 次数(从 windows 读 closed_by_timeout) */
+    readonly inconclusive: number;
+    /** contradicted 次数(从 audit 读) */
+    readonly contradicted: number;
+    /**
+     * 有效率:[0, 1] 或 null(数据不足)
+     *
+     * 公式: effective / (effective + inconclusive + contradicted)
+     * - inconclusive 进分母但不进分子(算半负面信号)
+     * - contradicted 不额外加权
+     * - hits < minHits(默认 3) → 返回 null
+     */
+    readonly effectiveRate: number | null;
+}
+/** 单个观察窗口记录 */
+export interface ObservationWindow {
+    /** 唯一 ID(randomUUID) */
+    readonly id: string;
+    /** 被检索命中的 engram id */
+    readonly engramId: string;
+    /** 检索查询(便于后续元学习) */
+    readonly query: string;
+    /** 命中时的分数 */
+    readonly score: number;
+    /** 命中时间(ISO) */
+    readonly hitAt: string;
+    /** 窗口截止时间(ISO) */
+    readonly deadline: string;
+    /** 该 engram 的 kind(决定窗口长度) */
+    readonly kind: EngramKind;
+    /** 会话 ID */
+    readonly sessionId?: string;
+    /** 状态:open / closed_by_reinforce / closed_by_failure / closed_by_timeout */
+    readonly status: "open" | "closed_by_reinforce" | "closed_by_failure" | "closed_by_timeout";
+}
+/**
+ * 计算给定 kinds 的窗口长度(取最长)
+ *
+ * 多 kind engram 取 max——任何维度未闭环都不算"完成"。
+ */
+export declare function computeWindowMs(kinds: readonly EngramKind[], overrides?: Partial<Readonly<Record<EngramKind, number>>>): number;
+/** sweepExpired 结果 */
+export interface SweepResult {
+    /** 关闭的窗口数 */
+    readonly closed: number;
+    /** 关闭的 engram id 列表(去重) */
+    readonly engramIds: readonly string[];
+}
+/**
+ * 有效性追踪器
+ *
+ * 不抛:所有写操作 fire-and-forget。
+ */
+export declare class EffectivenessTracker {
+    private readonly filePath;
+    private readonly auditLog;
+    private readonly windowsByKind?;
+    constructor(dataRoot: string, auditLog: AuditLog, options?: {
+        windowsByKind?: Partial<Readonly<Record<EngramKind, number>>>;
+    });
+    /**
+     * 开观察窗口(engram_search 命中时调)
+     *
+     * 同一 engram 同时只允许有一个 open 窗口——重复命中时刷新 deadline。
+     */
+    openWindow(input: {
+        readonly engramId: string;
+        readonly query: string;
+        readonly score: number;
+        readonly kinds: readonly EngramKind[];
+        readonly sessionId?: string;
+        readonly nowIso?: string;
+    }): ObservationWindow;
+    /**
+     * 标记某 engram 的最近 open 窗口为 effective(engram_reinforce 时调)
+     *
+     * @returns true 如果找到并关闭了一个 open 窗口
+     */
+    closeAsEffective(engramId: string, nowIso?: string): boolean;
+    /**
+     * 标记某 engram 的最近 open 窗口为 failure(engram_report_failure 时调)
+     *
+     * 失败已通过 report_failure audit 单独记录,这里仅关闭窗口避免后续触发 inconclusive。
+     */
+    closeAsFailure(engramId: string, nowIso?: string): boolean;
+    /**
+     * 扫描超时窗口,写 retrieve_inconclusive + 关闭
+     *
+     * 在 maintenance engine light 阶段调用。
+     */
+    sweepExpired(nowIso?: string): SweepResult;
+    /** 列出当前所有 open 窗口(调试/Viewer 用) */
+    listOpen(): readonly ObservationWindow[];
+    /**
+     * 派生某 engram 的有效率统计
+     *
+     * 数据源:
+     *   - hits/effective/inconclusive:从 observation-windows.jsonl 派生
+     *     · hits = 所有该 engram 的窗口记录数(每次 retrieve_hit 都开一个窗口)
+     *     · effective = closed_by_reinforce 状态计数
+     *     · inconclusive = closed_by_timeout 状态计数
+     *   - contradicted:从 audit.jsonl 派生(只有 audit 记录这种事件)
+     *
+     * hits < minHits(默认 3) → effectiveRate = null
+     *
+     * 与历史版本的差异:不再从 audit 读 retrieve_* 事件,因为它们每条对话消息
+     * 都可能产生,噪音太大。window 文件已经包含完整的 hits/effective/inconclusive
+     * 状态,effectiveness 公式精度保留。
+     */
+    effectiveness(engramId: string, options?: {
+        readonly minHits?: number;
+    }): EffectivenessReport;
+    /** 文件绝对路径 */
+    get path(): string;
+    /** 清空所有记录(测试用) */
+    clear(): void;
+    private closeExisting;
+    private readAll;
+    private writeAll;
+    private appendRecord;
+}
+//# sourceMappingURL=effectiveness-tracker.d.ts.map

package/dist/observability/effectiveness-tracker.d.ts.map

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

package/dist/observability/effectiveness-tracker.js

@@ -0,0 +1,251 @@
+/**
+ * 有效性追踪器（Effectiveness Tracker）
+ *
+ * 管理 retrieve_hit 后的观察窗口,自动判定 retrieve_effective / retrieve_inconclusive。
+ *
+ * 流程:
+ *   1. engram_search 命中 → openWindow(engramId, kind, query)
+ *   2. 在窗口期内调 reinforceEngram → closeAsEffective(engramId)
+ *   3. light maintenance 阶段 → sweepExpired() 把超时窗口标记为 inconclusive
+ *
+ * 窗口长度按 engram kind 区分:
+ *   - observation: 6h
+ *   - fact:        24h(默认)
+ *   - pattern:     48h
+ *   - procedure:   48h
+ *   - hypothesis:  7d
+ * 多 kind(engram.kinds) 取最长。
+ *
+ * 存储格式: $DATA_ROOT/.co-engram/observation-windows.jsonl
+ * 落盘原因: 进程重启不丢窗口;多 host 实例(Claude Code + OpenClaw)共享状态。
+ *
+ * 派生接口:
+ *   - effectiveness(engramId) → EffectivenessReport
+ *     本 tracker 提供 hits/effective/inconclusive(从 windows 文件派生),
+ *     contradicted 从注入的 auditLog 派生。
+ *
+ * @module @co-engram/core/observability
+ */
+import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync, } from "node:fs";
+import { dirname, join } from "node:path";
+/** kind → 窗口长度(毫秒) */
+export const DEFAULT_EFFECTIVENESS_WINDOWS = {
+    observation: 6 * 60 * 60 * 1000, // 6h
+    fact: 24 * 60 * 60 * 1000, // 24h
+    pattern: 48 * 60 * 60 * 1000, // 48h
+    procedure: 48 * 60 * 60 * 1000, // 48h
+    hypothesis: 7 * 24 * 60 * 60 * 1000, // 7d
+};
+/** 默认的最少命中次数门槛 */
+export const DEFAULT_MIN_HITS = 3;
+/**
+ * 计算给定 kinds 的窗口长度(取最长)
+ *
+ * 多 kind engram 取 max——任何维度未闭环都不算"完成"。
+ */
+export function computeWindowMs(kinds, overrides) {
+    if (kinds.length === 0) {
+        return DEFAULT_EFFECTIVENESS_WINDOWS.fact;
+    }
+    return Math.max(...kinds.map((k) => overrides?.[k] ?? DEFAULT_EFFECTIVENESS_WINDOWS[k]));
+}
+/**
+ * 有效性追踪器
+ *
+ * 不抛:所有写操作 fire-and-forget。
+ */
+export class EffectivenessTracker {
+    filePath;
+    auditLog;
+    windowsByKind;
+    constructor(dataRoot, auditLog, options = {}) {
+        this.filePath = join(dataRoot, ".co-engram", "observation-windows.jsonl");
+        this.auditLog = auditLog;
+        this.windowsByKind = options.windowsByKind;
+    }
+    /**
+     * 开观察窗口(engram_search 命中时调)
+     *
+     * 同一 engram 同时只允许有一个 open 窗口——重复命中时刷新 deadline。
+     */
+    openWindow(input) {
+        const now = input.nowIso ?? new Date().toISOString();
+        const windowMs = computeWindowMs(input.kinds, this.windowsByKind);
+        const deadline = new Date(new Date(now).getTime() + windowMs).toISOString();
+        // 关闭可能存在的 open 窗口(替换语义)
+        this.closeExisting(input.engramId, "closed_by_timeout", now, 
+        /* silent */ true);
+        const win = {
+            id: randomId(),
+            engramId: input.engramId,
+            query: input.query,
+            score: input.score,
+            hitAt: now,
+            deadline,
+            kind: input.kinds[0] ?? "fact",
+            sessionId: input.sessionId,
+            status: "open",
+        };
+        this.appendRecord(win);
+        // 不写 audit:window 文件已经记录了 hit,effectiveness() 从 windows 派生。
+        // 写 retrieve_hit audit 会让 audit.jsonl 被检索事件淹没。
+        return win;
+    }
+    /**
+     * 标记某 engram 的最近 open 窗口为 effective(engram_reinforce 时调)
+     *
+     * @returns true 如果找到并关闭了一个 open 窗口
+     */
+    closeAsEffective(engramId, nowIso) {
+        return this.closeExisting(engramId, "closed_by_reinforce", nowIso, 
+        /* silent */ false);
+    }
+    /**
+     * 标记某 engram 的最近 open 窗口为 failure(engram_report_failure 时调)
+     *
+     * 失败已通过 report_failure audit 单独记录,这里仅关闭窗口避免后续触发 inconclusive。
+     */
+    closeAsFailure(engramId, nowIso) {
+        return this.closeExisting(engramId, "closed_by_failure", nowIso, 
+        /* silent */ true);
+    }
+    /**
+     * 扫描超时窗口,写 retrieve_inconclusive + 关闭
+     *
+     * 在 maintenance engine light 阶段调用。
+     */
+    sweepExpired(nowIso) {
+        const now = nowIso ?? new Date().toISOString();
+        const records = this.readAll();
+        const closedIds = new Set();
+        let closed = 0;
+        const updated = records.map((r) => {
+            if (r.status === "open" && r.deadline <= now) {
+                closed += 1;
+                closedIds.add(r.engramId);
+                // 不写 audit:window 文件已经记录了 closed_by_timeout 状态,
+                // effectiveness() 从 windows 派生 inconclusive 计数。
+                return { ...r, status: "closed_by_timeout" };
+            }
+            return r;
+        });
+        if (closed > 0) {
+            this.writeAll(updated);
+        }
+        return { closed, engramIds: [...closedIds] };
+    }
+    /** 列出当前所有 open 窗口(调试/Viewer 用) */
+    listOpen() {
+        return this.readAll().filter((r) => r.status === "open");
+    }
+    /**
+     * 派生某 engram 的有效率统计
+     *
+     * 数据源:
+     *   - hits/effective/inconclusive:从 observation-windows.jsonl 派生
+     *     · hits = 所有该 engram 的窗口记录数(每次 retrieve_hit 都开一个窗口)
+     *     · effective = closed_by_reinforce 状态计数
+     *     · inconclusive = closed_by_timeout 状态计数
+     *   - contradicted:从 audit.jsonl 派生(只有 audit 记录这种事件)
+     *
+     * hits < minHits(默认 3) → effectiveRate = null
+     *
+     * 与历史版本的差异:不再从 audit 读 retrieve_* 事件,因为它们每条对话消息
+     * 都可能产生,噪音太大。window 文件已经包含完整的 hits/effective/inconclusive
+     * 状态,effectiveness 公式精度保留。
+     */
+    effectiveness(engramId, options = {}) {
+        const minHits = options.minHits ?? DEFAULT_MIN_HITS;
+        const oneYearAgo = new Date(Date.now() - 365 * 24 * 60 * 60 * 1000).toISOString();
+        const records = this.readAll().filter((r) => r.engramId === engramId && r.hitAt >= oneYearAgo);
+        const hits = records.length;
+        const effective = records.filter((r) => r.status === "closed_by_reinforce").length;
+        const inconclusive = records.filter((r) => r.status === "closed_by_timeout").length;
+        // contradicted 从 audit 派生(只有 audit 记录这种事件)
+        const contradicted = this.auditLog.query({
+            engramId,
+            action: "contradicted",
+            since: oneYearAgo,
+            limit: 100000,
+        }).length;
+        const denominator = effective + inconclusive + contradicted;
+        const effectiveRate = hits < minHits || denominator === 0 ? null : effective / denominator;
+        return { hits, effective, inconclusive, contradicted, effectiveRate };
+    }
+    /** 文件绝对路径 */
+    get path() {
+        return this.filePath;
+    }
+    /** 清空所有记录(测试用) */
+    clear() {
+        if (existsSync(this.filePath)) {
+            writeFileSync(this.filePath, "", "utf8");
+        }
+    }
+    // ============================================================
+    // 内部
+    // ============================================================
+    closeExisting(engramId, newStatus, nowIso, silent) {
+        const now = nowIso ?? new Date().toISOString();
+        const records = this.readAll();
+        // 从尾部往前找最近的 open 窗口
+        let foundIdx = -1;
+        for (let i = records.length - 1; i >= 0; i--) {
+            if (records[i].engramId === engramId && records[i].status === "open") {
+                foundIdx = i;
+                break;
+            }
+        }
+        if (foundIdx === -1)
+            return false;
+        const target = records[foundIdx];
+        records[foundIdx] = { ...target, status: newStatus };
+        this.writeAll(records);
+        // 不写 audit:window 文件已经记录了 closed_by_reinforce 状态,
+        // effectiveness() 从 windows 派生 effective 计数。
+        // silent=true(failure 关闭)时本来也不写 audit。
+        return true;
+    }
+    readAll() {
+        if (!existsSync(this.filePath))
+            return [];
+        const raw = readFileSync(this.filePath, "utf8");
+        return raw
+            .split("\n")
+            .filter((line) => line.trim().length > 0)
+            .map((line) => {
+            try {
+                return JSON.parse(line);
+            }
+            catch {
+                return null;
+            }
+        })
+            .filter((r) => r !== null);
+    }
+    writeAll(records) {
+        const dir = dirname(this.filePath);
+        if (!existsSync(dir)) {
+            mkdirSync(dir, { recursive: true });
+        }
+        const content = records.map((r) => JSON.stringify(r)).join("\n") + "\n";
+        writeFileSync(this.filePath, content, "utf8");
+    }
+    appendRecord(record) {
+        try {
+            const dir = dirname(this.filePath);
+            if (!existsSync(dir)) {
+                mkdirSync(dir, { recursive: true });
+            }
+            appendFileSync(this.filePath, `${JSON.stringify(record)}\n`, "utf8");
+        }
+        catch {
+            // intentional
+        }
+    }
+}
+/** 简易 ID 生成(避免引入 crypto 在测试中产生不同 UUID) */
+function randomId() {
+    return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+}
+//# sourceMappingURL=effectiveness-tracker.js.map

package/dist/observability/effectiveness-tracker.js.map

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

package/dist/observability/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Observability barrel
+ *
+ * 四大组件:
+ *   - AuditLog              记录状态变更 + 有效性信号(append-only jsonl)
+ *   - EffectivenessTracker  管理 retrieve_hit 后的观察窗口
+ *   - NecessityEvaluator    proposal 必要性评估(Layer 2)
+ *   - ProposalEngine        主题聚类 + 候选提示
+ *
+ * @module @co-engram/core/observability
+ */
+export * from "./audit-log.js";
+export * from "./effectiveness-tracker.js";
+export * from "./necessity-evaluator.js";
+export * from "./proposal-engine.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/observability/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/observability/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,cAAc,gBAAgB,CAAC;AAC/B,cAAc,4BAA4B,CAAC;AAC3C,cAAc,0BAA0B,CAAC;AACzC,cAAc,sBAAsB,CAAC"}

package/dist/observability/index.js

@@ -0,0 +1,16 @@
+/**
+ * Observability barrel
+ *
+ * 四大组件:
+ *   - AuditLog              记录状态变更 + 有效性信号(append-only jsonl)
+ *   - EffectivenessTracker  管理 retrieve_hit 后的观察窗口
+ *   - NecessityEvaluator    proposal 必要性评估(Layer 2)
+ *   - ProposalEngine        主题聚类 + 候选提示
+ *
+ * @module @co-engram/core/observability
+ */
+export * from "./audit-log.js";
+export * from "./effectiveness-tracker.js";
+export * from "./necessity-evaluator.js";
+export * from "./proposal-engine.js";
+//# sourceMappingURL=index.js.map

package/dist/observability/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/observability/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,cAAc,gBAAgB,CAAC;AAC/B,cAAc,4BAA4B,CAAC;AAC3C,cAAc,0BAA0B,CAAC;AACzC,cAAc,sBAAsB,CAAC"}

package/dist/observability/necessity-evaluator.d.ts

@@ -0,0 +1,116 @@
+/**
+ * 必要性评估器(Necessity Evaluator)
+ *
+ * 在 cluster 晋升 proposal 前,判断"这个反复出现的话题是否值得固化为团队记忆"。
+ * 设计参考 flexmem 的 task 层 `shouldSkipSummary`(8 条规则)+ mem0 的"重要性
+ * 判断交给 extraction LLM,filter 层只过滤明显垃圾"的分工哲学。
+ *
+ * 两层设计:
+ *   - Layer 1(proposal-engine.observe 入口):规则预过滤,零成本挡机械噪声
+ *   - Layer 2(proposal-engine.maybePromoteToProposal):必要性评估
+ *     - 默认 RuleBasedNecessityEvaluator(零依赖,挡 80% 低质量提案)
+ *     - host 可注入 LlmNecessityEvaluator(用 LLM 判断语义必要性)
+ *
+ * core 不绑定 LLM provider,通过 LlmClient 接口抽象;host 自行实现具体适配器
+ * (Anthropic / OpenAI-compatible / 本地模型)。
+ *
+ * @module @co-engram/core/observability
+ */
+/**
+ * Provider-agnostic LLM 调用接口
+ *
+ * host 实现具体适配器:
+ *   - claude-code-mcp:Anthropic API
+ *   - openclaw-plugin:OpenAI-compatible endpoint(可读 ~/.openclaw/openclaw.json)
+ */
+export interface LlmClient {
+    /**
+     * 同步完成一次 LLM 调用,返回生成的文本
+     *
+     * 实现需保证:
+     *   - 失败时抛错(由调用方决定 fallback)
+     *   - 不在内部 catch(LlmNecessityEvaluator 需感知失败以触发 fallback)
+     */
+    complete(prompt: string, opts?: {
+        readonly maxTokens?: number;
+        readonly temperature?: number;
+        readonly timeoutMs?: number;
+    }): Promise<string>;
+}
+/** 评估输入 */
+export interface NecessityInput {
+    /** cluster 累积的样本(已截断为短字符串,最多 maxSamples 条) */
+    readonly samples: readonly string[];
+    /** 累积次数 */
+    readonly occurrences: number;
+    /** 首次见到时间 ISO */
+    readonly firstSeenAt: string;
+    /** 最后见到时间 ISO */
+    readonly lastSeenAt: string;
+    /** 已有 engram 标题(用于重复检测提示,可选) */
+    readonly existingTitles: readonly string[];
+}
+/** 评估结果 */
+export interface NecessityVerdict {
+    /** 是否值得固化为团队记忆 */
+    readonly necessary: boolean;
+    /** 理由(展示给用户看,帮助审批决策) */
+    readonly reason: string;
+    /** 触发的规则名(规则版填充,如 'high_repetition'/'too_short';LLM 版留空) */
+    readonly rule?: string;
+    /** LLM 建议的标题(LLM 版填充,作为用户审批时的草稿) */
+    readonly suggestedTitle?: string;
+}
+/** 评估器接口 */
+export interface NecessityEvaluator {
+    evaluate(input: NecessityInput): Promise<NecessityVerdict>;
+}
+/** 预过滤结果 */
+export interface PrefilterVerdict {
+    readonly accepted: boolean;
+    readonly rule?: string;
+    readonly reason?: string;
+}
+/**
+ * 判断消息是否由 trivial 词主导(占比 > 60%)
+ *
+ * 用于 Layer 1 入口和 Layer 2 cluster 评估
+ */
+export declare function isTrivialDominated(content: string, threshold?: number): boolean;
+/**
+ * Layer 1 预过滤单条消息
+ *
+ * @param content 消息原文
+ * @param role 消息角色(user/assistant/system)
+ * @returns accepted=true 通过;accepted=false 时 rule/reason 标明拒绝原因
+ */
+export declare function prefilterMessage(content: string, role: "user" | "assistant" | "system"): PrefilterVerdict;
+/**
+ * 规则版必要性评估器
+ *
+ * 在 cluster 累积到 threshold 后,从 samples/occurrences 判断是否值得提案。
+ * 规则参考 flexmem `shouldSkipSummary`,适配 co-engram 单层 proposal 场景:
+ *   - rule:high_repetition     samples 内 uniqueRatio < 0.5(机械重复)
+ *   - rule:few_unique_samples  unique samples < 2(完全雷同)
+ *   - rule:too_short           平均长度 < 30 chars
+ *   - rule:low_density         平均有效 token < 5
+ *   - rule:trivial_dominated   70%+ samples 命中 trivial 词表
+ *
+ * 全部通过 → necessary=true,reason="通过 N 条规则检查"
+ */
+export declare class RuleBasedNecessityEvaluator implements NecessityEvaluator {
+    evaluate(input: NecessityInput): Promise<NecessityVerdict>;
+}
+/**
+ * LLM 版必要性评估器
+ *
+ * host 注入 LlmClient,core 不绑定 provider。
+ * LLM 失败时 fallback 到 RuleBasedNecessityEvaluator,保证可用性。
+ */
+export declare class LlmNecessityEvaluator implements NecessityEvaluator {
+    private readonly client;
+    private readonly fallback;
+    constructor(client: LlmClient);
+    evaluate(input: NecessityInput): Promise<NecessityVerdict>;
+}
+//# sourceMappingURL=necessity-evaluator.d.ts.map

package/dist/observability/necessity-evaluator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"necessity-evaluator.d.ts","sourceRoot":"","sources":["../../src/observability/necessity-evaluator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAMH;;;;;;GAMG;AACH,MAAM,WAAW,SAAS;IACxB;;;;;;OAMG;IACH,QAAQ,CACN,MAAM,EAAE,MAAM,EACd,IAAI,CAAC,EAAE;QACL,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;QAC5B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;QAC9B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;KAC7B,GACA,OAAO,CAAC,MAAM,CAAC,CAAC;CACpB;AAMD,WAAW;AACX,MAAM,WAAW,cAAc;IAC7B,8CAA8C;IAC9C,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,WAAW;IACX,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,iBAAiB;IACjB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,iBAAiB;IACjB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,gCAAgC;IAChC,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;CAC5C;AAED,WAAW;AACX,MAAM,WAAW,gBAAgB;IAC/B,kBAAkB;IAClB,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,wBAAwB;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,4DAA4D;IAC5D,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,oCAAoC;IACpC,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CAClC;AAED,YAAY;AACZ,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;CAC5D;AAiFD,YAAY;AACZ,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,SAAM,GAAG,OAAO,CAO5E;AAqBD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,QAAQ,GACpC,gBAAgB,CAqDlB;AA+GD;;;;;;;;;;;;GAYG;AACH,qBAAa,2BAA4B,YAAW,kBAAkB;IAC9D,QAAQ,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,gBAAgB,CAAC;CAqEjE;AAoCD;;;;;GAKG;AACH,qBAAa,qBAAsB,YAAW,kBAAkB;IAGlD,OAAO,CAAC,QAAQ,CAAC,MAAM;IAFnC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA8B;gBAE1B,MAAM,EAAE,SAAS;IAIxC,QAAQ,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,gBAAgB,CAAC;CAiDjE"}