model-compare-opencode-plugin 0.0.0-stage → 0.1.0

package/src/opencode/usebest.ts

@@ -0,0 +1,121 @@
+// src/opencode/usebest.ts
+// Shared /use-best decision + alias-view helpers (design §10). Pure module:
+// no OpenCode imports, no I/O. Both the server command (src/index.ts) and the
+// TUI entry (src/tui.tsx) consume it, so their decisions and messages can
+// never drift apart.
+
+import { parseUseBest, sanitizeCatalogText } from "./commands"
+import type { Priority } from "../core/types"
+
+export const PRIORITIES: readonly Priority[] = ["balanced", "price", "quality"]
+export const ALIAS_PROVIDER = "openrouter"
+export const aliasId = (p: Priority): string => `model-compare/${p}`
+export const aliasRef = (p: Priority): string => `${ALIAS_PROVIDER}/${aliasId(p)}`
+
+// The headless refusal text (§10; pinned by the integration suite's
+// REFUSAL_TEXT).
+export function useBestRefusal(p: Priority): string {
+  return `model-compare: ${aliasRef(p)} is currently disabled (no ranking data); not switching`
+}
+
+// The switch notice: the pick shown is the one the alias serves right now (a
+// pin can differ from rank 1 — minLead hysteresis), sanitized (F-20); "null"
+// means the caller could not observe a pick and says "unavailable".
+export function useBestNotice(p: Priority, currentPickId: string | null): string {
+  const pick = currentPickId === null ? "unavailable" : sanitizeCatalogText(currentPickId)
+  return `model-compare: switched to ${aliasRef(p)} (currently ${pick})`
+}
+
+// The full decision for a /use-best invocation: argument parsing plus the
+// enabled gate. `enabled` is the caller's registry view of each priority —
+// the server command reads state.enabled, the TUI entry reads the model
+// registry (which omits disabled aliases in some states and reports
+// `enabled: false` in others; absence is read as disabled by the caller).
+export function useBestDecision(input: {
+  argument: string
+  defaultPriority: Priority
+  enabled: (p: Priority) => boolean
+}): { ok: true; priority: Priority } | { ok: false; message: string } {
+  const parsed = parseUseBest(input.argument, input.defaultPriority)
+  if (!parsed.ok) return parsed
+  if (!input.enabled(parsed.priority)) {
+    return { ok: false, message: useBestRefusal(parsed.priority) }
+  }
+  return parsed
+}
+
+// ---- registry views (the TUI side's data source) ---------------------------
+
+// One model-compare alias as observed in the model registry.
+export type AliasView = {
+  priority: Priority
+  name: string
+  enabled: boolean
+  modelID: string | null
+}
+
+// Extract the plugin's alias entries from a model-list response. Only entries
+// present in the list are returned; a disabled alias is either omitted
+// entirely or reported with enabled: false — callers must treat a missing
+// view as disabled (probe-verified: list() omits disabled aliases).
+export function readAliasViews(
+  entries: ReadonlyArray<{ id?: unknown; name?: unknown; enabled?: unknown; modelID?: unknown }>,
+): AliasView[] {
+  const prefix = "model-compare/"
+  const views: AliasView[] = []
+  for (const entry of entries) {
+    if (typeof entry.id !== "string" || !entry.id.startsWith(prefix)) continue
+    const priority = entry.id.slice(prefix.length)
+    if (!PRIORITIES.includes(priority as Priority)) continue
+    views.push({
+      priority: priority as Priority,
+      name: typeof entry.name === "string" ? entry.name : "",
+      enabled: entry.enabled !== false,
+      modelID: typeof entry.modelID === "string" ? entry.modelID : null,
+    })
+  }
+  return views.sort(
+    (x, y) => PRIORITIES.indexOf(x.priority) - PRIORITIES.indexOf(y.priority),
+  )
+}
+
+// The pick shown in an alias's display name:
+// "Model Compare: <p> → <pick>[( fallback)]" → "<pick>[( fallback)]", or null
+// for the "(unavailable)" placeholder names.
+export function pickFromName(name: string): string | null {
+  const arrow = name.indexOf("→")
+  if (arrow === -1) return null
+  return name.slice(arrow + 1).trim()
+}
+
+// The pick an ENABLED alias view serves, or null when nothing observable is
+// served: the display name is the truth (it mirrors the picker, including
+// the "(fallback)" marker); modelID is the fallback when the name has no
+// arrow; an empty name is also "nothing observable". Exported for the TUI
+// half's picks dialog (statusLine's rules, one priority at a time). The
+// result is a DISPLAY string only (footer, dialog, toasts) and is flattened
+// here (F-20) as defense in depth: the name is normally built sanitized by
+// planAlias, but modelID is registry-sourced and can carry raw catalog text.
+export function pickOf(view: AliasView): string | null {
+  const pick = pickFromName(view.name) ?? view.modelID ?? (view.name === "" ? null : "unavailable")
+  return pick === null ? null : sanitizeCatalogText(pick)
+}
+
+// The priority column width for aligned pick rows: the longest priority
+// name ("balanced"), so every arrow — and the pick after it — starts at the
+// same column in the picks dialog: `price` gains three spaces before its
+// arrow, `quality` one.
+export function alignedPriority(priority: Priority): string {
+  return priority.padEnd(Math.max(...PRIORITIES.map((p) => p.length)))
+}
+
+// The compact footer line — the balanced pick only, e.g.
+// `MC: balanced → xiaomi/mimo-v2.6-flash`. The full three-priority view
+// lives behind the picks dialog (a select over the alias views);
+// registry-absent and disabled aliases read "disabled", a present-but-
+// unresolvable one reads "unavailable" — the line never vanishes.
+export function statusLine(views: AliasView[]): string {
+  const view = views.find((item) => item.priority === "balanced")
+  if (view === undefined || view.enabled === false) return "MC: balanced → disabled"
+  return `MC: balanced → ${pickOf(view) ?? "unavailable"}`
+}

package/src/rpc.ts

@@ -0,0 +1,78 @@
+// src/rpc.ts
+// The plugin's RPC surface (V2 plugins RPC): methods the TUI half and other
+// clients can call on the server plugin, plus the event the /model-compare
+// command emits. The report method returns the SAME text the command
+// synthesizes — one builder in src/index.ts serves both, so the two can
+// never drift. The report EVENT carries the structured entries (the TUI's
+// selectable report dialog), because the transcript notice itself only
+// surfaces at the session's next turn.
+import { Rpc } from "@opencode/plugin/rpc"
+
+export const ModelCompare = Rpc.define({
+  id: "model-compare",
+  methods: {
+    report: {
+      input: { type: "object", properties: {}, additionalProperties: false },
+      output: {
+        type: "object",
+        properties: {
+          text: { type: "string" },
+          age: { type: ["string", "null"] },
+          entries: {
+            type: "array",
+            items: {
+              type: "object",
+              properties: {
+                priority: { type: "string" },
+                rank: { type: ["integer", "null"] },
+                id: { type: "string" },
+                value: { type: "string" },
+                score: { type: "string" },
+                quality: { type: "string" },
+                price: { type: "string" },
+                current: { type: "boolean" },
+                fromFallback: { type: "boolean" },
+              },
+              required: ["priority", "rank", "id", "value", "score", "quality", "price", "current", "fromFallback"],
+              additionalProperties: false,
+            },
+          },
+        },
+        required: ["text", "age", "entries"],
+        additionalProperties: false,
+      },
+    },
+  },
+  events: {
+    report: {
+      schema: {
+        type: "object",
+        properties: {
+          sessionID: { type: "string" },
+          age: { type: ["string", "null"] },
+          entries: {
+            type: "array",
+            items: {
+              type: "object",
+              properties: {
+                priority: { type: "string" },
+                rank: { type: ["integer", "null"] },
+                id: { type: "string" },
+                value: { type: "string" },
+                score: { type: "string" },
+                quality: { type: "string" },
+                price: { type: "string" },
+                current: { type: "boolean" },
+                fromFallback: { type: "boolean" },
+              },
+              required: ["priority", "rank", "id", "value", "score", "quality", "price", "current", "fromFallback"],
+              additionalProperties: false,
+            },
+          },
+        },
+        required: ["sessionID", "age", "entries"],
+        additionalProperties: false,
+      },
+    },
+  },
+})

package/src/sources/index.ts

@@ -0,0 +1,115 @@
+// src/sources/index.ts
+// Source selection and acquisition (design §3, §9): pick the catalog source
+// and run it. "local" runs the configured-or-vendored script and rejects on
+// failure — the caller keeps its last-known-good document. "auto" probes
+// python first, runs local when it passes, and degrades to the remote catalog
+// with an actionable warning when python is unusable or the local run fails
+// (§3: warn and degrade, never throw from setup). "remote" fetches the
+// published catalog without ever touching python. Only a failed remote
+// fallback rejects.
+
+import { fileURLToPath } from "node:url"
+import type { Config } from "../config"
+import type { Sourced } from "../core/types"
+import { localIdentity, remoteIdentity, type Storage } from "../opencode/storage"
+import { probePython, runLocalScript } from "./local"
+import { fetchRemote } from "./remote"
+
+// The vendored script, resolved from this module (src/sources/) back to the
+// package root so it is found regardless of the process's working directory.
+const VENDORED_SCRIPT = fileURLToPath(new URL("../../vendor/model_compare.py", import.meta.url))
+
+// Injectable seams for tests; each defaults to the real implementation.
+// storage is required because the remote path cannot proceed without it.
+export type AcquireDeps = {
+  storage: Storage
+  probePython?: typeof probePython
+  runLocal?: typeof runLocalScript
+  fetchRemote?: typeof fetchRemote
+}
+
+export type Acquired = {
+  sourced: Sourced
+  source: "local" | "remote"
+  // The cache identity of the source that produced the document (storage.ts):
+  // the tick persists the document under it.
+  identity: string
+  fromCache: boolean
+  warnings: string[]
+}
+
+// runLocalScript prefixes every failure with this; the fallback warning
+// re-wraps the cause instead of repeating the prefix.
+const LOCAL_PREFIX = "local source failed: "
+
+function asReason(error: unknown): string {
+  return error instanceof Error ? error.message : String(error)
+}
+
+export async function acquire(cfg: Config, deps: AcquireDeps): Promise<Acquired> {
+  const probe = deps.probePython ?? probePython
+  const runLocal = deps.runLocal ?? runLocalScript
+  const doFetch = deps.fetchRemote ?? fetchRemote
+
+  const scriptPath = cfg.scriptPath ?? VENDORED_SCRIPT
+
+  // Remote mode never probes python or runs the script (§9). fetchRemote's
+  // fromCache flag is lifted to the result; sourced itself stays a plain
+  // Sourced (§5).
+  if (cfg.source === "remote") {
+    const { doc, acquiredAt, fromCache } = await doFetch(cfg.catalogURL, deps.storage)
+    return {
+      sourced: { doc, acquiredAt },
+      source: "remote",
+      identity: remoteIdentity(cfg.catalogURL),
+      fromCache,
+      warnings: [],
+    }
+  }
+
+  if (cfg.source === "local") {
+    const sourced = await runLocal(scriptPath)
+    return { sourced, source: "local", identity: localIdentity(cfg.scriptPath), fromCache: false, warnings: [] }
+  }
+
+  // Auto: probe first; a usable python gets one local attempt. Either
+  // failure — the probe or the run — degrades to remote with the cause named.
+  const warnings: string[] = []
+  const probed = await probe()
+  if (probed.ok) {
+    try {
+      const sourced = await runLocal(scriptPath)
+      return {
+        sourced,
+        source: "local",
+        identity: localIdentity(cfg.scriptPath),
+        fromCache: false,
+        warnings: [],
+      }
+    } catch (error) {
+      const cause = asReason(error).replace(LOCAL_PREFIX, "")
+      warnings.push(`local source failed (${cause}); using remote catalog`)
+    }
+  } else {
+    warnings.push(`${probed.reason}; using remote catalog`)
+  }
+
+  const { doc, acquiredAt, fromCache } = await doFetch(cfg.catalogURL, deps.storage)
+  return {
+    sourced: { doc, acquiredAt },
+    source: "remote",
+    identity: remoteIdentity(cfg.catalogURL),
+    fromCache,
+    warnings,
+  }
+}
+
+// The cache identities a configuration can have produced a document under:
+// setup seeds from the newest of them (under `auto` either source may have won).
+export function cacheIdentities(cfg: Config): string[] {
+  const local = localIdentity(cfg.scriptPath)
+  const remote = remoteIdentity(cfg.catalogURL)
+  if (cfg.source === "local") return [local]
+  if (cfg.source === "remote") return [remote]
+  return [local, remote]
+}

package/src/sources/local.ts

@@ -0,0 +1,175 @@
+// src/sources/local.ts
+// The local catalog source (design §9, §11): run the vendored script with
+// execFile — no shell, a timeout, and a minimal environment — then parse and
+// validate whatever it printed. Any failure (missing interpreter, non-zero
+// exit, timeout, invalid JSON, rejected document) rejects as
+// "local source failed: <reason>"; the exit code only refines the message,
+// with stderr informing it (§9).
+
+import { execFile as execFileCallback } from "node:child_process"
+import { promisify } from "node:util"
+import { validateCatalog } from "../core/catalog"
+import type { Sourced } from "../core/types"
+
+const execFile = promisify(execFileCallback)
+
+const STDERR_TAIL_CHARS = 500
+
+// execFile's default maxBuffer is 1 MiB — easily exceeded by a catalog
+// stdout, and the default kill would report it as a generic failure. An
+// explicit, generous cap keeps normal runs safe while bounding memory.
+export const MAX_BUFFER_BYTES = 64 * 1024 * 1024 // 64 MiB
+
+// The version probe prints one line; ten seconds is generous. A hung
+// interpreter (a stuck version-manager shim) must not stall the refresh tick.
+const PROBE_TIMEOUT_MS = 10_000
+
+// Environment variables the script may need beyond HOME and PATH (design
+// §11): its cache location, the AA key, proxy settings in both casings, and
+// custom CA paths. Passed through only when set and non-empty.
+const PASSTHROUGH_ENV = [
+  "XDG_CACHE_HOME",
+  "AA_API_KEY",
+  "HTTP_PROXY",
+  "HTTPS_PROXY",
+  "NO_PROXY",
+  "http_proxy",
+  "https_proxy",
+  "no_proxy",
+  "SSL_CERT_FILE",
+  "SSL_CERT_DIR",
+] as const
+
+// The shape execFile rejects with on failure: `code` is the exit status for a
+// non-zero exit, "ENOENT" when the interpreter is missing, and null when the
+// child was killed by a signal; `stdout`/`stderr` carry what was collected.
+type ExecFileError = Error & {
+  code?: string | number
+  killed?: boolean
+  signal?: NodeJS.Signals | null
+  stdout?: string
+  stderr?: string
+}
+
+// The script's environment (design §11): HOME and PATH from process.env
+// (omitted when absent) plus the passthrough list when set and non-empty.
+// Built fresh — process.env itself is never touched.
+export function scriptEnv(): NodeJS.ProcessEnv {
+  const env: NodeJS.ProcessEnv = {}
+  for (const key of ["HOME", "PATH"] as const) {
+    const value = process.env[key]
+    if (value !== undefined) env[key] = value
+  }
+  for (const key of PASSTHROUGH_ENV) {
+    const value = process.env[key]
+    if (value !== undefined && value !== "") env[key] = value
+  }
+  return env
+}
+
+// The trimmed last chunk of stderr for failure messages; empty stderr
+// contributes nothing to the message.
+function stderrTail(stderr: string | undefined): string {
+  const text = (stderr ?? "").trim()
+  if (text === "") return ""
+  const tail = text.length > STDERR_TAIL_CHARS ? text.slice(-STDERR_TAIL_CHARS) : text
+  return `; stderr: ${tail}`
+}
+
+// Whether the plugin can run the vendored script at all: python3 present and
+// at least 3.10 (design §9). The reason names what failed.
+export async function probePython(
+  timeoutMs = PROBE_TIMEOUT_MS,
+): Promise<{ ok: true } | { ok: false; reason: string }> {
+  let version: string
+  try {
+    const { stdout } = await execFile(
+      "python3",
+      ["-c", "import sys; print('.'.join(map(str, sys.version_info[:2])))"],
+      { timeout: timeoutMs, maxBuffer: MAX_BUFFER_BYTES },
+    )
+    version = stdout.trim()
+  } catch (error) {
+    const err = error as ExecFileError
+    if (err.code === "ENOENT") {
+      return { ok: false, reason: "python3 not found (spawn ENOENT)" }
+    }
+    if (err.code === "ERR_CHILD_PROCESS_STDIO_MAXBUFFER") {
+      return { ok: false, reason: `python3 probe output exceeded the ${MAX_BUFFER_BYTES / (1024 * 1024)} MiB cap` }
+    }
+    if (err.killed && err.signal) {
+      return { ok: false, reason: `python3 probe timed out after ${timeoutMs}ms` }
+    }
+    return { ok: false, reason: `python3 could not be probed: ${err.message}` }
+  }
+
+  const match = /^(\d+)\.(\d+)$/.exec(version)
+  if (match === null) {
+    return {
+      ok: false,
+      reason: `python3 reported unparseable version info: ${JSON.stringify(version)}`,
+    }
+  }
+  const major = Number(match[1])
+  const minor = Number(match[2])
+  if (major < 3 || (major === 3 && minor < 10)) {
+    return { ok: false, reason: `python3 is ${major}.${minor}, need >= 3.10` }
+  }
+  return { ok: true }
+}
+
+// Run the script (an explicit path — resolving the vendored default is the
+// caller's job), validate its stdout, and stamp the plugin's own acquisition
+// time on the document (design §5, §9).
+export async function runLocalScript(
+  scriptPath: string,
+  timeoutMs = 60_000,
+): Promise<Sourced> {
+  let stdout: string
+  try {
+    const result = await execFile("python3", [scriptPath, "--catalog"], {
+      env: scriptEnv(),
+      timeout: timeoutMs,
+      maxBuffer: MAX_BUFFER_BYTES,
+    })
+    stdout = result.stdout
+  } catch (error) {
+    const err = error as ExecFileError
+    const stderr = stderrTail(err.stderr)
+    if (err.code === "ENOENT") {
+      throw new Error(`local source failed: python3 not found (spawn ENOENT)${stderr}`)
+    }
+    // Checked before the signal branch: the maxBuffer kill also sets
+    // killed/signal, but its reason is distinct — the output cap, not the
+    // timeout.
+    if (err.code === "ERR_CHILD_PROCESS_STDIO_MAXBUFFER") {
+      throw new Error(
+        `local source failed: script output exceeded the ${MAX_BUFFER_BYTES / (1024 * 1024)} MiB cap${stderr}`,
+      )
+    }
+    if (err.signal) {
+      const cause = err.killed
+        ? `timed out after ${timeoutMs}ms`
+        : `terminated by ${err.signal}`
+      throw new Error(`local source failed: ${cause} (killed with ${err.signal})${stderr}`)
+    }
+    if (typeof err.code === "number") {
+      throw new Error(`local source failed: exit code ${err.code}${stderr}`)
+    }
+    throw new Error(`local source failed: ${err.message}${stderr}`)
+  }
+
+  let raw: unknown
+  try {
+    raw = JSON.parse(stdout)
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    throw new Error(`local source failed: invalid JSON on stdout (${message})`)
+  }
+
+  const validated = validateCatalog(raw)
+  if (!validated.ok) {
+    throw new Error(`local source failed: invalid catalog document: ${validated.reason}`)
+  }
+  return { doc: validated.catalog, acquiredAt: Date.now() }
+}

package/src/sources/remote.ts

@@ -0,0 +1,155 @@
+// src/sources/remote.ts
+// The remote catalog source (design §5, §8, §9): fetch the published catalog
+// document, validate it, and persist it as a versioned record so the last
+// accepted document survives restarts (§9's offline path). A record younger
+// than the TTL is served without a network round-trip; any fetch or validation
+// failure falls back to the cached record at any age, and fetchRemote only
+// rejects when there is no usable record at all.
+
+import { validateCatalog } from "../core/catalog"
+import type { Sourced } from "../core/types"
+import {
+  readCachedDoc,
+  remoteIdentity,
+  writeCachedDoc,
+  type Storage,
+} from "../opencode/storage"
+
+// The cache is revalidated after six hours (design §8).
+const DEFAULT_TTL_MS = 6 * 60 * 60 * 1000
+
+// A fetch that has not answered by then is aborted (design §4: "HTTPS fetch
+// with timeout"). Without it a dead socket would hold the refresh tick's
+// non-overlap guard forever.
+const DEFAULT_FETCH_TIMEOUT_MS = 30_000
+
+// The body size cap (hostile-input hardening): `catalogURL` is user-pointable
+// and the body is buffered whole for JSON.parse, so a hostile server must not
+// be able to exhaust memory. 16 MiB is far above any sane catalog (the
+// recorded fixture is well under 1 MiB).
+const MAX_BODY_BYTES = 16 * 1024 * 1024 // 16 MiB
+
+// Body-read failures share one taxonomy, the invalid-JSON reason style.
+function bodyTooLargeReason(): string {
+  return `invalid JSON in response (response body exceeds the ${MAX_BODY_BYTES / (1024 * 1024)} MiB cap)`
+}
+
+// Read the body as text, enforcing MAX_BODY_BYTES while reading: the stream
+// is cancelled the moment the cap is crossed, so an endless or oversized body
+// is never buffered further (a lying or absent Content-Length cannot bypass
+// the cap).
+async function readCappedText(
+  response: Response,
+  maxBytes: number,
+): Promise<{ ok: true; text: string } | { ok: false }> {
+  const body = response.body
+  if (body === null) return { ok: true, text: "" }
+  const reader = body.getReader()
+  const chunks: Uint8Array[] = []
+  let total = 0
+  try {
+    for (;;) {
+      const { done, value } = await reader.read()
+      if (done) break
+      if (value === undefined) continue
+      total += value.byteLength
+      if (total > maxBytes) return { ok: false }
+      chunks.push(value)
+    }
+  } finally {
+    // On the overflow path reading stops here — free the connection instead
+    // of leaving the stream (and the socket behind it) half-drained.
+    await reader.cancel().catch(() => {})
+  }
+  const bytes = new Uint8Array(total)
+  let offset = 0
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset)
+    offset += chunk.byteLength
+  }
+  return { ok: true, text: new TextDecoder().decode(bytes) }
+}
+
+// Injectable seams for tests: the network call, the plugin's clock, and the
+// TTL (design §8). All default to their production behavior.
+export type RemoteDeps = {
+  fetch?: typeof fetch
+  now?: () => number
+  ttlMs?: number
+  timeoutMs?: number
+}
+
+// One fetch-and-validate attempt as a result object (the fetch itself, the
+// HTTP status, the body parse, and the document each get their own reason).
+// Network errors surface with their own message; non-OK statuses name the
+// status code.
+async function fetchAndValidate(
+  url: string,
+  doFetch: typeof fetch,
+  now: () => number,
+  timeoutMs: number,
+): Promise<{ ok: true; sourced: Sourced } | { ok: false; reason: string }> {
+  let response: Response
+  try {
+    response = await doFetch(url, { signal: AbortSignal.timeout(timeoutMs) })
+  } catch (error) {
+    return { ok: false, reason: error instanceof Error ? error.message : String(error) }
+  }
+  if (!response.ok) {
+    return { ok: false, reason: `HTTP status ${response.status}` }
+  }
+
+  // Content-Length, when honest and present, fails before a single body byte
+  // is read; readCappedText enforces the same cap for the rest.
+  const declared = response.headers?.get("content-length")
+  if (declared !== null && declared !== undefined && /^\d+$/.test(declared) && Number(declared) > MAX_BODY_BYTES) {
+    await response.body?.cancel().catch(() => {})
+    return { ok: false, reason: bodyTooLargeReason() }
+  }
+
+  let raw: unknown
+  try {
+    const read = await readCappedText(response, MAX_BODY_BYTES)
+    if (!read.ok) return { ok: false, reason: bodyTooLargeReason() }
+    raw = JSON.parse(read.text)
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    return { ok: false, reason: `invalid JSON in response (${message})` }
+  }
+
+  const validated = validateCatalog(raw)
+  if (!validated.ok) {
+    return { ok: false, reason: `invalid catalog document: ${validated.reason}` }
+  }
+  return { ok: true, sourced: { doc: validated.catalog, acquiredAt: now() } }
+}
+
+// Fetch the remote catalog with a persisted six-hour cache (design §5, §8):
+// a fresh record is returned without fetching; otherwise the document is
+// fetched, validated, persisted in the document cache of this URL, and returned with
+// fromCache: false. A fetch or validation failure returns the cached record
+// whatever its age; with no usable record the reason is rejected.
+export async function fetchRemote(
+  url: string,
+  storage: Storage,
+  deps: RemoteDeps = {},
+): Promise<Sourced & { fromCache: boolean }> {
+  const doFetch = deps.fetch ?? globalThis.fetch
+  const now = deps.now ?? Date.now
+  const ttlMs = deps.ttlMs ?? DEFAULT_TTL_MS
+
+  const identity = remoteIdentity(url)
+  const cached = await readCachedDoc(storage, identity)
+  if (cached !== null && now() - cached.acquiredAt < ttlMs) {
+    return { ...cached, fromCache: true }
+  }
+
+  const attempt = await fetchAndValidate(url, doFetch, now, deps.timeoutMs ?? DEFAULT_FETCH_TIMEOUT_MS)
+  if (attempt.ok) {
+    const { doc, acquiredAt } = attempt.sourced
+    await writeCachedDoc(storage, identity, { doc, acquiredAt })
+    return { doc, acquiredAt, fromCache: false }
+  }
+  if (cached !== null) return { ...cached, fromCache: true }
+  throw new Error(`remote source failed: ${attempt.reason}`)
+}