@geraldmaron/construct 1.5.0 → 1.5.2

package/lib/model-policy.mjs

@@ -0,0 +1,329 @@
+/**
+ * lib/model-policy.mjs — user-facing model policy: presets, the effective-policy
+ * view, and per-specialist resolution traces, layered on the existing resolution
+ * chain (lib/model-router.mjs + lib/embedded-contract/model-resolve.mjs).
+ *
+ * Design constraint (construct-760c.7): the single edit surface for model
+ * assignment is specialists/org/models.json. config.schema is deliberately not a
+ * second surface. Presets are COMPUTED here from the cost/free selectors
+ * (model-cheapest-provider / model-free-selector / model-pricing) and then
+ * PERSISTED to models.json, which already sits below env pins in the chain — so
+ * CX_MODEL_<TIER> pins keep overriding and nothing new enters the chain.
+ *
+ * Budget invariant: computeBudgetTiers never treats a missing price as $0. An
+ * unknown or unreachable price ranks a candidate LAST, and flagship ids are
+ * hard-excluded — so with only an OpenRouter credential no frontier model can be
+ * selected for any tier, even when live pricing is unreachable.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import {
+  defaultModelRegistryPath,
+  getProviderModelCatalog,
+  resolveModelTiers,
+  MODEL_TIER_BY_WORK_CATEGORY,
+} from './model-router.mjs';
+import { getPricingForModels } from './model-pricing.mjs';
+import { pollFreeModels, selectForTier, isFreeModel } from './model-free-selector.mjs';
+import { getSpecialist } from './registry/loader.mjs';
+import { MODEL_TIERS } from './model-tiers.mjs';
+
+export const POLICY_PRESETS = ['budget', 'free', 'frontier', 'local'];
+export const POLICY_TIERS = MODEL_TIERS;
+
+// Flagship, high-cost models a budget/free policy must never resolve to. The set
+// mirrors the reasoning/standard flagships declared in PROVIDER_FAMILY_TIERS so a
+// preset can hard-exclude them regardless of whether live pricing was reachable;
+// the regex catches the same families' newer point releases.
+
+const FRONTIER_MODEL_IDS = new Set([
+  'anthropic/claude-opus-4-6',
+  'anthropic/claude-sonnet-4-6',
+  'openrouter/anthropic/claude-opus-4-6',
+  'openrouter/anthropic/claude-sonnet-4-6',
+  'openai/gpt-5.4',
+  'openai/gpt-5.1',
+  'openrouter/openai/gpt-5.4',
+  'openrouter/openai/gpt-5.1',
+  'openrouter/google/gemini-2.5-pro',
+  'openrouter/meta-llama/llama-3.1-405b-instruct',
+  'github-copilot/gpt-5.5',
+  'github-copilot/gpt-5.4',
+]);
+
+const FRONTIER_PATTERN = /(claude-opus|claude-sonnet|gpt-5\.(4|5)|gemini-2\.5-pro|llama-3\.1-405b|405b-instruct)/i;
+
+export function isFrontierModel(modelId) {
+  if (!modelId || typeof modelId !== 'string') return false;
+  if (isFreeModel(modelId)) return false;
+  return FRONTIER_MODEL_IDS.has(modelId) || FRONTIER_PATTERN.test(modelId);
+}
+
+function uniq(values) {
+  return [...new Set(values.filter((v) => typeof v === 'string' && v.trim()))];
+}
+
+function configuredProviders(env) {
+  const catalog = getProviderModelCatalog({ env });
+  return catalog.providers.filter((p) => p.configured);
+}
+
+function tierDefinition(primary, fallback = []) {
+  return { primary, fallback: uniq(fallback.filter((id) => id !== primary)) };
+}
+
+// Candidate models for a tier from every configured provider: the tier pin plus
+// the shipped option list. Frontier ids are dropped so a budget/free preset can
+// never rank one, whatever the pricing outcome.
+
+function budgetCandidates(providers, tier) {
+  const ids = [];
+  const local = new Set();
+  for (const p of providers) {
+    const list = uniq([p.tiers?.[tier], ...(p.options?.[tier] ?? [])]);
+    for (const id of list) {
+      ids.push(id);
+      if (p.local === true) local.add(id);
+    }
+  }
+  return { ids: uniq(ids).filter((id) => !isFrontierModel(id)), local };
+}
+
+/**
+ * Compute the budget tier assignments: the cheapest eligible model per tier from
+ * configured providers. Unknown/unreachable prices rank LAST (never $0), so the
+ * budget invariant holds even when the pricing fetch fails.
+ */
+export async function computeBudgetTiers({ env = process.env, getPricing = getPricingForModels } = {}) {
+  const providers = configuredProviders(env);
+  const warnings = [];
+  const models = {};
+  let pricingDegraded = false;
+
+  for (const tier of POLICY_TIERS) {
+    const { ids, local } = budgetCandidates(providers, tier);
+    if (ids.length === 0) {
+      models[tier] = tierDefinition(null, []);
+      continue;
+    }
+
+    let pricing = {};
+    try {
+      pricing = await getPricing(ids);
+    } catch {
+      pricing = {};
+    }
+
+    const scored = ids.map((id) => {
+      if (local.has(id)) return { id, cost: 0, priced: true };
+      const entry = pricing[id];
+      if (entry && Number.isFinite(Number(entry.input)) && Number.isFinite(Number(entry.output))) {
+        return { id, cost: Number(entry.input) + Number(entry.output), priced: true };
+      }
+      return { id, cost: Number.POSITIVE_INFINITY, priced: false };
+    });
+
+    const priced = scored.filter((s) => s.priced);
+    if (priced.length === 0) {
+      // No candidate had a reachable price. Fall back to a deterministic static
+      // ordering — a :free slug first, else the first non-frontier candidate —
+      // and say so rather than silently ranking on missing data.
+      pricingDegraded = true;
+      const free = ids.find((id) => isFreeModel(id));
+      const primary = free ?? ids[0];
+      models[tier] = tierDefinition(primary, ids.filter((id) => id !== primary).slice(0, 2));
+      continue;
+    }
+
+    scored.sort((a, b) => a.cost - b.cost);
+    const primary = scored[0].id;
+    const fallback = scored.slice(1).filter((s) => Number.isFinite(s.cost)).map((s) => s.id).slice(0, 2);
+    models[tier] = tierDefinition(primary, fallback);
+  }
+
+  if (pricingDegraded) {
+    warnings.push('Live pricing was unreachable for at least one tier; used static ordering (a :free slug, else the first eligible candidate).');
+  }
+  return { models, warnings };
+}
+
+/**
+ * Compute the free tier assignments: :free OpenRouter slugs only. A tier with no
+ * available free model is left null and reported, never silently substituted.
+ */
+export async function computeFreeTiers({ env = process.env, apiKey = null, poll = pollFreeModels } = {}) {
+  const warnings = [];
+  const models = {};
+  const key = apiKey || env.OPENROUTER_API_KEY || env.OPEN_ROUTER_API_KEY || null;
+  const freeModels = key ? await poll(key) : [];
+
+  for (const tier of POLICY_TIERS) {
+    const id = selectForTier(freeModels, tier, []);
+    if (id && isFreeModel(id)) {
+      models[tier] = tierDefinition(id, []);
+    } else {
+      models[tier] = tierDefinition(null, []);
+      warnings.push(`No free model available for the ${tier} tier; left unset (run \`construct models free\` to inspect the live catalog).`);
+    }
+  }
+  return { models, warnings };
+}
+
+// Best-available (flagship) per tier from configured providers, ranked by a fixed
+// capability order. This is the deliberately-expensive preset, so frontier ids are
+// not excluded here.
+
+const FRONTIER_PROVIDER_ORDER = [
+  'anthropic',
+  'openai',
+  'openrouter-anthropic',
+  'openrouter-openai',
+  'github-copilot',
+  'openrouter-google',
+  'openrouter-deepseek',
+  'openrouter-llama',
+  'openrouter-qwen',
+  'openrouter',
+];
+
+export function computeFrontierTiers({ env = process.env } = {}) {
+  const providers = configuredProviders(env);
+  const ranked = [...providers].sort((a, b) => {
+    const ia = FRONTIER_PROVIDER_ORDER.indexOf(a.id);
+    const ib = FRONTIER_PROVIDER_ORDER.indexOf(b.id);
+    return (ia === -1 ? 99 : ia) - (ib === -1 ? 99 : ib);
+  });
+  const models = {};
+  for (const tier of POLICY_TIERS) {
+    const provider = ranked.find((p) => p.tiers?.[tier]);
+    const primary = provider?.tiers?.[tier] ?? null;
+    const fallback = ranked.filter((p) => p !== provider).map((p) => p.tiers?.[tier]).filter(Boolean);
+    models[tier] = tierDefinition(primary, fallback.slice(0, 2));
+  }
+  return { models, warnings: [] };
+}
+
+export function computeLocalTiers({ env = process.env } = {}) {
+  const providers = configuredProviders(env).filter((p) => p.local === true);
+  const models = {};
+  for (const tier of POLICY_TIERS) {
+    const provider = providers.find((p) => p.tiers?.[tier]);
+    const primary = provider?.tiers?.[tier] ?? null;
+    const fallback = providers.filter((p) => p !== provider).map((p) => p.tiers?.[tier]).filter(Boolean);
+    models[tier] = tierDefinition(primary, fallback.slice(0, 2));
+  }
+  return { models, warnings: [] };
+}
+
+/**
+ * Compute a preset's per-tier assignments. Refuses (ok:false) with a clear
+ * message when no provider credential can back the preset, so a preset never
+ * silently writes an unbacked frontier default.
+ */
+export async function computePolicyPreset(preset, { env = process.env, apiKey = null, getPricing, poll } = {}) {
+  if (!POLICY_PRESETS.includes(preset)) {
+    return { ok: false, refusal: `Unknown preset '${preset}'. Choose one of: ${POLICY_PRESETS.join(', ')}.` };
+  }
+
+  const providers = configuredProviders(env);
+  const localProviders = providers.filter((p) => p.local === true);
+  const hasOpenRouter = Boolean(env.OPENROUTER_API_KEY || env.OPEN_ROUTER_API_KEY);
+
+  if (preset === 'free' && !hasOpenRouter) {
+    return { ok: false, refusal: 'The `free` preset needs an OpenRouter credential (OPENROUTER_API_KEY). Set one, then rerun.' };
+  }
+  if (preset === 'local' && localProviders.length === 0) {
+    return { ok: false, refusal: 'The `local` preset needs a local provider (Ollama or a local OpenAI-compatible server). Start one, then rerun.' };
+  }
+  if ((preset === 'budget' || preset === 'frontier') && providers.length === 0) {
+    return { ok: false, refusal: `The \`${preset}\` preset needs at least one configured provider credential. Set an API key (e.g. OPENROUTER_API_KEY / ANTHROPIC_API_KEY), then rerun.` };
+  }
+
+  let result;
+  if (preset === 'budget') result = await computeBudgetTiers({ env, ...(getPricing ? { getPricing } : {}) });
+  else if (preset === 'free') result = await computeFreeTiers({ env, apiKey, ...(poll ? { poll } : {}) });
+  else if (preset === 'frontier') result = computeFrontierTiers({ env });
+  else result = computeLocalTiers({ env });
+
+  const anyResolved = POLICY_TIERS.some((tier) => result.models[tier]?.primary);
+  if (!anyResolved) {
+    return { ok: false, refusal: `No model could be computed for the \`${preset}\` preset with the current credentials.`, warnings: result.warnings };
+  }
+
+  return { ok: true, preset, models: result.models, warnings: result.warnings ?? [] };
+}
+
+/**
+ * Persist computed tier assignments to the models.json registry — the single
+ * edit surface. Writes only `models`; env pins keep overriding at resolution.
+ */
+export function writeModelRegistry(registryPath, models, { preset = null } = {}) {
+  const payload = {
+    _comment: `Written by \`construct models policy set${preset ? ` ${preset}` : ''}\` (construct-760c.7). Tier defaults below fill only tiers no CX_MODEL_<TIER> env pin sets; env pins always win. Edit via \`construct models policy set <preset>\` or \`construct models set\`.`,
+    models: {},
+  };
+  for (const tier of POLICY_TIERS) {
+    const def = models[tier];
+    if (def?.primary) payload.models[tier] = { primary: def.primary, fallback: def.fallback ?? [] };
+  }
+  fs.mkdirSync(path.dirname(registryPath), { recursive: true });
+  fs.writeFileSync(registryPath, `${JSON.stringify(payload, null, 2)}\n`);
+  return payload;
+}
+
+/**
+ * Effective-policy view: per-tier resolved model and the winning source, plus the
+ * work-category → tier map. Reads through resolveModelTiers so an env pin is
+ * attributed as the winning source over a registry default.
+ */
+export function readPolicyView({ env = process.env, registryPath = null } = {}) {
+  const resolvedRegistryPath = registryPath ?? defaultModelRegistryPath(env);
+  const resolution = resolveModelTiers({ env, registryPath: resolvedRegistryPath });
+  const tiers = POLICY_TIERS.map((tier) => ({
+    tier,
+    model: resolution.models[tier],
+    source: resolution.sources[tier],
+    envPin: env[`CX_MODEL_${tier.toUpperCase()}`] || env[`CONSTRUCT_MODEL_${tier.toUpperCase()}`] || null,
+  }));
+  return {
+    registryPath: resolvedRegistryPath,
+    tiers,
+    workCategoryMap: { ...MODEL_TIER_BY_WORK_CATEGORY },
+    configured: resolution.configured,
+    complete: resolution.complete,
+  };
+}
+
+/**
+ * Per-specialist resolution trace: the specialist's declared modelTier/model, the
+ * tier it maps to, and the winning rule for that tier. Mirrors what
+ * `construct models resolve --json --tier <tier>` reports for the same tier.
+ */
+export function explainRole(roleId, { env = process.env, registryPath = null, rootDir = null } = {}) {
+  const specialist = getSpecialist(roleId, rootDir ? { rootDir } : {});
+  if (!specialist) {
+    return { ok: false, error: `Unknown specialist '${roleId}'.` };
+  }
+
+  const declaredModel = specialist.model || null;
+  const declaredTier = specialist.modelTier || null;
+  const tier = declaredTier || 'standard';
+
+  const resolvedRegistryPath = registryPath ?? defaultModelRegistryPath(env);
+  const resolution = resolveModelTiers({ env, registryPath: resolvedRegistryPath });
+
+  const resolvedModel = declaredModel || resolution.models[tier];
+  const source = declaredModel ? 'specialist model pin' : resolution.sources[tier];
+
+  return {
+    ok: true,
+    role: specialist.name ? `cx-${specialist.name}` : roleId,
+    declaredModel,
+    declaredTier,
+    tier,
+    resolvedModel,
+    source,
+    registryPath: resolvedRegistryPath,
+  };
+}

package/lib/model-router.mjs

@@ -26,6 +26,7 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { spawnSync } from "child_process";
 import { hasAnySecret } from "./providers/secret-resolver.mjs";
+import { MODEL_TIERS } from "./model-tiers.mjs";
 import { isOllamaModelInstalled, toOllamaNativeModelId } from "./ollama/installed-models.mjs";
 import { readRawFromOpenCodeProvider } from "./providers/credential-sources.mjs";
 import { findOpenCodeConfigPath } from "./opencode-config.mjs";
@@ -535,9 +536,9 @@ export function getPickerModelAllowlist({
     if (!providerFamilyEnabled(family.id, vis)) continue;
 
     const tiers = family.resolve({});
-    const pins = uniqueStrings(['reasoning', 'standard', 'fast'].map((tier) => tiers[tier]));
+    const pins = uniqueStrings(MODEL_TIERS.map((tier) => tiers[tier]));
     const shipped = uniqueStrings(
-      ['reasoning', 'standard', 'fast'].flatMap((tier) => family.options?.[tier] || []),
+      MODEL_TIERS.flatMap((tier) => family.options?.[tier] || []),
     );
 
     if (vis.mode === 'explicit') {
@@ -675,7 +676,7 @@ export function listAvailableModels({ env = process.env, cwd = process.cwd(), ac
   const models = [];
   const seen = new Set();
   for (const provider of providers) {
-    for (const tier of ['reasoning', 'standard', 'fast']) {
+    for (const tier of MODEL_TIERS) {
       for (const id of provider.options?.[tier] || []) {
         if (seen.has(id)) continue;
         seen.add(id);
@@ -1135,7 +1136,7 @@ function resolveTierAssignments(envValues = {}, registryModels = {}) {
   const defaults = getRegistryDefaults(registryModels);
   const tiers = {};
 
-  for (const tier of ["reasoning", "standard", "fast"]) {
+  for (const tier of MODEL_TIERS) {
     if (explicitSources[tier]) {
       tiers[tier] = { model: normalizedEnv[tier] ?? defaults[tier], source: explicitSources[tier] };
     } else if (normalizedEnv[tier]) {
@@ -1224,7 +1225,7 @@ export function applyFreeSameFamilyPreferenceToTierSet(tierSet, selectedModel) {
 
   const sameFamily = family.resolve({ reasoning: null, standard: null, fast: null });
   const next = { ...tierSet };
-  for (const tier of ["reasoning", "standard", "fast"]) {
+  for (const tier of MODEL_TIERS) {
     if (tierSet[tier] === selectedModel) continue;
     const candidate = sameFamily[tier];
     if (candidate && isFreeModel(candidate)) next[tier] = candidate;
@@ -1341,13 +1342,13 @@ export function resolveModelTiers(options = {}) {
   const tiers = resolveTierAssignments(normalizeEnvAssignments(env), registryModels);
   const models = {};
   const sources = {};
-  for (const tier of ['reasoning', 'standard', 'fast']) {
+  for (const tier of MODEL_TIERS) {
     models[tier] = tiers[tier].model;
     sources[tier] = tiers[tier].source;
   }
   const configured = Object.values(models).filter(Boolean).length;
   const errors = strict && configured < 3
-    ? [`Missing configuration for tiers: ${['reasoning', 'standard', 'fast'].filter((t) => !models[t]).join(', ')}`]
+    ? [`Missing configuration for tiers: ${MODEL_TIERS.filter((t) => !models[t]).join(', ')}`]
     : null;
 
   return {
@@ -1386,7 +1387,7 @@ export function validateModelTiers(options = {}) {
 export function formatModelStatus(options = {}) {
   const resolved = resolveModelTiers(options);
   let output = 'Model Configuration:\n\n';
-  for (const tier of ['reasoning', 'standard', 'fast']) {
+  for (const tier of MODEL_TIERS) {
     const model = resolved.models[tier];
     const source = resolved.sources[tier];
     const icon = source === 'not configured' ? '!' : 'ok';
@@ -1407,7 +1408,7 @@ export function readCurrentModels(envPath, registryModels = {}) {
   };
   const tiers = resolveTierAssignments(mergedAssignments, registryModels);
   const result = { sources: {} };
-  for (const tier of ["reasoning", "standard", "fast"]) {
+  for (const tier of MODEL_TIERS) {
     result[tier] = tiers[tier].model;
     result.sources[tier] = tiers[tier].source;
   }

package/lib/model-tiers.mjs

@@ -0,0 +1,27 @@
+/**
+ * lib/model-tiers.mjs — the canonical model-tier vocabulary.
+ *
+ * `reasoning`, `standard`, and `fast` are the three work tiers every
+ * model-resolution surface keys off: the router's family tables, the registry
+ * validator's accept-list, cost selection, policy presets, the CLI, and the
+ * MCP tool schemas. They lived as a `['reasoning', 'standard', 'fast']` literal
+ * re-typed in ~30 places, so adding or renaming a tier meant the accept-lists
+ * could silently diverge from what the router actually resolves (construct-v1wk).
+ *
+ * Single source of truth for that vocabulary — deliberately zero-dependency so
+ * the lowest-level consumers (the registry validator, setup) can import it
+ * without pulling the router's provider probes or model-policy's
+ * pricing/registry imports. A JSON-schema `enum` or any caller that needs a
+ * fresh mutable array spreads it: `[...MODEL_TIERS]`.
+ *
+ * The intentionally self-contained `lib/embedded-contract/` bundle keeps its
+ * own copy on purpose — it must not import `lib/` internals.
+ */
+
+export const MODEL_TIERS = Object.freeze(['reasoning', 'standard', 'fast']);
+
+export const MODEL_TIER_SET = Object.freeze(new Set(MODEL_TIERS));
+
+export function isModelTier(value) {
+  return MODEL_TIER_SET.has(value);
+}

package/lib/models/catalog.mjs

@@ -11,6 +11,7 @@ import { loadRegistry } from '../registry/loader.mjs';
 import path from 'node:path';
 import os from 'node:os';
 import { pollFreeModels } from '../model-free-selector.mjs';
+import { MODEL_TIERS } from '../model-tiers.mjs';
 import { resolveFirstSecret, hasAnySecret } from '../providers/secret-resolver.mjs';
 import { loadProjectConfig } from '../config/project-config.mjs';
 import { doctorRoot } from '../config/xdg.mjs';
@@ -105,7 +106,7 @@ export function providerFamilyEnabled(providerId, visibility) {
 
 export function collectTierDefaultIds(registryModels = {}) {
   const ids = [];
-  for (const tier of ['reasoning', 'standard', 'fast']) {
+  for (const tier of MODEL_TIERS) {
     const def = registryModels[tier];
     if (typeof def === 'string') ids.push(def);
     else if (def && typeof def === 'object') {
@@ -176,11 +177,11 @@ export function applyModelVisibilityFilter(catalog, {
     .filter((provider) => providerFamilyEnabled(provider.id, visibility))
     .map((provider) => {
       const options = {};
-      for (const tier of ['reasoning', 'standard', 'fast']) {
+      for (const tier of MODEL_TIERS) {
         options[tier] = (provider.options?.[tier] ?? []).filter((id) => modelAllowed(id, provider.id));
       }
       const tiers = { ...provider.tiers };
-      for (const tier of ['reasoning', 'standard', 'fast']) {
+      for (const tier of MODEL_TIERS) {
         if (tiers[tier] && !modelAllowed(tiers[tier], provider.id)) {
           tiers[tier] = options[tier]?.[0] ?? null;
         }
@@ -260,6 +261,6 @@ export function isModelVisible(modelId, {
     { visibility, registryModels, activeModelId },
   );
   return filtered.providers.some((p) =>
-    ['reasoning', 'standard', 'fast'].some((tier) => (p.options[tier] ?? []).includes(modelId)),
+    MODEL_TIERS.some((tier) => (p.options[tier] ?? []).includes(modelId)),
   );
 }

package/lib/orchestration/classification.mjs

@@ -49,6 +49,17 @@ const DOC_AUTHORING_PATTERNS = [
   { pattern: /\bchangelog/i, docType: 'changelog' },
 ];
 
+// The docType each pattern maps to must exist in the routing registry's
+// knownDocTypes(), or detectDocAuthoringIntent returns a docType with a null
+// owner and the request silently loses its canonical author. A drift-guard test
+// (tests/orchestration-doc-authoring-patterns.test.mjs) asserts the subset,
+// since the mapping cannot be generated from the registry (the regex is
+// natural-language, only the docType string is registry-owned) — construct-v1wk.
+
+export function docAuthoringDocTypes() {
+  return DOC_AUTHORING_PATTERNS.map(({ docType }) => docType);
+}
+
 const AUTHORING_VERBS = /\b(write|writing|draft|drafting|create|creating|author|authoring|produce|producing|compose|composing|prepare|preparing|generate|generating)\b/i;
 
 /**

package/lib/orchestration/context-bindings.mjs

@@ -0,0 +1,85 @@
+/**
+ * lib/orchestration/context-bindings.mjs — resolve per-run context-target
+ * bindings for orchestration runs (bead construct-760c.4).
+ *
+ * An orchestration run can name which registered source targets it should draw
+ * context from — `contextTargets: [{id, role?}]`. This module validates those
+ * ids against the project's effective `sources.targets[]` at PLAN time and
+ * resolves each to a binding record persisted on the run for audit and picked up
+ * by the run's retrieval path. An unknown id is a hard error before any task is
+ * built (never a silent skip), so a run never plans against context it can't
+ * reach.
+ *
+ * `role` is an optional free-form hint (e.g. "tracker", "reference") threaded
+ * verbatim onto the binding — there is no role enum in core. Content-capable
+ * targets (directory / synced corpus, via lib/sources/content-roots.mjs) also
+ * carry a resolved `contentRoot` so a directory-bound run can read the docs
+ * directly; targets with no local content (a tracker like jira) resolve to a
+ * binding with `contentRoot: null` and provider identity only.
+ */
+
+import { resolveEffectiveSourceTargetsFromConfig } from '../config/source-targets.mjs';
+import { resolveContentRoots } from '../sources/content-roots.mjs';
+
+export class ContextTargetError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'ContextTargetError';
+    this.code = 'CONTEXT_TARGET_UNKNOWN';
+  }
+}
+
+function normalizeRequests(contextTargets) {
+  if (contextTargets == null) return [];
+  const list = Array.isArray(contextTargets) ? contextTargets : [contextTargets];
+  return list
+    .map((entry) => (typeof entry === 'string' ? { id: entry } : entry))
+    .filter((entry) => entry && typeof entry === 'object' && typeof entry.id === 'string' && entry.id.trim())
+    .map((entry) => ({ id: entry.id.trim(), role: entry.role != null ? String(entry.role) : null }));
+}
+
+/**
+ * Resolve requested context targets into binding records, or throw
+ * ContextTargetError naming the offending id and the known ids. Returns an empty
+ * array when nothing is requested — the caller then falls back to today's
+ * implicit source resolution, unchanged.
+ *
+ * @param {Array<{id: string, role?: string}>|string[]} contextTargets
+ * @param {object} opts
+ * @param {object} opts.config    loaded project config
+ * @param {object} [opts.env]
+ * @param {string} [opts.cwd]     project root, for content-root resolution
+ * @returns {{id, provider, role, resolution, contentRoot, ref}[]}
+ */
+export function resolveContextBindings(contextTargets, { config, env = process.env, cwd = process.cwd() } = {}) {
+  const requests = normalizeRequests(contextTargets);
+  if (!requests.length) return [];
+
+  const targets = resolveEffectiveSourceTargetsFromConfig(config, env);
+  const byId = new Map(targets.map((t) => [t.id, t]));
+  const contentRoots = resolveContentRoots(targets, { projectRoot: cwd });
+  const rootByTargetId = new Map(contentRoots.map((r) => [r.origin.targetId, r]));
+
+  const bindings = [];
+  const seen = new Set();
+  for (const req of requests) {
+    if (seen.has(req.id)) continue;
+    seen.add(req.id);
+
+    const target = byId.get(req.id);
+    if (!target) {
+      const known = [...byId.keys()].join(', ') || '(none registered)';
+      throw new ContextTargetError(`unknown context target "${req.id}" — known targets: ${known}`);
+    }
+    const root = rootByTargetId.get(req.id) || null;
+    bindings.push({
+      id: target.id,
+      provider: target.provider,
+      role: req.role,
+      resolution: 'resolved',
+      contentRoot: root ? root.dir : null,
+      ref: root ? root.origin.ref : null,
+    });
+  }
+  return bindings;
+}

package/lib/orchestration/readiness.mjs

@@ -12,6 +12,7 @@ import { dirname, join } from 'node:path';
 import { getInstalledVersion } from '../version.mjs';
 import { CONTRACT_VERSION, MIN_CLIENT_CONTRACT_VERSION } from '../embedded-contract/contract-version.mjs';
 import { getDeploymentMode } from '../deployment-mode.mjs';
+import { MODEL_TIERS } from '../model-tiers.mjs';
 import { doctorRoot } from '../config/xdg.mjs';
 import { resolveExecution } from '../embedded-contract/execution.mjs';
 import { resolveEmbeddedModel } from '../embedded-contract/model-resolve.mjs';
@@ -165,7 +166,7 @@ export function buildOrchestrationReadiness(input = {}, { env = process.env, cwd
   const workerBackend = resolveWorkerBackend({ config });
   const modelResolved = {};
   let firstUnresolvedTier = null;
-  for (const tier of ['reasoning', 'standard', 'fast']) {
+  for (const tier of MODEL_TIERS) {
     const resolved = resolveEmbeddedModel({ requestedTier: tier }, { env });
     modelResolved[tier] = resolved.resolutionSource !== 'config-error';
     if (!modelResolved[tier] && !firstUnresolvedTier) firstUnresolvedTier = tier;