dsh-layered-memory 0.8.7 → 0.8.9

package/dist/store/cost-ledger.js

@@ -0,0 +1,173 @@
+function emptyCostAggregate() {
+    return { calls: 0, inputChars: 0, outputTokens: 0, reasoningTokens: 0, avgOutputTokens: 0, medianOutputTokens: 0 };
+}
+/** 已排序序列的中位数（偶数个取中间两者平均；空返回 0）。 */
+function medianOf(sorted) {
+    const n = sorted.length;
+    if (n === 0)
+        return 0;
+    const mid = Math.floor(n / 2);
+    return n % 2 ? sorted[mid] : (sorted[mid - 1] + sorted[mid]) / 2;
+}
+export class CostLedger {
+    db = null;
+    logger;
+    stmtInsert = null;
+    stmtDelete = null;
+    /** init 是否成功（未就绪 = 宿主库降级，方法全部返回零值不抛错）。 */
+    get ready() {
+        return this.stmtInsert !== null;
+    }
+    /** 建表 + 迁移 + 语句缓存（MemoryDb.initSchema 内调用；失败冒泡触发库级降级）。 */
+    init(db, logger) {
+        this.db = db;
+        this.logger = logger;
+        db.exec(`
+      CREATE TABLE IF NOT EXISTS token_cost (
+        ts INTEGER NOT NULL,
+        provider TEXT NOT NULL,
+        model TEXT NOT NULL,
+        layer TEXT NOT NULL,
+        input_chars INTEGER NOT NULL DEFAULT 0,
+        output_tokens INTEGER NOT NULL DEFAULT 0,
+        reasoning_tokens INTEGER NOT NULL DEFAULT 0
+      )
+    `);
+        // 迁移：provider/model 复合键引入前的旧表补 provider 列（历史行回填 unknown）
+        const cols = db.prepare('PRAGMA table_info(token_cost)').all();
+        if (!cols.some((c) => c.name === 'provider')) {
+            db.exec("ALTER TABLE token_cost ADD COLUMN provider TEXT NOT NULL DEFAULT 'unknown'");
+        }
+        db.exec('CREATE INDEX IF NOT EXISTS idx_token_cost_ts ON token_cost(ts)');
+        this.stmtInsert = db.prepare('INSERT INTO token_cost (ts, provider, model, layer, input_chars, output_tokens, reasoning_tokens) VALUES (?, ?, ?, ?, ?, ?, ?)');
+        this.stmtDelete = db.prepare('DELETE FROM token_cost WHERE ts < ?');
+    }
+    /**
+     * 记录一次蒸馏调用成本（明细表，写入时按 retentionDays 滚动清理；0 = 永久保留）。
+     * 失败/成功都记（token 照烧）；记账失败记 warn 但不阻断蒸馏（成本看板是增强能力）。
+     */
+    insertCostCall(provider, model, layer, inputChars, outputTokens, reasoningTokens, retentionDays) {
+        if (!this.db || !this.stmtInsert || !this.stmtDelete)
+            return;
+        try {
+            this.stmtInsert.run(Date.now(), provider, model, layer, Math.max(0, Math.round(inputChars)), Math.max(0, Math.round(outputTokens)), Math.max(0, Math.round(reasoningTokens)));
+            if (retentionDays > 0)
+                this.stmtDelete.run(Date.now() - retentionDays * 24 * 3600_000);
+        }
+        catch (err) {
+            this.logger?.warn(`[memory][sqlite] token_cost 记账失败: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    /**
+     * 查询 token_cost 单窗口聚合（成本看板用；since 为毫秒起点，0 = 全量）。
+     * 输入口径：inputChars 是字符（llm 流拿不到输入 token，沿用 llm-usage 的字符折算口径）。
+     * median 需取 output_tokens 序列在 JS 侧算（SQLite 无内置 median 函数）。
+     */
+    aggregateCost(since) {
+        if (!this.ready || !this.db)
+            return { total: emptyCostAggregate(), byModel: [] };
+        try {
+            const total = this.db
+                .prepare(`SELECT COUNT(*) AS calls,
+                  COALESCE(SUM(input_chars), 0) AS inputChars,
+                  COALESCE(SUM(output_tokens), 0) AS outputTokens,
+                  COALESCE(SUM(reasoning_tokens), 0) AS reasoningTokens,
+                  COALESCE(AVG(output_tokens), 0) AS avgOutputTokens
+             FROM token_cost WHERE ts >= ?`)
+                .get(since);
+            const tokenRows = this.db
+                .prepare('SELECT output_tokens FROM token_cost WHERE ts >= ? ORDER BY output_tokens')
+                .all(since);
+            const byModel = this.db
+                .prepare(`SELECT provider, model, COUNT(*) AS calls,
+                  COALESCE(SUM(input_chars), 0) AS inputChars,
+                  COALESCE(SUM(output_tokens), 0) AS outputTokens,
+                  COALESCE(SUM(reasoning_tokens), 0) AS reasoningTokens
+             FROM token_cost WHERE ts >= ? GROUP BY provider, model ORDER BY outputTokens DESC`)
+                .all(since);
+            return {
+                total: {
+                    calls: total.calls,
+                    inputChars: total.inputChars,
+                    outputTokens: total.outputTokens,
+                    reasoningTokens: total.reasoningTokens,
+                    avgOutputTokens: total.avgOutputTokens,
+                    medianOutputTokens: medianOf(tokenRows.map((r) => r.output_tokens)),
+                },
+                byModel,
+            };
+        }
+        catch {
+            return { total: emptyCostAggregate(), byModel: [] };
+        }
+    }
+    /**
+     * 按层级归并聚合（l1 = l1-extract + l1-dedup；成本看板层级表格用）。
+     * 降级/异常返回空数组，不抛错。
+     */
+    aggregateCostByLayer(since) {
+        if (!this.ready || !this.db)
+            return [];
+        try {
+            const rows = this.db
+                .prepare(`SELECT CASE WHEN layer IN ('l1-extract','l1-dedup') THEN 'l1' ELSE layer END AS layer,
+                  COUNT(*) AS calls,
+                  COALESCE(SUM(input_chars), 0) AS inputChars,
+                  COALESCE(SUM(output_tokens), 0) AS outputTokens,
+                  COALESCE(SUM(reasoning_tokens), 0) AS reasoningTokens,
+                  COALESCE(AVG(output_tokens), 0) AS avgOutputTokens
+             FROM token_cost WHERE ts >= ? GROUP BY layer ORDER BY layer`)
+                .all(since);
+            // 中位数需取 output_tokens 序列在 JS 侧算（SQLite 无内置 median）
+            const tokenRows = this.db
+                .prepare(`SELECT CASE WHEN layer IN ('l1-extract','l1-dedup') THEN 'l1' ELSE layer END AS layer,
+                  output_tokens
+             FROM token_cost WHERE ts >= ? ORDER BY layer, output_tokens`)
+                .all(since);
+            const medianByLayer = new Map();
+            for (const r of tokenRows) {
+                const arr = medianByLayer.get(r.layer);
+                if (arr)
+                    arr.push(r.output_tokens);
+                else
+                    medianByLayer.set(r.layer, [r.output_tokens]);
+            }
+            return rows.map((r) => ({
+                ...r,
+                medianOutputTokens: medianOf(medianByLayer.get(r.layer) ?? []),
+            }));
+        }
+        catch {
+            return [];
+        }
+    }
+    /**
+     * 按时间桶（bucketMs 毫秒）+ model 聚合，返回扁平行。
+     * offsetMs 把桶边界对齐本地时区；layer 为空=全部，'l1' 归并 extract/dedup，其余精确匹配。
+     * 趋势图与「日均/周均/月均 + 中位数」统计共用：JS 侧按不同 bucketMs 调三次再聚合。
+     */
+    aggregateByBucket(bucketMs, offsetMs, since, layer) {
+        if (!this.ready || !this.db)
+            return [];
+        try {
+            let sql = `SELECT CAST((ts + ?) / ? AS INTEGER) AS bucket, provider, model,
+                COUNT(*) AS calls,
+                COALESCE(SUM(output_tokens), 0) AS outputTokens,
+                COALESCE(SUM(reasoning_tokens), 0) AS reasoningTokens
+           FROM token_cost WHERE ts >= ?`;
+            const params = [offsetMs, bucketMs, since];
+            if (layer === 'l1') {
+                sql += ` AND layer IN ('l1-extract','l1-dedup')`;
+            }
+            else if (layer) {
+                sql += ` AND layer = ?`;
+                params.push(layer);
+            }
+            sql += ` GROUP BY bucket, provider, model ORDER BY bucket, provider, model`;
+            return this.db.prepare(sql).all(...params);
+        }
+        catch {
+            return [];
+        }
+    }
+}

package/dist/store/download-queue.d.ts

@@ -1,24 +1,7 @@
 import type { MemoryLogger } from '../types.js';
 import { type CatalogEntry } from './model-catalog.js';
-export type DownloadPhase = 'downloading' | 'verifying' | 'done' | 'cancelled' | 'error';
-export interface DownloadProgress {
-    modelId: string;
-    phase: DownloadPhase;
-    /** 当前文件序号（1-based）。 */
-    fileIndex: number;
-    fileCount: number;
-    /** 当前文件已收字节（含续传基线）。 */
-    fileReceived: number;
-    fileTotal: number;
-    /** 整模型累计字节（含已完成文件；分母 = 目录总大小）。 */
-    overallReceived: number;
-    overallTotal: number;
-    /** EMA 平滑速度（字节/秒）。 */
-    speedBps: number;
-    startedAt: number;
-    /** phase=error 时的原因。 */
-    error?: string;
-}
+import type { DownloadProgress } from '../contract.js';
+export type { DownloadPhase, DownloadProgress } from '../contract.js';
 export interface ModelStatus {
     id: string;
     /** none=未下载；partial=有断点/不完整；downloaded=全部文件就位且尺寸吻合。 */
@@ -104,4 +87,3 @@ export declare function resolveProxyUrl(setting: string | undefined, host: strin
 /** 代理 URL 日志脱敏：剥掉 userinfo（内网代理常带 user:pass 凭据），只留 scheme//host；
  *  解析失败的串原样也可能是凭据形态，返回占位符。 */
 export declare function maskProxyUrl(proxy: string): string;
-export {};

package/dist/store/embedding-source.d.ts

@@ -7,7 +7,8 @@ import { LocalEmbeddingService } from './local-embedding.js';
 import { ModelDownloadQueue } from './download-queue.js';
 import { RuntimeInstaller } from './runtime-installer.js';
 import type { MemoryDb } from './sqlite.js';
-export type EmbeddingSourceKind = 'remote' | 'local' | 'off';
+import type { EmbeddingSourceKind, EmbeddingStateView } from '../contract.js';
+export type { ApplyPhase, EmbeddingSourceKind, EmbeddingStateView, ReindexProgressState } from '../contract.js';
 export interface EmbeddingSourceState {
     source: EmbeddingSourceKind;
     /** source=local 时启用的目录模型 id。 */
@@ -38,17 +39,6 @@ export declare function resolveInitialEmbedding(cfg: MemoryConfig, sourceStore:
 /** 本地服务构造工厂（index.ts 的初始解析与 Manager 共用一份实现，防漂移）。
  *  推理在 worker 线程（见 local-embedding.ts）；此处只传 runtime 目录与模型目录。 */
 export declare function makeLocalServiceFactory(installer: RuntimeInstaller, downloader: ModelDownloadQueue, logger?: MemoryLogger, maxInputChars?: number): (modelId: string) => LocalEmbeddingService | null;
-export type ApplyPhase = 'idle' | 'installing-runtime' | 'warming' | 'switching' | 'reindexing' | 'done' | 'error';
-export interface ReindexProgressState {
-    running: boolean;
-    l1Done: number;
-    l1Total: number;
-    l0Done: number;
-    l0Total: number;
-    startedAt: number;
-    cancelled: boolean;
-    error?: string;
-}
 export interface EmbeddingManagerDeps {
     dataDir: string;
     cfg: MemoryConfig;
@@ -119,43 +109,3 @@ export declare class EmbeddingManager {
     /** RPC 快照（设置页嵌入区块数据源；client 忙时 1s 轮询）。 */
     snapshot(): Promise<EmbeddingStateView>;
 }
-export interface EmbeddingStateView {
-    source: EmbeddingSourceKind;
-    activeModel: string | null;
-    ceilings: {
-        remote: boolean;
-        local: boolean;
-    };
-    runtime: {
-        targetVersion: string;
-        phase: 'idle' | 'installing' | 'ready' | 'error' | 'cancelled';
-        installedVersion: string | null;
-        elapsedMs: number;
-        lastLines: string[];
-        error?: string;
-    };
-    models: Array<{
-        id: string;
-        name: string;
-        dims: number;
-        contextTokens: number;
-        tags: string[];
-        description: string;
-        totalBytes: number;
-        bytesOnDisk: number;
-        state: 'none' | 'partial' | 'downloaded';
-    }>;
-    download: ReturnType<ModelDownloadQueue['getProgress']>;
-    apply: {
-        phase: ApplyPhase;
-        message: string;
-        startedAt: number;
-        busy: boolean;
-    };
-    local: {
-        state: 'idle' | 'loading' | 'ready' | 'failed' | 'terminated';
-        error: string | null;
-    } | null;
-    reindex: ReindexProgressState;
-    activeNote?: string;
-}

package/dist/store/occupancy.d.ts

@@ -0,0 +1,30 @@
+import type { MemoryLogger } from '../types.js';
+import type { OccupancyLedger } from '../util/context-occupancy.js';
+/** 会话条目上限（按 updatedAt 淘汰最旧；防文件无限增长）。 */
+export declare const OCCUPANCY_SESSION_CAP = 200;
+export declare class OccupancyStore {
+    private readonly logger?;
+    private readonly file;
+    private readonly entries;
+    private persistFailed;
+    /** 串行化持久化写（避免并发原子写撞临时文件名）；init 链最前（先载入再落盘，防丢更新）。 */
+    private writeChain;
+    constructor(dataDir: string, logger?: MemoryLogger | undefined);
+    /** 载入持久化账目（合并进内存——构造与载入之间发生的 save 不丢）；失败降级内存态。 */
+    private init;
+    /**
+     * 该会话的持久化账目（热路径同步读；从未注入/已复位返回 null）。
+     * 返回**浅拷贝**——调用方（ledgerFor 复生）会在其上做迁移；若交出内部引用，
+     * 原地修改会让 save() 的 prev/ledger 恒等比较误判“数值未变”而跳过写穿（实测踩坑）。
+     */
+    load(sessionId: string): OccupancyLedger | null;
+    /**
+     * 迁移后写穿。数值未变只刷新内存时间戳不落盘（profile 稳定区每次请求组装都
+     * 触发迁移，但内容不变时不应产生文件写）；stock 归零即删除条目。
+     */
+    save(sessionId: string, ledger: OccupancyLedger): void;
+    /** 等待在途持久化写完成（测试/停机用）。 */
+    flush(): Promise<void>;
+    private persist;
+    private serialize;
+}

package/dist/store/occupancy.js

@@ -0,0 +1,134 @@
+/**
+ * 记忆占用流水存储：sessionId → OccupancyLedger 的持久化映射。
+ *
+ * 动机（2026-08-27 票07）：占用账本是进程内存态，dsh 重启后历史会话"窗口里明明
+ * 有记忆、账面却为零"，指示器对重启前注入的存量失明。本存储让账目跨进程复生：
+ * - 每次账本迁移后写穿（recall-dedupe 同款：串行化原子写 + 失败降级内存态）；
+ * - 查询热路径仍是同步内存读——文件只在迁移时刻与启动载入时触碰；
+ * - stock 归零的条目不落盘（compaction 复位即天然删除）；
+ * - agent 销毁不删记录（持久化语义与召回去重一致：会话恢复后账目继续）；
+ * - 90 天未更新过期清理 + 会话条目上限（session-modes/dedupe 同款量级）。
+ */
+import * as path from 'node:path';
+import { errDetail } from '../util/filelog.js';
+import { atomicWriteJson, ensureDir, readJsonIfExists } from './io.js';
+/** 会话条目上限（按 updatedAt 淘汰最旧；防文件无限增长）。 */
+export const OCCUPANCY_SESSION_CAP = 200;
+/** 条目过期清理（90 天未更新即丢弃，与 session-modes/dedupe 同款量级）。 */
+const PRUNE_MS = 90 * 24 * 3600_000;
+export class OccupancyStore {
+    logger;
+    file;
+    entries = new Map();
+    persistFailed = false;
+    /** 串行化持久化写（避免并发原子写撞临时文件名）；init 链最前（先载入再落盘，防丢更新）。 */
+    writeChain;
+    constructor(dataDir, logger) {
+        this.logger = logger;
+        this.file = path.join(dataDir, 'occupancy.json');
+        this.writeChain = this.init();
+    }
+    /** 载入持久化账目（合并进内存——构造与载入之间发生的 save 不丢）；失败降级内存态。 */
+    async init() {
+        const data = await readJsonIfExists(this.file);
+        if (!data?.sessions || typeof data.sessions !== 'object')
+            return;
+        const now = Date.now();
+        let count = 0;
+        for (const [sid, entry] of Object.entries(data.sessions)) {
+            if (typeof entry?.stockTokens !== 'number')
+                continue;
+            if (now - (entry.updatedAt ?? 0) > PRUNE_MS)
+                continue;
+            const existing = this.entries.get(sid);
+            if (existing) {
+                if (entry.updatedAt > existing.updatedAt)
+                    this.entries.set(sid, { ...entry });
+            }
+            else {
+                this.entries.set(sid, { ...entry });
+            }
+            count++;
+        }
+        if (count > 0)
+            this.logger?.info(`[memory] 记忆占用账目载入 ${count} 个会话`);
+    }
+    /**
+     * 该会话的持久化账目（热路径同步读；从未注入/已复位返回 null）。
+     * 返回**浅拷贝**——调用方（ledgerFor 复生）会在其上做迁移；若交出内部引用，
+     * 原地修改会让 save() 的 prev/ledger 恒等比较误判“数值未变”而跳过写穿（实测踩坑）。
+     */
+    load(sessionId) {
+        const e = this.entries.get(sessionId);
+        return e ? { ...e } : null;
+    }
+    /**
+     * 迁移后写穿。数值未变只刷新内存时间戳不落盘（profile 稳定区每次请求组装都
+     * 触发迁移，但内容不变时不应产生文件写）；stock 归零即删除条目。
+     */
+    save(sessionId, ledger) {
+        const prev = this.entries.get(sessionId);
+        const sameNumbers = prev !== undefined &&
+            prev.stockTokens === ledger.stockTokens &&
+            prev.recallTokens === ledger.recallTokens &&
+            prev.profileTokens === ledger.profileTokens &&
+            prev.lastInjectTokens === ledger.lastInjectTokens;
+        if (sameNumbers) {
+            prev.updatedAt = ledger.updatedAt;
+            return;
+        }
+        if (ledger.stockTokens <= 0) {
+            if (prev === undefined)
+                return;
+            this.entries.delete(sessionId);
+        }
+        else {
+            this.entries.set(sessionId, { ...ledger });
+        }
+        this.writeChain = this.writeChain.then(() => this.persist());
+    }
+    /** 等待在途持久化写完成（测试/停机用）。 */
+    flush() {
+        return this.writeChain;
+    }
+    async persist() {
+        try {
+            await ensureDir(path.dirname(this.file));
+            await atomicWriteJson(this.file, this.serialize());
+            this.persistFailed = false;
+        }
+        catch (err) {
+            if (!this.persistFailed) {
+                this.persistFailed = true;
+                this.logger?.warn(`[memory] 记忆占用持久化失败（降级内存态）: ${errDetail(err)}`);
+            }
+        }
+    }
+    serialize() {
+        const now = Date.now();
+        for (const [sid, e] of this.entries) {
+            if (now - e.updatedAt > PRUNE_MS && e.updatedAt > 0)
+                this.entries.delete(sid);
+        }
+        while (this.entries.size > OCCUPANCY_SESSION_CAP) {
+            let oldest;
+            let oldestAt = Infinity;
+            for (const [sid, e] of this.entries) {
+                if (e.updatedAt > 0 && e.updatedAt < oldestAt) {
+                    oldest = sid;
+                    oldestAt = e.updatedAt;
+                }
+            }
+            if (oldest === undefined)
+                break;
+            this.entries.delete(oldest);
+        }
+        const sessions = {};
+        for (const [sid, e] of this.entries) {
+            if (e.stockTokens <= 0)
+                continue; // 归零条目不落盘
+            sessions[sid] = { ...e };
+        }
+        return { version: 1, sessions };
+    }
+}

package/dist/store/runtime-installer.d.ts

@@ -1,19 +1,8 @@
 import type { MemoryLogger } from '../types.js';
 /** 钉死的 transformers.js 版本（D8：精确版本，升级插件时在此变更并重装运行时）。 */
 export declare const PINNED_TRANSFORMERS_VERSION = "4.2.0";
-export interface RuntimeProgress {
-    phase: 'idle' | 'installing' | 'ready' | 'error' | 'cancelled';
-    /** 插件钉死的目标版本。 */
-    targetVersion: string;
-    /** runtime 里实际就位的版本（未安装为 null）。 */
-    installedVersion: string | null;
-    startedAt: number;
-    /** 已运行毫秒（读时计算）。 */
-    elapsedMs: number;
-    /** npm 输出尾行（最近 5 行，让用户看到 npm 在干什么）。 */
-    lastLines: string[];
-    error?: string;
-}
+import type { RuntimeProgress } from '../contract.js';
+export type { RuntimeProgress } from '../contract.js';
 /** 子进程抽象（测试注入缝）：注册输出行回调 + 终止 + 终态。 */
 export interface SpawnedProcess {
     onStdout(cb: (line: string) => void): void;

package/dist/store/sqlite.d.ts

@@ -9,45 +9,10 @@ export interface StoreCapabilities {
     ftsSearch: boolean;
     vectorSearch: boolean;
 }
-/** token_cost 单窗口成本聚合（成本看板用）。 */
-export interface CostAggregate {
-    calls: number;
-    inputChars: number;
-    outputTokens: number;
-    reasoningTokens: number;
-    /** 单次调用输出 token 均值（无数据为 0）。 */
-    avgOutputTokens: number;
-    /** 单次调用输出 token 中位数（无数据为 0）。 */
-    medianOutputTokens: number;
-}
-/** 按 model 分组的成本行（成本看板用）。 */
-export interface CostByModel {
-    provider: string;
-    model: string;
-    calls: number;
-    inputChars: number;
-    outputTokens: number;
-    reasoningTokens: number;
-}
-/** 按层级（l1/l2/l3 归并）分组的成本行。 */
-export interface CostByLayer {
-    layer: string;
-    calls: number;
-    inputChars: number;
-    outputTokens: number;
-    reasoningTokens: number;
-    avgOutputTokens: number;
-    medianOutputTokens: number;
-}
-/** 按时间桶 + provider/model 聚合的扁平行（趋势图与日均/周均/月均 + 中位数统计共用）。 */
-export interface BucketRow {
-    bucket: number;
-    provider: string;
-    model: string;
-    calls: number;
-    outputTokens: number;
-    reasoningTokens: number;
-}
+import { CostLedger } from './cost-ledger.js';
+import type { BucketRow, CostAggregate, CostByLayer } from './cost-ledger.js';
+export type { BucketRow, CostAggregate, CostByLayer } from './cost-ledger.js';
+import type { CostByModel } from '../contract.js';
 /** L1 检索命中（含 BM25/余弦归一分数）。 */
 export interface L1SearchHit {
     id: string;
@@ -62,6 +27,7 @@ export interface L1SearchHit {
 export interface L0SearchHit extends L0MessageRecord {
     score: number;
 }
+/** 已排序序列的中位数（偶数个取中间两者平均；空返回 0）。 */
 export declare class MemoryDb {
     private db;
     private degraded;
@@ -83,9 +49,8 @@ export declare class MemoryDb {
     private stmtL1FtsDelete;
     private stmtL1FtsSearch;
     private stmtL1FtsSearchFamily;
-    /** token_cost 明细写入 / 滚动清理语句（构造期 prepare 缓存）。 */
-    private stmtInsertCost;
-    private stmtDeleteCost;
+    /** 成本账本（token_cost 表族；init 内初始化，未就绪时方法返回零值）。 */
+    readonly costLedger: CostLedger;
     private stmtUpsertL0;
     private stmtGetL0;
     /** 主表存在性点查（同 L1：防御性 FTS 删除的前置判断）。 */
@@ -187,31 +152,16 @@ export declare class MemoryDb {
     searchL1Vector(embedding: Float32Array, topK: number, family?: string): L1SearchHit[];
     /** 批量 upsert L0 消息（元数据 + FTS；embeddings 与 records 等长，可省略）。 */
     upsertL0Batch(records: L0MessageRecord[], embeddings?: Array<Float32Array | undefined>): boolean;
-    /**
-     * 记录一次蒸馏调用成本（明细表，写入时按 retentionDays 滚动清理；0 = 永久保留）。
-     * 失败/成功都记（token 照烧）；记账失败记 warn 但不阻断蒸馏（成本看板是增强能力）。
-     */
+    /** 记录一次蒸馏调用成本（委托 cost-ledger；语义见 CostLedger.insertCostCall）。 */
     insertCostCall(provider: string, model: string, layer: string, inputChars: number, outputTokens: number, reasoningTokens: number, retentionDays: number): void;
-    /**
-     * 查询 token_cost 单窗口聚合（成本看板用；since 为毫秒起点，0 = 全量）。
-     * 输入口径：inputChars 是字符（llm 流拿不到输入 token，沿用 llm-usage 的字符折算口径）。
-     * 成本看板是增强能力：降级态/查询异常一律返回零值，不向上抛错。
-     * median 需取 output_tokens 序列在 JS 侧算（SQLite 无内置 median 函数）。
-     */
+    /** 查询 token_cost 单窗口聚合（委托 cost-ledger；降级/异常返回零值）。 */
     aggregateCost(since: number): {
         total: CostAggregate;
         byModel: CostByModel[];
     };
-    /**
-     * 按层级归并聚合（l1 = l1-extract + l1-dedup；成本看板层级表格用）。
-     * 降级/异常返回空数组，不抛错。
-     */
+    /** 按层级归并聚合（委托 cost-ledger；降级/异常返回空数组）。 */
     aggregateCostByLayer(since: number): CostByLayer[];
-    /**
-     * 按时间桶（bucketMs 毫秒）+ model 聚合，返回扁平行。
-     * offsetMs 把桶边界对齐本地时区；layer 为空=全部，'l1' 归并 extract/dedup，其余精确匹配。
-     * 趋势图与「日均/周均/月均 + 中位数」统计共用：JS 侧按不同 bucketMs 调三次再聚合。
-     */
+    /** 按时间桶 + model 聚合（委托 cost-ledger；趋势图与日均/周均/月均共用）。 */
     aggregateByBucket(bucketMs: number, offsetMs: number, since: number, layer: string): BucketRow[];
     countL0(): number;
     /** 统计 recorded_at >= iso 的消息数（状态面板"今日捕获"用）。 */