dsh-expert-group 0.1.1

package/host/settings-runtime.js

@@ -0,0 +1,168 @@
+/**
+ * Host 关注点模块：settings 运行时状态（DSH 0.1.7-alpha.2 契约）。
+ *
+ * 持有三件事，全部服务于 **DEG 自有提交端点**（index.js 的 commitSettingsCandidate）：
+ * - 模型目录 generation 计数与 settings document revision 去重（两参数事件规则）；
+ * - 全局 settings 提交串行链（不等待可能永久 pending 的 domain 写入）；
+ * - 写入前的最后一道代次复核：提交起始代次与当前代次不一致时拒绝写入。
+ *
+ * 保证边界（规格书已记录的降级）：
+ * DEG **不承诺**在宿主通用 settings 写入路径上也保证模型目录有效。宿主没有 validate
+ * 钩子，配置编辑是同步的，DEG 的锁无法协调由通用写入发起的 provider 配置改动；因此
+ * 目录有效性只覆盖「DEG 自有提交端点在自己的写入前可检测到的变化」。
+ *
+ * 运行数据仍属于 storage domain；本模块只处理 settings 提交边界。
+ *
+ * @module dsh-expert-group/host/settings-runtime
+ */
+
+/** 写入前发现模型目录代次变化；RPC 层按 code 映射为可重试的保存失败。 */
+export class SettingsDirectoryChangedError extends Error {
+  constructor(message = "模型目录在保存期间发生变化，请刷新目录后重试") {
+    super(message);
+    this.name = "SettingsDirectoryChangedError";
+    this.code = "MODEL_DIRECTORY_CHANGED";
+  }
+}
+
+/**
+ * 把一层提交 patch 转成宿主的路径寻址写入操作。
+ *
+ * 每个顶层字段一律用「整值 set」表达，**绝不**用宿主 `update` 的递归合并：
+ * DEG 的 defaults / promptOverrides 是整份映射语义（空对象必须清空全部覆盖、
+ * 提交的 defaults 必须整体替换而不是与旧值做键级并集）。宿主的
+ * `mutate` + `{op:'set', path:[key]}` 在路径末段整体赋值，等价于旧契约里
+ * `update` 在顶层键上的行为；同时宿主会校验该路径确实是 volatile 字段。
+ *
+ * patch 值必须是 JSON 可表达的数据；`undefined` 条目由调用方负责过滤，不会出现在这里。
+ *
+ * @param {Record<string, unknown>} patch - 已归一的提交 patch。
+ * @returns {Array<{op:"set", path:string[], value:unknown}>} 有序写入操作。
+ */
+function settingsWriteOps(patch) {
+  return Object.entries(patch ?? {}).map(([key, value]) => ({ op: "set", path: [key], value }));
+}
+
+/**
+ * @param {object} options
+ * @param {object} options.settings - 注入的 ctx.settings（需要 mutate）。
+ * @param {string} options.namespace - 插件 settings namespace（= profile 条目 id）。
+ */
+export function createSettingsRuntimeModule({ settings, namespace } = {}) {
+  if (settings === null || typeof settings !== "object" || typeof settings.mutate !== "function") {
+    throw new TypeError("createSettingsRuntimeModule 需要 settings 服务（含 mutate）");
+  }
+  if (typeof namespace !== "string" || namespace.length === 0) {
+    throw new TypeError("createSettingsRuntimeModule 需要 namespace");
+  }
+  let generation = 0;
+  let writeChain = Promise.resolve();
+  let pendingWrites = 0;
+  let disposed = false;
+  const documentRevisions = new Map();
+
+  return Object.freeze({
+    get generation() { return generation; },
+    /** 目录/凭据变化推进代际，使进行中的提交过期。 */
+    bumpGeneration() {
+      generation += 1;
+      return generation;
+    },
+    isCurrentGeneration(value) {
+      return value === generation;
+    },
+    /**
+     * settings document 事件：按 namespace + revision 去重。
+     *
+     * DSH 0.1.7-alpha.2 只发送 `(ns, revision)` 两个参数（注册世代事件与
+     * registration token 都已从宿主删除），因此去重基线只有 revision：
+     * - 缺失/非法 revision：清除基线并保守失效（无法安全去重）；
+     * - 同 namespace 同 revision：忽略（同一份文档，没有新变化）；
+     * - 更高 revision：记录新基线并推进代际；
+     * - 更低 revision：只可能来自被替换的 settings 服务（新实例从 0 计数），
+     *   因此清除基线并保守失效，绝不把“新世代的低 revision”当成旧文档忽略。
+     * 去重基线在失效后会被清空，下一次同 revision 事件会重新失效——宁可多推进一次
+     * 代际，也不能因为 revision 回绕而错过一次目录变化。
+     * @returns {"ignored"|"invalidated"}
+     */
+    noteDocumentUpdate(namespaceName, revision) {
+      if (typeof namespaceName !== "string" || namespaceName.length === 0 || namespaceName === namespace) return "ignored";
+      if (!Number.isSafeInteger(revision) || revision < 0) {
+        documentRevisions.delete(namespaceName);
+        generation += 1;
+        return "invalidated";
+      }
+      const previous = documentRevisions.get(namespaceName);
+      if (previous !== undefined && revision === previous.revision) return "ignored";
+      documentRevisions.set(namespaceName, { revision });
+      generation += 1;
+      return "invalidated";
+    },
+    /**
+     * 全局 settings 提交串行链：失败不阻断后续提交，且不等待任何 domain 写入。
+     *
+     * 串行化是 revision 冲突语义的前提：并发提交按调用顺序排队，后一条看到前一条
+     * 落盘后的 revision，因此携带陈旧 expectedRevision 的提交会被宿主明确拒绝，而
+     * 不是互相覆盖。
+     * @param {Function} operation
+     */
+    enqueueCommit(operation) {
+      if (typeof operation !== "function") throw new TypeError("enqueueCommit 需要函数");
+      if (disposed) {
+        const error = new Error("settings runtime 已关闭");
+        error.code = "SETTINGS_RUNTIME_DISPOSED";
+        return Promise.reject(error);
+      }
+      pendingWrites += 1;
+      const run = writeChain.catch(() => {}).then(operation);
+      writeChain = run.catch(() => {});
+      let settled = false;
+      const settle = () => {
+        if (settled) return;
+        settled = true;
+        pendingWrites = Math.max(0, pendingWrites - 1);
+      };
+      run.then(settle, settle);
+      return run;
+    },
+    /**
+     * 在目录代次栅栏内写入 settings（DEG 自有提交端点的实际写入边界）。
+     *
+     * 调用方（commitSettingsCandidate）在串行链内先做语义校验与目录解析，再调本方法；
+     * 本方法在真正调用宿主写入**之前**复核代次：`generationAtStart` 与当前代次不一致
+     * 说明校验期间模型目录已变化，提交必须过期（抛 SettingsDirectoryChangedError）。
+     *
+     * 这是「提交前可检测的变化」这一降级保证的落点：它只覆盖 DEG 自己这条路径，
+     * 且只覆盖到宿主写入调用之前；不承诺拦截宿主通用写入路径，也不承诺封住宿主
+     * 异步落盘期间的竞态。
+     *
+     * 写入原语是 `mutate` + 顶层 `set`，而不是 `update`（理由见 settingsWriteOps）。
+     */
+    async updateAtGeneration(patch, expectedRevision, generationAtStart) {
+      if (disposed) {
+        const error = new Error("settings runtime 已关闭");
+        error.code = "SETTINGS_RUNTIME_DISPOSED";
+        throw error;
+      }
+      // 写入前的最后一道代次栅栏：校验完成到写入之间目录变化则不写。
+      if (generationAtStart !== generation) throw new SettingsDirectoryChangedError();
+      return settings.mutate(namespace, settingsWriteOps(patch), expectedRevision);
+    },
+    describe: () => ({
+      generation,
+      trackedNamespaces: documentRevisions.size,
+      pendingWrites,
+    }),
+    /**
+     * 幂等清理：监听器由 ctx 生命周期释放，本模块清空内部状态。
+     * 已登记的提交继续沿原串行链 drain；不重置 writeChain 或 pendingWrites，
+     * 由各自的幂等 settle 在迟到完成后准确收敛计数。
+     */
+    dispose() {
+      if (disposed) return;
+      disposed = true;
+      generation = 0;
+      documentRevisions.clear();
+    },
+  });
+}

package/host/settings-source.js

@@ -0,0 +1,265 @@
+/**
+ * Host 关注点模块：settings 源绑定（DSH 0.1.7-alpha.2 契约）。
+ *
+ * 接线方式：
+ * - 引导期通过 `ctx.settings.configure({ auto: false }, ctx.fiber)` 关闭宿主的自动
+ *   生成配置页（DEG 有自己的设置页）。owner 必须是**插件自己的 fiber**：宿主按
+ *   fiber 记录页面策略，省略 owner 会把策略记到 settings 服务自身并立刻因重复注册
+ *   抛错。返回的 disposer 挂到插件 effect 上，随生命周期释放。
+ * - 本条目当前值从 **describe()** 读取（找 ns === 本条目 id 的项取 value），不再使用
+ *   已删除的 `settings.register` / `scope.get()` / `scope.watch()`。
+ * - 运行期变更观察有三个观察点，全部收敛到同一个 `observeConfiguration()` 入口：
+ *   1. `loader/volatile-update`（**主**）：loader 把 volatile-only 变更提交进运行中的
+ *      fiber 之后派发；这是设置页保存与外部编辑生效最及时的信号。
+ *   2. `app-boot/config-reload`（**兜底**）：profile patch 归并完成、生命周期 settle
+ *      后无条件派发，覆盖只走重载路径的写入（程序化更新、HMR 关闭时的外部编辑）。
+ *   3. `settings/document-updated(ns, revision)`：本条目文档自身变化，保留兼容。
+ *
+ * 观察点注册位置是**契约要求**，不是风格选择：
+ * `loader/volatile-update` 由 loader 以 `fiber.ctx.emit(self, event, paths)` 派发，
+ * 其中 `self[Context.filter] = (owner) => owner.fiber === <条目 fiber>`。只有注册在
+ * 插件**顶层 ctx**（其 `hook.ctx.fiber` 正是条目 fiber）上的监听器能收到；
+ * `ctx.inject` 回调拿到的子 ctx 拥有**独立 fiber**，注册在那里永远收不到该事件。
+ * 因此三个观察点都注册在注入回调**之外**的顶层 ctx 上：既满足 fiber 过滤，也保证
+ * settings 服务替换时不会累积重复监听器。
+ *
+ * 严格边界：
+ * - 宿主新契约**没有** validate 钩子（`settings.register` 已删除），因此本模块不
+ *   接收、不安装任何 validate；语义校验由 DEG 自有提交端点承担
+ *   （见 index.js 的 commitSettingsCandidate）。
+ * - describe() 返回的 value 是 defaults resolved 后的结果，与旧 `scope.get()` 的
+ *   “已注册 schema 解析值”语义一致：读取归一仍按缺失字段回退默认值处理。
+ *
+ * @module dsh-expert-group/host/settings-source
+ */
+
+/**
+ * 运行期配置观察事件（按优先级排列）。
+ *
+ * - `loader/volatile-update`：条目本地事件，**带 fiber 过滤** → 必须注册在插件顶层 ctx。
+ * - `app-boot/config-reload`：无过滤的全局事件，作为兜底。
+ */
+const CONFIG_OBSERVATION_EVENTS = Object.freeze([
+  "loader/volatile-update",
+  "app-boot/config-reload",
+]);
+
+/**
+ * 从 describe() 结果里读取本条目描述符。
+ *
+ * 宿主只会把「声明了 volatile 字段的条目」放进 describe()；条目 id 被用户重命名
+ * 时这里读不到，调用方必须回落到插件默认 entry（不崩溃、不伪造值）。describe()
+ * 在配置编辑器尚未就绪等边界上可能抛错：读取失败只代表“当前不可读”。
+ *
+ * @param {object} service - 注入的 ctx.settings。
+ * @param {string} namespace - profile 条目 id（本插件为 dsh-expert-group）。
+ * @returns {object|undefined} 该条目的描述符；不可读时 undefined。
+ */
+export function findSettingsDescriptor(service, namespace) {
+  if (service === null || typeof service?.describe !== "function") return undefined;
+  let descriptors;
+  try {
+    descriptors = service.describe();
+  } catch {
+    return undefined;
+  }
+  if (!Array.isArray(descriptors)) return undefined;
+  const descriptor = descriptors.find((candidate) => candidate?.ns === namespace);
+  if (descriptor === undefined) return undefined;
+  if (descriptor.value === null || typeof descriptor.value !== "object") return undefined;
+  return descriptor;
+}
+
+/**
+ * 只取值面的便捷读取：找不到或 value 非对象时返回 undefined。
+ *
+ * @param {object} service - 注入的 ctx.settings。
+ * @param {string} namespace - profile 条目 id。
+ * @returns {object|undefined} 该条目的当前值（defaults resolved）。
+ */
+export function readSettingsDescriptorValue(service, namespace) {
+  return findSettingsDescriptor(service, namespace)?.value;
+}
+
+/**
+ * @param {object} options
+ * @param {number[]} [options.unloadingStates] - 覆盖卸载态数值（测试用）。
+ */
+export function createSettingsSourceModule({ unloadingStates = [4, 5] } = {}) {
+  const states = Array.isArray(unloadingStates) ? unloadingStates.slice() : [4, 5];
+  /**
+   * 当前绑定与观察状态；`dispose()` 置空。
+   *
+   * 单一对象同时承载「读源绑定」与「观察计数」，避免出现半释放的不一致：只要它为
+   * null，所有迟到事件与读取都变成 no-op。
+   */
+  let state = null;
+
+  function isUnloading(ctx) {
+    try {
+      const stateValue = ctx?.fiber?.state;
+      return states.includes(stateValue);
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * 运行期统一观察入口：**先重读**宿主 describe()，再按 revision **幂等**通知。
+   *
+   * - **重读总是发生**：读取面在事件到达后立刻看到宿主权威值，不存在旧快照缓存，
+   *   因此「设置保存后运行期立即跟随」不依赖任何记忆化假设。
+   * - **通知按 revision 去重**：一次用户保存通常先后触发 `loader/volatile-update`、
+   *   `app-boot/config-reload`，有时还叠加 `settings/document-updated`，它们描述的是
+   *   同一次变更；去重后 hooks.onChange() 只触发一次，不放大成刷新风暴。
+   * - revision 不可用时**不去重**：宁可多通知一次，也不能因为宿主/替身不提供版本号
+   *   而漏掉真实变更。
+   * - 未安装、已释放、卸载中、服务未就绪：不重读也不通知。
+   *
+   * @returns {boolean} 本次是否真的通知了变更。
+   */
+  function observeConfiguration() {
+    const active = state;
+    if (active === null || active.mode !== "inject") return false;
+    if (isUnloading(active.ctx)) return false;
+    if (active.refresh === null) return false;
+    // 重入保护：真实宿主的 describe() 自身会在 revision 变化时派发
+    // `settings/document-updated`，因此「本条目文档事件 → 重读 describe()」可能递归回到
+    // 本函数。重入的那一层直接返回，让最外层完成读取与通知，避免递归放大。
+    if (active.observing) return false;
+    active.observing = true;
+    let descriptor;
+    try {
+      descriptor = active.refresh();
+    } finally {
+      active.observing = false;
+    }
+    const revision = descriptor === undefined ? undefined : descriptor.revision;
+    if (revision !== undefined && active.known && revision === active.revision) {
+      active.suppressed += 1;
+      return false;
+    }
+    active.known = revision !== undefined;
+    active.revision = revision;
+    active.notifications += 1;
+    active.hooks.onChange();
+    return true;
+  }
+
+  return Object.freeze({
+    /**
+     * 按 0.1.7-alpha.2 契约接线：只通过注入的 ctx.settings 交互。
+     * @param {object} ctx - 插件 ctx（**顶层**；观察点必须注册在它上面）。
+     * @param {object} options
+     * @param {string} options.namespace - profile 条目 id。
+     * @param {object} [options.schema] - 旧签名的 schema 参数；宿主现在自行从条目
+     *   Config 投影，这里只保留参数形状，不再参与注册。
+     * @param {object} options.entry - describe() 不可读时的默认值（插件默认配置）。
+     * @param {{setSource:Function, onChange:Function}} options.hooks
+     */
+    install(ctx, { namespace, schema: _schema, entry, hooks } = {}) {
+      if (ctx === null || typeof ctx !== "object") throw new TypeError("settings source install 需要 ctx");
+      if (typeof namespace !== "string" || namespace.length === 0) throw new TypeError("settings source install 需要 namespace");
+      if (typeof hooks?.setSource !== "function" || typeof hooks?.onChange !== "function") {
+        throw new TypeError("settings source install 需要 setSource/onChange hooks");
+      }
+      if (typeof ctx.inject !== "function") {
+        // 旧/测试 Host 没有 inject：保持 entry 作为 source，不抛错。
+        hooks.setSource(() => entry);
+        hooks.onChange();
+        state = { namespace, mode: "entry", notifications: 0, suppressed: 0 };
+        return { namespace, mode: "entry" };
+      }
+
+      // 观察状态：服务未就绪时 refresh 为 null，事件一律 no-op（读取面仍是 entry）。
+      state = {
+        namespace,
+        mode: "inject",
+        ctx,
+        hooks,
+        refresh: null,
+        observing: false,
+        known: false,
+        revision: undefined,
+        notifications: 0,
+        suppressed: 0,
+      };
+
+      // 顶层观察点：只注册一次（不在注入回调里，避免服务替换时累积重复监听器）。
+      if (typeof ctx.on === "function") {
+        for (const event of CONFIG_OBSERVATION_EVENTS) {
+          ctx.on(event, () => { observeConfiguration(); });
+        }
+        // 本条目文档自身变化：与 loader 事件共用同一幂等入口。DEG 自己的提交也会走到
+        // 这里，因此读取面在提交完成后立即收敛到宿主权威值（不再依赖 registration token）。
+        ctx.on("settings/document-updated", (updatedNamespace) => {
+          if (updatedNamespace !== namespace) return;
+          observeConfiguration();
+        });
+      }
+
+      ctx.inject(["settings"], (settingsCtx) => {
+        const service = settingsCtx.settings;
+        const active = state;
+        if (active === null) return;
+        // 最新一次 describe() 读到的本条目值；undefined 表示当前不可读，读取面回落到 entry。
+        let current;
+
+        /** 重新读取宿主 describe()；条目消失时把 current 复位成 undefined（回落 entry）。 */
+        const refresh = () => {
+          const descriptor = findSettingsDescriptor(service, namespace);
+          current = descriptor === undefined ? undefined : descriptor.value;
+          return descriptor;
+        };
+        active.refresh = refresh;
+        // 服务世代切换：describe() 的 revision 从新实例重新计数，旧去重基线必须作废，
+        // 否则新世代的首个变更会被误判成「同一份文档」而漏通知。
+        active.known = false;
+        active.revision = undefined;
+
+        const bindEffect = typeof settingsCtx?.effect === "function" ? settingsCtx.effect.bind(settingsCtx) : ctx.effect.bind(ctx);
+
+        // 关闭宿主自动生成配置页（DEG 有自己的设置页）。owner 必须是插件自己的 fiber，
+        // 否则宿主会把策略记到 settings 服务自身并在重复注册时抛错。
+        bindEffect(() => {
+          if (typeof service?.configure !== "function") return () => {};
+          return service.configure({ auto: false }, ctx.fiber);
+        }, "dsh-expert-group: settings presentation policy");
+
+        // 首次读取并建立去重基线：安装期的 hooks.onChange() 自己会通知，不占用观察通道。
+        const descriptor = refresh();
+        active.known = descriptor !== undefined && Number.isSafeInteger(descriptor.revision);
+        active.revision = active.known ? descriptor.revision : undefined;
+
+        hooks.setSource(() => (current === undefined ? entry : current));
+        bindEffect(() => () => {
+          if (isUnloading(ctx)) return;
+          hooks.setSource(() => entry);
+          hooks.onChange();
+        }, "dsh-expert-group: settings source binding");
+        hooks.onChange();
+      });
+      return { namespace, mode: "inject" };
+    },
+    /**
+     * 只读装配记录（含运行期观察计数）。
+     *
+     * `observations` 供回归用例断言幂等与释放语义：
+     * - notifications：真正触发 hooks.onChange() 的次数；
+     * - suppressed：被 revision 去重抑制的事件次数。
+     */
+    describe: () => (state === null
+      ? { installed: false }
+      : {
+        installed: true,
+        namespace: state.namespace,
+        mode: state.mode,
+        observations: { notifications: state.notifications, suppressed: state.suppressed },
+      }),
+    dispose() {
+      // 释放后观察通道失效：所有迟到事件（loader 已提交 volatile 值、事件仍在队列里）
+      // 都变成 no-op，插件卸载后不得再刷新任何读源。
+      state = null;
+    },
+  });
+}

package/host/storage-binding.js

@@ -0,0 +1,94 @@
+/**
+ * Host 关注点模块：storage binding / 初始化代际 / 快照缓存。
+ *
+ * 接管原先散落在 apply 里的 binding 生成器实例、active binding 投影与
+ * domain/fan-out 快照缓存；写入串行链与 storage domain 的 open/close 时序仍留在
+ * index.js（源码契约测试锁定），任务 06 再收缩。
+ *
+ * @module dsh-expert-group/host/storage-binding
+ */
+import { createBindingController } from "../storage.js";
+
+/**
+ * @param {object} [options]
+ * @param {object} [options.bindingController] - 注入既有控制器（测试用）。
+ */
+export function createStorageBindingModule({ bindingController = createBindingController() } = {}) {
+  if (bindingController === null || typeof bindingController !== "object"
+    || typeof bindingController.begin !== "function" || typeof bindingController.install !== "function") {
+    throw new TypeError("createStorageBindingModule 需要 bindingController");
+  }
+  let domainSnapshot = {};
+  let fanoutSnapshot;
+
+  return Object.freeze({
+    /**
+     * 开始新 generation：旧 binding 立即失效，且清空快照缓存，
+     * 避免新 generation 复用上一代的 domain/fan-out 数据。
+     */
+    begin() {
+      const binding = bindingController.begin();
+      domainSnapshot = {};
+      fanoutSnapshot = undefined;
+      return binding;
+    },
+    /** 安装 ready binding；迟到/被替换的 binding 返回 false。 */
+    install: (binding, value) => bindingController.install(binding, value),
+    /**
+     * 使 binding 失效：脱离 current、清空快照缓存并取消未完成的初始化。
+     * 旧 generation 因此无法再回写新 binding。
+     *
+     * 快照缓存的重置是无条件的：domainSnapshot 恒为普通对象（只能被 begin()/setDomainSnapshot()
+     * 赋成对象或 {}），因此这里不存在「未初始化就跳过」的情形，无需再判断它是否为 undefined。
+     */
+    invalidate(binding) {
+      if (binding === undefined || binding === null) return false;
+      bindingController.invalidate(binding);
+      domainSnapshot = {};
+      try {
+        binding.cancelInitialization?.();
+      } catch {
+        // 取消回调是宿主注入的可选能力；异常不能影响失效本身。
+      }
+      return true;
+    },
+    isCurrent: (binding) => bindingController.isCurrent(binding),
+    current: () => bindingController.current(),
+    /** 只返回 ready binding；opening/fallback 都视为不可用。 */
+    active() {
+      const binding = bindingController.current();
+      return binding?.status === "ready" ? binding : void 0;
+    },
+    setDomainSnapshot(value) {
+      domainSnapshot = value !== null && typeof value === "object" ? value : {};
+      return domainSnapshot;
+    },
+    setFanoutSnapshot(value) {
+      fanoutSnapshot = value;
+      return fanoutSnapshot;
+    },
+    domainSnapshot: () => domainSnapshot,
+    fanoutSnapshot: () => fanoutSnapshot,
+    /** readStorageSnapshot 使用的合并投影（settings 字段由调用方补）。 */
+    snapshots: () => ({ ...domainSnapshot }),
+    describe() {
+      const binding = bindingController.current();
+      return {
+        hasBinding: binding !== undefined,
+        status: binding?.status,
+        generation: binding?.generation,
+        tableNames: binding === undefined ? [] : ["session_overrides", "child_models", "fanout_tasks"].filter((name) => binding[tableKeyOf(name)] !== undefined),
+      };
+    },
+    dispose() {
+      domainSnapshot = {};
+      fanoutSnapshot = undefined;
+    },
+  });
+}
+
+function tableKeyOf(tableName) {
+  if (tableName === "session_overrides") return "sessionTable";
+  if (tableName === "child_models") return "childTable";
+  return "fanoutTable";
+}