@ejstembler/pi-classifier-router 1.0.0

package/src/classify/laya.ts

@@ -0,0 +1,383 @@
+/**
+ * Laya (local System One) classifier: a persistent NDJSON sidecar process.
+ *
+ * Wire protocol, shared verbatim with `python/laya_worker.py`:
+ *   request  {"id":<int>,"op":"predict"|"ping"|"preload"|"shutdown", ...}
+ *   reply    {"id":<int>,"ok":true,"result":{...}}
+ *          | {"id":<int>,"ok":false,"error":<string>,"kind":"unavailable"|"timeout"|"protocol"}
+ *   event    {"event":"ready","version":<string>,"loaded":<string[]>}
+ *          | {"event":"error","error":<string>,"kind":...}
+ *
+ * stdout carries one JSON object per line and nothing else; the worker writes
+ * diagnostics to stderr. The child is spawned lazily and respawned after a
+ * crash, so a dead worker degrades to `unavailable` without poisoning the
+ * session.
+ */
+
+import { spawn } from "node:child_process";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { ClassifierError } from "../types.ts";
+import type {
+  Answers,
+  ClassificationResult,
+  Classifier,
+  ClassifierErrorCode,
+  ClassifierState,
+  ClassifyOptions,
+  LayaBackendConfig,
+  Questions,
+} from "../types.ts";
+import type { ClassifierDeps } from "./index.ts";
+
+const BACKEND = "laya";
+
+/** Repo root: two directories above `src/classify/laya.ts`. */
+const DEFAULT_EXTENSION_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
+
+/** The subset of `node:child_process.ChildProcess` this client needs. */
+export interface ChildProcessLike {
+  stdout: AsyncIterable<Uint8Array | string> | null;
+  stderr: AsyncIterable<Uint8Array | string> | null;
+  stdin: { write(chunk: string): boolean };
+  kill(signal?: string): boolean;
+  on(event: "exit" | "error", cb: (...args: unknown[]) => void): void;
+  pid?: number;
+}
+
+export type LayaSpawn = (
+  command: string,
+  args: string[],
+  options: { env: Record<string, string | undefined> },
+) => ChildProcessLike;
+
+interface ReadyInfo {
+  version: string;
+  loaded: string[];
+}
+
+interface PendingCall {
+  resolve: (value: unknown) => void;
+  reject: (error: ClassifierError) => void;
+}
+
+interface ReadyWaiter {
+  resolve: (value: ReadyInfo) => void;
+  reject: (error: ClassifierError) => void;
+}
+
+const defaultSpawn: LayaSpawn = (command, args, options) =>
+  spawn(command, args, { env: options.env, stdio: ["pipe", "pipe", "pipe"] }) as unknown as ChildProcessLike;
+
+export function createLayaClassifier(config: LayaBackendConfig, deps: ClassifierDeps = {}): Classifier {
+  const spawnImpl = deps.spawnImpl ?? defaultSpawn;
+  const extensionRoot = deps.extensionRoot ?? DEFAULT_EXTENSION_ROOT;
+  const workerScript = path.isAbsolute(config.workerScript)
+    ? config.workerScript
+    : path.resolve(extensionRoot, config.workerScript);
+
+  let child: ChildProcessLike | null = null;
+  let nextId = 1;
+  let ready: ReadyInfo | null = null;
+  let warnedStdout = false;
+  const pending = new Map<number, PendingCall>();
+  let readyWaiters: ReadyWaiter[] = [];
+
+  function spawnArgs(): string[] {
+    const args = ["--repo", config.repo];
+    if (config.device) args.push("--device", config.device);
+    if (config.router) args.push("--router");
+    if (config.preload) args.push("--preload");
+    if (config.subfolder) args.push("--subfolder", config.subfolder);
+    return args;
+  }
+
+  function childEnv(): Record<string, string | undefined> {
+    const env: Record<string, string | undefined> = { ...process.env, ...(deps.env ?? {}) };
+    const token = deps.env?.[config.hfTokenEnvVar] ?? process.env[config.hfTokenEnvVar];
+    if (token) env["HF_TOKEN"] = token;
+    return env;
+  }
+
+  /** Tear down a dead child: fail every in-flight call and allow a respawn. */
+  function failChild(proc: ChildProcessLike, message: string): void {
+    if (child !== proc) return;
+    child = null;
+    ready = null;
+    warnedStdout = false;
+    const error = new ClassifierError(BACKEND, "unavailable", message);
+    for (const call of [...pending.values()]) call.reject(error);
+    const waiters = readyWaiters;
+    readyWaiters = [];
+    for (const waiter of waiters) waiter.reject(error);
+  }
+
+  function handleStdoutLine(line: string): void {
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(line);
+    } catch {
+      if (!warnedStdout) {
+        warnedStdout = true;
+        deps.logger?.(`laya worker wrote a non-JSON stdout line: ${line.slice(0, 120)}`);
+      }
+      return;
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+      if (!warnedStdout) {
+        warnedStdout = true;
+        deps.logger?.(`laya worker wrote a JSON value that is not an object: ${line.slice(0, 120)}`);
+      }
+      return;
+    }
+
+    const record = parsed as Record<string, unknown>;
+    if (typeof record["event"] === "string") {
+      const event = record["event"];
+      if (event === "ready") {
+        ready = {
+          version: typeof record["version"] === "string" ? record["version"] : "unknown",
+          loaded: Array.isArray(record["loaded"])
+            ? record["loaded"].filter((name): name is string => typeof name === "string")
+            : [],
+        };
+        const waiters = readyWaiters;
+        readyWaiters = [];
+        for (const waiter of waiters) waiter.resolve(ready);
+      } else if (event === "error") {
+        const proc = child;
+        if (proc) failChild(proc, `laya worker reported an error: ${String(record["error"])}`);
+      } else {
+        deps.logger?.(`laya worker sent an unknown event: ${event}`);
+      }
+      return;
+    }
+
+    const id = record["id"];
+    if (typeof id !== "number" || !Number.isInteger(id)) {
+      deps.logger?.(`laya worker sent a reply without a numeric id: ${line.slice(0, 120)}`);
+      return;
+    }
+    const call = pending.get(id);
+    if (!call) {
+      // A late reply to a call that timed out, aborted, or outlived a dispose.
+      if (child) deps.logger?.(`laya worker replied to unknown request id ${id}`);
+      return;
+    }
+    if (record["ok"] === true) {
+      call.resolve(record["result"]);
+      return;
+    }
+    const kind = record["kind"];
+    const code: ClassifierErrorCode = kind === "timeout" || kind === "unavailable" || kind === "protocol" ? kind : "unavailable";
+    call.reject(
+      new ClassifierError(BACKEND, code, `laya worker failed: ${String(record["error"] ?? "unknown error")}`),
+    );
+  }
+
+  function handleStderrLine(line: string): void {
+    deps.logger?.(`laya worker: ${line}`);
+  }
+
+  function ensureChild(): ChildProcessLike {
+    if (child) return child;
+    const proc = spawnImpl(config.pythonBin, [workerScript, ...spawnArgs()], { env: childEnv() });
+    child = proc;
+    ready = null;
+    warnedStdout = false;
+    if (proc.stdout) {
+      void pump(proc.stdout, (line) => {
+        if (child === proc) handleStdoutLine(line);
+      });
+    }
+    if (proc.stderr) {
+      void pump(proc.stderr, (line) => {
+        if (child === proc) handleStderrLine(line);
+      });
+    }
+    proc.on("error", (error: unknown) => {
+      failChild(proc, `laya worker failed to start: ${error instanceof Error ? error.message : String(error)}`);
+    });
+    proc.on("exit", (code: unknown) => {
+      failChild(proc, `laya worker exited (${typeof code === "number" ? code : "signal"})`);
+    });
+    return proc;
+  }
+
+  function waitReady(timeoutMs: number, signal?: AbortSignal): Promise<ReadyInfo> {
+    const current = ready;
+    if (current) return Promise.resolve(current);
+    return new Promise<ReadyInfo>((resolve, reject) => {
+      let timer: NodeJS.Timeout;
+      const waiter: ReadyWaiter = {
+        resolve: (value) => {
+          clearTimeout(timer);
+          signal?.removeEventListener("abort", onAbort);
+          resolve(value);
+        },
+        reject: (error) => {
+          clearTimeout(timer);
+          signal?.removeEventListener("abort", onAbort);
+          reject(error);
+        },
+      };
+      const onAbort = (): void => {
+        readyWaiters = readyWaiters.filter((entry) => entry !== waiter);
+        waiter.reject(new ClassifierError(BACKEND, "aborted", "laya warmup aborted by caller"));
+      };
+      timer = setTimeout(() => {
+        readyWaiters = readyWaiters.filter((entry) => entry !== waiter);
+        waiter.reject(new ClassifierError(BACKEND, "timeout", `laya worker not ready within ${timeoutMs}ms`));
+      }, timeoutMs);
+      readyWaiters.push(waiter);
+      if (signal) {
+        if (signal.aborted) onAbort();
+        else signal.addEventListener("abort", onAbort, { once: true });
+      }
+    });
+  }
+
+  function request(
+    op: string,
+    payload: Record<string, unknown>,
+    timeoutMs: number,
+    signal?: AbortSignal,
+  ): Promise<unknown> {
+    return new Promise<unknown>((resolve, reject) => {
+      let proc: ChildProcessLike;
+      try {
+        proc = ensureChild();
+      } catch (error) {
+        reject(
+          new ClassifierError(
+            BACKEND,
+            "unavailable",
+            `could not spawn laya worker: ${error instanceof Error ? error.message : String(error)}`,
+          ),
+        );
+        return;
+      }
+
+      const id = nextId++;
+      let timer: NodeJS.Timeout;
+      const cleanup = (): void => {
+        clearTimeout(timer);
+        signal?.removeEventListener("abort", onAbort);
+      };
+      const failWith = (code: ClassifierErrorCode, message: string): void => {
+        if (!pending.has(id)) return;
+        pending.delete(id);
+        cleanup();
+        reject(new ClassifierError(BACKEND, code, message));
+      };
+      const onAbort = (): void => failWith("aborted", `laya ${op} aborted by caller`);
+
+      pending.set(id, {
+        resolve: (value) => {
+          if (!pending.has(id)) return;
+          pending.delete(id);
+          cleanup();
+          resolve(value);
+        },
+        reject: (error) => {
+          if (!pending.has(id)) return;
+          pending.delete(id);
+          cleanup();
+          reject(error);
+        },
+      });
+      timer = setTimeout(() => failWith("timeout", `laya ${op} exceeded ${timeoutMs}ms`), timeoutMs);
+      if (signal) {
+        if (signal.aborted) onAbort();
+        else signal.addEventListener("abort", onAbort, { once: true });
+      }
+
+      try {
+        proc.stdin.write(`${JSON.stringify({ id, op, ...payload })}\n`);
+      } catch (error) {
+        failWith("unavailable", `laya worker stdin closed: ${error instanceof Error ? error.message : String(error)}`);
+      }
+    });
+  }
+
+  return {
+    name: BACKEND,
+
+    async warmup(options?: ClassifyOptions): Promise<void> {
+      ensureChild();
+      await waitReady(config.warmupTimeoutMs, options?.signal);
+      if (config.preload) await request("preload", {}, config.warmupTimeoutMs, options?.signal);
+    },
+
+    async classify(
+      state: ClassifierState,
+      questions: Questions,
+      options?: ClassifyOptions,
+    ): Promise<ClassificationResult> {
+      const value = await request("predict", { state, questions }, config.timeoutMs, options?.signal);
+      if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw new ClassifierError(BACKEND, "protocol", "laya worker returned no result object");
+      }
+      const record = value as Record<string, unknown>;
+      const answers = record["answers"];
+      if (answers === null || typeof answers !== "object" || Array.isArray(answers)) {
+        throw new ClassifierError(BACKEND, "protocol", "laya worker returned no answers object");
+      }
+      const result: ClassificationResult = { answers: answers as Answers };
+      if (typeof record["model"] === "string") result.model = record["model"];
+      const usage = record["usage"];
+      if (usage !== null && typeof usage === "object" && !Array.isArray(usage)) {
+        result.usage = usage as ClassificationResult["usage"];
+      }
+      return result;
+    },
+
+    async dispose(): Promise<void> {
+      const proc = child;
+      if (!proc) return;
+      // Detach first so the imminent exit event cannot tear down a respawn.
+      child = null;
+      ready = null;
+      const error = new ClassifierError(BACKEND, "unavailable", "laya worker disposed");
+      for (const call of [...pending.values()]) call.reject(error);
+      const waiters = readyWaiters;
+      readyWaiters = [];
+      for (const waiter of waiters) waiter.reject(error);
+      try {
+        proc.stdin.write(`${JSON.stringify({ id: nextId++, op: "shutdown" })}\n`);
+      } catch {
+        // Best effort: the child may already be gone.
+      }
+      try {
+        proc.kill();
+      } catch {
+        // Best effort.
+      }
+    },
+  };
+}
+
+/** Split an async byte/string stream into lines, tolerating chunk boundaries. */
+async function pump(
+  stream: AsyncIterable<Uint8Array | string>,
+  onLine: (line: string) => void,
+): Promise<void> {
+  let buffer = "";
+  try {
+    for await (const chunk of stream) {
+      buffer += typeof chunk === "string" ? chunk : Buffer.from(chunk).toString("utf8");
+      let index = buffer.indexOf("\n");
+      while (index >= 0) {
+        const line = buffer.slice(0, index).replace(/\r$/, "");
+        buffer = buffer.slice(index + 1);
+        if (line.trim() !== "") onLine(line);
+        index = buffer.indexOf("\n");
+      }
+    }
+    const tail = buffer.trim();
+    if (tail !== "") onLine(tail);
+  } catch {
+    // Stream teardown; the child exit/error handler reports the failure.
+  }
+}

package/src/config.ts

@@ -0,0 +1,288 @@
+/**
+ * Config discovery, defaults, merge, and validation.
+ *
+ * Precedence is project over global; the first existing, parseable, valid file
+ * wins. A file that fails to read or parse is reported and skipped, but a file
+ * that parses yet violates the contract is rejected outright: silently
+ * mis-routing is worse than falling back to the session's own model.
+ */
+
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+import type { Question, RouterConfig, RouterConfigInput } from "./types.ts";
+
+export interface ConfigSource {
+  path: string;
+  scope: "project" | "global";
+}
+
+export interface ConfigLoadResult {
+  config: RouterConfig | null;
+  source: ConfigSource | null;
+  errors: string[];
+}
+
+/** Project config first, global config second. */
+export function configPaths(cwd: string, home: string): ConfigSource[] {
+  return [
+    { path: path.join(cwd, ".omp", "class-router.json"), scope: "project" },
+    { path: path.join(home, ".omp", "class-router.json"), scope: "global" },
+  ];
+}
+
+/** A complete, valid configuration. Fresh objects on every call. */
+export function defaultConfig(): RouterConfig {
+  return {
+    enabled: true,
+    backend: "jev",
+    jev: {
+      endpoint: "https://api.typesafe.ai/v1/systemone",
+      model: "jev-latest",
+      apiKeyEnvVar: "TYPESAFE_API_KEY",
+      timeoutMs: 3000,
+    },
+    laya: {
+      // HTTP transport is opt-in; the default spawns the local sidecar.
+      transport: "python",
+      endpoint: "",
+      apiKeyEnvVar: "",
+      pythonBin: "python3",
+      workerScript: "python/laya_worker.py",
+      repo: "convaiinnovations/laya",
+      subfolder: null,
+      device: null,
+      router: true,
+      preload: true,
+      timeoutMs: 4000,
+      warmupTimeoutMs: 600000,
+      hfTokenEnvVar: "HF_TOKEN",
+    },
+    routing: {
+      questions: {
+        task_complexity: {
+          type: "choice",
+          instructions: "How demanding is this request for an AI coding agent?",
+          criteria: {
+            trivial: "a single lookup, rename, or one-line answer; no exploration",
+            standard: "a normal multi-step edit or investigation inside one or two files",
+            hard: "large refactor, cross-cutting design, deep debugging, or long multi-file reasoning",
+          },
+        },
+      },
+      primaryQuestion: "task_complexity",
+      modelMapping: { trivial: "@smol", standard: "@default", hard: "@slow" },
+      fallbackChains: {
+        "@smol": ["@smol", "@default"],
+        "@default": ["@default", "@slow"],
+        "@slow": ["@slow", "@default"],
+      },
+      confidenceThreshold: 0.5,
+      defaultCategory: "standard",
+    },
+    circuitBreaker: { failureThreshold: 3, cooldownMs: 120000, halfOpenMaxTrials: 1 },
+    dryRun: false,
+    notify: true,
+    applyTo: "all",
+  };
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isNonEmptyString(value: unknown): value is string {
+  return typeof value === "string" && value.trim() !== "";
+}
+
+/**
+ * Per-key merge for the routing maps. A non-empty plain object merges over the
+ * defaults; anything else (including an explicitly empty object) replaces them,
+ * so validation can reject the intent instead of silently keeping defaults.
+ */
+function mergeKeyMap<T>(base: Record<string, T>, override: Record<string, T> | undefined): Record<string, T> {
+  if (override === undefined) return { ...base };
+  if (!isPlainObject(override) || Object.keys(override).length === 0) return override;
+  return { ...base, ...(override as Record<string, T>) };
+}
+
+/**
+ * Layer a partial input over defaults. Sections merge one level deep and the
+ * per-key maps (`questions`, `modelMapping`, `fallbackChains`) merge by key;
+ * arrays and scalars replace wholesale. The input is never mutated.
+ */
+function mergeConfig(base: RouterConfig, input: RouterConfigInput): RouterConfig {
+  const inputRouting = input.routing;
+  const routing = base.routing;
+  return {
+    enabled: input.enabled ?? base.enabled,
+    backend: input.backend ?? base.backend,
+    dryRun: input.dryRun ?? base.dryRun,
+    notify: input.notify ?? base.notify,
+    applyTo: input.applyTo ?? base.applyTo,
+    jev: { ...base.jev, ...(input.jev ?? {}) },
+    laya: { ...base.laya, ...(input.laya ?? {}) },
+    circuitBreaker: { ...base.circuitBreaker, ...(input.circuitBreaker ?? {}) },
+    routing: {
+      primaryQuestion: inputRouting?.primaryQuestion ?? routing.primaryQuestion,
+      confidenceThreshold: inputRouting?.confidenceThreshold ?? routing.confidenceThreshold,
+      // `null` is a meaningful value here, so an explicit null must survive `??`.
+      defaultCategory:
+        inputRouting?.defaultCategory !== undefined ? inputRouting.defaultCategory : routing.defaultCategory,
+      questions: mergeKeyMap(routing.questions, inputRouting?.questions),
+      modelMapping: mergeKeyMap(routing.modelMapping, inputRouting?.modelMapping),
+      fallbackChains: mergeKeyMap(routing.fallbackChains, inputRouting?.fallbackChains),
+    },
+  };
+}
+
+function validateConfig(config: RouterConfig): string[] {
+  const errors: string[] = [];
+
+  if (config.backend !== "jev" && config.backend !== "laya") {
+    errors.push(`backend must be "jev" or "laya", got ${JSON.stringify(config.backend)}`);
+  }
+
+  const routing = config.routing;
+  const questions = routing.questions;
+  if (!isPlainObject(questions) || Object.keys(questions).length === 0) {
+    errors.push("routing.questions must be a non-empty object of questions");
+  } else if (!(routing.primaryQuestion in questions)) {
+    errors.push(
+      `routing.primaryQuestion ${JSON.stringify(routing.primaryQuestion)} is not present in routing.questions`,
+    );
+  } else {
+    // Validate the merged question so a bad override cannot slip through.
+    const primary: Question | undefined = questions[routing.primaryQuestion];
+    if (primary === undefined || !isPlainObject(primary) || primary.type !== "choice") {
+      errors.push(
+        `routing.questions[${JSON.stringify(routing.primaryQuestion)}].type must be "choice"; ` +
+          "score and noul answers cannot name a model category",
+      );
+    }
+  }
+
+  const mapping = routing.modelMapping;
+  if (!isPlainObject(mapping) || Object.keys(mapping).length === 0) {
+    errors.push("routing.modelMapping must be a non-empty object mapping categories to model specs");
+  } else {
+    for (const [category, spec] of Object.entries(mapping)) {
+      if (typeof spec !== "string") {
+        errors.push(`routing.modelMapping[${JSON.stringify(category)}] must be a string, got ${typeof spec}`);
+      }
+    }
+  }
+
+  const threshold = routing.confidenceThreshold;
+  if (typeof threshold !== "number" || !Number.isFinite(threshold) || threshold < 0 || threshold > 1) {
+    errors.push(`routing.confidenceThreshold must be a number in [0, 1], got ${JSON.stringify(threshold)}`);
+  }
+
+  const chains = routing.fallbackChains;
+  if (!isPlainObject(chains)) {
+    errors.push("routing.fallbackChains must be an object of spec -> spec[] chains");
+  } else {
+    for (const [spec, chain] of Object.entries(chains)) {
+      if (!Array.isArray(chain) || chain.length === 0 || !chain.every(isNonEmptyString)) {
+        errors.push(
+          `routing.fallbackChains[${JSON.stringify(spec)}] must be a non-empty array of non-empty strings`,
+        );
+      }
+    }
+  }
+
+  const breaker = config.circuitBreaker;
+  if (typeof breaker.failureThreshold !== "number" || breaker.failureThreshold < 1) {
+    errors.push(`circuitBreaker.failureThreshold must be >= 1, got ${JSON.stringify(breaker.failureThreshold)}`);
+  }
+  if (typeof breaker.cooldownMs !== "number" || breaker.cooldownMs < 0) {
+    errors.push(`circuitBreaker.cooldownMs must be >= 0, got ${JSON.stringify(breaker.cooldownMs)}`);
+  }
+  if (typeof breaker.halfOpenMaxTrials !== "number" || breaker.halfOpenMaxTrials < 1) {
+    errors.push(`circuitBreaker.halfOpenMaxTrials must be >= 1, got ${JSON.stringify(breaker.halfOpenMaxTrials)}`);
+  }
+
+  if (typeof config.jev.timeoutMs !== "number" || config.jev.timeoutMs <= 0) {
+    errors.push(`jev.timeoutMs must be > 0, got ${JSON.stringify(config.jev.timeoutMs)}`);
+  }
+  if (typeof config.laya.timeoutMs !== "number" || config.laya.timeoutMs <= 0) {
+    errors.push(`laya.timeoutMs must be > 0, got ${JSON.stringify(config.laya.timeoutMs)}`);
+  }
+
+  const transport = config.laya.transport;
+  if (transport !== "python" && transport !== "http") {
+    errors.push(`laya.transport must be "python" or "http", got ${JSON.stringify(transport)}`);
+  } else if (transport === "http") {
+    const endpoint = config.laya.endpoint;
+    if (!isNonEmptyString(endpoint)) {
+      errors.push('laya.endpoint must be a non-empty URL when laya.transport is "http"');
+    } else {
+      let parsed: URL | null = null;
+      try {
+        parsed = new URL(endpoint);
+      } catch {
+        parsed = null;
+      }
+      if (parsed === null || (parsed.protocol !== "http:" && parsed.protocol !== "https:")) {
+        errors.push(`laya.endpoint must be an http(s) URL, got ${JSON.stringify(endpoint)}`);
+      }
+    }
+  }
+
+  return errors;
+}
+
+/**
+ * Walk the config paths in precedence order. Missing files everywhere resolve
+ * to a null config without error; read/parse failures are recorded and the
+ * search continues; a contract-violating file is rejected with a null config.
+ */
+export function loadConfig(
+  cwd: string,
+  home: string = os.homedir(),
+  env: Record<string, string | undefined> = process.env,
+): ConfigLoadResult {
+  void env;
+  const errors: string[] = [];
+
+  for (const source of configPaths(cwd, home)) {
+    let raw: string;
+    try {
+      raw = fs.readFileSync(source.path, "utf8");
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
+        const message = error instanceof Error ? error.message : String(error);
+        errors.push(`${source.scope} config ${source.path}: cannot read file: ${message}`);
+      }
+      continue;
+    }
+
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(raw);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      errors.push(`${source.scope} config ${source.path}: invalid JSON: ${message}`);
+      continue;
+    }
+
+    if (!isPlainObject(parsed)) {
+      errors.push(`${source.scope} config ${source.path}: expected a JSON object at the top level`);
+      continue;
+    }
+
+    const config = mergeConfig(defaultConfig(), parsed as RouterConfigInput);
+    const validationErrors = validateConfig(config);
+    if (validationErrors.length > 0) {
+      for (const message of validationErrors) {
+        errors.push(`${source.scope} config ${source.path}: ${message}`);
+      }
+      return { config: null, source: null, errors };
+    }
+
+    return { config, source, errors };
+  }
+
+  return { config: null, source: null, errors };
+}