fix: require runtime evidence in budget gate

scripts/lib/bundle-budgets.d.mts

@@ -1,4 +1,8 @@
 export const PERFORMANCE_BUDGETS: Readonly<Record<string, number>>;
+export function resolveBudgetGateMode(options: {
+  transferOnly: boolean;
+  runtimeTracePath: string | null;
+}): { kind: 'transfer-only' } | { kind: 'full'; runtimeTracePath: string };
 export function classifyArtifact(path: string, source?: string): string;
 export function evaluateBudgetTotals(totals: Readonly<Record<string, number>>): {
   violations: Array<{ budget: string; actual: number; threshold: number }>;

scripts/lib/bundle-budgets.mjs

@@ -20,6 +20,13 @@ export const PERFORMANCE_BUDGETS = Object.freeze({
   highTierGpuEstimate: 192 * 1024 * 1024,
 });
 
+export const resolveBudgetGateMode = ({ transferOnly, runtimeTracePath }) => {
+  if (transferOnly && runtimeTracePath !== null) throw new Error('Transfer-only mode cannot be combined with runtime evidence.');
+  if (transferOnly) return { kind: 'transfer-only' };
+  if (runtimeTracePath === null) throw new Error('A runtime trace is required for the full performance budget gate. Use --transfer-only only for a non-gating static build check.');
+  return { kind: 'full', runtimeTracePath };
+};
+
 export const classifyArtifact = (path, source = '') => {
   if (path === 'index.html') return 'initial-html';
   if (/^assets\/index-[^/]+\.css$/u.test(path)) return 'critical-css';