tickmarkr 2.5.3 → 2.5.5

package/dist/gates/test-manifest.js

@@ -0,0 +1,389 @@
+import { randomBytes } from "node:crypto";
+import { existsSync, mkdtempSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { isAbsolute, join, relative, sep } from "node:path";
+import { TEST_REPORTER_SOURCE } from "./test-reporter.js";
+import { shq } from "../adapters/types.js";
+import { FORK_CAP_ENV, ROUTING_ENV_SEAMS, SUITE_PARENT_ENV, shell, resolvedCapacity } from "../run/git.js";
+/**
+ * VL-1 (OBS-985 lineage): a test gate's completion must be the runner's OWN report, never a stdout
+ * count. `fileCountDeficit` (baseline.ts) reads a summary LINE — a selected screen's smaller count
+ * looked identical to a truncated full suite (OBS-985's shipped defect). This module is the
+ * independent validator: it names a MANIFEST (the files the runner is expected to collect), binds a
+ * report to ONE invocation with a nonce, and trusts nothing the runner did not certify per file.
+ */
+/** Parse the supported simple shell invocation, retaining quoted argument values. Shell programs
+ * are deliberately outside this contract: forwarding reporter options to their last command is unsafe. */
+function shellTokens(command) {
+    return command.match(/(?:[^\s'"\\&|;<>]+|'[^']*'|"(?:\\.|[^"\\])*"|\\.)+|[&|;<>]+/g) ?? [];
+}
+function words(command) {
+    const tokens = shellTokens(command);
+    return tokens.map((token) => token.replace(/'([^']*)'|"((?:\\.|[^"\\])*)"|\\(.)/g, (_all, single, double, escaped) => single ?? (double !== undefined ? double.replace(/\\(["\\$`])/g, "$1") : escaped)));
+}
+const namesRunner = (body) => /(?:^|[\s/\\'";&|])vitest(?:\.mjs)?(?=$|[\s'";&|])/.test(body);
+function scriptInvocation(cmd, cwd) {
+    const argv = words(cmd);
+    const raw = shellTokens(cmd);
+    let manager = 0;
+    while (/^[A-Za-z_][A-Za-z_0-9]*=/.test(argv[manager] ?? ""))
+        manager++;
+    if (!["npm", "pnpm", "yarn"].includes(argv[manager]))
+        return undefined;
+    const offset = manager + (["run", "run-script"].includes(argv[manager + 1]) ? 2 : 1);
+    const name = ["t", "tst"].includes(argv[offset]) ? "test" : argv[offset];
+    try {
+        const body = JSON.parse(readFileSync(join(cwd, "package.json"), "utf8")).scripts?.[name];
+        return typeof body === "string" ? { body, trailing: raw.slice(offset + 1).filter((a) => a !== "--"), environment: raw.slice(0, manager), npm: argv[manager] === "npm" } : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function isVitestTestCommand(cmd, cwd) {
+    return namesRunner(scriptInvocation(cmd, cwd)?.body ?? cmd);
+}
+function runnerInvocation(cmd, cwd) {
+    const script = scriptInvocation(cmd, cwd);
+    const body = script?.body ?? cmd;
+    if ([body, cmd].some((text) => shellTokens(text).some((token) => /^[&|;<>]+$/.test(token)) || /[`\n]|\$\(/.test(text)))
+        throw new Error("vitest command is compound or contains unsupported shell syntax");
+    const args = words(body);
+    const raw = shellTokens(body);
+    let i = 0;
+    while (/^[A-Za-z_][A-Za-z_0-9]*=/.test(args[i] ?? ""))
+        i++;
+    const env = [...(script?.environment ?? []), ...raw.slice(0, i)];
+    let runner = args[i];
+    const prefix = [];
+    if (runner === "node") {
+        prefix.push(runner);
+        runner = args[++i];
+    }
+    else if (runner === "npx") {
+        runner = args[++i];
+    }
+    if (!runner || !/(?:^|[/\\])vitest(?:\.mjs)?$/.test(runner))
+        throw new Error("vitest script body is not a supported direct runner invocation");
+    const binary = runner === "vitest" ? join(cwd, "node_modules/.bin/vitest") : isAbsolute(runner) ? runner : join(cwd, runner);
+    if (!existsSync(binary))
+        throw new Error(`vitest binary does not exist: ${binary}`);
+    const forwarded = [...raw.slice(i + 1), ...(script?.trailing ?? [])];
+    if (forwarded[0] === "run")
+        forwarded.shift();
+    const collection = forwarded.filter((a) => a !== "--run" && a !== "--watch" && a !== "--");
+    return {
+        listing: [...env, ...prefix.map(shq), shq(binary), "list", ...collection, "--json"].join(" "),
+        separator: script?.npm && !/(?:^|\s)--(?:\s|$)/.test(cmd) ? " --" : "",
+    };
+}
+/** One identity for every path this module compares: repo-relative, forward-slash. `vitest list
+ * --json` and `TestModule.moduleId` both hand back an absolute filesystem path already resolved
+ * through any symlink in it (e.g. macOS's `/var` -> `/private/var`, under which every OS temp dir —
+ * and so every test fixture worktree — lives); `cwd` as tickmarkr holds it may not be. Resolving cwd
+ * before computing the relative path is what makes the two actually comparable. Manifests built from
+ * a selected-test screen are already repo-relative and pass through unchanged. */
+export function toManifestPath(file, cwd) {
+    if (!isAbsolute(file))
+        return file.replace(/^\.\//, "").split(sep).join("/");
+    let resolvedCwd = cwd;
+    try {
+        resolvedCwd = realpathSync(cwd);
+    }
+    catch { /* cwd unreadable — best effort with the given path */ }
+    return relative(resolvedCwd, file).split(sep).join("/");
+}
+function isTestReportShape(v) {
+    if (typeof v !== "object" || v === null)
+        return false;
+    const r = v;
+    if (typeof r.nonce !== "string" || !Array.isArray(r.requested) || typeof r.started !== "object" || r.started === null || typeof r.completed !== "object" || r.completed === null)
+        return false;
+    if (!r.requested.every((f) => typeof f === "string"))
+        return false;
+    if (Object.values(r.started).some((v) => typeof v !== "number"))
+        return false;
+    for (const c of Object.values(r.completed)) {
+        if (typeof c !== "object" || c === null)
+            return false;
+        const cc = c;
+        if (typeof cc.at !== "number" || (cc.status !== "passed" && cc.status !== "failed"))
+            return false;
+    }
+    if (r.duplicateCompletions !== undefined) {
+        if (!Array.isArray(r.duplicateCompletions) || !r.duplicateCompletions.every((f) => typeof f === "string"))
+            return false;
+    }
+    if (r.certificate !== undefined) {
+        if (typeof r.certificate !== "object" || r.certificate === null)
+            return false;
+        const cert = r.certificate;
+        if (typeof cert.at !== "number" || typeof cert.exitCode !== "number")
+            return false;
+    }
+    return true;
+}
+/** Reads and structurally validates the report; a missing or malformed file is `undefined` — never a partial parse. */
+export function readTestReport(path) {
+    if (!existsSync(path))
+        return undefined;
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        return isTestReportShape(parsed) ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The independent validator: given the manifest THIS invocation was asked to prove, its bound nonce
+ * and the independently observed process exit code, decide the
+ * verdict from the report alone. `killedFile` short-circuits every report-shaped check — a job this
+ * module killed for a per-file hang never reaches its report.
+ */
+export function verifyManifestReport(opts) {
+    const { manifest, nonce, exitCode, report, killedFile, hangBudgetMs } = opts;
+    if (killedFile !== undefined) {
+        return {
+            kind: "infra",
+            pass: false,
+            details: `infra hang: "${killedFile}" started and did not complete within its ${hangBudgetMs}ms budget — killed, its process group is gone`,
+            meta: { classification: "infra", infra: true, kind: "hang", file: killedFile, hangBudgetMs },
+        };
+    }
+    if (!report) {
+        return {
+            kind: "fail-closed",
+            pass: false,
+            details: `exit ${exitCode ?? "unknown"} with no invocation-bound test report — a gate that trusts the exit code alone is exactly what this gate refuses to be; failing closed naming the missing report`,
+            meta: { classification: "infra", infra: true, missingReport: true },
+        };
+    }
+    if (report.nonce !== nonce) {
+        return {
+            kind: "fail-closed",
+            pass: false,
+            details: `test report carries nonce "${report.nonce}" — this invocation's nonce is "${nonce}"; a report from another invocation is never a verdict, failing closed`,
+            meta: { classification: "infra", infra: true, staleNonce: report.nonce, expectedNonce: nonce },
+        };
+    }
+    const requestedCounts = new Map();
+    for (const f of report.requested)
+        requestedCounts.set(f, (requestedCounts.get(f) ?? 0) + 1);
+    const duplicated = [...requestedCounts.entries()].find(([, n]) => n > 1)?.[0];
+    if (duplicated !== undefined) {
+        return {
+            kind: "fail-closed",
+            pass: false,
+            details: `test report names "${duplicated}" more than once in its requested set — a file counted twice is not a trustworthy completion record; failing closed`,
+            meta: { classification: "infra", infra: true, duplicateFile: duplicated },
+        };
+    }
+    if (report.duplicateCompletions?.length) {
+        const dup = report.duplicateCompletions[0];
+        return {
+            kind: "fail-closed",
+            pass: false,
+            details: `"${dup}" completed more than once in this report — a duplicate completion record (evidence the reporter preserved despite the later write overwriting it) is never a verdict; failing closed`,
+            meta: { classification: "infra", infra: true, duplicateCompletion: dup },
+        };
+    }
+    const uncorroborated = Object.keys(report.completed).find((f) => !(f in report.started) || !report.requested.includes(f));
+    if (uncorroborated !== undefined) {
+        return {
+            kind: "fail-closed",
+            pass: false,
+            details: `"${uncorroborated}" is marked completed without a matching requested/started record — an unattributed completion is never a verdict; failing closed`,
+            meta: { classification: "infra", infra: true, unattributedCompletion: uncorroborated },
+        };
+    }
+    if (!report.certificate) {
+        const pending = manifest.find((f) => f in report.started && !(f in report.completed));
+        return {
+            kind: "infra",
+            pass: false,
+            details: pending !== undefined
+                ? `the job was killed after its last file record but before its terminal certificate — never a verdict; last incomplete file was "${pending}"`
+                : `the job was killed after its last file record but before its terminal certificate — never a verdict`,
+            meta: { classification: "infra", infra: true, missingCertificate: true, ...(pending !== undefined ? { file: pending } : {}) },
+        };
+    }
+    const failures = Object.values(report.completed).filter((c) => c.status === "failed")
+        .flatMap((c) => c.failures?.length ? c.failures : ["<unnamed failure>"]);
+    if (failures.length)
+        return { kind: "work", pass: false,
+            details: `test report names failing fingerprint(s):\n${failures.join("\n")}`,
+            meta: { classification: "regression", failingTests: failures, processExit: exitCode } };
+    if (exitCode === undefined) {
+        return {
+            kind: "fail-closed",
+            pass: false,
+            details: `the process did not terminate with an exit code (likely killed by a signal) though a certificate naming exit ${report.certificate.exitCode} is present — a passing verdict requires a clean process termination; failing closed naming both`,
+            meta: { classification: "infra", infra: true, missingProcessExit: true, certificateExit: report.certificate.exitCode },
+        };
+    }
+    if (report.certificate.exitCode !== exitCode) {
+        return {
+            kind: "fail-closed",
+            pass: false,
+            details: `report certificate names exit ${report.certificate.exitCode} but the process exited ${exitCode} — a report that contradicts the exit code is never a verdict; failing closed naming both`,
+            meta: { classification: "infra", infra: true, certificateExit: report.certificate.exitCode, processExit: exitCode },
+        };
+    }
+    if (exitCode !== 0)
+        return {
+            kind: "fail-closed", pass: false,
+            details: `report has no failed tests but the process exited ${exitCode}; failing closed naming the successful report and nonzero exit`,
+            meta: { classification: "infra", infra: true, processExit: exitCode },
+        };
+    const unexpectedRequested = report.requested.find((f) => !manifest.includes(f));
+    const unexpectedStarted = Object.keys(report.started).find((f) => !report.requested.includes(f) || !manifest.includes(f));
+    if (unexpectedRequested ?? unexpectedStarted) {
+        const file = unexpectedRequested ?? unexpectedStarted;
+        return {
+            kind: "fail-closed", pass: false,
+            details: `"${file}" is outside the invocation's requested/start lifecycle — a report must certify exactly this manifest; failing closed`,
+            meta: { classification: "infra", infra: true, unexpectedLifecycleFile: file },
+        };
+    }
+    const pending = manifest.find((f) => f in report.started && !(f in report.completed));
+    if (pending !== undefined) {
+        return {
+            kind: "infra",
+            pass: false,
+            details: `"${pending}" started and never completed — an infra result naming the file`,
+            meta: { classification: "infra", infra: true, file: pending, incomplete: true },
+        };
+    }
+    const missing = manifest.find((f) => !(f in report.completed));
+    if (missing !== undefined) {
+        return {
+            kind: "infra",
+            pass: false,
+            details: `"${missing}" is in the manifest but absent from the report — an infra result naming the file`,
+            meta: { classification: "infra", infra: true, file: missing, missingFromReport: true },
+        };
+    }
+    return {
+        kind: "pass",
+        pass: true,
+        details: `invocation-bound test report succeeded — ${manifest.length} manifest file(s) present exactly once`,
+        meta: { manifestFiles: manifest.length },
+    };
+}
+/** How much longer than its baseline measurement one file may legitimately run before it is a hang. */
+export const FILE_HANG_SLACK = 3;
+export const DEFAULT_FILE_HANG_BUDGET_MS = 60_000;
+const usable = (n) => n !== undefined && Number.isFinite(n) && n > 0;
+export function fileHangBudgetMs(file, baselineDurations, ceilingMs = DEFAULT_FILE_HANG_BUDGET_MS, longestFile) {
+    const ceiling = usable(ceilingMs) ? ceilingMs : DEFAULT_FILE_HANG_BUDGET_MS;
+    const timings = baselineDurations?.filter((d) => usable(d.durationMs)) ?? [];
+    const longest = Math.max(0, ...timings.map((d) => d.durationMs), usable(longestFile?.durationMs) ? longestFile.durationMs : 0);
+    if (!longest)
+        return ceiling;
+    const known = timings.find((d) => d.file === file)?.durationMs;
+    return Math.min(ceiling, known === undefined ? FILE_HANG_SLACK * longest : Math.max(FILE_HANG_SLACK * known, longest));
+}
+/** Supervise the configured command and poll the runner's atomic lifecycle snapshots. Every
+ * timeout kills the detached process group, including descendants holding the output pipes. */
+export function runManifestedTest(cmd, cwd, opts) {
+    const pollMs = opts.pollMs ?? 20;
+    const overallCeilingMs = usable(opts.overallCeilingMs) ? opts.overallCeilingMs : DEFAULT_FILE_HANG_BUDGET_MS;
+    const env = { ...(opts.env ?? process.env), TICKMARKR_TEST_REPORT: opts.reportPath, TICKMARKR_TEST_NONCE: opts.nonce };
+    const controller = new AbortController();
+    let pid;
+    let killedFile;
+    let hangBudgetMs;
+    let poll;
+    const checkHang = (atCeiling = false) => {
+        const report = readTestReport(opts.reportPath);
+        if (!report || report.nonce !== opts.nonce)
+            return;
+        const now = Date.now();
+        for (const file of opts.manifest) {
+            const startedAt = report.started[file];
+            if (startedAt === undefined || file in report.completed)
+                continue;
+            const budget = fileHangBudgetMs(file, opts.baselineDurations, overallCeilingMs, opts.longestFile);
+            if (now - startedAt >= budget || (atCeiling && budget === overallCeilingMs)) {
+                killedFile = file;
+                hangBudgetMs = budget;
+                if (!atCeiling)
+                    controller.abort();
+                return;
+            }
+        }
+    };
+    return shell(cmd, cwd, overallCeilingMs, false, {
+        env, signal: controller.signal, onTimeout: () => checkHang(true),
+        onSpawn: (childPid) => {
+            pid = childPid;
+            // Neither the per-file clocks nor the command ceiling includes lease queue time.
+            clearInterval(poll);
+            poll = setInterval(checkHang, pollMs);
+        },
+    }).then((result) => ({
+        exitCode: result.signalExit ? undefined : result.code,
+        stdout: result.stdout, stderr: result.stderr,
+        report: readTestReport(opts.reportPath), killedFile, hangBudgetMs, pid,
+    })).finally(() => { clearInterval(poll); });
+}
+/** One configured runner execution, and its own collection under the same arguments and environment.
+ * The installed runner is trusted (R28 add.1 option B); the nonce catches stale artifacts, not forgery. */
+export async function evaluateManifestedTest(cmd, cwd, opts) {
+    const dir = opts.artifactDir ?? mkdtempSync(join(tmpdir(), "tickmarkr-test-report-"));
+    const nonce = randomBytes(16).toString("hex");
+    const reportPath = join(dir, `test-manifest-report-${nonce}.json`);
+    const reporterPath = join(dir, `test-reporter-${nonce}.mjs`);
+    let spawnedCommand = cmd;
+    const env = { ...process.env, PATH: `${join(cwd, "node_modules/.bin")}:${process.env.PATH ?? ""}`,
+        [FORK_CAP_ENV]: String(resolvedCapacity().forkCap), [SUITE_PARENT_ENV]: String(process.pid) };
+    for (const key of ROUTING_ENV_SEAMS)
+        delete env[key];
+    // A gate can itself be tested under Vitest. Do not give the child the outer worker identity.
+    for (const key of Object.keys(env))
+        if (["VITEST", "TEST", "VITEST_WORKER_ID", "VITEST_POOL_ID"].includes(key))
+            delete env[key];
+    try {
+        const invocation = runnerInvocation(cmd, cwd);
+        const listed = await runManifestedTest(invocation.listing, cwd, {
+            manifest: [], nonce, reportPath: join(dir, `listing-${nonce}.json`), env,
+            overallCeilingMs: opts.overallCeilingMs ?? DEFAULT_FILE_HANG_BUDGET_MS,
+        });
+        if (listed.exitCode !== 0)
+            throw new Error(`vitest cannot list files (exit ${listed.exitCode ?? "signal"}): ${listed.stderr || listed.stdout}`);
+        let files;
+        try {
+            const rows = JSON.parse(listed.stdout.slice(listed.stdout.indexOf("[")));
+            if (!Array.isArray(rows) || !rows.every((r) => typeof r?.file === "string"))
+                throw new Error("invalid listing");
+            files = [...new Set(rows.map((r) => toManifestPath(r.file, cwd)))].sort();
+        }
+        catch {
+            throw new Error(`vitest cannot list files: invalid JSON listing: ${listed.stdout}`);
+        }
+        if (!files.length)
+            throw new Error("vitest cannot list files: empty manifest");
+        writeFileSync(reporterPath, TEST_REPORTER_SOURCE);
+        spawnedCommand = `${cmd}${invocation.separator} --reporter=${shq(reporterPath)} --outputFile=${shq(reportPath)}`;
+        const invoked = await runManifestedTest(spawnedCommand, cwd, {
+            manifest: files, nonce, reportPath, env,
+            baselineDurations: opts.baselineDurations?.map((d) => ({ ...d, file: toManifestPath(d.file, cwd) })),
+            longestFile: opts.longestFile,
+            overallCeilingMs: opts.overallCeilingMs ?? DEFAULT_FILE_HANG_BUDGET_MS,
+            pollMs: 20,
+        });
+        const verdict = verifyManifestReport({ manifest: files, nonce, exitCode: invoked.exitCode,
+            report: invoked.report, killedFile: invoked.killedFile, hangBudgetMs: invoked.hangBudgetMs });
+        return { pass: verdict.pass, kind: verdict.kind,
+            details: verdict.details + (!invoked.report && invoked.stderr ? `\nvitest reporter: ${invoked.stderr}` : ""),
+            classification: verdict.meta.classification,
+            meta: { ...verdict.meta, nonce, manifest: files, spawnedCommand, processExit: invoked.exitCode, pid: invoked.pid },
+            exitCode: invoked.exitCode ?? -1, reportPath };
+    }
+    catch (error) {
+        return { pass: false, kind: "infra", classification: "infra", exitCode: -1, reportPath,
+            details: error instanceof Error ? error.message : String(error),
+            meta: { classification: "infra", infra: true, manifestDiscoveryFailed: true, spawnedCommand } };
+    }
+}

package/dist/gates/test-reporter.d.ts

@@ -0,0 +1,4 @@
+/** Loaded by the configured Vitest process. Atomic snapshots expose live lifecycle records to
+ * the supervisor; only onTestRunEnd emits the terminal record. This is a completeness protocol,
+ * not authentication against the installed runner (which the gate already trusts). */
+export declare const TEST_REPORTER_SOURCE: string;

package/dist/gates/test-reporter.js

@@ -0,0 +1,49 @@
+/** Loaded by the configured Vitest process. Atomic snapshots expose live lifecycle records to
+ * the supervisor; only onTestRunEnd emits the terminal record. This is a completeness protocol,
+ * not authentication against the installed runner (which the gate already trusts). */
+export const TEST_REPORTER_SOURCE = String.raw `
+import { writeFileSync, renameSync, realpathSync } from 'node:fs';
+import { relative, sep } from 'node:path';
+export default class TickmarkrReporter {
+  constructor() {
+    this.report = { nonce: process.env.TICKMARKR_TEST_NONCE, requested: [], started: {}, completed: {}, duplicateCompletions: [] };
+    this.path = process.env.TICKMARKR_TEST_REPORT;
+    this.cwd = realpathSync(process.cwd());
+  }
+  file(module) { return relative(this.cwd, module.moduleId).split(sep).join('/'); }
+  save() {
+    writeFileSync(this.path + '.tmp', JSON.stringify(this.report));
+    renameSync(this.path + '.tmp', this.path);
+  }
+  onTestRunStart(specifications) {
+    this.report.requested = specifications.map(s => this.file(s));
+    this.save();
+  }
+  onTestModuleStart(module) {
+    this.report.started[this.file(module)] = Date.now();
+    this.save();
+  }
+  onTestModuleEnd(module) {
+    const file = this.file(module);
+    const failed = module.state() === 'failed';
+    const failures = [];
+    if (failed) {
+      for (const test of module.children.allTests()) {
+        if (test.result().state === 'failed') {
+          const errors = test.result().errors || [];
+          failures.push(...(errors.length ? errors.map(e => 'FAIL ' + file + ' > ' + test.fullName + ': ' + e.message) : ['FAIL ' + file + ' > ' + test.fullName]));
+        }
+      }
+      if (!failures.length) failures.push('FAIL ' + file);
+    }
+    if (file in this.report.completed) this.report.duplicateCompletions.push(file);
+    this.report.completed[file] = { at: Date.now(), status: failed ? 'failed' : 'passed', failures };
+    this.save();
+  }
+  onTestRunEnd(modules, errors, reason) {
+    const failed = reason === 'failed' || errors.length > 0 || Object.values(this.report.completed).some(c => c.status === 'failed');
+    this.report.certificate = { at: Date.now(), exitCode: failed ? 1 : 0 };
+    this.save();
+  }
+}
+`;

package/dist/route/preference.d.ts

@@ -28,10 +28,31 @@ export declare function preferRanks(c: {
     shape: string;
     rank: number;
 }[];
+export declare function isExplicitIdOfAliasFamily(candidateModel: string, alias: string): boolean;
+export declare function entryMatchesChannel(entry: string, c: {
+    adapter: string;
+    model: string;
+    identity?: string;
+}, allowFamilyMatching?: boolean): boolean;
+export interface ExclusionScope {
+    scope: string;
+    path: string;
+    configPath: string;
+    entry: string;
+    by: "deny" | "allow";
+}
+export declare function exclusionCollector(c: {
+    adapter: string;
+    model: string;
+    identity?: string;
+}, routingOrCfg: TickmarkrConfig["routing"] | TickmarkrConfig, role?: PreferenceRole): ExclusionScope[];
+export declare const collectExclusions: typeof exclusionCollector;
+export declare const exclusionProvenance: typeof exclusionCollector;
 export declare function disallowedBy(c: {
     adapter: string;
     model: string;
-}, routing: TickmarkrConfig["routing"], role?: PreferenceRole): Disallowed | null;
+    identity?: string;
+}, routingOrCfg: TickmarkrConfig["routing"] | TickmarkrConfig, role?: PreferenceRole): Disallowed | null;
 export interface DenyPreferCollision {
     kind: "prefer" | "pin" | "pool";
     shape: string;

package/dist/route/preference.js

@@ -5,19 +5,24 @@ const PREFERENCE_ROLES = ["worker", "judge", "review", "consult"];
 /** Provider identity comes from the served model, not a gateway adapter's stamped vendor. */
 export function modelProvider(model, fallback = "unknown") {
     const id = model.toLowerCase();
-    const prefix = id.includes("/") ? id.slice(0, id.indexOf("/")) : "";
-    if (prefix === "openai" || prefix === "openai-codex" || /^(?:gpt|o\d)/.test(id))
+    const sepIdx = id.search(/[/:\s]/);
+    const prefix = sepIdx !== -1 ? id.slice(0, sepIdx) : "";
+    const remainder = sepIdx !== -1 ? id.slice(sepIdx + 1) : id;
+    if (prefix === "openai" || prefix === "openai-codex" || /^(?:gpt|o\d)/.test(remainder))
         return "openai";
-    if (prefix === "anthropic" || /^(?:claude|opus|sonnet|haiku|fable)(?:-|$)/.test(id))
+    if (prefix === "anthropic" || /^(?:claude|opus|sonnet|haiku|fable)(?:-|$)/.test(remainder))
         return "anthropic";
-    if (prefix === "google" || /^gemini(?:-|$)/.test(id))
+    if (prefix === "google" || /^gemini(?:-|$)/.test(remainder))
         return "google";
-    if (prefix === "xai" || /^grok(?:-|$)/.test(id))
+    if (prefix === "xai" || prefix === "xai-oauth" || /^(?:grok|xai)(?:-|$)/.test(remainder) || id.startsWith("xai-oauth"))
         return "xai";
-    if (["zai", "zhipu", "zai-coding-plan"].includes(prefix) || /^glm(?:-|$)/.test(id))
+    if (["zai", "zhipu", "zai-coding-plan"].includes(prefix) || /^glm(?:-|$)/.test(remainder))
         return "zhipu";
-    if (["kimi-code", "moonshot"].includes(prefix) || /^kimi(?:-|$)/.test(id))
+    if (["kimi-code", "moonshot"].includes(prefix) || /^kimi(?:-|$)/.test(remainder))
         return "moonshot";
+    const normalizedFallback = fallback.toLowerCase();
+    if (normalizedFallback === "xai-oauth" || normalizedFallback === "xai")
+        return "xai";
     return fallback;
 }
 // Router naming remains explicit while sharing the review gate's exact function object.
@@ -51,7 +56,9 @@ export function excludedChannels(cfg, adapters, health) {
         if (!health[id]?.installed || !health[id]?.authed)
             continue;
         for (const c of channelsFromConfig(id, cfg)) {
-            const d = disallowedBy(c, cfg.routing);
+            const identity = health[id]?.modelAuth?.[c.model]?.identity ?? health[id]?.modelIdentities?.[c.model];
+            const chan = identity ? { ...c, identity } : c;
+            const d = disallowedBy(chan, cfg.routing);
             if (d)
                 out.push({ key: channelKey(c), d });
         }
@@ -75,25 +82,116 @@ export function preferRanks(c, cfg) {
     }
     return out;
 }
-// entries in either list accept adapter id, model id, or adapter:model (grammar A1)
-export function disallowedBy(c, routing, role = "worker") {
-    const { allow, deny } = routing;
-    const matches = (e) => e === c.adapter || e === c.model || e === channelKey(c);
-    const workerDeny = role === "worker" ? deny?.workers : undefined;
-    const d = [
-        ...(deny?.adapters ?? []),
-        ...(deny?.models ?? []),
-        ...(workerDeny?.adapters ?? []),
-        ...(workerDeny?.models ?? []),
-    ].find(matches);
-    if (d)
-        return { by: "deny", entry: d };
+export function isExplicitIdOfAliasFamily(candidateModel, alias) {
+    if (candidateModel === alias)
+        return true;
+    const tokens = candidateModel.toLowerCase().split(/[^a-z0-9]+/);
+    return tokens.includes(alias.toLowerCase());
+}
+export function entryMatchesChannel(entry, c, allowFamilyMatching = false) {
+    if (entry === c.adapter)
+        return true;
+    if (entry === c.model)
+        return true;
+    if (entry === channelKey(c))
+        return true;
+    if (c.identity) {
+        if (entry === c.identity)
+            return true;
+        if (entry === `${c.adapter}:${c.identity}`)
+            return true;
+    }
+    if (!c.identity && allowFamilyMatching) {
+        const colon = entry.indexOf(":");
+        if (colon !== -1) {
+            const entryAdapter = entry.slice(0, colon);
+            const entryModel = entry.slice(colon + 1);
+            if (entryAdapter === c.adapter && isExplicitIdOfAliasFamily(entryModel, c.model)) {
+                return true;
+            }
+        }
+        else {
+            if (isExplicitIdOfAliasFamily(entry, c.model)) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+export function exclusionCollector(c, routingOrCfg, role = "worker") {
+    const routing = "routing" in routingOrCfg ? routingOrCfg.routing : routingOrCfg;
+    const out = [];
+    const { allow, deny } = routing ?? {};
+    for (const entry of deny?.adapters ?? []) {
+        if (entryMatchesChannel(entry, c, true)) {
+            out.push({
+                scope: "routing.deny.adapters",
+                path: "routing.deny.adapters",
+                configPath: "routing.deny.adapters",
+                entry,
+                by: "deny",
+            });
+        }
+    }
+    for (const entry of deny?.models ?? []) {
+        if (entryMatchesChannel(entry, c, true)) {
+            out.push({
+                scope: "routing.deny.models",
+                path: "routing.deny.models",
+                configPath: "routing.deny.models",
+                entry,
+                by: "deny",
+            });
+        }
+    }
+    if (role === "worker") {
+        for (const entry of deny?.workers?.adapters ?? []) {
+            if (entryMatchesChannel(entry, c, true)) {
+                out.push({
+                    scope: "routing.deny.workers.adapters",
+                    path: "routing.deny.workers.adapters",
+                    configPath: "routing.deny.workers.adapters",
+                    entry,
+                    by: "deny",
+                });
+            }
+        }
+        for (const entry of deny?.workers?.models ?? []) {
+            if (entryMatchesChannel(entry, c, true)) {
+                out.push({
+                    scope: "routing.deny.workers.models",
+                    path: "routing.deny.workers.models",
+                    configPath: "routing.deny.workers.models",
+                    entry,
+                    by: "deny",
+                });
+            }
+        }
+    }
     if (allow) {
-        const entries = [...(allow.adapters ?? []), ...(allow.models ?? [])];
-        if (!entries.some(matches))
-            return { by: "allow", entry: entries.join(", ") || "(empty allowlist)" };
+        const allAllow = [...(allow.adapters ?? []), ...(allow.models ?? [])];
+        const admitted = allAllow.some((e) => entryMatchesChannel(e, c, false));
+        if (!admitted) {
+            out.push({
+                scope: "routing.allow",
+                path: "routing.allow",
+                configPath: "routing.allow",
+                entry: allAllow.join(", ") || "(empty allowlist)",
+                by: "allow",
+            });
+        }
     }
-    return null;
+    return out;
+}
+export const collectExclusions = exclusionCollector;
+export const exclusionProvenance = exclusionCollector;
+// entries in either list accept adapter id, model id, or adapter:model (grammar A1)
+export function disallowedBy(c, routingOrCfg, role = "worker") {
+    const exclusions = exclusionCollector(c, routingOrCfg, role);
+    if (exclusions.length === 0)
+        return null;
+    const first = exclusions[0];
+    return { by: first.by, entry: first.entry };
 }
 // Delegates to route()'s preflightPrefer — doctor/resume preflight reuses the router grammar,
 // not a second colon/tier/model parser of the same config.