@aidriftline/driftline 0.1.14 → 0.1.16

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aidriftline/driftline",
-  "version": "0.1.14",
+  "version": "0.1.16",
   "description": "Finds OpenAI, Anthropic and Google model IDs in your code and warns before they are retired. CLI, GitHub Action and MCP server.",
   "mcpName": "io.github.AI-Driftline/driftline",
   "type": "module",

package/registry/models.json

@@ -1,5 +1,5 @@
 {
-  "checked": "2026-11-12",
+  "checked": "2026-11-13",
   "note": "Hand-maintained from the official deprecation pages. Re-check before each release. Entries with a 'kind' other than text are scanned and reported but never drift-tested. gpt-4-1106-preview is listed on OpenAI's page under both 2026-03-26 and 2026-10-23; the later date is used so builds are not failed on a conflicting record. Entries with routes: true keep answering after the date, but the provider sends the requests to the replacement model (Google calls this automatic routing); the 'retires' date is the day routing starts. gemini-3.5-flash and gemini-3.7-flash already route to newer models with no date given, so they are left out.",
   "sources": {
     "openai": "https://developers.openai.com/api/docs/deprecations",
@@ -151,7 +151,9 @@
       "provider": "openai",
       "retires": "2026-12-11",
       "qualifier": "exact",
-      "replacement": "gpt-5.6-sol",
+      "replacement": "gpt-6.1-sol",
+      "previous_replacement": "gpt-5.6-sol",
+      "replacement_changed": "2026-11-13",
       "announced": "2026-06-11"
     },
     {
@@ -159,7 +161,9 @@
       "provider": "openai",
       "retires": "2026-12-11",
       "qualifier": "exact",
-      "replacement": "gpt-5.6-sol",
+      "replacement": "gpt-6.1-sol",
+      "previous_replacement": "gpt-5.6-sol",
+      "replacement_changed": "2026-11-13",
       "announced": "2026-06-11"
     },
     {
@@ -167,7 +171,10 @@
       "provider": "openai",
       "retires": "2026-12-11",
       "qualifier": "exact",
-      "replacement": "gpt-5.6-sol",
+      "replacement": "gpt-6.1-sol",
+      "replacement_note": "reasoning.mode: pro, in the Responses API",
+      "previous_replacement": "gpt-5.6-sol",
+      "replacement_changed": "2026-11-13",
       "announced": "2026-06-11"
     },
     {
@@ -175,7 +182,10 @@
       "provider": "openai",
       "retires": "2026-12-11",
       "qualifier": "exact",
-      "replacement": "gpt-5.6-sol",
+      "replacement": "gpt-6.1-sol",
+      "replacement_note": "reasoning.mode: pro, in the Responses API",
+      "previous_replacement": "gpt-5.6-sol",
+      "replacement_changed": "2026-11-13",
       "announced": "2026-06-11"
     },
     {
@@ -183,7 +193,9 @@
       "provider": "openai",
       "retires": "2026-12-11",
       "qualifier": "exact",
-      "replacement": "gpt-5.6-sol",
+      "replacement": "gpt-6.1-sol",
+      "previous_replacement": "gpt-5.6-sol",
+      "replacement_changed": "2026-11-13",
       "announced": "2026-06-11"
     },
     {
@@ -191,7 +203,9 @@
       "provider": "openai",
       "retires": "2026-12-11",
       "qualifier": "exact",
-      "replacement": "gpt-5.6-sol",
+      "replacement": "gpt-6.1-sol",
+      "previous_replacement": "gpt-5.6-sol",
+      "replacement_changed": "2026-11-13",
       "announced": "2026-06-11"
     },
     {
@@ -199,7 +213,10 @@
       "provider": "openai",
       "retires": "2026-12-11",
       "qualifier": "exact",
-      "replacement": "gpt-5.6-sol",
+      "replacement": "gpt-6.1-sol",
+      "replacement_note": "reasoning.mode: pro, in the Responses API",
+      "previous_replacement": "gpt-5.6-sol",
+      "replacement_changed": "2026-11-13",
       "announced": "2026-06-11"
     },
     {
@@ -207,7 +224,10 @@
       "provider": "openai",
       "retires": "2026-12-11",
       "qualifier": "exact",
-      "replacement": "gpt-5.6-sol",
+      "replacement": "gpt-6.1-sol",
+      "replacement_note": "reasoning.mode: pro, in the Responses API",
+      "previous_replacement": "gpt-5.6-sol",
+      "replacement_changed": "2026-11-13",
       "announced": "2026-06-11"
     },
     {
@@ -215,7 +235,9 @@
       "provider": "openai",
       "retires": "2026-12-11",
       "qualifier": "exact",
-      "replacement": "gpt-5.6-terra",
+      "replacement": "gpt-6.1-terra",
+      "previous_replacement": "gpt-5.6-terra",
+      "replacement_changed": "2026-11-13",
       "announced": "2026-06-11"
     },
     {
@@ -223,7 +245,9 @@
       "provider": "openai",
       "retires": "2026-12-11",
       "qualifier": "exact",
-      "replacement": "gpt-5.6-terra",
+      "replacement": "gpt-6.1-terra",
+      "previous_replacement": "gpt-5.6-terra",
+      "replacement_changed": "2026-11-13",
       "announced": "2026-06-11"
     },
     {
@@ -231,7 +255,9 @@
       "provider": "openai",
       "retires": "2026-12-11",
       "qualifier": "exact",
-      "replacement": "gpt-5.6-luna",
+      "replacement": "gpt-6-luna",
+      "previous_replacement": "gpt-5.6-luna",
+      "replacement_changed": "2026-11-13",
       "announced": "2026-06-11"
     },
     {
@@ -239,7 +265,9 @@
       "provider": "openai",
       "retires": "2026-12-11",
       "qualifier": "exact",
-      "replacement": "gpt-5.6-luna",
+      "replacement": "gpt-6-luna",
+      "previous_replacement": "gpt-5.6-luna",
+      "replacement_changed": "2026-11-13",
       "announced": "2026-06-11"
     },
     {
@@ -344,6 +372,7 @@
       "retires": "2026-10-23",
       "qualifier": "exact",
       "replacement": "gpt-5.6-sol",
+      "replacement_note": "reasoning.mode: pro",
       "announced": "2026-04-22"
     },
     {
@@ -352,6 +381,7 @@
       "retires": "2026-10-23",
       "qualifier": "exact",
       "replacement": "gpt-5.6-sol",
+      "replacement_note": "reasoning.mode: pro",
       "announced": "2026-04-22"
     },
     {
@@ -1944,6 +1974,46 @@
       "qualifier": "earliest",
       "replacement": "antigravity-preview-09-2026",
       "kind": "agent"
+    },
+    {
+      "id": "gpt-3.5-turbo-completions",
+      "provider": "openai",
+      "retires": "2026-10-23",
+      "qualifier": "exact",
+      "replacement": "gpt-5.6-terra",
+      "announced": "2026-04-22"
+    },
+    {
+      "id": "gpt-4-completions",
+      "provider": "openai",
+      "retires": "2026-10-23",
+      "qualifier": "exact",
+      "replacement": "gpt-5.6-sol",
+      "announced": "2026-04-22"
+    },
+    {
+      "id": "gpt-4-0613-completions",
+      "provider": "openai",
+      "retires": "2026-10-23",
+      "qualifier": "exact",
+      "replacement": "gpt-5.6-sol",
+      "announced": "2026-04-22"
+    },
+    {
+      "id": "gpt-4-turbo-completions",
+      "provider": "openai",
+      "retires": "2026-10-23",
+      "qualifier": "exact",
+      "replacement": "gpt-5.6-sol",
+      "announced": "2026-04-22"
+    },
+    {
+      "id": "gpt-4-turbo-preview-completions",
+      "provider": "openai",
+      "retires": "2026-03-26",
+      "qualifier": "exact",
+      "replacement": "gpt-5",
+      "announced": "2025-09-26"
     }
   ]
 }

package/src/cli.js

@@ -7,6 +7,8 @@
 //   driftline [directory] --json       same scan, machine-readable (for scripts and coding agents)
 //   driftline mcp                      MCP server on stdio for coding agents (Claude Code, Cursor, ...)
 //   driftline --help | --version
+import { loadBestRegistry } from "./registry.js";
+import { migrationFor } from "./migration.js";
 import { resolve } from "node:path";
 import { readFileSync } from "node:fs";
 import { execFileSync } from "node:child_process";
@@ -67,8 +69,10 @@ if (cmd === "-h" || cmd === "--help" || cmd === "help") {
   if (!r.ok) { console.error(r.reason); process.exitCode = 1; }
   else console.log("Deactivated. That slot is free for another GitHub account.");
 } else {
+  const { reg } = await loadBestRegistry();
   const result = await run({
     root: resolve(cmd || "."),
+    registry: reg,
     licenseKey: process.env.DRIFTLINE_LICENSE_KEY || "",
     account: process.env.GITHUB_REPOSITORY_OWNER || accountFromGit(),
     log: (m) => console.error(m),
@@ -77,7 +81,7 @@ if (cmd === "-h" || cmd === "--help" || cmd === "help") {
     const pick = (f) => ({
       id: f.id, file: f.file, line: f.line, status: f.status, docOnly: !!f.doc,
       provider: f.entry?.provider, retires: f.entry?.retires, qualifier: f.entry?.qualifier,
-      replacement: f.entry?.replacement, routes: !!f.entry?.routes, aliasOf: f.entry?.aliasOf,
+      replacement: f.entry?.replacement, migration: migrationFor(f.entry) || undefined, routes: !!f.entry?.routes, aliasOf: f.entry?.aliasOf,
     });
     console.log(JSON.stringify({ findings: result.findings.map(pick), drift: result.drift || [] }, null, 2));
   } else console.log(result.markdown);

package/src/index.js

@@ -1,5 +1,7 @@
 #!/usr/bin/env node
 // GitHub Action entry point.
+import { replacementText, replacementChange, loadBestRegistry } from "./registry.js";
+import { migrationFor } from "./migration.js";
 import { resolve } from "node:path";
 import { statSync } from "node:fs";
 import { randomUUID } from "node:crypto";
@@ -26,9 +28,12 @@ async function main() {
     failOn = "retired";
   }
 
+  const { reg, source } = await loadBestRegistry({ offline: input("registry", "live").toLowerCase() === "bundled" });
+  console.log(`Registry: ${source === "live" ? "live copy from aidriftline.com" : "copy bundled with this version"}, checked ${reg.checked}.`);
   const result = await run({
     root,
     repoRoot: workspace,
+    registry: reg,
     warnDays,
     promptsFile: input("prompts-file", ".driftline/prompts.yml"),
     licenseKey: input("license-key"),
@@ -48,7 +53,10 @@ async function main() {
   }
   for (const f of toAnnotate.slice(0, MAX_ANNOTATIONS)) {
     const level = f.status === "deprecated" || f.doc ? "notice" : "warning";
-    const repl = f.entry?.replacement && !f.entry.routes ? ` Replacement: ${f.entry.replacement}.` : "";
+    const chg = replacementChange(f.entry);
+    const mig = f.entry.routes ? null : migrationFor(f.entry);
+    const more = mig && !mig.drop_in && mig.change !== "settings" ? ` Not just a rename: ${mig.note}` : mig?.change === "choose" ? ` ${mig.note}` : "";
+    const repl = f.entry?.replacement && !f.entry.routes ? ` Replacement: ${replacementText(f.entry)}.${chg ? ` (Changed by the provider on ${chg.on}; before it was ${chg.was}.)` : ""}` : "";
     const text = f.entry.routes && f.entry.replacement
       ? (f.days <= 0
         ? `Since ${f.entry.retires}, requests to ${f.id} are answered by ${f.entry.replacement}. The call still works, but the model behind it changed.`
@@ -56,7 +64,8 @@ async function main() {
       : f.entry.qualifier === "earliest" && f.days <= 0
       ? `${f.id} is past its earliest shutdown date (${f.entry.retires}) and may stop working at any time.`
       : `${f.id} ${STATUS_TEXT[f.status]} (${f.entry.retires}).`;
-    annotate(level, text + repl, f.file, f.line);
+    const routedMore = f.entry.routes && migrationFor(f.entry)?.change === "params" ? ` Before then, apply the request changes the provider lists: ${migrationFor(f.entry).note}` : "";
+    annotate(level, text + repl + more + routedMore, f.file, f.line);
   }
 
   // The report contains model answers; stop GitHub from reading any "::command::" lines inside it.

package/src/mcp.js

@@ -6,39 +6,33 @@
 import { readFileSync, statSync } from "node:fs";
 import { resolve } from "node:path";
 import { createInterface } from "node:readline";
-import { REGISTRY_PATH, buildRegistry, classify, normalizeId } from "./registry.js";
+import { loadBestRegistry, classify, normalizeId, replacementChange } from "./registry.js";
+import { migrationFor } from "./migration.js";
 import { scanDirectory } from "./scan.js";
 
 const VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
-const LIVE_URL = "https://aidriftline.com/models.json";
 const page = (id) => `https://aidriftline.com/models/${id}/`;
 const WHO = { openai: "OpenAI", anthropic: "Anthropic", google: "Google" };
 
-export async function loadBestRegistry({ fetchImpl = fetch, offline = process.env.DRIFTLINE_OFFLINE === "1" } = {}) {
-  const bundled = JSON.parse(readFileSync(REGISTRY_PATH, "utf8"));
-  if (offline) return { reg: buildRegistry(bundled), source: "bundled" };
-  try {
-    const res = await fetchImpl(LIVE_URL, { signal: AbortSignal.timeout(4000) });
-    const live = res.ok ? await res.json() : null;
-    if (live?.models?.length && live.checked >= bundled.checked) return { reg: buildRegistry(live), source: "live" };
-  } catch { /* offline or slow: use the bundled copy */ }
-  return { reg: buildRegistry(bundled), source: "bundled" };
-}
+export { loadBestRegistry }; // shared with the Action and CLI (src/registry.js)
 
 // One plain sentence an agent can pass on to the user.
-function advice(c) {
+function advice(c, today = new Date()) {
   const m = c.entry;
   if (!m) return "Not in Driftline's registry: no retirement is announced for it on the OpenAI, Anthropic or Google deprecation pages (or it is not a model ID).";
   const who = WHO[m.provider] || m.provider;
-  const repl = m.replacement ? ` Replacement: ${m.replacement}.` : "";
+  const chg = replacementChange(m, today);
+  const mig = migrationFor(m);
+  const migText = mig && !mig.drop_in && mig.change !== "settings" ? ` More than a rename: ${mig.note}` : mig?.change === "choose" ? ` ${mig.note}` : "";
+  const repl = m.replacement ? ` Replacement: ${m.replacement}${m.replacement_note ? ` (${m.replacement_note})` : ""}.${chg ? ` ${who} changed this recommendation on ${chg.on}; before it was ${chg.was}.` : ""}` : "";
   if (m.qualifier === "not-before") return `Active. ${who} says it will not be retired before ${m.retires}.`;
   if (m.routes) return c.days <= 0
-    ? `Since ${m.retires}, ${who} answers requests for it with ${m.replacement}. No error, but answers come from a different model.`
-    : `From ${m.retires} (in ${c.days} days), ${who} will answer requests for it with ${m.replacement}.`;
+    ? `Since ${m.retires}, ${who} answers requests for it with ${m.replacement}. No error, but answers come from a different model.${migText}`
+    : `From ${m.retires} (in ${c.days} days), ${who} will answer requests for it with ${m.replacement}.${migText}`;
   if (m.qualifier === "earliest") return c.days <= 0
-    ? `${who} listed ${m.retires} as the earliest shutdown date; it can stop working at any time now.${repl}`
-    : `${who} may shut it down from ${m.retires} (in ${c.days} days).${repl}`;
-  return c.days <= 0 ? `Retired on ${m.retires}. Calls to it fail.${repl}` : `Retires on ${m.retires} (in ${c.days} days). Calls fail after that.${repl}`;
+    ? `${who} listed ${m.retires} as the earliest shutdown date; it can stop working at any time now.${repl}${migText}`
+    : `${who} may shut it down from ${m.retires} (in ${c.days} days).${repl}${migText}`;
+  return c.days <= 0 ? `Retired on ${m.retires}. Calls to it fail.${repl}${migText}` : `Retires on ${m.retires} (in ${c.days} days). Calls fail after that.${repl}${migText}`;
 }
 
 function describe(rawId, reg, today) {
@@ -49,9 +43,11 @@ function describe(rawId, reg, today) {
     id: rawId, ...(id !== rawId ? { normalized: id } : {}),
     status: c.status, ...(m ? {
       provider: m.provider, retires: m.retires, qualifier: m.qualifier, days_left: c.days,
-      replacement: m.replacement || null, routes: !!m.routes, ...(m.aliasOf ? { alias_of: m.aliasOf } : {}), page: page(m.aliasOf || m.id),
+      replacement: m.replacement || null, ...(m.replacement_note ? { replacement_note: m.replacement_note } : {}),
+      ...(m.previous_replacement ? { previous_replacement: m.previous_replacement, replacement_changed: m.replacement_changed } : {}), routes: !!m.routes, ...(m.aliasOf ? { alias_of: m.aliasOf } : {}), page: page(m.aliasOf || m.id),
     } : {}),
-    advice: advice(c),
+    ...(m && migrationFor(m) ? { migration: migrationFor(m) } : {}),
+    advice: advice(c, today),
   };
 }
 
@@ -66,6 +62,10 @@ const MODEL_RESULT = {
     qualifier: { type: "string", enum: ["exact", "earliest", "not-before"], description: "exact date, earliest possible shutdown (Google), or not before this date (Anthropic)" },
     days_left: { type: "number", description: "Days until the date; 0 or negative when it has passed" },
     replacement: { type: ["string", "null"] },
+    previous_replacement: { type: "string", description: "The replacement the provider recommended before it changed its advice" },
+    replacement_changed: { type: "string", description: "YYYY-MM-DD: when the change was seen on the provider's page" },
+    migration: { type: "object", description: "Whether moving to the replacement is just a new model name (drop_in true) or needs more: change = rename | settings | params | api | re-embed | choose, with a note and the provider's guide", properties: { change: { type: "string" }, drop_in: { type: "boolean" }, note: { type: "string" }, guide: { type: ["string", "null"] } } },
+    replacement_note: { type: "string", description: "Extra instruction the provider gives with the replacement (e.g. a setting or API to use). Without it, switching the model name alone is not enough" },
     routes: { type: "boolean", description: "true: after the date the provider answers with the replacement model instead of failing" },
     alias_of: { type: "string" }, page: { type: "string", description: "aidriftline.com page with the source for this date" },
     advice: { type: "string", description: "One plain sentence to pass on to the user" },

package/src/migration.js

@@ -0,0 +1,101 @@
+// Is the replacement a drop-in, or does moving to it need more than a new model name?
+// Rules per model family, written from the providers' own migration docs (checked 13 Nov 2026).
+// Anything no rule matches is a plain rename, which is how Driftline has always presented it.
+//
+// migrationFor(entry) → { change, drop_in, note, guide }
+//   change: "rename"   the model name is the only change
+//           "settings" also set a parameter the provider names (e.g. reasoning.mode: pro)
+//           "params"   some request parameters are removed or renamed
+//           "api"      a different API, method or endpoint
+//           "re-embed" stored embeddings have to be recomputed
+//           "choose"   the provider names more than one replacement; which one depends on how you use it
+
+const OPENAI = "https://developers.openai.com/api/docs/guides/";
+const GOOGLE = "https://ai.google.dev/gemini-api/docs/";
+
+// Claude family version from an ID: claude-sonnet-4-5-20250929 → 4.5, claude-3-haiku-20240307 → 3, claude-opus-4-8 → 4.8
+function claudeVersion(id) {
+  const m = String(id || "").match(/^claude-(?:(?:opus|sonnet|haiku|fable|mythos)-)?(\d+)(?:[-.](\d))?(?:-|$)/);
+  return m ? Number(m[1]) + (m[2] ? Number(m[2]) / 10 : 0) : null;
+}
+const geminiMajor = (id) => { const m = String(id || "").match(/^gemini-(\d+)/); return m ? Number(m[1]) : null; };
+
+const RULES = [
+  {
+    when: (e) => e.provider === "openai" && (/^(davinci-002|babbage-002|gpt-3\.5-turbo-instruct)/.test(e.id) || /-completions$/.test(e.id)),
+    change: "api",
+    note: "The old Completions endpoint (a plain prompt) doesn't serve the replacement: move the call to the Responses API or Chat Completions (messages).",
+    guide: OPENAI + "migrate-to-responses",
+  },
+  {
+    when: (e) => e.provider === "openai" && /^(tts-1|gpt-4o-mini-tts)/.test(e.id),
+    change: "api",
+    note: "OpenAI calls this a change of API workflow: the replacement isn't a model for /v1/audio/speech and runs through the Realtime API.",
+    guide: OPENAI + "text-to-speech",
+  },
+  {
+    when: (e) => e.provider === "openai" && /realtime-preview/.test(e.id),
+    change: "api",
+    note: "The preview models ran on the Realtime beta (header OpenAI-Beta: realtime=v1), which OpenAI shut down; the replacement needs the current Realtime API.",
+    guide: OPENAI + "realtime",
+  },
+  {
+    when: (e) => e.provider === "openai" && /^(whisper-1|gpt-4o(-mini)?-transcribe)/.test(e.id),
+    change: "choose",
+    note: "OpenAI names two replacements: gpt-transcribe for recorded files, gpt-live-transcribe for live audio. Word timestamps, subtitles and translation work differently, so check those if you use them.",
+    guide: OPENAI + "transcription",
+  },
+  {
+    when: (e) => e.provider === "openai" && e.kind === "image" && /-sunburst$/.test(e.replacement || ""),
+    change: "rename",
+    note: "Same Images API. OpenAI offers two: …-sunburst for editing precision, …-flare for fast everyday generation.",
+    guide: OPENAI + "image-generation",
+  },
+  {
+    when: (e) => e.kind === "embedding",
+    change: "re-embed",
+    note: "Embeddings from different models can't be compared: re-embed your stored data with the new model, and query with that same model. The vector size may differ too.",
+    guide: (e) => e.provider === "google" ? GOOGLE + "embeddings" : OPENAI + "embeddings",
+  },
+  {
+    when: (e) => e.provider === "google" && /^imagen-/.test(e.id),
+    change: "api",
+    note: "Use generate_content instead of generate_images; images come back as content parts, not an image response object.",
+    guide: GOOGLE + "imagen",
+  },
+  {
+    when: (e) => e.provider === "google" && /^veo-/.test(e.id),
+    change: "api",
+    note: "Gemini Omni Flash uses the Interactions API (interactions.create), not Veo's video-generation call. Google also offers Veo itself on Gemini Enterprise Agent Platform.",
+    guide: GOOGLE + "video",
+  },
+  {
+    when: (e) => e.provider === "google" && (!e.kind || e.kind === "text") && geminiMajor(e.id) === 2 && geminiMajor(e.replacement) >= 3,
+    change: "params",
+    note: "Gemini 3 changes the request: remove temperature, top_p, top_k, candidate_count and prefilled model turns, replace thinking_budget with thinking_level, and check function calling.",
+    guide: (e) => GOOGLE + (/^gemini-3\.8/.test(e.replacement) ? "whats-new-gemini-3.8" : "whats-new-gemini-3.6"),
+  },
+  {
+    when: (e) => e.provider === "anthropic" && claudeVersion(e.id) !== null && claudeVersion(e.id) < 4.7 && claudeVersion(e.replacement) >= 4.7,
+    change: "params",
+    note: "Claude 4.7 and later accept only the default temperature, top_p and top_k: if your code sets them, remove them.",
+    guide: "https://platform.claude.com/docs/en/api/migration-2026-10-21",
+  },
+];
+
+export function migrationFor(entry) {
+  if (!entry?.replacement) return null;
+  // A provider's own instruction next to the replacement (registry replacement_note) comes first.
+  const setting = entry.replacement_note
+    ? { change: "settings", drop_in: false, note: `Also set ${entry.replacement_note}.`, guide: /reasoning\.mode/.test(entry.replacement_note) ? OPENAI + "reasoning" : null }
+    : null;
+  const rule = RULES.find((r) => r.when(entry));
+  if (!rule) return setting || { change: "rename", drop_in: true, note: "", guide: null };
+  const found = { change: rule.change, drop_in: rule.change === "rename", note: rule.note, guide: typeof rule.guide === "function" ? rule.guide(entry) : rule.guide };
+  return setting ? { ...found, change: found.change === "rename" ? "settings" : found.change, drop_in: false, note: `${setting.note} ${found.note}` } : found;
+}
+
+// Short label for tables: "Rename" or what else is needed.
+export const MIGRATION_LABEL = {
+  rename: "Rename", settings: "Rename + setting", params: "Parameter changes", api: "API change", "re-embed": "Re-embed data", choose: "Pick one of two",
+};

package/src/providers.js

@@ -63,7 +63,7 @@ async function postOnce(fetchImpl, url, headers, body) {
   return json;
 }
 
-export async function complete({ model, prompt, system, env = process.env, fetchImpl = fetch }) {
+export async function complete({ model, prompt, system, reasoningMode = null, env = process.env, fetchImpl = fetch }) {
   const provider = providerOf(model);
   const key = keyFor(provider, env);
   if (!key) throw new Error(missingKeyMessage(provider));
@@ -71,7 +71,7 @@ export async function complete({ model, prompt, system, env = process.env, fetch
   if (provider === "openai") {
     const data = await postJson(fetchImpl, "https://api.openai.com/v1/responses",
       { authorization: `Bearer ${key}` },
-      { model, input: prompt, ...(system ? { instructions: system } : {}) });
+      { model, input: prompt, ...(system ? { instructions: system } : {}), ...(reasoningMode ? { reasoning: { mode: reasoningMode } } : {}) });
     const text = typeof data.output_text === "string" ? data.output_text : (data.output || [])
       .flatMap((o) => o.content || [])
       .filter((c) => c.type === "output_text" || typeof c.text === "string")

package/src/registry.js

@@ -11,6 +11,26 @@ export function loadRegistry(path = REGISTRY_PATH) {
   return buildRegistry(JSON.parse(readFileSync(path, "utf8")));
 }
 
+// The live registry is updated as soon as a provider changes a date or replacement; the copy bundled with a
+// release can be days or weeks old. Everything (Action, CLI, MCP) uses the live copy when it can be read, looks
+// like ours and is at least as new as the bundled one; otherwise the bundled copy. reg.source says which.
+export const LIVE_URL = "https://aidriftline.com/models.json";
+export function validRegistry(data) {
+  return Array.isArray(data?.models) && data.models.length >= 50 && /^\d{4}-\d{2}-\d{2}$/.test(data.checked || "") &&
+    data.models.every((m) => typeof m?.id === "string" && ["openai", "anthropic", "google"].includes(m.provider) && /^\d{4}-\d{2}-\d{2}$/.test(m.retires || ""));
+}
+export async function loadBestRegistry({ fetchImpl = fetch, offline = process.env.DRIFTLINE_OFFLINE === "1", timeoutMs = 4000 } = {}) {
+  const bundled = JSON.parse(readFileSync(REGISTRY_PATH, "utf8"));
+  const use = (data, source, why = "") => { const reg = buildRegistry(data); reg.source = source; reg.sourceWhy = why; return { reg, source, why }; };
+  if (offline) return use(bundled, "bundled", "offline");
+  try {
+    const res = await fetchImpl(LIVE_URL, { signal: AbortSignal.timeout(timeoutMs) });
+    const live = res.ok ? await res.json() : null;
+    if (validRegistry(live)) return live.checked >= bundled.checked ? use(live, "live") : use(bundled, "bundled", "newer");
+  } catch { /* offline, slow or malformed: use the bundled copy */ }
+  return use(bundled, "bundled", "unreachable");
+}
+
 // Same as loadRegistry, from already-parsed JSON (e.g. the live copy at aidriftline.com/models.json).
 export function buildRegistry(data) {
   const byId = new Map(data.models.map((m) => [m.id, { ...m }]));
@@ -72,6 +92,20 @@ export function looksLikeModelId(id, known) {
 // Only text models can be drift-tested; audio, image, video, embedding and the rest are scan-only.
 export const isTextModel = (entry) => !entry?.kind || entry.kind === "text";
 
+// The replacement as people should read it: the model, plus the provider's extra instruction when there is one,
+// e.g. "gpt-6.1-sol (reasoning.mode: pro, in the Responses API)". Without the note, a rename alone is not the move.
+export const replacementText = (entry) => entry?.replacement
+  ? entry.replacement + (entry.replacement_note ? ` (${entry.replacement_note})` : "") : "";
+
+// Providers sometimes change the recommended replacement after announcing a retirement. The registry keeps
+// the old one and the date we saw the change, so reports can say so instead of silently switching targets.
+export const RECENT_CHANGE_DAYS = 120;
+export function replacementChange(entry, today = new Date()) {
+  if (!entry?.replacement_changed || !entry.previous_replacement) return null;
+  const days = Math.floor((today - new Date(entry.replacement_changed + "T00:00:00Z")) / DAY);
+  return days >= 0 && days <= RECENT_CHANGE_DAYS ? { on: entry.replacement_changed, was: entry.previous_replacement, days } : null;
+}
+
 /**
  * Classify one model ID against the registry on a given date.
  * status: retired | at-risk | deprecated | active | unknown

package/src/report.js

@@ -1,3 +1,6 @@
+import { replacementChange } from "./registry.js";
+import { migrationFor, MIGRATION_LABEL } from "./migration.js";
+
 const STATUS_LABEL = {
   retired: "🔴 Retired",
   "at-risk": "🟠 Retires soon",
@@ -7,6 +10,9 @@ const STATUS_LABEL = {
 };
 const RESULT_LABEL = { same: "✅ Same", changed: "🟡 Changed", broken: "🔴 Broken", error: "⚠️ Error", skipped: "⏭️ Skipped" };
 
+// "<br>changed 2026-11-13, was `gpt-5.6-sol`" when the provider changed its advice recently.
+const changed = (entry, today) => { const c = replacementChange(entry, today); return c ? `<br>_changed ${c.on}, was ${code(c.was)}_` : ""; };
+
 // Google gives only earliest dates; once one has passed the model may be gone already, so "retires soon" would be wrong.
 // Routed models keep answering after the date, but from the replacement model ("retired" would be wrong too).
 const label = (c) => c.status === "at-risk" && c.entry?.qualifier === "earliest" && c.days <= 0
@@ -43,7 +49,7 @@ const MAX_ANSWER = 1500;
 const MAX_ROWS = 150;
 const clip = (s) => { s = String(s || ""); return s.length > MAX_ANSWER ? s.slice(0, MAX_ANSWER) + "\n[…cut]" : s; };
 
-export function renderReport({ findings, drift, registry, notices = [], answers = true }) {
+export function renderReport({ findings, drift, registry, notices = [], answers = true, today = new Date() }) {
   const lines = ["## Driftline report", ""];
   const flagged = findings.filter((f) => ["retired", "at-risk", "deprecated"].includes(f.status));
   const byModel = new Map();
@@ -60,16 +66,30 @@ export function renderReport({ findings, drift, registry, notices = [], answers
     lines.push(n
       ? `**${n} reference${n === 1 ? "" : "s"} to retired or retiring models** across ${byModel.size} model ID${byModel.size === 1 ? "" : "s"} found.`
       : `Found ${byModel.size} model ID${byModel.size === 1 ? "" : "s"}. None are scheduled for retirement.`);
-    lines.push("", "| Model | Status | Retirement | Replacement | Where |", "|---|---|---|---|---|");
+    lines.push("", "| Model | Status | Retirement | Replacement | Change needed | Where |", "|---|---|---|---|---|---|");
+    const migNotes = new Map(); // note → { n, ids, guide } for the list under the table
     const order = ["retired", "at-risk", "deprecated", "active", "unknown"];
     const all = [...byModel.values()].sort((a, b) => order.indexOf(a.status) - order.indexOf(b.status));
     const rows = all.slice(0, MAX_ROWS); // flagged models sort first, so only unknown/active rows get cut
     for (const r of rows) {
+      const mig = migrationFor(r.entry);
+      let changeCell = "";
+      if (mig) {
+        if (mig.note && !(mig.change === "settings" && r.entry.replacement_note && mig.note === `Also set ${r.entry.replacement_note}.`)) {
+          if (!migNotes.has(mig.note)) migNotes.set(mig.note, { n: migNotes.size + 1, ids: [], guide: mig.guide });
+          migNotes.get(mig.note).ids.push(r.id);
+          changeCell = `${mig.drop_in ? "✅" : "⚠️"} ${MIGRATION_LABEL[mig.change]} [${migNotes.get(mig.note).n}]`;
+        } else changeCell = `${mig.drop_in ? "✅" : "⚠️"} ${MIGRATION_LABEL[mig.change]}`;
+      }
       const places = r.places.slice(0, 3).join(", ") + (r.places.length > 3 ? ` +${r.places.length - 3} more` : "");
       const docsOnly = r.places.length && byModel.get(r.id).docs === r.places.length ? " · docs only" : "";
-      lines.push(`| ${code(r.id)}${r.entry?.aliasOf ? " · alias of " + code(r.entry.aliasOf) : ""}${r.entry?.kind && r.entry.kind !== "text" ? " · " + r.entry.kind : ""} | ${label(r)}${docsOnly} | ${esc(when(r))} | ${r.entry?.replacement ? code(r.entry.replacement) : ""} | ${places} |`);
+      lines.push(`| ${code(r.id)}${r.entry?.aliasOf ? " · alias of " + code(r.entry.aliasOf) : ""}${r.entry?.kind && r.entry.kind !== "text" ? " · " + r.entry.kind : ""} | ${label(r)}${docsOnly} | ${esc(when(r))} | ${r.entry?.replacement ? code(r.entry.replacement) + (r.entry.replacement_note ? " (" + esc(r.entry.replacement_note) + ")" : "") + changed(r.entry, today) : ""} | ${changeCell} | ${places} |`);
     }
     if (all.length > rows.length) lines.push("", `_${all.length - rows.length} more model ID(s) with no retirement listed are not shown._`);
+    if (migNotes.size) {
+      lines.push("", "**More than a rename:**", "");
+      for (const [note, m] of migNotes) lines.push(`${m.n}. ${m.ids.map(code).join(", ")}: ${esc(note)}${m.guide ? ` ([provider guide](${m.guide}))` : ""}`);
+    }
   }
 
   if (drift?.length) {
@@ -96,7 +116,7 @@ export function renderReport({ findings, drift, registry, notices = [], answers
   }
 
   if (notices.length) lines.push("", ...notices.map((n) => `> ${n}`));
-  lines.push("", `<sub>Retirement dates checked against official provider pages on ${registry.checked}. ` +
+  lines.push("", `<sub>Retirement dates checked against official provider pages on ${registry.checked}${registry.source === "live" ? " (live list at aidriftline.com)" : ({ newer: " (list bundled with this version, newer than the live list)", unreachable: " (list bundled with this version; the live list could not be read)", offline: " (list bundled with this version)" })[registry.sourceWhy] || ""}. ` +
     `Sources: [OpenAI](${registry.sources.openai}) · [Anthropic](${registry.sources.anthropic}) · [Google](${registry.sources.google}).</sub>`);
   return lines.join("\n");
 }

package/src/run.js

@@ -1,12 +1,13 @@
 import { existsSync } from "node:fs";
 import { join, relative, sep } from "node:path";
-import { loadRegistry, classify, isTextModel } from "./registry.js";
+import { loadRegistry, classify, isTextModel, replacementChange } from "./registry.js";
 import { scanDirectory } from "./scan.js";
 import { loadPrompts } from "./prompts.js";
 import { complete, providerOf, keyFor, missingKeyMessage } from "./providers.js";
 import { compare, extractJson } from "./compare.js";
 import { checkLicense } from "./license.js";
 import { renderReport } from "./report.js";
+import { migrationFor } from "./migration.js";
 
 const MAX_PROMPTS = 20;
 const oneLine = (s) => String(s).replace(/[\r\n]+/g, " ");
@@ -61,9 +62,9 @@ export async function run({
   }
 
   const atRisk = findings.filter((f) => !f.doc && (f.status === "retired" || f.status === "at-risk")).length;
-  const markdown = renderReport({ findings, drift, registry, notices, answers });
+  const markdown = renderReport({ findings, drift, registry, notices, answers, today });
   // The issue never carries model answers: in a public repository anyone can read it.
-  const issueMarkdown = renderReport({ findings, drift, registry, notices, answers: false });
+  const issueMarkdown = renderReport({ findings, drift, registry, notices, answers: false, today });
   return { findings, drift, notices, atRisk, markdown, issueMarkdown };
 }
 
@@ -92,25 +93,39 @@ async function runDrift({ prompts, findings, registry, env, fetchImpl, today, wa
     for (const from of froms) {
       const status = classify(from, registry, { today, warnDays });
       const to = p.compare_to || status.entry?.replacement;
+      // The provider's replacement comes with an extra instruction (e.g. "reasoning.mode: pro") that this test
+      // doesn't apply: say so on every row, so nobody reads a plain-mode answer as the replacement's best.
+      const chg = !p.compare_to && replacementChange(status.entry, today);
+      // The provider says the replacement runs in a mode (e.g. reasoning.mode: pro): test it that way, as the customer would run it.
+      const proMode = !p.compare_to && /reasoning\.mode: pro/.test(status.entry?.replacement_note || "") && providerOf(to) === "openai" ? "pro" : null;
+      const mig = !p.compare_to ? migrationFor(status.entry) : null;
+      const caveat = [
+        proMode ? "Replacement tested with reasoning.mode: pro, as the provider recommends." : "",
+        !p.compare_to && !proMode && status.entry?.replacement_note
+          ? `Tested without "${status.entry.replacement_note}", which the provider says the replacement needs; answers after a correct switch may differ.` : "",
+        mig && !mig.drop_in && mig.change !== "settings" ? `Beyond the model name: ${mig.note}` : "",
+        chg ? `The provider changed this replacement on ${chg.on} (before: ${chg.was}); drift results from earlier runs compared against ${chg.was}.` : "",
+      ].filter(Boolean).join(" ");
+      const push = (row) => out.push(caveat ? { ...row, note: [row.note, caveat].filter(Boolean).join(" ") } : row);
       if (!to) {
-        out.push({ id: p.id, from, to: "—", result: "skipped", note: "No known replacement; set compare_to" });
+        push({ id: p.id, from, to: "—", result: "skipped", note: "No known replacement; set compare_to" });
         continue;
       }
       const missing = [from, to].map(providerOf).find((pr) => !keyFor(pr, env));
       if (missing) {
-        out.push({ id: p.id, from, to, result: "error", note: missingKeyMessage(missing) });
+        push({ id: p.id, from, to, result: "error", note: missingKeyMessage(missing) });
         continue;
       }
       log(oneLine(`Drift test ${p.id}: ${from} → ${to}`));
       try {
-        const after = await complete({ model: to, prompt: p.prompt, system: p.system, env, fetchImpl });
+        const after = await complete({ model: to, prompt: p.prompt, system: p.system, reasoningMode: proMode, env, fetchImpl });
         if (status.status === "retired") {
           if (!after.trim()) {
-            out.push({ id: p.id, from, to, after, before: "(current model already retired)", result: "broken", note: "Replacement returned an empty answer" });
+            push({ id: p.id, from, to, after, before: "(current model already retired)", result: "broken", note: "Replacement returned an empty answer" });
             continue;
           }
           const jsonOk = p.expect !== "json" || extractJson(after).ok;
-          out.push({ id: p.id, from, to, after, before: "(current model already retired)", result: jsonOk ? "changed" : "broken",
+          push({ id: p.id, from, to, after, before: "(current model already retired)", result: jsonOk ? "changed" : "broken",
             note: jsonOk ? "Current model is retired; review the replacement's answer" : "Replacement did not return valid JSON" });
           continue;
         }
@@ -120,12 +135,12 @@ async function runDrift({ prompts, findings, registry, env, fetchImpl, today, wa
         } catch (e) {
           if (!/^(Empty answer|Answer cut off)/.test(e.message)) throw e;
           // The current model gave nothing usable; the replacement's answer is still worth showing.
-          out.push({ id: p.id, from, to, after, before: `(${e.message})`, result: "changed", note: `Current model: ${e.message}. Review the replacement's answer` });
+          push({ id: p.id, from, to, after, before: `(${e.message})`, result: "changed", note: `Current model: ${e.message}. Review the replacement's answer` });
           continue;
         }
-        out.push({ id: p.id, from, to, before, after, ...compare(before, after, p.expect) });
+        push({ id: p.id, from, to, before, after, ...compare(before, after, p.expect) });
       } catch (e) {
-        out.push({ id: p.id, from, to, result: "error", note: e.message.slice(0, 200) });
+        push({ id: p.id, from, to, result: "error", note: e.message.slice(0, 200) });
       }
     }
   }