@nvae/llmswitch 1.0.0 → 1.3.0

package/dist/gateway/rate-limit.js

@@ -13,10 +13,10 @@
  *    blocked: a slightly loose limit is preferable to stalling live traffic on
  *    lock contention.
  */
-import { existsSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
-import { randomBytes } from "node:crypto";
+import { existsSync, readFileSync, rmSync } from "node:fs";
 import { join } from "node:path";
 import { atomicWriteFile, ensureDir } from "../utils/fs.js";
+import { acquireFileLock, } from "../utils/file-lock.js";
 import { getGatewayDir } from "../utils/paths.js";
 const WINDOW_MS = 60_000;
 const DAY_MS = 86_400_000;
@@ -36,112 +36,16 @@ const UNLIMITED = {
     resetAt: 0,
     retryAfterSeconds: 0,
 };
-function sleepSync(ms) {
-    const shared = new Int32Array(new SharedArrayBuffer(4));
-    Atomics.wait(shared, 0, 0, ms);
-}
-function pidAlive(pid) {
-    if (!Number.isInteger(pid) || pid < 1)
-        return false;
-    try {
-        process.kill(pid, 0);
-        return true;
-    }
-    catch (err) {
-        return err.code === "EPERM";
-    }
-}
 /**
  * Acquire the counter lock, or return null when it stays busy past the timeout.
- * A lock whose owner process is gone and which is older than the stale age is
- * reclaimed.
+ * Shared implementation with the usage accounting file (see utils/file-lock).
  */
 function acquireLock(now) {
-    const path = getRateLimitLockPath();
-    const id = randomBytes(8).toString("hex");
-    const payload = JSON.stringify({ id, pid: process.pid, at: now });
-    const deadline = now + LOCK_TIMEOUT_MS;
-    // The directory may not exist yet on a fresh install; without this the
-    // exclusive create below fails with ENOENT and persistence never engages.
-    try {
-        ensureDir(getGatewayDir());
-    }
-    catch {
-        return null;
-    }
-    for (;;) {
-        try {
-            writeFileSync(path, payload, { encoding: "utf8", flag: "wx", mode: 0o600 });
-            return makeLock(path, id);
-        }
-        catch (err) {
-            if (err.code !== "EEXIST")
-                return null;
-        }
-        if (reclaimable(path)) {
-            try {
-                const tmp = `${path}.${id}.tmp`;
-                writeFileSync(tmp, payload, { encoding: "utf8", mode: 0o600 });
-                renameSync(tmp, path);
-                if (readLockId(path) === id)
-                    return makeLock(path, id);
-            }
-            catch {
-                // Someone else won the race; fall through and retry.
-            }
-        }
-        if (Date.now() >= deadline)
-            return null;
-        sleepSync(LOCK_SPIN_MS);
-    }
-}
-function readLockId(path) {
-    try {
-        const raw = JSON.parse(readFileSync(path, "utf8"));
-        return typeof raw.id === "string" ? raw.id : null;
-    }
-    catch {
-        return null;
-    }
-}
-/**
- * A lock is reclaimable when its owner is gone. A dead owner can never release
- * the lock, so that case is reclaimed immediately; when ownership cannot be
- * determined we fall back to an age check that trusts whichever of the file
- * mtime or the recorded timestamp looks older.
- */
-function reclaimable(path) {
-    let record = {};
-    let readable = false;
-    try {
-        record = JSON.parse(readFileSync(path, "utf8"));
-        readable = true;
-    }
-    catch {
-        // Unreadable lock file: fall back to the age check below.
-    }
-    if (readable && typeof record.pid === "number") {
-        return !pidAlive(record.pid);
-    }
-    let fileAge = Number.POSITIVE_INFINITY;
-    try {
-        fileAge = Date.now() - statSync(path).mtimeMs;
-    }
-    catch {
-        return true;
-    }
-    const recordedAge = typeof record.at === "number"
-        ? Date.now() - record.at
-        : Number.NEGATIVE_INFINITY;
-    return Math.max(fileAge, recordedAge) > LOCK_STALE_MS;
-}
-function makeLock(path, id) {
-    return {
-        release() {
-            if (readLockId(path) === id)
-                rmSync(path, { force: true });
-        },
-    };
+    return acquireFileLock(getRateLimitLockPath(), {
+        timeoutMs: LOCK_TIMEOUT_MS,
+        staleMs: LOCK_STALE_MS,
+        spinMs: LOCK_SPIN_MS,
+    }, now);
 }
 function readWindows() {
     const path = getRateLimitPath();

package/dist/gateway/router.js

@@ -43,7 +43,13 @@ function providerHasModel(provider, model) {
     return provider.models.some((item) => item.toLowerCase() === wanted);
 }
 /** Split `provider/model` or `provider:model`; the model part may contain `/`. */
-function splitQualified(requested) {
+/**
+ * Split `provider/model` or `provider:model`. Exported so the CLI parses
+ * `--fallback` with exactly the same rules the router uses to resolve a
+ * requested model id — otherwise `provider:model` written as a fallback would be
+ * silently taken as a whole provider name.
+ */
+export function splitQualified(requested) {
     for (const separator of ["/", ":"]) {
         const index = requested.indexOf(separator);
         if (index <= 0)

package/dist/gateway/server.js

@@ -7,7 +7,7 @@
  * translated between formats as needed.
  */
 import { createServer, } from "node:http";
-import { parseBridgeRuntimeLimits } from "../bridge/runtime.js";
+import { ConcurrencyGate, parseBridgeRuntimeLimits, } from "../bridge/runtime.js";
 import { randomBytes } from "node:crypto";
 import { requestWithNodeTransport, } from "../bridge/transport.js";
 import { authenticateGatewayKey, keyAllowsTarget, listGatewayKeys, touchGatewayKey, } from "./keys.js";
@@ -292,27 +292,6 @@ function applyCors(req, res, config) {
     res.setHeader("Access-Control-Allow-Methods", "GET, POST, OPTIONS");
     res.setHeader("Access-Control-Max-Age", "600");
 }
-/** Bounded in-flight request counter shared by all data-plane endpoints. */
-class ConcurrencyGate {
-    max;
-    active = 0;
-    constructor(max) {
-        this.max = max;
-    }
-    get inFlight() {
-        return this.active;
-    }
-    tryAcquire() {
-        if (this.active >= this.max)
-            return false;
-        this.active += 1;
-        return true;
-    }
-    release() {
-        if (this.active > 0)
-            this.active -= 1;
-    }
-}
 export function createGatewayServer(options = {}) {
     const limits = parseBridgeRuntimeLimits();
     const gate = new ConcurrencyGate(limits.maxConcurrency);

package/dist/gateway/store.js

@@ -5,7 +5,7 @@
  * tool (claude/codex/opencode), so the same upstream can exist three times with
  * different names. The gateway needs one tool-independent provider list.
  */
-import { existsSync, readdirSync, readFileSync, unlinkSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync, statSync, unlinkSync, } from "node:fs";
 import { chmodSync } from "node:fs";
 import { TOOLS, isApiFormat, normalizeProxyValue } from "../types.js";
 import { ensureOpenAiV1BaseUrl, isOpenAiApiFormat } from "../utils/base-url.js";
@@ -101,10 +101,39 @@ function normalizeProvider(raw, fallbackName) {
             : new Date(0).toISOString(),
     };
 }
+/**
+ * Provider list cache.
+ *
+ * The gateway data plane reads the provider list on every request (routing,
+ * /v1/models, key scoping), and each read scanned the directory and JSON-parsed
+ * every file. Invalidation is by directory mtime plus a short TTL, so an edit
+ * from another process is still picked up within a second.
+ */
+const PROVIDER_CACHE_TTL_MS = 1_000;
+let providerCache = null;
+/** Drop the cache after any write (same process). */
+export function invalidateGatewayProviderCache() {
+    providerCache = null;
+}
 export function listGatewayProviders() {
     const dir = getGatewayProvidersDir();
     if (!existsSync(dir))
         return [];
+    let dirMtimeMs = 0;
+    try {
+        dirMtimeMs = statSync(dir).mtimeMs;
+    }
+    catch {
+        dirMtimeMs = 0;
+    }
+    const now = Date.now();
+    if (providerCache &&
+        // 目录路径也要比对：LLM_SWITCH_HOME 变了（测试、多配置目录）就必须重读。
+        providerCache.dir === dir &&
+        providerCache.dirMtimeMs === dirMtimeMs &&
+        now - providerCache.at < PROVIDER_CACHE_TTL_MS) {
+        return providerCache.value;
+    }
     const out = [];
     for (const file of readdirSync(dir)) {
         if (!file.endsWith(".json"))
@@ -114,7 +143,9 @@ export function listGatewayProviders() {
         if (provider)
             out.push(provider);
     }
-    return out.sort((a, b) => a.priority - b.priority || a.name.localeCompare(b.name));
+    const sorted = out.sort((a, b) => a.priority - b.priority || a.name.localeCompare(b.name));
+    providerCache = { at: now, dir, dirMtimeMs, value: sorted };
+    return sorted;
 }
 export function readGatewayProvider(name) {
     const path = getGatewayProviderPath(name);
@@ -164,6 +195,7 @@ export function saveGatewayProvider(provider) {
     ensureGatewayDir();
     ensureDir(getGatewayProvidersDir());
     atomicWriteFile(getGatewayProviderPath(next.name), JSON.stringify(next, null, 2) + "\n");
+    invalidateGatewayProviderCache();
     return next;
 }
 export function deleteGatewayProvider(name) {
@@ -172,6 +204,7 @@ export function deleteGatewayProvider(name) {
         throw new Error(`未找到 gateway provider「${name}」`);
     }
     unlinkSync(path);
+    invalidateGatewayProviderCache();
     // Drop routes that pointed at the removed provider.
     const routes = listGatewayRoutes().filter((route) => {
         if (route.provider === name)
@@ -228,9 +261,9 @@ export function importProvidersFromProfiles(tools = TOOLS) {
             }
             const models = Array.from(new Set([
                 profile.models.default,
-                profile.models.fast,
+                profile.models.smallModel,
                 ...(profile.models.list || []),
-            ].filter((m) => Boolean(m && m.trim()))));
+            ].filter((m) => Boolean(m?.trim()))));
             const provider = saveGatewayProvider({
                 name,
                 displayName: profile.displayName || name,

package/dist/gateway/usage.js

@@ -2,13 +2,19 @@
  * Per-day usage accounting for the gateway data plane.
  *
  * One JSON file with daily buckets; each row aggregates requests and token
- * counts for a (key, provider, model) triple. Writes are read-modify-write via
- * the same atomic-replace pattern as the rest of the store — the daemon is the
- * single writer in practice, so no lock is taken and a crashed process can lose
- * at most the in-flight update.
+ * counts for a (key, provider, model) triple.
+ *
+ * The read-modify-write runs under the same kind of advisory file lock as the
+ * rate-limit counters. A foreground `gateway serve` and a daemon can be up at
+ * the same time (both record usage), and since each write atomically replaces
+ * the whole file, an unlocked update would silently discard the other process's
+ * accounting. Losing the lock race degrades to "skip this record" rather than
+ * blocking a live request.
  */
 import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
 import { atomicWriteFile, ensureDir } from "../utils/fs.js";
+import { acquireFileLock } from "../utils/file-lock.js";
 import { getGatewayDir, getGatewayUsagePath } from "../utils/paths.js";
 const RETENTION_DAYS = 90;
 function emptyFile() {
@@ -28,6 +34,9 @@ function nonNegativeNumber(value) {
 export function getUsagePath() {
     return getGatewayUsagePath();
 }
+export function getUsageLockPath() {
+    return join(getGatewayDir(), "usage.lock");
+}
 function dayKey(now = Date.now()) {
     return new Date(now).toISOString().slice(0, 10);
 }
@@ -108,6 +117,10 @@ function mergeRow(rows, record) {
 }
 /** Best-effort: accounting failures must never break a live request. */
 export function recordUsage(record, now = Date.now()) {
+    // 拿不到锁就放弃这一条统计：宁可少记一次，也不要覆盖掉另一个进程的整份账。
+    const lock = acquireFileLock(getUsageLockPath(), { timeoutMs: 200 }, now);
+    if (!lock)
+        return;
     try {
         const file = readUsage();
         const day = dayKey(now);
@@ -119,6 +132,9 @@ export function recordUsage(record, now = Date.now()) {
     catch {
         // Non-fatal.
     }
+    finally {
+        lock.release();
+    }
 }
 /** Aggregated rows for the last `days` days (inclusive of today). */
 export function summarizeUsage(options = {}, now = Date.now()) {
@@ -143,10 +159,14 @@ export function summarizeUsage(options = {}, now = Date.now()) {
 }
 /** Drop every recorded usage (test seam and `llms gateway usage reset`). */
 export function resetUsage() {
+    const lock = acquireFileLock(getUsageLockPath(), { timeoutMs: 200 });
     try {
         atomicWriteFile(getUsagePath(), `${JSON.stringify(emptyFile(), null, 2)}\n`);
     }
     catch {
         // Nothing persisted yet.
     }
+    finally {
+        lock?.release();
+    }
 }

package/dist/store/profiles.js

@@ -1,8 +1,8 @@
 import { existsSync, readdirSync, unlinkSync } from "node:fs";
 import { readFileSync } from "node:fs";
-import { isApiFormat, normalizeProxyValue } from "../types.js";
+import { API_FORMATS, isApiFormat, normalizeProxyValue } from "../types.js";
 import { normalizeBaseUrlForFormat } from "../utils/base-url.js";
-import { atomicWriteFile, ensureDir, maskSecret } from "../utils/fs.js";
+import { atomicWriteFile, ensureDir, maskSecret, readStructuredFile, } from "../utils/fs.js";
 import { getProfilePath, getProfilesDir, getStatePath, getToolStoreDir, } from "../utils/paths.js";
 const NAME_RE = /^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/;
 /** Keep only metadata entries whose model id is still in the list. */
@@ -49,7 +49,18 @@ export function listProfiles(tool) {
         return [];
     return readdirSync(dir)
         .filter((f) => f.endsWith(".json"))
-        .map((f) => readProfile(tool, f.replace(/\.json$/, "")))
+        .map((f) => {
+        const name = f.replace(/\.json$/, "");
+        try {
+            return readProfile(tool, name);
+        }
+        catch (err) {
+            // 单个坏 profile 不应让整份列表（以及所有命令）不可用。
+            const msg = err instanceof Error ? err.message : String(err);
+            console.warn(`警告：跳过损坏的 ${tool} profile「${name}」：${msg}`);
+            return null;
+        }
+    })
         .filter((p) => p !== null)
         .sort((a, b) => a.name.localeCompare(b.name));
 }
@@ -60,7 +71,9 @@ export function readProfile(tool, name) {
     const path = getProfilePath(tool, name);
     if (!existsSync(path))
         return null;
-    const raw = JSON.parse(readFileSync(path, "utf8"));
+    const raw = readStructuredFile(path, (text) => JSON.parse(text), { label: `${tool} 供应商配置`, fallback: () => null });
+    if (!raw)
+        return null;
     return normalizeProfile(raw, name);
 }
 export function requireProfile(tool, name) {
@@ -87,6 +100,10 @@ export function resolveProfile(tool, query) {
         return byName;
     const profiles = listProfiles(tool);
     const normalized = normalizeReference(trimmed);
+    // 纯分隔符的输入（如 "---"）归一化后为空串，而 "".includes("") 恒真，
+    // 会让下面的包含匹配命中任意 profile。这种查询直接视为无匹配。
+    if (!normalized)
+        return null;
     const exactDisplay = profiles.find((p) => normalizeReference(p.displayName) === normalized);
     if (exactDisplay)
         return exactDisplay;
@@ -119,18 +136,25 @@ export function saveProfile(tool, profile) {
     if (!profile.models?.default?.trim()) {
         throw new Error("默认模型不能为空");
     }
-    const list = Array.from(new Set([profile.models.default, profile.models.fast, ...(profile.models.list || [])]
+    const list = Array.from(new Set([
+        profile.models.default,
+        profile.models.smallModel,
+        ...(profile.models.list || []),
+    ]
         .filter(Boolean)
         .map((m) => m.trim())));
     const meta = filterModelMeta(profile.models.meta, list);
+    const defaultModel = profile.models.default.trim();
+    const smallModel = profile.models.smallModel?.trim() || undefined;
     const next = {
         ...profile,
         displayName: profile.displayName || profile.name,
         baseUrl: normalizeBaseUrlForFormat(profile.apiFormat, profile.baseUrl),
         apiKey: profile.apiKey ?? "",
         models: {
-            default: profile.models.default.trim(),
-            fast: profile.models.fast?.trim() || undefined,
+            default: defaultModel,
+            // Same as the default model → no point declaring a separate small model.
+            smallModel: smallModel && smallModel !== defaultModel ? smallModel : undefined,
             list,
             meta,
         },
@@ -216,26 +240,42 @@ export function publicProfileView(profile) {
         updatedAt: profile.updatedAt,
     };
 }
+/**
+ * Small model as stored on disk. Older profiles used `models.fast`; keep reading
+ * it so existing installs do not silently lose the setting after the rename.
+ */
+function legacySmallModel(raw) {
+    const models = raw.models;
+    const value = models?.smallModel ?? models?.fast;
+    return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
 function normalizeProfile(raw, fallbackName) {
     const name = raw.name || fallbackName;
+    // apiFormat 非法时不要透传成合法类型再等到 apply 才炸——那时用户已经改了一堆东西。
+    if (!isApiFormat(raw.apiFormat)) {
+        throw new Error(`供应商「${name}」的 apiFormat「${String(raw.apiFormat)}」无效。` +
+            `可选：${API_FORMATS.join("、")}。请修正该 profile 或重新添加。`);
+    }
+    const apiFormat = raw.apiFormat;
     const list = Array.from(new Set([
         raw.models?.default,
-        raw.models?.fast,
+        legacySmallModel(raw),
         ...(raw.models?.list || []),
     ]
         .filter(Boolean)
         .map((m) => String(m).trim())));
+    const defaultModel = raw.models?.default || list[0] || "";
     return {
         name,
         displayName: raw.displayName || name,
-        apiFormat: raw.apiFormat,
-        baseUrl: isApiFormat(raw.apiFormat)
-            ? normalizeBaseUrlForFormat(raw.apiFormat, String(raw.baseUrl || ""))
-            : String(raw.baseUrl || "").replace(/\/+$/, ""),
+        apiFormat,
+        baseUrl: normalizeBaseUrlForFormat(apiFormat, String(raw.baseUrl || "")),
         apiKey: raw.apiKey ?? "",
         models: {
-            default: raw.models?.default || list[0] || "",
-            fast: raw.models?.fast || undefined,
+            default: defaultModel,
+            smallModel: legacySmallModel(raw) && legacySmallModel(raw) !== defaultModel
+                ? legacySmallModel(raw)
+                : undefined,
             list: list.length ? list : raw.models?.default ? [raw.models.default] : [],
             meta: filterModelMeta(raw.models?.meta, list),
         },

package/dist/types.js

@@ -4,6 +4,18 @@ export const API_FORMATS = [
     "openai-chat",
     "openai-responses",
 ];
+/**
+ * Tools whose config supports a second, lightweight model alongside the main
+ * one (title generation, summaries and other cheap tasks):
+ * - claude: ANTHROPIC_SMALL_FAST_MODEL / ANTHROPIC_DEFAULT_HAIKU_MODEL
+ * - opencode: top-level `small_model`
+ * Codex has no equivalent knob.
+ */
+const SMALL_MODEL_TOOLS = ["claude", "opencode"];
+/** Whether `models.smallModel` is meaningful for the given tool. */
+export function supportsSmallModel(tool) {
+    return SMALL_MODEL_TOOLS.includes(tool);
+}
 export function isTool(value) {
     return TOOLS.includes(value);
 }

package/dist/utils/display.js

@@ -0,0 +1,71 @@
+/**
+ * Terminal display-width helpers.
+ *
+ * `String.padEnd` counts UTF-16 code units, but CJK characters occupy two
+ * terminal columns. Padding Chinese headers or provider names with padEnd/
+ * padStart therefore produces visibly ragged columns. These helpers pad by
+ * rendered width instead.
+ */
+/**
+ * Columns occupied by one code point. Covers the East Asian Wide/Fullwidth
+ * ranges we actually emit (CJK, kana, hangul, fullwidth forms, common
+ * punctuation and emoji); everything else counts as one column.
+ */
+function codePointWidth(cp) {
+    // Combining marks and zero-width characters take no space.
+    if (cp === 0x200b || cp === 0x200c || cp === 0x200d || cp === 0xfeff)
+        return 0;
+    if (cp >= 0x0300 && cp <= 0x036f)
+        return 0;
+    if ((cp >= 0x1100 && cp <= 0x115f) || // Hangul Jamo
+        (cp >= 0x2e80 && cp <= 0x303e) || // CJK radicals, Kangxi, CJK punctuation
+        (cp >= 0x3041 && cp <= 0x33ff) || // Hiragana, Katakana, Hangul compat, CJK compat
+        (cp >= 0x3400 && cp <= 0x4dbf) || // CJK Ext A
+        (cp >= 0x4e00 && cp <= 0x9fff) || // CJK Unified
+        (cp >= 0xa000 && cp <= 0xa4cf) || // Yi
+        (cp >= 0xac00 && cp <= 0xd7a3) || // Hangul syllables
+        (cp >= 0xf900 && cp <= 0xfaff) || // CJK compat ideographs
+        (cp >= 0xfe30 && cp <= 0xfe6f) || // CJK compat forms
+        (cp >= 0xff00 && cp <= 0xff60) || // Fullwidth forms
+        (cp >= 0xffe0 && cp <= 0xffe6) ||
+        (cp >= 0x1f300 && cp <= 0x1f64f) || // Emoji
+        (cp >= 0x1f900 && cp <= 0x1f9ff) ||
+        (cp >= 0x20000 && cp <= 0x3fffd) // CJK Ext B+
+    ) {
+        return 2;
+    }
+    return 1;
+}
+/** Rendered width of a string in terminal columns. */
+export function displayWidth(value) {
+    let width = 0;
+    for (const char of value) {
+        width += codePointWidth(char.codePointAt(0));
+    }
+    return width;
+}
+/** Pad on the right to `width` rendered columns. */
+export function padEndDisplay(value, width) {
+    const missing = width - displayWidth(value);
+    return missing > 0 ? value + " ".repeat(missing) : value;
+}
+/** Pad on the left to `width` rendered columns. */
+export function padStartDisplay(value, width) {
+    const missing = width - displayWidth(value);
+    return missing > 0 ? " ".repeat(missing) + value : value;
+}
+/**
+ * Render a fixed-width table sized to its content, aligned by display width.
+ * Returns header + rows; the caller decides how to print them.
+ */
+export function renderTable(rows, columns) {
+    const cells = rows.map((row) => columns.map((col) => col.value(row)));
+    const widths = columns.map((col, i) => Math.max(displayWidth(col.header), ...cells.map((row) => displayWidth(row[i] ?? ""))));
+    const line = (values) => values
+        .map((value, i) => columns[i].align === "right"
+        ? padStartDisplay(value, widths[i])
+        : padEndDisplay(value, widths[i]))
+        .join("  ")
+        .trimEnd();
+    return [line(columns.map((col) => col.header)), ...cells.map(line)];
+}

package/dist/utils/fetch-models.js

@@ -69,7 +69,25 @@ export function buildModelsRequestHeaders(apiFormat, apiKey, customHeaders = {})
     }
     return headers;
 }
-export function parseModelIds(payload) {
+/**
+ * Extract a model identifier from a list item. Providers disagree on the field
+ * name: OpenAI uses `id`, some gateways `name`/`model`, and Codex-style
+ * catalogs (e.g. BigModel) use `slug`.
+ */
+export function modelItemId(item) {
+    if (typeof item === "string")
+        return item.trim();
+    if (!item || typeof item !== "object")
+        return "";
+    const row = item;
+    const id = row.id ?? row.name ?? row.model ?? row.slug;
+    return typeof id === "string" ? id.trim() : "";
+}
+/**
+ * Collect the model-array buckets from a /models payload, accepting the common
+ * `data` and `models` shapes plus a bare array.
+ */
+export function modelsFromPayload(payload) {
     if (!payload || typeof payload !== "object")
         return [];
     const root = payload;
@@ -80,18 +98,14 @@ export function parseModelIds(payload) {
         buckets.push(...root.models);
     if (Array.isArray(payload))
         buckets.push(...payload);
+    return buckets;
+}
+export function parseModelIds(payload) {
     const ids = new Set();
-    for (const item of buckets) {
-        if (typeof item === "string" && item.trim()) {
-            ids.add(item.trim());
-            continue;
-        }
-        if (!item || typeof item !== "object")
-            continue;
-        const row = item;
-        const id = row.id ?? row.name ?? row.model;
-        if (typeof id === "string" && id.trim())
-            ids.add(id.trim());
+    for (const item of modelsFromPayload(payload)) {
+        const id = modelItemId(item);
+        if (id)
+            ids.add(id);
     }
     return Array.from(ids).sort((a, b) => a.localeCompare(b));
 }