@stacksjs/ts-cloud 0.7.108 → 0.7.109

package/dist/spend/service.d.ts

@@ -0,0 +1,129 @@
+/**
+ * The spend service: one object that runs a full cycle.
+ *
+ * Everything below it is pure or a plain store, which is what makes the
+ * subsystem testable. This is the seam where they meet: ingest usage, evaluate
+ * every budget that governs a scope, apply or lift enforcement, and look for
+ * anomalies - in that order, because enforcement decisions should be made
+ * against the usage we just recorded, not the previous cycle's.
+ */
+import type { TelemetryRecord } from '../telemetry';
+import type { AnomalyOptions } from './anomaly';
+import type { EnforcementApplier, EnforcementPolicy, EnforcementReleaser, EnforcementRunResult } from './enforcement';
+import type { Budget, EnforcementAction, SpendAnomaly, SpendDecision, UsageDelta } from './model';
+import type { IngestResult, SpendStore, UsageSummary } from './store';
+import { AnomalyConfigStore } from './anomaly-config';
+import { SignalSource } from './signals';
+export interface SpendCycleOptions {
+    organizationId: string;
+    projectId?: string;
+    environmentId?: string;
+    /** Environment kind, so production can require approval for visible actions. */
+    environmentKind?: string;
+    now?: Date;
+    policy?: EnforcementPolicy;
+    handlers?: {
+        apply: EnforcementApplier;
+        release: EnforcementReleaser;
+    };
+}
+export interface BudgetStatus {
+    budget: Budget;
+    decision: SpendDecision;
+    summary: UsageSummary;
+    /** Enforcement currently in force for this budget. */
+    activeActions: EnforcementAction[];
+    /** Plain-language time until the cap, e.g. `2d 4h`. Empty when not projected. */
+    timeToCap: string;
+}
+export interface SpendCycleResult {
+    organizationId: string;
+    statuses: BudgetStatus[];
+    /** Strictest outcome across every governing budget. */
+    level: SpendDecision['level'];
+    actions: EnforcementAction[];
+    releases: EnforcementAction[];
+    enforcement: EnforcementRunResult[];
+    anomalies: SpendAnomaly[];
+    evaluatedAt: string;
+}
+export declare class SpendService {
+    private readonly store;
+    private readonly counters;
+    private readonly breaching;
+    /** Per-scope detector tuning and silences. Optional: detection works without it. */
+    readonly anomalyConfigs: AnomalyConfigStore;
+    /** Sources every detectable series: usage rollups and request telemetry. */
+    readonly signals: SignalSource;
+    constructor(store: SpendStore);
+    /** Meter a telemetry batch and fold it into the rollups. */
+    ingestTelemetry(organizationId: string, records: readonly TelemetryRecord[], defaultProvider?: string): IngestResult;
+    /** Fold pre-computed usage in directly. For collectors that already meter. */
+    ingestUsage(deltas: readonly UsageDelta[], aggregate?: boolean): IngestResult;
+    /** Evaluate one budget without touching enforcement. Safe to call anywhere. */
+    status(budget: Budget, now?: Date): BudgetStatus;
+    /**
+     * Run a full cycle for a scope.
+     *
+     * Without `handlers` this evaluates and records but applies nothing - the
+     * read-only mode a dashboard or a `--dry-run` CLI wants.
+     */
+    runCycle(options: SpendCycleOptions): Promise<SpendCycleResult>;
+    /**
+     * Grace-period bookkeeping.
+     *
+     * The clock starts when a budget first wants a non-notify action and is
+     * cleared the moment it stops. Keeping it here rather than in the database
+     * is deliberate: a grace period that survives a control-plane restart would
+     * let a long-resolved blip enforce hours later.
+     */
+    private trackBreach;
+    /**
+     * Look for an anomalous hour in the trailing cost series.
+     *
+     * Runs over a fixed 14-day lookback rather than the budget window: a monthly
+     * budget on day 2 has no history to speak of, and the seasonal baseline needs
+     * several same-phase observations before it means anything.
+     */
+    /**
+     * Look for anomalies across every detectable signal.
+     *
+     * Runs over a fixed 14-day lookback rather than the budget window: a monthly
+     * budget on day 2 has no history to speak of, and a seasonal baseline needs
+     * several same-phase observations before it means anything. Only complete
+     * hours are judged, since a partial hour always reads low.
+     *
+     * Per-route detection is opt-in through `routes`, and bounded to the busiest
+     * few. A long tail of one-hit routes produces noise rather than insight, and
+     * the routes that matter are the ones with enough traffic for a baseline.
+     */
+    detectAnomalies(options: SpendCycleOptions & {
+        signals?: string[];
+        routes?: boolean;
+    }, now?: Date, overrides?: AnomalyOptions): SpendAnomaly[];
+    /** Detect on one signal in one scope. Returns at most one anomaly per call. */
+    private detectSignal;
+    /**
+     * The payload behind the usage API.
+     *
+     * Shaped for a caller that has to decide something - an agent asking "can I
+     * afford this deploy?" needs the remaining headroom and the projection, not
+     * a pile of rollup rows.
+     */
+    usageReport(options: {
+        organizationId: string;
+        projectId?: string;
+        environmentId?: string;
+        period?: Budget['period'];
+        timezone?: string;
+        now?: Date;
+    }): Record<string, unknown>;
+}
+/** Insert zero-cost buckets for hours with no usage, so seasonal phases line up. */
+export declare function zeroFill(points: ReadonlyArray<{
+    bucketStart: string;
+    value: number;
+}>, from: string, to: string, maxBuckets?: number): Array<{
+    bucketStart: string;
+    value: number;
+}>;

package/dist/spend/signals.d.ts

@@ -0,0 +1,110 @@
+import type { ControlPlaneStore } from '../control-plane';
+import type { SeriesPoint } from './anomaly';
+import type { SpendStore } from './store';
+/** How an empty bucket should be treated. See rule 1 above. */
+export type GapPolicy = 'zero' | 'gap';
+export interface SignalDefinition {
+    key: string;
+    label: string;
+    /** `cost` and meters come from usage rollups; the rest from telemetry. */
+    source: 'usage' | 'telemetry';
+    gapPolicy: GapPolicy;
+    /**
+     * Minimum observations in a bucket before its value is trusted.
+     * Zero for counts - a count of three is still exactly three.
+     */
+    minSamples: number;
+    /** Units for the operator-facing floor, so `minAbsoluteDelta` reads sensibly. */
+    unit: string;
+    /** True when the signal is a ratio in 0-1. */
+    ratio?: boolean;
+}
+/**
+ * The signals detection can run on.
+ *
+ * Deliberately short. Every signal here is one an operator can act on: a spike
+ * in 5xx, a collapse in throughput, a latency regression, a cost jump. Adding
+ * signals nobody would act on makes the dashboard noisier without making
+ * anything safer.
+ */
+export declare const DETECTABLE_SIGNALS: readonly SignalDefinition[];
+export declare function signalDefinition(key: string): SignalDefinition | undefined;
+export interface SignalScope {
+    organizationId: string;
+    projectId?: string;
+    environmentId?: string;
+    /** Restrict to one route template, for per-route detection. */
+    route?: string;
+}
+export interface SignalWindow {
+    from: string;
+    to: string;
+}
+/** A series plus what it took to build it, so a caller can judge the verdict. */
+export interface SignalSeries {
+    signal: string;
+    points: SeriesPoint[];
+    /** Buckets that carried enough observations to be trusted. */
+    populated: number;
+    /** Buckets dropped for falling under `minSamples`. */
+    suppressed: number;
+    unit: string;
+}
+export declare class SignalSource {
+    private readonly controlPlane;
+    private readonly spend;
+    constructor(controlPlane: ControlPlaneStore, spend: SpendStore);
+    private query;
+    /** Usage-backed series: cost, or one meter's quantity. */
+    private usageSeries;
+    /**
+     * Telemetry-backed series, aggregated in SQL.
+     *
+     * Request records are the source rather than pre-aggregated metrics, because
+     * a ratio has to be computed from the same rows on both sides. Dividing a
+     * request-count metric by an error-count metric collected separately gives a
+     * rate that is wrong whenever the two were sampled differently.
+     */
+    private telemetrySeries;
+    /**
+     * p95 latency per hour.
+     *
+     * Computed with a window function rather than by pulling durations into
+     * memory: a busy hour is hundreds of thousands of rows, and the point of
+     * doing this in SQL is not having to hold them.
+     */
+    private latencySeries;
+    /** The series for one signal. Returns an all-gap series for an unknown one. */
+    series(signal: string, scope: SignalScope, window: SignalWindow): SignalSeries;
+    /**
+     * Route templates worth evaluating individually.
+     *
+     * Bounded and ordered by traffic: per-route detection on a long tail of
+     * one-hit routes produces noise, not insight, and the routes that matter are
+     * the ones carrying enough traffic for a baseline to exist.
+     */
+    busiestRoutes(scope: SignalScope, window: SignalWindow, limit?: number, minRequests?: number): string[];
+}
+/**
+ * Detector options per signal.
+ *
+ * The floors are in each signal's own units, which is the only way they mean
+ * anything: 25 cents, 1,000 requests, and 2 percentage points are all "small
+ * enough to ignore" for their signal and nonsense for the others.
+ */
+export declare function optionsForSignal(signal: string): {
+    seasonLength: number;
+    threshold: number;
+    minHistory: number;
+    minAbsoluteDelta: number;
+    detectDrops: boolean;
+};
+/**
+ * How far back a signal needs to look.
+ *
+ * A weekly season with three same-phase observations needs three weeks of
+ * history, not two. A fixed 14-day lookback silently starves every weekly
+ * signal: the detector finds two prior points, falls under `minHistory`, and
+ * reports nothing forever while looking perfectly healthy.
+ */
+export declare function lookbackHoursForSignal(signal: string): number;

package/dist/spend/signals.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/spend/sms-sdk.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/spend/spend.integration.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/spend/store.d.ts

@@ -0,0 +1,166 @@
+import type { ControlPlaneStore, JsonValue } from '../control-plane';
+import type { PriceBook } from './pricing';
+import type { Budget, BudgetPeriod, BudgetThreshold, EnforcementAction, EnforcementRecord, EnforcementState, MeterKey, SpendAnomaly, SpendDecision, UsageDelta, UsageRollup } from './model';
+import { budgetWindow } from './window';
+/** Collapse a nullable scope into a non-empty string for uniqueness purposes. */
+export declare function scopeKey(organizationId: string, projectId?: string, environmentId?: string): string;
+export interface CreateBudgetInput {
+    organizationId: string;
+    projectId?: string;
+    environmentId?: string;
+    name: string;
+    period: BudgetPeriod;
+    timezone?: string;
+    currency?: string;
+    softLimitCents?: number;
+    hardLimitCents?: number;
+    thresholds?: BudgetThreshold[];
+    meters?: MeterKey[];
+    graceSeconds?: number;
+    hysteresisPercent?: number;
+    dryRun?: boolean;
+    enabled?: boolean;
+}
+export interface UsageQuery {
+    organizationId: string;
+    projectId?: string;
+    environmentId?: string;
+    resourceId?: string;
+    meters?: MeterKey[];
+    providers?: string[];
+    from: string;
+    to: string;
+}
+export interface UsageTotal {
+    meter: MeterKey;
+    provider: string;
+    quantity: number;
+    costCents: number;
+    sampleCount: number;
+}
+export interface UsageSummary {
+    from: string;
+    to: string;
+    totalCents: number;
+    byMeter: UsageTotal[];
+    /** Hourly cost series across the window, ascending. Drives projection and anomalies. */
+    series: Array<{
+        bucketStart: string;
+        costCents: number;
+        quantity: number;
+    }>;
+}
+export interface IngestResult {
+    applied: number;
+    duplicates: number;
+    costCents: number;
+    unpricedMeters: string[];
+}
+/**
+ * The default ladder, used when a budget declares no thresholds of its own.
+ *
+ * The shape is deliberate: warn early and twice, act only at the limit, and
+ * make the projection rung fire before the actual one. A project that is on
+ * track to blow its cap in three days is far cheaper to fix than one that
+ * already has.
+ */
+export declare const DEFAULT_THRESHOLDS: readonly BudgetThreshold[];
+export declare class SpendStore {
+    readonly controlPlane: ControlPlaneStore;
+    private readonly options;
+    constructor(controlPlane: ControlPlaneStore, options?: {
+        now?: () => Date;
+        priceBook?: PriceBook;
+    });
+    now(): string;
+    get priceBook(): PriceBook;
+    private query;
+    createBudget(input: CreateBudgetInput): Budget;
+    getBudget(id: string): Budget | undefined;
+    listBudgets(filter: {
+        organizationId: string;
+        projectId?: string;
+        enabledOnly?: boolean;
+    }): Budget[];
+    /**
+     * Every budget that governs a scope, most specific last.
+     *
+     * Order matters to callers that apply the strictest cap: an environment
+     * budget should be able to tighten, never loosen, the project's.
+     */
+    budgetsForScope(organizationId: string, projectId?: string, environmentId?: string): Budget[];
+    updateBudget(id: string, patch: Partial<CreateBudgetInput>, expectedVersion?: number): Budget;
+    deleteBudget(id: string): boolean;
+    /**
+     * Fold usage deltas into hourly rollups, pricing each as it lands.
+     *
+     * Costs are computed against the period total already recorded for the same
+     * meter, so a tier boundary or a free allowance is crossed exactly once per
+     * window regardless of how the deltas were batched.
+     */
+    ingestUsage(deltas: ReadonlyArray<UsageDelta & {
+        key?: string;
+    }>): IngestResult;
+    private deltaFallbackKey;
+    /**
+     * Quantity already recorded this billing month for a delta's meter.
+     *
+     * Allowances and tiers are monthly on every provider we price, so the
+     * calendar month is the right accumulator regardless of a budget's own
+     * period - a weekly budget still sits inside a monthly free tier.
+     */
+    private periodQuantity;
+    private usageClauses;
+    /** Totals per meter plus the hourly cost series, for one window. */
+    summarizeUsage(query: UsageQuery): UsageSummary;
+    listRollups(query: UsageQuery, limit?: number): UsageRollup[];
+    /** Spend in a budget's current window, honouring its meter filter. */
+    budgetSpendCents(budget: Budget, now?: Date): {
+        window: ReturnType<typeof budgetWindow>;
+        summary: UsageSummary;
+    };
+    /** Drop rollups and receipts older than `days`. Rollups are cheap; receipts are not. */
+    pruneUsage(days: number, now?: Date): {
+        rollups: number;
+        receipts: number;
+    };
+    recordDecision(decision: SpendDecision): void;
+    listDecisions(budgetId: string, limit?: number): Array<Record<string, unknown>>;
+    /**
+     * Open an enforcement, or return the one already live for this budget+action.
+     *
+     * Idempotent by construction: the partial unique index makes a second insert
+     * for a live action fail, and re-evaluating a budget every minute must not
+     * pile up duplicate enforcements.
+     */
+    openEnforcement(input: {
+        budget: Budget;
+        action: EnforcementAction;
+        reason: string;
+        triggeredAtPercent: number;
+        restore?: Record<string, JsonValue>;
+        simulated?: boolean;
+    }): EnforcementRecord;
+    getEnforcement(id: string): EnforcementRecord | undefined;
+    activeEnforcement(budgetId: string, action: EnforcementAction): EnforcementRecord | undefined;
+    listEnforcements(filter: {
+        organizationId: string;
+        budgetId?: string;
+        activeOnly?: boolean;
+    }): EnforcementRecord[];
+    transitionEnforcement(id: string, state: EnforcementState, patch?: {
+        error?: string;
+        restore?: Record<string, JsonValue>;
+    }): EnforcementRecord;
+    /** Record an anomaly, ignoring a repeat for the same signal and bucket. */
+    recordAnomaly(input: Omit<SpendAnomaly, 'id' | 'createdAt'>): SpendAnomaly | undefined;
+    getAnomaly(id: string): SpendAnomaly | undefined;
+    listAnomalies(filter: {
+        organizationId: string;
+        projectId?: string;
+        since?: string;
+        unacknowledgedOnly?: boolean;
+        limit?: number;
+    }): SpendAnomaly[];
+    acknowledgeAnomaly(id: string): boolean;
+}

package/dist/spend/transports.d.ts

@@ -0,0 +1,169 @@
+/**
+ * Making an enforcement action affect real traffic.
+ *
+ * `appliers.ts` writes the gate; this is the part that talks to a provider. The
+ * split matters: the gate is what makes a cap true, and a transport is a
+ * best-effort effect on top of it, so a provider outage leaves the cap in force
+ * rather than silently open.
+ *
+ * Two rules every method here obeys:
+ *
+ *   1. **Return what it takes to undo.** A cap that cannot be lifted is an
+ *      outage, so each method returns the prior state rather than assuming a
+ *      default to restore to. "There was no reserved concurrency" and "reserved
+ *      concurrency was 50" need different restores.
+ *   2. **Never widen the blast radius.** On a shared box, stopping the gateway
+ *      would take down every other tenant on it to save one project money. The
+ *      compute transport stops the project's own units and says so.
+ */
+import type { CloudFrontClient } from '../aws/cloudfront';
+import type { LambdaClient } from '../aws/lambda';
+import type { JsonValue } from '../control-plane';
+import type { SpendEnforcementTransport } from './appliers';
+import type { DdosConfig } from '../protection/ddos';
+/** Shell access to one box. Matches `sshExec` so a driver can pass it straight in. */
+export type RemoteExec = (host: string, command: string) => Promise<{
+    code: number;
+    stdout: string;
+    stderr: string;
+}>;
+export interface AwsSpendTransportOptions {
+    lambda: LambdaClient;
+    cloudfront?: CloudFrontClient;
+    /**
+     * Resolve the Lambda functions in scope. A project usually has more than one
+     * (http, queue, scheduler) and a cap should stop all of them, not just the
+     * one that happens to be named first.
+     */
+    functions: (scope: {
+        projectId?: string;
+        environmentId?: string;
+    }) => Promise<string[]> | string[];
+    /** Publish + alias flip after an env change, for provisioned-concurrency stacks. */
+    republish?: (functionName: string) => Promise<void>;
+}
+/**
+ * AWS serverless enforcement.
+ *
+ * `suspend_functions` sets reserved concurrency to zero: triggers still fire,
+ * Lambda rejects the invocation, nothing runs, and one call reverses it. The
+ * alternatives are worse — deleting the function loses its triggers, and
+ * detaching the event source mapping is a multi-step change that is easy to
+ * half-restore.
+ *
+ * `throttle_requests` is deliberately absent. Rate limiting in front of
+ * CloudFront needs AWS WAF, which ts-cloud does not provision, and pretending
+ * otherwise would report a cap as applied when nothing changed. The applier
+ * marks it `unsupported: true` instead.
+ */
+export declare class AwsSpendTransport implements SpendEnforcementTransport {
+    private readonly options;
+    constructor(options: AwsSpendTransportOptions);
+    private targets;
+    suspendFunctions(scope: {
+        projectId?: string;
+        environmentId?: string;
+    }): Promise<Record<string, JsonValue>>;
+    resumeFunctions(restore: Record<string, JsonValue>): Promise<void>;
+    /**
+     * Serve only what is already static.
+     *
+     * On AWS that is the same lever as suspending functions: the origin stops
+     * rendering and CloudFront keeps serving S3 objects and cached responses.
+     * Two ladder rungs mapping to one mechanism is honest here — the rungs differ
+     * on other providers, and the restore payload records which one applied it.
+     */
+    serveStatic(scope: {
+        projectId?: string;
+        environmentId?: string;
+    }): Promise<Record<string, JsonValue>>;
+    restoreDynamic(restore: Record<string, JsonValue>): Promise<void>;
+    /**
+     * Park all traffic behind a 503.
+     *
+     * `MAINTENANCE_MODE` is read by the serverless runtime adapter, so the
+     * function still runs and answers 503 rather than erroring — which keeps the
+     * bypass header working for whoever is fixing the problem.
+     */
+    suspendProject(scope: {
+        projectId?: string;
+        environmentId?: string;
+    }): Promise<Record<string, JsonValue>>;
+    resumeProject(restore: Record<string, JsonValue>): Promise<void>;
+}
+export interface ComputeSpendTransportOptions {
+    host: string;
+    exec: RemoteExec;
+    /**
+     * Systemd unit bases for this scope, e.g. `acme-web`. The deploy runs each
+     * release as `<base>@<releaseId>.service`, so the wildcard is what stops
+     * whichever release is currently live.
+     */
+    units: (scope: {
+        projectId?: string;
+        environmentId?: string;
+    }) => Promise<string[]> | string[];
+    /** Current L3/L4 config, so a throttle can re-render it with tighter limits. */
+    ddos?: DdosConfig;
+    /** Renders the install script. Injected so the transport stays testable. */
+    renderDdos?: (config: DdosConfig) => string;
+}
+/**
+ * Enforcement on a box we control over SSH.
+ *
+ * **What this deliberately does not do:** stop `rpx-gateway.service`. On a
+ * shared box that gateway fronts every tenant, and taking it down to cap one
+ * project's spend would be an outage for everyone else. Suspension here stops
+ * the project's own units; requests then get whatever the gateway returns for
+ * an origin that is down. That is a real, bounded effect, and the restore
+ * payload records exactly which units were stopped.
+ */
+export declare class ComputeSpendTransport implements SpendEnforcementTransport {
+    private readonly options;
+    constructor(options: ComputeSpendTransportOptions);
+    private unitsFor;
+    /** Stop the app units, recording the instances that were actually running. */
+    private stopUnits;
+    private startUnits;
+    suspendFunctions(scope: {
+        projectId?: string;
+        environmentId?: string;
+    }): Promise<Record<string, JsonValue>>;
+    resumeFunctions(restore: Record<string, JsonValue>): Promise<void>;
+    serveStatic(scope: {
+        projectId?: string;
+        environmentId?: string;
+    }): Promise<Record<string, JsonValue>>;
+    restoreDynamic(restore: Record<string, JsonValue>): Promise<void>;
+    suspendProject(scope: {
+        projectId?: string;
+        environmentId?: string;
+    }): Promise<Record<string, JsonValue>>;
+    resumeProject(restore: Record<string, JsonValue>): Promise<void>;
+    /**
+     * Tighten the kernel's per-source connection limits.
+     *
+     * Reuses the same generator the deploy uses, so a throttle is the ordinary
+     * ruleset with scaled thresholds rather than a second, divergent one. The
+     * restore payload carries the original thresholds so lifting it re-renders
+     * exactly what was there before.
+     */
+    throttleRequests(input: {
+        projectId?: string;
+        environmentId?: string;
+        factor: number;
+    }): Promise<Record<string, JsonValue>>;
+    restoreRequests(restore: Record<string, JsonValue>): Promise<void>;
+}
+/**
+ * Fan one action out to several transports.
+ *
+ * A project that serves static assets from CloudFront and dynamic routes from a
+ * box needs both capped, and capping one is worse than capping neither: traffic
+ * shifts to whichever half is still up and the bill moves rather than stops.
+ *
+ * Every leg runs even if an earlier one throws, and the first error is rethrown
+ * once all have been attempted. Stopping at the first failure would leave the
+ * others uncapped with no record of it.
+ */
+export declare function compositeSpendTransport(transports: readonly SpendEnforcementTransport[]): SpendEnforcementTransport;

package/dist/spend/transports.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/spend/window.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Budget period windows, in the operator's timezone.
+ *
+ * A monthly cap that rolls over at UTC midnight is wrong for most of the world
+ * - it resets in the middle of a Californian afternoon, and the "month" it
+ * measures does not match the month on the invoice. Periods are therefore
+ * computed against an IANA timezone.
+ *
+ * Dependency-free: `Intl.DateTimeFormat` already knows every zone and every DST
+ * rule, so the offset is read from it rather than from a bundled tz database.
+ * DST is why the offset is resolved twice - the naive instant for local
+ * midnight can land on the wrong side of a transition, and the second pass
+ * corrects it.
+ */
+import type { BudgetPeriod, BudgetWindow } from './model';
+interface ZonedParts {
+    year: number;
+    month: number;
+    day: number;
+    hour: number;
+    minute: number;
+    second: number;
+    weekday: number;
+}
+/** Validate a timezone once; an unknown zone should fail loudly, not silently bill in UTC. */
+export declare function isValidTimeZone(timeZone: string): boolean;
+export declare function zonedParts(instant: Date, timeZone: string): ZonedParts;
+/** Milliseconds the zone is ahead of UTC at `instant`. */
+export declare function zoneOffsetMs(instant: Date, timeZone: string): number;
+/**
+ * The UTC instant of a given local wall-clock time.
+ *
+ * Two passes: the first offset is read at the naive guess, the second at the
+ * corrected instant. On a DST boundary those differ, and only the second is
+ * right. Times that do not exist locally (the spring-forward gap) resolve
+ * forward, which is the conventional and the safe direction for a period start.
+ */
+export declare function utcInstantOfLocal(timeZone: string, year: number, month: number, day: number, hour?: number): Date;
+/**
+ * The window `now` falls inside for a period, plus how far through it we are.
+ *
+ * Weeks start Monday: a Sunday-start week splits the working week across two
+ * budgets, which makes every week-over-week comparison lie.
+ */
+export declare function budgetWindow(period: BudgetPeriod, timeZone: string, now?: Date): BudgetWindow;
+/** The window immediately before the one containing `now`. Used for comparisons. */
+export declare function previousBudgetWindow(period: BudgetPeriod, timeZone: string, now?: Date): BudgetWindow;
+/** Truncate an instant to the start of its UTC hour - the rollup bucket. */
+export declare function hourBucket(instant: Date | string): string;
+/** Every hour bucket in `[from, to)`, ascending. Bounded so a bad range cannot hang. */
+export declare function hourBucketsBetween(from: string, to: string, maxBuckets?: number): string[];
+export {};

package/dist/spend/window.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/ui/404.html

@@ -782,6 +782,7 @@ video {
           <a class="" href="/operations/workloads?env=production">Workloads</a>
           <a class="" href="/operations/observability?env=production">Observability</a>
           <a class="" href="/operations/alerts?env=production">Alerts & health</a>
+          <a class="" href="/operations/spend?env=production">Spend & budgets</a>
           <a href="/server/metrics?env=production">Metrics</a><a href="/server/services?env=production">Runtime services</a>
           <a class="" href="/operations/jobs?env=production">Workers & schedules</a>
           <a class="" href="/operations/configuration?env=production">Environment &amp; secrets</a>