modelalive 0.5.0 → 1.0.2

package/dist/index.d.ts

@@ -5,8 +5,20 @@ export declare function check(model: string, opts?: {
     today?: Date;
 }): AliveResult;
 export declare function resolve(model: string, today?: Date): string;
+export interface ResolveDetail {
+    queried_model: string;
+    resolved: string;
+    chain: string[];
+    breaking_changes: string[];
+}
+export declare function resolveDetail(model: string, today?: Date): ResolveDetail;
 export declare function ensure(model: string, opts?: {
     strictUnknown?: boolean;
     today?: Date;
 }): string;
+export declare function gate<T>(model: string, fn: (safeModel: string) => T, opts?: {
+    strictUnknown?: boolean;
+    today?: Date;
+}): T;
 export * from "./types.js";
+export { normalizeModel } from "./normalize.js";

package/dist/index.js

@@ -1,8 +1,10 @@
 import { daysUntil, effectiveStatus, loadRegistry, resolveAlias, } from "./registry.js";
+import { normalizeModel } from "./normalize.js";
 import { ModelRetiredError, ModelUnknownError } from "./types.js";
+const MAX_DEPTH = 12;
 export function alive(model, today = new Date()) {
     const registry = loadRegistry();
-    const queried = model.trim();
+    const queried = normalizeModel(model);
     const [canonical, aliased] = resolveAlias(queried, registry);
     const entry = registry.models[canonical];
     if (!entry) {
@@ -63,24 +65,60 @@ export function check(model, opts = {}) {
     return result;
 }
 export function resolve(model, today = new Date()) {
-    let current = model.trim();
+    return resolveDetail(model, today).resolved;
+}
+export function resolveDetail(model, today = new Date()) {
+    let current = normalizeModel(model);
     const visited = new Set();
-    for (let i = 0; i < 12; i++) {
+    const chain = [];
+    const breakingChanges = [];
+    for (let i = 0; i < MAX_DEPTH; i++) {
         if (visited.has(current))
             break;
         visited.add(current);
+        chain.push(current);
         const result = alive(current, today);
+        for (const change of result.breaking_changes ?? []) {
+            if (!breakingChanges.includes(change))
+                breakingChanges.push(change);
+        }
         if (result.status === "active" || result.status === "unknown") {
-            return result.canonical_model ?? current;
+            return {
+                queried_model: model,
+                resolved: result.canonical_model ?? current,
+                chain,
+                breaking_changes: breakingChanges,
+            };
+        }
+        if (!result.replacement) {
+            return {
+                queried_model: model,
+                resolved: result.canonical_model ?? current,
+                chain,
+                breaking_changes: breakingChanges,
+            };
         }
-        if (!result.replacement)
-            return result.canonical_model ?? current;
         const repl = alive(result.replacement, today);
-        if (repl.status === "active")
-            return result.replacement;
+        if (repl.status === "active") {
+            for (const change of repl.breaking_changes ?? []) {
+                if (!breakingChanges.includes(change))
+                    breakingChanges.push(change);
+            }
+            return {
+                queried_model: model,
+                resolved: result.replacement,
+                chain: [...chain, result.replacement],
+                breaking_changes: breakingChanges,
+            };
+        }
         current = result.replacement;
     }
-    return current;
+    return {
+        queried_model: model,
+        resolved: current,
+        chain,
+        breaking_changes: breakingChanges,
+    };
 }
 export function ensure(model, opts = {}) {
     const result = alive(model, opts.today);
@@ -92,4 +130,8 @@ export function ensure(model, opts = {}) {
     }
     return resolve(model, opts.today);
 }
+export function gate(model, fn, opts = {}) {
+    return fn(ensure(model, opts));
+}
 export * from "./types.js";
+export { normalizeModel } from "./normalize.js";

package/dist/normalize.d.ts

@@ -0,0 +1 @@
+export declare function normalizeModel(model: string): string;

package/dist/normalize.js

@@ -0,0 +1,17 @@
+const MODEL_ID_PATTERN = /^[a-zA-Z0-9][a-zA-Z0-9._:/-]{0,200}$/;
+const FINE_TUNED_PREFIX = /^ft:([^:]+(?::[^:]+)*)/;
+export function normalizeModel(model) {
+    let cleaned = model.trim();
+    if (!cleaned)
+        throw new Error("Model ID cannot be empty");
+    const ftMatch = FINE_TUNED_PREFIX.exec(cleaned);
+    if (ftMatch) {
+        const base = ftMatch[1].split(":")[0];
+        if (base)
+            cleaned = base;
+    }
+    if (!MODEL_ID_PATTERN.test(cleaned)) {
+        throw new Error(`Invalid model ID format: ${model}`);
+    }
+    return cleaned;
+}

package/dist/smoke.test.js

@@ -1,7 +1,14 @@
 import assert from "node:assert/strict";
-import { alive, ensure, resolve } from "./index.js";
+import { alive, ensure, gate, normalizeModel, resolve, resolveDetail, } from "./index.js";
 assert.equal(alive("claude-sonnet-4-20250514").status, "retired");
 assert.equal(resolve("claude-sonnet-4-20250514"), "claude-sonnet-4-6");
 assert.equal(ensure("claude-sonnet-4-20250514"), "claude-sonnet-4-6");
 assert.equal(alive("claude-sonnet-4-6").status, "active");
+const detail = resolveDetail("claude-opus-4-20250514");
+assert.equal(detail.resolved, "claude-opus-4-8");
+assert.ok(detail.breaking_changes.length >= 1);
+assert.equal(normalizeModel("ft:gpt-4o-mini:org:foo:bar"), "gpt-4o-mini");
+assert.equal(alive("anthropic.claude-sonnet-4-6-v1:0").canonical_model, "claude-sonnet-4-6");
+const gated = gate("gemini-2.0-flash", (safe) => safe);
+assert.equal(gated, "gemini-3.5-flash");
 console.log("modelalive js: ok");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "modelalive",
-  "version": "0.5.0",
+  "version": "1.0.2",
   "description": "Pre-flight check: is this LLM model ID still alive?",
   "type": "module",
   "main": "dist/index.js",