@whispering233/ai-editor-db 0.0.1

package/dist/queries/compute-state.js

@@ -0,0 +1,135 @@
+// @whispering233/ai-editor-db 状态计算（S5.2 computeState）：沿大纲树父链累积 Delta 得到实体到达状态
+//
+// 单一事实来源：
+// - doc/api/endpoints.md 第 464-510 行（POST /delta/compute：Req/Res、累积规则四段——
+//   双层排序、set/update/add/remove 语义、update from 不匹配跳过 + conflicts、软删过滤）
+// - 决策 9（只沿大纲树父链累积已确认 Delta、双层排序、op=update 校验当前值等于 from、
+//   不匹配跳过 + skipped/conflicts 标注不返回 409、plot_edge 不参与、推演不落库）
+// - doc/database/schema.md 第 107 行注记（状态计算规则摘要）
+//
+// 复用边界（不重复实现）：
+// - listDeltasByNode（delta.ts）：按节点查询 + 可见性三态过滤（决策 12 修订：delta 自身 /
+//   触发节点 / 目标实体任一软删即不可见）+ 节点内按 order 升序——computeState 的软删过滤
+//   与「节点内 order 序」由此获得
+// - getOutlinePathIds（storage/outline.ts）：根 → at_node 树路径（严格三层下路径唯一）；
+//   节点不存在时抛错——视为调用方 bug 不捕获
+// - getEntity（entity.ts）：目标实体行（data 已解析为对象）；不存在/已软删返回 null
+//
+// plot_edge 不参与（决策 9）：本实现只读 delta_records，relation_records 的剧情连线
+// 天然不进入累积，无需额外过滤。
+import { listDeltasByNode } from "./delta.js";
+import { getEntity } from "./entity.js";
+import { getOutlinePathIds, readOutlineFile } from "../storage/outline.js";
+/**
+ * 应用单条 change 到 state（endpoints.md 第 500-510 行四段规则 + 决策 9 修订）：
+ * - `set`：state[field] = to（直接替换）
+ * - `update`：state[field] === from → state[field] = to；否则**跳过该 change**——
+ *   在 skipped 追加 { index, field, expected: from, actual } 且 conflicts 追加
+ *   { deltaId, field, expected: from, actual }（继续累积后续 change/delta，不抛 409——
+ *   手动编辑 data 不产生 Delta 属正常用户行为）
+ * - `add`：state[field] 为数组 → 按 value 追加；非数组**静默跳过**（防御，不标 conflicts——
+ *   契约仅定义 update 冲突）
+ * - `remove`：state[field] 为数组 → 按值匹配移除**首个**匹配；值不存在静默忽略；
+ *   非数组静默跳过
+ * 字段约定（endpoints.md 第 407-413 行）：add/remove 用 value，set/update 用 to。
+ * 防御：非对象 change 静默忽略（changes 列来自 JSON 解析，坏项不打挂整条计算）。
+ */
+function applyChange(state, change, index, deltaId, skipped, conflicts) {
+    if (change === null || typeof change !== "object")
+        return;
+    const { field, op } = change;
+    switch (op) {
+        case "set": // set：直接替换（to）
+            state[field] = change.to;
+            break;
+        case "update": // update：旧值 → 新值，校验当前值 === from
+            if (state[field] === change.from) {
+                state[field] = change.to;
+            }
+            else {
+                const actual = state[field];
+                skipped.push({ index, field, expected: change.from, actual });
+                conflicts.push({ deltaId, field, expected: change.from, actual });
+            }
+            break;
+        case "add": // add：按 value 向数组追加（非数组静默跳过）
+            if (Array.isArray(state[field])) {
+                state[field].push(change.value);
+            }
+            break;
+        case "remove": // remove：按值匹配移除首个（值不存在静默忽略；非数组静默跳过）
+            if (Array.isArray(state[field])) {
+                const arr = state[field];
+                const idx = arr.findIndex((v) => v === change.value);
+                if (idx !== -1)
+                    arr.splice(idx, 1);
+            }
+            break;
+    }
+}
+/**
+ * 计算实体到达指定大纲节点时的累积状态（POST /api/v1/delta/compute，endpoints.md 第 464-510 行）。
+ *
+ * **前置约定**：
+ * - atNodeId 必须存在——路由层先校验节点存在性并映射 404 OUTLINE_NODE_NOT_FOUND 后调用；
+ *   getOutlinePathIds 对缺失节点抛错，视为调用方 bug，本模块不捕获。
+ * - 目标实体不存在（或已软删，getEntity 过滤）→ 返回 **null**，路由层映射 404 ENTITY_NOT_FOUND。
+ *
+ * 累积流程（决策 9 + schema.md 第 107 行）：
+ * 1. state 基座 = 实体初始 data 深拷贝（structuredClone，不污染 getEntity 返回行）
+ * 2. 树路径 = getOutlinePathIds(tree, atNodeId)（根 → at_node，含 root 哨兵——无 delta 挂它，
+ *    无害）；路径上每节点调 listDeltasByNode（内置可见性三态过滤与 order ASC），
+ *    过滤 target_id === targetId——天然满足「节点间树路径序 + 节点内 order 序」双层排序
+ *    与软删过滤
+ * 3. 逐 change 应用（applyChange，决策 9 修订四段语义）；update 冲突跳过不打断后续累积
+ * 4. 响应：appliedDeltas 每项 { nodeId, description, changes（原样数组）, skipped?（仅该 delta
+ *    有跳过时出现）}；conflicts 为跨全部 delta 的扁平数组
+ *
+ * target_type 不参与过滤（仅回显）：id 前缀体系（char-/set-/loc-/hook-/sc-/ch-/vol- 等）保证
+ * target_id 全局唯一，targetId 即足以定位目标；endpoints.md Req 携带 target_type 用于响应回显。
+ *
+ * @param outlineDir 项目根目录（outline.json 读取：树路径 + 节点软删校验）
+ * @returns ComputeStateResult；目标实体不存在/已软删返回 null
+ */
+export function computeState(db, outlineDir, input) {
+    // 1. 目标实体：不存在或已软删 → null（决策 12 过滤；路由层映射 404 ENTITY_NOT_FOUND）
+    const entity = getEntity(db, input.targetId);
+    if (entity === null)
+        return null;
+    // 2. 树路径（根 → at_node；缺失节点抛错——路由层前置校验后的调用方 bug，不捕获）
+    const tree = readOutlineFile(outlineDir);
+    const path = getOutlinePathIds(tree, input.atNodeId);
+    // 3. state 基座：初始 data 深拷贝（每次计算独立，不污染实体行）
+    const state = structuredClone(entity.data);
+    const appliedDeltas = [];
+    const conflicts = [];
+    // 4. 双层排序累积：节点间按路径序（根 → at_node），节点内按 order ASC（listDeltasByNode）
+    for (const nodeId of path) {
+        for (const delta of listDeltasByNode(db, nodeId, outlineDir)) {
+            if (delta.targetId !== input.targetId)
+                continue; // 只取目标实体的 Delta
+            const skipped = [];
+            const changes = delta.changes;
+            for (let i = 0; i < changes.length; i++) {
+                applyChange(state, changes[i], i, delta.id, skipped, conflicts);
+            }
+            const applied = {
+                nodeId: delta.nodeId,
+                description: delta.description,
+                changes, // 原样 changes 数组（本模块不修改，可安全共享引用）
+            };
+            if (skipped.length > 0)
+                applied.skipped = skipped; // 仅该 delta 有跳过时出现
+            appliedDeltas.push(applied);
+        }
+    }
+    return {
+        targetType: input.targetType,
+        targetId: input.targetId,
+        atNodeId: input.atNodeId,
+        state,
+        appliedDeltas,
+        conflicts,
+    };
+}
+//# sourceMappingURL=compute-state.js.map

package/dist/queries/compute-state.js.map

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

package/dist/queries/delta.d.ts

@@ -0,0 +1,76 @@
+import type { DeltaChange, DeltaRecord, DeltaRow } from "@whispering233/ai-editor-shared";
+import { type Db } from "../connection.js";
+/** 追加入参（endpoints.md 第 402-419 行；无 order 字段——服务端生成） */
+export interface InsertDeltaInput {
+    /** 触发变更的大纲节点 ID */
+    nodeId: string;
+    targetType: string;
+    targetId: string;
+    changes: DeltaChange[];
+    /** 人类可读描述 */
+    description: string;
+}
+/**
+ * 追加属性变更记录（POST /api/v1/delta，endpoints.md 第 397-434 行）：
+ * - **order 服务端生成、全局单调递增**：SELECT COALESCE(MAX("order"), 0) + 1，包单库事务
+ *   （better-sqlite3 同步单连接下读-写无竞态，事务保证跨语句原子与回滚语义）
+ * - **前置约定：本层不校验触发节点/目标存在性**——endpoints.md POST /delta 未定义
+ *   该错误码；指向不存在节点的记录会因可见性规则（决策 12 修订：触发节点缺失视同
+ *   不可见、目标缺失仅省略 name）永久不可见。存在性校验由 S5.3 路由层负责。
+ * - id = shared generateId("delta-")（与关系 generateId("rel-") 同构；mapping.test.ts
+ *   的 "delta-1" 形状一致；前缀 + nanoid 全局唯一）
+ * - created_at = updated_at = nowIso()（应用层写时间约定，schema.md 第 16 行）
+ * @returns 完整行（DeltaRow，changes 已解析为数组）
+ */
+export declare function insertDelta(db: Db, input: InsertDeltaInput): DeltaRow;
+/**
+ * 按 id 取单条 Delta（S7.5 提案快照重校验，决策 14）：
+ * 记录级查询——自身软删（deleted_at 非空）视为不存在返回 null；
+ * 触发节点/目标端点的可见性联动（决策 12 修订）不在此判定：
+ * 提案引用的对象是 delta_records 记录本身，「存在性 + 自身 updated_at」即决策 14 语义
+ * （与 getRelation 的端点联动过滤不同——关系引用同样只比对关系自身，见 proposal/relation.ts
+ * buildProposeRemoveRelation 只采集 refRelation）。
+ * @returns 完整行（DeltaRow，changes 已解析）；不存在或已软删返回 null
+ */
+export declare function getDeltaRow(db: Db, id: string): DeltaRow | null;
+/**
+ * 按触发节点查询 Delta（GET /api/v1/delta/node/:nodeId，endpoints.md 第 436-462 行）：
+ * - SQL：node_id = ? AND deleted_at IS NULL，按 "order" 递增（computeState 同节点内应用序）
+ * - **可见性三态过滤（决策 12 修订，AND）**：见 filterVisibleDeltas（本函数行同属一个
+ *   触发节点，仍逐行判定——与 listDeltasByTarget 共用同一实现，语义幂等）
+ * @param outlineDir 项目根（触发节点与大纲 target 的软删/标题校验读 outline.json）
+ */
+export declare function listDeltasByNode(db: Db, nodeId: string, outlineDir: string): DeltaRecord[];
+/**
+ * 按目标端点查询 Delta（S6.3 工具 get_delta_history 下沉，tools.md「状态查询」）：
+ * - SQL：target_id = ? AND deleted_at IS NULL，按 "order" 递增（order 全局单调 =
+ *   创建顺序，即「按时间/节点排序」）
+ * - 可见性过滤与 listDeltasByNode **完全一致**（filterVisibleDeltas 共享：delta 自身 /
+ *   触发节点 / 目标端点三态软删判定 + targetName 联表，决策 12 修订）
+ * @param outlineDir 项目根（触发节点与大纲 target 的软删/标题校验读 outline.json）
+ */
+export declare function listDeltasByTarget(db: Db, targetId: string, outlineDir: string): DeltaRecord[];
+/** 悬空 Delta 的不可见原因（决策 12 修订三态的后两态 + 脏引用兜底） */
+export type DanglingDeltaReason = "trigger_missing" | "trigger_deleted" | "target_missing" | "target_deleted";
+/** 悬空 Delta 记录摘要（delta 自身未软删但已不可见——「幽灵变更」） */
+export interface DanglingDeltaInfo {
+    id: string;
+    nodeId: string;
+    targetType: string;
+    targetId: string;
+    description: string;
+    reason: DanglingDeltaReason;
+}
+/**
+ * 全量悬空 Delta 诊断（S6.4 工具 find_orphan_elements 下沉，tools.md「孤立元素」）：
+ * delta 自身未软删，但三态可见性（决策 12 修订）后两态命中——该记录永不生效：
+ * - trigger_missing：触发节点已物理删除（purge 后脏引用）
+ * - trigger_deleted：触发节点已软删但本 delta 未级联软删（跨存储不一致的 delta 侧，
+ *   与 outline-ops 级联软删/启动一致性校验（决策 16 修订）兜底的对象同源）
+ * - target_missing：目标端点已物理删除（实体 purge / 大纲节点 purge）
+ * - target_deleted：目标端点已软删但本 delta 未级联软删
+ * 软删自身的 delta（回收站对象）**不在此列**——由回收站管理，非悬空。
+ * @param outlineDir 项目根（触发节点与大纲 target 的存在性/软删校验读 outline.json）
+ */
+export declare function listDanglingDeltas(db: Db, outlineDir: string): DanglingDeltaInfo[];
+//# sourceMappingURL=delta.d.ts.map

package/dist/queries/delta.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"delta.d.ts","sourceRoot":"","sources":["../../src/queries/delta.ts"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,QAAQ,EAAmB,MAAM,iCAAiC,CAAC;AAG3G,OAAO,EAAmB,KAAK,EAAE,EAAE,MAAM,kBAAkB,CAAC;AAoC5D,uDAAuD;AACvD,MAAM,WAAW,gBAAgB;IAC/B,mBAAmB;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,WAAW,EAAE,CAAC;IACvB,aAAa;IACb,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,EAAE,EAAE,EAAE,EAAE,KAAK,EAAE,gBAAgB,GAAG,QAAQ,CAiCrE;AAkED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI,CAM/D;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,WAAW,EAAE,CAa1F;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,WAAW,EAAE,CAQ9F;AAID,8CAA8C;AAC9C,MAAM,MAAM,mBAAmB,GAAG,iBAAiB,GAAG,iBAAiB,GAAG,gBAAgB,GAAG,gBAAgB,CAAC;AAE9G,8CAA8C;AAC9C,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,mBAAmB,CAAC;CAC7B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,EAAE,EAAE,UAAU,EAAE,MAAM,GAAG,iBAAiB,EAAE,CAiElF"}

package/dist/queries/delta.js

@@ -0,0 +1,287 @@
+// @whispering233/ai-editor-db Delta 增查（S5.1）：增量插入 + 按节点查询（联表 target_name + 可见性联动）
+//
+// 单一事实来源：
+// - doc/api/endpoints.md 第 395-462 行（POST /delta 追加 + GET /delta/node/:nodeId；
+//   DeltaRecord 含 targetName 联表字段；**无 order 入参**——服务端全局单调生成；
+//   op 语义 2026-08 修订：set/update/add/remove）
+// - doc/database/schema.md 第 89-105 行（delta_records 表：changes JSON、order 全局单调、
+//   created_at/updated_at/deleted_at ISO 应用层写入）
+// - 决策 12 修订（可见性联动触发节点与目标实体：任一软删即不可见）、
+//   决策 9 修订（computeState 只沿大纲树父链累积已确认 Delta——同一节点内按 order 应用）
+//
+// 边界：级联软删/还原/补标已有实现——entity.ts softDeleteEntity（target_id 级联）、
+// server outline.ts cascadeSoftDelete（node_id 级联）、trash.ts restore/purge 级联、
+// S4.2 一致性补标；本卡只做增量插入与可见性查询，不重复。
+//
+// 可见性过滤实现（决策 12 修订，三态 AND）：
+// - SQL 层：delta 自身 deleted_at IS NULL
+// - JS 层（参照 relation.ts buildEndpointContext 模式）：
+//   触发节点（node_id）未软删——outline.json 检查；
+//   目标端点未软删——实体 target 查 entities 软删集合（一次 IN 查询），
+//   大纲节点 target 走 outline.json
+// - name 联表同路径：实体 → entities.name、大纲节点 → outline.json title
+import { generateId, mapRowToDelta } from "@whispering233/ai-editor-shared";
+import { nowIso } from "../storage/atomic.js";
+import { withTransaction } from "../connection.js";
+import { findOutlineNode, readOutlineFile } from "../storage/outline.js";
+/** 实体端点类型集合（entities 表 type 列；其余 target_type 按大纲节点处理，relation.ts 同款约定） */
+const ENTITY_TARGET_TYPES = ["character", "setting", "location", "hook"];
+/** 行 → DeltaRow（changes JSON 解析；坏行防御同 entity.ts parseDataColumn 风格） */
+function rowToDeltaRow(row) {
+    return {
+        id: row.id,
+        node_id: row.node_id,
+        target_type: row.target_type,
+        target_id: row.target_id,
+        changes: parseChanges(row.changes),
+        description: row.description,
+        order: row.order,
+        created_at: row.created_at,
+        updated_at: row.updated_at,
+        deleted_at: row.deleted_at ?? null,
+    };
+}
+/**
+ * changes 列解析防御：非法 JSON / 非数组 → []（单条坏行不打挂整表查询；
+ * 与 entity.ts parseDataColumn / chat.ts parseToolCalls 防御风格一致）
+ */
+function parseChanges(value) {
+    if (typeof value !== "string")
+        return [];
+    try {
+        const parsed = JSON.parse(value);
+        return Array.isArray(parsed) ? parsed : [];
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * 追加属性变更记录（POST /api/v1/delta，endpoints.md 第 397-434 行）：
+ * - **order 服务端生成、全局单调递增**：SELECT COALESCE(MAX("order"), 0) + 1，包单库事务
+ *   （better-sqlite3 同步单连接下读-写无竞态，事务保证跨语句原子与回滚语义）
+ * - **前置约定：本层不校验触发节点/目标存在性**——endpoints.md POST /delta 未定义
+ *   该错误码；指向不存在节点的记录会因可见性规则（决策 12 修订：触发节点缺失视同
+ *   不可见、目标缺失仅省略 name）永久不可见。存在性校验由 S5.3 路由层负责。
+ * - id = shared generateId("delta-")（与关系 generateId("rel-") 同构；mapping.test.ts
+ *   的 "delta-1" 形状一致；前缀 + nanoid 全局唯一）
+ * - created_at = updated_at = nowIso()（应用层写时间约定，schema.md 第 16 行）
+ * @returns 完整行（DeltaRow，changes 已解析为数组）
+ */
+export function insertDelta(db, input) {
+    return withTransaction(db, () => {
+        const now = nowIso();
+        const order = db.prepare('SELECT COALESCE(MAX("order"), 0) + 1 AS next FROM delta_records').get().next;
+        const row = {
+            id: generateId("delta-"),
+            node_id: input.nodeId,
+            target_type: input.targetType,
+            target_id: input.targetId,
+            changes: input.changes,
+            description: input.description,
+            order,
+            created_at: now,
+            updated_at: now,
+            deleted_at: null,
+        };
+        db.prepare('INSERT INTO delta_records (id, node_id, target_type, target_id, changes, description, "order", created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)').run(row.id, row.node_id, row.target_type, row.target_id, JSON.stringify(row.changes), row.description, row.order, row.created_at, row.updated_at);
+        return row;
+    });
+}
+/**
+ * 行数组 → 可见性三态过滤 + targetName 联表（决策 12 修订，AND）：
+ * 1. delta 自身未软删（SQL 层 WHERE deleted_at IS NULL 保证，调用方负责）
+ * 2. 触发节点未软删（outline.json：节点 deleted !== true；节点不存在视同不可见——
+ *    purge 已物理清除其 Delta，脏引用兜底为空）——**逐行判定**（listDeltasByTarget
+ *    的行可来自不同触发节点，listDeltasByNode 复用同一逻辑，语义幂等）
+ * 3. 目标端点未软删：实体 target 查 entities 软删集合（一次 IN 查询）；大纲 target 查树
+ *    （target 不存在 → 不过滤但省略 name——与 relation.ts 端点缺失语义一致）
+ * - targetName 联表（参照 relation.ts buildEndpointContext）：实体 → entities.name
+ *   （一次 IN 查询）；大纲节点 → outline.json title；解析失败/缺失 → 省略字段
+ *
+ * 供 listDeltasByNode / listDeltasByTarget 共用（S6.3 工具下沉：按目标查询复用同一语义）。
+ * @param tree 已读取的 outline.json 树（调用方读取一次，避免重复 I/O）
+ */
+function filterVisibleDeltas(db, rows, tree) {
+    // 目标实体端点：一次 IN 查询收集软删集合与名称映射（含软删实体——名称填充不受
+    // 可见性影响，过滤在另一层；relation.ts 同款取舍）。重复 target_id 用 Set 去重
+    // （同一节点多条 Delta 指向同一实体时常见），避免 IN 参数重复
+    const entityIds = [
+        ...new Set(rows
+            .filter((r) => ENTITY_TARGET_TYPES.includes(r.target_type))
+            .map((r) => r.target_id)),
+    ];
+    const entitySoftDeleted = new Set();
+    const entityNames = new Map();
+    if (entityIds.length > 0) {
+        const placeholders = entityIds.map(() => "?").join(",");
+        const softRows = db
+            .prepare(`SELECT id FROM entities WHERE deleted_at IS NOT NULL AND id IN (${placeholders})`)
+            .all(...entityIds);
+        for (const r of softRows)
+            entitySoftDeleted.add(r.id);
+        const nameRows = db
+            .prepare(`SELECT id, name FROM entities WHERE id IN (${placeholders})`)
+            .all(...entityIds);
+        for (const r of nameRows)
+            entityNames.set(r.id, r.name);
+    }
+    const records = [];
+    for (const raw of rows) {
+        const row = rowToDeltaRow(raw);
+        // 触发节点软删检查（决策 12 修订：触发节点软删 → 该 Delta 不可见）
+        const trigger = findOutlineNode(tree, row.node_id);
+        if (trigger === undefined || trigger.deleted === true)
+            continue;
+        // 目标端点软删检查（决策 12 修订）
+        let targetSoftDeleted;
+        let targetName;
+        if (ENTITY_TARGET_TYPES.includes(row.target_type)) {
+            targetSoftDeleted = entitySoftDeleted.has(row.target_id);
+            targetName = entityNames.get(row.target_id);
+        }
+        else {
+            const node = findOutlineNode(tree, row.target_id);
+            targetSoftDeleted = node !== undefined && node.deleted === true;
+            if (node !== undefined)
+                targetName = node.title;
+        }
+        if (targetSoftDeleted)
+            continue;
+        const record = mapRowToDelta(row); // shared 映射（camelCase；targetName 可选字段另行填充）
+        if (targetName !== undefined)
+            record.targetName = targetName;
+        records.push(record);
+    }
+    return records;
+}
+/**
+ * 按 id 取单条 Delta（S7.5 提案快照重校验，决策 14）：
+ * 记录级查询——自身软删（deleted_at 非空）视为不存在返回 null；
+ * 触发节点/目标端点的可见性联动（决策 12 修订）不在此判定：
+ * 提案引用的对象是 delta_records 记录本身，「存在性 + 自身 updated_at」即决策 14 语义
+ * （与 getRelation 的端点联动过滤不同——关系引用同样只比对关系自身，见 proposal/relation.ts
+ * buildProposeRemoveRelation 只采集 refRelation）。
+ * @returns 完整行（DeltaRow，changes 已解析）；不存在或已软删返回 null
+ */
+export function getDeltaRow(db, id) {
+    const row = db.prepare("SELECT * FROM delta_records WHERE id = ? AND deleted_at IS NULL").get(id);
+    if (row === undefined)
+        return null;
+    return rowToDeltaRow(row);
+}
+/**
+ * 按触发节点查询 Delta（GET /api/v1/delta/node/:nodeId，endpoints.md 第 436-462 行）：
+ * - SQL：node_id = ? AND deleted_at IS NULL，按 "order" 递增（computeState 同节点内应用序）
+ * - **可见性三态过滤（决策 12 修订，AND）**：见 filterVisibleDeltas（本函数行同属一个
+ *   触发节点，仍逐行判定——与 listDeltasByTarget 共用同一实现，语义幂等）
+ * @param outlineDir 项目根（触发节点与大纲 target 的软删/标题校验读 outline.json）
+ */
+export function listDeltasByNode(db, nodeId, outlineDir) {
+    const rows = db
+        .prepare('SELECT * FROM delta_records WHERE node_id = ? AND deleted_at IS NULL ORDER BY "order" ASC')
+        .all(nodeId);
+    if (rows.length === 0)
+        return [];
+    const tree = readOutlineFile(outlineDir);
+    // 触发节点软删检查（决策 12 修订：触发节点软删 → 其全部 Delta 不可见；
+    // 提前短路避免无谓的实体软删集合 IN 查询）
+    const trigger = findOutlineNode(tree, nodeId);
+    if (trigger === undefined || trigger.deleted === true)
+        return [];
+    return filterVisibleDeltas(db, rows, tree);
+}
+/**
+ * 按目标端点查询 Delta（S6.3 工具 get_delta_history 下沉，tools.md「状态查询」）：
+ * - SQL：target_id = ? AND deleted_at IS NULL，按 "order" 递增（order 全局单调 =
+ *   创建顺序，即「按时间/节点排序」）
+ * - 可见性过滤与 listDeltasByNode **完全一致**（filterVisibleDeltas 共享：delta 自身 /
+ *   触发节点 / 目标端点三态软删判定 + targetName 联表，决策 12 修订）
+ * @param outlineDir 项目根（触发节点与大纲 target 的软删/标题校验读 outline.json）
+ */
+export function listDeltasByTarget(db, targetId, outlineDir) {
+    const rows = db
+        .prepare('SELECT * FROM delta_records WHERE target_id = ? AND deleted_at IS NULL ORDER BY "order" ASC')
+        .all(targetId);
+    if (rows.length === 0)
+        return [];
+    const tree = readOutlineFile(outlineDir);
+    return filterVisibleDeltas(db, rows, tree);
+}
+/**
+ * 全量悬空 Delta 诊断（S6.4 工具 find_orphan_elements 下沉，tools.md「孤立元素」）：
+ * delta 自身未软删，但三态可见性（决策 12 修订）后两态命中——该记录永不生效：
+ * - trigger_missing：触发节点已物理删除（purge 后脏引用）
+ * - trigger_deleted：触发节点已软删但本 delta 未级联软删（跨存储不一致的 delta 侧，
+ *   与 outline-ops 级联软删/启动一致性校验（决策 16 修订）兜底的对象同源）
+ * - target_missing：目标端点已物理删除（实体 purge / 大纲节点 purge）
+ * - target_deleted：目标端点已软删但本 delta 未级联软删
+ * 软删自身的 delta（回收站对象）**不在此列**——由回收站管理，非悬空。
+ * @param outlineDir 项目根（触发节点与大纲 target 的存在性/软删校验读 outline.json）
+ */
+export function listDanglingDeltas(db, outlineDir) {
+    const rows = db
+        .prepare('SELECT * FROM delta_records WHERE deleted_at IS NULL ORDER BY "order" ASC')
+        .all();
+    if (rows.length === 0)
+        return [];
+    const tree = readOutlineFile(outlineDir);
+    // 实体目标端点状态：一次 IN 批量收集（避免逐行查询——relation.ts buildEndpointContext 同款先例）
+    const entityIds = [
+        ...new Set(rows
+            .filter((r) => ENTITY_TARGET_TYPES.includes(r.target_type))
+            .map((r) => r.target_id)),
+    ];
+    const entityStates = new Map();
+    if (entityIds.length > 0) {
+        const placeholders = entityIds.map(() => "?").join(",");
+        const found = db
+            .prepare(`SELECT id, deleted_at FROM entities WHERE id IN (${placeholders})`)
+            .all(...entityIds);
+        const foundIds = new Set(found.map((f) => f.id));
+        for (const id of entityIds) {
+            if (!foundIds.has(id)) {
+                entityStates.set(id, "missing");
+            }
+            else {
+                const f = found.find((x) => x.id === id);
+                entityStates.set(id, f.deleted_at !== null ? "deleted" : "ok");
+            }
+        }
+    }
+    const out = [];
+    for (const raw of rows) {
+        const row = rowToDeltaRow(raw);
+        // 触发节点：缺失 → 脏引用；软删 → 未级联
+        const trigger = findOutlineNode(tree, row.node_id);
+        if (trigger === undefined) {
+            out.push({ id: row.id, nodeId: row.node_id, targetType: row.target_type, targetId: row.target_id, description: row.description, reason: "trigger_missing" });
+            continue;
+        }
+        if (trigger.deleted === true) {
+            out.push({ id: row.id, nodeId: row.node_id, targetType: row.target_type, targetId: row.target_id, description: row.description, reason: "trigger_deleted" });
+            continue;
+        }
+        // 目标端点：实体查批量 Map / 大纲节点查树
+        let targetState;
+        if (ENTITY_TARGET_TYPES.includes(row.target_type)) {
+            targetState = entityStates.get(row.target_id) ?? "missing";
+        }
+        else {
+            const node = findOutlineNode(tree, row.target_id);
+            targetState = node === undefined ? "missing" : node.deleted === true ? "deleted" : "ok";
+        }
+        if (targetState !== "ok") {
+            out.push({
+                id: row.id,
+                nodeId: row.node_id,
+                targetType: row.target_type,
+                targetId: row.target_id,
+                description: row.description,
+                reason: targetState === "missing" ? "target_missing" : "target_deleted",
+            });
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=delta.js.map

package/dist/queries/delta.js.map

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

package/dist/queries/entity.d.ts

@@ -0,0 +1,110 @@
+import type { EntityRow, EntitySummary, EntityType } from "@whispering233/ai-editor-shared";
+import { type Db } from "../connection.js";
+/** 列表查询参数（endpoints.md 第 162-169 行；缺省值语义与路由层对齐） */
+export interface EntityListQuery {
+    type?: EntityType;
+    /** 搜索关键词（模糊匹配 name；LIKE 通配符 %/_ 原样透传——模糊搜索语义，注释明示） */
+    q?: string;
+    /**
+     * data 字段过滤（S6.3 工具 search_entities 下沉，tools.md「实体查询」filters）：
+     * status 精确匹配 data.status；tags 要求 data.tags 数组包含全部指定 tags（AND）。
+     * 列表摘要不含 data（toSummary 只提取关键字段），故本过滤走「全行查询 + JS 层判定」。
+     */
+    filters?: {
+        tags?: string[];
+        status?: string;
+    };
+    /** 分页偏移，默认 0 */
+    offset?: number;
+    /** 每页条数，默认 50，最大 200（超限 clamp，防恶意大页） */
+    limit?: number;
+    sort?: "name" | "created_at" | "updated_at";
+    order?: "asc" | "desc";
+}
+/** 列表结果（endpoints.md 第 171-177 行；items 为 API 形态 EntitySummary，与 chat.ts 同款风格） */
+export interface EntityListResult {
+    items: EntitySummary[];
+    total: number;
+}
+/** 行 → EntityRow（data 从 JSON 字符串解析为对象；坏行防御见 rowToEntityRow 注释） */
+export declare function rowToEntityRow(row: Record<string, unknown>): EntityRow;
+/**
+ * 实体列表（GET /api/v1/entity/:type，endpoints.md 第 154-193 行）：
+ * type 过滤 + q 模糊搜索（name LIKE）+ 排序（name/created_at/updated_at × asc/desc，
+ * 白名单防注入）+ 分页（limit clamp 1-200）+ **默认过滤软删**（决策 12）。
+ * total 为过滤后总数（不含分页）。
+ * filters 语义（S6.3 下沉）：data 字段 JS 过滤（列表摘要不含 data），此时 SQL 只做
+ * type/q/软删过滤，filters + 分页在 JS 层（MVP 数据量小，全行查询可接受）；
+ * 无 filters 时保持 COUNT + LIMIT SQL 原路径（行为不变）。
+ */
+export declare function listEntities(db: Db, query: EntityListQuery): EntityListResult;
+/** 按 id 取实体详情（GET /api/v1/entity/:type/:id）；不存在或已软删返回 null（决策 12 过滤） */
+export declare function getEntity(db: Db, id: string): EntityRow | null;
+/** 实体的 Delta 计数（详情响应 deltaCount；决策 12 修订：目标实体软删的 Delta 不可见） */
+export declare function countDeltasForEntity(db: Db, id: string): number;
+/**
+ * 创建实体（POST /api/v1/entity/:type，endpoints.md 第 221-253 行）：
+ * id = shared generateEntityId（char-/set-/loc-/hook- 前缀）、created_at/updated_at 应用层 ISO、
+ * data 缺省 {}、type 必须 ∈ ENTITY_TYPES（非法抛错——路由层 schema 校验后一般不可达，防御）。
+ * @returns 新行（EntityRow，data 已解析）
+ */
+export declare function createEntity(db: Db, input: {
+    type: EntityType;
+    name: string;
+    data?: Record<string, unknown>;
+}): EntityRow;
+/**
+ * 部分更新实体（PUT /api/v1/entity/:type/:id，endpoints.md 第 255-278 行）：
+ * 仅合并传入字段——name 直接替换；data **浅合并**（未传字段保留，endpoints.md 第 267 行）；
+ * updated_at 刷新（决策 14 提案快照比对）。软删实体不可更新（getEntity 过滤 → null，路由层 404）。
+ * 读后写包 withTransaction（oracle 审核建议 2）：better-sqlite3 同步单连接下无竞态（安全），
+ * 包事务统一风格（与 softDeleteEntity 一致）；返回行在事务内直接构造，无额外复杂度。
+ * @returns 更新后的行；实体不存在或已软删返回 null
+ */
+export declare function updateEntity(db: Db, id: string, patch: {
+    name?: string;
+    data?: Record<string, unknown>;
+}): EntityRow | null;
+/**
+ * 软删实体（DELETE /api/v1/entity/:type/:id，决策 12）：
+ * **级联软删关联关系与 Delta**（单库内事务保证原子性）：
+ * - relation_records：source_id = id **或** target_id = id（任一端点软删即不可见，决策 12 修订）
+ * - delta_records：target_id = id（目标实体软删即不可见，决策 12 修订）
+ * - 自身：deleted_at 置位 + updated_at 刷新（决策 12 修订：软删亦更新版本戳）
+ * 幂等：实体已软删（或不存在）→ 返回 null 且无任何副作用（级联 UPDATE 均带 deleted_at IS NULL 过滤）。
+ *
+ * @returns { relations, deltas } 实际级联行数；实体不存在/已软删返回 null
+ */
+export declare function softDeleteEntity(db: Db, id: string, deletedAt: string): {
+    relations: number;
+    deltas: number;
+} | null;
+/** 实体聚合统计结果：总数 + 类型专属分布（稀疏字段，仅出现对应类型的分布） */
+export interface EntitySummaryStats {
+    type: EntityType;
+    /** 非软删实体总数（决策 12 修订：回收站对象不计入） */
+    total: number;
+    /** character：data.role 分布 */
+    byRole?: Record<string, number>;
+    /** character / hook：data.status 分布 */
+    byStatus?: Record<string, number>;
+    /** setting：data.category 分布 */
+    byCategory?: Record<string, number>;
+    /** location：data.type 分布 */
+    byType?: Record<string, number>;
+    /** hook：data.payoff_timing 分布 */
+    byPayoffTiming?: Record<string, number>;
+    /** character：data.abilities 频率（取前 10，防 token 爆炸，决策 15） */
+    topAbilities?: {
+        ability: string;
+        count: number;
+    }[];
+}
+/**
+ * 实体聚合统计（S6.3 工具 get_entity_summary 下沉，tools.md「聚合分析」）：
+ * 指定类型实体的总数 + 类型专属分布。仅统计非软删实体（决策 12 修订）；
+ * 分布字段按类型稀疏出现：character→byRole/byStatus/topAbilities、setting→byCategory、
+ * location→byType、hook→byStatus/byPayoffTiming；缺字段（data 未填）不报错、不计入。
+ */
+export declare function getEntitySummaryStats(db: Db, type: EntityType): EntitySummaryStats;
+//# sourceMappingURL=entity.d.ts.map

package/dist/queries/entity.d.ts.map

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