Skip to content

Commit 414861d

Browse files
committed
fix(routing): address second review round on route decision traces (RI-01)
- combo requests persist one immutable combo trace; child adoption can no longer overwrite it with a concrete child route trace (P1) - attach the initial route trace immediately after routeModel so pre-dispatch rejections still record the decision - normalizer now marks every cap it applies (candidates/exclusions/ requirements/strings) and unions it with incoming flags - startup hydration keeps expanding the read window to the file start and budgets for trace-sized rows - byte-budget fallback re-measures after shrinking and strips exclusions deterministically as a last resort - tests: combo server-path trace, normalizer flags, trace-sized hydration
1 parent 3d7b086 commit 414861d

6 files changed

Lines changed: 237 additions & 67 deletions

File tree

‎src/router.ts‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -355,6 +355,34 @@ export class NoEnabledOpenAiProviderError extends Error {
355355
}
356356
}
357357

358+
/**
359+
* One immutable selection trace for a combo request: built once from the
360+
* initial pick, before any child dispatch. Fallback execution stays in the
361+
* usage entry's `attempts[]`; the trace never changes after selection.
362+
*/
363+
export function comboRouteDecisionTrace(
364+
config: OcxConfig,
365+
comboId: string,
366+
pick: ComboPick,
367+
requestedModel: string,
368+
): RouteDecisionTraceV1 {
369+
const combo = getCombo(config, comboId);
370+
return buildRouteDecisionTrace({
371+
requestedModel,
372+
routeKind: "combo",
373+
selected: {
374+
provider: pick.target.provider,
375+
model: pick.target.model,
376+
reason: "combo-pick",
377+
candidateIndex: pick.targetIndex,
378+
...(combo
379+
? { tieBreak: combo.strategy === "round-robin" ? "round-robin" : "failover" }
380+
: {}),
381+
},
382+
candidates: combo ? comboRouteCandidates(config, pick, combo) : undefined,
383+
});
384+
}
385+
358386
// Codex uses a small number of control-plane model ids that are not part of the public GPT/o
359387
// naming families. Keep this exact: a broad `codex-*` rule could capture a third-party model.
360388
const CODEX_INTERNAL_OPENAI_MODELS = new Set(["codex-auto-review"]);

‎src/routing/trace.ts‎

Lines changed: 91 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -340,54 +340,80 @@ function enforceByteBudget(trace: RouteDecisionTraceV1): RouteDecisionTraceV1 {
340340
const kept = selectedIndex < half
341341
? slimmed.candidates.slice(0, half)
342342
: [...slimmed.candidates.slice(0, half - 1), slimmed.candidates[selectedIndex]!];
343-
return {
343+
let result: RouteDecisionTraceV1 = {
344344
...slimmed,
345345
truncated: { ...truncated, candidates: true as const },
346346
candidates: kept,
347347
selected: { ...slimmed.selected, candidateIndex: Math.min(selectedIndex, kept.length - 1) },
348348
};
349+
// Last resort: halving candidates still over budget (only reachable with
350+
// pathological strings) - drop to 8 exclusions per candidate, deterministically.
351+
if (serializedByteLength(result) > MAX_TRACE_BYTES) {
352+
result = {
353+
...result,
354+
truncated: { ...result.truncated, exclusions: true as const },
355+
candidates: result.candidates.map(candidate => ({
356+
...candidate,
357+
exclusions: candidate.exclusions.slice(0, 8),
358+
})),
359+
};
360+
}
361+
return result;
349362
}
350363

351364
// ---- defensive parsing of persisted rows --------------------------------------
352365

366+
/** Caps applied by the normalizer; unioned into `truncated` on the result. */
367+
interface ParseCaps {
368+
candidates?: true;
369+
exclusions?: true;
370+
requirements?: true;
371+
strings?: true;
372+
}
373+
353374
/** Defensive parse of one persisted exclusion reason. */
354-
function parseExclusion(raw: unknown): RouteExclusionReason | null {
375+
function parseExclusion(raw: unknown, caps: ParseCaps): RouteExclusionReason | null {
355376
if (!isPlainRecord(raw)) return null;
356377
const code = raw.code;
357378
if (typeof code !== "string" || code.length === 0) return null;
358-
return {
359-
code: code.slice(0, MAX_TRACE_STRING),
360-
...(typeof raw.detail === "string"
361-
? { detail: raw.detail.slice(0, MAX_TRACE_STRING) }
362-
: {}),
363-
};
379+
if (code.length > MAX_TRACE_STRING) caps.strings = true;
380+
const out: RouteExclusionReason = { code: code.slice(0, MAX_TRACE_STRING) };
381+
if (typeof raw.detail === "string") {
382+
if (raw.detail.length > MAX_TRACE_STRING) caps.strings = true;
383+
out.detail = raw.detail.slice(0, MAX_TRACE_STRING);
384+
}
385+
return out;
364386
}
365387

366388
/** Defensive parse of one persisted requirement; rejects unknown outcomes. */
367-
function parseRequirement(raw: unknown): RouteRequirementEvidence | null {
389+
function parseRequirement(raw: unknown, caps: ParseCaps): RouteRequirementEvidence | null {
368390
if (!isPlainRecord(raw)) return null;
369391
const id = raw.id;
370392
const outcome = raw.outcome;
371393
if (typeof id !== "string" || id.length === 0) return null;
372394
if (typeof outcome !== "string" || !REQUIREMENT_OUTCOMES.has(outcome)) return null;
373-
return {
395+
if (id.length > MAX_TRACE_STRING) caps.strings = true;
396+
const out: RouteRequirementEvidence = {
374397
id: id.slice(0, MAX_TRACE_STRING),
375-
...(typeof raw.expected === "string"
376-
? { expected: raw.expected.slice(0, MAX_TRACE_STRING) }
377-
: typeof raw.expected === "number" || typeof raw.expected === "boolean"
378-
? { expected: raw.expected }
379-
: {}),
380-
...(typeof raw.actual === "string"
381-
? { actual: raw.actual.slice(0, MAX_TRACE_STRING) }
382-
: unknownable(raw.actual) !== undefined
383-
? { actual: unknownable(raw.actual) }
384-
: {}),
385398
outcome: outcome as RouteRequirementEvidence["outcome"],
386399
};
400+
if (typeof raw.expected === "string") {
401+
if (raw.expected.length > MAX_TRACE_STRING) caps.strings = true;
402+
out.expected = raw.expected.slice(0, MAX_TRACE_STRING);
403+
} else if (typeof raw.expected === "number" || typeof raw.expected === "boolean") {
404+
out.expected = raw.expected;
405+
}
406+
if (typeof raw.actual === "string") {
407+
if (raw.actual.length > MAX_TRACE_STRING) caps.strings = true;
408+
out.actual = raw.actual.slice(0, MAX_TRACE_STRING);
409+
} else if (unknownable(raw.actual) !== undefined) {
410+
out.actual = unknownable(raw.actual);
411+
}
412+
return out;
387413
}
388414

389415
/** Whitelisted capability-evidence parse; unknown fields are dropped. */
390-
function parseCapability(raw: unknown): RouteCapabilityEvidence | undefined {
416+
function parseCapability(raw: unknown, caps: ParseCaps): RouteCapabilityEvidence | undefined {
391417
if (!isPlainRecord(raw)) return undefined;
392418
const out: RouteCapabilityEvidence = {};
393419
if (finiteNumber(raw.contextWindow)) out.contextWindow = raw.contextWindow;
@@ -399,6 +425,7 @@ function parseCapability(raw: unknown): RouteCapabilityEvidence | undefined {
399425
if (structuredOutput !== undefined) out.structuredOutput = structuredOutput;
400426
if (Array.isArray(raw.reasoningEfforts)
401427
&& raw.reasoningEfforts.every((value): value is string => typeof value === "string")) {
428+
if (raw.reasoningEfforts.some((value: string) => value.length > MAX_TRACE_STRING)) caps.strings = true;
402429
out.reasoningEfforts = raw.reasoningEfforts
403430
.slice(0, 8)
404431
.map(value => value.slice(0, MAX_TRACE_STRING));
@@ -430,7 +457,7 @@ function parseHealth(raw: unknown): RouteHealthEvidence | undefined {
430457
}
431458

432459
/** Whitelisted quota-evidence parse; requires a boolean `known`. */
433-
function parseQuota(raw: unknown): RouteQuotaEvidence | undefined {
460+
function parseQuota(raw: unknown, caps: ParseCaps): RouteQuotaEvidence | undefined {
434461
if (!isPlainRecord(raw)) return undefined;
435462
if (typeof raw.known !== "boolean") return undefined;
436463
const out: RouteQuotaEvidence = { known: raw.known };
@@ -440,17 +467,19 @@ function parseQuota(raw: unknown): RouteQuotaEvidence | undefined {
440467
if (typeof raw.reauthOrCooling === "boolean") out.reauthOrCooling = raw.reauthOrCooling;
441468
if (finiteNumber(raw.reservedHeadroomTokens)) out.reservedHeadroomTokens = raw.reservedHeadroomTokens;
442469
if (typeof raw.source === "string" && raw.source) {
470+
if (raw.source.length > MAX_TRACE_STRING) caps.strings = true;
443471
out.source = raw.source.slice(0, MAX_TRACE_STRING);
444472
}
445473
return out;
446474
}
447475

448476
/** Whitelisted cost-evidence parse. */
449-
function parseCost(raw: unknown): RouteCostEvidence | undefined {
477+
function parseCost(raw: unknown, caps: ParseCaps): RouteCostEvidence | undefined {
450478
if (!isPlainRecord(raw)) return undefined;
451479
const out: RouteCostEvidence = {};
452480
if (finiteNumber(raw.estimatedUsd)) out.estimatedUsd = raw.estimatedUsd;
453481
if (typeof raw.priceSource === "string" && raw.priceSource) {
482+
if (raw.priceSource.length > MAX_TRACE_STRING) caps.strings = true;
454483
out.priceSource = raw.priceSource.slice(0, MAX_TRACE_STRING);
455484
}
456485
if (typeof raw.incomplete === "boolean") out.incomplete = raw.incomplete;
@@ -472,20 +501,24 @@ function parseScore(raw: unknown): RouteScoreEvidence | undefined {
472501
}
473502

474503
/** Defensive parse of one persisted candidate with bounded evidence blocks. */
475-
function parseCandidate(raw: unknown): RouteCandidateTrace | null {
504+
function parseCandidate(raw: unknown, caps: ParseCaps): RouteCandidateTrace | null {
476505
if (!isPlainRecord(raw)) return null;
477506
const provider = raw.provider;
478507
const model = raw.model;
479508
if (typeof provider !== "string" || provider.length === 0) return null;
480509
if (typeof model !== "string" || model.length === 0) return null;
510+
if (provider.length > MAX_TRACE_STRING) caps.strings = true;
511+
if (model.length > MAX_TRACE_STRING) caps.strings = true;
512+
if (typeof raw.accountRef === "string" && raw.accountRef.length > MAX_TRACE_STRING) caps.strings = true;
481513
if (typeof raw.eligible !== "boolean") return null;
482514
const exclusions = Array.isArray(raw.exclusions)
483-
? raw.exclusions.map(parseExclusion).filter((value): value is RouteExclusionReason => value !== null)
515+
? raw.exclusions.map(value => parseExclusion(value, caps)).filter((value): value is RouteExclusionReason => value !== null)
484516
: [];
485-
const capability = parseCapability(raw.capability);
517+
if (Array.isArray(raw.exclusions) && raw.exclusions.length > MAX_EXCLUSIONS_PER_CANDIDATE) caps.exclusions = true;
518+
const capability = parseCapability(raw.capability, caps);
486519
const health = parseHealth(raw.health);
487-
const quota = parseQuota(raw.quota);
488-
const cost = parseCost(raw.cost);
520+
const quota = parseQuota(raw.quota, caps);
521+
const cost = parseCost(raw.cost, caps);
489522
const score = parseScore(raw.score);
490523
return {
491524
provider: provider.slice(0, MAX_TRACE_STRING),
@@ -511,18 +544,22 @@ function parseCandidate(raw: unknown): RouteCandidateTrace | null {
511544
export function normalizeRouteDecisionTrace(raw: unknown): RouteDecisionTraceV1 | null {
512545
if (!isPlainRecord(raw)) return null;
513546
if (raw.version !== 1) return null;
547+
const caps: ParseCaps = {};
514548
const decisionId = raw.decisionId;
515549
const createdAt = raw.createdAt;
516550
const requestedModel = raw.requestedModel;
517551
const routeKind = raw.routeKind;
518552
if (typeof decisionId !== "string" || decisionId.length === 0) return null;
553+
if (decisionId.length > MAX_TRACE_STRING) caps.strings = true;
519554
if (!finiteNumber(createdAt)) return null;
520555
if (typeof requestedModel !== "string" || requestedModel.length === 0) return null;
556+
if (requestedModel.length > MAX_TRACE_STRING) caps.strings = true;
521557
if (typeof routeKind !== "string" || !ROUTE_KINDS.has(routeKind as RouteDecisionKind)) return null;
522558
if (!Array.isArray(raw.candidates) || raw.candidates.length === 0) return null;
559+
if (raw.candidates.length > MAX_TRACE_CANDIDATES) caps.candidates = true;
523560

524561
const candidates = raw.candidates
525-
.map(parseCandidate)
562+
.map(value => parseCandidate(value, caps))
526563
.filter((value): value is RouteCandidateTrace => value !== null)
527564
.slice(0, MAX_TRACE_CANDIDATES);
528565
if (candidates.length === 0) return null;
@@ -534,34 +571,42 @@ export function normalizeRouteDecisionTrace(raw: unknown): RouteDecisionTraceV1
534571
const selectedReason = selected.reason;
535572
if (typeof selectedProvider !== "string" || typeof selectedModel !== "string") return null;
536573
if (typeof selectedReason !== "string") return null;
574+
if (selectedProvider.length > MAX_TRACE_STRING) caps.strings = true;
575+
if (selectedModel.length > MAX_TRACE_STRING) caps.strings = true;
576+
if (selectedReason.length > MAX_TRACE_STRING) caps.strings = true;
577+
if (typeof selected.accountRef === "string" && selected.accountRef.length > MAX_TRACE_STRING) caps.strings = true;
578+
if (typeof selected.tieBreak === "string" && selected.tieBreak.length > MAX_TRACE_STRING) caps.strings = true;
537579
const candidateIndex = Number.isInteger(selected.candidateIndex)
538580
? selected.candidateIndex as number
539581
: 0;
540582
if (candidateIndex < 0 || candidateIndex >= candidates.length) return null;
541583

542-
const requirements = Array.isArray(raw.requirements)
543-
? raw.requirements.map(parseRequirement)
544-
.filter((value): value is RouteRequirementEvidence => value !== null)
545-
.slice(0, MAX_REQUIREMENTS)
546-
: [];
584+
const rawRequirements = Array.isArray(raw.requirements) ? raw.requirements : [];
585+
if (rawRequirements.length > MAX_REQUIREMENTS) caps.requirements = true;
586+
const requirements = rawRequirements
587+
.map(value => parseRequirement(value, caps))
588+
.filter((value): value is RouteRequirementEvidence => value !== null)
589+
.slice(0, MAX_REQUIREMENTS);
547590

548591
const profile = isPlainRecord(raw.profile)
549592
&& typeof raw.profile.id === "string"
550593
&& typeof raw.profile.revision === "string"
551-
? {
552-
id: raw.profile.id.slice(0, MAX_TRACE_STRING),
553-
revision: raw.profile.revision.slice(0, MAX_TRACE_STRING),
554-
}
594+
? (() => {
595+
if (raw.profile.id.length > MAX_TRACE_STRING) caps.strings = true;
596+
if (raw.profile.revision.length > MAX_TRACE_STRING) caps.strings = true;
597+
return {
598+
id: raw.profile.id.slice(0, MAX_TRACE_STRING),
599+
revision: raw.profile.revision.slice(0, MAX_TRACE_STRING),
600+
};
601+
})()
555602
: undefined;
556603

557-
const truncated = isPlainRecord(raw.truncated)
558-
? {
559-
...(raw.truncated.candidates === true ? { candidates: true as const } : {}),
560-
...(raw.truncated.exclusions === true ? { exclusions: true as const } : {}),
561-
...(raw.truncated.requirements === true ? { requirements: true as const } : {}),
562-
...(raw.truncated.strings === true ? { strings: true as const } : {}),
563-
}
564-
: undefined;
604+
const incoming = isPlainRecord(raw.truncated) ? raw.truncated : {};
605+
const truncated: RouteDecisionTraceV1["truncated"] = {};
606+
if (incoming.candidates === true || caps.candidates) truncated.candidates = true;
607+
if (incoming.exclusions === true || caps.exclusions) truncated.exclusions = true;
608+
if (incoming.requirements === true || caps.requirements) truncated.requirements = true;
609+
if (incoming.strings === true || caps.strings) truncated.strings = true;
565610

566611
return {
567612
version: 1,

‎src/server/responses/core.ts‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ import {
1616
previousResponseReplayFailure,
1717
rememberResponseState,
1818
} from "../../responses/state";
19-
import { routeModel, type RouteResult } from "../../router";
19+
import { comboRouteDecisionTrace, routeModel, type RouteResult } from "../../router";
2020
import {
2121
advanceComboAfterFailure,
2222
comboDefaultEffort,
@@ -966,6 +966,7 @@ export async function handleComboResponses(
966966
model: requestedModel,
967967
provider: "combo",
968968
comboId,
969+
routeDecision: logCtx.routeDecision,
969970
attempts: logCtx.attempts,
970971
activeAttempt: undefined,
971972
activeAttemptStartedAt: undefined,
@@ -1000,6 +1001,9 @@ export async function handleComboResponses(
10001001
if (!pick) {
10011002
return comboUnavailableResponse(`No available targets for combo: ${comboId}`);
10021003
}
1004+
// One immutable combo selection trace, before any child dispatch; child
1005+
// adoption below must never replace it with a concrete child route trace.
1006+
logCtx.routeDecision = comboRouteDecisionTrace(config, comboId, pick, requestedModel);
10031007

10041008
let lastFailure: Response | null = null;
10051009
while (pick) {
@@ -1103,6 +1107,7 @@ export async function handleComboResponses(
11031107
model: requestedModel,
11041108
provider: "combo",
11051109
comboId,
1110+
routeDecision: logCtx.routeDecision,
11061111
attempts: logCtx.attempts,
11071112
activeAttempt: attempt,
11081113
activeAttemptStartedAt: started,
@@ -1373,6 +1378,7 @@ async function handleResponsesInner(
13731378
let route: RouteResult;
13741379
try {
13751380
route = routeModel(config, parsed.modelId);
1381+
logCtx.routeDecision = route.routeDecision;
13761382
} catch (err) {
13771383
if (err instanceof NoAvailableComboTargetsError) {
13781384
return comboUnavailableResponse(err.message);

‎src/usage/log.ts‎

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -655,9 +655,11 @@ export function readRecentUsageEntries(limit: number): PersistedUsageEntry[] {
655655
fd = openSync(path, "r");
656656
const size = fstatSync(fd).size;
657657
if (size <= 0) return [];
658-
// ~4 KiB/row budget with a floor; expand once if the window yields too few lines.
659-
let windowBytes = Math.min(size, Math.max(64 * 1024, Math.ceil(limit) * 4 * 1024));
660-
for (let attempt = 0; attempt < 2; attempt++) {
658+
// Trace-sized rows (up to MAX_TRACE_BYTES, RI-01) need a larger per-row
659+
// budget than the pre-trace ledger; keep expanding until the window covers
660+
// the file start or the whole file so a restart never hydrates nothing.
661+
let windowBytes = Math.min(size, Math.max(64 * 1024, Math.ceil(limit) * 20 * 1024));
662+
while (true) {
661663
const start = Math.max(0, size - windowBytes);
662664
const buf = Buffer.alloc(size - start);
663665
readSync(fd, buf, 0, buf.length, start);
@@ -677,6 +679,7 @@ export function readRecentUsageEntries(limit: number): PersistedUsageEntry[] {
677679
// most recent N valid rows (not N physical lines minus corrupt ones).
678680
const entries = parseUsageLines(lines);
679681
if (entries.length >= limit || start === 0 || windowBytes >= size) return entries.slice(-limit);
682+
if (windowBytes >= size) break;
680683
windowBytes = Math.min(size, windowBytes * 4);
681684
}
682685
return [];

0 commit comments

Comments
 (0)