amicus 4.9.7 → 4.10.0

package/src/utils/alias-store.js

@@ -0,0 +1,65 @@
+/**
+ * @module utils/alias-store
+ * The write sinks the alias review flow needs beyond `setup.js :: addAlias`
+ * (#238 §2). Every write is read-modify-write through `saveConfig` (which
+ * normalizes, D6) and preserves every other key — the no-clobber contract of
+ * `provider-default-picker.js :: applyProviderDefault`.
+ *
+ * `removeAlias` is BOTH "unpin" (a curated name resurrects from the defaults)
+ * and "delete" (a user-invented name is gone) — the meaning is decided by
+ * whether the name is curated, not by this module (D1).
+ *
+ * Dismissals are keyed `alias@proposedId` (Q5): permanent for that pair, and a
+ * newer proposed id for the same alias is a new key that asks again.
+ */
+
+'use strict';
+
+const own = (obj, key) => Object.prototype.hasOwnProperty.call(obj, key);
+
+/**
+ * @param {string} alias
+ * @returns {boolean} true when a key was removed and the config saved
+ */
+function removeAlias(alias) {
+  if (typeof alias === 'string') { alias = alias.trim(); }
+  if (!alias || typeof alias !== 'string' || alias === 'null') {
+    throw new Error(`Invalid alias name: '${alias}'. Alias name must be a non-empty string.`);
+  }
+  const { loadConfig, saveConfig } = require('./config');
+  const config = loadConfig();
+  if (!config || !config.aliases || typeof config.aliases !== 'object' || !own(config.aliases, alias)) { return false; }
+  delete config.aliases[alias];
+  saveConfig(config);
+  return true;
+}
+
+/** @returns {Object<string,string>} null-prototype copy of aliasReview.dismissed */
+function readDismissals() {
+  const { loadConfig } = require('./config');
+  const config = loadConfig();
+  const out = { __proto__: null };
+  const d = config && config.aliasReview && typeof config.aliasReview === 'object' ? config.aliasReview.dismissed : null;
+  if (d && typeof d === 'object') {
+    for (const [k, v] of Object.entries(d)) { if (typeof v === 'string') { out[k] = v; } }
+  }
+  return out;
+}
+
+/**
+ * @param {string} dismissKey `alias@proposedId`
+ * @param {Date} [now]
+ */
+function recordDismissal(dismissKey, now = new Date()) {
+  if (typeof dismissKey !== 'string' || !dismissKey || !dismissKey.includes('@')) {
+    throw new Error(`Invalid dismissKey '${dismissKey}': expected alias@proposedId`);
+  }
+  const { loadConfig, saveConfig } = require('./config');
+  const config = loadConfig() || {};
+  if (!config.aliasReview || typeof config.aliasReview !== 'object') { config.aliasReview = {}; }
+  if (!config.aliasReview.dismissed || typeof config.aliasReview.dismissed !== 'object') { config.aliasReview.dismissed = {}; }
+  config.aliasReview.dismissed[dismissKey] = now.toISOString();
+  saveConfig(config);
+}
+
+module.exports = { removeAlias, readDismissals, recordDismissal };

package/src/utils/config.js

@@ -77,7 +77,10 @@ function saveConfig(configData) {
       }
       cleaned[key] = value;
     }
-    configData.aliases = cleaned;
+    // #238 D6: a key equal to the shipped default is the same as absence —
+    // drop it so the alias FOLLOWS the next pin bump (one Notice per key).
+    const { normalizeAliases } = require('./alias-state');
+    configData.aliases = normalizeAliases(cleaned, DEFAULT_ALIASES, (line) => process.stderr.write(line)).aliases;
   }
   const configDir = getConfigDir();
   fs.mkdirSync(configDir, { recursive: true, mode: 0o700 });
@@ -187,9 +190,11 @@ function computeConfigHash() {
 /** @returns {string} Markdown alias table with (default) marker, or empty string */
 function buildAliasTable() {
   const config = loadConfig();
-  if (!config || !config.aliases || Object.keys(config.aliases).length === 0) {
-    return '';
-  }
+  if (!config) { return ''; }
+  // #238 D6: EFFECTIVE aliases — a following alias is absent from config.aliases
+  // but is still an alias the project's CLAUDE.md block must list.
+  const aliases = getEffectiveAliases();
+  if (Object.keys(aliases).length === 0) { return ''; }
 
   const defaultAlias = config.default || null;
   const lines = [];
@@ -197,7 +202,7 @@ function buildAliasTable() {
   lines.push('| Alias | Model |');
   lines.push('|-------|-------|');
 
-  for (const [alias, model] of Object.entries(config.aliases)) {
+  for (const [alias, model] of Object.entries(aliases)) {
     const marker = (alias === defaultAlias) ? ' (default)' : '';
     lines.push(`| ${alias}${marker} | ${model} |`);
   }

package/src/utils/degrade.js

@@ -39,6 +39,14 @@ const DEGRADE_CHANNELS = Object.freeze(new Set([
   // lost reviewer by consumers that only ever meant seats (verdict-seat-loss.js
   // already gates the Stage-2 notes out of `seat-unbound` for the same reason).
   'stage2-judge',
+  // #242 / spec §5 (v4.9.8): render-time rows the report derives from runStats
+  // (council/report-lost-rows.js) — never emitted by the sink, so neither can
+  // flip `degraded` or the exit code. `unverified-repair`: a seat's findings
+  // came from a repair of a response with no findings block
+  // (runStats[].findingsUnverified); `repair-refused`: the repair broke its
+  // count contract (runStats[].repairRefused). Registered here because the
+  // degrade-contract drift pin reads every `channel:` literal in src/.
+  'unverified-repair', 'repair-refused',
   'internal',
   // doctor channels
   'doctor-check-failed', 'doctor-fix',

package/src/utils/model-id-siblings.js

@@ -0,0 +1,106 @@
+/**
+ * @module utils/model-id-siblings
+ * The tier-safe sibling comparator (#238 D7). A sibling shares a pin's vendor
+ * path, its pre-version prefix and its post-version suffix, and differs only in
+ * the version number — so `gpt-5.6-terra` is never compared against
+ * `gpt-5.6-sol`, and `kimi-k3` never against `kimi-k2.7-code`. Lifted verbatim
+ * from scripts/check-ci-alias-pins.js (which still consumes it) so the alias
+ * review engine (alias-proposals.js) asks the user's pinned ids the SAME sibling
+ * question the CI drift gate asks the CI alias map. `amicus models --check`
+ * asks a DIFFERENT question of the same shipped pins — still-listed vs.
+ * gone-from-the-catalog — through `alias-audit.js :: findStaleAliases`, not
+ * this module (#249 r2 review F2: this line previously implied otherwise).
+ *
+ * Known limits, both under-report by design (a suppressed sibling, never a
+ * manufactured one) — INVARIANT: neither rule can ever turn two DIFFERENT
+ * models into siblings, only fail to notice two of the SAME family are:
+ *   1. A dash-versioned id — Anthropic's `claude-opus-4-5`, say — parses its
+ *      trailing `-5` as part of the suffix rather than the version (the
+ *      version group only extends through a DOTTED numeric run), so two
+ *      dash-versioned releases are never compared as siblings at all.
+ *   2. A numeric run glued to a following ASCII letter is a size/variant
+ *      token, never a version (#249 r2 B2) — `parsePin` returns `null` for
+ *      both `gpt-oss-20b` and `gpt-oss-120b` (#249 r2 review F6: a null
+ *      parse has no prefix at all, unlike limit 1's dash-versioned case
+ *      above), since `20`/`120` are each immediately followed by `b` and no
+ *      other numeric-dotted run exists to fall back to. MEASURED against a
+ *      638-id live catalog cache: 129 ids carry a glued run (`24b`, `70b`,
+ *      `a3b`, `8x22b`, `4o`, …) — without this rule `gpt-oss-120b` reads as
+ *      a "newer same-tier sibling" of `gpt-oss-20b`, a different model
+ *      wearing a bigger size, not a newer version. A run preceded by a
+ *      letter is unaffected (`kimi-k3`, `deepseek-v4-pro`, `qwen3.8-max`
+ *      keep parsing exactly as before) — only the character AFTER the run
+ *      is examined.
+ * `scripts/check-ci-alias-pins.js`'s CI drift gate consumes `parsePin`
+ * unchanged, so it inherits rule 2 automatically.
+ */
+
+'use strict';
+
+/**
+ * Split a model id into the parts a sibling comparison needs.
+ * `openrouter/z-ai/glm-5.3` -> vendor `openrouter/z-ai`, prefix `glm-`,
+ * version [5,3], suffix ``. Returns null when the tail carries no numeric
+ * version (nothing to compare) or the id is an OpenRouter floating pointer,
+ * whose `~` forms name no concrete release.
+ * @param {string} id
+ * @returns {{vendor:string, prefix:string, version:number[], suffix:string}|null}
+ */
+function parsePin(id) {
+  if (typeof id !== 'string' || id.includes('~')) { return null; }
+  const cut = id.lastIndexOf('/');
+  if (cut === -1) { return null; }
+  const vendor = id.slice(0, cut);
+  const tail = id.slice(cut + 1);
+  // Scan every numeric-dotted run left to right; the first one NOT glued to
+  // a following ASCII letter is the version (#249 r2 B2 -- see the module
+  // docblock's known limit 2). A glued run is a size/variant token (`20b`,
+  // `8x22b`) and is skipped, falling through to whatever comes after it --
+  // which, once a version is found, is everything the plain suffix already
+  // captured, glued runs included.
+  for (const m of tail.matchAll(/\d+(?:\.\d+)*/g)) {
+    const end = m.index + m[0].length;
+    if (/[A-Za-z]/.test(tail[end] || '')) { continue; }
+    return { vendor, prefix: tail.slice(0, m.index), version: m[0].split('.').map(Number), suffix: tail.slice(end) };
+  }
+  return null;
+}
+
+/** @returns {number} >0 when a is newer than b, <0 when older, 0 when equal */
+function compareVersions(a, b) {
+  for (let i = 0; i < Math.max(a.length, b.length); i++) {
+    const diff = (a[i] || 0) - (b[i] || 0);
+    if (diff !== 0) { return diff; }
+  }
+  return 0;
+}
+
+/**
+ * @param {string} pinned a fully-qualified model id
+ * @param {string[]} catalogIds every id in the live catalog
+ * @returns {string|null} the newest strictly-newer sibling, or null
+ */
+function newestSibling(pinned, catalogIds) {
+  const pin = parsePin(pinned);
+  if (!pin) { return null; }
+  let best = null;
+  let bestVersion = pin.version;
+  for (const id of catalogIds) {
+    // No blanket `:` skip. `:free` / `:batch` land in `suffix`, so the
+    // suffix equality below ALREADY refuses to bump a plain pin to a billing
+    // variant — while a blanket skip additionally blinded the checker to a
+    // pin that is ITSELF a variant (a `:free` pin could never find a `:free`
+    // sibling, and went quietly unwatched forever). Council finding D3.
+    const other = parsePin(id);
+    if (!other) { continue; }
+    if (other.vendor !== pin.vendor) { continue; }
+    if (other.prefix !== pin.prefix || other.suffix !== pin.suffix) { continue; }
+    if (compareVersions(other.version, bestVersion) > 0) {
+      best = id;
+      bestVersion = other.version;
+    }
+  }
+  return best;
+}
+
+module.exports = { parsePin, compareVersions, newestSibling };

package/src/utils/model-validator.js

@@ -159,7 +159,7 @@ async function validateAgainstCatalog(resolvedModel, alias) {
   throw new Error(
     `Model '${resolvedModel}' not found in the OpenRouter catalog.\n` +
     (list ? `Did you mean:\n${list}\n` : '') +
-    `Fix: amicus setup --add-alias ${alias || '<alias>'}=${relevant[0] ? relevant[0].id : 'openrouter/provider/model'}\n` +
+    `Fix: amicus aliases --review  (or pin directly: amicus setup --add-alias ${alias || '<alias>'}=${relevant[0] ? relevant[0].id : 'openrouter/provider/model'})\n` +
     'Run \'amicus models --refresh\' to update the catalog, or pass --no-validate-model to skip.'
   );
 }

package/src/utils/quick-picks.js

@@ -10,7 +10,7 @@
 
 'use strict';
 
-const { getFamilies, toDefaultAliases, DIVERGENT_VENDORS } = require('./curated-models');
+const { getFamilies, DIVERGENT_VENDORS } = require('./curated-models');
 const { directFormIfSafe } = require('./model-canonicalization');
 
 const MARKER_RE = /(-preview|-exp|-beta|-latest|:free)+$/;
@@ -37,7 +37,11 @@ function compareIdsDesc(a, b) {
 function pickCurrent(catalog, nsPrefix, vendorPath, idPattern) {
   const prefix = `${nsPrefix}${vendorPath}/`;
   const ids = (Array.isArray(catalog) ? catalog : [])
-    .map(m => m && m.id)
+    // #238 §5: a non-authoritative row (the hardcoded Anthropic floor, a
+    // floor-fallback) is not evidence of what the provider serves — the same
+    // guard gateway-route-audit.js :: isAuthoritative applies per gateway.
+    .filter(m => m && m.authoritative !== false)
+    .map(m => m.id)
     .filter(id => typeof id === 'string' && id.startsWith(prefix))
     .filter(id => idPattern.test(id.slice(prefix.length)));
   if (ids.length === 0) { return null; }
@@ -92,38 +96,15 @@ function toStorableRoute(pick, catalogInfo) {
   }
   const route = routes.openrouter || Object.values(routes)[0];
   if (!route) { return undefined; }
-  // issue 214 remedy 1: this value is PERSISTED (sidecar/setup.js writes it into
-  // config.aliases; toLiveSeedAliases seeds a fresh config with it), so it must
-  // not be a blind prefix strip. directFormIfSafe keeps the optimism for a
-  // namespace that was never fetched while refusing for one the catalog
-  // disproves OR whose fetch was rejected -- the gap #208 closed on the picker
-  // path and left open here.
+  // issue 214 remedy 1: this value is PERSISTED -- sidecar/setup.js writes it
+  // into config.aliases for the chosen default when it differs from the
+  // shipped pin (#238 Q9) -- so it must not be a blind prefix strip.
+  // directFormIfSafe keeps the optimism for a namespace that was never
+  // fetched while refusing for one the catalog disproves OR whose fetch was
+  // rejected -- the gap #208 closed on the picker path and left open here.
   return directFormIfSafe(pick.vendorPath, route, catalogInfo || { models: [] });
 }
 
-/**
- * Seed map for fresh configs: static defaults overlaid with live family
- * routes (cardless aliases stay pinned). See `toStorableRoute` for why the
- * overlaid value is not a raw prefix strip.
- * @returns {Object<string,string>}
- */
-function toLiveSeedAliases(catalogOrInfo) {
-  // Accepts the bare models array (historical callers) or a full catalogInfo.
-  // issue 214: the evidence was always handed in and then discarded.
-  const info = Array.isArray(catalogOrInfo)
-    ? { models: catalogOrInfo }
-    : (catalogOrInfo || { models: [] });
-  const seeds = toDefaultAliases();
-  for (const r of resolveQuickPicks(info.models || [])) {
-    if (r.source === 'live' && r.routes.openrouter) {
-      const stored = toStorableRoute(r, info);
-      if (stored) { seeds[r.alias] = stored; }
-    }
-  }
-  return seeds;
-}
-
-
 /**
  * Per-provider SAFE storable form for a resolved quick pick (issue 214).
  *
@@ -147,4 +128,4 @@ function canonicalRoutesFor(pick, catalogInfo) {
   return out;
 }
 
-module.exports = { compareIdsDesc, canonicalRoutesFor, pickCurrent, resolveQuickPicks, toLiveSeedAliases, toStorableRoute };
+module.exports = { compareIdsDesc, canonicalRoutesFor, pickCurrent, resolveQuickPicks, toStorableRoute };

package/src/utils/text-sanitize.js

@@ -20,6 +20,17 @@
  * that has landed here (ANSI in round 2, bidi in round 3) was a class the
  * previous pass could not see.
  *
+ * `safeFragment` (#249 r2 C4) is the same discipline for a shorter kind of
+ * text: not a sentence-length excerpt but ONE quoted config/catalog/typed
+ * value — an alias name, a model id, a dismiss key. MEASURED: the longest id
+ * in a 638-row live catalog cache is 67 characters
+ * (`openrouter/cognitivecomputations/dolphin-mistral-24b-venice-edition`);
+ * past 96 it is a payload, not an id. `utils/alias-shadow.js` keeps its OWN
+ * 64-char local cap (measured against the curated table alone, which never
+ * exceeds 39 characters) through this same `collapseExcerpt` function — one
+ * sanitizer, two caps sized to what each caller actually holds, no second
+ * dialect.
+ *
  * PURE: no I/O, no throwing paths, no state.
  */
 
@@ -75,7 +86,23 @@ function collapseExcerpt(text, maxChars = MAX_EXCERPT_CHARS) {
   return `${oneLine.slice(0, maxChars - 1)}…`;
 }
 
+/** One quoted fragment's cap — an id/name/key, not a sentence. See the module docblock. */
+const MAX_FRAGMENT_CHARS = 96;
+
+/**
+ * One third-party fragment (an alias name, a model id, a dismiss key, a
+ * catalog note), safe to interpolate into a terminal line. Same pass as
+ * `collapseExcerpt`, just capped for a short value instead of a sentence.
+ * @param {*} value
+ * @returns {string}
+ */
+function safeFragment(value) {
+  return collapseExcerpt(value, MAX_FRAGMENT_CHARS);
+}
+
 module.exports = {
   collapseExcerpt,
   MAX_EXCERPT_CHARS,
+  safeFragment,
+  MAX_FRAGMENT_CHARS,
 };