@leaf233/dsh-llm-rate-limiter 0.2.0 → 0.3.0

package/lib/index.js

@@ -2,28 +2,36 @@
  * dsh-llm-rate-limiter — Host (server-side) entry point.
  *
  * Intercepts the `llm/stream` waterfall and enforces per-model rate limits.
- * Configuration lives in the "llm-rate-limiter" settings namespace, editable
- * from the browser GUI.
+ *
+ * Configuration is the profile ENTRY's own `config` (this module's exported
+ * {@link Config} schema), read through the volatile references Cordis builds
+ * for it. `dsh-settings` projects the volatile fields of every active entry
+ * into a form the browser can edit, so the plugin ships no settings service
+ * of its own. (DSH 0.1.5 had a `ctx.settings.register()` namespace API; 0.1.7
+ * removed it, and its browser half dropped `settingsScope` for `configForms`.
+ * The migration record lives in CHANGELOG.md under `[0.3.0]`.)
  *
  * The `llm/stream` waterfall signature is:
  *   (options: GenerateOptions, next: () => AsyncIterable<StreamChunk>) => AsyncIterable<StreamChunk>
  *
  * where `options` always has `.provider` (string) and `.model` (string).
  *
- * The settings service is injected dynamically (like dshmarket's
- * installMarketSettings): `ctx.inject(['settings'], (scopedCtx) => ...)`, so a
- * host without a settings provider simply runs without the GUI wiring — the
- * composed entry stays as configured. Inherited from the DSH house pattern.
- *
  * @module dsh-llm-rate-limiter
  */
 
 import { TokenBucketStrategy } from "./strategies/token-bucket.js";
 import { SlidingWindowStrategy } from "./strategies/sliding-window.js";
-import { RateLimiterConfig } from "./types/config.js";
-import { CHANNEL, createStatusChannel } from "./status-rpc.js";
+import { Config } from "./types/config.js";
+import { CHANNEL, createChannelRoute, createStatusChannel } from "./status-rpc.js";
 
 const name = "llm-rate-limiter";
+/**
+ * Settings namespace / profile entry id.
+ *
+ * `dsh-settings` keys every form by `entry.options.id` (`lib/index.js:432`),
+ * which is the `id` this plugin's `cordis.patch.yml` row declares. Renaming
+ * that row id therefore renames this namespace too — keep the two in step.
+ */
 const SETTINGS_NS = "llm-rate-limiter";
 
 /** Maximum retained events in the status ring (bounded memory). */
@@ -33,9 +41,45 @@ const SNAPSHOT_EVENT_COUNT = 8;
 
 /* ── Helpers ─────────────────────────────────────────────────────────── */
 
+/** Built-in defaults, used when a reference yields nothing (or no config at all). */
+const FALLBACK = {
+  enabled: true,
+  strategy: "token-bucket",
+  defaults: { maxConcurrent: 5, maxRpm: 60, burstSize: 10, refillRate: 1 },
+  models: {},
+  onThrottled: "queue",
+  maxQueueWaitMs: 60_000,
+};
+
+/**
+ * Read one volatile reference from the parsed Config.
+ *
+ * The loader mutates volatile references IN PLACE when only raw config values
+ * changed (`cordis-plugin-loader/lib/index.js:393` `_commitVolatile()`), so
+ * the reference object stays valid for the plugin's whole lifetime and its
+ * `get()` always yields the current value. Call this at each use rather than
+ * caching the unwrapped value.
+ *
+ * @param ref - a `.volatile()` field of the parsed Config, or undefined when
+ *   the entry was mounted with no config at all.
+ * @param fallback - value used when the reference is absent.
+ * @returns the current plain value.
+ */
+function read(ref, fallback) {
+  if (ref === undefined || ref === null) return fallback;
+  if (typeof ref.get === "function") {
+    const value = ref.get();
+    return value === undefined || value === null ? fallback : value;
+  }
+  return ref;
+}
+
 /**
  * Merge defaults + per-model overrides into a flat config object that both
  * strategy constructors understand.
+ *
+ * @param cfg - plain config object (`{ enabled, strategy, defaults, models, ... }`).
+ * @param key - `"provider/model"` of the call being limited.
  */
 function resolveModelConfig(cfg, key) {
   const o = cfg.models?.[key] ?? {};
@@ -92,22 +136,26 @@ function terminalChunk(modelKey, signal) {
 
 /**
  * @param {import("@deepseek-ai/cordis").Context} ctx
+ * @param {object} [config] - parsed Config; volatile fields are live references.
  */
-function apply(ctx) {
+function apply(ctx, config) {
   const logger = ctx.logger?.("rate-limiter");
 
-  // Shared mutable config state.  Starts with built-in defaults; once the
-  // settings service is available the watcher replaces it with the live
-  // user-configured value on every change.
-  const defaultBase = {
-    enabled: true,
-    strategy: "token-bucket",
-    defaults: { maxConcurrent: 5, maxRpm: 60, burstSize: 10, refillRate: 1 },
-    models: {},
-    onThrottled: "queue",
-    maxQueueWaitMs: 60_000,
-  };
-  let cfg = { ...defaultBase };
+  /**
+   * Snapshot the whole config as one plain object, reading each reference at
+   * call time. Derived settings are not cached: a volatile-only change updates
+   * the references in place without re-running `apply`.
+   */
+  function readConfig() {
+    return {
+      enabled: read(config?.enabled, FALLBACK.enabled),
+      strategy: read(config?.strategy, FALLBACK.strategy),
+      defaults: read(config?.defaults, FALLBACK.defaults),
+      models: read(config?.models, FALLBACK.models),
+      onThrottled: read(config?.onThrottled, FALLBACK.onThrottled),
+      maxQueueWaitMs: read(config?.maxQueueWaitMs, FALLBACK.maxQueueWaitMs),
+    };
+  }
 
   /** @type {Map<string, TokenBucketStrategy | SlidingWindowStrategy>} */
   const limiters = new Map();
@@ -135,6 +183,7 @@ function apply(ctx) {
 
   /** Build the JSON-safe snapshot served on the "snapshot" endpoint. */
   function buildSnapshot() {
+    const cfg = readConfig();
     const models = {};
     for (const [key, limiter] of limiters) {
       try {
@@ -162,57 +211,114 @@ function apply(ctx) {
     rev += 1;
   }
 
-  // ── Settings wiring (dynamic inject) ───────────────────────
-  // Wrapped in ctx.inject so the plugin works on older DSH versions that
-  // don't have a settings service at all — the callback simply never runs.
+  // ── Settings presentation (dynamic inject) ─────────────────
+  // This plugin ships its own browser page, so it opts out of any
+  // schema-generated page. Wrapped in ctx.inject so a host WITHOUT a settings
+  // service still runs the limiter — the callback simply never runs. The
+  // optional child ctx names the plugin fiber the policy belongs to, which is
+  // why `ctx.fiber` is passed explicitly (`dsh-settings/lib/index.js:370`).
   ctx.inject(["settings"], (scopedCtx) => {
-    const scope = scopedCtx.settings.register(SETTINGS_NS, RateLimiterConfig, {
-      base: defaultBase,
-    });
-
-    logger?.info("rate limiter settings namespace registered (%s)", SETTINGS_NS);
-
-    // Replace cfg with live settings value on every change.
-    cfg = scope.get();
-    scope.watch((c) => { cfg = c; });
-
-    // Dispose limiters on settings teardown.
-    scopedCtx.effect(() => () => {
-      logger?.info("rate limiter settings scope tearing down (%s)", SETTINGS_NS);
-      for (const limiter of limiters.values()) limiter.dispose();
-      limiters.clear();
-    }, "rate-limiter: settings scope teardown");
+    if (typeof scopedCtx.settings?.configure !== "function") return; // older/foreign settings seam: keep running
+    scopedCtx.effect(
+      () => scopedCtx.settings.configure({ auto: false }, ctx.fiber),
+      "rate-limiter: settings presentation",
+    );
   });
 
-  // ── Status RPC channel (dynamic inject) ────────────────────
+  // ── Status channel (dynamic inject) ────────────────────────
   // Same defensive shape as the settings wiring: on a host without a
   // connection service the callback never runs and the plugin stays silent.
-  // The registration is owned by this fiber, so unloading withdraws it.
+  // Either path below registers inside an effect owned by this fiber, so
+  // unloading the plugin withdraws the channel automatically.
+  //
+  // Two mounting paths exist, and both speak the same wire protocol, so the
+  // browser half never needs to know which one is live:
+  //
+  //   1. connection.rpc.handle(channel, handler) — the framework's generic
+  //      channel registry (preferred: the framework owns the route, the
+  //      request validation, and the withdrawal).
+  //
+  //   2. a self-registered prefix route reusing connection.requestRejection()
+  //      — the fallback for hosts where path 1 is broken. DSH 0.1.5-rc.3
+  //      changed dsh-client-connection's own `inject` from
+  //      ["webServer", "credentials"] to ["credentials"] while its
+  //      HostConnectionService.register() still dereferences
+  //      `owner.webServer`, and Cordis rebinds a cross-fiber service's `ctx`
+  //      to the *reader's* fiber — so rpc.handle() throws
+  //      'cannot get property "webServer" without inject'. Registering the
+  //      route on our own fiber (which injects webServer below) avoids that
+  //      while still using the framework's own 403/401 fence.
+  //      Still unfixed in 0.1.7-rc.1 (dsh-client-connection/lib/index.js:798
+  //      keeps `inject = ["credentials"]`), so the fallback still fires.
   ctx.inject(["connection"], (scopedCtx) => {
     const connection = scopedCtx.get("connection");
+    const channel = createStatusChannel({ buildSnapshot, resetTotals });
+
+    // ── Path 1: the framework's generic channel registry ──
     const handle = typeof connection?.rpc?.handle === "function"
       ? connection.rpc.handle.bind(connection.rpc)
       : undefined;
-    if (handle === undefined) return; // older host: degrade silently
 
+    if (handle !== undefined) {
+      try {
+        scopedCtx.effect(() => {
+          const unregister = handle(CHANNEL, channel);
+          return () => { unregister(); };
+        }, "rate-limiter: status rpc channel");
+        logger?.info("rate limiter status channel mounted via connection.rpc (%s)", CHANNEL);
+        return;
+      } catch (err) {
+        logger?.warn(
+          "connection.rpc channel registration failed (%s); falling back to a self-registered route",
+          err instanceof Error ? err.message : String(err),
+        );
+      }
+    }
+
+    // ── Path 2: self-registered route (needs webServer on THIS fiber) ──
+    // The fence is mandatory: without connection.requestRejection() we would
+    // be publishing an unauthenticated route, so we refuse to mount at all.
+    // Probing once here turns a broken fence into a mount-time refusal instead
+    // of a per-request surprise.
     try {
-      scopedCtx.effect(() => {
-        const unregister = handle(CHANNEL, createStatusChannel({ buildSnapshot, resetTotals }));
-        return () => { unregister(); };
-      }, "rate-limiter: status rpc channel");
+      if (typeof connection?.requestRejection !== "function") {
+        logger?.warn("connection.requestRejection unavailable; status channel not mounted");
+        return;
+      }
+      connection.requestRejection({ headers: {} });
     } catch (err) {
-      logger?.warn("status channel registration failed: %s", err instanceof Error ? err.message : String(err));
+      logger?.warn(
+        "connection.requestRejection unusable (%s); refusing to mount an unfenced status route",
+        err instanceof Error ? err.message : String(err),
+      );
       return;
     }
 
-    logger?.info("rate limiter status channel mounted (%s)", CHANNEL);
+    scopedCtx.inject(["webServer"], (webCtx) => {
+      const webServer = webCtx.get("webServer");
+      if (typeof webServer?.register !== "function") return; // no web carrier: degrade silently
+
+      try {
+        webCtx.effect(() => webServer.register(createChannelRoute({
+          channel: CHANNEL,
+          handler: channel,
+          reject: (req) => connection.requestRejection(req),
+        })), "rate-limiter: status route (self-registered)");
+      } catch (err) {
+        logger?.warn("status channel registration failed: %s", err instanceof Error ? err.message : String(err));
+        return;
+      }
+
+      logger?.info("rate limiter status channel mounted via self-registered route (%s)", CHANNEL);
+    });
   });
 
   // ── LLM stream interceptor ─────────────────────────────────
-  // ctx.on('llm/stream') doesn't need the settings service — it's a plain
-  // waterfall listener that reads the shared `cfg` variable (initialised
-  // with defaults; replaced by the settings watcher when available).
+  // Reads the live Config on every call, so a settings edit that reaches the
+  // loader takes effect on the next request without a restart.
   const disposeLlmListener = ctx.on("llm/stream", async function* rateLimitInterceptor(options, next) {
+    const cfg = readConfig();
+
     if (!cfg.enabled) {
       yield* next();
       return;
@@ -297,4 +403,4 @@ function apply(ctx) {
   logger?.info("rate limiter active — llm/stream interceptor registered");
 }
 
-export { apply, name, SETTINGS_NS };
+export { apply, name, SETTINGS_NS, Config };

package/lib/status-rpc.js

@@ -2,15 +2,27 @@
  * dsh-llm-rate-limiter — status RPC channel (Host half).
  *
  * Exposes live rate-limiter statistics to the browser over the framework's
- * generic Connection RPC channel — the same idiom dsh-context uses for its
- * detail channel. The framework supplies POST+JSON transport, the Host/Origin
- * fence (403) and browser authentication (401); this module only answers
- * endpoints and shapes envelopes.
+ * generic Connection RPC channel. The framework supplies POST+JSON transport,
+ * the Host/Origin fence (403) and browser authentication (401); this module
+ * only answers endpoints and shapes envelopes.
  *
- * Registration is owned by the calling fiber (`register()` wraps
- * `owner.webServer.register` in `owner.effect`), so unloading the plugin
- * withdraws the channel automatically — there is no connection bookkeeping
- * here.
+ * Two mounting paths exist, and both speak the *same* wire protocol so the
+ * browser half never needs to know which one is active:
+ *
+ *  1. `connection.rpc.handle(channel, handler)` — the framework's own generic
+ *     channel registry. Preferred: the framework owns the route, the request
+ *     validation, and the fiber-scoped withdrawal.
+ *
+ *  2. `createChannelRoute({ channel, handler, reject })` — a self-registered
+ *     prefix route for hosts where path 1 is broken. DSH 0.1.5-rc.3 changed
+ *     `@deepseek-ai/dsh-client-connection`'s own `inject` from
+ *     `["webServer", "credentials"]` to `["credentials"]` while
+ *     `HostConnectionService.register()` still dereferences
+ *     `owner.webServer`, so `rpc.handle` throws
+ *     `cannot get property "webServer" without inject`. This route is
+ *     registered on our own fiber (which *can* see `webServer`) and reuses the
+ *     connection service's public `requestRejection()` fence, so the 403/401
+ *     policy is still the framework's.
  *
  * Envelope contract (mirrors the Connection wire schema):
  *   success: { ok: true,  value: <JSON-safe> }
@@ -25,6 +37,27 @@
  */
 const CHANNEL = "/llm-rate-limiter";
 
+/**
+ * Endpoint grammar for one path segment, copied verbatim from the framework's
+ * `ENDPOINT_SEGMENT_PATTERN` in dsh-client-connection. Keeping it identical is
+ * what makes the self-registered route accept and reject exactly the same URLs
+ * as `rpc.handle` would.
+ */
+const ENDPOINT_SEGMENT_PATTERN = /^[A-Za-z0-9_$.-]+$/;
+
+/**
+ * Buffered-body cap for the self-registered route. Both endpoints are called
+ * with an empty payload, so this is a defensive memory bound rather than a
+ * real limit (the framework uses its own, much larger, carrier cap).
+ */
+const MAX_REQUEST_BODY_BYTES = 1024 * 1024;
+
+/**
+ * Correlation id echoed when the request envelope cannot be parsed at all —
+ * the same literal the framework uses (`INVALID_REQUEST_RPC_ID`).
+ */
+const INVALID_REQUEST_RPC_ID = "invalid-request";
+
 /**
  * Build a failure envelope. Field-for-field the same shape the Connection
  * host accepts, so callers can rely on `ok` discrimination alone.
@@ -64,4 +97,189 @@ function createStatusChannel({ buildSnapshot, resetTotals }) {
   };
 }
 
-export { CHANNEL, createStatusChannel, failure, success };
+/* ── self-registered route (the DSH 0.1.5-rc.3 fallback) ───────────────── */
+
+/** Narrow an unknown JSON value to a plain object. */
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Extract the endpoint from a channel-relative pathname, mirroring the
+ * framework's `endpointFromPath`: a single `channel/<endpoint>` segment whose
+ * segments all satisfy {@link ENDPOINT_SEGMENT_PATTERN}.
+ *
+ * @param {string} channel - the channel prefix (e.g. `/llm-rate-limiter`).
+ * @param {string} pathname - request pathname.
+ * @returns {string | undefined} the endpoint, or undefined when the URL is not
+ *   a well-formed member of this channel.
+ */
+function endpointFromPath(channel, pathname) {
+  if (!pathname.startsWith(`${channel}/`)) return undefined;
+  const endpoint = pathname.slice(channel.length + 1);
+  const segments = endpoint.split("/");
+  if (segments.some((segment) => segment === "" || segment === "." || segment === ".." || !ENDPOINT_SEGMENT_PATTERN.test(segment))) return undefined;
+  return endpoint;
+}
+
+/**
+ * Read and decode the request body, refusing anything above `limit` bytes so a
+ * hostile caller cannot make the host buffer without bound.
+ *
+ * @param {import("node:http").IncomingMessage} req - node request stream.
+ * @param {number} limit - maximum accepted byte count.
+ * @returns {Promise<string>} the decoded UTF-8 body.
+ * @throws {Error & { code: "TOO_LARGE" }} when the body exceeds `limit`.
+ */
+async function readBody(req, limit) {
+  const chunks = [];
+  let received = 0;
+  for await (const chunk of req) {
+    const buffer = typeof chunk === "string" ? Buffer.from(chunk) : chunk;
+    received += buffer.byteLength;
+    if (received > limit) {
+      const error = new Error("request body too large");
+      error.code = "TOO_LARGE";
+      throw error;
+    }
+    chunks.push(buffer);
+  }
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+/**
+ * Write one `server-response` envelope as JSON — byte-for-byte the shape
+ * `Response.json(...)` produces on the framework's own route.
+ *
+ * @param {import("node:http").ServerResponse} res - response to own.
+ * @param {string} rpcId - correlation id to echo.
+ * @param {object} result - the `{ ok, value }` / `{ ok, error }` envelope.
+ */
+function sendEnvelope(res, rpcId, result) {
+  res.writeHead(200, { "content-type": "application/json" });
+  res.end(JSON.stringify({ type: "server-response", rpcId, result }));
+}
+
+/**
+ * Build a webserver prefix route that speaks the Connection RPC wire protocol.
+ *
+ * This is the fallback carrier for {@link createStatusChannel} on hosts where
+ * `connection.rpc.handle` throws. Every request-shape decision mirrors the
+ * framework's `rpcFetchHandler` so the browser half is byte-compatible with the
+ * preferred path:
+ *
+ * | condition | response |
+ * |---|---|
+ * | fence/auth rejected by `reject` | `403` (or `401`) + `forbidden`/`unauthorized` |
+ * | non-POST, or URL outside the channel | `404 not found` |
+ * | `content-type` not `application/json` | `415` |
+ * | body over {@link MAX_REQUEST_BODY_BYTES} | `413` |
+ * | body not JSON | `400 body is not JSON` |
+ * | envelope not a `client-request` | `gateway/bad-request` envelope |
+ * | `method` ≠ endpoint | `gateway/bad-request` envelope |
+ * | handler threw | `500 handler failure: ...` |
+ * | otherwise | `200` + `server-response` envelope |
+ *
+ * @param {object} deps
+ * @param {string} deps.channel - channel prefix to own (e.g. `/llm-rate-limiter`).
+ * @param {(endpoint: string, payload: unknown, signal?: AbortSignal) => Promise<object>} deps.handler - endpoint dispatcher.
+ * @param {(req: import("node:http").IncomingMessage) => number | undefined} deps.reject - the framework's `connection.requestRejection` fence; returns an HTTP status to refuse with, or undefined to allow.
+ * @returns {{ kind: "prefix", path: string, handler: (req: import("node:http").IncomingMessage, res: import("node:http").ServerResponse) => Promise<void> }}
+ */
+function createChannelRoute({ channel, handler, reject }) {
+  return {
+    kind: "prefix",
+    path: channel,
+    handler: async (req, res) => {
+      // 1. The framework's own fence: Host/Origin trust (403) then browser
+      //    authentication (401). Reusing it keeps the security policy identical.
+      const rejection = reject(req);
+      if (rejection !== undefined) {
+        res.writeHead(rejection);
+        res.end(rejection === 401 ? "unauthorized" : "forbidden");
+        return;
+      }
+
+      // 2. POST-only, and only inside this channel (framework: 404 otherwise).
+      const url = new URL(req.url ?? "/", "http://dsh.internal");
+      const endpoint = endpointFromPath(channel, url.pathname);
+      if (req.method !== "POST" || endpoint === undefined) {
+        res.writeHead(404);
+        res.end("not found");
+        return;
+      }
+
+      // 3. JSON only (framework: 415).
+      const mediaType = String(req.headers["content-type"] ?? "").split(";", 1)[0].trim().toLowerCase();
+      if (mediaType !== "application/json") {
+        res.writeHead(415);
+        res.end("content type must be application/json");
+        return;
+      }
+
+      // 4. Buffer the body under a defensive cap, then parse it.
+      let raw;
+      try {
+        raw = await readBody(req, MAX_REQUEST_BODY_BYTES);
+      } catch (error) {
+        if (error?.code === "TOO_LARGE") {
+          res.writeHead(413, { connection: "close" });
+          res.end();
+          req.destroy?.();
+          return;
+        }
+        throw error;
+      }
+      let body;
+      try {
+        body = JSON.parse(raw);
+      } catch {
+        res.writeHead(400);
+        res.end("body is not JSON");
+        return;
+      }
+
+      // 5. Validate the client-request envelope; echo the correlation id
+      //    whenever it is a string, exactly like the framework does.
+      const rpcId = typeof body?.rpcId === "string" ? body.rpcId : INVALID_REQUEST_RPC_ID;
+      if (!isRecord(body) || body.type !== "client-request" || typeof body.rpcId !== "string" || typeof body.method !== "string") {
+        sendEnvelope(res, rpcId, failure("gateway/bad-request", "invalid client-request message", { issues: [] }));
+        return;
+      }
+      if (body.method !== endpoint) {
+        sendEnvelope(res, rpcId, failure(
+          "gateway/bad-request",
+          `method ${JSON.stringify(body.method)} does not match endpoint ${JSON.stringify(endpoint)}`,
+          { issues: [] },
+        ));
+        return;
+      }
+
+      // 6. Dispatch. Tie the signal to the response lifetime, as the framework's
+      //    http bridge does, so a dropped client can cancel the work.
+      const abort = new AbortController();
+      res.on?.("close", () => {
+        if (!res.writableEnded) abort.abort();
+      });
+      let result;
+      try {
+        result = await handler(endpoint, body.payload, abort.signal);
+      } catch (error) {
+        res.writeHead(500);
+        res.end(`handler failure: ${String(error)}`);
+        return;
+      }
+      sendEnvelope(res, rpcId, result);
+    },
+  };
+}
+
+export {
+  CHANNEL,
+  MAX_REQUEST_BODY_BYTES,
+  createChannelRoute,
+  createStatusChannel,
+  endpointFromPath,
+  failure,
+  success,
+};

package/lib/types/config.js

@@ -1,8 +1,15 @@
 /**
  * Rate limiter configuration schema.
  *
- * The settings namespace is "llm-rate-limiter".  Users override values through
- * the DSH settings document; the host merges them on top of `base`.
+ * The plugin's Config is the profile entry's own schema: Cordis validates the
+ * entry's `config` against it, so the host reads values from the references
+ * this schema produces rather than from a settings namespace.
+ *
+ * Fields marked `.volatile()` become separately addressable live references
+ * (`config.enabled.get()`). Only volatile fields appear in the settings form
+ * (`dsh-settings`'s `volatileForm()`), and an entry whose Config has NO
+ * volatile field is dropped from the form list entirely — so the set of
+ * `.volatile()` marks below IS the settings UI's field list.
  *
  * @module dsh-llm-rate-limiter/types/config
  */
@@ -12,6 +19,12 @@ import Schema from "@deepseek-ai/schemastery";
 /**
  * Per-model overrides — key is `"provider/model"` (e.g. `"deepseek/deepseek-chat"`).
  * Every field is optional; omitted fields inherit from `defaults`.
+ *
+ * This sub-schema deliberately carries NO `.volatile()`: it is the `inner`
+ * of a `dict`, and two volatile layers on one path are rejected
+ * (`volatile fields require a fixed object path without an enclosing volatile
+ * field`, `schemastery/lib/index.mjs:246`). The whole `models` dict is made
+ * volatile instead — see below.
  */
 const ModelOverride = Schema.object({
   maxConcurrent: Schema.number().step(1).min(1).description("Max concurrent requests for this model"),
@@ -21,33 +34,52 @@ const ModelOverride = Schema.object({
   enabled: Schema.boolean().description("Enable/disable rate limiting for this model"),
 });
 
-export const RateLimiterConfig = Schema.object({
+/**
+ * Per-model defaults — applied to every model unless overridden.
+ * The object is volatile AS A WHOLE so `config.defaults.get()` yields one
+ * plain object and the settings form edits `["defaults", field]` paths.
+ */
+const Defaults = Schema.object({
+  maxConcurrent: Schema.number().step(1).min(1).default(5).description("Max concurrent requests"),
+  maxRpm: Schema.number().step(1).min(1).default(60).description("Max requests per minute"),
+  burstSize: Schema.number().step(1).min(1).default(10).description("Burst capacity (token-bucket)"),
+  refillRate: Schema.number().min(0.1).default(1).description("Tokens per second (token-bucket)"),
+});
+
+export const Config = Schema.object({
   /** Master switch */
-  enabled: Schema.boolean().default(true).description("Enable the rate limiter globally"),
+  enabled: Schema.boolean().default(true).volatile().description("Enable the rate limiter globally"),
 
   /** Default strategy */
   strategy: Schema.union([
     Schema.const("token-bucket").description("Token Bucket — allows bursts up to burstSize"),
     Schema.const("sliding-window").description("Sliding Window — smooth, fixed requests-per-minute"),
-  ]).default("token-bucket").description("Rate limiting algorithm"),
+  ]).default("token-bucket").volatile().description("Rate limiting algorithm"),
 
   /** Global defaults — applied to every model unless overridden */
-  defaults: Schema.object({
-    maxConcurrent: Schema.number().step(1).min(1).default(5).description("Max concurrent requests"),
-    maxRpm: Schema.number().step(1).min(1).default(60).description("Max requests per minute"),
-    burstSize: Schema.number().step(1).min(1).default(10).description("Burst capacity (token-bucket)"),
-    refillRate: Schema.number().min(0.1).default(1).description("Tokens per second (token-bucket)"),
-  }).default({}).description("Default limits applied to all models"),
+  defaults: Defaults.default({}).volatile().description("Default limits applied to all models"),
 
-  /** Per-model overrides — key is "provider/model" */
-  models: Schema.dict(ModelOverride).description("Per-model rate limit overrides"),
+  /**
+   * Per-model overrides — key is "provider/model".
+   *
+   * WHOLE-BLOCK volatile: `dict(inner).volatile()`, never
+   * `dict(inner.volatile())`. The latter marks the dict's `inner` while the
+   * `sKey`/`inner` nodes are "blocked" (`schemastery/lib/index.mjs:249-250`),
+   * which throws at validation time.
+   *
+   * Because `isVolatilePath` (`dsh-settings/lib/index.js:153-158`) returns
+   * true on reaching ANY volatile node without inspecting its descendants,
+   * paths such as `["models", "provider/model", "maxRpm"]` remain writable
+   * through the settings form under this whole-block mark.
+   */
+  models: Schema.dict(ModelOverride).default({}).volatile().description("Per-model rate limit overrides"),
 
   /** Queue behaviour when a request is throttled */
   onThrottled: Schema.union([
     Schema.const("queue").description("Wait in queue until a slot opens"),
     Schema.const("reject").description("Immediately return an error"),
-  ]).default("queue").description("What happens when a request exceeds the limit"),
+  ]).default("queue").volatile().description("What happens when a request exceeds the limit"),
 
   /** Maximum time a request waits in queue before being rejected */
-  maxQueueWaitMs: Schema.number().step(1).min(1000).default(60_000).description("Max queue wait (ms)"),
-}).description("LLM call rate limiter settings");
+  maxQueueWaitMs: Schema.number().step(1).min(1000).default(60_000).volatile().description("Max queue wait (ms)"),
+}).description("LLM call rate limiter settings");

package/lib/types/index.js

@@ -1 +1 @@
-export { RateLimiterConfig } from "./config.js";
+export { Config } from "./config.js";