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

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: 47fa75d13ad607554de1aa51de03557a769e2366

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

@@ -28,6 +28,8 @@
 
 `settings/document-updated (ns, revision)` 在**原始**用户分节发生变化时触发，无论解析值是否随之改变。配置界面需要的是这一个：存入一个与组合 `base` 相同的覆盖值不会改变解析值，却改变了文档的说法（该字段从继承变成了覆盖），也推进了每个已打开编辑器所持有的 revision。监听器的收容方式与 `settings/updated` 相同。
 
+两条声明都住在 client-safe 的 `./types` 子路径出口，与其签名点名的 `SettingsNamespace`、`SettingsUpdateSource` 类型同处一处；包根继续 re-export 这些类型。于是 Host 编译面之外的消费方读到的正是 Host 发射的那一份签名，而不必再写一遍。
+
 ## 模型体验
 
 间接生效：消费插件从各自 namespace 解析影响模型的值（例如默认模型路由）；效果由各消费者自己的文档描述。

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). */
@@ -116,36 +113,6 @@ 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;
-    }
 }
 /**
  * Deep equality over JSON-compatible data (objects, arrays, primitives) — the

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 Settings 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 Settings;
+//# 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.2",
   "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/cordis": "^4.0.1-rc.1",
-    "@deepseek-ai/schemastery": "^3.18.1-rc.1"
+    "@deepseek-ai/dsh-brand": "^0.0.1-rc.2",
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.2",
+    "@deepseek-ai/schemastery": "^3.18.1-rc.1",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-brand": "^0.0.1-rc.1",
-    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-brand": "^0.0.1-rc.2",
     "@deepseek-ai/cordis": "^4.0.1-rc.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.2",
     "@deepseek-ai/schemastery": "^3.18.1-rc.1"
   }
 }