@objectstack/service-settings 9.2.0 → 9.3.0

package/dist/index.d.cts

@@ -231,6 +231,19 @@ declare class UnknownKeyError extends Error {
     readonly code: "SETTINGS_UNKNOWN_KEY";
     constructor(namespace: string, key: string);
 }
+/**
+ * Thrown when a write would leave the namespace in an invalid state —
+ * a `required` field that is visible under the post-write values is
+ * empty (e.g. provider=cloudflare saved without an API key). The whole
+ * batch is rejected; `fields` maps each offending key to a message the
+ * UI can render inline.
+ */
+declare class SettingsValidationError extends Error {
+    readonly namespace: string;
+    readonly fields: Record<string, string>;
+    readonly code: "SETTINGS_VALIDATION";
+    constructor(namespace: string, fields: Record<string, string>);
+}
 
 /**
  * Concrete SettingsService. See `src/settings-service.types.ts` for
@@ -325,6 +338,32 @@ declare class SettingsService {
     set(namespace: string, key: string, value: unknown, ctx?: SettingsContext): Promise<ResolvedSettingValue>;
     /** Persist multiple keys atomically (best-effort). */
     setMany(namespace: string, patch: Record<string, unknown>, ctx?: SettingsContext): Promise<Record<string, ResolvedSettingValue>>;
+    /**
+     * Save-time validation for `setMany`, fulfilling the spec promise that
+     * `required` is enforced server-side and hidden specifiers are not
+     * validated. Semantics, tuned to reject broken configs without
+     * breaking unrelated single-key writes:
+     *
+     * - The post-write value map is computed (current values overlaid
+     *   with the patch; `null` patch entries fall back to the default).
+     * - A specifier is checked only when the patch TOUCHES it — its own
+     *   key is in the patch, or a key its `visible` expression references
+     *   is (switching provider must validate that provider's fields).
+     * - `required` + visible + empty → rejected.
+     * - `pattern` (text fields) + non-empty value that mismatches → rejected.
+     * - All-null patches (namespace reset) and unparseable visibility
+     *   expressions skip validation rather than block the write.
+     */
+    private validatePatch;
+    /**
+     * Clear every persisted row in a namespace so values fall back to
+     * env/defaults. Env-locked keys are untouched (env wins over rows
+     * anyway and refuses writes). Persisted rows are nulled rather than
+     * deleted so the audit trail records the reset per key.
+     *
+     * Returns the number of cleared keys.
+     */
+    resetNamespace(namespace: string, ctx?: SettingsContext): Promise<number>;
     /** Invoke a declared action (test connection, rotate, …). */
     runAction(namespace: string, actionId: string, payload: unknown, ctx?: SettingsContext): Promise<SettingsActionResult>;
     private loadRows;
@@ -376,6 +415,39 @@ declare class LocalCryptoProvider implements ICryptoProvider {
  */
 declare const InMemoryCryptoProvider: typeof LocalCryptoProvider;
 
+/**
+ * Evaluator for the restricted visibility expressions used by settings
+ * manifests, e.g. `"${data.provider === 'cloudflare'}"` or
+ * `"${data.embedder_provider && data.embedder_provider !== 'none'}"`.
+ *
+ * The server needs these at save time so `setMany` can enforce `required`
+ * only on fields that are actually visible for the current provider —
+ * a half-filled Cloudflare form must be rejected, while OpenAI fields
+ * stay irrelevant. The console UI evaluates the same strings client-side;
+ * this is deliberately NOT a general JS evaluator, just the tiny grammar
+ * the manifests use:
+ *
+ *   orExpr   := andExpr ('||' andExpr)*
+ *   andExpr  := unary ('&&' unary)*
+ *   unary    := '!' unary | comparison
+ *   compare  := primary (('===' | '!==' | '==' | '!=') primary)?
+ *   primary  := '(' orExpr ')' | string | number | true | false | null | data.<ident>
+ *
+ * Anything outside the grammar throws `VisibilityParseError`; callers
+ * should treat that as "cannot determine visibility" and skip validation
+ * for the field (lenient) rather than block the save.
+ */
+declare class VisibilityParseError extends Error {
+    constructor(expr: string, detail: string);
+}
+/** `data.*` keys referenced by a visibility expression (regex-level scan). */
+declare function referencedKeys(visible: unknown): string[];
+/**
+ * Evaluate a visibility expression against the merged form data.
+ * Throws {@link VisibilityParseError} for anything outside the grammar.
+ */
+declare function evaluateVisibility(visible: unknown, data: Record<string, unknown>): boolean;
+
 /** Configuration options for the SettingsServicePlugin. */
 interface SettingsServicePluginOptions {
     /**
@@ -644,4 +716,4 @@ declare const jaJP: TranslationData;
 
 declare const settingsBuiltinTranslations: TranslationBundle;
 
-export { type CryptoAdapter, type CryptoMode, InMemoryCryptoProvider, type KeySource, LocalCryptoProvider, type LocalCryptoProviderOptions, NoopCryptoAdapter, SETTINGS_PLUGIN_ID, SETTINGS_PLUGIN_VERSION, type SettingsActionHandler, type SettingsAuditSink, type SettingsContext, type SettingsEngine, SettingsLockedError, type SettingsRoutesOptions, type SettingsRow, SettingsService, type SettingsServiceOptions, SettingsServicePlugin, type SettingsServicePluginOptions, UnknownKeyError, UnknownNamespaceError, brandingSettingsManifest, builtinSettingsManifests, envKeyOf, featureFlagsSettingsManifest, mailSettingsManifest, mailTestActionHandler, registerSettingsRoutes, settingsBuiltinTranslations, settingsObjects, settingsPluginManifestHeader, en as settingsTranslationsEn, jaJP as settingsTranslationsJaJP, zhCN as settingsTranslationsZhCN, storageSettingsManifest, storageTestActionHandler };
+export { type CryptoAdapter, type CryptoMode, InMemoryCryptoProvider, type KeySource, LocalCryptoProvider, type LocalCryptoProviderOptions, NoopCryptoAdapter, SETTINGS_PLUGIN_ID, SETTINGS_PLUGIN_VERSION, type SettingsActionHandler, type SettingsAuditSink, type SettingsContext, type SettingsEngine, SettingsLockedError, type SettingsRoutesOptions, type SettingsRow, SettingsService, type SettingsServiceOptions, SettingsServicePlugin, type SettingsServicePluginOptions, SettingsValidationError, UnknownKeyError, UnknownNamespaceError, VisibilityParseError, brandingSettingsManifest, builtinSettingsManifests, envKeyOf, evaluateVisibility, featureFlagsSettingsManifest, mailSettingsManifest, mailTestActionHandler, referencedKeys, registerSettingsRoutes, settingsBuiltinTranslations, settingsObjects, settingsPluginManifestHeader, en as settingsTranslationsEn, jaJP as settingsTranslationsJaJP, zhCN as settingsTranslationsZhCN, storageSettingsManifest, storageTestActionHandler };

package/dist/index.d.ts

@@ -231,6 +231,19 @@ declare class UnknownKeyError extends Error {
     readonly code: "SETTINGS_UNKNOWN_KEY";
     constructor(namespace: string, key: string);
 }
+/**
+ * Thrown when a write would leave the namespace in an invalid state —
+ * a `required` field that is visible under the post-write values is
+ * empty (e.g. provider=cloudflare saved without an API key). The whole
+ * batch is rejected; `fields` maps each offending key to a message the
+ * UI can render inline.
+ */
+declare class SettingsValidationError extends Error {
+    readonly namespace: string;
+    readonly fields: Record<string, string>;
+    readonly code: "SETTINGS_VALIDATION";
+    constructor(namespace: string, fields: Record<string, string>);
+}
 
 /**
  * Concrete SettingsService. See `src/settings-service.types.ts` for
@@ -325,6 +338,32 @@ declare class SettingsService {
     set(namespace: string, key: string, value: unknown, ctx?: SettingsContext): Promise<ResolvedSettingValue>;
     /** Persist multiple keys atomically (best-effort). */
     setMany(namespace: string, patch: Record<string, unknown>, ctx?: SettingsContext): Promise<Record<string, ResolvedSettingValue>>;
+    /**
+     * Save-time validation for `setMany`, fulfilling the spec promise that
+     * `required` is enforced server-side and hidden specifiers are not
+     * validated. Semantics, tuned to reject broken configs without
+     * breaking unrelated single-key writes:
+     *
+     * - The post-write value map is computed (current values overlaid
+     *   with the patch; `null` patch entries fall back to the default).
+     * - A specifier is checked only when the patch TOUCHES it — its own
+     *   key is in the patch, or a key its `visible` expression references
+     *   is (switching provider must validate that provider's fields).
+     * - `required` + visible + empty → rejected.
+     * - `pattern` (text fields) + non-empty value that mismatches → rejected.
+     * - All-null patches (namespace reset) and unparseable visibility
+     *   expressions skip validation rather than block the write.
+     */
+    private validatePatch;
+    /**
+     * Clear every persisted row in a namespace so values fall back to
+     * env/defaults. Env-locked keys are untouched (env wins over rows
+     * anyway and refuses writes). Persisted rows are nulled rather than
+     * deleted so the audit trail records the reset per key.
+     *
+     * Returns the number of cleared keys.
+     */
+    resetNamespace(namespace: string, ctx?: SettingsContext): Promise<number>;
     /** Invoke a declared action (test connection, rotate, …). */
     runAction(namespace: string, actionId: string, payload: unknown, ctx?: SettingsContext): Promise<SettingsActionResult>;
     private loadRows;
@@ -376,6 +415,39 @@ declare class LocalCryptoProvider implements ICryptoProvider {
  */
 declare const InMemoryCryptoProvider: typeof LocalCryptoProvider;
 
+/**
+ * Evaluator for the restricted visibility expressions used by settings
+ * manifests, e.g. `"${data.provider === 'cloudflare'}"` or
+ * `"${data.embedder_provider && data.embedder_provider !== 'none'}"`.
+ *
+ * The server needs these at save time so `setMany` can enforce `required`
+ * only on fields that are actually visible for the current provider —
+ * a half-filled Cloudflare form must be rejected, while OpenAI fields
+ * stay irrelevant. The console UI evaluates the same strings client-side;
+ * this is deliberately NOT a general JS evaluator, just the tiny grammar
+ * the manifests use:
+ *
+ *   orExpr   := andExpr ('||' andExpr)*
+ *   andExpr  := unary ('&&' unary)*
+ *   unary    := '!' unary | comparison
+ *   compare  := primary (('===' | '!==' | '==' | '!=') primary)?
+ *   primary  := '(' orExpr ')' | string | number | true | false | null | data.<ident>
+ *
+ * Anything outside the grammar throws `VisibilityParseError`; callers
+ * should treat that as "cannot determine visibility" and skip validation
+ * for the field (lenient) rather than block the save.
+ */
+declare class VisibilityParseError extends Error {
+    constructor(expr: string, detail: string);
+}
+/** `data.*` keys referenced by a visibility expression (regex-level scan). */
+declare function referencedKeys(visible: unknown): string[];
+/**
+ * Evaluate a visibility expression against the merged form data.
+ * Throws {@link VisibilityParseError} for anything outside the grammar.
+ */
+declare function evaluateVisibility(visible: unknown, data: Record<string, unknown>): boolean;
+
 /** Configuration options for the SettingsServicePlugin. */
 interface SettingsServicePluginOptions {
     /**
@@ -644,4 +716,4 @@ declare const jaJP: TranslationData;
 
 declare const settingsBuiltinTranslations: TranslationBundle;
 
-export { type CryptoAdapter, type CryptoMode, InMemoryCryptoProvider, type KeySource, LocalCryptoProvider, type LocalCryptoProviderOptions, NoopCryptoAdapter, SETTINGS_PLUGIN_ID, SETTINGS_PLUGIN_VERSION, type SettingsActionHandler, type SettingsAuditSink, type SettingsContext, type SettingsEngine, SettingsLockedError, type SettingsRoutesOptions, type SettingsRow, SettingsService, type SettingsServiceOptions, SettingsServicePlugin, type SettingsServicePluginOptions, UnknownKeyError, UnknownNamespaceError, brandingSettingsManifest, builtinSettingsManifests, envKeyOf, featureFlagsSettingsManifest, mailSettingsManifest, mailTestActionHandler, registerSettingsRoutes, settingsBuiltinTranslations, settingsObjects, settingsPluginManifestHeader, en as settingsTranslationsEn, jaJP as settingsTranslationsJaJP, zhCN as settingsTranslationsZhCN, storageSettingsManifest, storageTestActionHandler };
+export { type CryptoAdapter, type CryptoMode, InMemoryCryptoProvider, type KeySource, LocalCryptoProvider, type LocalCryptoProviderOptions, NoopCryptoAdapter, SETTINGS_PLUGIN_ID, SETTINGS_PLUGIN_VERSION, type SettingsActionHandler, type SettingsAuditSink, type SettingsContext, type SettingsEngine, SettingsLockedError, type SettingsRoutesOptions, type SettingsRow, SettingsService, type SettingsServiceOptions, SettingsServicePlugin, type SettingsServicePluginOptions, SettingsValidationError, UnknownKeyError, UnknownNamespaceError, VisibilityParseError, brandingSettingsManifest, builtinSettingsManifests, envKeyOf, evaluateVisibility, featureFlagsSettingsManifest, mailSettingsManifest, mailTestActionHandler, referencedKeys, registerSettingsRoutes, settingsBuiltinTranslations, settingsObjects, settingsPluginManifestHeader, en as settingsTranslationsEn, jaJP as settingsTranslationsJaJP, zhCN as settingsTranslationsZhCN, storageSettingsManifest, storageTestActionHandler };

package/dist/index.js

@@ -48,6 +48,178 @@ var UnknownKeyError = class extends Error {
     this.code = "SETTINGS_UNKNOWN_KEY";
   }
 };
+var SettingsValidationError = class extends Error {
+  constructor(namespace, fields) {
+    super(
+      `Settings for '${namespace}' are incomplete: ` + Object.entries(fields).map(([k, msg]) => `${k} \u2014 ${msg}`).join("; ")
+    );
+    this.namespace = namespace;
+    this.fields = fields;
+    this.code = "SETTINGS_VALIDATION";
+  }
+};
+
+// src/visibility-eval.ts
+var VisibilityParseError = class extends Error {
+  constructor(expr, detail) {
+    super(`Cannot parse visibility expression "${expr}": ${detail}`);
+    this.name = "VisibilityParseError";
+  }
+};
+function visibilitySource(visible) {
+  let src;
+  if (typeof visible === "string") src = visible;
+  else if (visible && typeof visible === "object" && typeof visible.source === "string") {
+    src = visible.source;
+  }
+  if (src === void 0) return void 0;
+  const trimmed = src.trim();
+  if (trimmed.startsWith("${") && trimmed.endsWith("}")) return trimmed.slice(2, -1).trim();
+  return trimmed;
+}
+function referencedKeys(visible) {
+  const src = visibilitySource(visible);
+  if (!src) return [];
+  return [...src.matchAll(/data\.([A-Za-z_][A-Za-z0-9_]*)/g)].map((m) => m[1]);
+}
+function tokenize(expr) {
+  const tokens = [];
+  let i = 0;
+  while (i < expr.length) {
+    const ch = expr[i];
+    if (/\s/.test(ch)) {
+      i++;
+      continue;
+    }
+    if (ch === "(" || ch === ")") {
+      tokens.push({ kind: "punct", value: ch });
+      i++;
+      continue;
+    }
+    let matchedOp = false;
+    for (const op of ["===", "!==", "==", "!=", "&&", "||"]) {
+      if (expr.startsWith(op, i)) {
+        tokens.push({ kind: "punct", value: op });
+        i += op.length;
+        matchedOp = true;
+        break;
+      }
+    }
+    if (matchedOp) continue;
+    if (ch === "!") {
+      tokens.push({ kind: "punct", value: "!" });
+      i++;
+      continue;
+    }
+    if (ch === "'" || ch === '"') {
+      const quote = ch;
+      let j = i + 1;
+      let out = "";
+      while (j < expr.length && expr[j] !== quote) {
+        if (expr[j] === "\\" && j + 1 < expr.length) {
+          out += expr[j + 1];
+          j += 2;
+        } else {
+          out += expr[j];
+          j++;
+        }
+      }
+      if (j >= expr.length) throw new VisibilityParseError(expr, "unterminated string");
+      tokens.push({ kind: "string", value: out });
+      i = j + 1;
+      continue;
+    }
+    if (/[0-9]/.test(ch)) {
+      const m = /^[0-9]+(\.[0-9]+)?/.exec(expr.slice(i));
+      tokens.push({ kind: "number", value: Number(m[0]) });
+      i += m[0].length;
+      continue;
+    }
+    if (/[A-Za-z_]/.test(ch)) {
+      const m = /^[A-Za-z_][A-Za-z0-9_.]*/.exec(expr.slice(i));
+      const word = m[0];
+      if (word === "true") tokens.push({ kind: "keyword", value: true });
+      else if (word === "false") tokens.push({ kind: "keyword", value: false });
+      else if (word === "null") tokens.push({ kind: "keyword", value: null });
+      else if (word.startsWith("data.")) {
+        const key = word.slice("data.".length);
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) throw new VisibilityParseError(expr, `unsupported reference "${word}"`);
+        tokens.push({ kind: "ref", value: key });
+      } else throw new VisibilityParseError(expr, `unsupported identifier "${word}"`);
+      i += word.length;
+      continue;
+    }
+    throw new VisibilityParseError(expr, `unexpected character "${ch}"`);
+  }
+  return tokens;
+}
+function evaluateVisibility(visible, data) {
+  const src = visibilitySource(visible);
+  if (!src) return true;
+  const tokens = tokenize(src);
+  let pos = 0;
+  const peek = () => tokens[pos];
+  const eat = (value) => {
+    const t = tokens[pos];
+    if (t?.kind === "punct" && t.value === value) {
+      pos++;
+      return true;
+    }
+    return false;
+  };
+  function primary() {
+    const t = peek();
+    if (!t) throw new VisibilityParseError(src, "unexpected end of expression");
+    if (t.kind === "punct" && t.value === "(") {
+      pos++;
+      const v = orExpr();
+      if (!eat(")")) throw new VisibilityParseError(src, "missing closing parenthesis");
+      return v;
+    }
+    if (t.kind === "string" || t.kind === "number" || t.kind === "keyword") {
+      pos++;
+      return t.value;
+    }
+    if (t.kind === "ref") {
+      pos++;
+      return data[t.value];
+    }
+    throw new VisibilityParseError(src, `unexpected token`);
+  }
+  function comparison() {
+    const left = primary();
+    const t = peek();
+    if (t?.kind === "punct" && ["===", "!==", "==", "!="].includes(t.value)) {
+      pos++;
+      const right = primary();
+      return t.value === "===" || t.value === "==" ? left === right : left !== right;
+    }
+    return left;
+  }
+  function unary() {
+    if (eat("!")) return !unary();
+    return comparison();
+  }
+  function andExpr() {
+    let v = unary();
+    while (eat("&&")) {
+      const r = unary();
+      v = v && r;
+    }
+    return v;
+  }
+  function orExpr() {
+    let v = andExpr();
+    while (eat("||")) {
+      const r = andExpr();
+      v = v || r;
+    }
+    return v;
+  }
+  const result = orExpr();
+  if (pos !== tokens.length) throw new VisibilityParseError(src, "trailing tokens");
+  return Boolean(result);
+}
 
 // src/settings-service.ts
 var DEFAULT_OBJECT = "sys_setting";
@@ -333,6 +505,7 @@ var SettingsService = class {
         throw new SettingsLockedError(namespace, key, `locked-by-${upper.scope}`);
       }
     }
+    await this.validatePatch(namespace, patch, ctx);
     for (const [key, rawValue] of Object.entries(patch)) {
       const scope = reg.scopes.get(key);
       const userId = scope === "user" ? ctx.userId ?? null : null;
@@ -424,12 +597,111 @@ var SettingsService = class {
     }
     return out;
   }
+  /**
+   * Save-time validation for `setMany`, fulfilling the spec promise that
+   * `required` is enforced server-side and hidden specifiers are not
+   * validated. Semantics, tuned to reject broken configs without
+   * breaking unrelated single-key writes:
+   *
+   * - The post-write value map is computed (current values overlaid
+   *   with the patch; `null` patch entries fall back to the default).
+   * - A specifier is checked only when the patch TOUCHES it — its own
+   *   key is in the patch, or a key its `visible` expression references
+   *   is (switching provider must validate that provider's fields).
+   * - `required` + visible + empty → rejected.
+   * - `pattern` (text fields) + non-empty value that mismatches → rejected.
+   * - All-null patches (namespace reset) and unparseable visibility
+   *   expressions skip validation rather than block the write.
+   */
+  async validatePatch(namespace, patch, ctx) {
+    const reg = this.registry.get(namespace);
+    if (!reg) return;
+    const entries = Object.entries(patch);
+    if (entries.length === 0) return;
+    if (entries.every(([, v]) => v === null || typeof v === "undefined")) return;
+    const data = {};
+    for (const [key] of reg.scopes) {
+      data[key] = (await this.get(namespace, key, ctx)).value;
+    }
+    for (const [key, value] of entries) {
+      data[key] = value === null || typeof value === "undefined" ? reg.defaults.get(key) ?? null : value;
+    }
+    const patchKeys = new Set(Object.keys(patch));
+    const errors = {};
+    for (const spec of reg.manifest.specifiers ?? []) {
+      const key = spec.key;
+      const type = String(spec.type ?? "");
+      if (!key || LAYOUT_ONLY_TYPES.has(type)) continue;
+      let visible = true;
+      let deps = [];
+      if (typeof spec.visible !== "undefined") {
+        try {
+          visible = evaluateVisibility(spec.visible, data);
+          deps = referencedKeys(spec.visible);
+        } catch {
+          continue;
+        }
+      }
+      if (!visible) continue;
+      if (!patchKeys.has(key) && !deps.some((d) => patchKeys.has(d))) continue;
+      const value = data[key];
+      const label = typeof spec.label === "string" ? spec.label : key;
+      const empty = value === null || typeof value === "undefined" || typeof value === "string" && value.trim() === "";
+      if (spec.required === true && empty) {
+        errors[key] = `${label} is required for this configuration.`;
+        continue;
+      }
+      if (!empty && typeof spec.pattern === "string" && typeof value === "string") {
+        let re;
+        try {
+          re = new RegExp(spec.pattern);
+        } catch {
+          re = void 0;
+        }
+        if (re && !re.test(value)) {
+          const hint = typeof spec.description === "string" ? ` ${spec.description}` : "";
+          errors[key] = `${label} does not match the expected format.${hint}`;
+        }
+      }
+    }
+    if (Object.keys(errors).length > 0) {
+      throw new SettingsValidationError(namespace, errors);
+    }
+  }
+  /**
+   * Clear every persisted row in a namespace so values fall back to
+   * env/defaults. Env-locked keys are untouched (env wins over rows
+   * anyway and refuses writes). Persisted rows are nulled rather than
+   * deleted so the audit trail records the reset per key.
+   *
+   * Returns the number of cleared keys.
+   */
+  async resetNamespace(namespace, ctx = {}) {
+    const payload = await this.getNamespace(namespace, ctx);
+    const patch = {};
+    for (const [key, v] of Object.entries(payload.values)) {
+      if (v.source === "global" || v.source === "tenant" || v.source === "user") {
+        patch[key] = null;
+      }
+    }
+    const keys = Object.keys(patch);
+    if (keys.length > 0) await this.setMany(namespace, patch, ctx);
+    return keys.length;
+  }
   /** Invoke a declared action (test connection, rotate, …). */
   async runAction(namespace, actionId, payload, ctx = {}) {
     const reg = this.registry.get(namespace);
     if (!reg) throw new UnknownNamespaceError(namespace);
     const handler = reg.actions.get(actionId);
     if (!handler) {
+      if (actionId === "reset") {
+        const cleared = await this.resetNamespace(namespace, ctx);
+        return {
+          ok: true,
+          severity: "info",
+          message: cleared > 0 ? `Cleared ${cleared} saved value(s); environment/default configuration is back in effect.` : "No saved values to clear \u2014 already using environment/default configuration."
+        };
+      }
       return {
         ok: false,
         severity: "error",
@@ -856,6 +1128,11 @@ function registerSettingsRoutes(http, service, opts = {}) {
         sendError(res, 404, "UNKNOWN_NAMESPACE", err.message);
       } else if (err instanceof UnknownKeyError) {
         sendError(res, 400, "UNKNOWN_KEY", err.message, { namespace: err.namespace, key: err.key });
+      } else if (err instanceof SettingsValidationError) {
+        sendError(res, 400, "SETTINGS_VALIDATION", err.message, {
+          namespace: err.namespace,
+          fields: err.fields
+        });
       } else {
         sendError(res, 500, "INTERNAL", err?.message ?? "Failed to write namespace");
       }
@@ -1417,7 +1694,8 @@ var manifest4 = {
       key: "gateway_model",
       label: "Gateway model",
       required: true,
-      description: "Forwarded as AI_GATEWAY_MODEL. Example: openai/gpt-4o",
+      description: "Forwarded as AI_GATEWAY_MODEL. Format: provider/model, e.g. openai/gpt-4o or anthropic/claude-sonnet-4.6.",
+      pattern: "^[A-Za-z0-9_-]+\\/[A-Za-z0-9._:-]+$",
       visible: "${data.provider === 'gateway'}"
     },
     {
@@ -1613,6 +1891,7 @@ var manifest4 = {
       label: "Model",
       required: false,
       default: "openai/gpt-4o-mini",
+      pattern: "^[A-Za-z0-9_-]+\\/[A-Za-z0-9._:@-]+$",
       description: "Format: provider/model. Allowed providers (per Cloudflare /compat): anthropic, openai, groq, mistral, cohere, perplexity, workers-ai, google-ai-studio, vertex, grok, deepseek, cerebras, baseten, parallel.",
       visible: "${data.provider === 'cloudflare'}"
     },
@@ -1769,6 +2048,18 @@ var manifest4 = {
       icon: "Plug",
       handler: { kind: "http", method: "POST", url: "/api/settings/ai/test" }
     },
+    // Escape hatch: clears every saved row in this namespace so the
+    // runtime falls back to env auto-detection (AI_GATEWAY_MODEL /
+    // OPENAI_API_KEY / …). Without it, a broken saved config can only
+    // be removed by editing sys_setting by hand.
+    {
+      type: "action_button",
+      id: "reset",
+      label: "Reset to environment defaults",
+      required: false,
+      icon: "RotateCcw",
+      handler: { kind: "http", method: "POST", url: "/api/settings/ai/reset" }
+    },
     // ════════════════════════════════════════════════════════════════
     // Embedder — text → vector provider used by knowledge / RAG.
     // Decoupled from the chat provider above so an organisation can
@@ -3610,14 +3901,18 @@ export {
   SettingsLockedError,
   SettingsService,
   SettingsServicePlugin,
+  SettingsValidationError,
   UnknownKeyError,
   UnknownNamespaceError,
+  VisibilityParseError,
   brandingSettingsManifest,
   builtinSettingsManifests,
   envKeyOf,
+  evaluateVisibility,
   featureFlagsSettingsManifest,
   mailSettingsManifest,
   mailTestActionHandler,
+  referencedKeys,
   registerSettingsRoutes,
   settingsBuiltinTranslations,
   settingsObjects,