@danypops/jittor 0.6.0 → 0.8.0

package/src/domain/usage.ts

@@ -1,5 +1,4 @@
 import { MAX_USAGE_BUCKETS, MILLISECONDS_PER_DAY, MILLISECONDS_PER_HOUR } from "../constants.ts";
-import type { StoredMetricObservation } from "./metric.ts";
 
 export const USAGE_PERIODS = [
 	{ id: "hourly", label: "Hourly", windowMs: MILLISECONDS_PER_HOUR, bucketCount: 12 },
@@ -14,6 +13,52 @@ export function usagePeriod(period: UsagePeriod): typeof USAGE_PERIODS[number] {
 	return USAGE_PERIODS.find((candidate) => candidate.id === period)!;
 }
 
+export function usagePeriodStart(period: UsagePeriod, now: number): number {
+	return Math.max(0, now - usagePeriod(period).windowMs);
+}
+
+/**
+ * The bucket boundaries a chart period actually renders. Shared, byte-identical, by both sides of
+ * the wire: the daemon computes the SAME window from the same (period, now[, bucketCount]) before
+ * running its SQL-side GROUP BY, so a pre-aggregated bucket sum always lands in exactly the bucket
+ * the chart expects -- there is no second, independent bucketing pass left to disagree with it.
+ */
+export interface UsageBucketWindow {
+	start: number;
+	end: number;
+	bucketCount: number;
+	bucketSizeMs: number;
+}
+
+export function resolveUsageWindow(period: UsagePeriod, now: number, bucketCount?: number): UsageBucketWindow {
+	const end = now;
+	const start = usagePeriodStart(period, end);
+	const requested = bucketCount ?? usagePeriod(period).bucketCount;
+	const count = Math.max(1, Math.min(MAX_USAGE_BUCKETS, Math.floor(requested)));
+	const bucketSizeMs = Math.max(1, (end - start) / count);
+	return { start, end, bucketCount: count, bucketSizeMs };
+}
+
+/** Mirrors the SQL-side `MIN(CAST((observed_at - start) / bucketSizeMs AS INTEGER), bucketCount - 1)` grouping exactly. */
+export function usageBucketIndex(observedAt: number, window: UsageBucketWindow): number {
+	return Math.min(window.bucketCount - 1, Math.max(0, Math.floor((observedAt - window.start) / window.bucketSizeMs)));
+}
+
+/**
+ * One already-summed (scope, metric, bucket) cell -- what the daemon's SQL-side GROUP BY returns,
+ * replacing a bounded-but-still-truncatable fetch of raw per-observation rows. Result size scales
+ * with (distinct scopes x distinct metrics x bucket count), never with raw event count, so a
+ * heavy scope's full history is represented exactly regardless of how many observations it made
+ * (a real incident: a scope with 49,270 rows in a week had its "weekly" chart built from the 250
+ * most recent rows alone -- 3.3 minutes of real activity mislabeled as a full week).
+ */
+export interface UsageAggregateRow {
+	scope: string;
+	metric: string;
+	bucketIndex: number;
+	sum: number;
+}
+
 export interface UsageSeries {
 	key: string;
 	provider: string;
@@ -48,8 +93,6 @@ export interface UsageGraph {
 
 export interface UsageGraphOptions {
 	period: UsagePeriod;
-	now: number;
-	bucketCount?: number;
 	truncated?: boolean;
 }
 
@@ -60,69 +103,52 @@ const BREAKDOWN_KEYS = {
 	"cache-write-tokens": "cacheWrite",
 } as const satisfies Record<string, keyof UsageBreakdown>;
 
-export function usagePeriodStart(period: UsagePeriod, now: number): number {
-	return Math.max(0, now - usagePeriod(period).windowMs);
-}
-
-export function identity(row: StoredMetricObservation): { key: string; provider: string; model: string } {
-	const separator = row.scope.indexOf(":");
-	const fallbackProvider = separator >= 0 ? row.scope.slice(0, separator) : row.scope;
-	const fallbackModel = separator >= 0 ? row.scope.slice(separator + 1) : "unknown";
-	const provider = typeof row.attributes["provider"] === "string" ? row.attributes["provider"] : fallbackProvider;
-	const model = typeof row.attributes["model"] === "string" ? row.attributes["model"] : fallbackModel;
+/**
+ * Derives provider/model from `scope` alone (`"${provider}:${model}"`, see assistantUsageMetrics),
+ * rather than needing a row's `attributes.provider`/`attributes.model` -- source "pi" always
+ * constructs `scope` from those exact same two values, so the two are equivalent for this source,
+ * and an aggregated bucket sum has no per-row attributes left to read anyway.
+ */
+export function identity(scope: string): { key: string; provider: string; model: string } {
+	const separator = scope.indexOf(":");
+	const provider = separator >= 0 ? scope.slice(0, separator) : scope;
+	const model = separator >= 0 ? scope.slice(separator + 1) : "unknown";
 	return { key: `${provider}/${model}`, provider, model };
 }
 
-interface BucketWindow { start: number; end: number; bucketCount: number; bucketSize: number }
-
-function bucketWindow(options: UsageGraphOptions): BucketWindow {
-	const end = options.now;
-	const start = usagePeriodStart(options.period, end);
-	const requestedBuckets = options.bucketCount ?? usagePeriod(options.period).bucketCount;
-	const bucketCount = Math.max(1, Math.min(MAX_USAGE_BUCKETS, Math.floor(requestedBuckets)));
-	const bucketSize = Math.max(1, (end - start) / bucketCount);
-	return { start, end, bucketCount, bucketSize };
-}
-
-function emptyBuckets(window: BucketWindow): { start: number; end: number; total: number; series: Record<string, number> }[] {
+function emptyBuckets(window: UsageBucketWindow): { start: number; end: number; total: number; series: Record<string, number> }[] {
 	return Array.from({ length: window.bucketCount }, (_, index) => ({
-		start: window.start + index * window.bucketSize,
-		end: index === window.bucketCount - 1 ? window.end : window.start + (index + 1) * window.bucketSize,
+		start: window.start + index * window.bucketSizeMs,
+		end: index === window.bucketCount - 1 ? window.end : window.start + (index + 1) * window.bucketSizeMs,
 		total: 0,
 		series: {},
 	}));
 }
 
-function bucketIndexFor(observedAt: number, window: BucketWindow): number {
-	return Math.min(window.bucketCount - 1, Math.floor((observedAt - window.start) / window.bucketSize));
-}
-
-export function buildUsageGraph(rows: StoredMetricObservation[], options: UsageGraphOptions): UsageGraph {
-	const window = bucketWindow(options);
-	const { start, end } = window;
+export function buildUsageGraph(rows: UsageAggregateRow[], window: UsageBucketWindow, options: UsageGraphOptions): UsageGraph {
 	const buckets: UsageBucket[] = emptyBuckets(window);
 	const breakdown: UsageBreakdown = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 };
 	const identities = new Map<string, UsageSeries>();
 
 	for (const row of rows) {
 		const breakdownKey = BREAKDOWN_KEYS[row.metric as keyof typeof BREAKDOWN_KEYS];
-		if (row.source !== "pi" || row.unit !== "tokens" || !breakdownKey || typeof row.value !== "number" || row.value < 0) continue;
-		if (row.observedAt < start || row.observedAt > end) continue;
-		const bucket = buckets[bucketIndexFor(row.observedAt, window)]!;
-		const series = identity(row);
-		bucket.total += row.value;
-		bucket.series[series.key] = (bucket.series[series.key] ?? 0) + row.value;
-		breakdown[breakdownKey] += row.value;
+		if (!breakdownKey || !Number.isFinite(row.sum) || row.sum < 0) continue;
+		if (!Number.isInteger(row.bucketIndex) || row.bucketIndex < 0 || row.bucketIndex >= buckets.length) continue;
+		const bucket = buckets[row.bucketIndex]!;
+		const series = identity(row.scope);
+		bucket.total += row.sum;
+		bucket.series[series.key] = (bucket.series[series.key] ?? 0) + row.sum;
+		breakdown[breakdownKey] += row.sum;
 		const current = identities.get(series.key) ?? { ...series, total: 0 };
-		current.total += row.value;
+		current.total += row.sum;
 		identities.set(series.key, current);
 	}
 
 	const series = [...identities.values()].sort((left, right) => right.total - left.total || left.key.localeCompare(right.key));
 	return {
 		period: options.period,
-		start,
-		end,
+		start: window.start,
+		end: window.end,
 		buckets,
 		series,
 		totalTokens: buckets.reduce((sum, bucket) => sum + bucket.total, 0),
@@ -162,29 +188,27 @@ export interface CostGraph {
  * surface from day one (alongside raw token counts), since token counts alone do not reflect that
  * output tokens and premium models cost disproportionately more per token.
  */
-export function buildCostGraph(rows: StoredMetricObservation[], options: UsageGraphOptions): CostGraph {
-	const window = bucketWindow(options);
-	const { start, end } = window;
+export function buildCostGraph(rows: UsageAggregateRow[], window: UsageBucketWindow, options: UsageGraphOptions): CostGraph {
 	const buckets: CostBucket[] = emptyBuckets(window);
 	const identities = new Map<string, CostSeries>();
 
 	for (const row of rows) {
-		if (row.source !== "pi" || row.unit !== "usd" || row.metric !== "cost" || typeof row.value !== "number" || row.value < 0) continue;
-		if (row.observedAt < start || row.observedAt > end) continue;
-		const bucket = buckets[bucketIndexFor(row.observedAt, window)]!;
-		const series = identity(row);
-		bucket.total += row.value;
-		bucket.series[series.key] = (bucket.series[series.key] ?? 0) + row.value;
+		if (row.metric !== "cost" || !Number.isFinite(row.sum) || row.sum < 0) continue;
+		if (!Number.isInteger(row.bucketIndex) || row.bucketIndex < 0 || row.bucketIndex >= buckets.length) continue;
+		const bucket = buckets[row.bucketIndex]!;
+		const series = identity(row.scope);
+		bucket.total += row.sum;
+		bucket.series[series.key] = (bucket.series[series.key] ?? 0) + row.sum;
 		const current = identities.get(series.key) ?? { ...series, total: 0 };
-		current.total += row.value;
+		current.total += row.sum;
 		identities.set(series.key, current);
 	}
 
 	const series = [...identities.values()].sort((left, right) => right.total - left.total || left.key.localeCompare(right.key));
 	return {
 		period: options.period,
-		start,
-		end,
+		start: window.start,
+		end: window.end,
 		buckets,
 		series,
 		totalUsd: buckets.reduce((sum, bucket) => sum + bucket.total, 0),

package/src/log.ts

@@ -0,0 +1,28 @@
+/**
+ * Structured daemon logging, now backed by `@danypops/daemon-kit/logging` (pino) instead of a
+ * hand-rolled `console.error(JSON.stringify(...))` -- daemon-kit's own module doc explains why:
+ * level ordering/filtering/child-scoping is exactly the kind of thing worth one shared,
+ * dependency-backed implementation instead of four independent hand-rolled ones. One deliberate,
+ * disclosed shape change from jittor's old bespoke format: the event name is now pino's `msg`
+ * field rather than a separate `event` field, matching daemon-kit's shared convention across all
+ * four daemons. `component`/`level`/`timestamp` and credential-safety (callers still must pass
+ * only bounded, non-sensitive fields) are unchanged.
+ */
+import { createLogger, type LogLevel as DaemonKitLogLevel, type Logger } from "@danypops/daemon-kit/logging";
+
+export type LogLevel = Extract<DaemonKitLogLevel, "info" | "warn" | "error">;
+
+/**
+ * Also passed directly as `StartDaemonOptions.logger` so daemon-kit's own maintenance-task
+ * failure logging shares this same sink/shape. `destination` is pinned to `console.error` rather
+ * than daemon-kit's own default (a raw fd 2 write via `pino.destination(2)`, which bypasses
+ * `console.error` entirely) so existing tooling/tests that intercept `console.error` keep working.
+ */
+export const logger: Logger = createLogger("jittor-daemon", {
+	destination: { write: (chunk: string) => { console.error(chunk.replace(/\n$/, "")); return true; } },
+});
+
+/** Credential-safe structured daemon event. Callers must pass bounded, non-sensitive fields. */
+export function logEvent(level: LogLevel, event: string, fields: Record<string, unknown> = {}): void {
+	logger[level](event, fields);
+}

package/src/ports/metric-store.ts

@@ -1,8 +1,38 @@
+import type { UsageAggregateRow } from "../domain/usage.ts";
 import type { MetricObservation, MetricQuery, StoredMetricObservation } from "../domain/metric.ts";
 
+export interface DistinctScopesFilter {
+	source: string;
+	since: number;
+	until: number;
+	limit: number;
+}
+
+export interface UsageAggregateFilter {
+	source: string;
+	/** Only these scopes are summed -- callers pass the bounded result of distinctScopes, so a real explosion of distinct scopes truncates honestly instead of this method silently discovering and aggregating an unbounded set on its own. */
+	scopes: string[];
+	since: number;
+	until: number;
+	bucketSizeMs: number;
+	bucketCount: number;
+}
+
 export interface MetricStore {
 	record(observation: MetricObservation): StoredMetricObservation;
 	query(filter?: MetricQuery): StoredMetricObservation[];
+	/** Bounded distinct scope values for a source within a time window, so callers can fetch a fair share per scope instead of one flat query a single heavy scope could monopolize. */
+	distinctScopes(filter: DistinctScopesFilter): string[];
+	/**
+	 * SQL-side (scope, metric, bucket) sums for a bounded scope list -- result size scales with
+	 * (scopes x distinct metrics x buckets), never with raw event count, so a heavy scope's full
+	 * history is represented exactly regardless of how many observations fed it. Replaces fetching
+	 * up to a fixed number of raw rows per scope, which could silently truncate a single heavy
+	 * scope's own older history within the requested window (a real incident: a scope with 49,270
+	 * rows in a week had its "weekly" chart built from the 250 most recent rows alone -- 3.3
+	 * minutes of real activity mislabeled as a full week).
+	 */
+	aggregateUsage(filter: UsageAggregateFilter): UsageAggregateRow[];
 	pruneBefore(cutoff: number): number;
 	checkpoint(): void;
 	close(): void;

package/src/providers/anthropic-contracts.ts

@@ -27,6 +27,7 @@ export interface AnthropicRateLimitSnapshot {
 }
 
 function metric(
+	source: AnthropicMetricSource,
 	scope: string,
 	name: string,
 	value: number,
@@ -34,7 +35,7 @@ function metric(
 	observedAt: number,
 	attributes: Record<string, unknown> = {},
 ): MetricObservation {
-	return { source: "anthropic", scope, metric: name, value, unit, observedAt, attributes };
+	return { source, scope, metric: name, value, unit, observedAt, attributes };
 }
 
 function headerInteger(headers: Headers, name: string): number | null {
@@ -61,20 +62,30 @@ function parseWindow(headers: Headers, prefix: string): AnthropicRateLimitWindow
 	return { limit, remaining, resetsAt };
 }
 
-function windowMetrics(scope: string, window: AnthropicRateLimitWindow | null, observedAt: number): MetricObservation[] {
+function windowMetrics(source: AnthropicMetricSource, scope: string, window: AnthropicRateLimitWindow | null, observedAt: number): MetricObservation[] {
 	if (!window) return [];
 	const metrics: MetricObservation[] = [];
 	const attributes = { limit: window.limit, remaining: window.remaining, resetsAt: window.resetsAt };
 	if (window.limit !== null && window.limit > 0 && window.remaining !== null) {
 		const remainingFraction = window.remaining / window.limit;
 		if (remainingFraction < 0 || remainingFraction > 1) throw new Error(`Anthropic ${scope} remaining exceeds its configured limit`);
-		metrics.push(metric(scope, "remaining-fraction", remainingFraction, "ratio", observedAt, attributes));
-		metrics.push(metric(scope, "used-fraction", 1 - remainingFraction, "ratio", observedAt, attributes));
+		metrics.push(metric(source, scope, "remaining-fraction", remainingFraction, "ratio", observedAt, attributes));
+		metrics.push(metric(source, scope, "used-fraction", 1 - remainingFraction, "ratio", observedAt, attributes));
 	}
 	return metrics;
 }
 
-export function parseAnthropicRateLimitHeaders(headers: Headers, observedAt = Date.now()): AnthropicRateLimitSnapshot {
+/**
+ * Direct Anthropic API calls and Anthropic-on-Vertex passthroughs (e.g. the third-party
+ * `@twogiants/pi-anthropic-vertex` extension, which reuses Pi's built-in Anthropic Messages stream
+ * with Anthropic's own `@anthropic-ai/vertex-sdk` client) may both emit this same header shape, but
+ * they are different accounts against different quota pools -- Anthropic's own org-scoped buckets
+ * vs whatever a Vertex project's passthrough exposes, if anything. Tagging the metric source keeps
+ * them from ever being blended into one budget reading.
+ */
+export type AnthropicMetricSource = "anthropic" | "anthropic-vertex";
+
+export function parseAnthropicRateLimitHeaders(headers: Headers, observedAt = Date.now(), source: AnthropicMetricSource = "anthropic"): AnthropicRateLimitSnapshot {
 	const requests = parseWindow(headers, "anthropic-ratelimit-requests");
 	const tokens = parseWindow(headers, "anthropic-ratelimit-tokens");
 	const inputTokens = parseWindow(headers, "anthropic-ratelimit-input-tokens");
@@ -96,12 +107,12 @@ export function parseAnthropicRateLimitHeaders(headers: Headers, observedAt = Da
 		retryAfterMs: retryAfterSeconds === null ? null : Math.round(retryAfterSeconds * 1_000),
 		observedAt,
 		metrics: [
-			...windowMetrics("requests", requests, observedAt),
-			...windowMetrics("tokens", tokens, observedAt),
-			...windowMetrics("input-tokens", inputTokens, observedAt),
-			...windowMetrics("output-tokens", outputTokens, observedAt),
-			...windowMetrics("priority-input-tokens", priorityInputTokens, observedAt),
-			...windowMetrics("priority-output-tokens", priorityOutputTokens, observedAt),
+			...windowMetrics(source, "requests", requests, observedAt),
+			...windowMetrics(source, "tokens", tokens, observedAt),
+			...windowMetrics(source, "input-tokens", inputTokens, observedAt),
+			...windowMetrics(source, "output-tokens", outputTokens, observedAt),
+			...windowMetrics(source, "priority-input-tokens", priorityInputTokens, observedAt),
+			...windowMetrics(source, "priority-output-tokens", priorityOutputTokens, observedAt),
 		],
 	};
 }

package/src/providers/google-adc-auth.ts

@@ -0,0 +1,63 @@
+import { GoogleAuth } from "google-auth-library";
+import { GOOGLE_ADC_TOKEN_REFRESH_SKEW_MS } from "../constants.ts";
+
+/**
+ * The only file in Jittor that imports `google-auth-library` (Jittor's first runtime dependency;
+ * see docs/PROVIDER_RESEARCH.md for why ADC token acquisition -- not the Vertex/Budget API
+ * surface itself -- is the one piece worth a mature dependency instead of hand-rolling: it is
+ * security-sensitive OAuth/JWT/metadata-server protocol code, the exact class of thing the
+ * project's own off-the-shelf-modules guidance calls out as worth not reimplementing).
+ *
+ * This matches the individual-GCP-project migration's "passwordless/keyless" model: Application
+ * Default Credentials (a user's own `gcloud auth application-default login` session, a Compute/
+ * Cloud Run metadata identity, or Workload Identity Federation), never a static service-account
+ * key file. `google-auth-library` auto-detects which of those applies to the environment it runs
+ * in; Jittor does not choose or configure a credential type itself.
+ */
+export type GoogleAdcTokenProvider = () => Promise<string>;
+
+/** The minimal shape this module actually calls on an ADC client; matches google-auth-library's real `AuthClient`/`Credentials` fields (verified against its published `.d.ts`), kept narrow so tests can inject a fake without constructing a real `GoogleAuth`. */
+export interface GoogleAdcClient {
+	getAccessToken(): Promise<{ token?: string | null }>;
+	credentials?: { expiry_date?: number | null };
+}
+
+export type GoogleAdcClientFactory = (scopes: readonly string[]) => Promise<GoogleAdcClient>;
+
+async function defaultAdcClientFactory(scopes: readonly string[]): Promise<GoogleAdcClient> {
+	return new GoogleAuth({ scopes: [...scopes] }).getClient();
+}
+
+/**
+ * Wraps ADC token acquisition with the caching every other Jittor provider adapter skips
+ * only because their upstreams don't require an OAuth exchange per call: a fresh Google access
+ * token is valid for roughly an hour, and re-deriving ADC (which may itself make a metadata-server
+ * or token-exchange network call) on every poll would be wasteful and, for some ADC sources,
+ * rate-limited. `GOOGLE_ADC_TOKEN_REFRESH_SKEW_MS` triggers a refresh slightly before Google
+ * itself would consider the cached token invalid.
+ */
+export function createGoogleAdcTokenProvider(
+	scopes: readonly string[],
+	clock: () => number = Date.now,
+	clientFactory: GoogleAdcClientFactory = defaultAdcClientFactory,
+): GoogleAdcTokenProvider {
+	let cachedClient: GoogleAdcClient | undefined;
+	let cachedToken: string | undefined;
+	let cachedExpiryEpochMs = 0;
+
+	return async function getAccessToken(): Promise<string> {
+		const now = clock();
+		if (cachedToken && now < cachedExpiryEpochMs - GOOGLE_ADC_TOKEN_REFRESH_SKEW_MS) return cachedToken;
+		cachedClient ??= await clientFactory(scopes);
+		const { token } = await cachedClient.getAccessToken();
+		if (!token) throw new Error("Google Application Default Credentials did not return an access token");
+		// `credentials.expiry_date` is the verified google-auth-library field (epoch ms). When a
+		// credential type doesn't report one, this deliberately does not fabricate an assumed TTL --
+		// it treats the token as already due for refresh, so the next call re-fetches rather than
+		// caching for a guessed duration.
+		const expiryDate = cachedClient.credentials?.expiry_date;
+		cachedToken = token;
+		cachedExpiryEpochMs = typeof expiryDate === "number" ? expiryDate : now;
+		return token;
+	};
+}

package/src/providers/google-vertex-budget-contracts.ts

@@ -0,0 +1,181 @@
+import type { BudgetWindow } from "../policy.ts";
+import type { MetricObservation } from "../domain/metric.ts";
+import type { GoogleVertexMetricSource } from "./google-vertex-contracts.ts";
+import {
+	GOOGLE_VERTEX_BUDGET_CONFIDENCE,
+	GOOGLE_VERTEX_BUDGET_DISPLAY_NAME_MAX_CHARACTERS,
+	MILLISECONDS_PER_SECOND,
+} from "../constants.ts";
+
+/**
+ * Cloud Billing's programmatic budget notification schema (Pub/Sub attributes + base64 JSON data
+ * body), verified against
+ * https://docs.cloud.google.com/billing/docs/how-to/budgets-programmatic-notifications#notification-format
+ * and the worked example in
+ * https://docs.cloud.google.com/billing/docs/how-to/listen-to-notifications (fetched 2026-07-23).
+ * This is the individual-GCP-project era's real hot(ish)-path budget signal Google documents:
+ * "Budget notifications are sent to the Pub/Sub topic multiple times per day with the current
+ * status of your budget", unlike the per-response rate-limit header Vertex generateContent itself
+ * does not expose (see google-vertex-contracts.ts). Two honesty caveats the docs are explicit
+ * about and this module must not paper over: (1) "Budgets use estimated Cloud Billing data which
+ * is subject to change until your invoice is finalized" and (2) "Pub/Sub only provides
+ * at-least-once delivery. You might receive a message multiple times, and messages might arrive
+ * out of order."
+ */
+export type GoogleVertexBudgetAmountType = "SPECIFIED_AMOUNT" | "LAST_MONTH_COST" | "LAST_PERIODS_COST";
+
+export interface GoogleVertexBudgetNotification {
+	billingAccountId: string;
+	budgetId: string;
+	schemaVersion: string;
+	budgetDisplayName: string;
+	costAmount: number;
+	costIntervalStart: number;
+	budgetAmount: number;
+	budgetAmountType: GoogleVertexBudgetAmountType;
+	currencyCode: string;
+	alertThresholdExceeded?: number;
+	forecastThresholdExceeded?: number;
+	publishedAt: number;
+}
+
+const BUDGET_AMOUNT_TYPES: readonly GoogleVertexBudgetAmountType[] = ["SPECIFIED_AMOUNT", "LAST_MONTH_COST", "LAST_PERIODS_COST"];
+
+function requiredString(value: unknown, name: string, maxLength = 512): string {
+	if (typeof value !== "string" || value.length === 0 || value.length > maxLength) {
+		throw new Error(`Google Vertex budget notification schema changed: ${name}`);
+	}
+	return value;
+}
+
+function requiredFiniteNumber(value: unknown, name: string): number {
+	if (typeof value !== "number" || !Number.isFinite(value)) throw new Error(`Google Vertex budget notification schema changed: ${name}`);
+	return value;
+}
+
+function requiredTimestamp(value: unknown, name: string): number {
+	const parsed = typeof value === "string" ? Date.parse(value) : Number.NaN;
+	if (Number.isNaN(parsed)) throw new Error(`Google Vertex budget notification schema changed: ${name} is not RFC 3339`);
+	return parsed;
+}
+
+function optionalFraction(value: unknown, name: string): number | undefined {
+	if (value === undefined) return undefined;
+	if (typeof value !== "number" || !Number.isFinite(value) || value < 0) throw new Error(`Google Vertex budget notification schema changed: ${name}`);
+	return value;
+}
+
+/**
+ * Parses one already-base64-decoded, JSON-parsed notification body plus its Pub/Sub message
+ * attributes (`billingAccountId`, `budgetId`, `schemaVersion`) and the message's own
+ * `publishTime`. Fails closed (throws) on any missing/mistyped field, matching the
+ * `classifyGoogleVertexFailure`/Anthropic header-parsing convention: an unrecognized shape must
+ * never be silently coerced into a plausible-looking budget number.
+ */
+export function parseGoogleVertexBudgetNotification(
+	data: unknown,
+	attributes: { billingAccountId?: unknown; budgetId?: unknown; schemaVersion?: unknown },
+	publishedAt: number,
+): GoogleVertexBudgetNotification {
+	if (typeof data !== "object" || data === null || Array.isArray(data)) throw new Error("Google Vertex budget notification schema changed: data");
+	const input = data as Record<string, unknown>;
+	if (!Number.isFinite(publishedAt) || publishedAt < 0) throw new Error("Google Vertex budget notification schema changed: publishTime");
+
+	const budgetAmountType = requiredString(input["budgetAmountType"], "budgetAmountType");
+	if (!BUDGET_AMOUNT_TYPES.includes(budgetAmountType as GoogleVertexBudgetAmountType)) {
+		throw new Error("Google Vertex budget notification schema changed: budgetAmountType");
+	}
+
+	return {
+		billingAccountId: requiredString(attributes.billingAccountId, "billingAccountId"),
+		budgetId: requiredString(attributes.budgetId, "budgetId"),
+		schemaVersion: requiredString(attributes.schemaVersion, "schemaVersion"),
+		budgetDisplayName: requiredString(input["budgetDisplayName"], "budgetDisplayName", GOOGLE_VERTEX_BUDGET_DISPLAY_NAME_MAX_CHARACTERS),
+		costAmount: requiredFiniteNumber(input["costAmount"], "costAmount"),
+		costIntervalStart: requiredTimestamp(input["costIntervalStart"], "costIntervalStart"),
+		budgetAmount: requiredFiniteNumber(input["budgetAmount"], "budgetAmount"),
+		budgetAmountType: budgetAmountType as GoogleVertexBudgetAmountType,
+		currencyCode: requiredString(input["currencyCode"], "currencyCode", 8),
+		alertThresholdExceeded: optionalFraction(input["alertThresholdExceeded"], "alertThresholdExceeded"),
+		forecastThresholdExceeded: optionalFraction(input["forecastThresholdExceeded"], "forecastThresholdExceeded"),
+		publishedAt,
+	};
+}
+
+/**
+ * Real dollar figures from Google, not a fabricated fraction: `spend`/`cap` are the two numbers
+ * the notification actually carries, and `spend-fraction` is their honest quotient (which the
+ * BudgetWindow below separately clamps to 1 for policy purposes -- this raw metric intentionally
+ * is not clamped, so a genuine over-cap soft-quota period stays visible in the metrics history).
+ */
+export function googleVertexBudgetMetrics(
+	notification: GoogleVertexBudgetNotification,
+	observedAt: number,
+	source: GoogleVertexMetricSource = "google-vertex",
+): MetricObservation[] {
+	const attributes: Record<string, unknown> = {
+		billingAccountId: notification.billingAccountId,
+		budgetId: notification.budgetId,
+		budgetDisplayName: notification.budgetDisplayName,
+		budgetAmountType: notification.budgetAmountType,
+		currencyCode: notification.currencyCode,
+		...(notification.alertThresholdExceeded !== undefined ? { alertThresholdExceeded: notification.alertThresholdExceeded } : {}),
+		...(notification.forecastThresholdExceeded !== undefined ? { forecastThresholdExceeded: notification.forecastThresholdExceeded } : {}),
+	};
+	const metrics: MetricObservation[] = [
+		{ source, scope: "budget", metric: "spend", value: notification.costAmount, unit: "usd", observedAt, attributes },
+		{ source, scope: "budget", metric: "cap", value: notification.budgetAmount, unit: "usd", observedAt, attributes },
+	];
+	if (notification.budgetAmount > 0) {
+		metrics.push({ source, scope: "budget", metric: "spend-fraction", value: notification.costAmount / notification.budgetAmount, unit: "ratio", observedAt, attributes });
+	}
+	return metrics;
+}
+
+/**
+ * Cloud Billing's notification payload does not carry the budget's configured calendar period
+ * (month/quarter/year/custom); the Budget resource itself defaults to a monthly period when
+ * unset (see the Budget REST resource docs), and this is what Cloud Billing budgets default to
+ * and what the P&GE individual-project migration documents ("The $500 quota limit is a monthly
+ * limit"). Calendar periods reset "at 12 AM US and Canadian Pacific Time (UTC-8)" per Google's
+ * own documented wording -- a fixed offset, not DST-aware America/Los_Angeles -- so this mirrors
+ * that literal documented rule rather than a locale-aware guess.
+ */
+const PACIFIC_FIXED_OFFSET_MS = 8 * 60 * 60 * MILLISECONDS_PER_SECOND;
+
+function nextPacificCalendarMonthStart(epochMs: number): number {
+	const pacific = new Date(epochMs - PACIFIC_FIXED_OFFSET_MS);
+	const nextMonthStartPacific = Date.UTC(pacific.getUTCFullYear(), pacific.getUTCMonth() + 1, 1, 0, 0, 0, 0);
+	return nextMonthStartPacific + PACIFIC_FIXED_OFFSET_MS;
+}
+
+/**
+ * Builds the BudgetWindow the routing policy consumes. Returns null (no window, not a fabricated
+ * one) when `budgetAmount` isn't a usable positive cap. `usedFraction` is clamped to 1 for the
+ * policy-facing window even when real spend has exceeded a soft-quota cap (the P&GE rollout keeps
+ * serving requests past 100% during its soft-quota phase) -- clamping a known-to-be->=100% real
+ * number to the window's documented [0,1] invariant is not fabrication; the unclamped truth is
+ * still recorded by `googleVertexBudgetMetrics`'s `spend-fraction`.
+ */
+export function googleVertexBudgetWindow(
+	notification: GoogleVertexBudgetNotification,
+	observedAt: number,
+	source: GoogleVertexMetricSource = "google-vertex",
+): BudgetWindow | null {
+	if (notification.budgetAmount <= 0) return null;
+	const resetsAt = nextPacificCalendarMonthStart(notification.costIntervalStart);
+	const windowSeconds = (resetsAt - notification.costIntervalStart) / MILLISECONDS_PER_SECOND;
+	if (windowSeconds <= 0) return null;
+	const usedFraction = Math.min(1, Math.max(0, notification.costAmount / notification.budgetAmount));
+	return {
+		id: `google-vertex-budget:${notification.budgetId}@${observedAt}`,
+		source,
+		scope: `budget:${notification.budgetId}`,
+		usedFraction,
+		windowSeconds,
+		resetsAt,
+		observedAt,
+		freshness: "fresh",
+		confidence: GOOGLE_VERTEX_BUDGET_CONFIDENCE,
+	};
+}