create-walle 0.10.2 → 0.10.3

package/template/coding-task-manager/lib/model-availability.js

@@ -0,0 +1,727 @@
+'use strict';
+
+// WP-1 (docs/remote-box-model-access-2026-10-26.html §6.1, §5.1 R-3, §5.3 D-2/D-3/D-9):
+// "the box answers what it can serve" — this module is the BOX side of that answer.
+//
+// It makes ONE unauthenticated `GET <origin>/` per distinct origin a configured route points at,
+// and reports the network verdict. It is deliberately NOT the proxy's authenticated generation
+// probe (D-3): an authenticated probe would send the key to that host and spend tokens, and it
+// could not separate "the network path is dead" (the Spark's corporate gateway: 8 s timeout) from
+// "the host answered and refused us" (401 in 0.12 s) — the second is exactly what a live vendor
+// looks like to a credential-less caller.
+//
+// Three rules are load-bearing and enforced by tests/model-availability.test.js:
+//   * NOTHING from a route row is ever sent. No authorization / x-api-key / x-portkey-* header, no
+//     header copied off the row — the probe carries no headers at all (node adds Host, nothing else).
+//   * "reachable" means the network path, never "the key works". Any HTTP status is reachable; the
+//     key is still checked at launch time by the route-readiness probe.
+//   * Timeouts are the signal, so the caps are part of the contract: connect+TLS within
+//     PROBE_CONNECT_MS, the whole probe within PROBE_TOTAL_MS.
+//
+// Results are cached per origin for ORIGIN_TTL_MS, single-flighted per origin, and run at most
+// PROBE_CONCURRENCY at a time (D-9: one probe per origin per 10 min, never a poll).
+const http = require('http');
+const https = require('https');
+
+/** Connect + TLS cap. The Spark's unreachable case needs > 3 s to time out (observed 8.0 s). */
+const PROBE_CONNECT_MS = 3000;
+/** Whole-probe cap, connect included. */
+const PROBE_TOTAL_MS = 5000;
+/** How long one origin's verdict is reused. */
+const ORIGIN_TTL_MS = 10 * 60 * 1000;
+/** At most this many probes are in flight at once. */
+const PROBE_CONCURRENCY = 4;
+/** `?refresh=1` may drop one caller's cache at most once per this window (§6.1). */
+const REFRESH_MIN_INTERVAL_MS = 60 * 1000;
+
+// The adapter default each provider type resolves to when its row carries no `base_url` (§4: the
+// deepseek/moonshot constants are the modules' own export, asserted equal in the unit test; ollama's
+// is wall-e/llm/ollama.js:254). Keys are the `type` values in model_providers.
+const DEFAULT_ORIGINS = Object.freeze({
+  deepseek: 'https://api.deepseek.com',
+  moonshot: 'https://api.moonshot.ai',
+  ollama: 'http://127.0.0.1:11434',
+  openai: 'https://api.openai.com',
+  anthropic: 'https://api.anthropic.com',
+  google: 'https://generativelanguage.googleapis.com',
+});
+
+const LOOPBACK_HOSTS = new Set(['127.0.0.1', 'localhost', '::1', '[::1]']);
+
+// Performance.now()-free wall clock: every stamp is taken through the injected `now` so a test can
+// assert the TTL arithmetic without sleeping.
+function _ms(now) {
+  return typeof now === 'function' ? Number(now()) || 0 : Date.now();
+}
+
+/** scheme://host[:port] of `value`, or null when it is not an http(s) URL. */
+function originOf(value) {
+  const raw = String(value == null ? '' : value).trim();
+  if (!raw) return null;
+  let url = null;
+  try {
+    url = new URL(raw);
+  } catch {
+    return null; // expected: a malformed base_url is "unknown origin", never a probe target
+  }
+  if (url.protocol !== 'http:' && url.protocol !== 'https:') return null;
+  if (!url.hostname) return null;
+  return url.origin;
+}
+
+function _urlOf(origin) {
+  const normalized = originOf(origin);
+  if (!normalized) return null;
+  try {
+    return new URL(normalized);
+  } catch {
+    return null; // expected: originOf already validated the shape; belt and braces
+  }
+}
+
+function _isLoopback(hostname) {
+  return LOOPBACK_HOSTS.has(String(hostname || '').toLowerCase());
+}
+
+function _result(reach, status, startedAt, now) {
+  return {
+    reach,
+    status: status == null ? null : Number(status),
+    connectMs: Math.max(0, _ms(now) - startedAt),
+    probedAt: new Date(startedAt).toISOString(),
+  };
+}
+
+/**
+ * ONE unauthenticated GET against `origin`'s root, with the two caps. NEVER throws and always
+ * resolves with `{ reach, status, connectMs, probedAt }`.
+ *
+ * `reach`: 'reachable' (any HTTP status came back) | 'unreachable' | 'no_server' (a loopback origin
+ * refused the connection — nothing is listening there).
+ */
+function _probeOnce(url, requestFn, now) {
+  return new Promise((resolve) => {
+    const startedAt = _ms(now);
+    let settled = false;
+    let req = null;
+    let totalTimer = null;
+    const settle = (reach, status) => {
+      if (settled) return;
+      settled = true;
+      if (totalTimer) clearTimeout(totalTimer);
+      resolve(_result(reach, status, startedAt, now));
+    };
+    const abandon = () => {
+      try {
+        if (req && typeof req.destroy === 'function') req.destroy();
+      } catch {
+        /* expected: the socket is already gone — this is a probe being abandoned */
+      }
+    };
+    try {
+      totalTimer = setTimeout(() => {
+        abandon();
+        settle('unreachable', null);
+      }, PROBE_TOTAL_MS);
+      if (totalTimer && typeof totalTimer.unref === 'function') totalTimer.unref();
+
+      // No headers are copied from any route row and no credential header is ever added: the only
+      // header on the wire is the Host node itself must send.
+      req = requestFn({
+        protocol: url.protocol,
+        hostname: url.hostname,
+        port: url.port || (url.protocol === 'https:' ? 443 : 80),
+        path: '/',
+        method: 'GET',
+        timeout: PROBE_CONNECT_MS,
+        headers: {},
+        // A fresh socket per probe: a pooled keep-alive socket would skip the connect/TLS events
+        // below (so the 3 s cap could not be lifted) and would outlive the probe.
+        agent: false,
+      }, (res) => {
+        // Any status — 200, 401, 404, 403 — proves the network path. The body is drained and the
+        // socket released at once; a probe never reads a payload.
+        const status = res && res.statusCode != null ? res.statusCode : null;
+        try {
+          if (res && typeof res.resume === 'function') res.resume();
+        } catch {
+          /* expected: draining a response we deliberately never read */
+        }
+        abandon();
+        settle('reachable', status);
+      });
+      if (!req || typeof req.on !== 'function') {
+        settle('unreachable', null);
+        return;
+      }
+      req.on('error', (err) => {
+        // A refused loopback port is "nothing is listening here" (the Ollama rows), not
+        // "the network cannot get there" — the two render differently and mean different things.
+        const code = err && err.code;
+        if (code === 'ECONNREFUSED' && _isLoopback(url.hostname)) {
+          settle('no_server', null);
+          return;
+        }
+        settle('unreachable', null);
+      });
+      req.on('timeout', () => {
+        abandon();
+        settle('unreachable', null);
+      });
+      // `timeout` is a socket IDLE timeout, so on its own it would also cut a host that connected
+      // and is slow to answer. PROBE_CONNECT_MS caps connect + TLS only: once the socket is
+      // connected (https: TLS done) the idle timeout is lifted and PROBE_TOTAL_MS alone bounds the
+      // wait for the status line.
+      req.on('socket', (socket) => {
+        if (!socket || typeof socket.once !== 'function') return;
+        socket.once(url.protocol === 'https:' ? 'secureConnect' : 'connect', () => {
+          if (typeof req.setTimeout === 'function') req.setTimeout(0);
+        });
+      });
+      req.end();
+    } catch {
+      // expected: a synchronous throw from a malformed request is "the probe did not answer"
+      settle('unreachable', null);
+    }
+  });
+}
+
+// ---- at most PROBE_CONCURRENCY probes at once -------------------------------------------------
+let _active = 0;
+const _waiting = [];
+
+function _acquire() {
+  if (_active < PROBE_CONCURRENCY) {
+    _active += 1;
+    return Promise.resolve();
+  }
+  // The slot is handed over by _release (the count never drops), so a caller arriving between the
+  // release and this waiter's continuation cannot take the same slot and exceed the cap.
+  return new Promise((resolve) => {
+    _waiting.push(resolve);
+  });
+}
+
+function _release() {
+  const next = _waiting.shift();
+  if (typeof next === 'function') {
+    next();
+    return;
+  }
+  _active = Math.max(0, _active - 1);
+}
+
+/**
+ * ONE unauthenticated probe of `origin`. Never throws; `request` and `now` are injectable so a test
+ * drives it with a fake socket and a fake clock (and can prove the header rule by recording).
+ *
+ * @returns {Promise<{reach: string, status: number|null, connectMs: number|null, probedAt: string|null}>}
+ */
+function probeOrigin(origin, { request, now = Date.now } = {}) {
+  const url = _urlOf(origin);
+  if (!url) return Promise.resolve({ reach: 'unknown', status: null, connectMs: null, probedAt: null });
+  const requestFn = typeof request === 'function'
+    ? request
+    : (url.protocol === 'https:' ? https.request : http.request);
+  return _probeOnce(url, requestFn, now);
+}
+
+// ---- per-origin cache + single-flight ---------------------------------------------------------
+/** origin -> { result, at }. Process state by design: a verdict is about NOW, and a restart may. */
+const _cache = new Map();
+/** origin -> in-flight promise, so N concurrent callers cost ONE probe. */
+const _inflight = new Map();
+/** caller key -> the hub CLOCK stamp of its last honoured `?refresh=1`. */
+const _refreshAt = new Map();
+
+/**
+ * One probe of `origin` behind the 10 min cache, the per-origin single flight AND the at-most-
+ * PROBE_CONCURRENCY gate — every probe this module makes on behalf of a caller goes through here, so
+ * the cap and the single flight are properties of the probing path, not of one implementation of it.
+ * `cache` is injectable (a Map) so a test isolates one case from the next; production uses the
+ * module map.
+ */
+function _probeThrough(origin, probeFn, { request, now, cache, bypassCache }) {
+  const key = String(origin);
+  if (!bypassCache) {
+    const entry = cache.get(key);
+    if (entry && _ms(now) - Number(entry.at || 0) < ORIGIN_TTL_MS) return Promise.resolve(entry.result);
+  }
+  const pending = _inflight.get(key);
+  if (pending) return pending;
+  const run = _acquire()
+    .then(() => probeFn(origin, { request, now }))
+    .then((result) => {
+      _release();
+      cache.set(key, { result, at: _ms(now) });
+      return result;
+    }, (error) => {
+      _release();
+      throw error;
+    })
+    .finally(() => {
+      _inflight.delete(key);
+    });
+  _inflight.set(key, run);
+  return run;
+}
+
+/**
+ * The cached, single-flighted, concurrency-capped verdict for ONE origin -- the same path
+ * buildAvailability uses (R-4: no second probe, never a header from a route row).
+ * @returns {Promise<{reach:'reachable'|'unreachable'|'no_server'|'unknown', status:number|null, connectMs:number|null, probedAt:string|null}>}
+ */
+function originVerdict(origin, { probe = probeOrigin, cache = _cache, now = Date.now, request } = {}) {
+  const normalized = originOf(origin);
+  if (!normalized) return Promise.resolve({ reach: 'unknown', status: null, connectMs: null, probedAt: null });
+  return _probeThrough(normalized, probe, { request, now, cache, bypassCache: false });
+}
+
+/** The `?refresh=1` gate: honest at most once per caller per window (§6.1). */
+function _mayRefresh(callerKey, now) {
+  const key = String(callerKey || 'local');
+  const t = _ms(now);
+  const last = Number(_refreshAt.get(key) || 0);
+  if (last && t - last < REFRESH_MIN_INTERVAL_MS) return false;
+  _refreshAt.set(key, t);
+  return true;
+}
+
+function _isEnabled(row) {
+  return !(row && (row.enabled === 0 || row.enabled === false));
+}
+
+/** `keyed` follows the redacted list's own `has_credential` (model-admin.js:946). */
+function _isKeyed(row) {
+  if (!row) return false;
+  if (Object.prototype.hasOwnProperty.call(row, 'has_credential')) return !!row.has_credential;
+  return !!row.has_key;
+}
+
+function _rowOrigin(row) {
+  const base = row && (row.base_url || row.baseUrl);
+  const fromBase = originOf(base);
+  if (fromBase) return fromBase;
+  const type = String((row && row.type) || '').trim().toLowerCase();
+  return DEFAULT_ORIGINS[type] || null;
+}
+
+/** The row list inside a `/api/models/providers` body — [] for any other shape. */
+function _providersOf(body) {
+  if (!body || typeof body !== 'object') return [];
+  return Array.isArray(body.providers) ? body.providers.filter((row) => row && typeof row === 'object') : [];
+}
+
+/** The box's own route rows, from its Wall-E `GET /api/models/providers` over loopback. */
+async function _readProviderRows(walleClient) {
+  const client = walleClient || require('./walle-client');
+  const response = await client.requestJson('/api/models/providers');
+  return _providersOf(response && response.json);
+}
+
+/** `{ claude: { signedIn }, codex: { signedIn } }` from either the wire shape or a normalized one. */
+function _normalizeNative(loginState) {
+  const providers = loginState && typeof loginState === 'object' && loginState.providers
+    ? loginState.providers
+    : loginState;
+  const signedInOf = (agent) => {
+    const entry = providers && providers[agent];
+    if (!entry || typeof entry !== 'object') return false;
+    if (typeof entry.signedIn === 'boolean') return entry.signedIn;
+    const account = entry.account;
+    return !!(account && typeof account === 'object' && account.signedIn === true);
+  };
+  return { claude: { signedIn: signedInOf('claude') }, codex: { signedIn: signedInOf('codex') } };
+}
+
+/**
+ * §6.1's 200 body. Rows come from the box's own Wall-E (`/api/models/providers`, key already
+ * stripped), one probe per distinct origin, and NOTHING but a verdict leaves this function: no key
+ * bytes, no header values, no header names off a row.
+ *
+ * @param {object} deps
+ * @param {object} deps.walleClient   loopback Wall-E client (`{ requestJson }`)
+ * @param {object} deps.loginState    `GET /api/providers/login-state`'s body (or a normalized one)
+ * @param {Array}  deps.delegatePrefs the box's `default:claude` / `default:codex` rows
+ * @param {Function} [deps.probe]     probe implementation (defaults to probeOrigin)
+ * @param {Map}    [deps.cache]       per-origin cache (defaults to the module cache)
+ */
+async function buildAvailability({
+  walleClient,
+  loginState,
+  delegatePrefs,
+  probe = probeOrigin,
+  cache = _cache,
+  refresh = false,
+  now = Date.now,
+  instanceId = '',
+  callerKey = 'local',
+  request,
+} = {}) {
+  const checkedAt = _ms(now);
+  const rows = await _readProviderRows(walleClient);
+  const bypassCache = refresh === true && _mayRefresh(callerKey, now);
+
+  const origins = [];
+  for (const row of rows) {
+    const origin = _rowOrigin(row);
+    if (origin && !origins.includes(origin)) origins.push(origin);
+  }
+  const verdicts = new Map();
+  await Promise.all(origins.map(async (origin) => {
+    const result = await _probeThrough(origin, probe, { request, now, cache, bypassCache });
+    verdicts.set(origin, result);
+  }));
+
+  const routes = rows.map((row) => {
+    const origin = _rowOrigin(row);
+    const verdict = origin ? verdicts.get(origin) : null;
+    return {
+      id: String(row.id == null ? '' : row.id),
+      type: String(row.type == null ? '' : row.type),
+      enabled: _isEnabled(row),
+      keyed: _isKeyed(row),
+      origin,
+      reach: verdict ? verdict.reach : 'unknown',
+      status: verdict ? verdict.status : null,
+      connectMs: verdict ? verdict.connectMs : null,
+      probedAt: verdict ? verdict.probedAt : null,
+    };
+  });
+
+  const byId = new Map(routes.map((route) => [route.id, route]));
+  const prefs = Array.isArray(delegatePrefs) ? delegatePrefs : [];
+  const delegateDefaults = prefs
+    .filter((pref) => pref && typeof pref === 'object')
+    .map((pref) => {
+      const routeId = String(pref.routeId == null ? '' : pref.routeId);
+      const row = byId.get(routeId);
+      return {
+        agent: String(pref.agent == null ? '' : pref.agent),
+        lane: String(pref.lane == null ? '' : pref.lane),
+        routeId,
+        model: String(pref.model == null ? '' : pref.model),
+        reach: row ? row.reach : 'unknown',
+      };
+    });
+
+  return {
+    ok: true,
+    instanceId: String(instanceId || ''),
+    checkedAt: new Date(checkedAt).toISOString(),
+    routes,
+    delegateDefaults,
+    native: _normalizeNative(loginState),
+  };
+}
+
+// ------------------------------------------------------------------------------------------------
+// WP-4 §6.4 (docs/remote-box-model-access-2026-10-26.html): REMOVE a box's own route rows.
+//
+// The hub never writes a box's rows directly (R-2: the box owns its rows), so the box exposes the
+// removal and the box's own Wall-E is the only thing that deletes. This module owns the two things
+// that make that safe: the request shape is validated HERE (both the box route and the hub route
+// call `normalizeRouteIds`, so a malformed body is one 400 with one message), and the DELETE is
+// aimed only at ids the box actually has — Wall-E answers 200 for an unknown id (wall-e/http/
+// model-admin.js), so "not in the list" would otherwise be reported as removed.
+//
+// Nothing in this path reads, copies or returns a credential: only ids cross the wire, and both
+// halves of the answer are id lists.
+// ------------------------------------------------------------------------------------------------
+
+/** `{ routeIds }` bound, shared by the box route and the hub route (§6.4: 1..64). */
+const MAX_ROUTE_IDS = 64;
+/** Longest accepted route id (§6.4: 200 chars). */
+const MAX_ROUTE_ID_CHARS = 200;
+
+/**
+ * Validate a `routeIds` value: an array of 1..64 non-empty strings, each at most 200 chars, deduped
+ * preserving first-seen order. Anything else is `{ ok: false, message }` — one wording for both
+ * routes, so the two 400s cannot drift.
+ *
+ * @returns {{ok: true, ids: string[]} | {ok: false, message: string}}
+ */
+function normalizeRouteIds(value) {
+  if (!Array.isArray(value)) return { ok: false, message: 'routeIds must be an array of strings' };
+  if (value.length < 1 || value.length > MAX_ROUTE_IDS) {
+    return { ok: false, message: `routeIds must hold between 1 and ${MAX_ROUTE_IDS} ids` };
+  }
+  const ids = [];
+  for (const raw of value) {
+    if (typeof raw !== 'string') return { ok: false, message: 'routeIds must contain only strings' };
+    if (!raw.trim()) return { ok: false, message: 'routeIds must not contain an empty id' };
+    if (raw.length > MAX_ROUTE_ID_CHARS) return { ok: false, message: `a route id is longer than ${MAX_ROUTE_ID_CHARS} characters` };
+    if (!ids.includes(raw)) ids.push(raw);
+  }
+  return { ok: true, ids };
+}
+
+/**
+ * Remove route ids from the box's own Wall-E (§6.4): ONE pre-read of `GET /api/models/providers`
+ * decides what exists, then exactly ONE `DELETE /api/models/providers/<id>` per present distinct id.
+ * An id the box does not have lands in `missing` and is NEVER deleted (Wall-E's DELETE answers 200
+ * even for an unknown id, so a blind delete could not be told apart from a real removal).
+ *
+ * A Wall-E non-2xx on the read or on any delete is `walle_unavailable` — the caller's 502, never a
+ * partial success dressed up as one.
+ *
+ * @param {object} deps
+ * @param {object} [deps.walleClient] loopback Wall-E client (`{ requestJson }`); defaults to the real one
+ * @param {string[]} deps.routeIds
+ * @returns {Promise<{removed: string[], missing: string[]}>}
+ */
+async function removeRoutes({ walleClient, routeIds } = {}) {
+  const client = walleClient || require('./walle-client');
+  const normalized = normalizeRouteIds(routeIds);
+  if (!normalized.ok) {
+    const error = new Error(normalized.message);
+    error.code = 'invalid_request';
+    throw error;
+  }
+  const read = await client.requestJson('/api/models/providers');
+  const readStatus = Number(read && read.status);
+  if (!Number.isFinite(readStatus) || readStatus < 200 || readStatus >= 300) {
+    const error = new Error('Wall-E did not answer the provider read');
+    error.code = 'walle_unavailable';
+    throw error;
+  }
+  const present = new Set(_providersOf(read && read.json).map((row) => String(row.id == null ? '' : row.id)));
+  const removed = [];
+  const missing = [];
+  for (const id of normalized.ids) {
+    if (!present.has(id)) {
+      missing.push(id);
+      continue;
+    }
+    const answer = await client.requestJson(`/api/models/providers/${encodeURIComponent(id)}`, { method: 'DELETE' });
+    const status = Number(answer && answer.status);
+    if (!Number.isFinite(status) || status < 200 || status >= 300) {
+      const error = new Error(`Wall-E refused the delete (${status || 0})`);
+      error.code = 'walle_unavailable';
+      throw error;
+    }
+    removed.push(id);
+  }
+  return { removed, missing };
+}
+
+// ------------------------------------------------------------------------------------------------
+// WP-5 §6.4 (docs/remote-box-model-access-2026-10-26.html): COPY one hub route onto a box.
+//
+// The direction is deliberately the same as the remove leg's — the box owns its rows, so the hub
+// never writes them (R-2) and asks the box to import — but with one difference that is the whole of
+// R-5/R-6: this is the only path where a CREDENTIAL crosses a machine boundary, and only because
+// the user clicked "Use on <box>" for ONE route. Three rules make that safe:
+//   * the hub reads the row (key included) from its OWN Wall-E over loopback, through
+//     `GET /api/wall-e/internal/provider-export` — a loopback-only leaf, never a browser route;
+//   * the row crosses to the box over the hub's own peer credential, and is a strict ALLOWLIST
+//     (`normalizeImportRow`), so a sender can never push an unvetted column (custom headers, a
+//     usage/health counter, a derived field) into the box's table — and an unknown key is a 400,
+//     never a silent drop;
+//   * nothing on either side logs or returns the key: both halves answer `{ ok, routeId }`, and the
+//     request body is the only carrier.
+// ------------------------------------------------------------------------------------------------
+
+/** The import row's fields — exactly what a hub export can carry, and nothing else (§6.4). */
+const IMPORT_ROW_FIELDS = Object.freeze([
+  'id', 'name', 'type', 'base_url', 'auth_method', 'api_key', 'enabled',
+  'max_output_tokens', 'reasoning_field', 'reasoning_effort_default', 'ca_cert_pem',
+]);
+const IMPORT_ROW_FIELD_SET = new Set(IMPORT_ROW_FIELDS);
+/** Per-field bounds. `api_key` is bounded only as a sanity cap — never truncated (a cut key would
+ *  be a silently broken route); `ca_cert_pem` matches wall-e/http/model-provider-ca.js's 64 KB PEM. */
+const IMPORT_FIELD_CHARS = Object.freeze({
+  id: 200, name: 200, type: 60, base_url: 500, auth_method: 60, api_key: 512, reasoning_field: 60,
+  reasoning_effort_default: 40, ca_cert_pem: 70000,
+});
+/** The reasoning-effort values the brain's own upsert accepts (brain/models.js). */
+const IMPORT_REASONING_EFFORTS = new Set(['low', 'medium', 'xhigh', 'off']);
+
+/** One required/optional import string: `{ value }` or `{ message }` — the message is constant. */
+function _importString(value, field, { required = false } = {}) {
+  if (value === undefined || value === null) {
+    return required ? { message: `row.${field} is required` } : { value: null };
+  }
+  if (typeof value !== 'string') return { message: `row.${field} must be a string` };
+  const trimmed = value.trim();
+  if (!trimmed) return required ? { message: `row.${field} is required` } : { value: null };
+  if (trimmed.length > IMPORT_FIELD_CHARS[field]) {
+    return { message: `row.${field} is longer than ${IMPORT_FIELD_CHARS[field]} characters` };
+  }
+  return { value: trimmed };
+}
+
+/**
+ * Validate ONE imported route row (§6.4). The allowlist is the point: an unknown key is a 400 —
+ * never dropped — because a key the sender thought mattered and that this route quietly ignored
+ * would be a route that looks copied and is not.
+ *
+ * @returns {{ok: true, row: object} | {ok: false, message: string}}
+ */
+function normalizeImportRow(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    return { ok: false, message: 'row must be an object' };
+  }
+  for (const key of Object.keys(value)) {
+    if (!IMPORT_ROW_FIELD_SET.has(key)) return { ok: false, message: 'row carries a field this route does not accept' };
+  }
+  const row = {};
+  for (const field of ['id', 'name', 'type', 'base_url']) {
+    const parsed = _importString(value[field], field, { required: field === 'id' || field === 'name' || field === 'type' });
+    if (parsed.message) return { ok: false, message: parsed.message };
+    if (parsed.value !== null) row[field] = parsed.value;
+  }
+  for (const field of ['auth_method', 'api_key', 'reasoning_field', 'ca_cert_pem']) {
+    const parsed = _importString(value[field], field);
+    if (parsed.message) return { ok: false, message: parsed.message };
+    if (parsed.value !== null) row[field] = parsed.value;
+  }
+  if (value.enabled !== undefined && value.enabled !== null && typeof value.enabled !== 'boolean' && value.enabled !== 0 && value.enabled !== 1) {
+    return { ok: false, message: 'row.enabled must be a boolean' };
+  }
+  row.enabled = !(value.enabled === false || value.enabled === 0);
+  if (value.max_output_tokens !== undefined && value.max_output_tokens !== null) {
+    if (!Number.isInteger(value.max_output_tokens) || value.max_output_tokens <= 0) {
+      return { ok: false, message: 'row.max_output_tokens must be a positive integer' };
+    }
+    row.max_output_tokens = value.max_output_tokens;
+  }
+  const effort = _importString(value.reasoning_effort_default, 'reasoning_effort_default');
+  if (effort.message) return { ok: false, message: effort.message };
+  if (effort.value !== null) {
+    if (!IMPORT_REASONING_EFFORTS.has(effort.value)) return { ok: false, message: 'row.reasoning_effort_default is not a valid effort level' };
+    row.reasoning_effort_default = effort.value;
+  }
+  return { ok: true, row };
+}
+
+/** Longest accepted `expectOrigin` — a `scheme://host[:port]` far below any real origin. */
+const MAX_COPY_ORIGIN_CHARS = 300;
+
+/**
+ * Validate a §6.4 copy request: `{ routeId, expectOrigin }` — BOTH present, and nothing else.
+ * `expectOrigin` is the origin the `copyable` list showed the user, compared exactly — it is what turns a list the client
+ * read a minute ago into a refusal (`origin_changed`) rather than a copy of a row that has since
+ * been repointed at a different host.
+ *
+ * @returns {{ok: true, routeId: string, expectOrigin: string} | {ok: false, message: string}}
+ */
+function normalizeCopyRequest(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    return { ok: false, message: 'the request body must be an object' };
+  }
+  for (const key of Object.keys(value)) {
+    if (key !== 'routeId' && key !== 'expectOrigin') return { ok: false, message: 'the body carries a field this route does not accept' };
+  }
+  const routeId = typeof value.routeId === 'string' ? value.routeId.trim() : '';
+  if (!routeId) return { ok: false, message: 'routeId is required' };
+  if (routeId.length > MAX_ROUTE_ID_CHARS) return { ok: false, message: `routeId is longer than ${MAX_ROUTE_ID_CHARS} characters` };
+  // BOTH fields are required: an absent `expectOrigin` would silently degrade the stale-UI guard
+  // into nothing, where the client that never checked an origin should hear about it instead. An
+  // EMPTY string is a real value — it is what the list shows for a row with no resolvable origin.
+  if (typeof value.expectOrigin !== 'string') return { ok: false, message: 'expectOrigin is required' };
+  const expectOrigin = value.expectOrigin.trim();
+  if (expectOrigin.length > MAX_COPY_ORIGIN_CHARS) {
+    return { ok: false, message: `expectOrigin is longer than ${MAX_COPY_ORIGIN_CHARS} characters` };
+  }
+  return { ok: true, routeId, expectOrigin };
+}
+
+/** The origin a hub row is copied FROM: its own `base_url`, else its type's adapter default. */
+function rowOrigin(row) {
+  return _rowOrigin(row);
+}
+
+/**
+ * The raw upsert's wire body for a validated import row (wall-e/http/model-admin.js's
+ * `POST /api/models/providers` → brain/models.js's `upsertModelProvider`): the three columns whose
+ * wire names differ from the row's, and nothing else. `auth_method` is NOT accepted by that
+ * destructuring, so it is not forwarded — see the module's report note (WP-5a observation).
+ */
+function _upsertBodyFor(row) {
+  const body = { id: row.id, name: row.name, type: row.type, enabled: row.enabled };
+  if (row.base_url) body.baseUrl = row.base_url;
+  if (row.api_key) body.apiKeyEncrypted = row.api_key;
+  if (row.ca_cert_pem) body.caCert = row.ca_cert_pem;
+  if (row.max_output_tokens) body.max_output_tokens = row.max_output_tokens;
+  if (row.reasoning_field) body.reasoning_field = row.reasoning_field;
+  if (row.reasoning_effort_default) body.reasoning_effort_default = row.reasoning_effort_default;
+  return body;
+}
+
+/** `{status, json}` of one loopback call, or throws `walle_unavailable` for anything unusable. */
+function _requireWalleAnswer(answer, what) {
+  const status = Number(answer && answer.status);
+  if (!Number.isFinite(status) || status < 200 || status >= 300) {
+    const error = new Error(`Wall-E did not answer the ${what}`);
+    error.code = 'walle_unavailable';
+    throw error;
+  }
+  return answer;
+}
+
+/**
+ * §6.4: create/replace ONE route on the box's own Wall-E from an already-validated import row.
+ * The row is validated AGAIN here (the box route calls both, like the remove leg's two callers), so
+ * a direct caller of this function can never reach Wall-E with an unvetted row.
+ *
+ * @returns {Promise<{routeId: string}>} — never the row, never the key
+ */
+async function importRoute({ walleClient, row } = {}) {
+  const client = walleClient || require('./walle-client');
+  const normalized = normalizeImportRow(row);
+  if (!normalized.ok) {
+    const error = new Error(normalized.message);
+    error.code = 'invalid_request';
+    throw error;
+  }
+  const answer = await client.requestJson('/api/models/providers', { method: 'POST', body: _upsertBodyFor(normalized.row) });
+  _requireWalleAnswer(answer, 'provider write');
+  return { routeId: normalized.row.id };
+}
+
+/** The HUB's own route rows (`GET /api/models/providers` on this machine's Wall-E; keys already
+ *  stripped by that list). Throws `walle_unavailable` when the read is not a usable answer. */
+async function readOwnProviderRows({ walleClient } = {}) {
+  const client = walleClient || require('./walle-client');
+  const answer = _requireWalleAnswer(await client.requestJson('/api/models/providers'), 'provider read');
+  return _providersOf(answer.json);
+}
+
+/**
+ * §6.4/R-5: ONE hub route WITH its key, read over loopback through Wall-E's export leaf — the only
+ * read in this codebase that returns a credential. `null` means "no such route" (the leaf's 404);
+ * anything else non-2xx is `walle_unavailable`.
+ *
+ * @returns {Promise<{row: object}|null>}
+ */
+async function exportOwnRoute({ walleClient, routeId } = {}) {
+  const client = walleClient || require('./walle-client');
+  const path = `/api/wall-e/internal/provider-export?id=${encodeURIComponent(String(routeId || ''))}`;
+  const answer = await client.requestJson(path);
+  if (Number(answer && answer.status) === 404) return null;
+  _requireWalleAnswer(answer, 'provider export');
+  const row = answer.json && answer.json.row;
+  return row && typeof row === 'object' ? { row } : null;
+}
+
+module.exports = {
+  DEFAULT_ORIGINS,
+  probeOrigin,
+  buildAvailability,
+  normalizeRouteIds,
+  removeRoutes,
+  normalizeImportRow,
+  normalizeCopyRequest,
+  importRoute,
+  readOwnProviderRows,
+  exportOwnRoute,
+  rowOrigin,
+  originOf,
+  originVerdict,
+  PROBE_CONNECT_MS,
+  PROBE_TOTAL_MS,
+  ORIGIN_TTL_MS,
+  PROBE_CONCURRENCY,
+  REFRESH_MIN_INTERVAL_MS,
+};