@deepseek-ai/dsh-settings 0.0.1-rc.1 → 0.0.1-rc.3

package/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/settings/settings/README.md
-README.md: 7917f38017bfb23dc4718ee533c1f9a92b519d41
-README.zh.md: f46cf433b4d2207b17b0f40cc3b9cf70794b512c
+README.md: b1c32c7f4cd05b05802400b33dfdd40f7ed20e61
+README.zh.md: ebb5d2cebb347301c32ea3f2c3448dd33b57872e

package/README.md

@@ -28,6 +28,8 @@ Subclasses implement `writable`, `load()`, and `persist(ns, section)`, optionall
 
 `settings/document-updated (ns, revision)` fires whenever the RAW user section changes, whether or not the resolved value did. Configuration surfaces need this one: storing an override equal to the composition base leaves the resolved value alone but changes what the document says (the field is now overridden, not inherited) and moves the revision every open editor is holding. Listener containment matches `settings/updated`.
 
+Both declarations live in the client-safe `./types` subpath export, together with the `SettingsNamespace` and `SettingsUpdateSource` types their signatures name; the package root re-exports those types. A consumer outside the Host compilation face therefore reads the very signature the Host emits instead of restating it.
+
 ## Model Experience
 
 Indirectly, through consumer plugins that resolve model-affecting values (for example a default model route) from their namespaces; each consumer's own surface documents the effect.

package/README.zh.md

@@ -2,42 +2,44 @@
 
 [English](README.md) | 中文
 
-用户设置 Service Definition（`ctx.settings`）。一个提供方持有按 namespace 分节的原始文档；插件注册 namespace schema 并读取分层解析值：schema 默认值，然后注册方的组合 `base`（其 cordis.yml entry 配置子集），最后用户文档分节。不挂载提供方时消费者行为不变：仍只按 entry 配置解析，因此任何组合有无 settings 都能工作。
+用户设置 Service Definition（`ctx.settings`）。一个提供方持有按 namespace 分节的原始文档；插件注册 namespace schema 并读取分层解析值：schema 默认值，然后注册方的组合 `base`（其 cordis.yml entry 配置子集），最后用户文档分节。不挂载提供方时消费方行为不变：仍只按 entry 配置解析，因此任何组合有无 settings 都能工作。
 
 ## 服务 API
 
 - `documentPath` — 提供方拥有用户可编辑文件时，该字段是文件的绝对路径；非文件提供方保留 `undefined`。Host 配置适配器据此派生可用性，而浏览器协议只暴露一个布尔能力，绝不暴露文件系统目标。
 - `prepareDocument()` — 让文档做好供原生编辑器打开的准备后返回该路径。基类实现返回 `documentPath`；文件提供方可先创建缺失的文档。
-- `register(ns, schema, { base?, applies? })` — 返回 owner 的 `SettingsScope`（`get`/`watch`/`update`）。注册是调用方插件 fiber 上的 effect：dispose 该 fiber 即移除 namespace 及其观察者。schema 拒绝的存量分节会使注册本身失败；重复 namespace 立即报错。
-- `describe(options?)` — 每个 namespace 一条描述（`schema.toJSON()` 封装、解析值、分离出的 `base`/`user` 层、`applies`），供配置界面使用；字段出现在 `user` 中即标记其被用户覆盖。`describe({ redactSecrets: true })` 从每一层剥离 `role('secret')` 字段，并附加 `secrets` 槽位列表（`{ path, set }`）；每个协议接口都必须传入它，纯遍历器 `redactSecrets(schema, value)` 已导出，供其他 wire 使用。
+- `register(ns, schema, { base?, applies? })` — 返回 owner 的 `SettingsScope`（`get`/`watch`/`update`）。注册是调用方插件 fiber 上的 effect：dispose（资源释放）该 fiber 即移除 namespace 及其观察者。schema 拒绝的存量分节会使注册本身失败；重复 namespace 立即报错。
+- `describe(options?)` — 每个 namespace 一条描述（`schema.toJSON()` 封装、解析值、分离出的 `base`/`user` 层、`applies`），供配置界面使用；字段出现在 `user` 中即标记其被用户覆盖。`describe({ redactSecrets: true })` 从每一层剥离 `role('secret')` 字段，并附加 `secrets` slot 列表（`{ path, set }`）；每个协议接口都必须传入它，纯遍历器 `redactSecrets(schema, value)` 已导出，供其他 wire 使用。
 - `get(ns)` — 解析值；未注册时为 `undefined`。
-- `update(ns, patch)` — 把普通对象 patch 深合并进用户分节（绝不合并进 `base`），校验解析候选值，经提供方持久化后提交。patch 只能包含与 JSON 兼容的数据：Date、Map、BigInt、非有限数或循环引用会在任何内容持久化前带着以 `$` 为根的路径拒绝（YAML/JSON 存储在重载时会静默改变这类值）。校验失败在持久化前拒绝；只读提供方（`writable: false`）拒绝一切写入。同一 namespace 的写入按调用顺序串行。
+- `update(ns, patch)` — 把普通对象 patch 深合并进用户分节（绝不合并进 `base`），校验解析候选值，经提供方持久化后提交。patch 只能包含与 JSON 兼容的数据：Date、Map、BigInt、非有限数或循环引用会在任何内容持久化前被拒绝，并给出以 `$` 为根的路径（YAML/JSON 存储在重载时会静默改变这类值）。校验失败在持久化前拒绝；只读提供方（`writable: false`）拒绝一切写入。同一 namespace 的写入按调用顺序串行。
 - `replace(ns, section)` — 整体替换用户分节：这是刻意的重置（`replace({})` 重新继承 `base` 与 schema 默认值）。
 - `mutate(ns, ops)` — 在写入排到队首那一刻的分节上，按序施加 `{ op: 'set' | 'unset', path }` 编辑。这是任何持有**不完整**视图的调用方的删除路径：配置 UI 读到的是脱敏后的 descriptor，据此重建分节再整体替换，会把 wire 从未回传的每个机密都删掉，而一条 op 只点名它真正要改的那个字段。
-- 每次写入都可携带可选的 `expectedRevision`。每个 descriptor 都带有该 namespace 的 `revision`——一个针对其**原始**分节的单调计数器；期望值不再匹配的写入会以 `SettingsConflictError`（`code: 'SETTINGS_CONFLICT'`，并附上两个 revision）被拒绝，而不是覆盖先完成写入的写入方。写队列只保证写入的先后次序，它本身分辨不出新的写入方与持有陈旧快照的写入方。
-- 解析值是深冻结快照。每次提交后观察者收到 `(next, prev)`：同一回调的调用异步、逐次、按提交顺序执行（慢的旧调用绝不会覆盖更新的结果），异常——同步抛出与异步拒绝——均被隔离。watch 的 disposer 返回后不再启动新的调用（已排队的那一次会被跳过）；已启动的调用仍会结算。`settings/updated` 事件逐监听器扇出，一个抛错的 listener 不会饿死其余 listener；异步 listener 的拒绝会被隔离并记入日志，这正是 `INVARIANT` 编码的失败只从同步 listener 重新抛出的原因。
-- 服务卸载先拒绝新写入与观察者调用的启动，再排干全部排队写入与已启动的观察者调用后才完成；registrant fiber 在写入途中被 dispose 时，该写入仍到达存储，但不向任何人提交或通知。
+- 每次写入都可携带可选的 `expectedRevision`。每个 descriptor 都带有该 namespace 的 `revision`——一个针对其**原始**分节的单调计数器；期望值不再匹配的写入会以 `SettingsConflictError`（`code: 'SETTINGS_CONFLICT'`，并附上两个 revision）被拒绝，而不是覆盖先完成写入的写入方。写队列只保证写入的先后次序，它本身分辨不出持有新鲜快照的写入方与持有陈旧快照的写入方。
+- 解析值是深冻结快照。每次提交后观察者收到 `(next, prev)`：同一回调的调用异步、逐次、按提交顺序执行（慢的旧调用绝不会晚于较新的调用生效），异常——同步抛出与异步拒绝——均被隔离。watch 的 disposer 返回后不再启动新的调用（已排队的那一次会被跳过）；已启动的调用仍会结算。`settings/updated` 事件逐监听器扇出，一个抛错的 listener 不会饿死其余 listener；异步 listener 的拒绝会被隔离并记入日志，这正是 `INVARIANT` 编码的失败只从同步 listener 重新抛出的原因。
+- 服务卸载先拒绝新写入与观察者调用的启动，再排干全部排队写入与已启动的观察者调用后才完成；registrant fiber 在写入途中被 dispose 时，该写入仍到达存储，但不会提交，也不会通知任何人。
 
 ## 提供方约定
 
-子类实现 `writable`、`load()`、`persist(ns, section)`，可选择为一个本地用户可编辑文件重写 `documentPath` 与 `prepareDocument()`，并通过受保护的 `publish(doc)` 推入外部观察到的文档。基类 service init 在服务可注入前加载并发布一次文档；自有 init（watcher、连接）的 provider 先经 `yield* super[Service.init]()` 委托。publish 时每个已注册 namespace 独立重解析：非法分节保留该 namespace 的最后可用值并告警——热重载绝不拖垮进程；启动期与注册期校验则立即报错。
+子类实现 `writable`、`load()`、`persist(ns, section)`，可选择为一个本地用户可编辑文件重写 `documentPath` 与 `prepareDocument()`，并通过受保护的 `publish(doc)` 推入外部观察到的文档。基类服务 init 在服务可注入前加载并发布一次文档；拥有自有 init（watcher、连接）的提供方会先通过 `yield* super[Service.init]()` 委托给基类。publish 时每个已注册 namespace 独立重解析：非法分节保留该 namespace 的最后可用值并告警——热重载绝不拖垮进程；启动期与注册期校验则立即报错。
 
 ## 事件
 
 `settings/updated (ns, next, prev, source)` 在每次提交后触发；`source` 为 `update`（进程内写入）或 `provider`（外部变更）。解析值深相等时绝不触发——它面向消费方，而消费方只关心自己的值有没有变。
 
-`settings/document-updated (ns, revision)` 在**原始**用户分节发生变化时触发，无论解析值是否随之改变。配置界面需要的是这一个：存入一个与组合 `base` 相同的覆盖值不会改变解析值，却改变了文档的说法（该字段从继承变成了覆盖），也推进了每个已打开编辑器所持有的 revision。监听器的收容方式与 `settings/updated` 相同。
+`settings/document-updated (ns, revision)` 在**原始**用户分节发生变化时触发，无论解析值是否随之改变。配置界面需要的是这一个：存入一个与组合 `base` 相同的覆盖值不会改变解析值，却改变了文档的说法（该字段从继承变成了覆盖），也推进了每个已打开编辑器所持有的 revision。监听器的异常隔离方式与 `settings/updated` 相同。
+
+两条声明都住在 client-safe 的 `./types` 子路径出口，与其签名点名的 `SettingsNamespace`、`SettingsUpdateSource` 类型同处一处；包根继续 re-export 这些类型。于是 Host 编译面之外的消费方读到的正是 Host 发射的那一份签名，而不必再写一遍。
 
 ## 模型体验
 
-间接生效：消费插件从各自 namespace 解析影响模型的值（例如默认模型路由）；效果由各消费者自己的文档描述。
+间接生效：消费方插件从各自 namespace 解析影响模型的值（例如默认模型路由）；效果由各消费方自己的接口文档说明。
 
 #### KV Cache 影响
 
-无直接失效；把设置值折叠进请求前缀的消费方负责该变更。
+无直接失效；把设置值纳入请求前缀的消费方负责该变更。
 
 ## 已知限制与暂缓事项
 
 - **单一用户层** — 解析只认识 schema 默认值、一个组合 `base` 与一个用户文档；它尚未记录每个解析值由哪一层提供。
-- **`redactSecrets` 并非一条可被证明的协议边界**：walker 只跟随 `object`/`dict`/`array`，因此只能经由 union、intersection 或 transform 抵达的 `role('secret')` 会被**原样**返回，且 `secrets` 列表为空；而 `schema.toJSON()` 会把 secret 字段的 `.default(...)` 一并带给每个客户端。这两种情况都不会被拒绝；机密无法经由被遍历的容器抵达的 schema，绝不可注册到暴露于协议的 namespace 上。真正的答案是一个 fail-closed 的 `describeForWire()`——它拒绝自己无法证明安全的 schema，并对序列化信封与错误文本做净化——此项暂缓。
+- **`redactSecrets` 并非一条可被证明的协议边界**：walker 只跟随 `object`/`dict`/`array`，因此只能经由 union、intersection 或 transform 抵达的 `role('secret')` 会被**原样**返回，且 `secrets` 列表为空；而 `schema.toJSON()` 会把 secret 字段的 `.default(...)` 一并带给每个客户端。这两种情况都不会被拒绝；机密无法经由被遍历的容器抵达的 schema，绝不可注册到暴露于协议的 namespace 上。真正的答案是一个 fail-closed 的 `describeForWire()`——它拒绝自己无法证明安全的 schema，并对序列化封装与错误文本做净化——此项暂缓。
 - **跨进程并发由提供方定义** — seam 仅在进程内按 namespace 串行化写入；跨进程并发按提供方行为收敛（本地文件提供方在写锁下读-改-写，因此 namespace 在并发写入者下不会丢失，同 namespace 冲突按后写胜出解决）。

package/lib/index.js

@@ -251,7 +251,7 @@ function deepFreeze(value) {
 * the base class owns namespace registration, resolution, validation, change
 * detection, and the `settings/updated` commit event.
 */
-var Settings = class extends Service {
+var SettingsProvider = class extends Service {
 	registrations = /* @__PURE__ */ new Map();
 	/** Latest published raw document; empty until the provider's first publish. */
 	document = {};
@@ -635,4 +635,4 @@ function installSettingsSection(ctx, ns, schema, entry, hooks) {
 	});
 }
 //#endregion
-export { Settings, Settings as default, SettingsConflictError, deepEqualJson, installSettingsSection, redactSecrets, settingsNamespace };
+export { SettingsConflictError, SettingsProvider, SettingsProvider as default, deepEqualJson, installSettingsSection, redactSecrets, settingsNamespace };

package/lib/types/index.d.ts

@@ -7,12 +7,11 @@
  */
 import { Context, Service } from '@deepseek-ai/cordis';
 import type z from '@deepseek-ai/schemastery';
-import type { Branded } from '@deepseek-ai/dsh-brand';
 import type { RedactedSecret } from './redact.ts';
+import type { SettingsNamespace, SettingsUpdateSource } from './types.ts';
 export { redactSecrets } from './redact.ts';
 export type { RedactedSecret, RedactedValue } from './redact.ts';
-/** Nominal id of one registered settings namespace. */
-export type SettingsNamespace = Branded<'SettingsNamespace'>;
+export type { SettingsNamespace, SettingsUpdateSource } from './types.ts';
 /**
  * Brand a raw string as a {@link SettingsNamespace}.
  * @param value - candidate namespace; lowercase kebab-case, as in plugin short names.
@@ -21,8 +20,6 @@ export type SettingsNamespace = Branded<'SettingsNamespace'>;
 export declare function settingsNamespace(value: string): SettingsNamespace;
 /** When a namespace's changes take effect for its owner. */
 export type SettingsApplies = 'live' | 'restart';
-/** Origin of one committed settings change. */
-export type SettingsUpdateSource = 'update' | 'provider';
 /** Registration options beyond the namespace schema. */
 export interface SettingsRegisterOptions<T> {
     /** Composition-layer values resolved below the user layer (entry-config subset). */
@@ -75,7 +72,7 @@ export interface SettingsDescriptor {
     /** Schema-declared secret positions; present only under `redactSecrets`. */
     secrets?: RedactedSecret[];
 }
-/** Options for {@link Settings.describe}. */
+/** Options for {@link SettingsProvider.describe}. */
 export interface SettingsDescribeOptions {
     /**
      * Strip `role('secret')` fields from `value`/`base`/`user` and enumerate
@@ -114,37 +111,7 @@ export interface SettingsScope<T> {
 }
 declare module '@deepseek-ai/cordis' {
     interface Context {
-        settings: Settings;
-    }
-    interface Events {
-        /**
-         * Committed change to one registered namespace's resolved value. Emitted
-         * after the provider persisted (for `update`) or published (`provider`)
-         * the change; never emitted when the resolved value is deep-equal.
-         * Listener failures are contained and logged — a sync throw and an async
-         * rejection alike — except `INVARIANT`-coded failures, which rethrow
-         * after every listener ran; that rethrow reaches the emitter only from
-         * synchronous listeners, so invariant checks on this event must not be
-         * async functions.
-         * @param ns - the namespace whose resolved value changed.
-         * @param next - the new resolved value.
-         * @param prev - the previous resolved value.
-         * @param source - whether the change entered through `update()` or the provider.
-         * @mode emit
-         */
-        'settings/updated'(ns: SettingsNamespace, next: unknown, prev: unknown, source: SettingsUpdateSource): void;
-        /**
-         * One registered namespace's RAW user section changed, whether or not the
-         * resolved value did. `settings/updated` is the consumer-facing event and
-         * stays deep-equal-gated; this one exists for configuration surfaces,
-         * which must learn that a field went from inherited to overridden (same
-         * resolved value, different meaning) and that their held revision is
-         * stale. Listener containment matches `settings/updated`.
-         * @param ns - the namespace whose stored section changed.
-         * @param revision - the namespace's new revision.
-         * @mode emit
-         */
-        'settings/document-updated'(ns: SettingsNamespace, revision: number): void;
+        settings: SettingsProvider;
     }
 }
 /**
@@ -197,7 +164,7 @@ export type SettingsPathOp = {
  * the base class owns namespace registration, resolution, validation, change
  * detection, and the `settings/updated` commit event.
  */
-export declare abstract class Settings extends Service {
+export declare abstract class SettingsProvider extends Service {
     private readonly registrations;
     /** Latest published raw document; empty until the provider's first publish. */
     private document;
@@ -372,5 +339,5 @@ export interface SettingsSectionHooks<T> {
  * @param hooks - source sink and change notification.
  */
 export declare function installSettingsSection<T>(ctx: Context, ns: SettingsNamespace, schema: z<T>, entry: T, hooks: SettingsSectionHooks<T>): void;
-export default Settings;
+export default SettingsProvider;
 //# sourceMappingURL=index.d.ts.map

package/lib/types/index.js

@@ -0,0 +1,688 @@
+/**
+ * Service Definition for the user-settings capability seam (`ctx.settings`). Providers store one raw document of
+ * per-namespace sections; plugins register a namespace schema and read the
+ * resolved value, which layers schema defaults, the registrant's composition
+ * `base`, and the user document section, in that order.
+ * @module @deepseek-ai/dsh-settings
+ */
+import { Service } from '@deepseek-ai/cordis';
+import { redactSecrets } from "./redact.js";
+export { redactSecrets } from "./redact.js";
+const NAMESPACE_PATTERN = /^[a-z][a-z0-9-]*$/;
+/**
+ * Brand a raw string as a {@link SettingsNamespace}.
+ * @param value - candidate namespace; lowercase kebab-case, as in plugin short names.
+ * @returns the branded namespace.
+ */
+export function settingsNamespace(value) {
+    if (!NAMESPACE_PATTERN.test(value)) {
+        throw new TypeError(`settings namespace "${value}" must match ${String(NAMESPACE_PATTERN)}`);
+    }
+    return value;
+}
+/**
+ * Deep equality over JSON-compatible data (objects, arrays, primitives) — the
+ * Service Definition's single change-detection predicate, exported so the invariant
+ * companion checks exactly the implementation's relation.
+ * @param a - one JSON-compatible value.
+ * @param b - the other JSON-compatible value.
+ * @returns whether the two values are structurally equal.
+ */
+export function deepEqualJson(a, b) {
+    if (a === b)
+        return true;
+    if (typeof a !== 'object' || typeof b !== 'object' || a === null || b === null)
+        return false;
+    if (Array.isArray(a) || Array.isArray(b)) {
+        if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length)
+            return false;
+        return a.every((entry, index) => deepEqualJson(entry, b[index]));
+    }
+    const left = a;
+    const right = b;
+    const keys = Object.keys(left);
+    if (keys.length !== Object.keys(right).length)
+        return false;
+    return keys.every(key => key in right && deepEqualJson(left[key], right[key]));
+}
+/**
+ * A write refused because the namespace moved since the caller read it. The
+ * Service Definition's serialized write queue orders writes; it cannot tell a fresh writer
+ * from one holding a stale snapshot, which is what this reports.
+ */
+export class SettingsConflictError extends Error {
+    /** Stable machine code for wire layers mapping this to their own taxonomy. */
+    code = 'SETTINGS_CONFLICT';
+    /** The revision the write expected. */
+    expected;
+    /** The revision the namespace actually stands at. */
+    actual;
+    /**
+     * @param ns - the namespace whose write was refused.
+     * @param expected - the revision the caller sent.
+     * @param actual - the revision now stored.
+     */
+    constructor(ns, expected, actual) {
+        super(`settings namespace "${ns}" changed since it was read (expected revision ${String(expected)}, now ${String(actual)})`);
+        this.name = 'SettingsConflictError';
+        this.expected = expected;
+        this.actual = actual;
+    }
+}
+/** Whether a value is a plain data object (not an array, null, or class instance). */
+function isPlainObject(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+/** Apply one path op to a detached section, returning the next section. */
+function applyPathOp(section, op) {
+    const [head, ...rest] = op.path;
+    // The empty path addresses the section itself.
+    if (head === undefined) {
+        if (op.op === 'unset')
+            return {};
+        if (!isPlainObject(op.value)) {
+            throw new TypeError('settings mutate: setting the section root requires a plain object');
+        }
+        return { ...op.value };
+    }
+    if (rest.length === 0) {
+        if (op.op === 'set')
+            return { ...section, [head]: op.value };
+        const { [head]: _removed, ...kept } = section;
+        return kept;
+    }
+    const child = section[head];
+    if (!isPlainObject(child)) {
+        // Unsetting through an absent path is already satisfied; setting through
+        // one creates the intermediate objects it needs.
+        if (op.op === 'unset')
+            return section;
+        return { ...section, [head]: applyPathOp({}, { ...op, path: rest }) };
+    }
+    return { ...section, [head]: applyPathOp(child, { ...op, path: rest }) };
+}
+/** Human label for a value that lossless JSON cannot represent (numbers reject inline). */
+function describeRejected(value) {
+    if (value === undefined)
+        return 'undefined';
+    if (typeof value === 'object' && value !== null) {
+        const proto = Object.getPrototypeOf(value);
+        const name = proto?.constructor?.name;
+        return name === undefined || name === 'Object' ? 'a non-plain object' : `a ${name}`;
+    }
+    return `a ${typeof value}`;
+}
+/**
+ * Detach and validate one write input in a single walk before persistence:
+ * only JSON data (plain objects, arrays, strings, finite numbers,
+ * booleans, `null`) may reach a provider document. `structuredClone` alone
+ * would admit Dates, Maps, BigInts, and cycles that YAML/JSON storage then
+ * silently distorts on the reload round-trip. `undefined` entries in objects
+ * are skipped — the same sparse-patch semantics as {@link mergeLayers} — while
+ * an `undefined` array entry is rejected rather than coerced.
+ * @param root - plain-object write input (caller-checked).
+ * @param reject - builds the validation error from a value label and its `$`-rooted path.
+ * @returns the detached JSON-compatible clone.
+ */
+function cloneJsonShaped(root, reject) {
+    const visiting = new WeakSet();
+    const clone = (value, path) => {
+        if (value === null || typeof value === 'string' || typeof value === 'boolean')
+            return value;
+        if (typeof value === 'number') {
+            if (!Number.isFinite(value))
+                throw reject('a non-finite number', path);
+            return value;
+        }
+        if (Array.isArray(value)) {
+            if (visiting.has(value))
+                throw reject('a circular reference', path);
+            visiting.add(value);
+            const entries = value.map((entry, index) => clone(entry, `${path}[${index}]`));
+            // Un-mark on exit so one object referenced twice without a cycle passes.
+            visiting.delete(value);
+            return entries;
+        }
+        if (isPlainObject(value)) {
+            if (visiting.has(value))
+                throw reject('a circular reference', path);
+            visiting.add(value);
+            // TODO(settings-json-properties): Use property-safe construction here and
+            // in mergeLayers so valid JSON keys such as "__proto__" remain own data.
+            const out = {};
+            for (const [key, entry] of Object.entries(value)) {
+                if (entry === undefined)
+                    continue;
+                out[key] = clone(entry, `${path}.${key}`);
+            }
+            visiting.delete(value);
+            return out;
+        }
+        throw reject(describeRejected(value), path);
+    };
+    return clone(root, '$');
+}
+/**
+ * Layer `over` onto `under`: plain objects merge recursively, every other
+ * value (arrays included) replaces the lower layer wholesale. `over` never
+ * carries `undefined` entries — sections come from parsed documents and write
+ * snapshots pass {@link cloneJsonShaped}, which strips them so a sparse patch
+ * cannot erase lower keys.
+ */
+function mergeLayers(under, over) {
+    if (over === undefined)
+        return under;
+    if (!isPlainObject(under) || !isPlainObject(over))
+        return over;
+    const merged = { ...under };
+    for (const [key, value] of Object.entries(over)) {
+        merged[key] = key in merged ? mergeLayers(merged[key], value) : value;
+    }
+    return merged;
+}
+/** Recursively freeze one resolved value so handed-out snapshots stay immutable. */
+function deepFreeze(value) {
+    if (typeof value !== 'object' || value === null || Object.isFrozen(value))
+        return value;
+    for (const entry of Object.values(value))
+        deepFreeze(entry);
+    return Object.freeze(value);
+}
+/**
+ * Abstract settings service. Providers implement raw-document storage
+ * (`load`/`persist`) and push external changes through {@link Settings.publish};
+ * the base class owns namespace registration, resolution, validation, change
+ * detection, and the `settings/updated` commit event.
+ */
+export class SettingsProvider extends Service {
+    registrations = new Map();
+    /** Latest published raw document; empty until the provider's first publish. */
+    document = {};
+    /** Per-namespace write chains; settled tails, so a failure never poisons the queue. */
+    writeQueues = new Map();
+    /** In-flight watcher invocation segments, drained by the dispose teardown. */
+    pendingTails = new Set();
+    /** Set at service dispose: refuse new writes while queued ones drain. */
+    stopped = false;
+    /** Opaque read of {@link stopped}: control flow cannot narrow it across awaits. */
+    isStopped() {
+        return this.stopped;
+    }
+    constructor(ctx) {
+        super(ctx, 'settings');
+    }
+    /**
+     * Load the provider's document once and publish it before the service
+     * becomes injectable, and register the write-drain teardown. Providers with
+     * their own init (watchers, connections) delegate here first via
+     * `yield* super[Service.init]()`; their disposers then run before the drain.
+     */
+    async *[Service.init]() {
+        yield async () => {
+            // Teardown: refuse new writes and new watcher starts, then wait until
+            // every queued write chain and every started watcher invocation settles
+            // so disposal completes only once storage and observers are quiescent.
+            // Invocations queued but not yet started skip via the stopped check.
+            this.stopped = true;
+            await Promise.allSettled([...this.writeQueues.values(), ...this.pendingTails]);
+        };
+        this.publish(await this.load());
+    }
+    /**
+     * Absolute path of the provider's user-editable document, when its storage
+     * is one local file. Configuration surfaces use this only as availability
+     * metadata; the guarded open operation resolves the path again Host-side.
+     * Non-file providers leave it undefined and expose no open-document affordance.
+     * @returns the absolute local document path, or undefined for non-file storage.
+     */
+    get documentPath() {
+        return undefined;
+    }
+    /**
+     * Prepare the provider's user-editable document for a native editor. File
+     * providers may materialize an absent document before returning its path;
+     * non-file providers return undefined.
+     * @returns the absolute local document path, or undefined for non-file storage.
+     */
+    prepareDocument() {
+        return Promise.resolve(this.documentPath);
+    }
+    /**
+     * Register a namespace schema and receive its owner scope. The registration
+     * is an effect on the calling plugin's fiber: disposing that fiber removes
+     * the namespace and its observers. An invalid stored section fails the
+     * registration itself — the earliest point where the schema can judge it.
+     * @param ns - unique namespace; duplicate registration fails loud.
+     * @param schema - schemastery schema resolving this namespace's value.
+     * @param options - composition `base` layer and effect timing.
+     * @returns the owner scope for reads, observation, and updates.
+     */
+    register(ns, schema, options) {
+        if (this.registrations.has(ns)) {
+            throw new Error(`settings namespace "${ns}" is already registered`);
+        }
+        const registration = {
+            ns,
+            schema: schema,
+            base: options?.base,
+            applies: options?.applies ?? 'live',
+            ...options?.validate === undefined
+                ? {}
+                : { validate: options.validate },
+            resolved: deepFreeze(this.resolve(schema, options?.base, this.section(ns), options?.validate)),
+            revision: 0,
+            watchers: new Set(),
+        };
+        this.ctx.effect(() => {
+            this.registrations.set(ns, registration);
+            // TODO(settings-registration-quiescence): Deactivate every watcher and await
+            // its tail on disposal so callbacks cannot outlive the registrant fiber.
+            return () => this.registrations.delete(ns);
+        }, `settings.register(${JSON.stringify(String(ns))})`);
+        return {
+            get: () => registration.resolved,
+            watch: (callback) => {
+                const watcher = { callback: callback, tail: Promise.resolve(), active: true };
+                registration.watchers.add(watcher);
+                return () => {
+                    watcher.active = false;
+                    registration.watchers.delete(watcher);
+                };
+            },
+            update: patch => this.update(ns, patch),
+            replace: section => this.replace(ns, section),
+        };
+    }
+    /**
+     * Describe every registered namespace for configuration surfaces, including
+     * the composition `base` and raw user layers so a form can mark which fields
+     * the user overrode (presence in `user`) and what a reset returns to.
+     * @param options - redaction switch; wire surfaces must redact.
+     * @returns one descriptor per registered namespace, in registration order.
+     */
+    describe(options) {
+        return [...this.registrations.values()].map((registration) => {
+            let user;
+            try {
+                user = this.section(registration.ns);
+            }
+            catch {
+                // A malformed stored section already warned at publish and kept the
+                // last good resolved value; only that malformed shape can throw here,
+                // and describing it as "no user layer" keeps this read total.
+                user = undefined;
+            }
+            const base = registration.base === undefined ? undefined : structuredClone(registration.base);
+            const detachedUser = user === undefined ? undefined : structuredClone(user);
+            const descriptor = {
+                ns: registration.ns,
+                schema: registration.schema.toJSON(),
+                value: registration.resolved,
+                revision: registration.revision,
+                ...base === undefined ? {} : { base },
+                ...detachedUser === undefined ? {} : { user: detachedUser },
+                applies: registration.applies,
+            };
+            if (options?.redactSecrets !== true)
+                return descriptor;
+            const schema = registration.schema;
+            const redacted = redactSecrets(schema, registration.resolved);
+            return {
+                ...descriptor,
+                value: redacted.value,
+                ...base === undefined ? {} : { base: redactSecrets(schema, base).value },
+                ...detachedUser === undefined ? {} : { user: redactSecrets(schema, detachedUser).value },
+                secrets: redacted.secrets,
+            };
+        });
+    }
+    /**
+     * Read one registered namespace's resolved value.
+     * @param ns - the namespace to read.
+     * @returns the resolved value, or `undefined` while unregistered.
+     */
+    get(ns) {
+        return this.registrations.get(ns)?.resolved;
+    }
+    /**
+     * Merge a patch into one registered namespace's user layer, validate the
+     * resolved candidate, persist through the provider, then commit and emit.
+     * A validation failure rejects before anything is persisted. Writes to one
+     * namespace are serialized: concurrent updates apply in call order, each
+     * merging over the previous write's committed section.
+     * @param ns - the registered namespace to update.
+     * @param patch - plain-object patch over the user section.
+     * @param expectedRevision - the descriptor `revision` the caller read; a
+     *   namespace that moved past it rejects with {@link SettingsConflictError}.
+     */
+    async update(ns, patch, expectedRevision) {
+        return this.write(ns, patch, 'merge', expectedRevision);
+    }
+    /**
+     * Replace one registered namespace's user section wholesale, validate,
+     * persist, then commit and emit. Keys absent from `section` fall back to the
+     * composition `base` and schema defaults — this is the removal/reset path a
+     * merge-only patch cannot express (`replace({})` re-inherits everything).
+     * @param ns - the registered namespace to replace.
+     * @param section - the complete next user section.
+     * @param expectedRevision - the descriptor `revision` the caller read; a
+     *   namespace that moved past it rejects with {@link SettingsConflictError}.
+     */
+    async replace(ns, section, expectedRevision) {
+        return this.write(ns, section, 'replace', expectedRevision);
+    }
+    /**
+     * Apply path-addressed edits to one registered namespace's user section,
+     * validate, persist, then commit and emit. The ops are applied to the
+     * section as it stands when the write reaches the front of the queue, so a
+     * caller never has to restate fields it did not touch — and, crucially,
+     * cannot delete fields it never saw. This is the write path for any caller
+     * holding a redacted view; `replace` remains the wholesale reset.
+     * @param ns - the registered namespace to edit.
+     * @param ops - ordered path edits; later ops observe earlier ones.
+     * @param expectedRevision - the descriptor `revision` the caller read; a
+     *   namespace that moved past it rejects with {@link SettingsConflictError}.
+     */
+    async mutate(ns, ops, expectedRevision) {
+        if (!Array.isArray(ops))
+            throw new TypeError(`settings mutate for "${ns}" must be an array of path ops`);
+        for (const op of ops) {
+            if (!isPlainObject(op) || (op['op'] !== 'set' && op['op'] !== 'unset')) {
+                throw new TypeError(`settings mutate for "${ns}" ops must be {op:'set'|'unset', path}`);
+            }
+            if (!Array.isArray(op['path']) || op['path'].some(part => typeof part !== 'string')) {
+                throw new TypeError(`settings mutate for "${ns}" op paths must be arrays of strings`);
+            }
+        }
+        return this.write(ns, ops, 'mutate', expectedRevision);
+    }
+    /** Validate a write, then queue it on the namespace's serialized write chain. */
+    write(ns, input, mode, expectedRevision) {
+        const verb = mode === 'merge' ? 'update' : mode === 'replace' ? 'replace' : 'mutate';
+        const registration = this.registrations.get(ns);
+        if (registration === undefined) {
+            throw new Error(`settings namespace "${ns}" is not registered`);
+        }
+        if (this.isStopped()) {
+            throw new Error(`settings service is disposed: "${ns}" cannot be written`);
+        }
+        if (!this.writable) {
+            throw new Error(`settings provider is read-only: "${ns}" cannot be updated in-process`);
+        }
+        // A mutate's ops array is wrapped so one JSON-shape walk covers both
+        // shapes; merge/replace carry the section itself.
+        let payload;
+        if (mode === 'mutate') {
+            payload = { ops: input };
+        }
+        else {
+            if (!isPlainObject(input))
+                throw new TypeError(`settings ${verb} for "${ns}" must be a plain object`);
+            payload = input;
+        }
+        // Snapshot at call time: the queue must never read a caller-owned object
+        // the caller may keep mutating while the write waits its turn. The same
+        // walk rejects values that JSON cannot preserve (see cloneJsonShaped).
+        const snapshot = cloneJsonShaped(payload, (label, path) => new TypeError(`settings ${verb} for "${ns}" must contain only JSON-compatible data (found ${label} at ${path})`));
+        const previous = this.writeQueues.get(ns) ?? Promise.resolve();
+        // Chain past a failed predecessor: one rejected write must not poison the
+        // namespace queue for every later caller.
+        const run = previous.catch(() => undefined).then(async () => {
+            if (this.isStopped()) {
+                throw new Error(`settings service was disposed before the queued "${ns}" ${verb} ran`);
+            }
+            if (this.registrations.get(ns) !== registration) {
+                throw new Error(`settings namespace "${ns}" registration was disposed before the queued ${verb} ran`);
+            }
+            // Every mode derives from the section as it stands NOW, at the front of
+            // the queue — never from whatever the caller last saw.
+            const current = this.section(ns) ?? {};
+            // The revision check belongs HERE, not at call time: the queue orders
+            // writes but cannot tell a fresh writer from one holding a snapshot
+            // that a predecessor already superseded.
+            if (expectedRevision !== undefined && expectedRevision !== registration.revision) {
+                throw new SettingsConflictError(ns, expectedRevision, registration.revision);
+            }
+            const section = mode === 'merge'
+                ? mergeLayers(current, snapshot)
+                : mode === 'replace'
+                    ? snapshot
+                    : snapshot['ops'].reduce(applyPathOp, current);
+            const next = deepFreeze(this.resolve(registration.schema, registration.base, section, registration.validate));
+            await this.persist(ns, section);
+            // The write reached storage either way; the cache must say so. Commit
+            // only when this registration is still the namespace owner — a fiber
+            // disposed (or replaced) mid-persist must not receive the notification.
+            this.document[ns] = section;
+            // TODO(settings-replacement-resync): Re-resolve any replacement registration
+            // from this persisted section so an old in-flight write cannot leave it stale.
+            if (this.registrations.get(ns) === registration && !this.isStopped()) {
+                this.bumpRevision(registration, current, section);
+                this.commit(registration, next, 'update');
+            }
+        });
+        this.writeQueues.set(ns, run);
+        return run;
+    }
+    /**
+     * Provider hook: commit a complete raw document observed in storage. Each
+     * registered namespace re-resolves; an invalid section keeps that
+     * namespace's last good value and warns, other namespaces still commit.
+     * @param doc - the detached raw document (unregistered sections preserved).
+     * @param source - change origin; defaults to `provider`.
+     */
+    publish(doc, source = 'provider') {
+        // Read every raw section BEFORE swapping the document, so the revision
+        // bump below compares what was stored with what now is — an external edit
+        // moves the revision exactly like an in-process write.
+        const before = new Map();
+        for (const registration of this.registrations.values()) {
+            try {
+                before.set(registration.ns, this.section(registration.ns));
+            }
+            catch {
+                // A malformed stored section is not a readable "before"; treating it
+                // as absent still bumps against any well-formed replacement.
+                before.set(registration.ns, undefined);
+            }
+        }
+        this.document = doc;
+        for (const registration of this.registrations.values()) {
+            let next;
+            try {
+                next = deepFreeze(this.resolve(registration.schema, registration.base, this.section(registration.ns), registration.validate));
+            }
+            catch (error) {
+                this.ctx.logger.warn('settings: keeping last good "%s" after invalid stored section', registration.ns);
+                this.ctx.logger.warn(error);
+                continue;
+            }
+            this.bumpRevision(registration, before.get(registration.ns), this.section(registration.ns));
+            this.commit(registration, next, source);
+        }
+    }
+    /** Read one namespace's raw user section, rejecting non-object sections. */
+    section(ns) {
+        const section = this.document[ns];
+        if (section === undefined)
+            return undefined;
+        if (!isPlainObject(section)) {
+            throw new TypeError(`settings section "${ns}" must be an object of keys`);
+        }
+        return section;
+    }
+    /** Resolve one namespace value: schema defaults, then `base`, then the user layer. */
+    resolve(schema, base, section, validate) {
+        // The merged candidate is untyped by construction; the schema call is the
+        // runtime validation that admits it into T.
+        const value = schema(mergeLayers(base, section));
+        // The owner's own check runs on the admitted value, so it sees defaults
+        // and the composition base exactly as the owner will.
+        validate?.(value);
+        return value;
+    }
+    /**
+     * Advance a namespace's revision when its RAW section changed, and announce
+     * it. Deliberately independent of {@link commit}'s resolved-value equality:
+     * storing an override equal to the composition base leaves the resolved
+     * value alone but changes what the document says, which is exactly what a
+     * configuration surface must re-read.
+     */
+    bumpRevision(registration, before, after) {
+        if (deepEqualJson(before, after))
+            return;
+        registration.revision += 1;
+        this.emitDocumentUpdated(registration.ns, registration.revision);
+    }
+    /** Contained fan-out of `settings/document-updated`, mirroring {@link commit}'s. */
+    emitDocumentUpdated(ns, revision) {
+        let invariantFailure;
+        const args = ['settings/document-updated', ns, revision];
+        for (const listener of this.ctx.events.dispatch('emit', args)) {
+            try {
+                const returned = listener(ns, revision);
+                if (returned != null && typeof returned.then === 'function') {
+                    void Promise.resolve(returned).then(undefined, (error) => {
+                        this.warnListenerFailure(ns, error);
+                    });
+                }
+            }
+            catch (error) {
+                if (error?.code === 'INVARIANT') {
+                    invariantFailure ??= error;
+                    continue;
+                }
+                this.warnListenerFailure(ns, error);
+            }
+        }
+        if (invariantFailure !== undefined)
+            throw invariantFailure;
+    }
+    /** Commit a resolved value when changed: swap, notify watchers, emit the event. */
+    commit(registration, next, source) {
+        const prev = registration.resolved;
+        if (deepEqualJson(next, prev))
+            return;
+        registration.resolved = next;
+        for (const watcher of [...registration.watchers]) {
+            // Serialize per watcher: invocations of one callback run one at a time
+            // in commit order, so a slow stale invocation can never apply after a
+            // newer one. Sync throws and async rejections land in the same handler.
+            // The activity check runs when the queued invocation would start, so a
+            // disposer (or service stop) that ran while it waited prevents the
+            // start entirely; started invocations drain at service dispose.
+            const segment = watcher.tail
+                .then(() => {
+                if (!watcher.active || this.isStopped())
+                    return;
+                return watcher.callback(next, prev);
+            })
+                .then(() => undefined, (error) => {
+                this.warnWatcherFailure(registration.ns, error);
+            });
+            watcher.tail = segment;
+            this.pendingTails.add(segment);
+            void segment.then(() => this.pendingTails.delete(segment));
+        }
+        // Fan the event out one listener at a time (the plain emit stops at the
+        // first throwing listener, starving the rest). Invariant violations are
+        // harness-fatal by design and rethrow after every listener ran; any other
+        // failure is contained so one broken observer cannot wedge the commit
+        // path (and, through it, a provider's reload loop).
+        let invariantFailure;
+        const args = ['settings/updated', registration.ns, next, prev, source];
+        for (const listener of this.ctx.events.dispatch('emit', args)) {
+            try {
+                const returned = listener(registration.ns, next, prev, source);
+                if (returned != null && typeof returned.then === 'function') {
+                    // An emit listener may still be an async function; its rejection
+                    // cannot reach the synchronous INVARIANT rethrow below, so it is
+                    // contained here instead of becoming an unhandled rejection.
+                    void Promise.resolve(returned).then(undefined, (error) => {
+                        this.warnListenerFailure(registration.ns, error);
+                    });
+                }
+            }
+            catch (error) {
+                if (error?.code === 'INVARIANT') {
+                    invariantFailure ??= error;
+                    continue;
+                }
+                this.warnListenerFailure(registration.ns, error);
+            }
+        }
+        if (invariantFailure !== undefined)
+            throw invariantFailure;
+    }
+    /** Contained-watcher diagnostic shared by the sync and async failure paths. */
+    warnWatcherFailure(ns, error) {
+        this.ctx.logger.warn('settings: watcher for "%s" failed', ns);
+        this.ctx.logger.warn(error);
+    }
+    /** Contained-listener diagnostic shared by the sync and async failure paths. */
+    warnListenerFailure(ns, error) {
+        this.ctx.logger.warn('settings: a settings/updated listener for "%s" failed', ns);
+        this.ctx.logger.warn(error);
+    }
+}
+/**
+ * Value mirror of the `FiberState` members {@link isUnloading} compares
+ * against: a const enum has no runtime object to import, and the value is
+ * needed at runtime (same rationale as the CLI boot driver's mirror).
+ */
+const FIBER_DISPOSED = 4;
+const FIBER_UNLOADING = 5;
+/** Whether the consumer's own fiber is tearing down (not just losing the settings service). */
+function isUnloading(ctx) {
+    const state = ctx.fiber.state;
+    return state === FIBER_UNLOADING || state === FIBER_DISPOSED;
+}
+/**
+ * Install the canonical optional-settings consumer wiring: while a settings
+ * service exists, register `ns` with the consumer's composition entry as the
+ * `base` layer and point the source thunk at the resolved scope; when the
+ * service goes away (disposal, provider reload), fall back to the entry so
+ * the consumer keeps working exactly as composed. The registration rides the
+ * scoped fiber, so no settings service ever mounted means none of this runs.
+ * @param ctx - consumer plugin context owning the wiring.
+ * @param ns - the consumer-owned settings namespace.
+ * @param schema - schema resolving the namespace (typically the plugin Config).
+ * @param entry - the consumer's composition entry config, used as `base`.
+ * @param hooks - source sink and change notification.
+ */
+export function installSettingsSection(ctx, ns, schema, entry, hooks) {
+    ctx.inject(['settings'], (sctx) => {
+        const scope = sctx.settings.register(ns, schema, {
+            base: entry,
+            ...hooks.validate === undefined ? {} : { validate: hooks.validate },
+        });
+        hooks.setSource(() => scope.get());
+        sctx.effect(() => () => {
+            // This disposer runs for two different reasons. A settings provider
+            // detaching leaves the consumer running, so it must fall back to its
+            // composition entry and re-judge what it derived. The consumer's own
+            // unload runs it too — and there `onChange` would re-register routes
+            // and touch resources the teardown is releasing, so the fallback is
+            // pointless and the notification actively harmful.
+            if (isUnloading(ctx))
+                return;
+            hooks.setSource(() => entry);
+            hooks.onChange();
+        });
+        hooks.onChange();
+        scope.watch(() => {
+            // A stored change landing while the consumer unloads reaches the watcher
+            // before the registration is released, and `onChange` is exactly as
+            // harmful here as in the disposer above: it re-registers routes against
+            // a fiber whose resources are being let go.
+            if (isUnloading(ctx))
+                return;
+            hooks.onChange();
+        });
+    });
+}
+export default SettingsProvider;
+//# sourceMappingURL=index.js.map

package/lib/types/invariant.js

@@ -0,0 +1,41 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-settings`.
+ * @module @deepseek-ai/dsh-settings/invariant
+ */
+import { deepEqualJson } from "./index.js";
+const PACKAGE_NAME = '@deepseek-ai/dsh-settings';
+/** Cordis companion plugin name. */
+export const name = 'settings-invariant';
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants'];
+/**
+ * Install the commit-event contract: `settings/updated` fires only for a
+ * currently registered namespace, only when the resolved value changed, and
+ * only with the service's authoritative resolved value — all judged with the
+ * seam's own equality predicate.
+ */
+const install = (ctx, fail) => {
+    ctx.on('settings/updated', (ns, next, prev) => {
+        const settings = ctx.get('settings');
+        if (settings === undefined) {
+            fail(`settings/updated for "${ns}" emitted without a live settings service`);
+        }
+        const current = settings.get(ns);
+        if (current === undefined) {
+            fail(`settings/updated for "${ns}" emitted while the namespace is unregistered`);
+        }
+        if (!deepEqualJson(current, next)) {
+            fail(`settings/updated for "${ns}" does not match the authoritative resolved value`);
+        }
+        if (deepEqualJson(next, prev)) {
+            fail(`settings/updated for "${ns}" emitted without a resolved-value change`);
+        }
+    });
+};
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//# sourceMappingURL=invariant.js.map

package/lib/types/redact.js

@@ -0,0 +1,78 @@
+/**
+ * Structural secret redaction for settings values. `role('secret')` fields are
+ * removed from a value before it crosses a wire boundary; a sidecar records
+ * each schema-declared secret position and whether it currently holds a value,
+ * so a configuration surface can render a write-only input without ever
+ * receiving the secret itself.
+ * @module @deepseek-ai/dsh-settings/redact
+ */
+/** Whether a value is a plain data object the walker may recurse into. */
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function walk(node, value, path, secrets) {
+    if (node === undefined)
+        return value;
+    if (node.meta?.role === 'secret') {
+        secrets.push({ path, set: value !== undefined });
+        return undefined;
+    }
+    switch (node.type) {
+        case 'object': {
+            const properties = node.dict ?? {};
+            const source = isRecord(value) ? value : undefined;
+            const rebuilt = {};
+            if (source !== undefined) {
+                for (const [key, entry] of Object.entries(source)) {
+                    if (key in properties)
+                        continue;
+                    rebuilt[key] = entry;
+                }
+            }
+            for (const [key, child] of Object.entries(properties)) {
+                const stripped = walk(child, source?.[key], [...path, key], secrets);
+                if (stripped !== undefined)
+                    rebuilt[key] = stripped;
+            }
+            return source === undefined && Object.keys(rebuilt).length === 0 ? value : rebuilt;
+        }
+        case 'dict': {
+            if (!isRecord(value))
+                return value;
+            const rebuilt = {};
+            for (const [key, entry] of Object.entries(value)) {
+                const stripped = walk(node.inner, entry, [...path, key], secrets);
+                if (stripped !== undefined)
+                    rebuilt[key] = stripped;
+            }
+            return rebuilt;
+        }
+        case 'array': {
+            if (!Array.isArray(value))
+                return value;
+            return value.map((entry, index) => walk(node.inner, entry, [...path, String(index)], secrets));
+        }
+        default:
+            // TODO(settings-wire-redaction): Fail closed instead — a secret reachable
+            // only through a union, intersection, or transform is returned verbatim
+            // here, with nothing recording that it was missed.
+            return value;
+    }
+}
+/**
+ * Remove every `role('secret')` field a schema declares from a value. The
+ * walker follows `object`, `dict`, and `array` containers; a secret must be
+ * declared directly on a field reachable through those containers (a secret
+ * buried inside a union branch or transform is not reachable and must not be
+ * modeled that way). The input is never mutated.
+ * @param schema - live schemastery schema describing the value.
+ * @param value - the value to strip; `undefined` yields an empty record with
+ *   object-property secret slots still enumerated.
+ * @returns the stripped detached value and the ordered secret positions.
+ */
+export function redactSecrets(schema, value) {
+    const secrets = [];
+    const stripped = walk(schema, value, [], secrets);
+    return { value: stripped, secrets };
+}
+//# sourceMappingURL=redact.js.map

package/lib/types/types.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Client-safe type surface of the user-settings seam: the namespace brand, the
+ * commit-origin union, and the seam's Cordis event declarations. Types only —
+ * no runtime code, and nothing here reaches a Host-only symbol, so a Client
+ * compilation face reads exactly the signatures the Host emits.
+ *
+ * @module @deepseek-ai/dsh-settings/types
+ */
+import type { Branded } from '@deepseek-ai/dsh-brand';
+/** Nominal id of one registered settings namespace. */
+export type SettingsNamespace = Branded<'SettingsNamespace'>;
+/** Origin of one committed settings change. */
+export type SettingsUpdateSource = 'update' | 'provider';
+declare module '@deepseek-ai/cordis' {
+    interface Events {
+        /**
+         * Committed change to one registered namespace's resolved value. Emitted
+         * after the provider persisted (for `update`) or published (`provider`)
+         * the change; never emitted when the resolved value is deep-equal.
+         * Listener failures are contained and logged — a sync throw and an async
+         * rejection alike — except `INVARIANT`-coded failures, which rethrow
+         * after every listener ran; that rethrow reaches the emitter only from
+         * synchronous listeners, so invariant checks on this event must not be
+         * async functions.
+         * @param ns - the namespace whose resolved value changed.
+         * @param next - the new resolved value.
+         * @param prev - the previous resolved value.
+         * @param source - whether the change entered through `update()` or the provider.
+         * @mode emit
+         */
+        'settings/updated'(ns: SettingsNamespace, next: unknown, prev: unknown, source: SettingsUpdateSource): void;
+        /**
+         * One registered namespace's RAW user section changed, whether or not the
+         * resolved value did. `settings/updated` is the consumer-facing event and
+         * stays deep-equal-gated; this one exists for configuration surfaces,
+         * which must learn that a field went from inherited to overridden (same
+         * resolved value, different meaning) and that their held revision is
+         * stale. Listener containment matches `settings/updated`.
+         * @param ns - the namespace whose stored section changed.
+         * @param revision - the namespace's new revision.
+         * @mode emit
+         */
+        'settings/document-updated'(ns: SettingsNamespace, revision: number): void;
+    }
+}
+//# sourceMappingURL=types.d.ts.map

package/lib/types/types.js

@@ -0,0 +1,10 @@
+/**
+ * Client-safe type surface of the user-settings seam: the namespace brand, the
+ * commit-origin union, and the seam's Cordis event declarations. Types only —
+ * no runtime code, and nothing here reaches a Host-only symbol, so a Client
+ * compilation face reads exactly the signatures the Host emits.
+ *
+ * @module @deepseek-ai/dsh-settings/types
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-settings",
   "description": "Abstract user-settings seam (ctx.settings) for the DeepSeek Harness",
-  "version": "0.0.1-rc.1",
+  "version": "0.0.1-rc.3",
   "publishConfig": {
     "access": "restricted"
   },
@@ -22,25 +22,30 @@
       "types": "./lib/types/invariant.d.ts",
       "default": "./lib/invariant.js"
     },
+    "./types": {
+      "types": "./lib/types/types.d.ts",
+      "default": "./lib/types/types.js"
+    },
     "./src/*": "./src/*",
     "./package.json": "./package.json"
   },
   "files": [
     "lib/index.js",
     "lib/invariant.js",
+    "lib/types/**/*.js",
     "lib/types/**/*.d.ts"
   ],
   "license": "BSD-3-Clause",
   "peerDependencies": {
-    "@deepseek-ai/dsh-brand": "^0.0.1-rc.1",
-    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.3",
+    "@deepseek-ai/dsh-brand": "^0.0.1-rc.3",
     "@deepseek-ai/cordis": "^4.0.1-rc.1",
     "@deepseek-ai/schemastery": "^3.18.1-rc.1"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-brand": "^0.0.1-rc.1",
-    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
-    "@deepseek-ai/cordis": "^4.0.1-rc.1",
-    "@deepseek-ai/schemastery": "^3.18.1-rc.1"
+    "@deepseek-ai/dsh-brand": "^0.0.1-rc.3",
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.3",
+    "@deepseek-ai/schemastery": "^3.18.1-rc.1",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1"
   }
 }