dsh-prime-memory 0.20.0-beta.2 → 0.20.0-beta.21

package/dist/store/l1.d.ts

@@ -61,6 +61,8 @@ export declare class L1Store {
     private readonly decayHalfLifeDays;
     /** §D 第 3 路(图谱回链);缺省 = 不接,恰为 2 路。 */
     private readonly graphLaneProvider?;
+    /** 孤儿记忆计数(没有任何 Room 的记录;rooms-get 面板「无绑定」chip 用)。 */
+    untaggedL1Count(): number;
     /** Room 计数缓存(见 `listRooms()`:tags 仅随反刍变化,不必每次敲库)。 */
     private roomCache;
     constructor(dataDir: string, db: MemoryDb, embed?: EmbeddingService, strategy?: RecallStrategy, logger?: MemoryLogger, 
@@ -68,6 +70,8 @@ export declare class L1Store {
     decayHalfLifeDays?: number, 
     /** 图谱路提供者(§D 第 3 路);不传则该路不存在,融合退回双路。 */
     graphLane?: GraphLaneProvider);
+    /** 读路径时效半衰期(天;0=关)。老化权重展示与召回衰减同一事实源。 */
+    get decayHalfLife(): number;
     init(): Promise<void>;
     /** 旧版单文件 records.jsonl 一次性导入检索库,成功后改名 .imported。 */
     private importLegacy;
@@ -108,6 +112,34 @@ export declare class L1Store {
         source: string;
     } | null;
     finishSceneRecluster(jobId: string, ok: boolean): void;
+    /**
+     * 收集某 Room 的全部匹配记录(含已退场行,口径与 Room 计数一致)。
+     * 内部分页拉取,上限 cap 防跑飞;返回记录数组供备份与干跑预览。
+     */
+    listByTagAll(tag: string, cap?: number): MemoryRecord[];
+    /**
+     * 备份某 Room 的匹配记录到 `<dataDir>/rooms-merge-backups/<ts>-<tag>.json`
+     * (执行前快照;破坏性重写前的唯一回滚物料)。返回备份文件路径与条数。
+     */
+    backupTagRecords(tag: string): {
+        file: string;
+        count: number;
+    };
+    /**
+     * 游标重写:把 metadata.tags 里的 `from` 全部替换为 `to`(**含已退场行**,
+     * 口径与 Room 计数一致)。写前重读-合并-写回(relabel 同款):只动 tags,
+     * roomCandidates/roomReview/hall/cogHall/sourceAnchors 等其余键原样保全。
+     *
+     * 单次上限 cap(500)可续跑:再次调用同一 from 即继续处理剩余行。
+     * 返回重写条数 + 受影响的 (family, scene) 集(供 recluster 'room-merge' 入队)。
+     */
+    rewriteTag(from: string, to: string, cap?: number): {
+        rewritten: number;
+        scanned: number;
+        families: string[];
+        scenes: string[];
+        hasMore: boolean;
+    };
     /** 按 id 精确取记录(去重决策的版本号查询用,避免全表扫描)。 */
     getByIds(ids: string[]): MemoryRecord[];
     /**
@@ -311,6 +343,8 @@ export declare class L1Store {
         halls?: readonly string[];
         /** Room 过滤(metadata.tags 含该 slug)。 */
         tag?: string;
+        /** 孤儿记忆筛选(true = 只列没有 Room 的记录;与 tag 互斥,tag 优先)。 */
+        untagged?: boolean;
         workspaceId?: string;
         /** 退场筛查:三态(`undefined` 全部 / `false` 仅活跃 / `true` 仅已退场)。 */
         retired?: boolean;

package/dist/store/l1.js

@@ -6,7 +6,7 @@
  *
  * 去重/合并的更新记录走 upsert(新 record id + 版本递增),不再全量重写文件。
  */
-import { existsSync, promises as fs } from 'node:fs';
+import { existsSync, mkdirSync, promises as fs, writeFileSync } from 'node:fs';
 import * as path from 'node:path';
 import { familyForType, isScopeVisible } from '../types.js';
 import { graphHitRecordIds } from '../graph/search.js';
@@ -34,6 +34,10 @@ export class L1Store {
     decayHalfLifeDays;
     /** §D 第 3 路(图谱回链);缺省 = 不接,恰为 2 路。 */
     graphLaneProvider;
+    /** 孤儿记忆计数(没有任何 Room 的记录;rooms-get 面板「无绑定」chip 用)。 */
+    untaggedL1Count() {
+        return this.db.untaggedL1Count();
+    }
     /** Room 计数缓存(见 `listRooms()`:tags 仅随反刍变化,不必每次敲库)。 */
     roomCache = null;
     constructor(dataDir, db, embed = new NoopEmbeddingService(), strategy = 'hybrid', logger, 
@@ -52,6 +56,10 @@ export class L1Store {
         this.decayHalfLifeDays = decayHalfLifeDays ?? 30;
         this.graphLaneProvider = graphLane;
     }
+    /** 读路径时效半衰期(天;0=关)。老化权重展示与召回衰减同一事实源。 */
+    get decayHalfLife() {
+        return this.decayHalfLifeDays;
+    }
     async init() {
         await ensureDir(this.recordsDir);
         await this.importLegacy();
@@ -158,6 +166,65 @@ export class L1Store {
     finishSceneRecluster(jobId, ok) {
         this.db.finishSceneRecluster(jobId, ok);
     }
+    // ── Room merge/rename 的游标重写(分类管理 beta.5;破坏性面)──────────────
+    /**
+     * 收集某 Room 的全部匹配记录(含已退场行,口径与 Room 计数一致)。
+     * 内部分页拉取,上限 cap 防跑飞;返回记录数组供备份与干跑预览。
+     */
+    listByTagAll(tag, cap = 500) {
+        const out = [];
+        for (let offset = 0; offset < cap; offset += 200) {
+            const page = this.list({ tag, retired: undefined, limit: Math.min(200, cap - out.length), offset });
+            out.push(...page.items);
+            if (page.items.length < 200 || out.length >= cap)
+                break;
+        }
+        return out;
+    }
+    /**
+     * 备份某 Room 的匹配记录到 `<dataDir>/rooms-merge-backups/<ts>-<tag>.json`
+     * (执行前快照;破坏性重写前的唯一回滚物料)。返回备份文件路径与条数。
+     */
+    backupTagRecords(tag) {
+        const records = this.listByTagAll(tag, 2000);
+        const backupDir = path.join(this.dataDir, 'rooms-merge-backups');
+        if (!existsSync(backupDir))
+            mkdirSync(backupDir, { recursive: true });
+        const file = path.join(backupDir, `${Date.now()}-${tag.replace(/[^a-z0-9-]/gi, '_')}.json`);
+        writeFileSync(file, JSON.stringify({ tag, exportedAt: new Date().toISOString(), records }, null, 2), 'utf8');
+        return { file, count: records.length };
+    }
+    /**
+     * 游标重写:把 metadata.tags 里的 `from` 全部替换为 `to`(**含已退场行**,
+     * 口径与 Room 计数一致)。写前重读-合并-写回(relabel 同款):只动 tags,
+     * roomCandidates/roomReview/hall/cogHall/sourceAnchors 等其余键原样保全。
+     *
+     * 单次上限 cap(500)可续跑:再次调用同一 from 即继续处理剩余行。
+     * 返回重写条数 + 受影响的 (family, scene) 集(供 recluster 'room-merge' 入队)。
+     */
+    rewriteTag(from, to, cap = 500) {
+        const rows = this.listByTagAll(from, cap + 1);
+        const hasMore = rows.length > cap;
+        const batch = rows.slice(0, cap);
+        let rewritten = 0;
+        const families = new Set();
+        const scenes = new Set();
+        for (const r of batch) {
+            const meta = { ...(r.metadata ?? {}) };
+            const tags = Array.isArray(meta.tags) ? meta.tags.map(String) : [];
+            if (!tags.includes(from))
+                continue; // 命中是 json_each 判等,数组缺失即无可改
+            const next = tags.map((t) => (t === from ? to : t));
+            meta.tags = [...new Set(next)];
+            if (this.patchMetadata(r.id, meta)) {
+                rewritten++;
+                families.add(r.family ?? 'chat');
+                if (r.scene_name)
+                    scenes.add(r.scene_name);
+            }
+        }
+        return { rewritten, scanned: batch.length, families: [...families], scenes: [...scenes], hasMore };
+    }
     /** 按 id 精确取记录(去重决策的版本号查询用,避免全表扫描)。 */
     getByIds(ids) {
         return this.db.getL1ByIds(ids);

package/dist/store/recall-usage.d.ts

@@ -0,0 +1,43 @@
+import type { MemoryLogger } from '../types.js';
+export declare const RECALL_USAGE_FILE_VERSION: 1;
+export interface RecallUsageEntry {
+    attempts: number;
+    used: number;
+    lastAttemptAt: number | null;
+    lastUsedAt: number | null;
+}
+export interface RecallUsageSummary {
+    /** 有统计的记忆条数。 */
+    tracked: number;
+    /** 尝试总次数(Σ attempts)。 */
+    attempted: number;
+    /** 使用总次数(Σ used)。 */
+    used: number;
+    /** 使用率(百分比整数;attempted=0 时 0)。 */
+    rate: number;
+}
+export declare class RecallUsageStore {
+    private readonly logger?;
+    private readonly file;
+    private entries;
+    private loaded;
+    private degraded;
+    private degradedLogged;
+    private writeTimer;
+    private writeChain;
+    constructor(dataDir: string, logger?: MemoryLogger | undefined);
+    init(): Promise<void>;
+    private ensureLoaded;
+    /** 一轮召回:候选集 attempts++/lastAttemptAt=now;used 子集额外 used++/lastUsedAt=now
+     *  (used 不在候选内 = 防御路径,同样算一次尝试——用了就是被尝试过)。 */
+    recordAttempt(candidateIds: readonly string[], usedIds: readonly string[]): void;
+    get(id: string): RecallUsageEntry | undefined;
+    summary(): RecallUsageSummary;
+    /** 立即落盘(去抖窗口内的兜底;测试/停机用)。 */
+    flush(): Promise<void>;
+    /** 同步等待在途写(测试用;无在途写时立即返回)。 */
+    flushSync(): void;
+    private prune;
+    private schedulePersist;
+    private persist;
+}

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;
+    }
+}