pi-model-fallback 0.1.0 → 0.3.2

package/extensions/index.ts

@@ -3,15 +3,27 @@ import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { getAgentDir, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
-import { defaultConfig, findFallback, modelKey, modelRefKey, validateConfigShape, type ModelFallbackConfig } from "../lib/config.js";
+import {
+  defaultConfig,
+  findFallback,
+  modelKey,
+  modelRefKey,
+  validateConfigShape,
+  type ModelFallbackConfig,
+  type ModelRef,
+} from "../lib/config.js";
+import { findActiveStateEntry, readState, upsertStateEntry, writeState, type FallbackState } from "../lib/state.js";
 import { modelFallbackPaths, readConfig, writeConfig, type ModelFallbackPaths } from "../lib/storage.js";
 
 const PACKAGE_ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
 const STATUS_KEY = "model-fallback";
+const DEFAULT_429_COOLDOWN_MS = 72 * 60 * 60 * 1000;
+const DEFAULT_5XX_COOLDOWN_MS = 10 * 60 * 1000;
 
 export default function modelFallback(pi: ExtensionAPI) {
   let paths: ModelFallbackPaths = modelFallbackPaths(getAgentDir());
   let config: ModelFallbackConfig | undefined;
+  let state: FallbackState | undefined;
   let originalModelKey: string | undefined;
   let activeFallbackKey: string | undefined;
   let lastFallbackReason: string | undefined;
@@ -31,12 +43,95 @@ export default function modelFallback(pi: ExtensionAPI) {
     }
   }
 
+  async function loadState(ctx: ExtensionContext): Promise<FallbackState | undefined> {
+    try {
+      syncPaths(ctx);
+      state = await readState(paths.state);
+      await writeState(paths.state, state);
+      return state;
+    } catch (error) {
+      ctx.ui.notify(`Model fallback state error: ${errorMessage(error)}`, "warning");
+      return undefined;
+    }
+  }
+
   function updateStatus(ctx: ExtensionContext): void {
     ctx.ui.setStatus(STATUS_KEY, activeFallbackKey ? `fallback:${activeFallbackKey}` : undefined);
   }
 
-  pi.on("session_start", async (_event, ctx) => {
+  async function applyPersistentFallback(ctx: ExtensionContext): Promise<void> {
+    const current = ctx.model;
+    if (!current) return;
+    const loadedConfig = config ?? (await loadConfig(ctx));
+    if (!loadedConfig?.enabled) return;
+    const loadedState = state ?? (await loadState(ctx));
+    if (!loadedState) return;
+
+    const active = findActiveStateEntry(loadedState, modelToRef(current));
+    if (!active) return;
+
+    const fallbackModel = ctx.modelRegistry.find(active.fallback.provider, active.fallback.model);
+    if (!fallbackModel) {
+      ctx.ui.notify(`Model fallback state target missing: ${modelRefKey(active.fallback)}`, "warning");
+      return;
+    }
+
+    const ok = await pi.setModel(fallbackModel);
+    if (!ok) {
+      ctx.ui.notify(`Model fallback auth unavailable: ${modelRefKey(active.fallback)}`, "warning");
+      return;
+    }
+
+    originalModelKey = modelKey(current);
+    activeFallbackKey = modelRefKey(active.fallback);
+    lastFallbackReason = `persistent ${active.status} from ${originalModelKey} until ${active.until}`;
+    updateStatus(ctx);
+    ctx.ui.notify(`Model fallback preselected: ${originalModelKey} → ${activeFallbackKey} until ${active.until}.`, "warning");
+  }
+
+  async function persistFailure(source: ModelRef, status: number, headers: Record<string, string>, ctx: ExtensionContext): Promise<void> {
+    const loaded = config ?? (await loadConfig(ctx));
+    if (!loaded) return;
+    const match = findFallback(loaded, { provider: source.provider, id: source.model }, status);
+    if (!match) return;
+    if (activeFallbackKey && activeFallbackKey === modelRefKey(match.fallback)) return;
+
+    const fallbackModel = ctx.modelRegistry.find(match.fallback.provider, match.fallback.model);
+    if (!fallbackModel) {
+      ctx.ui.notify(`Model fallback missing: ${modelRefKey(match.fallback)}`, "warning");
+      return;
+    }
+
+    const now = new Date();
+    const until = new Date(now.getTime() + cooldownMsFor(match.rule.cooldownMs, status, headers)).toISOString();
+    const loadedState = state ?? (await loadState(ctx)) ?? { version: 1 as const, entries: [] };
+    state = upsertStateEntry(loadedState, {
+      source,
+      fallback: match.fallback,
+      status,
+      until,
+      createdAt: now.toISOString(),
+      ruleName: match.rule.name,
+    });
+    await writeState(paths.state, state);
+
+    const ok = await pi.setModel(fallbackModel);
+    if (!ok) {
+      ctx.ui.notify(`Model fallback auth unavailable: ${modelRefKey(match.fallback)}`, "warning");
+      return;
+    }
+
+    originalModelKey = modelRefKey(source);
+    activeFallbackKey = modelRefKey(match.fallback);
+    lastFallbackReason = `${status} from ${originalModelKey}; persistent until ${until}`;
+    updateStatus(ctx);
+    ctx.ui.notify(`Model fallback: ${originalModelKey} → ${activeFallbackKey} (${status}). Future sessions preselect fallback until ${until}.`, "warning");
+  }
+
+  pi.on("agent_start", async (_event, ctx) => {
     await loadConfig(ctx);
+    await loadState(ctx);
+    await applyPersistentFallback(ctx);
     updateStatus(ctx);
   });
 
@@ -56,41 +151,43 @@ export default function modelFallback(pi: ExtensionAPI) {
     if (event.status >= 200 && event.status < 300) return;
     if (activeFallbackKey && modelKey(current) === activeFallbackKey) return;
 
-    const match = findFallback(loaded, current, event.status);
-    if (!match) return;
-
-    const fallbackModel = ctx.modelRegistry.find(match.fallback.provider, match.fallback.model);
-    if (!fallbackModel) {
-      ctx.ui.notify(`Model fallback missing: ${modelRefKey(match.fallback)}`, "warning");
-      return;
-    }
-
-    const ok = await pi.setModel(fallbackModel);
-    if (!ok) {
-      ctx.ui.notify(`Model fallback auth unavailable: ${modelRefKey(match.fallback)}`, "warning");
-      return;
-    }
+    await persistFailure(modelToRef(current), event.status, event.headers, ctx);
+  });
 
-    originalModelKey = modelKey(current);
-    activeFallbackKey = modelRefKey(match.fallback);
-    lastFallbackReason = `${event.status} from ${originalModelKey}`;
-    updateStatus(ctx);
-    ctx.ui.notify(`Model fallback: ${originalModelKey} → ${activeFallbackKey} (${event.status}). Re-run the prompt to use fallback.`, "warning");
+  pi.on("turn_end", async (event, ctx) => {
+    const message = event.message as unknown;
+    if (!isRecord(message) || message.role !== "assistant") return;
+    const errorMessage = typeof message.errorMessage === "string" ? message.errorMessage : undefined;
+    if (!errorMessage) return;
+    const status = parseStatusFromErrorMessage(errorMessage);
+    if (status === undefined) return;
+    const provider = typeof message.provider === "string" ? message.provider : ctx.model?.provider;
+    const model = typeof message.model === "string" ? message.model : ctx.model?.id;
+    if (!provider || !model) return;
+    if (activeFallbackKey && `${provider}/${model}` === activeFallbackKey) return;
+    await persistFailure({ provider, model }, status, {}, ctx);
   });
 
   pi.registerCommand("model-fallback:status", {
     description: "Show model fallback status",
     handler: async (_args, ctx) => {
       const loaded = config ?? (await loadConfig(ctx)) ?? defaultConfig();
-      ctx.ui.notify(formatStatus(loaded, paths.config, activeFallbackKey, originalModelKey, lastFallbackReason), "info");
+      const loadedState = state ?? (await loadState(ctx)) ?? { version: 1 as const, entries: [] };
+      ctx.ui.notify(formatStatus(loaded, loadedState, paths.config, paths.state, activeFallbackKey, originalModelKey, lastFallbackReason), "info");
     },
   });
 
   pi.registerCommand("model-fallback:reset", {
-    description: "Return from fallback model to the pre-fallback model when remembered",
+    description: "Return from fallback model to the pre-fallback model when remembered and clear persistent state",
     handler: async (_args, ctx) => {
+      syncPaths(ctx);
+      state = { version: 1, entries: [] };
+      await writeState(paths.state, state);
       if (!originalModelKey) {
-        ctx.ui.notify("Model fallback: no remembered original model.", "info");
+        ctx.ui.notify("Model fallback: persistent state cleared; no remembered original model.", "info");
+        activeFallbackKey = undefined;
+        lastFallbackReason = undefined;
+        updateStatus(ctx);
         return;
       }
       const [provider, ...modelParts] = originalModelKey.split("/");
@@ -108,7 +205,7 @@ export default function modelFallback(pi: ExtensionAPI) {
       originalModelKey = undefined;
       lastFallbackReason = undefined;
       updateStatus(ctx);
-      ctx.ui.notify(`Model fallback reset: ${modelKey(model)}`, "info");
+      ctx.ui.notify(`Model fallback reset: ${modelKey(model)}; persistent state cleared.`, "info");
     },
   });
 
@@ -129,7 +226,15 @@ export default function modelFallback(pi: ExtensionAPI) {
       syncPaths(ctx);
       if (params.action === "read" || params.action === "status") {
         const current = await readConfig(paths.config);
-        return textResult(JSON.stringify(current, null, 2), { configPath: paths.config, activeFallbackKey, originalModelKey, lastFallbackReason });
+        const currentState = await readState(paths.state);
+        return textResult(JSON.stringify(current, null, 2), {
+          configPath: paths.config,
+          statePath: paths.state,
+          state: currentState,
+          activeFallbackKey,
+          originalModelKey,
+          lastFallbackReason,
+        });
       }
       if (!params.configJson) throw new Error("configJson is required for validate/save.");
       const nextConfig = validateConfigShape(JSON.parse(params.configJson));
@@ -174,11 +279,22 @@ function validateRegisteredModels(ctx: ExtensionContext, nextConfig: ModelFallba
   }
 }
 
-function formatStatus(config: ModelFallbackConfig, configPath: string, activeFallbackKey?: string, originalModelKey?: string, reason?: string): string {
+function formatStatus(
+  config: ModelFallbackConfig,
+  state: FallbackState,
+  configPath: string,
+  statePath: string,
+  activeFallbackKey?: string,
+  originalModelKey?: string,
+  reason?: string,
+): string {
   return [
     `Model fallback: ${config.enabled ? "enabled" : "disabled"}`,
     `Config: ${configPath}`,
+    `State: ${statePath}`,
     `Rules: ${config.rules.length}`,
+    `Persistent entries: ${state.entries.length}`,
+    ...state.entries.map((entry) => `- ${modelRefKey(entry.source)} -> ${modelRefKey(entry.fallback)} until ${entry.until} (${entry.status})`),
     `Active fallback: ${activeFallbackKey ?? "none"}`,
     `Original model: ${originalModelKey ?? "none"}`,
     `Reason: ${reason ?? "none"}`,
@@ -196,6 +312,62 @@ function textResult(text: string, details?: Record<string, unknown>) {
   return { content: [{ type: "text" as const, text }], details: details ?? {} };
 }
 
+function cooldownMsFor(ruleCooldownMs: number | undefined, status: number, headers: Record<string, string>): number {
+  const headerMs = cooldownMsFromHeaders(headers);
+  if (headerMs !== undefined) return headerMs;
+  if (ruleCooldownMs !== undefined) return ruleCooldownMs;
+  if (status === 429) return DEFAULT_429_COOLDOWN_MS;
+  if (status >= 500 && status <= 599) return DEFAULT_5XX_COOLDOWN_MS;
+  return DEFAULT_5XX_COOLDOWN_MS;
+}
+
+function cooldownMsFromHeaders(headers: Record<string, string>): number | undefined {
+  const normalized = Object.fromEntries(Object.entries(headers).map(([key, value]) => [key.toLowerCase(), value]));
+  const retryAfter = parseRetryAfter(normalized["retry-after"]);
+  if (retryAfter !== undefined) return retryAfter;
+
+  for (const name of ["x-ratelimit-reset", "x-ratelimit-reset-requests", "x-ratelimit-reset-tokens", "ratelimit-reset", "x-rate-limit-reset"]) {
+    const parsed = parseResetHeader(normalized[name]);
+    if (parsed !== undefined) return parsed;
+  }
+  return undefined;
+}
+
+function parseRetryAfter(value: string | undefined): number | undefined {
+  if (!value) return undefined;
+  const trimmed = value.trim();
+  const seconds = Number(trimmed);
+  if (Number.isFinite(seconds) && seconds > 0) return Math.ceil(seconds * 1000);
+  const dateMs = Date.parse(trimmed);
+  if (!Number.isNaN(dateMs) && dateMs > Date.now()) return dateMs - Date.now();
+  return undefined;
+}
+
+function parseResetHeader(value: string | undefined): number | undefined {
+  if (!value) return undefined;
+  const trimmed = value.trim();
+  const numeric = Number(trimmed);
+  if (Number.isFinite(numeric) && numeric > 0) {
+    if (numeric > 1_000_000_000_000) return Math.max(0, numeric - Date.now());
+    if (numeric > 1_000_000_000) return Math.max(0, numeric * 1000 - Date.now());
+    return Math.ceil(numeric * 1000);
+  }
+  const dateMs = Date.parse(trimmed);
+  if (!Number.isNaN(dateMs) && dateMs > Date.now()) return dateMs - Date.now();
+  return undefined;
+}
+
+function parseStatusFromErrorMessage(message: string): number | undefined {
+  const match = message.match(/\b([1-5][0-9]{2})\b/);
+  if (!match) return undefined;
+  const status = Number(match[1]);
+  return Number.isInteger(status) ? status : undefined;
+}
+
+function modelToRef(model: { provider: string; id: string }): ModelRef {
+  return { provider: model.provider, model: model.id };
+}
+
 function errorMessage(error: unknown): string {
   return error instanceof Error ? error.message : String(error);
 }

package/lib/config.ts

@@ -1,136 +1,144 @@
-import type { Model } from "@earendil-works/pi-ai";
-
-export const CONFIG_VERSION = 1;
-export const DEFAULT_FALLBACK_STATUSES = [429, 500, 502, 503, 504] as const;
-
-export interface ModelRef {
-  provider: string;
-  model: string;
-}
-
-export interface FallbackRule {
-  name?: string;
-  matchProviders?: string[];
-  matchModels?: ModelRef[];
-  statuses?: number[];
-  fallback: ModelRef;
-}
-
-export interface ModelFallbackConfig {
-  version: 1;
-  enabled: boolean;
-  rules: FallbackRule[];
-}
-
-export interface MatchedFallback {
-  rule: FallbackRule;
-  fallback: ModelRef;
-}
-
-export function defaultConfig(): ModelFallbackConfig {
-  return {
-    version: CONFIG_VERSION,
-    enabled: true,
-    rules: [
-      {
-        name: "zai-to-deepseek-flash",
-        matchProviders: ["zai"],
-        statuses: [...DEFAULT_FALLBACK_STATUSES],
-        fallback: { provider: "deepseek", model: "deepseek-v4-flash" },
-      },
-    ],
-  };
-}
-
-export function validateConfigShape(value: unknown): ModelFallbackConfig {
-  if (!isRecord(value)) throw new Error("Config must be an object.");
-  if (value.version !== CONFIG_VERSION) throw new Error(`Unsupported config version: ${String(value.version)}.`);
-  const enabled = typeof value.enabled === "boolean" ? value.enabled : true;
-  if (!Array.isArray(value.rules)) throw new Error("rules must be an array.");
-  if (value.rules.length === 0) throw new Error("rules must include at least one fallback rule.");
-
-  return {
-    version: CONFIG_VERSION,
-    enabled,
-    rules: value.rules.map((ruleValue, index) => validateRule(ruleValue, index)),
-  };
-}
-
-export function findFallback(config: ModelFallbackConfig, model: Pick<Model<any>, "provider" | "id">, status: number): MatchedFallback | undefined {
-  if (!config.enabled) return undefined;
-  for (const rule of config.rules) {
-    if (!statusesFor(rule).has(status)) continue;
-    if (!modelMatches(rule, model)) continue;
-    return { rule, fallback: rule.fallback };
-  }
-  return undefined;
-}
-
-export function modelRefKey(ref: ModelRef): string {
-  return `${ref.provider}/${ref.model}`;
-}
-
-export function modelKey(model: Pick<Model<any>, "provider" | "id">): string {
-  return `${model.provider}/${model.id}`;
-}
-
-function validateRule(value: unknown, index: number): FallbackRule {
-  if (!isRecord(value)) throw new Error(`rules[${index}] must be an object.`);
-  const rule: FallbackRule = { fallback: readModelRef(value.fallback, `rules[${index}].fallback`) };
-  if (typeof value.name === "string" && value.name.trim() !== "") rule.name = value.name.trim();
-  if (value.matchProviders !== undefined) rule.matchProviders = readStringArray(value.matchProviders, `rules[${index}].matchProviders`);
-  if (value.matchModels !== undefined) rule.matchModels = readModelRefArray(value.matchModels, `rules[${index}].matchModels`);
-  if (value.statuses !== undefined) rule.statuses = readStatuses(value.statuses, `rules[${index}].statuses`);
-  if ((!rule.matchProviders || rule.matchProviders.length === 0) && (!rule.matchModels || rule.matchModels.length === 0)) {
-    throw new Error(`rules[${index}] must define matchProviders or matchModels.`);
-  }
-  return rule;
-}
-
-function modelMatches(rule: FallbackRule, model: Pick<Model<any>, "provider" | "id">): boolean {
-  if (rule.matchModels?.some((entry) => entry.provider === model.provider && entry.model === model.id)) return true;
-  if (rule.matchProviders?.includes(model.provider)) return true;
-  return false;
-}
-
-function statusesFor(rule: FallbackRule): Set<number> {
-  return new Set(rule.statuses && rule.statuses.length > 0 ? rule.statuses : DEFAULT_FALLBACK_STATUSES);
-}
-
-function readModelRef(value: unknown, path: string): ModelRef {
-  if (!isRecord(value)) throw new Error(`${path} must be an object.`);
-  return {
-    provider: readNonEmptyString(value.provider, `${path}.provider`),
-    model: readNonEmptyString(value.model, `${path}.model`),
-  };
-}
-
-function readModelRefArray(value: unknown, path: string): ModelRef[] {
-  if (!Array.isArray(value)) throw new Error(`${path} must be an array.`);
-  if (value.length === 0) throw new Error(`${path} must not be empty.`);
-  return value.map((entry, index) => readModelRef(entry, `${path}[${index}]`));
-}
-
-function readStringArray(value: unknown, path: string): string[] {
-  if (!Array.isArray(value)) throw new Error(`${path} must be an array.`);
-  if (value.length === 0) throw new Error(`${path} must not be empty.`);
-  return value.map((entry, index) => readNonEmptyString(entry, `${path}[${index}]`));
-}
-
-function readStatuses(value: unknown, path: string): number[] {
-  if (!Array.isArray(value)) throw new Error(`${path} must be an array.`);
-  if (value.length === 0) throw new Error(`${path} must not be empty.`);
-  return value.map((entry, index) => {
-    if (!Number.isInteger(entry) || entry < 100 || entry > 599) throw new Error(`${path}[${index}] must be an HTTP status code.`);
-    return entry;
-  });
-}
-
-function readNonEmptyString(value: unknown, path: string): string {
-  if (typeof value !== "string" || value.trim() === "") throw new Error(`${path} must be a non-empty string.`);
-  return value.trim();
-}
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
+import type { Model } from "@earendil-works/pi-ai";
+
+export const CONFIG_VERSION = 1;
+export const DEFAULT_FALLBACK_STATUSES = [429, 500, 502, 503, 504] as const;
+
+export interface ModelRef {
+  provider: string;
+  model: string;
+}
+
+export interface FallbackRule {
+  name?: string;
+  matchProviders?: string[];
+  matchModels?: ModelRef[];
+  statuses?: number[];
+  /** Persistent failover cooldown in milliseconds after a matching failure. Defaults: 429 => 72h, 5xx => 10m. */
+  cooldownMs?: number;
+  fallback: ModelRef;
+}
+
+export interface ModelFallbackConfig {
+  version: 1;
+  enabled: boolean;
+  rules: FallbackRule[];
+}
+
+export interface MatchedFallback {
+  rule: FallbackRule;
+  fallback: ModelRef;
+}
+
+export function defaultConfig(): ModelFallbackConfig {
+  return {
+    version: CONFIG_VERSION,
+    enabled: true,
+    rules: [
+      {
+        name: "zai-to-deepseek-flash",
+        matchProviders: ["zai"],
+        statuses: [...DEFAULT_FALLBACK_STATUSES],
+        fallback: { provider: "deepseek", model: "deepseek-v4-flash" },
+      },
+    ],
+  };
+}
+
+export function validateConfigShape(value: unknown): ModelFallbackConfig {
+  if (!isRecord(value)) throw new Error("Config must be an object.");
+  if (value.version !== CONFIG_VERSION) throw new Error(`Unsupported config version: ${String(value.version)}.`);
+  const enabled = typeof value.enabled === "boolean" ? value.enabled : true;
+  if (!Array.isArray(value.rules)) throw new Error("rules must be an array.");
+  if (value.rules.length === 0) throw new Error("rules must include at least one fallback rule.");
+
+  return {
+    version: CONFIG_VERSION,
+    enabled,
+    rules: value.rules.map((ruleValue, index) => validateRule(ruleValue, index)),
+  };
+}
+
+export function findFallback(config: ModelFallbackConfig, model: Pick<Model<any>, "provider" | "id">, status: number): MatchedFallback | undefined {
+  if (!config.enabled) return undefined;
+  for (const rule of config.rules) {
+    if (!statusesFor(rule).has(status)) continue;
+    if (!modelMatches(rule, model)) continue;
+    return { rule, fallback: rule.fallback };
+  }
+  return undefined;
+}
+
+export function modelRefKey(ref: ModelRef): string {
+  return `${ref.provider}/${ref.model}`;
+}
+
+export function modelKey(model: Pick<Model<any>, "provider" | "id">): string {
+  return `${model.provider}/${model.id}`;
+}
+
+function validateRule(value: unknown, index: number): FallbackRule {
+  if (!isRecord(value)) throw new Error(`rules[${index}] must be an object.`);
+  const rule: FallbackRule = { fallback: readModelRef(value.fallback, `rules[${index}].fallback`) };
+  if (typeof value.name === "string" && value.name.trim() !== "") rule.name = value.name.trim();
+  if (value.matchProviders !== undefined) rule.matchProviders = readStringArray(value.matchProviders, `rules[${index}].matchProviders`);
+  if (value.matchModels !== undefined) rule.matchModels = readModelRefArray(value.matchModels, `rules[${index}].matchModels`);
+  if (value.statuses !== undefined) rule.statuses = readStatuses(value.statuses, `rules[${index}].statuses`);
+  if (value.cooldownMs !== undefined) rule.cooldownMs = readPositiveInteger(value.cooldownMs, `rules[${index}].cooldownMs`);
+  if ((!rule.matchProviders || rule.matchProviders.length === 0) && (!rule.matchModels || rule.matchModels.length === 0)) {
+    throw new Error(`rules[${index}] must define matchProviders or matchModels.`);
+  }
+  return rule;
+}
+
+function modelMatches(rule: FallbackRule, model: Pick<Model<any>, "provider" | "id">): boolean {
+  if (rule.matchModels?.some((entry) => entry.provider === model.provider && entry.model === model.id)) return true;
+  if (rule.matchProviders?.includes(model.provider)) return true;
+  return false;
+}
+
+function statusesFor(rule: FallbackRule): Set<number> {
+  return new Set(rule.statuses && rule.statuses.length > 0 ? rule.statuses : DEFAULT_FALLBACK_STATUSES);
+}
+
+function readModelRef(value: unknown, path: string): ModelRef {
+  if (!isRecord(value)) throw new Error(`${path} must be an object.`);
+  return {
+    provider: readNonEmptyString(value.provider, `${path}.provider`),
+    model: readNonEmptyString(value.model, `${path}.model`),
+  };
+}
+
+function readModelRefArray(value: unknown, path: string): ModelRef[] {
+  if (!Array.isArray(value)) throw new Error(`${path} must be an array.`);
+  if (value.length === 0) throw new Error(`${path} must not be empty.`);
+  return value.map((entry, index) => readModelRef(entry, `${path}[${index}]`));
+}
+
+function readStringArray(value: unknown, path: string): string[] {
+  if (!Array.isArray(value)) throw new Error(`${path} must be an array.`);
+  if (value.length === 0) throw new Error(`${path} must not be empty.`);
+  return value.map((entry, index) => readNonEmptyString(entry, `${path}[${index}]`));
+}
+
+function readStatuses(value: unknown, path: string): number[] {
+  if (!Array.isArray(value)) throw new Error(`${path} must be an array.`);
+  if (value.length === 0) throw new Error(`${path} must not be empty.`);
+  return value.map((entry, index) => {
+    if (!Number.isInteger(entry) || entry < 100 || entry > 599) throw new Error(`${path}[${index}] must be an HTTP status code.`);
+    return entry;
+  });
+}
+
+function readPositiveInteger(value: unknown, path: string): number {
+  if (typeof value !== "number" || !Number.isInteger(value) || value <= 0) throw new Error(`${path} must be a positive integer.`);
+  return value;
+}
+
+function readNonEmptyString(value: unknown, path: string): string {
+  if (typeof value !== "string" || value.trim() === "") throw new Error(`${path} must be a non-empty string.`);
+  return value.trim();
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}