dsh-plugin-guide 0.3.21 → 0.3.23

package/references/official-docs/docs/subsystems/settings.md

@@ -1,169 +1,18 @@
-# User Settings
+# Plugin Configuration Forms
 
 English | [中文](settings.zh.md)
 
-The user-settings seam of [dsh-settings](../../packages/settings/settings) holds one user-owned document of per-namespace sections and resolves each registered namespace as schema defaults, then the registrant's composition `base`, then the user section. Providers such as [dsh-settings-file](../../packages/settings/settings-file) store the raw document and push external edits; consumer plugins register a schema and read or observe the resolved value. Composition config stays in `cordis.yml` — a namespace carries only the user-editable subset.
+The [settings service](../../packages/settings/settings/README.md) projects volatile Config fields from active profile entries. The [configuration editor](../../packages/boot/config-editor/README.md) persists edits through Cordis patches. Business consumers read `.get()` on their own Config references.
 
-Source: [`packages/settings/settings/src/index.ts`](../../packages/settings/settings/src/index.ts)
-
-## Identity
-
-A namespace names one plugin-owned section of the user document. The brand prevents callers from mixing settings namespaces with other ids passed between packages or processes; construction validates lowercase kebab-case syntax.
-
-```ts type-equiv
-/** Nominal id of one registered settings namespace. */
-type SettingsNamespace = Branded<'SettingsNamespace'>
-```
-
-## Registration
-
-Registration binds a schemastery schema to a namespace on the calling plugin's fiber — disposing that fiber removes the namespace and its observers. The options carry the composition layer, the owner's effect timing, and an optional check for what the schema cannot express.
-
-```ts type-equiv
-/** Registration options beyond the namespace schema. */
-interface SettingsRegisterOptions<T> {
-  /** Composition-layer values resolved below the user layer (entry-config subset). */
-  base?: Partial<T>
-  /** Owner's effect timing, surfaced to configuration UIs; defaults to `live`. */
-  applies?: SettingsApplies
-  /**
-   * Reject a resolved section the owner could not act on, for constraints its
-   * schema cannot express — a cross-field requirement, or one field's validity
-   * depending on another's. Throwing here refuses the *write* that produced the
-   * value, so a caller learns at `update`/`replace`/`mutate` instead of storing
-   * something that would silently disable the owner.
-   *
-   * Kept separate from the schema because the schema is also what a
-   * configuration surface renders and what an absent section resolves through;
-   * folding a cross-field check into it would change both.
-   *
-   * Once the owner is registered, a stored section that fails this keeps the
-   * namespace's last good value and warns, exactly as a schema failure does,
-   * so an externally edited document cannot strand a running owner. At
-   * registration there is no last good value yet, so a stored section that
-   * already fails rejects the registration itself — again exactly as a schema
-   * failure does.
-   * @param value - the resolved section, schema-valid by construction.
-   */
-  validate?: (value: T) => void
-}
-```
-
-`validate` runs after the schema admits a value, so it sees defaults and the composition base exactly as the owner will. `dsh-llm-pi-ai` uses it to refuse a provider profile it could not serve at the write that produced it, rather than storing one that would disable every route in its namespace.
-
-`applies` is a UI hint, not a mechanism: a `restart` owner never watches, so its value is read once at construction and configuration surfaces can badge the pending change.
-
-```ts type-equiv
-/** When a namespace's changes take effect for its owner. */
-type SettingsApplies = 'live' | 'restart'
-```
-
-## Owner scope
-
-The scope is the owner-facing handle. `update` merges a sparse patch over the user section only (never into `base`); `replace` sets the section wholesale, which is the removal/reset path — keys absent from the replacement re-inherit `base` and schema defaults. Writes to one namespace are serialized in call order, and resolved values are deep-frozen snapshots.
-
-```ts type-equiv
-/** Owner-facing handle for one registered namespace. */
-interface SettingsScope<T> {
-  /** Current resolved value: schema defaults, then `base`, then the user layer. */
-  get(): T
-  /**
-   * Observe committed changes to this namespace's resolved value. Invocations
-   * of one callback run asynchronously, one at a time, in commit order; a
-   * rejection is contained and logged like a sync throw. After the disposer
-   * returns, no further invocation starts — one already queued is skipped;
-   * one already started still settles, and service disposal waits for it.
-   * @param callback - invoked after each commit with the next and previous values.
-   * @returns the disposer removing this observer.
-   */
-  watch(callback: (next: T, prev: T) => void | Promise<void>): () => void
-  /**
-   * Merge a partial patch into this namespace's user layer and persist it.
-   * @param patch - plain-object patch over the user section; JSON-compatible data
-   * only (non-JSON values reject with their path before anything persists).
-   */
-  update(patch: object): Promise<void>
-  /**
-   * Replace this namespace's user section wholesale; absent keys re-inherit
-   * the composition `base` and schema defaults (`replace({})` resets all).
-   * @param section - the complete next user section; JSON-compatible data only,
-   * as for {@link update}.
-   */
-  replace(section: object): Promise<void>
-}
-```
+## Identity and values
 
-## Descriptors
-
-`describe()` serializes every registered namespace for configuration surfaces: the schemastery `toJSON()` envelope drives schema-rendered forms, the resolved value fills them, and the detached `base`/`user` layers let a form mark user-overridden fields by presence. `describe({ redactSecrets: true })` — mandatory on every wire surface — strips `role('secret')` fields from all three layers and enumerates their `{path, set}` slots so a page can render write-only inputs without ever receiving a secret.
-
-```ts type-equiv
-/** One registered namespace as surfaced to configuration UIs. */
-interface SettingsDescriptor {
-  /** The registered namespace. */
-  ns: SettingsNamespace
-  /** Serialized schemastery schema (`schema.toJSON()`). */
-  schema: unknown
-  /** Current resolved value. */
-  value: unknown
-  /**
-   * Monotonic revision of the raw user section this descriptor was read at.
-   * Send it back as `expectedRevision` on a write to refuse a stale one.
-   */
-  revision: number
-  /** Registrant's composition `base` layer (detached), when one was declared. */
-  base?: unknown
-  /**
-   * Raw user section from the stored document (detached), when one exists and
-   * is well-formed; a field's presence here is what marks it user-overridden.
-   */
-  user?: unknown
-  /** Owner's declared effect timing. */
-  applies: SettingsApplies
-  /** Schema-declared secret positions; present only under `redactSecrets`. */
-  secrets?: RedactedSecret[]
-}
-```
+A form namespace is the local id of a uniquely addressed entry in the active profile. Multiple plugin instances have separate forms when their entry ids differ. Ordinary fields are excluded. Descriptors carry resolved values, inherited values, explicit profile overrides, and an optimistic revision.
 
-A caller that holds only the redacted descriptor cannot safely rebuild a section, so removals travel as path ops instead. Each descriptor also carries a `revision` over the raw section; a write may send it back as `expectedRevision`, and one that no longer matches is refused rather than applied over the writer that landed first.
-```ts type-equiv
-/**
- * One path-addressed edit to a namespace's user section. Path mutation exists
- * for a caller holding an INCOMPLETE view of the section — a configuration UI
- * reads the redacted descriptor, which by construction never received the
- * `role('secret')` fields. Such a caller can name the field it means without
- * restating the section: a wholesale `replace` rebuilt from a redacted
- * document silently deletes every secret the wire never returned.
- */
-type SettingsPathOp =
-  | { op: 'set'; path: readonly string[]; value: unknown }
-  | { op: 'unset'; path: readonly string[] }
-```
+## Edits
 
-```ts type-equiv
-/** Options for {@link SettingsProvider.describe}. */
-interface SettingsDescribeOptions {
-  /**
-   * Strip `role('secret')` fields from `value`/`base`/`user` and enumerate
-   * them in each descriptor's `secrets`. Every wire surface MUST pass this;
-   * the verbatim default exists for same-process configuration UIs only.
-   */
-  redactSecrets?: boolean
-}
-```
-
-## Change commits
+`update` merges submitted fields. `replace` resets live fields to inherited configuration before applying submitted fields. `mutate` addresses individual paths, preserving secrets absent from a client response. Every write validates the complete Config and refuses stale revisions before persistence.
 
-Every committed change — an in-process write or an externally observed provider edit — emits `settings/updated (ns, next, prev, source)` after the new value is authoritative, and never when the resolved value is deep-equal. The source tag separates the two entry paths.
-
-```ts type-equiv
-/** Origin of one committed settings change. */
-type SettingsUpdateSource = 'update' | 'provider'
-```
-
-## Native document operations
-
-`SettingsDocumentOpenValue` confirms that `settings/openSettingsDocument` prepared the provider-owned document and handed it to the native text editor. `AgentPresetDirectoryOpenValue` reports either a completed native handoff or the resolved user-preset directory when desktop opening is unavailable. Neither operation accepts a browser-selected Host path.
+`settings/document-updated` invalidates form descriptors after Loader configuration changes. It is a UI notification; consumers use `loader/volatile-update` only when they need to refresh registration facts.
 
 <!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
 
@@ -173,105 +22,52 @@ type SettingsUpdateSource = 'update' | 'provider'
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — the language sides differ only in locale-specific paired document paths. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
-<a id="ctxsettings--settingsprovider-abstract-seam"></a>
+<a id="ctxsettings--settingsforms"></a>
 
-### `ctx.settings` — `SettingsProvider` (abstract seam)
+### `ctx.settings` — `SettingsForms`
 
-Abstract settings service. Providers implement raw-document storage (`load`/`persist`) and push external changes through Settings.publish; the base class owns namespace registration, resolution, validation, change detection, and the `settings/updated` commit event.
+Project Config schemas into forms and own optional instance-level UI policy.
 
 ```ts cordis-catalog
-/**
- * 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(): Promise<string | undefined>
-
-/**
- * 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.
- * @throws {TypeError} when `ns` is not a lowercase hyphenated identifier.
+/** Register the calling plugin instance's page policy without changing its Config.
+ * @param presentation Automatic-page policy for this instance; `auto` defaults to true.
+ * @param owner Plugin instance the policy belongs to; defaults to the calling fiber.
+ * @returns Disposer; register it with the calling plugin's effects.
+ * @throws If this instance already has a registered policy.
  */
-register<const Namespace extends string, T>( ns: Namespace & SettingsNamespaceInput<Namespace>, schema: z<T>, options?: SettingsRegisterOptions<T>, ): SettingsScope<T>
+configure(presentation: { auto?: boolean }, owner: Fiber = this.ctx.fiber): () => void
 
-/**
- * Attach one optional-settings consumer to this provider. The consumer
- * registers its composition entry as the base layer while this provider is
- * present, then falls back to that entry if the provider detaches.
- * @param owner - consumer context whose unload suppresses fallback work.
- * @param ns - consumer-owned settings namespace.
- * @param schema - schema resolving the namespace.
- * @param entry - composition entry used as the base and fallback value.
- * @param hooks - source sink, change notification, and optional validation.
- * @throws {TypeError} when `ns` is not a lowercase hyphenated identifier.
+/** Locate the profile patch for native editing.
+ * @returns The existing profile patch path.
  */
-installSection<const Namespace extends string, T>( owner: Context, ns: Namespace & SettingsNamespaceInput<Namespace>, schema: z<T>, entry: T, hooks: SettingsSectionHooks<T>, ): void
+prepareDocument(): Promise<string>
 
-/**
- * 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.
+/** Read active plugin schemas and their live values.
+ * @param options Redaction required for remote callers.
+ * @returns Forms keyed by unique profile entry ids.
  */
 describe(options?: SettingsDescribeOptions): SettingsDescriptor[]
 
-/**
- * Read one registered namespace's resolved value.
- * @param ns - the namespace to read.
- * @returns the resolved value, or `undefined` while unregistered.
- * @throws {TypeError} when `ns` is not a lowercase hyphenated identifier.
+/** Merge editable fields into an entry's config.
+ * @param ns Profile entry id.
+ * @param patch Fields to merge.
+ * @param expectedRevision Revision returned by describe.
  */
-get<const Namespace extends string>(ns: Namespace & SettingsNamespaceInput<Namespace>): unknown
+async update(ns: string, patch: object, expectedRevision?: number): Promise<void>
 
-/**
- * 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}.
- * @throws {TypeError} when `ns` is not a lowercase hyphenated identifier.
+/** Reset all live fields, then set the supplied fields; ordinary config is preserved.
+ * @param ns Profile entry id.
+ * @param section Complete form values.
+ * @param expectedRevision Revision returned by describe.
  */
-async update<const Namespace extends string>( ns: Namespace & SettingsNamespaceInput<Namespace>, patch: object, expectedRevision?: number, ): Promise<void>
+async replace(ns: string, section: object, expectedRevision?: number): Promise<void>
 
-/**
- * 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}.
- * @throws {TypeError} when `ns` is not a lowercase hyphenated identifier.
+/** Apply field edits without restating redacted secrets; unsetting an array index removes its element.
+ * @param ns Profile entry id.
+ * @param ops Ordered form edits.
+ * @param expectedRevision Revision returned by describe.
  */
-async replace<const Namespace extends string>( ns: Namespace & SettingsNamespaceInput<Namespace>, section: object, expectedRevision?: number, ): Promise<void>
-
-/**
- * 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}.
- * @throws {TypeError} when `ns` is not a lowercase hyphenated identifier.
- */
-async mutate<const Namespace extends string>( ns: Namespace & SettingsNamespaceInput<Namespace>, ops: readonly SettingsPathOp[], expectedRevision?: number, ): Promise<void>
+async mutate(ns: string, ops: readonly SettingsPathOp[], expectedRevision?: number): Promise<void>
 ```
 
 Source: [`packages/settings/settings/src/index.ts`](../../packages/settings/settings/src/index.ts)
@@ -291,12 +87,6 @@ Host service backing the generated `ctx.remote.settings` namespace. Every remote
  */
 @Remote describe(): SettingsDescribeValue
 
-/**
- * Report whether this deployment can open an authored Agent preset directory natively.
- * @returns true when the matching open operation is available.
- */
-@Remote canOpenAgentPresetDirectory(): boolean
-
 /**
  * Merge a patch into one namespace's stored user section.
  * @param ns - namespace key to write.
@@ -336,15 +126,6 @@ Host service backing the generated `ctx.remote.settings` namespace. Every remote
  * @throws RemoteError when no document exists, preparation fails, or opening fails.
  */
 @Remote async openSettingsDocument(signal: AbortSignal): Promise<SettingsDocumentOpenValue>
-
-/**
- * Open one user-authored Agent preset directory or return its path when no native opener exists.
- * @param agentPreset - preset id resolved against Host-owned roots.
- * @param signal - caller lifetime; abort terminates the native command.
- * @returns an opened confirmation or the resolved directory for text display.
- * @throws RemoteError when the preset is missing, read-only, invalid, or cannot be opened.
- */
-@Remote async openAgentPresetDirectory( agentPreset: string, signal: AbortSignal, ): Promise<AgentPresetDirectoryOpenValue>
 ```
 
 Source: [`packages/api/settings-controller/src/index.ts`](../../packages/api/settings-controller/src/index.ts)
@@ -357,49 +138,18 @@ Source: [`packages/api/settings-controller/src/index.ts`](../../packages/api/set
 
 #### `settings/document-updated` — emit
 
-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`.
+One profile entry's form values, availability, or page policy changed. Form clients re-read its schema, resolved values, and revision.
 
 ```ts cordis-catalog
 /**
- * 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.
+ * One profile entry's form values, availability, or page policy changed.
+ * Form clients re-read its schema, resolved values, and revision.
+ * @param ns Profile entry id.
+ * @param revision The entry's new revision.
  * @mode emit
  */
 'settings/document-updated'(ns: SettingsNamespace, revision: number): void
 ```
 
-Source: [`packages/settings/settings/src/types.ts`](../../packages/settings/settings/src/types.ts)
-
-<a id="settingsupdated--emit"></a>
-
-#### `settings/updated` — emit
-
-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.
-
-```ts cordis-catalog
-/**
- * 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
-```
-
 Source: [`packages/settings/settings/src/types.ts`](../../packages/settings/settings/src/types.ts)
 <!-- END GENERATED cordis-surface -->