dsh-prime-memory 0.16.2 → 0.16.4

package/dist/store/recall-usage.js

@@ -0,0 +1,149 @@
+/**
+ * 召回使用统计 sidecar(老化权重效果统计的数据面)。
+ *
+ * 口径(用户裁定):**进 topN(被注入上下文)才算被使用**;参与尝试未进 = 只有
+ * attempts。每轮召回 recordAttempt(候选集, 注入集)——内存即时、去抖原子持久化
+ * (召回是热路径,统计只碰内存 Map)。
+ *
+ * 存储:`recall-usage.json` slots 式 sidecar,与 rooms-registry/session-modes 同族
+ * 纪律:缺失 = 合法空表;损坏/不可读 → 只读降级(内存态照常,停止回写),绝不阻塞
+ * 召回读路径(R2 红线)。
+ */
+import * as path from 'node:path';
+import { readJsonStrict, atomicWriteText, ensureDir } from '../util/io.js';
+export const RECALL_USAGE_FILE_VERSION = 1;
+/** 条目上限(防已退场/被取代记忆的 id 无限累积):超限按 lastAttemptAt 淘汰最旧。 */
+const MAX_ENTRIES = 50_000;
+/** 去抖持久化间隔(召回热路径;窗口内断电最多丢最近统计,不影响记忆本体)。 */
+const PERSIST_DEBOUNCE_MS = 5_000;
+export class RecallUsageStore {
+    logger;
+    file;
+    entries = new Map();
+    loaded = false;
+    degraded;
+    degradedLogged = false;
+    writeTimer;
+    writeChain = Promise.resolve();
+    constructor(dataDir, logger) {
+        this.logger = logger;
+        this.file = path.join(dataDir, 'recall-usage.json');
+    }
+    async init() {
+        await ensureDir(path.dirname(this.file));
+        const read = await readJsonStrict(this.file);
+        if (!read.ok) {
+            if (read.reason !== 'missing') {
+                this.degraded = `${read.reason}${'detail' in read && read.detail ? `: ${read.detail}` : ''}`;
+                this.logger?.warn(`[memory] 召回使用统计只读降级: ${this.degraded}`);
+            }
+            this.loaded = true;
+            return;
+        }
+        const raw = read.value.entries ?? {};
+        for (const [id, e] of Object.entries(raw)) {
+            if (!e || typeof e.attempts !== 'number')
+                continue;
+            this.entries.set(id, {
+                attempts: e.attempts,
+                used: typeof e.used === 'number' ? e.used : 0,
+                lastAttemptAt: typeof e.lastAttemptAt === 'number' ? e.lastAttemptAt : null,
+                lastUsedAt: typeof e.lastUsedAt === 'number' ? e.lastUsedAt : null,
+            });
+        }
+        this.loaded = true;
+    }
+    ensureLoaded() {
+        if (!this.loaded)
+            throw new Error('召回使用统计未初始化(先 await init())');
+    }
+    /** 一轮召回:候选集 attempts++/lastAttemptAt=now;used 子集额外 used++/lastUsedAt=now
+     *  (used 不在候选内 = 防御路径,同样算一次尝试——用了就是被尝试过)。 */
+    recordAttempt(candidateIds, usedIds) {
+        this.ensureLoaded();
+        if (candidateIds.length === 0 && usedIds.length === 0)
+            return;
+        const now = Date.now();
+        const cand = new Set(candidateIds);
+        for (const id of cand) {
+            const e = this.entries.get(id) ?? { attempts: 0, used: 0, lastAttemptAt: null, lastUsedAt: null };
+            e.attempts += 1;
+            e.lastAttemptAt = now;
+            this.entries.set(id, e);
+        }
+        for (const id of usedIds) {
+            const e = this.entries.get(id) ?? { attempts: 0, used: 0, lastAttemptAt: null, lastUsedAt: null };
+            e.used += 1;
+            if (!cand.has(id)) {
+                e.attempts += 1;
+                e.lastAttemptAt = now;
+            }
+            e.lastUsedAt = now;
+            this.entries.set(id, e);
+        }
+        this.prune();
+        this.schedulePersist();
+    }
+    get(id) {
+        this.ensureLoaded();
+        const e = this.entries.get(id);
+        return e ? { ...e } : undefined;
+    }
+    summary() {
+        this.ensureLoaded();
+        let attempted = 0;
+        let used = 0;
+        for (const e of this.entries.values()) {
+            attempted += e.attempts;
+            used += e.used;
+        }
+        return { tracked: this.entries.size, attempted, used, rate: attempted > 0 ? Math.round((used / attempted) * 100) : 0 };
+    }
+    /** 立即落盘(去抖窗口内的兜底;测试/停机用)。 */
+    flush() {
+        if (this.writeTimer) {
+            clearTimeout(this.writeTimer);
+            this.writeTimer = undefined;
+        }
+        return this.persist();
+    }
+    /** 同步等待在途写(测试用;无在途写时立即返回)。 */
+    flushSync() {
+        void this.flush();
+    }
+    prune() {
+        if (this.entries.size <= MAX_ENTRIES)
+            return;
+        const byOldest = [...this.entries.entries()].sort((a, b) => (a[1].lastAttemptAt ?? 0) - (b[1].lastAttemptAt ?? 0));
+        for (const [id] of byOldest.slice(0, this.entries.size - MAX_ENTRIES))
+            this.entries.delete(id);
+    }
+    schedulePersist() {
+        if (this.degraded || this.writeTimer)
+            return;
+        this.writeTimer = setTimeout(() => {
+            this.writeTimer = undefined;
+            void this.persist();
+        }, PERSIST_DEBOUNCE_MS);
+        this.writeTimer.unref?.(); // 不为统计写hold进程(停机即丢窗口内统计,可接受)
+    }
+    async persist() {
+        if (this.degraded)
+            return;
+        this.writeChain = this.writeChain.then(async () => {
+            try {
+                await ensureDir(path.dirname(this.file));
+                const data = { version: RECALL_USAGE_FILE_VERSION, entries: Object.fromEntries(this.entries) };
+                await atomicWriteText(this.file, JSON.stringify(data));
+            }
+            catch (err) {
+                this.degraded = err instanceof Error ? err.message : String(err);
+                if (!this.degradedLogged) {
+                    this.degradedLogged = true;
+                    this.logger?.warn(`[memory] 召回使用统计写入失败,只读降级: ${this.degraded}`);
+                }
+            }
+        });
+        await this.writeChain;
+    }
+}

package/dist/store/rooms-registry.d.ts

@@ -0,0 +1,66 @@
+import type { MemoryLogger } from '../types.js';
+/** 版本常量(file-versions 同款集中纪律;registry 为独立 sidecar 文件)。 */
+export declare const ROOMS_REGISTRY_FILE_VERSION: 1;
+export interface RoomRegistryEntry {
+    /** Room slug(小写字母数字连字符;与自生长 tags 同域,isTag 校验)。 */
+    slug: string;
+    /** 人类可读名(面板/标注器提示;可中文)。 */
+    label?: string;
+    /** 归类说明(喂标注器,对 LLM 归类价值最高)。 */
+    description?: string;
+    /** 来源:pre-registered(预注册)| grown(从自生长 slug 收编)。 */
+    source: 'pre-registered' | 'grown';
+    /** 合并/改名时的旧 slug(标注器与导出消歧;不参与 list({tag}) 查询)。 */
+    aliases?: string[];
+    status: 'active' | 'retired';
+    createdAt: string;
+    updatedAt: string;
+}
+export type RoomRegistryInput = Pick<RoomRegistryEntry, 'slug'> & Partial<Pick<RoomRegistryEntry, 'label' | 'description' | 'source' | 'aliases'>>;
+/**
+ * 两级 Room slug(`major` 或 `major/minor`):事实源在 metadata-validators.ts
+ * (normTags 写回闸同源放行),此处 re-export 兼容既有导入。
+ */
+export { isRoomSlug } from '../metadata-validators.js';
+/** 大类归属:`major/minor` 取 major;平级 slug 自身即大类。 */
+export declare function majorOf(slug: string): string;
+export declare class RoomRegistryStore {
+    private readonly logger?;
+    private readonly file;
+    private entries;
+    private rev;
+    private loaded;
+    private degraded;
+    private degradedLogged;
+    private writeChain;
+    constructor(dataDir: string, logger?: MemoryLogger | undefined);
+    /** 载入(启动时 await 一次)。缺失 = 合法空表;损坏/不可读 = 只读降级(回退自生长目录)。 */
+    init(): Promise<void>;
+    private ensureLoaded;
+    /** 全量条目(含 retired;副本返回,活引用纪律)。 */
+    list(): RoomRegistryEntry[];
+    /** active 条目(rooms-get 合并与标注器词表来源)。 */
+    listActive(): RoomRegistryEntry[];
+    /** 精确 slug 查找(含 retired;含别名命中)。 */
+    bySlug(slug: string): RoomRegistryEntry | undefined;
+    /** 注册(幂等:已存在——含别名命中——时原地补全 label/description,不新建)。上限 200 防刷。 */
+    register(input: RoomRegistryInput): Promise<{
+        entry: RoomRegistryEntry;
+        created: boolean;
+    }>;
+    /** 编辑已有条目的 label/description(注册后可重编辑;未提供的字段不动;未找到=false)。 */
+    update(slug: string, patch: {
+        label?: string;
+        description?: string;
+    }): Promise<boolean>;
+    /** 改状态(active↔retired);无变化返回 false。 */
+    setStatus(slug: string, status: 'active' | 'retired'): Promise<boolean>;
+    /** 改名(merge 1:1 收尾):slug 换名 + 旧 slug 进 aliases。新名与既有条目冲突时走 merge。
+     *  目标用两级制词表(isRoomSlug)——把 standalone room 归类到 hall 下(改名 major/minor)
+     *  走的就是这条路;isTag 会误拒带 slash 的目标。 */
+    renameSlug(oldSlug: string, newSlug: string): Promise<boolean>;
+    /** 合并收尾:fromSlug 条目转 retired + toSlug 进 aliases(记录重写由调用方游标执行)。 */
+    markMerged(fromSlug: string, toSlug: string): Promise<boolean>;
+    /** 写穿持久化(串行链;失败降级内存态并告警一次)。 */
+    private persist;
+}

package/dist/store/rooms-registry.js

@@ -0,0 +1,250 @@
+/**
+ * Room 注册表(预注册词表,分类管理 beta.4)。
+ *
+ * 动机:Room 此前纯自生长(metadata.tags 涌现),tags 标注器不参考词表——
+ * 「81 个 Room 大多 1 条」的碎片化即来源于此。注册表让「策划好的分类」先行:
+ * 候选标注器与 tags 标注器优先挂靠注册表 slug;零计数注册条目也进词表。
+ *
+ * 存储:slots 式 sidecar(`rooms-registry.json`),全量载入内存 + 写穿原子持久化,
+ * `rev` 乐观观察计数。**读侧分类**(occupancy 同款):文件缺失 = 合法空表;
+ * 损坏/不可读 → 告警 + 只读降级(内存态照常生效,停止回写)——降级即**回退纯
+ * 自生长目录**,绝不阻塞 rooms-get / 标注器(R2 红线)。
+ */
+import * as path from 'node:path';
+import { isRoomSlug } from '../metadata-validators.js';
+import { readJsonStrict, atomicWriteText, ensureDir } from '../util/io.js';
+/** 版本常量(file-versions 同款集中纪律;registry 为独立 sidecar 文件)。 */
+export const ROOMS_REGISTRY_FILE_VERSION = 1;
+/** 大类(顶层)注册上限(防刷)。小类(`major/minor`)不占大类额度,另有总量保险。 */
+const REGISTRY_MAJOR_CAP = 200;
+/** 全量保险上限(大类+小类总和;防极端滥用)。 */
+const REGISTRY_TOTAL_CAP = 2000;
+/**
+ * 两级 Room slug(`major` 或 `major/minor`):事实源在 metadata-validators.ts
+ * (normTags 写回闸同源放行),此处 re-export 兼容既有导入。
+ */
+export { isRoomSlug } from '../metadata-validators.js';
+/** 大类归属:`major/minor` 取 major;平级 slug 自身即大类。 */
+export function majorOf(slug) {
+    const i = slug.indexOf('/');
+    return i === -1 ? slug : slug.slice(0, i);
+}
+/** aliases 上限(合并/改名历史)。 */
+const ALIASES_CAP = 16;
+export class RoomRegistryStore {
+    logger;
+    file;
+    entries = [];
+    rev = 0;
+    loaded = false;
+    degraded;
+    degradedLogged = false;
+    writeChain = Promise.resolve();
+    constructor(dataDir, logger) {
+        this.logger = logger;
+        this.file = path.join(dataDir, 'rooms-registry.json');
+    }
+    /** 载入(启动时 await 一次)。缺失 = 合法空表;损坏/不可读 = 只读降级(回退自生长目录)。 */
+    async init() {
+        await ensureDir(path.dirname(this.file));
+        const read = await readJsonStrict(this.file);
+        if (!read.ok) {
+            if (read.reason !== 'missing') {
+                this.degraded = `${read.reason}${'detail' in read && read.detail ? `: ${read.detail}` : ''}`;
+                this.logger?.warn(`[memory] Room 注册表只读降级(回退纯自生长目录): ${this.degraded}`);
+            }
+            this.loaded = true;
+            return;
+        }
+        if (read.value.version !== ROOMS_REGISTRY_FILE_VERSION) {
+            this.logger?.warn(`[memory] Room 注册表版本 ${String(read.value.version)} 未知,按当前形状读取`);
+        }
+        const rooms = Array.isArray(read.value.rooms) ? read.value.rooms : [];
+        for (const r of rooms) {
+            if (!r || typeof r.slug !== 'string' || !isRoomSlug(r.slug))
+                continue; // 非法 slug 丢弃——两级制,isTag 会误丢 hall/minor(beta.17 修)
+            this.entries.push({
+                slug: r.slug,
+                label: typeof r.label === 'string' ? r.label : undefined,
+                description: typeof r.description === 'string' ? r.description : undefined,
+                source: r.source === 'grown' ? 'grown' : 'pre-registered',
+                aliases: Array.isArray(r.aliases) ? r.aliases.filter((a) => typeof a === 'string' && a !== '') : undefined,
+                status: r.status === 'retired' ? 'retired' : 'active',
+                createdAt: typeof r.createdAt === 'string' ? r.createdAt : '',
+                updatedAt: typeof r.updatedAt === 'string' ? r.updatedAt : '',
+            });
+        }
+        this.rev = typeof read.value.rev === 'number' ? read.value.rev : 0;
+        this.loaded = true;
+    }
+    ensureLoaded() {
+        if (!this.loaded)
+            throw new Error('Room 注册表未初始化(先 await init())');
+    }
+    /** 全量条目(含 retired;副本返回,活引用纪律)。 */
+    list() {
+        this.ensureLoaded();
+        return this.entries.map((e) => ({ ...e }));
+    }
+    /** active 条目(rooms-get 合并与标注器词表来源)。 */
+    listActive() {
+        return this.list().filter((e) => e.status === 'active');
+    }
+    /** 精确 slug 查找(含 retired;含别名命中)。 */
+    bySlug(slug) {
+        this.ensureLoaded();
+        const found = this.entries.find((e) => e.slug === slug || (e.aliases ?? []).includes(slug));
+        return found ? { ...found } : undefined;
+    }
+    /** 注册(幂等:已存在——含别名命中——时原地补全 label/description,不新建)。上限 200 防刷。 */
+    async register(input) {
+        this.ensureLoaded();
+        const slug = String(input.slug ?? '').trim().toLowerCase();
+        if (!slug || !isRoomSlug(slug)) {
+            throw new Error(`非法 Room slug: ${String(input.slug)}(两级制:major 或 major/minor,各段小写字母数字连字符)`);
+        }
+        const found = this.entries.find((e) => e.slug === slug || (e.aliases ?? []).includes(slug));
+        if (found) {
+            let changed = false;
+            if (!found.label && typeof input.label === 'string' && input.label.trim()) {
+                found.label = input.label.trim().slice(0, 60);
+                changed = true;
+            }
+            if (!found.description && typeof input.description === 'string' && input.description.trim()) {
+                found.description = input.description.trim().slice(0, 300);
+                changed = true;
+            }
+            if (changed) {
+                found.updatedAt = new Date().toISOString();
+                this.rev++;
+                await this.persist();
+            }
+            return { entry: { ...found }, created: false };
+        }
+        // 额度两级制(用户裁定:200 上限只管大类;小类细分不占大类额度):
+        // 大类 = slug 无 '/' 的条目 ∪ 已用 major 前缀;小类只受总量保险约束。
+        const isMinor = slug.includes('/');
+        if (isMinor && this.entries.length >= REGISTRY_TOTAL_CAP) {
+            throw new Error(`Room 注册表总量已达上限(${REGISTRY_TOTAL_CAP}),请先合并/退役部分条目`);
+        }
+        if (!isMinor) {
+            const majors = new Set(this.entries.map((e) => majorOf(e.slug)));
+            if (!majors.has(slug) && majors.size >= REGISTRY_MAJOR_CAP) {
+                throw new Error(`大类已达上限(${REGISTRY_MAJOR_CAP}):请用「大类/小类」细分(如 ${slug}/子项),或合并/退役部分大类`);
+            }
+        }
+        const now = new Date().toISOString();
+        const entry = {
+            slug,
+            label: typeof input.label === 'string' && input.label.trim() ? input.label.trim().slice(0, 60) : undefined,
+            description: typeof input.description === 'string' && input.description.trim()
+                ? input.description.trim().slice(0, 300)
+                : undefined,
+            source: input.source === 'grown' ? 'grown' : 'pre-registered',
+            aliases: Array.isArray(input.aliases) && input.aliases.length > 0 ? input.aliases.slice(0, ALIASES_CAP) : undefined,
+            status: 'active',
+            createdAt: now,
+            updatedAt: now,
+        };
+        this.entries.push(entry);
+        this.rev++;
+        await this.persist();
+        return { entry: { ...entry }, created: true };
+    }
+    /** 编辑已有条目的 label/description(注册后可重编辑;未提供的字段不动;未找到=false)。 */
+    async update(slug, patch) {
+        this.ensureLoaded();
+        const found = this.entries.find((e) => e.slug === slug);
+        if (!found)
+            return false;
+        let changed = false;
+        if (typeof patch.label === 'string' && patch.label.trim()) {
+            found.label = patch.label.trim().slice(0, 60);
+            changed = true;
+        }
+        if (typeof patch.description === 'string' && patch.description.trim()) {
+            found.description = patch.description.trim().slice(0, 300);
+            changed = true;
+        }
+        if (!changed)
+            return false;
+        found.updatedAt = new Date().toISOString();
+        this.rev++;
+        await this.persist();
+        return true;
+    }
+    /** 改状态(active↔retired);无变化返回 false。 */
+    async setStatus(slug, status) {
+        this.ensureLoaded();
+        const found = this.entries.find((e) => e.slug === slug);
+        if (!found || found.status === status)
+            return false;
+        found.status = status;
+        found.updatedAt = new Date().toISOString();
+        this.rev++;
+        await this.persist();
+        return true;
+    }
+    /** 改名(merge 1:1 收尾):slug 换名 + 旧 slug 进 aliases。新名与既有条目冲突时走 merge。
+     *  目标用两级制词表(isRoomSlug)——把 standalone room 归类到 hall 下(改名 major/minor)
+     *  走的就是这条路;isTag 会误拒带 slash 的目标。 */
+    async renameSlug(oldSlug, newSlug) {
+        this.ensureLoaded();
+        if (!isRoomSlug(newSlug))
+            throw new Error(`非法 Room slug: ${newSlug}(两级制:major 或 major/minor)`);
+        const found = this.entries.find((e) => e.slug === oldSlug);
+        if (!found)
+            return false;
+        if (this.entries.some((e) => e.slug === newSlug)) {
+            throw new Error(`目标 slug 已存在: ${newSlug}(应走 merge 而非 rename)`);
+        }
+        found.slug = newSlug;
+        found.aliases = [...new Set([...(found.aliases ?? []), oldSlug])].slice(0, ALIASES_CAP);
+        found.updatedAt = new Date().toISOString();
+        this.rev++;
+        await this.persist();
+        return true;
+    }
+    /** 合并收尾:fromSlug 条目转 retired + toSlug 进 aliases(记录重写由调用方游标执行)。 */
+    async markMerged(fromSlug, toSlug) {
+        this.ensureLoaded();
+        const found = this.entries.find((e) => e.slug === fromSlug);
+        if (!found)
+            return false;
+        found.status = 'retired';
+        const target = this.entries.find((e) => e.slug === toSlug);
+        if (target) {
+            target.aliases = [...new Set([...(target.aliases ?? []), fromSlug])].slice(0, ALIASES_CAP);
+            target.updatedAt = new Date().toISOString();
+        }
+        found.updatedAt = new Date().toISOString();
+        this.rev++;
+        await this.persist();
+        return true;
+    }
+    /** 写穿持久化(串行链;失败降级内存态并告警一次)。 */
+    async persist() {
+        if (this.degraded)
+            return;
+        this.writeChain = this.writeChain.then(async () => {
+            const data = {
+                version: ROOMS_REGISTRY_FILE_VERSION,
+                rev: this.rev + 1,
+                rooms: this.entries,
+            };
+            try {
+                await ensureDir(path.dirname(this.file));
+                await atomicWriteText(this.file, JSON.stringify(data, null, 2));
+                this.rev = data.rev;
+            }
+            catch (err) {
+                this.degraded = err instanceof Error ? err.message : String(err);
+                if (!this.degradedLogged) {
+                    this.degradedLogged = true;
+                    this.logger?.warn(`[memory] Room 注册表写入失败,只读降级: ${this.degraded}`);
+                }
+            }
+        });
+        await this.writeChain;
+    }
+}

package/dist/store/sqlite.d.ts

@@ -384,6 +384,8 @@ export declare class MemoryDb {
         halls?: readonly string[];
         /** Room 过滤(metadata.tags 含该 slug)。 */
         tag?: string;
+        /** 孤儿记忆筛选(true = 只列没有 Room 的记录;与 tag 互斥,tag 优先)。 */
+        untagged?: boolean;
         workspaceId?: string;
         /**
          * 退场(软删)筛查:三态。
@@ -429,6 +431,8 @@ export declare class MemoryDb {
         room: string;
         count: number;
     }>;
+    /** 孤儿记忆计数:没有任何 Room(tags 为空/缺失)的记录条数(含已退场,与 l1RoomCounts 同口径)。 */
+    untaggedL1Count(): number;
     /** Hall 域计数(八边形角数据源):按 metadata.hall 分组计数 + 未打标行数。失败返回空。 */
     wingL1Counts(): {
         counts: Record<string, number>;
@@ -460,6 +464,18 @@ export declare class MemoryDb {
     countL0Since(iso: string): number;
     /** 统计某会话已捕获消息数(session-stats 数据源;idx_l0_session_id 索引点查)。 */
     countL0BySession(sessionId: string): number;
+    /**
+     * §A 崩溃恢复水位线(memorax-absorb):该会话 L0 已落盘的最大 turn。
+     * L0 为追加式事实源、从不裁剪 → 水位线崩溃安全;turn 空洞是常态
+     * (off 档/无消息轮),MAX 语义不受影响。空会话返回 undefined。
+     */
+    maxCapturedTurn(sessionId: string): number | undefined;
+    /**
+     * §A 幂等检查:该 (session, turn) 是否已有任意 L0 行。
+     * 水位线 MAX(turn) 只判"整轮无"、判不了"部分有"——恢复窗口内逐 turn
+     * 做存在性检查,命中即整轮跳过(重放 record id 非确定,upsert 不能去重)。
+     */
+    hasAnyL0Message(sessionId: string, turn: number): boolean;
     /** 按会话取最近消息(时间升序返回;走 idx_l0_session_id 索引)。
      *  蒸馏背景参考专用——按会话现查替代全局内存数组(ADR-0003)。 */
     recentL0BySession(sessionId: string, limit: number): L0MessageRecord[];

package/dist/store/sqlite.js

@@ -1486,6 +1486,11 @@ export class MemoryDb {
                 where.push(`EXISTS (SELECT 1 FROM json_each(CASE WHEN json_valid(metadata_json) THEN metadata_json ELSE '{}' END, '$.tags') j WHERE j.value = ?)`);
                 params.push(opts.tag);
             }
+            else if (opts.untagged) {
+                // 孤儿记忆:没有任何 Room(tags 数组缺失/为空/字段非法)。与 room 计数同一
+                // json_valid 守卫口径;与 l1RoomCounts() 计数互补(rooms 计数 + 孤儿数 = 全量)。
+                where.push(`NOT EXISTS (SELECT 1 FROM json_each(CASE WHEN json_valid(metadata_json) THEN metadata_json ELSE '{}' END, '$.tags'))`);
+            }
             // 退场筛查(三态,见 opts.retired 注释):与 listRetiredL1 同一判据,保证
             // 「仅退场」视图与「已退场」区看到同一批行。
             if (opts.retired === false) {
@@ -1601,6 +1606,21 @@ export class MemoryDb {
             return [];
         }
     }
+    /** 孤儿记忆计数:没有任何 Room(tags 为空/缺失)的记录条数(含已退场,与 l1RoomCounts 同口径)。 */
+    untaggedL1Count() {
+        if (this.degraded)
+            return 0;
+        try {
+            const row = this.db
+                .prepare(`SELECT COUNT(*) AS n FROM l1_records r
+           WHERE NOT EXISTS (SELECT 1 FROM json_each(CASE WHEN json_valid(r.metadata_json) THEN r.metadata_json ELSE '{}' END, '$.tags'))`)
+                .get();
+            return Number(row?.n ?? 0);
+        }
+        catch {
+            return 0;
+        }
+    }
     /** Hall 域计数(八边形角数据源):按 metadata.hall 分组计数 + 未打标行数。失败返回空。 */
     wingL1Counts() {
         if (this.degraded)
@@ -1797,6 +1817,43 @@ export class MemoryDb {
             return 0;
         }
     }
+    /**
+     * §A 崩溃恢复水位线(memorax-absorb):该会话 L0 已落盘的最大 turn。
+     * L0 为追加式事实源、从不裁剪 → 水位线崩溃安全;turn 空洞是常态
+     * (off 档/无消息轮),MAX 语义不受影响。空会话返回 undefined。
+     */
+    maxCapturedTurn(sessionId) {
+        if (this.degraded)
+            return undefined;
+        try {
+            const row = this.db
+                .prepare('SELECT MAX(turn) AS max_turn FROM l0_conversations WHERE session_id = ?')
+                .get(sessionId);
+            return typeof row?.max_turn === 'number' ? row.max_turn : undefined;
+        }
+        catch (err) {
+            this.logger?.warn(`[memory] L0 水位线查询失败(按空处理): ${err instanceof Error ? err.message : String(err)}`);
+            return undefined;
+        }
+    }
+    /**
+     * §A 幂等检查:该 (session, turn) 是否已有任意 L0 行。
+     * 水位线 MAX(turn) 只判"整轮无"、判不了"部分有"——恢复窗口内逐 turn
+     * 做存在性检查,命中即整轮跳过(重放 record id 非确定,upsert 不能去重)。
+     */
+    hasAnyL0Message(sessionId, turn) {
+        if (this.degraded || !Number.isFinite(turn))
+            return false;
+        try {
+            const row = this.db
+                .prepare('SELECT 1 FROM l0_conversations WHERE session_id = ? AND turn = ? LIMIT 1')
+                .get(sessionId, turn);
+            return row !== undefined;
+        }
+        catch {
+            return false;
+        }
+    }
     /** 按会话取最近消息(时间升序返回;走 idx_l0_session_id 索引)。
      *  蒸馏背景参考专用——按会话现查替代全局内存数组(ADR-0003)。 */
     recentL0BySession(sessionId, limit) {

package/dist/store/trace.d.ts

@@ -0,0 +1,39 @@
+import type { TraceEvent } from '../contract.js';
+export interface TraceStoreOptions {
+    /** 保留天数;0 = 永久保留。 */
+    retentionDays: number;
+    /** 单文件字节上限(超过停写 + marker)。 */
+    maxFileBytes?: number;
+}
+export declare class TraceStore {
+    private readonly dataDir;
+    private readonly opts;
+    /** 已停写的日期(5MB 上限触发;当日内后续事件丢弃,次日自动恢复)。 */
+    private readonly truncatedDays;
+    private lastPruneDay;
+    private chain;
+    constructor(dataDir: string, opts: TraceStoreOptions);
+    /** 追加事件(异步串行链,失败静默)。 */
+    append(event: TraceEvent): void;
+    /** 等待挂起的写入排空(dispose 序用)。 */
+    flush(): Promise<void>;
+    /**
+     * 尾部读取:从最近的日期文件倒序收集,按 kind 过滤,返回至多 `lines` 条
+     * (按写入顺序 = 时间升序)。坏行跳过(readJsonl 同款)。
+     */
+    tail(lines: number, kind?: TraceEvent['kind']): Promise<TraceEvent[]>;
+    private dir;
+    private fileFor;
+    private recentFiles;
+    private writeOne;
+    /** 删除超过保留期的旧日文件(retentionDays 0 = 永久)。 */
+    private pruneOldDays;
+}
+/** 插件启动时注入(index.ts 调用);enabled=false 或 0 天保留不影响初始化本身。 */
+export declare function initTraceStore(dataDir: string, opts: TraceStoreOptions): void;
+/** 测试/卸载:清空单例。 */
+export declare function resetTraceStore(): void;
+/** 埋点入口:未初始化 = no-op。fire-and-forget,永不抛。 */
+export declare function trace(event: TraceEvent): void;
+/** RPC tail 数据源;未初始化返回 undefined(端点回空集)。 */
+export declare function getTraceStore(): TraceStore | null;