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

package/src/opencode/aliases.ts

@@ -0,0 +1,58 @@
+// src/opencode/aliases.ts
+// Alias plan computation (design §8, §9). The plan is pure data: what alias to
+// point at, what to call it, and whether it can be enabled at all. Copying the
+// concrete model's capabilities/limit/cost/variants/time/status onto the alias
+// is the applier's job (it reads them through editor.get), so this module never
+// touches model internals.
+
+import type { ModelEntry, Priority } from "../core/types"
+import { sanitizeCatalogText } from "./commands"
+
+// The resolved pick for a priority: the winning model's id, or null when
+// resolution found nothing (§9). `fromFallback` marks a pick that came from a
+// curated ranking rather than the scored ordering.
+export type AliasTarget = { id: string | null; fromFallback: boolean }
+
+// What the applier needs to know about one alias.
+export type AliasPlan = {
+  modelID: string | null
+  name: string
+  enabled: boolean
+  warnings: string[]
+}
+
+// §8 rule: a missing pick model DISABLES the alias with a warning — it is never
+// silently skipped. `model` is undefined when the pick's model was removed by
+// another plugin, or when there is no catalog to look it up in.
+export function planAlias(
+  p: Priority,
+  target: AliasTarget,
+  model: ModelEntry | undefined,
+): AliasPlan {
+  if (target.id === null) {
+    return {
+      modelID: null,
+      name: `Model Compare: ${p} (unavailable)`,
+      enabled: false,
+      warnings: [`no pick resolved for ${p}`],
+    }
+  }
+  if (model === undefined) {
+    return {
+      modelID: null,
+      name: `Model Compare: ${p} (unavailable)`,
+      enabled: false,
+      warnings: [`pick model ${target.id} missing from catalog for ${p}`],
+    }
+  }
+  return {
+    modelID: target.id,
+    // The pick in the display name is flattened (F-20): `target.id` is
+    // catalog-derived and the name surfaces in the model picker, the TUI
+    // status line and dialogs. `modelID` stays RAW — switching needs the
+    // real id.
+    name: `Model Compare: ${p} → ${sanitizeCatalogText(target.id)}${target.fromFallback ? " (fallback)" : ""}`,
+    enabled: true,
+    warnings: [],
+  }
+}

package/src/opencode/commands.ts

@@ -0,0 +1,251 @@
+// src/opencode/commands.ts
+// Command logic for /use-best and /model-compare (design §10): parsing the
+// optional priority argument and rendering the ranking report. Pure module —
+// no OpenCode imports, no I/O. The plugin wires the results into
+// ctx.session.switchModel and the synthetic report message.
+//
+// The data age is the plugin's own acquisition time of the document (§5, §9),
+// not upstream's `generated_at`.
+
+import { effectiveWeights, overallScore } from "../core/rank"
+import type { Catalog, ModelEntry, Priority, Sourced, Weights } from "../core/types"
+import type { AliasTarget } from "./aliases"
+
+const PRIORITIES: Priority[] = ["balanced", "price", "quality"]
+const MINUTE = 60_000
+const HOUR = 60 * MINUTE
+const DAY = 24 * HOUR
+const TOP_N = 5
+
+// §10: /use-best's optional argument. Empty (after trimming) means the
+// default priority; a priority name wins case-insensitively; anything else is
+// refused with a message naming the valid priorities.
+export function parseUseBest(
+  text: string,
+  defaultPriority: Priority,
+): { ok: true; priority: Priority } | { ok: false; message: string } {
+  const trimmed = text.trim()
+  if (trimmed === "") return { ok: true, priority: defaultPriority }
+  const match = PRIORITIES.find((p) => p === trimmed.toLowerCase())
+  if (match !== undefined) return { ok: true, priority: match }
+  return {
+    ok: false,
+    message: `model-compare: unknown priority "${trimmed}"; valid priorities: ${PRIORITIES.join(", ")}`,
+  }
+}
+
+// Small humanizer for the report's data age (§10): days/hours/minutes only;
+// anything under a minute (including clock skew) is "just now".
+export function humanizeAge(ageMs: number): string {
+  if (ageMs < MINUTE) return "just now"
+  const days = Math.floor(ageMs / DAY)
+  if (days >= 1) return `${days}d old`
+  const hours = Math.floor(ageMs / HOUR)
+  if (hours >= 1) {
+    const minutes = Math.floor((ageMs % HOUR) / MINUTE)
+    return minutes > 0 ? `${hours}h ${minutes}m old` : `${hours}h old`
+  }
+  return `${Math.floor(ageMs / MINUTE)}m old`
+}
+
+const MAX_TEXT = 120
+
+// Catalog-sourced strings (model ids) end up in a message the model reads
+// (the synthetic report), and `catalogURL` is user-pointable, so they are
+// flattened to a single line first: control characters, newlines and the
+// Unicode line/paragraph separators become spaces, whitespace runs collapse,
+// and the length is capped (F-20). Real OpenRouter ids are unaffected.
+export function sanitizeCatalogText(text: string): string {
+  const flat = text
+    .replace(/[\u0000-\u001f\u007f-\u009f\u2028\u2029]/g, " ")
+    .replace(/\s+/g, " ")
+    .trim()
+  return flat.length > MAX_TEXT ? `${flat.slice(0, MAX_TEXT - 1)}…` : flat
+}
+
+// What the report knows beyond the ranking: the pick each alias currently
+// serves (a pin can differ from rank 1 — minLead hysteresis) and which
+// priorities rank under a weights override.
+export type ReportContext = {
+  picks?: Partial<Record<Priority, AliasTarget>>
+  overrides?: Partial<Record<Priority, Partial<Weights>>>
+}
+
+// Whether a priority's weights override actually took effect, shared by the
+// two report builders (formatReport, reportEntries) so the "(custom weights)"
+// label and the recomputed scores can never disagree: the effective weights
+// are returned only when the override was applied to the merged map (at least
+// one key landed) and the merge was NOT the zero-sum fallback to the
+// published/default weights — in every other case the override changed
+// nothing, so the published scores are shown under the plain header.
+function overrideInEffect(
+  doc: Catalog,
+  p: Priority,
+  override: Partial<Weights> | undefined,
+): Weights | null {
+  if (override === undefined) return null
+  const eff = effectiveWeights(doc, p, override)
+  return eff.applied && !eff.zeroSum ? eff.weights : null
+}
+
+// §10: /model-compare's report. `ranks` arrives already ranked, top-first
+// (under the same overrides, see ReportContext), and only the top 5 per
+// priority are rendered; a ranked id absent from the catalog still takes its
+// line, with "-" instead of a score. An empty models list means no ranking
+// data at all. With an override that actually took effect (overrideInEffect),
+// the section is labelled "(custom weights)" and the shown score is the
+// recomputed one: the published `overall` belongs to upstream's weights, not
+// the user's. An override that applied nothing shows the plain header and the
+// published scores.
+export function formatReport(
+  sourced: Sourced,
+  ranks: Record<Priority, string[]>,
+  context: ReportContext = {},
+): string {
+  if (sourced.doc.models.length === 0) {
+    return "**model-compare** — no ranking data available"
+  }
+  const byId = new Map<string, ModelEntry>()
+  for (const model of sourced.doc.models) byId.set(model.id, model)
+  const lines = [
+    `**model-compare** — top 5 per priority (data age: ${humanizeAge(Date.now() - sourced.acquiredAt)})`,
+  ]
+  for (const p of PRIORITIES) {
+    const weights = overrideInEffect(sourced.doc, p, context.overrides?.[p])
+    const custom = weights !== null
+    const pick = context.picks?.[p]
+    lines.push(custom ? `### ${p} (custom weights)` : `### ${p}`)
+    const top = ranks[p].slice(0, TOP_N)
+    for (const [index, id] of top.entries()) {
+      const model = byId.get(id)
+      const value =
+        model === undefined ? null : weights ? overallScore(model, weights) : model.scores.overall[p]
+      const score = value === null ? "-" : value.toFixed(3)
+      const marker = pick?.id === id ? " ← current pick" : ""
+      lines.push(`${index + 1}. ${sanitizeCatalogText(id)} (${score})${marker}`)
+    }
+    // A pick that is not visible in the list above needs its own line.
+    if (pick !== undefined && (pick.id === null || !top.includes(pick.id))) {
+      if (pick.id === null) {
+        lines.push("Current pick: none (alias disabled)")
+      } else if (pick.fromFallback) {
+        lines.push(`Current pick: ${sanitizeCatalogText(pick.id)} (fallback)`)
+      } else {
+        const rank = ranks[p].indexOf(pick.id)
+        lines.push(
+          `Current pick: ${sanitizeCatalogText(pick.id)} (${rank === -1 ? "not in the ranking" : `rank ${rank + 1}`})`,
+        )
+      }
+    }
+  }
+  return lines.join("\n")
+}
+
+// The report as structured entries: the same ranking, scoring and pick-marker
+// rules as formatReport, in a shape a client can render interactively (the
+// TUI's selectable report dialog — one entry per listed model, selecting it
+// switches straight to that model). The pick formatReport renders as its
+// extra "Current pick:" line gets its own entry here: `rank` is that pick's
+// 1-based position in the full ranking (formatReport's "rank N"), or null
+// only when the pick is absent from ranks[p] (formatReport's "not in the
+// ranking"); its `score` stays "-" because formatReport's Current pick line
+// shows the rank, not a score. `score` otherwise keeps formatReport's "-" for
+// an id missing from the catalog; `fromFallback` marks a pick the fallback is
+// serving. F-20 id split: `id` is the DISPLAY id (sanitized like
+// formatReport's lines) while `value` is the RAW catalog id — the one
+// switchToModel needs — so a dialog row shows `id` but picks `value`.
+// `quality` is upstream's quality index (one decimal, "-" when absent) and
+// `price` the effective-tier input/output per 1M pair ("Free" for a 0/0
+// model, "-" when either half is unknown).
+export type ReportEntry = {
+  priority: Priority
+  rank: number | null
+  id: string
+  value: string
+  score: string
+  quality: string
+  price: string
+  current: boolean
+  fromFallback: boolean
+}
+
+// Quality index → one decimal ("37.9", "56.0"); absent → "-".
+function fmtQuality(model: ModelEntry | undefined): string {
+  if (model === undefined || model.quality === null) return "-"
+  return model.quality.toFixed(1)
+}
+
+// Effective-tier input/output per 1M: both explicitly zero → "Free" (the
+// Switch-model dialog's convention); either half unknown → "-" (a half pair
+// is never invented from `?? 0`); else "0.14/0.28".
+function fmtPrice(model: ModelEntry | undefined): string {
+  if (model === undefined) return "-"
+  const input = model.pricing.input_per_1m
+  const output = model.pricing.output_per_1m
+  if (input === undefined || output === undefined) return "-"
+  if (input === 0 && output === 0) return "Free"
+  return `${input.toFixed(2)}/${output.toFixed(2)}`
+}
+
+export function reportEntries(
+  sourced: Sourced,
+  ranks: Record<Priority, string[]>,
+  context: ReportContext = {},
+): ReportEntry[] {
+  // The same empty-catalog guard as formatReport: the RPC's text and its
+  // entries must agree on "no ranking data", so no models means no entries —
+  // the client renders its own no-data notice beside the text's no-data line.
+  if (sourced.doc.models.length === 0) return []
+  const byId = new Map<string, ModelEntry>()
+  for (const model of sourced.doc.models) byId.set(model.id, model)
+  const entries: ReportEntry[] = []
+  for (const p of PRIORITIES) {
+    const weights = overrideInEffect(sourced.doc, p, context.overrides?.[p])
+    const pick = context.picks?.[p]
+    const top = ranks[p].slice(0, TOP_N)
+    for (const [index, id] of top.entries()) {
+      const model = byId.get(id)
+      const scoreValue =
+        model === undefined ? null : weights ? overallScore(model, weights) : model.scores.overall[p]
+      const current = pick?.id === id
+      entries.push({
+        priority: p,
+        rank: index + 1,
+        // F-20: `id` is the sanitized DISPLAY id (dialog rows, toasts);
+        // `value` keeps the raw catalog id so switchToModel still receives
+        // the real model id.
+        id: sanitizeCatalogText(id),
+        value: id,
+        score: scoreValue === null ? "-" : scoreValue.toFixed(3),
+        quality: fmtQuality(model),
+        price: fmtPrice(model),
+        current,
+        // A top-5 row that IS the current pick carries the pick's fallback
+        // marker like the outside-top-5 entry below (formatReport's
+        // "(fallback)" suffix on its Current pick line).
+        fromFallback: current && pick?.fromFallback === true,
+      })
+    }
+    // The pick outside the top 5 gets its own entry, with its rank from the
+    // full ranking exactly like formatReport's extra "Current pick:" line
+    // (rank N when the pick is ranked at all, null = "not in the ranking");
+    // its score is "-" there — formatReport shows the rank, not a score. A
+    // disabled alias's "none" pick has nothing to select, so it is skipped.
+    if (pick !== undefined && pick.id !== null && !top.includes(pick.id)) {
+      const model = byId.get(pick.id)
+      const rank = ranks[p].indexOf(pick.id)
+      entries.push({
+        priority: p,
+        rank: rank === -1 ? null : rank + 1,
+        id: sanitizeCatalogText(pick.id),
+        value: pick.id,
+        score: "-",
+        quality: fmtQuality(model),
+        price: fmtPrice(model),
+        current: true,
+        fromFallback: pick.fromFallback,
+      })
+    }
+  }
+  return entries
+}

package/src/opencode/guard.ts

@@ -0,0 +1,44 @@
+// src/opencode/guard.ts
+// The primary-kind guard (design §9). Pure decision logic: given the request
+// kind, the requesting agent's configured model ref, and whether each alias is
+// enabled, decide whether the request must abort. It never touches OpenCode —
+// the hook (Task 12) supplies the inputs and acts on the decision.
+//
+// Known trade-off (§9, §15): in headless runs the guard can fire even though
+// the root-governed effective model is healthy, because it keys on the agent's
+// configured ref. This is accepted, not a bug.
+
+import type { Priority } from "../core/types"
+
+// A model reference as configured on an agent (`agent.model`).
+export type ModelRef = { providerID: string; id: string }
+
+const ALIAS_PREFIX = "model-compare/"
+
+const PRIORITIES: readonly Priority[] = ["balanced", "price", "quality"]
+
+// The priority an alias ref points at, or null when the ref is not one of our
+// aliases. Matches ONLY openrouter + `model-compare/<p>` where the remainder
+// after the prefix IS a priority name — ids may carry more slashes in
+// OpenRouter's vendor/model style, so anything after the priority disqualifies.
+export function parseAliasRef(ref: ModelRef | undefined): Priority | null {
+  if (ref === undefined || ref.providerID !== "openrouter") return null
+  if (!ref.id.startsWith(ALIAS_PREFIX)) return null
+  const remainder = ref.id.slice(ALIAS_PREFIX.length)
+  return PRIORITIES.includes(remainder as Priority) ? (remainder as Priority) : null
+}
+
+// Abort only a primary request whose agent is configured with a DISABLED
+// alias. Everything else — non-primary kinds, enabled aliases, real model
+// refs, missing refs — passes with no error.
+export function guardDecision(
+  kind: string,
+  agentModel: ModelRef | undefined,
+  isEnabled: (p: Priority) => boolean,
+): { error?: string } {
+  const p = parseAliasRef(agentModel)
+  if (kind !== "primary" || p === null || isEnabled(p)) return {}
+  return {
+    error: `model-compare: no ranking data for openrouter/model-compare/${p}; set options.fallback or check the data source`,
+  }
+}

package/src/opencode/refresh.ts

@@ -0,0 +1,188 @@
+// src/opencode/refresh.ts
+// The 30-minute refresh tick (design §8, §9). One pass:
+//   1. acquire fresh data; on failure keep going WITHOUT a catalog, so §9's
+//      chain (stored pin if runnable → fallback if runnable → none) is
+//      re-evaluated against what OpenRouter lists right now;
+//   2. compute the next picks as a pure plan (resolution.ts) — nothing is
+//      mutated yet;
+//   3. persist pin records and the doc cache; a storage failure aborts the
+//      pass with the state untouched, so the next pass redoes it;
+//   4. publish the plan to the alias transform, replay it via the
+//      spike-verified provider→model→agent reloads, and only THEN mark it as
+//      applied. A reload that throws leaves the applied view (what the guard
+//      and /use-best read) on the old picks, so the next tick sees a
+//      difference and retries the reload.
+// The tick never overlaps itself, is bounded by a hard deadline, and its
+// errors are logged, never thrown: the timer must not die.
+
+import type { Config } from "../config"
+import type { Priority } from "../core/types"
+import { writeCachedDoc, writeRecord } from "./storage"
+import { PRIORITIES, planPicks, type PickPlan } from "./resolution"
+import type { Acquired, acquire } from "../sources"
+import type { PluginCtx, WireState } from "../index"
+
+const ALIAS_PROVIDER = "openrouter"
+export const REFRESH_MS = 1_800_000 // 30 minutes (design §8)
+// Hard ceiling for one whole tick (F-01). It must outlast the legitimate worst
+// case: the probe (10 s) + the script (60 s) + the provider→model→agent reload
+// chain, which the integration harness measured at 90-105 s. Past it the tick
+// is abandoned and the non-overlap guard is released.
+export const TICK_DEADLINE_MS = 180_000
+
+// The ids OpenRouter currently lists as enabled models — the runnable set
+// resolution checks candidates against (§7.1). Also used at setup to decide
+// which stored pins may enable their alias and whether the configured
+// fallback is runnable.
+export async function runnableSet(ctx: PluginCtx): Promise<Set<string>> {
+  const listed = await ctx.model.list()
+  const set = new Set<string>()
+  for (const model of listed.data) {
+    if (model.providerID === ALIAS_PROVIDER && model.enabled !== false) set.add(model.id)
+  }
+  return set
+}
+
+// One warning per refresh when any alias is disabled (§9): sessions on it —
+// root default or /use-best — fall back to OpenCode's own choice silently.
+export function warnDisabledAliases(
+  enabled: Partial<Record<Priority, boolean>>,
+  when: string,
+): void {
+  const disabled = PRIORITIES.filter((p) => enabled[p] !== true)
+  if (disabled.length === 0) return
+  console.warn(
+    "[model-compare]",
+    `${when}: aliases disabled (sessions on them fall back to OpenCode's own choice): ${disabled
+      .map((p) => `${ALIAS_PROVIDER}/model-compare/${p}`)
+      .join(", ")}`,
+  )
+}
+
+// Publishes a plan as both the desired registry state (read by the alias
+// transform) and — at setup, where registration applies it immediately — the
+// applied view.
+export function adoptPlan(state: WireState, plan: PickPlan, applied: boolean): void {
+  state.plan = { picks: { ...plan.picks }, enabled: { ...plan.enabled } }
+  state.pins = { ...plan.pins }
+  if (applied) commitApplied(state, plan)
+}
+
+// The registry now serves `plan`: the applied view follows, except for aliases
+// the transform found it could not enable (concrete model gone from the
+// editor) — those stay disabled for the guard and /use-best.
+export function commitApplied(state: WireState, plan: PickPlan): void {
+  state.picks = { ...plan.picks }
+  state.enabled = { ...plan.enabled }
+  for (const p of PRIORITIES) if (state.registryDisabled[p]) state.enabled[p] = false
+}
+
+// Does the plan differ from what the registry last applied? An alias the
+// transform disabled by itself still counts as "applied as enabled": the plan
+// wanted it and the registry did what it could.
+function differsFromApplied(state: WireState, plan: PickPlan): boolean {
+  return PRIORITIES.some((p) => {
+    const previous = state.picks[p]
+    const appliedEnabled = state.enabled[p] === true || state.registryDisabled[p] === true
+    return (
+      (previous?.id ?? null) !== plan.picks[p].id ||
+      (previous?.fromFallback ?? false) !== plan.picks[p].fromFallback ||
+      appliedEnabled !== plan.enabled[p]
+    )
+  })
+}
+
+// Builds the tick. The refreshing flag lives in this closure so consecutive
+// invocations never overlap (§8); the caller only schedules and cancels it.
+export function createTick(
+  ctx: PluginCtx,
+  config: Config,
+  state: WireState,
+  deps: { acquire: typeof acquire; now: () => number; deadlineMs?: number },
+): () => Promise<void> {
+  let refreshing = false
+  return async () => {
+    if (refreshing) return
+    refreshing = true
+    // An abandoned body (deadline hit) must not touch state if it ever wakes.
+    const run = { abandoned: false }
+    const deadlineMs = deps.deadlineMs ?? TICK_DEADLINE_MS
+    let timer: ReturnType<typeof setTimeout> | undefined
+    const deadline = new Promise<never>((_resolve, reject) => {
+      timer = setTimeout(() => {
+        run.abandoned = true
+        reject(new Error(`refresh exceeded its ${deadlineMs}ms deadline; abandoning it`))
+      }, deadlineMs)
+    })
+    try {
+      await Promise.race([body(run), deadline])
+    } catch (error) {
+      console.error("[model-compare]", error)
+    } finally {
+      clearTimeout(timer)
+      refreshing = false
+    }
+  }
+
+  async function body(run: { abandoned: boolean }): Promise<void> {
+    let result: Acquired | null = null
+    try {
+      result = await deps.acquire(config, { storage: ctx.storage })
+      if (!result) throw new Error("the source returned no document")
+    } catch (error) {
+      // §9: no fresh catalog is not the end of the pass — fall through and
+      // re-resolve pin → fallback → none against the current runnable set.
+      result = null
+      console.error("[model-compare]", error)
+    }
+    if (run.abandoned) return
+    if (result) for (const warning of result.warnings) console.warn("[model-compare]", warning)
+
+    const runnable = await runnableSet(ctx)
+    const next = planPicks({
+      config,
+      doc: result?.sourced.doc ?? null,
+      runnable,
+      pins: state.pins,
+      now: deps.now(),
+    })
+    for (const notice of next.notices) console.warn("[model-compare]", notice)
+
+    // Persist before anything is published: a storage failure throws here,
+    // with the state untouched, and the next tick simply redoes the pass.
+    // The deadline may have fired while the runnable set was fetched: an
+    // abandoned tick must not touch storage either (F-01 semantics —
+    // abandoned means neither state nor storage is touched).
+    if (run.abandoned) return
+    if (result) {
+      for (const { key, pin } of next.writes) await writeRecord(ctx.storage, key, pin)
+      await writeCachedDoc(ctx.storage, result.identity, result.sourced)
+    }
+    if (run.abandoned) return
+
+    const changed = differsFromApplied(state, next)
+    if (result) state.sourced = result.sourced
+    adoptPlan(state, next, false)
+    warnDisabledAliases(next.enabled, "refresh")
+    if (changed) {
+      // The spike-verified replay order (§8, §15 item 1): provider first,
+      // then model, then agent. A throw leaves the applied view stale on
+      // purpose: the next tick's comparison fails again and retries.
+      await ctx.provider.reload()
+      await ctx.model.reload()
+      await ctx.agent.reload()
+    }
+    // The reload chain is slow (measured 90-105 s) — the deadline can fire
+    // in the middle of it. An abandoned tick must not commit its plan as
+    // applied: the applied view (the guard, /use-best) stays on the old
+    // picks, and the next tick's comparison retries the reload.
+    if (run.abandoned) return
+    commitApplied(state, next)
+    console.warn(
+      "[model-compare]",
+      result
+        ? `refresh complete: source=${result.source} fromCache=${result.fromCache} changed=${changed}`
+        : `refresh failed; resolved without a fresh catalog: changed=${changed}`,
+    )
+  }
+}

package/src/opencode/resolution.ts

@@ -0,0 +1,69 @@
+// src/opencode/resolution.ts
+// One resolution pass over all three priorities (design §7, §9), shared by
+// setup and the refresh tick so the two can never disagree about the chain:
+//   fresh catalog  → §7.4 rules (rank, pin hysteresis, expiry) then §9 chain
+//   no catalog     → stored pin (if runnable) → fallback (if runnable) → none
+// The result is a pure plan: nothing is applied or persisted here.
+
+import type { Config } from "../config"
+import { pinKey, resolve, type Pin } from "../core/pins"
+import { effectiveWeights } from "../core/rank"
+import type { Catalog, Priority } from "../core/types"
+import type { AliasTarget } from "./aliases"
+
+export const PRIORITIES: readonly Priority[] = ["balanced", "price", "quality"]
+
+export type PickPlan = {
+  picks: Record<Priority, AliasTarget>
+  enabled: Record<Priority, boolean>
+  // The pin state after this pass (a pass without a catalog never changes it).
+  pins: Partial<Record<Priority, Pin>>
+  // Pin records to persist: only produced when a fresh catalog is available.
+  writes: Array<{ key: string; pin: Pin }>
+  notices: string[]
+}
+
+export function planPicks(input: {
+  config: Config
+  // null = no fresh catalog (cold start, offline start, failed refresh).
+  doc: Catalog | null
+  runnable: ReadonlySet<string>
+  pins: Partial<Record<Priority, Pin>>
+  now: number
+}): PickPlan {
+  const { config, doc, runnable, pins, now } = input
+  const plan: PickPlan = {
+    picks: {} as Record<Priority, AliasTarget>,
+    enabled: {} as Record<Priority, boolean>,
+    pins: { ...pins },
+    writes: [],
+    notices: [],
+  }
+  for (const p of PRIORITIES) {
+    const resolved = resolve({
+      catalog: doc,
+      p,
+      override: config.weights[p],
+      runnable: (id) => runnable.has(id),
+      fallback: config.fallback,
+      stored: pins[p] ?? null,
+      now,
+      pinDays: config.pinDays,
+      minLead: config.minLead,
+    })
+    if (resolved.pin === null) delete plan.pins[p]
+    else plan.pins[p] = resolved.pin
+    plan.picks[p] =
+      resolved.targetId === null
+        ? { id: null, fromFallback: false }
+        : { id: resolved.targetId, fromFallback: resolved.source === "fallback" }
+    plan.enabled[p] = resolved.targetId !== null
+    if (doc !== null && resolved.pin !== null) {
+      // The effective-weights hash keys the record (§7.2).
+      const key = pinKey(p, effectiveWeights(doc, p, config.weights[p]).weights)
+      plan.writes.push({ key, pin: resolved.pin })
+    }
+    plan.notices.push(...resolved.notices)
+  }
+  return plan
+}