@zfdx123/dsh-hooks-ordering 1.0.4 → 1.0.6

package/client.js

@@ -14,9 +14,11 @@
 //   - the file is a classic script, so it has no import/export: React arrives
 //     through the synchronous `require` handed to the factory.
 //
-// Writes go through `scope.mutate` rather than `scope.set`: the latter is
-// documented for a "scalar field", while our fields are string arrays, and
-// path-addressed ops say exactly what is meant for both save and reset.
+// Writes go through two path-addressed ops rather than a scalar setter: the
+// fields are string arrays, and `{op:'set'|'unset', path}` says exactly what is
+// meant for both save and reset. They are sent to the settings Remote namespace
+// (`ctx.remote.settings.mutate`), which resolves them against the stored section
+// rather than against whatever this page last read.
 //
 // The namespace is `applies: 'restart'`, so the page says so instead of
 // pretending a save took effect immediately.
@@ -102,7 +104,7 @@
         fieldHooks: 'waterfall 钩子（每行一个）',
         fieldSerialHooks: 'serial 钩子（每行一个）',
         fieldLog: '约束 DAG 日志文件（留空即不记录）',
-        note: '改动在重启 dsh 后生效（该命名空间 applies: restart）。清空某字段即回到组合层：目前 base = {hooks} 个 waterfall / {serial} 个 serial 钩子。',
+        note: '改动在重启 dsh 后生效（hooks/serialHooks 的变更需要重新挂载钩子）。清空某字段即回到 schema 默认值。',
         saveFailed: '保存失败：{message}',
         saving: '保存中…',
         save: '保存',
@@ -119,7 +121,7 @@
         fieldHooks: 'Waterfall hooks (one per line)',
         fieldSerialHooks: 'Serial hooks (one per line)',
         fieldLog: 'Constraint DAG log file (leave empty to log nothing)',
-        note: 'Changes take effect after dsh restarts (the namespace is applies: restart). Clearing a field returns it to the composition layer: base = {hooks} waterfall / {serial} serial hooks right now.',
+        note: 'Changes take effect after dsh restarts (editing hooks/serialHooks re-mounts the hook brackets). Clearing a field returns it to the schema default.',
         saveFailed: 'Save failed: {message}',
         saving: 'Saving…',
         save: 'Save',
@@ -344,17 +346,285 @@
         return style
       }
 
+      /**
+       * The name this plugin's settings entry actually has, resolved at runtime
+       * from the descriptors the host returns.
+       *
+       * It CANNOT be a constant. The settings namespace is the **loader entry
+       * id**, which belongs to whoever wrote the row that mounted this plugin,
+       * not to the plugin: the aggregator's `cordis.patch.yml` uses
+       * `dsh-plugin-hooks-ordering`, while this package's own patch uses
+       * `hooks-ordering`. Hardcoding the latter against the former produced
+       *
+       *   no settings entry is named "hooks-ordering" (describe() returned: …, dsh-plugin-hooks-ordering, …)
+       *
+       * and the write path was refused outright:
+       *
+       *   settings/rejected: No configurable plugin entry "hooks-ordering"
+       *
+       * Matching on the descriptor's own `ns` removes the guesswork: whatever id
+       * the mounting row has, this is the entry it produced.
+       */
+      var resolvedNs = null
+
+      /**
+       * Normalise a Remote answer to `{ ok, value }` / `{ ok: false, reason }`.
+       *
+       * The 0.1.7 Remote protocol answers every call with a `RemoteResult`
+       * envelope and the client proxy hands that envelope through as-is, so a
+       * caller that reads fields off the answer directly sees `undefined` while
+       * the wire traffic is healthy. A plain value is accepted too, so this
+       * keeps working if a future runtime unwraps for us.
+       *
+       * @param answer - whatever the Remote call resolved to.
+       * @returns the unwrapped outcome.
+       */
+      function unwrapRemote(answer) {
+        if (answer !== null && typeof answer === 'object' && typeof answer.ok === 'boolean') {
+          if (answer.ok === false) {
+            var failure = answer.error
+            var reason =
+              failure && typeof failure === 'object'
+                ? String(failure.code || 'remote error') + ': ' + String(failure.message || '')
+                : String(failure || 'remote error')
+            return { ok: false, reason: reason }
+          }
+          return { ok: true, value: answer.value }
+        }
+        return { ok: true, value: answer }
+      }
+
+      /**
+       * @param list - descriptor list from `describe()`.
+       * @returns the descriptor for this plugin, or undefined.
+       */
+      function pickEntry(list) {
+        // Fast path: the row used this package's own documented id.
+        var direct = list.find(function (entry) {
+          return entry && entry.ns === NS
+        })
+        if (direct !== undefined) return direct
+        // Otherwise take the entry that was mounting this plugin created.
+        // `dsh-plugin-hooks-ordering` is the shipped aggregator row; the suffix
+        // test also covers a user's own row name.
+        var suffixed = list.filter(function (entry) {
+          return entry && typeof entry.ns === 'string' && entry.ns.slice(-NS.length) === NS
+        })
+        return suffixed.length === 1 ? suffixed[0] : undefined
+      }
+
       // ── the settings page ──────────────────────────────────────────────────
+
+      /**
+       * Interpret the setting page's view of one entry.
+       *
+       * Three inputs can describe it: an already-assembled view (`{status,
+       * value, ...}`), a raw settings descriptor (`{ns, value, revision}`), or
+       * nothing at all.
+       *
+       * @param raw - one of the shapes above, or null/undefined.
+       * @returns a view this page can render, or `null` when there is no entry.
+       */
+      function normaliseSnapshot(raw) {
+        if (raw === null || raw === undefined) return null
+        var writable = raw.writable !== false
+        if (raw.status === 'unavailable' || raw.available === false) {
+          return {
+            status: 'unavailable',
+            available: false,
+            writable: false,
+            revision: undefined,
+            value: null,
+            base: {},
+            reason: raw.reason,
+          }
+        }
+        return {
+          status: 'ready',
+          available: true,
+          writable: writable,
+          revision: raw.revision,
+          value: raw.value || null,
+          base: raw.base || {},
+        }
+      }
+
+      /**
+       * Adapt the 0.1.7 `ctx.remote.settings` namespace to the snapshot surface
+       * this page renders from.
+       *
+       * 0.1.6 exposed a `settingsScope` service that answered snapshots
+       * synchronously. 0.1.7 removed it: a page now talks to the settings
+       * Remote, whose `describe()`/`mutate()` are async and keyed by the
+       * profile entry id. This adapter resolves the descriptor once, re-resolves
+       * it on the host's `settings/document-updated` notification.
+       *
+       * @param ctx - the plugin context (provides `remote`).
+       */
+      function createSettingsSource(ctx) {
+        var remote = ctx && ctx.remote && ctx.remote.settings
+        /**
+         * The name this plugin's settings entry actually has is resolved at
+         * runtime by {@link pickEntry} into the module-level `resolvedNs`; see
+         * the note there for why it cannot be a constant.
+         */
+
+        /**
+         * Why the form has no data. Kept as a concrete, user-visible string:
+         * "not available" on its own made a wiring fault indistinguishable from
+         * a not-yet-mounted host half, and that cost a lot of blind debugging.
+         */
+        function unavailableBecause(reason) {
+          return {
+            status: 'unavailable',
+            available: false,
+            writable: false,
+            value: null,
+            revision: undefined,
+            reason: reason,
+          }
+        }
+
+        /**
+         * @returns a promise of the current descriptor view, or of an
+         * `unavailable` view carrying the concrete reason.
+         */
+        function read() {
+          if (!ctx || !ctx.remote) {
+            return Promise.resolve(unavailableBecause('ctx.remote is not injected'))
+          }
+          if (!remote) {
+            return Promise.resolve(unavailableBecause('the ctx.remote.settings namespace is absent'))
+          }
+          if (typeof remote.describe !== 'function') {
+            return Promise.resolve(unavailableBecause('ctx.remote.settings.describe is not a function'))
+          }
+          return Promise.resolve()
+            .then(function () {
+              return remote.describe()
+            })
+            .then(function (answer) {
+              // A Remote call answers with a `RemoteResult` envelope
+              // (`{ok:true, value}` / `{ok:false, error}`) and the client proxy
+              // does NOT unwrap it: reading `answer.namespaces` directly got
+              // `undefined`, which surfaced as the misleading
+              // "describe() returned no namespaces array" while the network
+              // exchange was perfectly healthy (ok:true, 20 namespaces).
+              var result = unwrapRemote(answer)
+              if (result.ok === false) {
+                return unavailableBecause('describe() failed: ' + result.reason)
+              }
+              var value = result.value
+              if (value === null || value === undefined) {
+                return unavailableBecause('describe() returned no value')
+              }
+              var list = Array.isArray(value.namespaces) ? value.namespaces : null
+              if (list === null) {
+                return unavailableBecause(
+                  'describe() value has no namespaces array (keys: ' + Object.keys(value).join(', ') + ')',
+                )
+              }
+              var found = pickEntry(list)
+              if (found === undefined) {
+                var seen = list
+                  .map(function (entry) {
+                    return entry && entry.ns
+                  })
+                  .filter(Boolean)
+                  .join(', ')
+                return unavailableBecause(
+                  'no settings entry for this plugin (looked for "' +
+                    NS +
+                    '"; describe() returned: ' +
+                    (seen || 'nothing') +
+                    ')',
+                )
+              }
+              resolvedNs = found.ns
+              return {
+                status: 'ready',
+                available: true,
+                // The provider's writability gates the whole form; a read-only
+                // deployment still shows the effective values.
+                writable: answer.writable !== false,
+                value: found.value || null,
+                revision: found.revision,
+                base: {},
+              }
+            }, function (failure) {
+              return unavailableBecause(
+                'describe() failed: ' + String((failure && failure.message) || failure),
+              )
+            })
+        }
+
+        return {
+          available: remote !== undefined && typeof remote.describe === 'function',
+          /**
+           * @param ops - `SettingsPathOp` list, e.g. `{op:'set', path, value}`.
+           * @returns a promise resolving to the refreshed view.
+           */
+          mutate: function (ops) {
+            if (!remote || typeof remote.mutate !== 'function') {
+              return Promise.reject(new Error('settings remote is unavailable in this deployment'))
+            }
+            // The revision is read fresh immediately before the write so a page
+            // left open across another edit reports a conflict instead of
+            // silently overwriting it. `read()` also refreshes `resolvedNs`.
+            return read().then(function (snap) {
+              if (!snap.available) {
+                throw new Error(snap.reason || 'this plugin has no settings entry in the active profile')
+              }
+              if (resolvedNs === null) {
+                throw new Error('this plugin did not resolve its settings entry id')
+              }
+              // The write answers with a RemoteResult envelope as well; unwrap
+              // it so a refusal surfaces as a real message instead of looking
+              // like a successful save.
+              return remote.mutate(resolvedNs, ops, snap.revision).then(function (answer) {
+                var result = unwrapRemote(answer)
+                if (result.ok === false) throw new Error(result.reason)
+                return result.value
+              })
+            })
+          },
+          /**
+           * @param listener - called after every host-side change to this entry.
+           * @returns an unsubscribe function.
+           */
+          subscribe: function (listener) {
+            // The event surface lives on `ctx.remote` itself, not on the
+            // namespace: a shipped settings page listens as
+            // `ctx.remote.$on('credentials/reference-updated', …)` while
+            // declaring `inject: ['remote', 'remote.<ns>']`.
+            var events = ctx && ctx.remote
+            if (!events || typeof events.$on !== 'function') return function () {}
+            try {
+              return events.$on('settings/document-updated', function (ns) {
+                // Match the resolved entry id, not the package-relative name.
+                if (ns === undefined || ns === resolvedNs || ns === NS) listener()
+              })
+            } catch (error) {
+              // A missing gateway listener must not take the page down.
+              return function () {}
+            }
+          },
+          read: read,
+        }
+      }
+
       /** @param props - the section owner props plus the plugin context. */
       function SettingsSection(props) {
         var ctx = props.ctx
-        var scopeRef = useRef(null)
-        if (scopeRef.current === null) scopeRef.current = ctx.settingsScope.bind({ namespace: NS })
-        var scope = scopeRef.current
-
-        var snapState = useState(function () {
-          return scope.getSnapshot()
-        })
+        // A host that can answer synchronously may hand the view over directly;
+        // against the real shell this is undefined and the page reads the
+        // settings Remote instead.
+        var seed = normaliseSnapshot(props.settingsSnapshot)
+        var sourceRef = useRef(null)
+        if (sourceRef.current === null) sourceRef.current = createSettingsSource(ctx)
+        var source = sourceRef.current
+
+        var snapState = useState(seed)
         var snap = snapState[0]
         var setSnap = snapState[1]
 
@@ -372,23 +642,39 @@
 
         useEffect(
           function () {
-            return scope.subscribe(function () {
-              setSnap(scope.getSnapshot())
-            })
+            var alive = true
+            function refresh() {
+              source.read().then(
+                function (next) {
+                  if (alive) setSnap(next)
+                },
+                function (failure) {
+                  if (alive) setError(String((failure && failure.message) || failure))
+                },
+              )
+            }
+            // A supplied snapshot is already the current view; only the Remote
+            // path needs the initial round trip.
+            if (seed === null) refresh()
+            var off = source.subscribe(refresh)
+            return function () {
+              alive = false
+              off()
+            }
           },
-          [scope],
+          [source],
         )
 
         // Re-seed the editor from every accepted snapshot, but never over an
         // unsaved edit: the user's typing outranks a background refresh.
-        var revision = snap.revision
+        var revision = snap ? snap.revision : undefined
         useEffect(
           function () {
-            if (dirtyRef.current) return
+            if (dirtyRef.current || snap === null) return
             var value = snap.value || {}
             setDraft({ hooks: toLines(value.hooks), serialHooks: toLines(value.serialHooks), log: value.log || '' })
           },
-          [revision, snap.value],
+          [revision, snap],
         )
 
         /** @param fieldName - settings field to edit; @param next - its new textarea content. */
@@ -417,7 +703,7 @@
         }
 
         function save() {
-          var value = snap.value || {}
+          var value = (snap && snap.value) || {}
           var ops = []
           if (!sameLines(value.hooks, draft.hooks)) {
             ops.push({ op: 'set', path: ['hooks'], value: fromLines(draft.hooks) })
@@ -429,13 +715,13 @@
             ops.push({ op: 'set', path: ['log'], value: draft.log })
           }
           if (ops.length === 0) return
-          settle(scope.mutate(ops))
+          settle(source.mutate(ops))
         }
 
-        /** Send every field back to the composition layer (`base`). */
+        /** Send every field back to the composition default (the schema default). */
         function reset() {
           settle(
-            scope.mutate([
+            source.mutate([
               { op: 'unset', path: ['hooks'] },
               { op: 'unset', path: ['serialHooks'] },
               { op: 'unset', path: ['log'] },
@@ -443,7 +729,9 @@
           )
         }
 
-        var writable = snap.writable
+        // Unknown until the descriptor arrives; a read-only provider disables
+        // the whole form rather than letting the user type into a dead editor.
+        var writable = snap !== null && snap.writable
 
         /**
          * @param label - field caption.
@@ -496,37 +784,44 @@
           )
         }
 
-        var dirty =
-          !sameLines(snap.value && snap.value.hooks, draft.hooks) ||
-          !sameLines(snap.value && snap.value.serialHooks, draft.serialHooks) ||
-          ((snap.value && snap.value.log) || '') !== draft.log
+        var current = (snap && snap.value) || {}
 
-        var base = snap.base || {}
+        var dirty =
+          !sameLines(current.hooks, draft.hooks) ||
+          !sameLines(current.serialHooks, draft.serialHooks) ||
+          (current.log || '') !== draft.log
+
+        // Three states: the descriptor has not arrived yet, this deployment has
+        // no settings entry for the plugin, or the form is ready.
+        var body
+        if (snap === null) {
+          body = e('p', null, t('loading'))
+        } else if (!snap.available) {
+          // Print the concrete cause next to the headline: the generic sentence
+          // alone could not tell a wiring fault from an unmounted host half.
+          body = e(
+            'div',
+            null,
+            e('p', null, t('unavailable')),
+            snap.reason ? e('p', { className: 'ho-note' }, String(snap.reason)) : null,
+          )
+        } else {
+          body = e(
+            'div',
+            { className: CLASS },
+            renderListField(t('fieldHooks'), 'hooks', draft.hooks, 8),
+            renderListField(t('fieldSerialHooks'), 'serialHooks', draft.serialHooks, 3),
+            renderLineField(t('fieldLog'), 'log', draft.log),
+          )
+        }
 
         return e(
           'div',
           { className: CLASS },
           e('h3', null, t('nav')),
           e('p', null, t('intro')),
-          snap.status === 'loading'
-            ? e('p', null, t('loading'))
-            : snap.status === 'unavailable'
-              ? e('p', null, t('unavailable'))
-              : e(
-                  'div',
-                  { className: CLASS },
-                  renderListField(t('fieldHooks'), 'hooks', draft.hooks, 8),
-                  renderListField(t('fieldSerialHooks'), 'serialHooks', draft.serialHooks, 3),
-                  renderLineField(t('fieldLog'), 'log', draft.log),
-                ),
-          e(
-            'p',
-            { className: 'ho-note' },
-            t('note', {
-              hooks: String(Array.isArray(base.hooks) ? base.hooks.length : 0),
-              serial: String(Array.isArray(base.serialHooks) ? base.serialHooks.length : 0),
-            }),
-          ),
+          body,
+          e('p', { className: 'ho-note' }, t('note')),
           error ? saveFailedStatus(error) : null,
           e(
             'div',
@@ -546,7 +841,7 @@
       }
 
       /**
-       * @param message - the failure text reported by `scope.mutate`.
+       * @param message - the failure text reported by the settings write.
        * @returns the save-failure status: the shell's StateDot + Tag when the kit is
        * there, the plugin's own chip when it is not.
        */
@@ -560,11 +855,12 @@
       }
 
       // ── plugin ─────────────────────────────────────────────────────────────
-      // 'locale' is a required service: without the locale plugin in the
-      // composition this plugin does not activate at all, rather than
-      // registering a page with no copy. bindLocale still degrades for a
-      // partial context (see above).
-      var inject = ['slots', 'settingsScope', 'locale']
+      // 'remote.settings' is a required service: the settings Remote namespace
+      // is how a 0.1.7 page reads and writes its entry. Without it the page is
+      // not registered at all, rather than rendering an editor that cannot save.
+      // 0.1.6 exposed `settingsScope` instead; that service no longer exists, so
+      // naming it here would leave this plugin permanently pending.
+      var inject = ['slots', 'remote', 'remote.settings', 'locale']
 
       /** @param ctx - the client plugin context. */
       function apply(ctx) {
@@ -599,6 +895,8 @@
       exports.apply = apply
       exports.inject = inject
       exports.NS = NS
+      exports.pickEntry = pickEntry
+      exports.unwrapRemote = unwrapRemote
       exports.CLASS = CLASS
       exports.CSS = CSS
       exports.ZH = zh

package/lib/index.d.ts

@@ -4,6 +4,7 @@ import { a as Phase, i as HookOrderingLogConfig, n as HookControlError } from ".
 import { n as HookOrdering, r as HookOrderingConfig, t as HookEntry } from "./waterfall-_5HkptkS.js";
 import { n as SerialHookOrdering, r as SerialHookOrderingConfig, t as SerialHookEntry } from "./serial-D8ZJCBKL.js";
 import { Context } from "@deepseek-ai/cordis";
+import * as _deepseek_ai_schemastery0 from "@deepseek-ai/schemastery";
 
 //#region src/dsh.d.ts
 
@@ -75,8 +76,23 @@ declare const DEFAULT_WATERFALL_HOOKS: readonly string[];
 declare const DEFAULT_SYNC_RETURN_HOOKS: readonly string[];
 /** The dsh serial hook controlled by default. */
 declare const DEFAULT_SERIAL_HOOKS: readonly string[];
-/** Plugin config. */
-interface Config {
+/**
+ * This plugin's Cordis Config schema.
+ *
+ * Since DSH 0.1.7 this *is* the Settings page: the fields are `.volatile()`, so
+ * the settings service projects exactly them into an editable form and commits
+ * an edit into the live reference rather than remounting the plugin. The
+ * defaults are the real hook sets below, so an entry whose `config:` key is
+ * empty resolves to them.
+ */
+declare const Config: _deepseek_ai_schemastery0.default;
+/**
+ * Plugin config as a plain value.
+ *
+ * A loader-resolved config carries the volatile fields as references instead of
+ * plain arrays, so this describes the *plain* shape callers and tests construct.
+ */
+interface ConfigShape {
   /**
    * Waterfall hooks to control. Defaults to {@link DEFAULT_WATERFALL_HOOKS}.
    * Pass `[]` to disable the waterfall service entirely.
@@ -92,10 +108,16 @@ interface Config {
    * therefore refuse participants. Defaults to {@link DEFAULT_SYNC_RETURN_HOOKS}.
    * Pass `[]` — or a set without a given hook — to opt in to ordering it, once
    * the host awaits that dispatch.
+   *
+   * Composition-only: this describes the HOST's dispatch, not a user
+   * preference, so it is intentionally not a field of {@link Config} and never
+   * appears on the Settings page.
    */
   syncReturnHooks?: readonly string[];
   /** When set, the constraint DAG (JSON) is logged to this file on every change. */
   log?: string;
+  /** Overrides the loader entry id; only non-loader harnesses need it. */
+  entryId?: string;
 }
 /**
  * Mount {@link HookOrdering} and/or {@link SerialHookOrdering} and control the
@@ -107,15 +129,23 @@ interface Config {
  * package's own `cordis.patch.yml` is written exactly that way — every option
  * commented out — so a null config must mean "all defaults", not a crash.
  *
- * The row is the *composition* layer of the settings namespace: the Settings
- * page edits a user layer over it, and a namespace the user has not touched
- * resolves back to this row (or to the built-in defaults). Without a settings
- * provider — plain Cordis — the row is the whole answer.
+ * Since DSH 0.1.7 there is no second "user layer": the row's `config` IS the
+ * editable settings, because Cordis validates it against {@link Config} and the
+ * settings service projects that schema. A volatile field arrives here as a
+ * reference rather than a plain array, which is why every read goes through
+ * {@link readSetting} — that also keeps a plain Cordis mount (and an older
+ * harness) working, where the fields are plain values.
+ *
+ * `hooks`/`serialHooks` are read once, at apply time. An edit from the Settings
+ * page therefore needs a plugin reload to take effect — the same restart
+ * semantics this namespace declared before 0.1.7 (`applies: 'restart'`), since
+ * changing the controlled set means adding or removing live hook brackets and
+ * the coordinator has no public "release one hook" operation.
  *
  * @param ctx - the Cordis context.
  * @param config - which hooks to control and an optional DAG `log` file; null means all defaults.
  */
-declare function apply(ctx: Context, config?: Config | null): void;
+declare function apply(ctx: Context, config?: ConfigShape | null): void;
 //#endregion
-export { type Config, DEFAULT_SERIAL_HOOKS, DEFAULT_SYNC_RETURN_HOOKS, DEFAULT_WATERFALL_HOOKS, type Dag, type DagEdge, type DagSection, type DagSectionGraph, DuplicateNameError, HookControlError, type HookEntry, HookOrdering, type HookOrderingConfig, type HookOrderingLogConfig, type Orderable, OrderingCycleError, type Phase, type SerialHookEntry, SerialHookOrdering, type SerialHookOrderingConfig, apply, buildDag, inject, name, topoSort };
+export { Config, type ConfigShape, DEFAULT_SERIAL_HOOKS, DEFAULT_SYNC_RETURN_HOOKS, DEFAULT_WATERFALL_HOOKS, type Dag, type DagEdge, type DagSection, type DagSectionGraph, DuplicateNameError, HookControlError, type HookEntry, HookOrdering, type HookOrderingConfig, type HookOrderingLogConfig, type Orderable, OrderingCycleError, type Phase, type SerialHookEntry, SerialHookOrdering, type SerialHookOrderingConfig, apply, buildDag, inject, name, topoSort };
 //# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../src/dsh.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;cAuBa,IAAA;;;;;;;;;;;;;;;;;;cAmBA;;;;;;;;;;;;;;;;;;;cAoBA;;;;;;;;;;;;;;;;;;;;;;;;;;;cAuCA;;cAOA;;UAGI,MAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAwCD,KAAA,MAAW,kBAAiB"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/dsh.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;cAuBa,IAAA;;;;;;;;;;;;;;;;;;cAmBA;;;;;;;;;;;;;;;;;;;cAoBA;;;;;;;;;;;;;;;;;;;;;;;;;;;cAuCA;;cAOA;;;;;;;;;;cAWA,QAA2E,yBAAA,CAArE;;;;;;;UAWF,WAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAsDD,KAAA,MAAW,kBAAiB"}

package/lib/index.js

@@ -6,51 +6,43 @@ import { t as SerialHookOrdering } from "./serial-Cu7usHjI.js";
 import Schema from "@deepseek-ai/schemastery";
 
 //#region src/settings.ts
-/** Namespace name — dsh requires a lowercase hyphenated identifier. */
-const SETTINGS_NS = "hooks-ordering";
 /**
-* Schema for {@link SETTINGS_NS}.
+* Build the Config schema from the caller's default hook lists.
 *
-* Every field defaults to its "off" value. The *meaningful* defaults — the
-* hooks this plugin controls when nothing overrides them — are supplied by the
-* caller as the composition `base` layer (see {@link resolveSettings}), so a
-* namespace the user has never touched still resolves to a complete object.
+* Every field is `.volatile()`, so every field is user-editable from the
+* Settings page and an edit is committed into the live reference instead of
+* remounting the plugin. `log` is volatile too, because a non-volatile field
+* would not appear in the form at all.
+*
+* @param defaultWaterfallHooks - waterfall hooks controlled when unconfigured.
+* @param defaultSerialHooks - serial hooks controlled when unconfigured.
+* @returns a callable schemastery schema, which is what Cordis resolves through.
 */
-const HooksOrderingSettingsSchema = Schema.object({
-	hooks: Schema.array(Schema.string()).default([]),
-	serialHooks: Schema.array(Schema.string()).default([]),
-	log: Schema.string().default("")
-});
+function hooksOrderingConfig(defaultWaterfallHooks, defaultSerialHooks) {
+	return Schema.object({
+		hooks: Schema.array(Schema.string()).default([...defaultWaterfallHooks]).volatile(),
+		serialHooks: Schema.array(Schema.string()).default([...defaultSerialHooks]).volatile(),
+		log: Schema.string().default("").volatile()
+	});
+}
 /**
-* Register the settings namespace and read its resolved value.
-*
-* `base` is the composition layer — what the row (or the built-in defaults)
-* asks for — so the user layer edits *over* it and a reset returns to it rather
-* than to an empty form.
-*
-* `applies: 'restart'` is deliberate. Changing `hooks`/`serialHooks` means
-* installing or removing bracket listeners on live hooks, and the coordinator
-* has no public "release one hook" operation; a restart applies the change
-* cleanly instead of re-wiring the dispatch chain mid-flight.
-*
-* @param ctx - the Cordis context to look the service up on.
-* @param base - the composition layer to register as the base value.
-* @returns the resolved settings, or `undefined` when the provider is missing
-* (which `inject: ['settings']` rules out in dsh — the guard is defensive) or
-* registration failed — the caller then uses `base`.
+* Read one resolved field, unwrapping a volatile reference when the loader
+* supplied one and falling back to a default when the field is absent.
+*
+* A loader-provided Config carries volatile fields as references (`.get()`);
+* a plain Cordis mount, or an older harness, passes plain values. Both must
+* work, and an absent field must not be confused with an explicit empty one.
+*
+* @param config - the resolved plugin config (possibly `null`).
+* @param field - the field to read.
+* @param fallback - value to use when the field is absent.
+* @returns the field's current value, or `fallback`.
 */
-function resolveSettings(ctx, base) {
-	const settings = ctx.get("settings");
-	if (settings === void 0) return void 0;
-	try {
-		return settings.register(SETTINGS_NS, HooksOrderingSettingsSchema, {
-			base,
-			applies: "restart"
-		}).get();
-	} catch (error) {
-		console.warn("hooks-ordering: settings registration failed; falling back to the composition config:", error);
-		return;
-	}
+function readSetting(config, field, fallback) {
+	const value = config?.[field];
+	if (value === void 0 || value === null) return fallback;
+	if (typeof value.get === "function") return value.get() ?? fallback;
+	return value;
 }
 
 //#endregion
@@ -139,6 +131,16 @@ const DEFAULT_SYNC_RETURN_HOOKS = [
 /** The dsh serial hook controlled by default. */
 const DEFAULT_SERIAL_HOOKS = ["agent/turn-stopping"];
 /**
+* This plugin's Cordis Config schema.
+*
+* Since DSH 0.1.7 this *is* the Settings page: the fields are `.volatile()`, so
+* the settings service projects exactly them into an editable form and commits
+* an edit into the live reference rather than remounting the plugin. The
+* defaults are the real hook sets below, so an entry whose `config:` key is
+* empty resolves to them.
+*/
+const Config = hooksOrderingConfig(DEFAULT_WATERFALL_HOOKS, DEFAULT_SERIAL_HOOKS);
+/**
 * Mount {@link HookOrdering} and/or {@link SerialHookOrdering} and control the
 * configured hooks once the services are active.
 *
@@ -148,22 +150,29 @@ const DEFAULT_SERIAL_HOOKS = ["agent/turn-stopping"];
 * package's own `cordis.patch.yml` is written exactly that way — every option
 * commented out — so a null config must mean "all defaults", not a crash.
 *
-* The row is the *composition* layer of the settings namespace: the Settings
-* page edits a user layer over it, and a namespace the user has not touched
-* resolves back to this row (or to the built-in defaults). Without a settings
-* provider — plain Cordis — the row is the whole answer.
+* Since DSH 0.1.7 there is no second "user layer": the row's `config` IS the
+* editable settings, because Cordis validates it against {@link Config} and the
+* settings service projects that schema. A volatile field arrives here as a
+* reference rather than a plain array, which is why every read goes through
+* {@link readSetting} — that also keeps a plain Cordis mount (and an older
+* harness) working, where the fields are plain values.
+*
+* `hooks`/`serialHooks` are read once, at apply time. An edit from the Settings
+* page therefore needs a plugin reload to take effect — the same restart
+* semantics this namespace declared before 0.1.7 (`applies: 'restart'`), since
+* changing the controlled set means adding or removing live hook brackets and
+* the coordinator has no public "release one hook" operation.
 *
 * @param ctx - the Cordis context.
 * @param config - which hooks to control and an optional DAG `log` file; null means all defaults.
 */
 function apply(ctx, config = {}) {
 	const row = config ?? {};
-	const base = {
-		hooks: row.hooks ?? DEFAULT_WATERFALL_HOOKS,
-		serialHooks: row.serialHooks ?? DEFAULT_SERIAL_HOOKS,
-		log: row.log ?? ""
+	const { hooks, serialHooks, log } = {
+		hooks: readSetting(row, "hooks", DEFAULT_WATERFALL_HOOKS),
+		serialHooks: readSetting(row, "serialHooks", DEFAULT_SERIAL_HOOKS),
+		log: readSetting(row, "log", "")
 	};
-	const { hooks, serialHooks, log } = resolveSettings(ctx, base) ?? base;
 	const serviceConfig = log === "" ? {} : { log };
 	const syncReturnHooks = row.syncReturnHooks ?? DEFAULT_SYNC_RETURN_HOOKS;
 	const deps = [];
@@ -186,5 +195,5 @@ function apply(ctx, config = {}) {
 }
 
 //#endregion
-export { DEFAULT_SERIAL_HOOKS, DEFAULT_SYNC_RETURN_HOOKS, DEFAULT_WATERFALL_HOOKS, DuplicateNameError, HookControlError, HookOrdering, OrderingCycleError, SerialHookOrdering, apply, buildDag, inject, name, topoSort };
+export { Config, DEFAULT_SERIAL_HOOKS, DEFAULT_SYNC_RETURN_HOOKS, DEFAULT_WATERFALL_HOOKS, DuplicateNameError, HookControlError, HookOrdering, OrderingCycleError, SerialHookOrdering, apply, buildDag, inject, name, topoSort };
 //# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":["DEFAULT_WATERFALL_HOOKS: readonly string[]","DEFAULT_SYNC_RETURN_HOOKS: readonly string[]","DEFAULT_SERIAL_HOOKS: readonly string[]","base: HooksOrderingSettings","deps: string[]","HookOrdering"],"sources":["../src/settings.ts","../src/dsh.ts"],"sourcesContent":["/**\n * The dsh settings namespace for this plugin: the three fields a user can edit\n * from the Settings page instead of a `cordis.patch.yml` row.\n *\n * Two constraints are load-bearing and easy to get wrong:\n *\n * - The schema handed to `settings.register` must be a **callable** schemastery\n *   schema. dsh resolves a namespace by calling `schema(merged)` and reads\n *   `schema.toJSON()` for the form, so a plain object throws\n *   `schema is not a function` — during plugin assembly, which takes the whole\n *   profile down rather than failing one form.\n * - That is also why registration is wrapped in `try/catch` here: an optional\n *   settings form must never be able to stop the harness from booting.\n *\n * @module dsh-hooks-ordering/settings\n */\n\nimport type { Context } from '@deepseek-ai/cordis'\nimport Schema from '@deepseek-ai/schemastery'\n\n/** The three fields this plugin exposes for configuration. */\nexport interface HooksOrderingSettings {\n  /** Waterfall hooks to control; `[]` disables the waterfall service entirely. */\n  readonly hooks: readonly string[]\n  /** Serial hooks to control; `[]` disables the serial service entirely. */\n  readonly serialHooks: readonly string[]\n  /** Constraint-DAG log file; the empty string means \"do not log\". */\n  readonly log: string\n}\n\n/** Namespace name — dsh requires a lowercase hyphenated identifier. */\nexport const SETTINGS_NS = 'hooks-ordering'\n\n/**\n * Schema for {@link SETTINGS_NS}.\n *\n * Every field defaults to its \"off\" value. The *meaningful* defaults — the\n * hooks this plugin controls when nothing overrides them — are supplied by the\n * caller as the composition `base` layer (see {@link resolveSettings}), so a\n * namespace the user has never touched still resolves to a complete object.\n */\nexport const HooksOrderingSettingsSchema = Schema.object({\n  hooks: Schema.array(Schema.string()).default([]),\n  serialHooks: Schema.array(Schema.string()).default([]),\n  log: Schema.string().default(''),\n})\n\n/**\n * The slice of dsh's `settings` service this plugin uses.\n *\n * Structural rather than imported from `@deepseek-ai/dsh-settings`: it describes\n * exactly the contract this plugin relies on without adding a build-time\n * dependency on a dsh package, whose internals are still 0.1.x-rc.\n */\nexport interface SettingsServiceLike {\n  /**\n   * @param ns - the namespace to register; must be a lowercase hyphenated identifier.\n   * @param schema - a callable schemastery schema, not a plain object.\n   * @param options - `base` is the composition layer, `applies` says whether an\n   * edit takes effect live or needs a restart.\n   * @returns a scope whose `get()` is the resolved value (schema defaults, then `base`, then the user layer).\n   */\n  register(\n    ns: string,\n    schema: unknown,\n    options?: { readonly base?: unknown; readonly applies?: 'live' | 'restart' },\n  ): { get(): HooksOrderingSettings }\n}\n\n/**\n * Register the settings namespace and read its resolved value.\n *\n * `base` is the composition layer — what the row (or the built-in defaults)\n * asks for — so the user layer edits *over* it and a reset returns to it rather\n * than to an empty form.\n *\n * `applies: 'restart'` is deliberate. Changing `hooks`/`serialHooks` means\n * installing or removing bracket listeners on live hooks, and the coordinator\n * has no public \"release one hook\" operation; a restart applies the change\n * cleanly instead of re-wiring the dispatch chain mid-flight.\n *\n * @param ctx - the Cordis context to look the service up on.\n * @param base - the composition layer to register as the base value.\n * @returns the resolved settings, or `undefined` when the provider is missing\n * (which `inject: ['settings']` rules out in dsh — the guard is defensive) or\n * registration failed — the caller then uses `base`.\n */\nexport function resolveSettings(ctx: Context, base: HooksOrderingSettings): HooksOrderingSettings | undefined {\n  const settings = ctx.get('settings') as SettingsServiceLike | undefined\n  if (settings === undefined) return undefined\n  try {\n    return settings.register(SETTINGS_NS, HooksOrderingSettingsSchema, { base, applies: 'restart' }).get()\n  } catch (error) {\n    console.warn('hooks-ordering: settings registration failed; falling back to the composition config:', error)\n    return undefined\n  }\n}\n","/**\n * The DeepSeek-Harness layer: a dsh plugin that mounts the ordering services\n * and takes control of the real dsh hooks that multiple independent packages\n * contribute to, so a profile can opt into deterministic ordering with one row.\n *\n * dsh (deepseek-harness) ships waterfall hooks such as `agent/pre-step`\n * (subscribed by a dozen+ independent packages), `tools/post-execute`,\n * `llm/stream`, and `system-prompt/assemble`, plus the serial hook\n * `agent/turn-stopping`. Their relative listener order is load-bearing yet\n * today decided only by binary `prepend` and registration timing. This plugin\n * controls those hooks up front; controlling an empty hook is a transparent\n * pass-through, so nothing changes until participants register with\n * `before`/`after`.\n *\n * @module dsh-hooks-ordering/dsh\n */\n\nimport type { Context } from '@deepseek-ai/cordis'\nimport HookOrdering from './waterfall.ts'\nimport { SerialHookOrdering } from './serial.ts'\nimport { type HooksOrderingSettings, resolveSettings } from './settings.ts'\n\n/** Cordis plugin name used by loader diagnostics. */\nexport const name = 'hooks-ordering'\n\n/**\n * `settings` is a **hard** dependency, and it has to be declared rather than\n * probed.\n *\n * cordis activates a plugin as soon as the services it declares exist, and\n * `ctx.get('settings')` reads the service store *without* creating that\n * requirement. Without this line the dsh layer loads in the first wave — before\n * the host has provided `settings` — the probe returns `undefined`, and the\n * settings namespace is never registered. Silently: no form, no error.\n *\n * Declaring it makes cordis wait, which also lands this plugin's prepended\n * brackets later in the boot, exactly where the ordering guarantee wants them.\n *\n * This entry targets dsh only — the hook names below are dsh's, and dsh always\n * provides `settings`, so the dependency costs nothing here. `/waterfall` and\n * `/serial` are the entries that carry no host-service requirement.\n */\nexport const inject = ['settings']\n\n/**\n * The dsh waterfall hooks this plugin controls by default — the ones multiple\n * independent packages contribute to, where relative order matters. Controlling\n * a hook with no registered participants is a no-op pass-through.\n *\n * Every name here was checked against the events dsh actually declares: each is\n * a `@mode waterfall` event in the installed build, and each is dispatched with\n * `await`, so the caller already handles a Promise and the bracket's async\n * phases cannot change the hook's return type. `tools/code-dispatch-log` used\n * to sit in this list and no dsh package declares it at all — controlling a\n * name nothing dispatches \"succeeds\" and then does nothing forever, which is\n * exactly the dead configuration this list must not carry.\n *\n * The other admission rule is {@link DEFAULT_SYNC_RETURN_HOOKS}: a hook whose\n * value the caller consumes without awaiting cannot carry ordered participants,\n * so controlling it by default would install a bracket nothing may ever\n * register into — the same dead configuration by a different route.\n */\nexport const DEFAULT_WATERFALL_HOOKS: readonly string[] = [\n  'agent/pre-step',\n  'agent/request',\n  'agent/request-error',\n  'system-prompt/assemble',\n  'tools/pre-execute',\n  'tools/execute',\n  'tools/post-execute',\n  'fs/write-intent',\n  'fs/edit-intent',\n  'approval/request',\n]\n\n/**\n * dsh hooks whose dispatch return value is consumed by the caller without\n * awaiting, and which therefore cannot carry ordered participants. Verified\n * against the installed build:\n *\n * - `llm/stream` — `dsh-llm` dispatches it as\n *   `return this.ctx.waterfall(this, \"llm/stream\", options, …)` (no await), and\n *   `dsh-session-title-llm` iterates the result with\n *   `for await (const chunk of ctx.llm.stream(options))`. A Promise there throws\n *   \"not async iterable\". It is a genuine multi-contributor hook (dsh-agent-loop,\n *   dsh-llm's own invariant, dsh-session-checkpoint-policy, dsh-session-title),\n *   so it is a real loss — but ordering it requires dsh to await the dispatch,\n *   not a plugin-side workaround.\n * - `session-telemetry/record` — `dsh-session-telemetry` returns the record\n *   straight out of the waterfall and hands it to the backend, so a Promise\n *   would be emitted as a record: silent corruption, no error anywhere.\n * - `compaction/summary-error` — `dsh-compaction-basic` dispatches it as\n *   `recover: (…) => this.ctx.waterfall(this, \"compaction/summary-error\", …, () => false)`\n *   (no await) and consumes the boolean synchronously in\n *   `if (!dependencies.recover(error, agent, prepared.shadowedSeqs, signal)) throw error`.\n *   A Promise is always truthy, so `!recover(…)` is always false and every\n *   summarizer failure is swallowed instead of rethrown — the compaction then\n *   proceeds as if recovery had succeeded.\n *\n * Override per profile with `syncReturnHooks` once the host awaits one of them.\n */\nexport const DEFAULT_SYNC_RETURN_HOOKS: readonly string[] = [\n  'llm/stream',\n  'session-telemetry/record',\n  'compaction/summary-error',\n]\n\n/** The dsh serial hook controlled by default. */\nexport const DEFAULT_SERIAL_HOOKS: readonly string[] = ['agent/turn-stopping']\n\n/** Plugin config. */\nexport interface Config {\n  /**\n   * Waterfall hooks to control. Defaults to {@link DEFAULT_WATERFALL_HOOKS}.\n   * Pass `[]` to disable the waterfall service entirely.\n   */\n  hooks?: readonly string[]\n  /**\n   * Serial hooks to control. Defaults to {@link DEFAULT_SERIAL_HOOKS}.\n   * Pass `[]` to disable the serial service entirely.\n   */\n  serialHooks?: readonly string[]\n  /**\n   * Hooks whose return value the host consumes without awaiting, and which must\n   * therefore refuse participants. Defaults to {@link DEFAULT_SYNC_RETURN_HOOKS}.\n   * Pass `[]` — or a set without a given hook — to opt in to ordering it, once\n   * the host awaits that dispatch.\n   */\n  syncReturnHooks?: readonly string[]\n  /** When set, the constraint DAG (JSON) is logged to this file on every change. */\n  log?: string\n}\n\n/**\n * Mount {@link HookOrdering} and/or {@link SerialHookOrdering} and control the\n * configured hooks once the services are active.\n *\n * `config` may be `null`, and that is the ordinary case rather than an edge\n * case: a loader row whose `config:` key is followed only by comments parses as\n * YAML null, and a default parameter covers `undefined` but not `null`. This\n * package's own `cordis.patch.yml` is written exactly that way — every option\n * commented out — so a null config must mean \"all defaults\", not a crash.\n *\n * The row is the *composition* layer of the settings namespace: the Settings\n * page edits a user layer over it, and a namespace the user has not touched\n * resolves back to this row (or to the built-in defaults). Without a settings\n * provider — plain Cordis — the row is the whole answer.\n *\n * @param ctx - the Cordis context.\n * @param config - which hooks to control and an optional DAG `log` file; null means all defaults.\n */\nexport function apply(ctx: Context, config: Config | null = {}): void {\n  const row = config ?? {}\n  const base: HooksOrderingSettings = {\n    hooks: row.hooks ?? DEFAULT_WATERFALL_HOOKS,\n    serialHooks: row.serialHooks ?? DEFAULT_SERIAL_HOOKS,\n    log: row.log ?? '',\n  }\n  const { hooks, serialHooks, log } = resolveSettings(ctx, base) ?? base\n  const serviceConfig = log === '' ? {} : { log }\n  // Not part of the settings namespace: the sync-return list describes the\n  // HOST's dispatch, not a user preference, so it is composition (row) only.\n  const syncReturnHooks = row.syncReturnHooks ?? DEFAULT_SYNC_RETURN_HOOKS\n\n  const deps: string[] = []\n  if (hooks.length > 0) {\n    ctx.plugin(HookOrdering, { ...serviceConfig, syncReturnHooks })\n    deps.push('hooksOrdering')\n  }\n  if (serialHooks.length > 0) {\n    ctx.plugin(SerialHookOrdering, serviceConfig)\n    deps.push('serialHooksOrdering')\n  }\n  if (deps.length === 0) return\n\n  // The services activate asynchronously; control the hooks once they exist.\n  ctx.inject(deps, (ready) => {\n    for (const hook of hooks) ready.hooksOrdering.control(hook)\n    for (const hook of serialHooks) ready.serialHooksOrdering.control(hook)\n  })\n}\n"],"mappings":";;;;;;;;;AA+BA,MAAa,cAAc;;;;;;;;;AAU3B,MAAa,8BAA8B,OAAO,OAAO;CACvD,OAAO,OAAO,MAAM,OAAO,QAAQ,CAAC,CAAC,QAAQ,EAAE,CAAC;CAChD,aAAa,OAAO,MAAM,OAAO,QAAQ,CAAC,CAAC,QAAQ,EAAE,CAAC;CACtD,KAAK,OAAO,QAAQ,CAAC,QAAQ,GAAG;CACjC,CAAC;;;;;;;;;;;;;;;;;;;AA0CF,SAAgB,gBAAgB,KAAc,MAAgE;CAC5G,MAAM,WAAW,IAAI,IAAI,WAAW;AACpC,KAAI,aAAa,OAAW,QAAO;AACnC,KAAI;AACF,SAAO,SAAS,SAAS,aAAa,6BAA6B;GAAE;GAAM,SAAS;GAAW,CAAC,CAAC,KAAK;UAC/F,OAAO;AACd,UAAQ,KAAK,yFAAyF,MAAM;AAC5G;;;;;;;ACvEJ,MAAa,OAAO;;;;;;;;;;;;;;;;;;AAmBpB,MAAa,SAAS,CAAC,WAAW;;;;;;;;;;;;;;;;;;;AAoBlC,MAAaA,0BAA6C;CACxD;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACD;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4BD,MAAaC,4BAA+C;CAC1D;CACA;CACA;CACD;;AAGD,MAAaC,uBAA0C,CAAC,sBAAsB;;;;;;;;;;;;;;;;;;;AA2C9E,SAAgB,MAAM,KAAc,SAAwB,EAAE,EAAQ;CACpE,MAAM,MAAM,UAAU,EAAE;CACxB,MAAMC,OAA8B;EAClC,OAAO,IAAI,SAAS;EACpB,aAAa,IAAI,eAAe;EAChC,KAAK,IAAI,OAAO;EACjB;CACD,MAAM,EAAE,OAAO,aAAa,QAAQ,gBAAgB,KAAK,KAAK,IAAI;CAClE,MAAM,gBAAgB,QAAQ,KAAK,EAAE,GAAG,EAAE,KAAK;CAG/C,MAAM,kBAAkB,IAAI,mBAAmB;CAE/C,MAAMC,OAAiB,EAAE;AACzB,KAAI,MAAM,SAAS,GAAG;AACpB,MAAI,OAAOC,mBAAc;GAAE,GAAG;GAAe;GAAiB,CAAC;AAC/D,OAAK,KAAK,gBAAgB;;AAE5B,KAAI,YAAY,SAAS,GAAG;AAC1B,MAAI,OAAO,oBAAoB,cAAc;AAC7C,OAAK,KAAK,sBAAsB;;AAElC,KAAI,KAAK,WAAW,EAAG;AAGvB,KAAI,OAAO,OAAO,UAAU;AAC1B,OAAK,MAAM,QAAQ,MAAO,OAAM,cAAc,QAAQ,KAAK;AAC3D,OAAK,MAAM,QAAQ,YAAa,OAAM,oBAAoB,QAAQ,KAAK;GACvE"}
+{"version":3,"file":"index.js","names":["DEFAULT_WATERFALL_HOOKS: readonly string[]","DEFAULT_SYNC_RETURN_HOOKS: readonly string[]","DEFAULT_SERIAL_HOOKS: readonly string[]","deps: string[]","HookOrdering"],"sources":["../src/settings.ts","../src/dsh.ts"],"sourcesContent":["/**\n * This plugin's Cordis Config — and, since DSH 0.1.7, its Settings page.\n *\n * 0.1.7 removed `ctx.settings.register(ns, schema)`. Settings are now *projected\n * from each entry's own Config*: the loader validates the row's `config` against\n * this schema, resolves the defaults, and the settings service renders exactly\n * the nodes marked `.volatile()` as an editable form. Three consequences are\n * load-bearing here:\n *\n * - The defaults below are the *real* defaults, not \"off\" placeholders. Nothing\n *   supplies a second `base` layer any more, so an entry whose `config:` key is\n *   empty must resolve to the hook set this plugin controls by default.\n * - `.volatile()` belongs on the individual fields, never on the root object:\n *   a volatile root collapses the whole Config into a single reference and\n *   discards every nested default (verified against schemastery 3.18.4), and\n *   schemastery rejects a volatile node nested inside another volatile node.\n * - The schema is built lazily by {@link hooksOrderingConfig}. `dsh.ts` imports\n *   this module and this module needs `dsh.ts`'s default hook lists, so building\n *   the schema eagerly would read those bindings before they are initialized.\n *\n * `syncReturnHooks` is deliberately absent: it describes the HOST's dispatch\n * (which hooks are consumed without awaiting), not a user preference, so it\n * stays composition-only in `apply()`.\n *\n * @module dsh-hooks-ordering/settings\n */\n\nimport Schema from '@deepseek-ai/schemastery'\n\n/** The fields this plugin exposes as editable settings. */\nexport interface HooksOrderingSettings {\n  /** Waterfall hooks to control; `[]` disables the waterfall service entirely. */\n  readonly hooks: readonly string[]\n  /** Serial hooks to control; `[]` disables the serial service entirely. */\n  readonly serialHooks: readonly string[]\n  /** Constraint-DAG log file; the empty string means \"do not log\". */\n  readonly log: string\n}\n\n/**\n * Entry id used by `cordis.patch.yml` and, in 0.1.7, by the settings form.\n *\n * The form is keyed by the **loader entry id**; this constant is the shipped\n * row's id, and it is also the client half's settings-section id.\n */\nexport const SETTINGS_NS = 'hooks-ordering'\n\n/**\n * Build the Config schema from the caller's default hook lists.\n *\n * Every field is `.volatile()`, so every field is user-editable from the\n * Settings page and an edit is committed into the live reference instead of\n * remounting the plugin. `log` is volatile too, because a non-volatile field\n * would not appear in the form at all.\n *\n * @param defaultWaterfallHooks - waterfall hooks controlled when unconfigured.\n * @param defaultSerialHooks - serial hooks controlled when unconfigured.\n * @returns a callable schemastery schema, which is what Cordis resolves through.\n */\nexport function hooksOrderingConfig(\n  defaultWaterfallHooks: readonly string[],\n  defaultSerialHooks: readonly string[],\n): Schema {\n  return Schema.object({\n    hooks: Schema.array(Schema.string()).default([...defaultWaterfallHooks]).volatile(),\n    serialHooks: Schema.array(Schema.string()).default([...defaultSerialHooks]).volatile(),\n    log: Schema.string().default('').volatile(),\n  })\n}\n\n/**\n * Read one resolved field, unwrapping a volatile reference when the loader\n * supplied one and falling back to a default when the field is absent.\n *\n * A loader-provided Config carries volatile fields as references (`.get()`);\n * a plain Cordis mount, or an older harness, passes plain values. Both must\n * work, and an absent field must not be confused with an explicit empty one.\n *\n * @param config - the resolved plugin config (possibly `null`).\n * @param field - the field to read.\n * @param fallback - value to use when the field is absent.\n * @returns the field's current value, or `fallback`.\n */\nexport function readSetting<T>(\n  config: object | null | undefined,\n  field: string,\n  fallback: T,\n): T {\n  const value = (config as Record<string, unknown> | null | undefined)?.[field]\n  if (value === undefined || value === null) return fallback\n  if (typeof (value as { get?: unknown }).get === 'function') {\n    const current = (value as { get(): unknown }).get()\n    return (current ?? fallback) as T\n  }\n  return value as T\n}\n","/**\n * The DeepSeek-Harness layer: a dsh plugin that mounts the ordering services\n * and takes control of the real dsh hooks that multiple independent packages\n * contribute to, so a profile can opt into deterministic ordering with one row.\n *\n * dsh (deepseek-harness) ships waterfall hooks such as `agent/pre-step`\n * (subscribed by a dozen+ independent packages), `tools/post-execute`,\n * `llm/stream`, and `system-prompt/assemble`, plus the serial hook\n * `agent/turn-stopping`. Their relative listener order is load-bearing yet\n * today decided only by binary `prepend` and registration timing. This plugin\n * controls those hooks up front; controlling an empty hook is a transparent\n * pass-through, so nothing changes until participants register with\n * `before`/`after`.\n *\n * @module dsh-hooks-ordering/dsh\n */\n\nimport type { Context } from '@deepseek-ai/cordis'\nimport HookOrdering from './waterfall.ts'\nimport { SerialHookOrdering } from './serial.ts'\nimport { type HooksOrderingSettings, hooksOrderingConfig, readSetting } from './settings.ts'\n\n/** Cordis plugin name used by loader diagnostics. */\nexport const name = 'hooks-ordering'\n\n/**\n * `settings` is a **hard** dependency, and it has to be declared rather than\n * probed.\n *\n * cordis activates a plugin as soon as the services it declares exist, and\n * `ctx.get('settings')` reads the service store *without* creating that\n * requirement. Without this line the dsh layer loads in the first wave — before\n * the host has provided `settings` — the probe returns `undefined`, and the\n * settings namespace is never registered. Silently: no form, no error.\n *\n * Declaring it makes cordis wait, which also lands this plugin's prepended\n * brackets later in the boot, exactly where the ordering guarantee wants them.\n *\n * This entry targets dsh only — the hook names below are dsh's, and dsh always\n * provides `settings`, so the dependency costs nothing here. `/waterfall` and\n * `/serial` are the entries that carry no host-service requirement.\n */\nexport const inject = ['settings']\n\n/**\n * The dsh waterfall hooks this plugin controls by default — the ones multiple\n * independent packages contribute to, where relative order matters. Controlling\n * a hook with no registered participants is a no-op pass-through.\n *\n * Every name here was checked against the events dsh actually declares: each is\n * a `@mode waterfall` event in the installed build, and each is dispatched with\n * `await`, so the caller already handles a Promise and the bracket's async\n * phases cannot change the hook's return type. `tools/code-dispatch-log` used\n * to sit in this list and no dsh package declares it at all — controlling a\n * name nothing dispatches \"succeeds\" and then does nothing forever, which is\n * exactly the dead configuration this list must not carry.\n *\n * The other admission rule is {@link DEFAULT_SYNC_RETURN_HOOKS}: a hook whose\n * value the caller consumes without awaiting cannot carry ordered participants,\n * so controlling it by default would install a bracket nothing may ever\n * register into — the same dead configuration by a different route.\n */\nexport const DEFAULT_WATERFALL_HOOKS: readonly string[] = [\n  'agent/pre-step',\n  'agent/request',\n  'agent/request-error',\n  'system-prompt/assemble',\n  'tools/pre-execute',\n  'tools/execute',\n  'tools/post-execute',\n  'fs/write-intent',\n  'fs/edit-intent',\n  'approval/request',\n]\n\n/**\n * dsh hooks whose dispatch return value is consumed by the caller without\n * awaiting, and which therefore cannot carry ordered participants. Verified\n * against the installed build:\n *\n * - `llm/stream` — `dsh-llm` dispatches it as\n *   `return this.ctx.waterfall(this, \"llm/stream\", options, …)` (no await), and\n *   `dsh-session-title-llm` iterates the result with\n *   `for await (const chunk of ctx.llm.stream(options))`. A Promise there throws\n *   \"not async iterable\". It is a genuine multi-contributor hook (dsh-agent-loop,\n *   dsh-llm's own invariant, dsh-session-checkpoint-policy, dsh-session-title),\n *   so it is a real loss — but ordering it requires dsh to await the dispatch,\n *   not a plugin-side workaround.\n * - `session-telemetry/record` — `dsh-session-telemetry` returns the record\n *   straight out of the waterfall and hands it to the backend, so a Promise\n *   would be emitted as a record: silent corruption, no error anywhere.\n * - `compaction/summary-error` — `dsh-compaction-basic` dispatches it as\n *   `recover: (…) => this.ctx.waterfall(this, \"compaction/summary-error\", …, () => false)`\n *   (no await) and consumes the boolean synchronously in\n *   `if (!dependencies.recover(error, agent, prepared.shadowedSeqs, signal)) throw error`.\n *   A Promise is always truthy, so `!recover(…)` is always false and every\n *   summarizer failure is swallowed instead of rethrown — the compaction then\n *   proceeds as if recovery had succeeded.\n *\n * Override per profile with `syncReturnHooks` once the host awaits one of them.\n */\nexport const DEFAULT_SYNC_RETURN_HOOKS: readonly string[] = [\n  'llm/stream',\n  'session-telemetry/record',\n  'compaction/summary-error',\n]\n\n/** The dsh serial hook controlled by default. */\nexport const DEFAULT_SERIAL_HOOKS: readonly string[] = ['agent/turn-stopping']\n\n/**\n * This plugin's Cordis Config schema.\n *\n * Since DSH 0.1.7 this *is* the Settings page: the fields are `.volatile()`, so\n * the settings service projects exactly them into an editable form and commits\n * an edit into the live reference rather than remounting the plugin. The\n * defaults are the real hook sets below, so an entry whose `config:` key is\n * empty resolves to them.\n */\nexport const Config = hooksOrderingConfig(DEFAULT_WATERFALL_HOOKS, DEFAULT_SERIAL_HOOKS)\n\n/** The same schema under its pre-0.1.7 name. */\nexport const HooksOrderingConfig = Config\n\n/**\n * Plugin config as a plain value.\n *\n * A loader-resolved config carries the volatile fields as references instead of\n * plain arrays, so this describes the *plain* shape callers and tests construct.\n */\nexport interface ConfigShape {\n  /**\n   * Waterfall hooks to control. Defaults to {@link DEFAULT_WATERFALL_HOOKS}.\n   * Pass `[]` to disable the waterfall service entirely.\n   */\n  hooks?: readonly string[]\n  /**\n   * Serial hooks to control. Defaults to {@link DEFAULT_SERIAL_HOOKS}.\n   * Pass `[]` to disable the serial service entirely.\n   */\n  serialHooks?: readonly string[]\n  /**\n   * Hooks whose return value the host consumes without awaiting, and which must\n   * therefore refuse participants. Defaults to {@link DEFAULT_SYNC_RETURN_HOOKS}.\n   * Pass `[]` — or a set without a given hook — to opt in to ordering it, once\n   * the host awaits that dispatch.\n   *\n   * Composition-only: this describes the HOST's dispatch, not a user\n   * preference, so it is intentionally not a field of {@link Config} and never\n   * appears on the Settings page.\n   */\n  syncReturnHooks?: readonly string[]\n  /** When set, the constraint DAG (JSON) is logged to this file on every change. */\n  log?: string\n  /** Overrides the loader entry id; only non-loader harnesses need it. */\n  entryId?: string\n}\n\n/**\n * Mount {@link HookOrdering} and/or {@link SerialHookOrdering} and control the\n * configured hooks once the services are active.\n *\n * `config` may be `null`, and that is the ordinary case rather than an edge\n * case: a loader row whose `config:` key is followed only by comments parses as\n * YAML null, and a default parameter covers `undefined` but not `null`. This\n * package's own `cordis.patch.yml` is written exactly that way — every option\n * commented out — so a null config must mean \"all defaults\", not a crash.\n *\n * Since DSH 0.1.7 there is no second \"user layer\": the row's `config` IS the\n * editable settings, because Cordis validates it against {@link Config} and the\n * settings service projects that schema. A volatile field arrives here as a\n * reference rather than a plain array, which is why every read goes through\n * {@link readSetting} — that also keeps a plain Cordis mount (and an older\n * harness) working, where the fields are plain values.\n *\n * `hooks`/`serialHooks` are read once, at apply time. An edit from the Settings\n * page therefore needs a plugin reload to take effect — the same restart\n * semantics this namespace declared before 0.1.7 (`applies: 'restart'`), since\n * changing the controlled set means adding or removing live hook brackets and\n * the coordinator has no public \"release one hook\" operation.\n *\n * @param ctx - the Cordis context.\n * @param config - which hooks to control and an optional DAG `log` file; null means all defaults.\n */\nexport function apply(ctx: Context, config: ConfigShape | null = {}): void {\n  const row = config ?? {}\n  const settings: HooksOrderingSettings = {\n    hooks: readSetting(row, 'hooks', DEFAULT_WATERFALL_HOOKS),\n    serialHooks: readSetting(row, 'serialHooks', DEFAULT_SERIAL_HOOKS),\n    log: readSetting(row, 'log', ''),\n  }\n  const { hooks, serialHooks, log } = settings\n  const serviceConfig = log === '' ? {} : { log }\n  // Not part of the settings form: the sync-return list describes the HOST's\n  // dispatch, not a user preference, so it is composition (row) only.\n  const syncReturnHooks = row.syncReturnHooks ?? DEFAULT_SYNC_RETURN_HOOKS\n\n  const deps: string[] = []\n  if (hooks.length > 0) {\n    ctx.plugin(HookOrdering, { ...serviceConfig, syncReturnHooks })\n    deps.push('hooksOrdering')\n  }\n  if (serialHooks.length > 0) {\n    ctx.plugin(SerialHookOrdering, serviceConfig)\n    deps.push('serialHooksOrdering')\n  }\n  if (deps.length === 0) return\n\n  // The services activate asynchronously; control the hooks once they exist.\n  ctx.inject(deps, (ready) => {\n    for (const hook of hooks) ready.hooksOrdering.control(hook)\n    for (const hook of serialHooks) ready.serialHooksOrdering.control(hook)\n  })\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AA2DA,SAAgB,oBACd,uBACA,oBACQ;AACR,QAAO,OAAO,OAAO;EACnB,OAAO,OAAO,MAAM,OAAO,QAAQ,CAAC,CAAC,QAAQ,CAAC,GAAG,sBAAsB,CAAC,CAAC,UAAU;EACnF,aAAa,OAAO,MAAM,OAAO,QAAQ,CAAC,CAAC,QAAQ,CAAC,GAAG,mBAAmB,CAAC,CAAC,UAAU;EACtF,KAAK,OAAO,QAAQ,CAAC,QAAQ,GAAG,CAAC,UAAU;EAC5C,CAAC;;;;;;;;;;;;;;;AAgBJ,SAAgB,YACd,QACA,OACA,UACG;CACH,MAAM,QAAS,SAAwD;AACvE,KAAI,UAAU,UAAa,UAAU,KAAM,QAAO;AAClD,KAAI,OAAQ,MAA4B,QAAQ,WAE9C,QADiB,MAA6B,KAAK,IAChC;AAErB,QAAO;;;;;;ACvET,MAAa,OAAO;;;;;;;;;;;;;;;;;;AAmBpB,MAAa,SAAS,CAAC,WAAW;;;;;;;;;;;;;;;;;;;AAoBlC,MAAaA,0BAA6C;CACxD;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACD;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4BD,MAAaC,4BAA+C;CAC1D;CACA;CACA;CACD;;AAGD,MAAaC,uBAA0C,CAAC,sBAAsB;;;;;;;;;;AAW9E,MAAa,SAAS,oBAAoB,yBAAyB,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiExF,SAAgB,MAAM,KAAc,SAA6B,EAAE,EAAQ;CACzE,MAAM,MAAM,UAAU,EAAE;CAMxB,MAAM,EAAE,OAAO,aAAa,QALY;EACtC,OAAO,YAAY,KAAK,SAAS,wBAAwB;EACzD,aAAa,YAAY,KAAK,eAAe,qBAAqB;EAClE,KAAK,YAAY,KAAK,OAAO,GAAG;EACjC;CAED,MAAM,gBAAgB,QAAQ,KAAK,EAAE,GAAG,EAAE,KAAK;CAG/C,MAAM,kBAAkB,IAAI,mBAAmB;CAE/C,MAAMC,OAAiB,EAAE;AACzB,KAAI,MAAM,SAAS,GAAG;AACpB,MAAI,OAAOC,mBAAc;GAAE,GAAG;GAAe;GAAiB,CAAC;AAC/D,OAAK,KAAK,gBAAgB;;AAE5B,KAAI,YAAY,SAAS,GAAG;AAC1B,MAAI,OAAO,oBAAoB,cAAc;AAC7C,OAAK,KAAK,sBAAsB;;AAElC,KAAI,KAAK,WAAW,EAAG;AAGvB,KAAI,OAAO,OAAO,UAAU;AAC1B,OAAK,MAAM,QAAQ,MAAO,OAAM,cAAc,QAAQ,KAAK;AAC3D,OAAK,MAAM,QAAQ,YAAa,OAAM,oBAAoB,QAAQ,KAAK;GACvE"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zfdx123/dsh-hooks-ordering",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "description": "钩子排序：为 Cordis 的 waterfall / serial 钩子提供确定性的 before/after 排序，让互相独立的插件能声明彼此的先后关系（拓扑排序、环检测、可配置控制集与设置页）。",
   "keywords": [
     "cordis",
@@ -61,11 +61,11 @@
   ],
   "engines": {
     "node": "^22.19.0 || >=24.0.0",
-    "dsh": "^0.1.6-alpha.1"
+    "dsh": "^0.1.7-rc.2"
   },
   "peerDependencies": {
-    "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-settings": "^0.1.6-alpha.1"
+    "@deepseek-ai/cordis": "^4.0.4",
+    "@deepseek-ai/dsh-settings": "^0.1.7-rc.2"
   },
   "peerDependenciesMeta": {
     "@deepseek-ai/dsh-settings": {
@@ -73,10 +73,10 @@
     }
   },
   "dependencies": {
-    "@deepseek-ai/schemastery": "^3.18.1"
+    "@deepseek-ai/schemastery": "^3.18.4"
   },
   "devDependencies": {
-    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/cordis": "^4.0.4",
     "@types/node": "^22.20.1",
     "@vitest/coverage-v8": "^3.2.4",
     "oxlint": "^1.0.0",

package/src/dsh.ts

@@ -18,7 +18,7 @@
 import type { Context } from '@deepseek-ai/cordis'
 import HookOrdering from './waterfall.ts'
 import { SerialHookOrdering } from './serial.ts'
-import { type HooksOrderingSettings, resolveSettings } from './settings.ts'
+import { type HooksOrderingSettings, hooksOrderingConfig, readSetting } from './settings.ts'
 
 /** Cordis plugin name used by loader diagnostics. */
 export const name = 'hooks-ordering'
@@ -108,8 +108,27 @@ export const DEFAULT_SYNC_RETURN_HOOKS: readonly string[] = [
 /** The dsh serial hook controlled by default. */
 export const DEFAULT_SERIAL_HOOKS: readonly string[] = ['agent/turn-stopping']
 
-/** Plugin config. */
-export interface Config {
+/**
+ * This plugin's Cordis Config schema.
+ *
+ * Since DSH 0.1.7 this *is* the Settings page: the fields are `.volatile()`, so
+ * the settings service projects exactly them into an editable form and commits
+ * an edit into the live reference rather than remounting the plugin. The
+ * defaults are the real hook sets below, so an entry whose `config:` key is
+ * empty resolves to them.
+ */
+export const Config = hooksOrderingConfig(DEFAULT_WATERFALL_HOOKS, DEFAULT_SERIAL_HOOKS)
+
+/** The same schema under its pre-0.1.7 name. */
+export const HooksOrderingConfig = Config
+
+/**
+ * Plugin config as a plain value.
+ *
+ * A loader-resolved config carries the volatile fields as references instead of
+ * plain arrays, so this describes the *plain* shape callers and tests construct.
+ */
+export interface ConfigShape {
   /**
    * Waterfall hooks to control. Defaults to {@link DEFAULT_WATERFALL_HOOKS}.
    * Pass `[]` to disable the waterfall service entirely.
@@ -125,10 +144,16 @@ export interface Config {
    * therefore refuse participants. Defaults to {@link DEFAULT_SYNC_RETURN_HOOKS}.
    * Pass `[]` — or a set without a given hook — to opt in to ordering it, once
    * the host awaits that dispatch.
+   *
+   * Composition-only: this describes the HOST's dispatch, not a user
+   * preference, so it is intentionally not a field of {@link Config} and never
+   * appears on the Settings page.
    */
   syncReturnHooks?: readonly string[]
   /** When set, the constraint DAG (JSON) is logged to this file on every change. */
   log?: string
+  /** Overrides the loader entry id; only non-loader harnesses need it. */
+  entryId?: string
 }
 
 /**
@@ -141,25 +166,33 @@ export interface Config {
  * package's own `cordis.patch.yml` is written exactly that way — every option
  * commented out — so a null config must mean "all defaults", not a crash.
  *
- * The row is the *composition* layer of the settings namespace: the Settings
- * page edits a user layer over it, and a namespace the user has not touched
- * resolves back to this row (or to the built-in defaults). Without a settings
- * provider — plain Cordis — the row is the whole answer.
+ * Since DSH 0.1.7 there is no second "user layer": the row's `config` IS the
+ * editable settings, because Cordis validates it against {@link Config} and the
+ * settings service projects that schema. A volatile field arrives here as a
+ * reference rather than a plain array, which is why every read goes through
+ * {@link readSetting} — that also keeps a plain Cordis mount (and an older
+ * harness) working, where the fields are plain values.
+ *
+ * `hooks`/`serialHooks` are read once, at apply time. An edit from the Settings
+ * page therefore needs a plugin reload to take effect — the same restart
+ * semantics this namespace declared before 0.1.7 (`applies: 'restart'`), since
+ * changing the controlled set means adding or removing live hook brackets and
+ * the coordinator has no public "release one hook" operation.
  *
  * @param ctx - the Cordis context.
  * @param config - which hooks to control and an optional DAG `log` file; null means all defaults.
  */
-export function apply(ctx: Context, config: Config | null = {}): void {
+export function apply(ctx: Context, config: ConfigShape | null = {}): void {
   const row = config ?? {}
-  const base: HooksOrderingSettings = {
-    hooks: row.hooks ?? DEFAULT_WATERFALL_HOOKS,
-    serialHooks: row.serialHooks ?? DEFAULT_SERIAL_HOOKS,
-    log: row.log ?? '',
+  const settings: HooksOrderingSettings = {
+    hooks: readSetting(row, 'hooks', DEFAULT_WATERFALL_HOOKS),
+    serialHooks: readSetting(row, 'serialHooks', DEFAULT_SERIAL_HOOKS),
+    log: readSetting(row, 'log', ''),
   }
-  const { hooks, serialHooks, log } = resolveSettings(ctx, base) ?? base
+  const { hooks, serialHooks, log } = settings
   const serviceConfig = log === '' ? {} : { log }
-  // Not part of the settings namespace: the sync-return list describes the
-  // HOST's dispatch, not a user preference, so it is composition (row) only.
+  // Not part of the settings form: the sync-return list describes the HOST's
+  // dispatch, not a user preference, so it is composition (row) only.
   const syncReturnHooks = row.syncReturnHooks ?? DEFAULT_SYNC_RETURN_HOOKS
 
   const deps: string[] = []

package/src/index.ts

@@ -45,7 +45,8 @@ export { type SerialHookEntry, type SerialHookOrderingConfig, SerialHookOrdering
 // it as its default.
 export {
   apply,
-  type Config,
+  Config,
+  type ConfigShape,
   DEFAULT_SERIAL_HOOKS,
   DEFAULT_SYNC_RETURN_HOOKS,
   DEFAULT_WATERFALL_HOOKS,

package/src/settings.ts

@@ -1,24 +1,33 @@
 /**
- * The dsh settings namespace for this plugin: the three fields a user can edit
- * from the Settings page instead of a `cordis.patch.yml` row.
+ * This plugin's Cordis Config — and, since DSH 0.1.7, its Settings page.
  *
- * Two constraints are load-bearing and easy to get wrong:
+ * 0.1.7 removed `ctx.settings.register(ns, schema)`. Settings are now *projected
+ * from each entry's own Config*: the loader validates the row's `config` against
+ * this schema, resolves the defaults, and the settings service renders exactly
+ * the nodes marked `.volatile()` as an editable form. Three consequences are
+ * load-bearing here:
  *
- * - The schema handed to `settings.register` must be a **callable** schemastery
- *   schema. dsh resolves a namespace by calling `schema(merged)` and reads
- *   `schema.toJSON()` for the form, so a plain object throws
- *   `schema is not a function` — during plugin assembly, which takes the whole
- *   profile down rather than failing one form.
- * - That is also why registration is wrapped in `try/catch` here: an optional
- *   settings form must never be able to stop the harness from booting.
+ * - The defaults below are the *real* defaults, not "off" placeholders. Nothing
+ *   supplies a second `base` layer any more, so an entry whose `config:` key is
+ *   empty must resolve to the hook set this plugin controls by default.
+ * - `.volatile()` belongs on the individual fields, never on the root object:
+ *   a volatile root collapses the whole Config into a single reference and
+ *   discards every nested default (verified against schemastery 3.18.4), and
+ *   schemastery rejects a volatile node nested inside another volatile node.
+ * - The schema is built lazily by {@link hooksOrderingConfig}. `dsh.ts` imports
+ *   this module and this module needs `dsh.ts`'s default hook lists, so building
+ *   the schema eagerly would read those bindings before they are initialized.
+ *
+ * `syncReturnHooks` is deliberately absent: it describes the HOST's dispatch
+ * (which hooks are consumed without awaiting), not a user preference, so it
+ * stays composition-only in `apply()`.
  *
  * @module dsh-hooks-ordering/settings
  */
 
-import type { Context } from '@deepseek-ai/cordis'
 import Schema from '@deepseek-ai/schemastery'
 
-/** The three fields this plugin exposes for configuration. */
+/** The fields this plugin exposes as editable settings. */
 export interface HooksOrderingSettings {
   /** Waterfall hooks to control; `[]` disables the waterfall service entirely. */
   readonly hooks: readonly string[]
@@ -28,70 +37,60 @@ export interface HooksOrderingSettings {
   readonly log: string
 }
 
-/** Namespace name — dsh requires a lowercase hyphenated identifier. */
-export const SETTINGS_NS = 'hooks-ordering'
-
 /**
- * Schema for {@link SETTINGS_NS}.
+ * Entry id used by `cordis.patch.yml` and, in 0.1.7, by the settings form.
  *
- * Every field defaults to its "off" value. The *meaningful* defaults — the
- * hooks this plugin controls when nothing overrides them — are supplied by the
- * caller as the composition `base` layer (see {@link resolveSettings}), so a
- * namespace the user has never touched still resolves to a complete object.
+ * The form is keyed by the **loader entry id**; this constant is the shipped
+ * row's id, and it is also the client half's settings-section id.
  */
-export const HooksOrderingSettingsSchema = Schema.object({
-  hooks: Schema.array(Schema.string()).default([]),
-  serialHooks: Schema.array(Schema.string()).default([]),
-  log: Schema.string().default(''),
-})
+export const SETTINGS_NS = 'hooks-ordering'
 
 /**
- * The slice of dsh's `settings` service this plugin uses.
+ * Build the Config schema from the caller's default hook lists.
+ *
+ * Every field is `.volatile()`, so every field is user-editable from the
+ * Settings page and an edit is committed into the live reference instead of
+ * remounting the plugin. `log` is volatile too, because a non-volatile field
+ * would not appear in the form at all.
  *
- * Structural rather than imported from `@deepseek-ai/dsh-settings`: it describes
- * exactly the contract this plugin relies on without adding a build-time
- * dependency on a dsh package, whose internals are still 0.1.x-rc.
+ * @param defaultWaterfallHooks - waterfall hooks controlled when unconfigured.
+ * @param defaultSerialHooks - serial hooks controlled when unconfigured.
+ * @returns a callable schemastery schema, which is what Cordis resolves through.
  */
-export interface SettingsServiceLike {
-  /**
-   * @param ns - the namespace to register; must be a lowercase hyphenated identifier.
-   * @param schema - a callable schemastery schema, not a plain object.
-   * @param options - `base` is the composition layer, `applies` says whether an
-   * edit takes effect live or needs a restart.
-   * @returns a scope whose `get()` is the resolved value (schema defaults, then `base`, then the user layer).
-   */
-  register(
-    ns: string,
-    schema: unknown,
-    options?: { readonly base?: unknown; readonly applies?: 'live' | 'restart' },
-  ): { get(): HooksOrderingSettings }
+export function hooksOrderingConfig(
+  defaultWaterfallHooks: readonly string[],
+  defaultSerialHooks: readonly string[],
+): Schema {
+  return Schema.object({
+    hooks: Schema.array(Schema.string()).default([...defaultWaterfallHooks]).volatile(),
+    serialHooks: Schema.array(Schema.string()).default([...defaultSerialHooks]).volatile(),
+    log: Schema.string().default('').volatile(),
+  })
 }
 
 /**
- * Register the settings namespace and read its resolved value.
- *
- * `base` is the composition layer — what the row (or the built-in defaults)
- * asks for — so the user layer edits *over* it and a reset returns to it rather
- * than to an empty form.
+ * Read one resolved field, unwrapping a volatile reference when the loader
+ * supplied one and falling back to a default when the field is absent.
  *
- * `applies: 'restart'` is deliberate. Changing `hooks`/`serialHooks` means
- * installing or removing bracket listeners on live hooks, and the coordinator
- * has no public "release one hook" operation; a restart applies the change
- * cleanly instead of re-wiring the dispatch chain mid-flight.
+ * A loader-provided Config carries volatile fields as references (`.get()`);
+ * a plain Cordis mount, or an older harness, passes plain values. Both must
+ * work, and an absent field must not be confused with an explicit empty one.
  *
- * @param ctx - the Cordis context to look the service up on.
- * @param base - the composition layer to register as the base value.
- * @returns the resolved settings, or `undefined` when the provider is missing
- * (which `inject: ['settings']` rules out in dsh — the guard is defensive) or
- * registration failed — the caller then uses `base`.
+ * @param config - the resolved plugin config (possibly `null`).
+ * @param field - the field to read.
+ * @param fallback - value to use when the field is absent.
+ * @returns the field's current value, or `fallback`.
  */
-export function resolveSettings(ctx: Context, base: HooksOrderingSettings): HooksOrderingSettings | undefined {
-  const settings = ctx.get('settings') as SettingsServiceLike | undefined
-  if (settings === undefined) return undefined
-  try {
-    return settings.register(SETTINGS_NS, HooksOrderingSettingsSchema, { base, applies: 'restart' }).get()
-  } catch (error) {
-    console.warn('hooks-ordering: settings registration failed; falling back to the composition config:', error)
-    return undefined
+export function readSetting<T>(
+  config: object | null | undefined,
+  field: string,
+  fallback: T,
+): T {
+  const value = (config as Record<string, unknown> | null | undefined)?.[field]
+  if (value === undefined || value === null) return fallback
+  if (typeof (value as { get?: unknown }).get === 'function') {
+    const current = (value as { get(): unknown }).get()
+    return (current ?? fallback) as T
   }
+  return value as T
 }