server-storage

name	server-storage
description	@stello-ai/server 的 PG 持久化层设计决策和实现模式。触发条件：修改或引用 server 存储层。

Server Storage Layer — PG 持久化

相关 skill：storage-design（接口定义）、server-design（传输层）

---

Schema 设计决策

7 张表：users, spaces, sessions, records, session_data, session_refs, core_data

• 不需要 topology_nodes 表 — TopologyNode 从 sessions 表派生（SELECT id, parent_id, label）
• children/refs 不存列 — WHERE parent_id= 派生 children，JOIN session_refs 派生 refs
• session_data 统一槽位 — 不同 key 存不同语义（system_prompt / insight / memory / scope / index），避免列爆炸
• records 表共享 — session 包和 core 包各自投影字段（Message 无 metadata，TurnRecord 有）
• CASCADE 删除 — sessions ON DELETE CASCADE 级联到 records、session_data、session_refs

---

3 个 Storage Adapter

Adapter	实现接口	职责
PgSessionStorage	SessionStorage（@stello-ai/session）	单个 Session 数据操作（含 root，所有 Session 同构）
PgSessionTree	SessionTree（@stello-ai/core）	拓扑：createSession / listRoots / 树操作 / 固化配置
PgMemoryEngine	MemoryEngine（@stello-ai/core）	核心数据读写、递归上下文组装

批量 digest 收集由 StelloAgent.listSessionDigests() 在应用层组合 SessionTree.listAll() + SessionStorage.getMemory/getInsight 完成，存储层不需要提供专用方法。

---

关键实现模式

spaceId 隔离

所有 adapter 构造时绑定 spaceId，所有 SQL 查询 WHERE space_id = $1。多租户隔离在查询层保证。

Slot 统一存储

session_data (session_id, key) 表，UPSERT 模式 ON CONFLICT (session_id, key) DO UPDATE。

两种 SessionMeta 投影

PG 存 sessions 表超集。不同 adapter 投影为不同类型：

• PgSessionStorage → @stello-ai/session 的 SessionMeta（id / label / status / createdAt / updatedAt）
• PgSessionTree → @stello-ai/core 的 SessionMeta（含 scope / turnCount / lastActiveAt）+ TopologyNode（纯树结构）

递归 CTE

getAncestors、getAllDescendantIds、assembleContext 都用 WITH RECURSIVE 遍历树结构。

事务支持

PgSessionStorage.transaction() 通过类型判断区分 Pool 与 PoolClient。Pool 时获取独占 client 开事务，PoolClient 时直接执行。