dsh-sessions-manager 3.6.2 → 3.7.1

package/src/move-notices.js

@@ -0,0 +1,129 @@
+// move-notices.js — 排队移动「后台终局」的持久通知（3.7.0 T2）。
+//
+// 背景（UX 黑洞）：排队移动发起时有诚实的「已排队」提示，但**后台完成/最终放弃**
+// 原先只 console.warn——用户合上页面就永远不知道结果。本模块把每次终局落成一条
+// 独立通知，经 sidebar-state 带出、client 弹出、ack 后清除。
+//
+// 为什么是独立文件而不是 pending-moves.json 加字段：排队的两个终局（成功 remove、
+// 放弃 bumpAttempts→dropped）都会把条目从 items 里删掉——挂在条目上的字段与载体
+// 同生共死，恰恰在两个目标场景里都观察不到。独立文件另外两点好处：pending-moves
+// 的 items 形状与 schemaVersion 保持 1 不动（旧 host 读新文件不可见，回滚零影响）；
+// 通知的生命周期（服务端保留到 ack + 7 天 TTL + 20 条截断）与队列互不干扰。
+//
+// 投递语义：**留在服务端直到 client ack**——pop 式投递会被「toast 没弹用户就关了
+// 页面」直接丢通知。同浏览器多 tab 的即时去重靠 client 的 localStorage 已见集合，
+// ack 只是尽力清理（ack 失败无害，TTL 兜底）。
+//
+// 写入沿用本仓库索引的既定纪律：schemaVersion + 串行 mutation + 原子写（tmp →
+// rename）+ 0600 + 防御式归一化（坏数据逐条丢弃，坏文件当空集合）。
+import { readFileSync } from 'node:fs'
+import { mkdir, rename, writeFile } from 'node:fs/promises'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
+const SCHEMA_VERSION = 1
+// env 在 create 时读取而非模块加载时冻结（测试动态导入的既定模式；生产单实例两可）。
+export const MAX_NOTICES = 20
+export const NOTICE_MAX_AGE_MS = 7 * 24 * 3600 * 1000
+const KINDS = new Set(['moved', 'abandoned'])
+
+function isSafeId(value) {
+  return typeof value === 'string' && value.length > 0 && value.length <= 200
+}
+function str(v, max) {
+  return typeof v === 'string' && v ? v.slice(0, max) : null
+}
+
+export function normalizeNotice(raw) {
+  if (!raw || typeof raw !== 'object') return null
+  if (!KINDS.has(raw.kind) || !isSafeId(raw.sessionId)) return null
+  const at = Number.isFinite(raw.at) && raw.at > 0 ? Math.floor(raw.at) : 0
+  if (!at) return null
+  const sessionId = String(raw.sessionId)
+  return {
+    id: str(raw.id, 400) || `${sessionId}:${raw.kind}:${at}`,
+    kind: raw.kind,
+    sessionId,
+    targetPath: str(raw.targetPath, 500),
+    attempts: Number.isSafeInteger(raw.attempts) && raw.attempts >= 0 ? raw.attempts : null,
+    reason: str(raw.reason, 300),
+    at,
+  }
+}
+
+function normalizeStore(raw) {
+  const source = raw && Array.isArray(raw.items) ? raw.items : []
+  const seen = new Set()
+  const items = []
+  for (const entry of source) {
+    const n = normalizeNotice(entry)
+    if (!n || seen.has(n.id)) continue
+    seen.add(n.id)
+    items.push(n)
+  }
+  items.sort((a, b) => a.at - b.at)
+  const trimmed = items.length > MAX_NOTICES ? items.slice(items.length - MAX_NOTICES) : items
+  return { schemaVersion: SCHEMA_VERSION, items: trimmed }
+}
+
+/**
+ * @param {object} [options]
+ * @param {string} [options.dir] 通知文件所在目录（测试注入临时目录）
+ */
+export function createMoveNoticeStore(options = {}) {
+  const dir = options.dir
+    || process.env.DSH_SESSIONS_MANAGER_PENDING_DIR
+    || process.env.DSH_SESSIONS_MANAGER_STAR_DIR
+    || join(homedir(), '.dsh', 'sessions-manager')
+  const indexPath = options.indexPath || join(dir, 'move-notices.json')
+  let mutation = Promise.resolve()
+
+  function read() {
+    try {
+      return normalizeStore(JSON.parse(readFileSync(indexPath, 'utf8')))
+    } catch (e) {
+      return normalizeStore(null)
+    }
+  }
+
+  async function write(store) {
+    await mkdir(dir, { recursive: true })
+    const tmp = join(dir, `.move-notices-${process.pid}-${Date.now()}.tmp`)
+    await writeFile(tmp, JSON.stringify(normalizeStore(store), null, 2), { encoding: 'utf8', mode: 0o600 })
+    await rename(tmp, indexPath)
+  }
+
+  function mutate(mutator) {
+    const operation = mutation.then(async () => {
+      const store = read()
+      const result = await mutator(store)
+      await write(store)
+      return result
+    })
+    mutation = operation.catch(() => {})
+    return operation
+  }
+
+  return {
+    indexPath,
+    // 终局落一条通知；同 id（会话+类型+时刻）幂等去重。
+    append: (notice) => mutate((store) => {
+      const n = normalizeNotice(notice)
+      if (!n) return null
+      if (store.items.some((x) => x.id === n.id)) return n
+      store.items.push(n)
+      return n
+    }),
+    // 只读列出未过期、未 ack 的通知（按时间升序）。过期项在下次写入时随归一化清掉。
+    async list() {
+      const now = Date.now()
+      return read().items.filter((n) => now - n.at <= NOTICE_MAX_AGE_MS)
+    },
+    ack: (ids) => mutate((store) => {
+      const drop = new Set((Array.isArray(ids) ? ids : []).filter((v) => typeof v === 'string' && v.length <= 400).map(String))
+      const before = store.items.length
+      store.items = store.items.filter((n) => !drop.has(n.id))
+      return before - store.items.length
+    }),
+  }
+}

package/src/saved-filters.js

@@ -0,0 +1,208 @@
+// Durable "saved filters" store (schema v1).
+//
+// Same discipline as src/star-index.js / src/tag-index.js: version field,
+// per-entry defensive normalize, atomic write (tmp + rename at 0o600) and a
+// single chained mutation queue. Filter payloads are OPAQUE JSON: the host
+// never interprets them (the UI round-trips its own chip state); we only
+// bound the serialized size so a corrupt entry can never bloat the state
+// file. Lives in the plugin state directory next to tags.json.
+import { mkdir, rename, writeFile } from 'node:fs/promises'
+import { readFileSync } from 'node:fs'
+import { randomBytes } from 'node:crypto'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
+// v1 is the first saved-filters schema. Unlike tags.json (which starts at v4
+// to dodge star's v3) this document lives in its own file and can begin
+// counting from 1.
+export const FILTER_SCHEMA_VERSION = 1
+
+// Caps: ≤20 saved filters, ≤40 code points per name (Array.from counting),
+// ≤2048 characters of serialized JSON per payload.
+export const MAX_FILTERS = 20
+export const MAX_FILTER_NAME = 40
+export const MAX_FILTER_JSON = 2048
+
+// Same state directory (and same env override) as the star / tag indexes.
+const DEFAULT_FILTER_DIR = join(homedir(), '.dsh', 'sessions-manager')
+
+const FILTER_ID_ALPHABET = 'abcdefghijklmnopqrstuvwxyz0123456789'
+
+function randomSuffix() {
+  const bytes = randomBytes(8)
+  let out = ''
+  for (const b of bytes) out += FILTER_ID_ALPHABET[b % FILTER_ID_ALPHABET.length]
+  return out
+}
+
+function isSafeFilterId(value) {
+  return typeof value === 'string' && value.length > 0 && value.length <= 64 && !/[\\/\0]/.test(value)
+}
+
+function filterError(message, status, code) {
+  const error = new Error(message)
+  error.status = status
+  if (code) error.code = code
+  throw error
+}
+
+function normalizeFilterName(value) {
+  if (typeof value !== 'string') return null
+  const name = value.trim()
+  if (!name || /[\\/\0]/.test(name)) return null
+  if (Array.from(name).length > MAX_FILTER_NAME) return null
+  return name
+}
+
+function nameKey(name) {
+  return name.toLocaleLowerCase()
+}
+
+// Serialize an opaque payload, or null when it cannot be stored (not JSON at
+// all — e.g. undefined/functions — or beyond the size cap).
+function normalizeFiltersPayload(value) {
+  let serialized
+  try {
+    serialized = JSON.stringify(value)
+  } catch {
+    return null
+  }
+  if (typeof serialized !== 'string' || serialized.length > MAX_FILTER_JSON) return null
+  try {
+    return JSON.parse(serialized)
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Coerce anything on disk (or nothing at all) into a valid v1 store.
+ * A dirty entry (bad id/name, unserializable or oversize payload, duplicate
+ * id / casefold-duplicate name) is dropped whole, never partially repaired.
+ */
+export function normalizeFilterStore(raw) {
+  const source = raw && typeof raw === 'object' && !Array.isArray(raw) ? raw : null
+  const items = []
+  const ids = new Set()
+  const names = new Set()
+  for (const item of (source && Array.isArray(source.items) ? source.items : [])) {
+    if (!item || typeof item !== 'object') continue
+    if (!isSafeFilterId(item.id) || ids.has(item.id)) continue
+    const name = normalizeFilterName(item.name)
+    if (name === null) continue
+    const key = nameKey(name)
+    if (names.has(key)) continue
+    const filters = normalizeFiltersPayload(item.filters)
+    if (filters === null) continue
+    ids.add(item.id)
+    names.add(key)
+    const createdAt = Number.isFinite(Number(item.createdAt)) ? Number(item.createdAt) : 0
+    items.push({ id: item.id, name, filters, createdAt })
+    if (items.length >= MAX_FILTERS) break
+  }
+  return { schemaVersion: FILTER_SCHEMA_VERSION, items }
+}
+
+/**
+ * Open the saved-filters store.
+ * @param {object} [options]
+ * @param {string} [options.dir] - Directory holding the store (tests inject a temp dir).
+ * @param {string} [options.indexPath] - Full store path, overriding `dir`.
+ */
+export function createSavedFilters(options = {}) {
+  const dir = options.dir || process.env.DSH_SESSIONS_MANAGER_STAR_DIR || DEFAULT_FILTER_DIR
+  const indexPath = options.indexPath || join(dir, 'saved-filters.json')
+  let mutation = Promise.resolve()
+
+  async function read() {
+    try {
+      return normalizeFilterStore(JSON.parse(readFileSync(indexPath, 'utf8')))
+    } catch {
+      return normalizeFilterStore(null)
+    }
+  }
+
+  async function write(store) {
+    await mkdir(dir, { recursive: true })
+    const tmp = join(dir, `.saved-filters-${process.pid}-${Date.now()}.tmp`)
+    await writeFile(tmp, JSON.stringify(normalizeFilterStore(store), null, 2), { encoding: 'utf8', mode: 0o600 })
+    await rename(tmp, indexPath)
+  }
+
+  // Serialize read-modify-write cycles (same chain semantics as the star index).
+  function mutate(mutator) {
+    const operation = mutation.then(async () => {
+      const store = await read()
+      const result = await mutator(store)
+      await write(store)
+      return result
+    })
+    mutation = operation.catch(() => {})
+    return operation
+  }
+
+  function newFilterId(store) {
+    for (let i = 0; i < 16; i++) {
+      const id = `f_${randomSuffix()}`
+      if (!store.items.some((t) => t.id === id)) return id
+    }
+    return filterError('无法生成筛选 id（随机碰撞异常）', 500, 'DSM_FILTER_ID_COLLISION')
+  }
+
+  /**
+   * Save a named filter. `filters` is stored verbatim (opaque to the host).
+   * @param {string} rawName
+   * @param {*} filters
+   * @returns {Promise<{id, name, filters, createdAt}>}
+   * @throws 400 DSM_FILTER_NAME_INVALID | 400 DSM_FILTER_INVALID
+   *         | 400 DSM_FILTER_TOO_LARGE | 409 DSM_FILTER_EXISTS | 409 DSM_FILTER_LIMIT
+   */
+  async function save(rawName, filters) {
+    const name = normalizeFilterName(rawName)
+    if (name === null) filterError(`筛选名无效（非空、不含斜杠、不超过 ${MAX_FILTER_NAME} 个字符）`, 400, 'DSM_FILTER_NAME_INVALID')
+    // Bound the opaque payload before it can ever reach disk, with honest
+    // codes for "not JSON at all" vs. "oversize".
+    let serialized
+    try {
+      serialized = JSON.stringify(filters)
+    } catch {
+      serialized = undefined
+    }
+    if (typeof serialized !== 'string') filterError('筛选条件必须是可 JSON 序列化的数据', 400, 'DSM_FILTER_INVALID')
+    if (serialized === 'null') filterError('筛选条件不能为 null', 400, 'DSM_FILTER_INVALID')
+    if (serialized.length > MAX_FILTER_JSON) filterError(`筛选条件过大（序列化后最多 ${MAX_FILTER_JSON} 字符）`, 400, 'DSM_FILTER_TOO_LARGE')
+    const payload = JSON.parse(serialized)
+    const key = nameKey(name)
+    return mutate((store) => {
+      if (store.items.some((t) => nameKey(t.name) === key)) filterError('同名筛选已存在', 409, 'DSM_FILTER_EXISTS')
+      if (store.items.length >= MAX_FILTERS) filterError(`保存的筛选已达上限（${MAX_FILTERS}）`, 409, 'DSM_FILTER_LIMIT')
+      const item = { id: newFilterId(store), name, filters: payload, createdAt: Date.now() }
+      store.items.push(item)
+      return item
+    })
+  }
+
+  /**
+   * Delete saved filters by id (unknown ids are ignored).
+   * @param {string[]} ids
+   * @returns {Promise<number>} how many items were actually removed.
+   */
+  function remove(ids) {
+    const wanted = new Set((Array.isArray(ids) ? ids : []).filter(isSafeFilterId).map(String))
+    return mutate((store) => {
+      const before = store.items.length
+      store.items = store.items.filter((t) => !wanted.has(t.id))
+      return before - store.items.length
+    })
+  }
+
+  /**
+   * @returns {Promise<Array<{id, name, filters, createdAt}>>}
+   */
+  async function list() {
+    const store = await read()
+    return store.items
+  }
+
+  return { read, write, mutate, list, save, remove, indexPath, dir }
+}

package/src/tag-index.js

@@ -0,0 +1,308 @@
+// Durable "session tags" index (schema v4).
+//
+// Deliberately mirrors the star index in src/star-index.js: version field,
+// per-entry defensive normalize (dirty data is dropped, never repaired by
+// guessing), atomic write (tmp + rename at 0o600) and a single chained
+// mutation queue so two concurrent requests can never clobber each other.
+// Tags are pure user metadata: create/rename/merge/remove rewrite THIS
+// document only and never touch a session (the 3.7.0 red line, plan §1.3).
+// Extracted from the host bundle so it can be unit-tested directly — pass
+// `dir` to point the index at a temp directory.
+import { mkdir, rename as fsRename, writeFile } from 'node:fs/promises'
+import { readFileSync } from 'node:fs'
+import { randomBytes } from 'node:crypto'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
+// v4 is the first tag schema; it starts at 4 so it can never be confused with
+// the recycle bin's v1/v2 or the star index's v3 documents even if a file is
+// copied between them.
+export const TAG_SCHEMA_VERSION = 4
+
+// Caps (plan §1.3): ≤200 tag definitions globally, ≤10 tags per session,
+// ≤24 code points per name. Array.from counting means one Chinese character
+// (or one surrogate pair) counts as exactly 1, so the limit is honest for CJK.
+export const MAX_TAGS = 200
+export const MAX_TAGS_PER_SESSION = 10
+export const MAX_TAG_NAME = 24
+
+// Same state directory (and same env override) as the star index: all
+// plugin-owned user marks live together in ~/.dsh/sessions-manager.
+const DEFAULT_TAG_DIR = join(homedir(), '.dsh', 'sessions-manager')
+
+// Random short ids: 't_' + 8 lowercase alphanumeric chars. Ids are minted
+// once and never reused (rename only rewrites the name), so assignments can
+// reference them safely. A collision (36^-8) is simply re-rolled.
+const TAG_ID_ALPHABET = 'abcdefghijklmnopqrstuvwxyz0123456789'
+
+function randomSuffix() {
+  const bytes = randomBytes(8)
+  let out = ''
+  for (const b of bytes) out += TAG_ID_ALPHABET[b % TAG_ID_ALPHABET.length]
+  return out
+}
+
+function isSafeSessionId(value) {
+  return typeof value === 'string' && value.length > 0 && value.length <= 200 && !/[\\/\0]/.test(value) && value !== '.' && value !== '..'
+}
+
+function isSafeTagId(value) {
+  return typeof value === 'string' && value.length > 0 && value.length <= 64 && !/[\\/\0]/.test(value)
+}
+
+function tagError(message, status, code) {
+  const error = new Error(message)
+  error.status = status
+  if (code) error.code = code
+  throw error
+}
+
+// Trim + shape-check a user-supplied tag name. Returns the cleaned name or
+// null; the caller turns null into a 400. Slashes and NUL are rejected in
+// line with this plugin's path-safety discipline for anything persisted.
+export function normalizeTagName(value) {
+  if (typeof value !== 'string') return null
+  const name = value.trim()
+  if (!name || /[\\/\0]/.test(name)) return null
+  if (Array.from(name).length > MAX_TAG_NAME) return null
+  return name
+}
+
+// Casefold key used for the global name-uniqueness rule.
+function nameKey(name) {
+  return name.toLocaleLowerCase()
+}
+
+/**
+ * Coerce anything on disk (or nothing at all) into a valid v4 store.
+ * Every entry is defended individually: a bad tag entry or a dangling
+ * assignment (a tagId no longer defined) is dropped silently.
+ */
+export function normalizeTagStore(raw) {
+  const source = raw && typeof raw === 'object' && !Array.isArray(raw) ? raw : null
+  const tags = []
+  const ids = new Set()
+  const names = new Set()
+  for (const item of (source && Array.isArray(source.tags) ? source.tags : [])) {
+    if (!item || typeof item !== 'object') continue
+    // Strings only: coercing a number into an id would let junk into the
+    // index and mask a caller bug (same reasoning as normalizeStarStore).
+    if (!isSafeTagId(item.id) || ids.has(item.id)) continue
+    const name = normalizeTagName(item.name)
+    if (name === null) continue
+    const key = nameKey(name)
+    if (names.has(key)) continue
+    ids.add(item.id)
+    names.add(key)
+    const createdAt = Number.isFinite(Number(item.createdAt)) ? Number(item.createdAt) : 0
+    tags.push({ id: item.id, name, createdAt })
+    if (tags.length >= MAX_TAGS) break
+  }
+  const assignments = {}
+  const rawAssignments = source && source.assignments && typeof source.assignments === 'object' && !Array.isArray(source.assignments)
+    ? source.assignments
+    : null
+  if (rawAssignments) {
+    for (const [sid, value] of Object.entries(rawAssignments)) {
+      if (!isSafeSessionId(sid) || !Array.isArray(value)) continue
+      const kept = []
+      const seen = new Set()
+      for (const tagId of value) {
+        // Unknown ids are dangling (tag deleted meanwhile, or a foreign file
+        // was copied in): drop, never keep a ghost the UI could not render.
+        if (!ids.has(tagId) || seen.has(tagId)) continue
+        seen.add(tagId)
+        kept.push(tagId)
+        if (kept.length >= MAX_TAGS_PER_SESSION) break
+      }
+      if (kept.length) assignments[sid] = kept
+    }
+  }
+  return { schemaVersion: TAG_SCHEMA_VERSION, tags, assignments }
+}
+
+/**
+ * Open the tag index.
+ * @param {object} [options]
+ * @param {string} [options.dir] - Directory holding the index (tests inject a temp dir).
+ * @param {string} [options.indexPath] - Full index path, overriding `dir`.
+ */
+export function createTagIndex(options = {}) {
+  const dir = options.dir || process.env.DSH_SESSIONS_MANAGER_STAR_DIR || DEFAULT_TAG_DIR
+  const indexPath = options.indexPath || join(dir, 'tags.json')
+  let mutation = Promise.resolve()
+
+  async function read() {
+    try {
+      return normalizeTagStore(JSON.parse(readFileSync(indexPath, 'utf8')))
+    } catch {
+      return normalizeTagStore(null)
+    }
+  }
+
+  async function write(store) {
+    await mkdir(dir, { recursive: true })
+    const tmp = join(dir, `.tags-${process.pid}-${Date.now()}.tmp`)
+    await writeFile(tmp, JSON.stringify(normalizeTagStore(store), null, 2), { encoding: 'utf8', mode: 0o600 })
+    await fsRename(tmp, indexPath)
+  }
+
+  // Serialize read-modify-write cycles: every mutator sees the store as left by
+  // the previous one, and a rejected mutator still keeps the chain alive (and
+  // writes nothing — the checks throw before `write` is reached).
+  function mutate(mutator) {
+    const operation = mutation.then(async () => {
+      const store = await read()
+      const result = await mutator(store)
+      await write(store)
+      return result
+    })
+    mutation = operation.catch(() => {})
+    return operation
+  }
+
+  function newTagId(store) {
+    for (let i = 0; i < 16; i++) {
+      const id = `t_${randomSuffix()}`
+      if (!store.tags.some((t) => t.id === id)) return id
+    }
+    // Astronomically unreachable; honest failure beats a duplicate id.
+    return tagError('无法生成标签 id（随机碰撞异常）', 500, 'DSM_TAG_ID_COLLISION')
+  }
+
+  /**
+   * Define a new tag.
+   * @param {string} rawName
+   * @returns {Promise<{id: string, name: string, createdAt: number}>}
+   * @throws 400 DSM_TAG_NAME_INVALID | 409 DSM_TAG_EXISTS | 409 DSM_TAG_LIMIT
+   */
+  async function create(rawName) {
+    const name = normalizeTagName(rawName)
+    if (name === null) tagError(`标签名无效（非空、不含斜杠、不超过 ${MAX_TAG_NAME} 个字符）`, 400, 'DSM_TAG_NAME_INVALID')
+    const key = nameKey(name)
+    return mutate((store) => {
+      if (store.tags.some((t) => nameKey(t.name) === key)) tagError('同名标签已存在', 409, 'DSM_TAG_EXISTS')
+      if (store.tags.length >= MAX_TAGS) tagError(`标签总数已达上限（${MAX_TAGS}）`, 409, 'DSM_TAG_LIMIT')
+      const tag = { id: newTagId(store), name, createdAt: Date.now() }
+      store.tags.push(tag)
+      return tag
+    })
+  }
+
+  /**
+   * Rename a tag. Ids never change, so assignments survive a rename untouched.
+   * A rename that only differs in case is legal (it's not a "duplicate" of
+   * another tag); a collision with a DIFFERENT tag is rejected.
+   * (Note: this method name is why the atomic rename above is `fsRename`.)
+   * @throws 400 | 404 DSM_TAG_NOT_FOUND | 409 DSM_TAG_EXISTS
+   */
+  async function rename(id, rawName) {
+    const name = normalizeTagName(rawName)
+    if (name === null) tagError(`标签名无效（非空、不含斜杠、不超过 ${MAX_TAG_NAME} 个字符）`, 400, 'DSM_TAG_NAME_INVALID')
+    const key = nameKey(name)
+    return mutate((store) => {
+      const tag = store.tags.find((t) => t.id === id)
+      if (!tag) tagError('标签不存在', 404, 'DSM_TAG_NOT_FOUND')
+      if (store.tags.some((t) => t.id !== tag.id && nameKey(t.name) === key)) tagError('同名标签已存在', 409, 'DSM_TAG_EXISTS')
+      tag.name = name
+      return tag
+    })
+  }
+
+  /**
+   * Fold the source tag into the target tag: every session carrying the
+   * source also carries the target (deduped; the per-session cap truncates an
+   * overflow rather than failing a half-applied merge — the UI must never be
+   * stuck with a source it cannot remove). The source definition and all of
+   * its assignments are then dropped. Sessions themselves are never touched.
+   * @throws 400 DSM_TAG_INVALID | 404 DSM_TAG_NOT_FOUND
+   */
+  async function merge(fromId, toId) {
+    if (!isSafeTagId(fromId) || !isSafeTagId(toId) || fromId === toId) {
+      tagError('合并的源/目标标签无效或相同', 400, 'DSM_TAG_INVALID')
+    }
+    return mutate((store) => {
+      if (!store.tags.some((t) => t.id === fromId) || !store.tags.some((t) => t.id === toId)) {
+        tagError('标签不存在', 404, 'DSM_TAG_NOT_FOUND')
+      }
+      for (const [sid, list] of Object.entries(store.assignments)) {
+        if (!list.includes(fromId)) continue
+        const merged = [...new Set(list.filter((x) => x !== fromId).concat(toId))]
+        store.assignments[sid] = merged.slice(0, MAX_TAGS_PER_SESSION)
+      }
+      store.tags = store.tags.filter((t) => t.id !== fromId)
+      return { merged: true }
+    })
+  }
+
+  /**
+   * Drop a tag definition and every assignment to it. Idempotent: an unknown
+   * id is a no-op success (the UI may race itself). NEVER touches a session.
+   */
+  function removeTag(id) {
+    return mutate((store) => {
+      if (isSafeTagId(id)) {
+        store.tags = store.tags.filter((t) => t.id !== id)
+        for (const [sid, list] of Object.entries(store.assignments)) {
+          const kept = list.filter((x) => x !== id)
+          if (kept.length) store.assignments[sid] = kept
+          else delete store.assignments[sid]
+        }
+      }
+      return { removed: true }
+    })
+  }
+
+  /**
+   * Replace the full tag set of one session (the UI always sends the complete
+   * list; "assign" and "unassign" are just set-with-one-more / set-minus-one).
+   * @param {string} sessionId
+   * @param {string[]} tagIds
+   * @returns {Promise<object>} the full assignments map after the change.
+   * @throws 400 DSM_TAG_SESSION_INVALID | 400 DSM_TAG_IDS_INVALID
+   *         | 400 DSM_TAG_UNKNOWN | 409 DSM_TAG_LIMIT
+   */
+  async function setTags(sessionId, tagIds) {
+    if (!isSafeSessionId(sessionId)) tagError('无效的 sessionId', 400, 'DSM_TAG_SESSION_INVALID')
+    if (!Array.isArray(tagIds)) tagError('tagIds 必须是数组', 400, 'DSM_TAG_IDS_INVALID')
+    const seen = new Set()
+    const wanted = []
+    for (const v of tagIds) {
+      // Strings only (same reasoning as the star index): a number in the list
+      // is a caller bug, not data to coerce.
+      if (!isSafeTagId(v)) tagError('无效的标签 id', 400, 'DSM_TAG_UNKNOWN')
+      if (seen.has(v)) continue
+      seen.add(v)
+      wanted.push(v)
+    }
+    if (wanted.length > MAX_TAGS_PER_SESSION) tagError(`单个会话最多 ${MAX_TAGS_PER_SESSION} 个标签`, 409, 'DSM_TAG_LIMIT')
+    return mutate((store) => {
+      const known = new Set(store.tags.map((t) => t.id))
+      const unknown = wanted.filter((id) => !known.has(id))
+      if (unknown.length) tagError(`未知的标签 id：${unknown.join('、')}`, 400, 'DSM_TAG_UNKNOWN')
+      if (wanted.length) store.assignments[sessionId] = [...wanted]
+      else delete store.assignments[sessionId]
+      return store.assignments
+    })
+  }
+
+  // Drop assignments once their session is gone (purged / deleted), otherwise
+  // the index would grow forever with ids that can never be listed again.
+  function removeIds(ids) {
+    const wanted = (Array.isArray(ids) ? ids : []).filter(isSafeSessionId)
+    return mutate((store) => {
+      for (const sid of wanted) delete store.assignments[sid]
+      return store.assignments
+    })
+  }
+
+  /**
+   * @returns {Promise<{tags: Array<{id,name,createdAt}>, assignments: object}>}
+   */
+  async function list() {
+    const store = await read()
+    return { tags: store.tags, assignments: store.assignments }
+  }
+
+  return { read, write, mutate, list, create, rename, merge, removeTag, setTags, removeIds, indexPath, dir }
+}