@usagekit/core 0.1.0 → 0.4.0

package/dist/contracts.d.ts

@@ -37,6 +37,12 @@ export type Scope = {
     accessCredential?: AccessCredential;
     /** Which provider secret version was used. Rotation identity, not caller identity. */
     providerCredentialVersion?: string;
+    /**
+     * Connection labels snapshotted at reservation: 1..16 unique entries, each 1..64 characters
+     * matching [a-z0-9][a-z0-9_.:-]*, sorted before storage. Attribution only: excluded from
+     * reserve identity, so a replay keeps the first reservation's tags.
+     */
+    tags?: readonly string[];
 };
 export type FundingSource = "byok" | "platform";
 export type Surface = "app" | "programmatic";
@@ -62,6 +68,7 @@ export type BudgetWindow = {
  * Each variant names one constraint in a namespace.
  * A platform_pool bounds spend shared by many principals and applies to operations
  * naming that pool in ReserveInput. It is not the platform principal's own budget.
+ * A tag bounds every operation whose scope.tags contains it, across principals.
  * A wallet is not a budget: the host ledger owns balances, holds and charges,
  * coordinated through the host credit bridge. A wallet-level monthly cap may still
  * be a principal Budget because the cap is a constraint, not a balance.
@@ -86,16 +93,49 @@ export type BudgetScope = {
     kind: "platform_pool";
     namespace: string;
     poolId: string;
+} | {
+    kind: "tag";
+    namespace: string;
+    tag: string;
 };
+/**
+ * surface selects the traffic a budget bounds: "any" matches every operation, a Surface
+ * matches operations whose source belongs to that surface group (see sourcesOf), and a
+ * Source matches exactly that source. Hosts set surface and source at authentication.
+ */
 export type Budget = {
     id: string;
     version: number;
     scope: BudgetScope;
-    surface: Surface | "any";
+    surface: Surface | Source | "any";
     unit: string;
     limit: Quantity | null;
     window: BudgetWindow;
-    onExceed: "block" | "warn";
+    /** block denies past limit. allow admits with a warning; wire and stored rows may still say the deprecated alias for allow. */
+    onExceed: "block" | "allow";
+    /** Only with onExceed allow: same unit as limit and greater than it. Exceeding it denies admission. */
+    hardLimit?: Quantity;
+    /** At most eight thresholds in ascending order; each crossing is reported once per epoch. */
+    alerts?: readonly BudgetAlert[];
+};
+/** percent is an integer 1..100 of limit; a Quantity threshold is in the budget unit. */
+export type BudgetAlert = {
+    at: {
+        percent: number;
+    } | Quantity;
+};
+/**
+ * Reported by the command whose admitted or settled figures first reach the threshold.
+ * The store records each crossing atomically per budget id, epoch and threshold, so a
+ * replay returns the stored crossings and no later command reports the same one again.
+ */
+export type BudgetAlertCrossed = {
+    budgetId: string;
+    budgetVersion: number;
+    epoch: string;
+    at: BudgetAlert["at"];
+    used: Quantity;
+    reserved: Quantity;
 };
 export type LifecycleState = "reserved" | "dispatch_intended" | "pending" | "settled" | "released";
 export type Certainty = "measured" | "estimated" | "unknown";
@@ -138,14 +178,14 @@ export type Receipt = {
  * Store selects all applying budgets atomically inside reserve; Meter's pre-resolution
  * is advisory and never sufficient for admission.
  * Match namespace and the bound: principal, group, connection, accessCredential by
- * kind and id, or poolId listed in platformPools. Match surface or "any".
+ * kind and id, or poolId listed in platformPools. Match "any", the surface or the source.
  * Each applicable budget's unit must appear in estimate. A missing bounded unit is
  * a Meter validation error, not permission to bypass the bound. Store re-checks this
  * against current budgets. Units without budgets are recorded without a bound.
  * Use the current budget version at reservation time; snapshot its resolved epoch
  * and version into budgetEpochs. Check every applying budget in one atomic command.
- * Return the first exceeded bound in deterministic host-policy order; default:
- * platform_pool, principal, group, connection, access_credential.
+ * Return the first exceeded bound in deterministic host-policy order; the default
+ * is defaultBudgetOrder: platform_pool, principal, group, tag, connection, access_credential.
  * A guest session is actor, not budget owner. The platform or a dedicated guest
  * principal owns the operation; its pool and host-enforced session limit both apply.
  */
@@ -168,6 +208,10 @@ export type ReserveInput = {
     provider: string;
     operation: string;
     estimate: readonly Quantity[];
+    /** Set by a Meter that resolved the estimate from a catalog; hosts may set it themselves. */
+    estimateSource?: EstimateSource;
+    /** "<provider>:<validFrom>" of the list price row behind the estimate. */
+    providerPriceVersion?: string;
     correlationId?: string;
     parentOperationId?: string;
 };
@@ -205,11 +249,13 @@ export type ReserveResult = ValidationFailure | {
     replayed: false;
     operation: Operation;
     warnings: readonly AllowanceExceeded[];
+    alerts: readonly BudgetAlertCrossed[];
 } | {
     outcome: "reserved";
     replayed: true;
     operation: Operation;
     warnings: readonly AllowanceExceeded[];
+    alerts: readonly BudgetAlertCrossed[];
 } | {
     outcome: "exceeded";
     exceeded: AllowanceExceeded;
@@ -218,6 +264,84 @@ export type ReserveResult = ValidationFailure | {
     outcome: "conflict";
     reason: "semantic_mismatch";
     operation: Operation;
+}
+/**
+ * The connection's tracking policy is passthrough for this operation, or the catalog marks it
+ * free: counted with state passthrough, never reserved. The caller may forward the call.
+ */
+ | {
+    outcome: "passthrough";
+    replayed: boolean;
+    operation: null;
+}
+/**
+ * No estimate was given and the catalog does not know the operation: counted with state
+ * unpriced, never reserved. Host policy decides whether to forward the call.
+ */
+ | {
+    outcome: "unpriced";
+    replayed: boolean;
+    operation: null;
+};
+/** Where a reserve estimate came from, in resolution order. */
+export type EstimateSource = "manual" | "measured" | "list" | "unknown";
+/**
+ * Meter reserve input. With a catalog, estimate may be omitted: the Meter resolves it from the
+ * catalog for the connection and the request options. Store always receives a ReserveInput.
+ */
+export type MeterReserveInput = Omit<ReserveInput, "estimate"> & {
+    /** Omitted: the Meter resolves it through its catalog and the connection policy. */
+    estimate?: readonly Quantity[];
+    /** Request options that move the price, read from the request by the descriptor. */
+    options?: Readonly<Record<string, string>>;
+};
+/**
+ * Non-operation outcomes, counted per state and never reserved. Metered requests are the
+ * operations themselves and are not counted here.
+ */
+export type RequestState = "passthrough" | "unpriced" | "cached" | "rate_limited";
+/**
+ * One counted request. commandId is the replay key: an identical replay counts once and returns
+ * replayed: true; a changed payload under the same commandId is a conflict. Counts carry no
+ * content and never touch budgets.
+ */
+export type CountRequestInput = {
+    commandId: string;
+    scope: Scope;
+    surface: Surface;
+    source: Source;
+    provider: string;
+    operation: string;
+    state: RequestState;
+    platformPools?: readonly string[];
+};
+export type CountRequestResult = ValidationFailure | {
+    outcome: "counted";
+    replayed: boolean;
+} | {
+    outcome: "conflict";
+    reason: "command_mismatch";
+};
+/** Requests counted at store time in [from, to), with the scope and access rules of usage. */
+export type RequestCountsQuery = {
+    scope: UsageScope;
+    from: string;
+    to: string;
+    connection?: string;
+    groupBy: readonly ("provider" | "operation" | "connection" | "source" | "day")[];
+    /** Rows per page, 1..1000, default 1000; truncated reports more rows. */
+    limit?: number;
+};
+/** One row per dimension combination and state, ordered by dimensions then state. */
+export type RequestCountRow = {
+    dimensions: Readonly<Record<string, string>>;
+    state: RequestState;
+    count: bigint;
+};
+export type RequestCountsPage = {
+    rows: readonly RequestCountRow[];
+    asOf: string;
+    truncated: boolean;
 };
 export type OperationRef = Pick<Scope, "namespace" | "principal"> & {
     operationId: string;
@@ -341,6 +465,7 @@ export type SettleResult = ValidationFailure | {
     outcome: "settled";
     replayed: boolean;
     operation: Operation;
+    alerts: readonly BudgetAlertCrossed[];
 } | {
     outcome: "rejected";
     reason: "not_holder" | "lease_expired" | "version_conflict" | "invalid_state" | "receipt_conflict";
@@ -390,14 +515,18 @@ export type AccessContext = {
     canReadBillingDetail: boolean;
     canManageBudgets: boolean;
 };
-/** groupBy: "principal" is allowed only for group or namespace scope. */
+/**
+ * groupBy: "principal" is allowed only for group or namespace scope.
+ * "platform_pool" and "tag" explode one row per pool or tag of an operation, with an
+ * empty dimension when the operation has none; those rows are not additive across tags.
+ */
 export type UsageQuery = {
     scope: UsageScope;
     from: string;
     to: string;
     connection?: string;
     units: readonly string[];
-    groupBy: readonly ("principal" | "provider" | "operation" | "surface" | "source" | "connection" | "day" | "access_credential" | "platform_pool")[];
+    groupBy: readonly ("principal" | "provider" | "operation" | "surface" | "source" | "connection" | "day" | "access_credential" | "platform_pool" | "funding_source" | "tag")[];
     cursor?: string;
     limit?: number;
 };
@@ -415,6 +544,27 @@ export type UsagePage = {
     watermark: string;
     nextCursor?: string;
 };
+/**
+ * Operations whose createdAt lies in [from, to), in one lifecycle state of states (all when
+ * omitted), ordered by createdAt then operationId. Same scope and access rules as usage.
+ * Pagination mirrors usage: the first page fixes membership and order at its watermark; later
+ * pages take the cursor with the unchanged query and return each operation as currently stored.
+ */
+export type OperationsQuery = {
+    scope: UsageScope;
+    from: string;
+    to: string;
+    states?: readonly LifecycleState[];
+    connection?: string;
+    cursor?: string;
+    limit?: number;
+};
+export type OperationsPage = {
+    operations: readonly Operation[];
+    asOf: string;
+    watermark: string;
+    nextCursor?: string;
+};
 /** Budgets defined for exactly this scope, regardless of any operation. */
 export type DefinedBudgetsQuery = {
     scope: BudgetScope;
@@ -428,6 +578,8 @@ export type DefinedBudgetsQuery = {
 export type ApplicableBudgetsQuery = {
     scope: Scope;
     surface: Surface;
+    /** Include budgets bound to exactly this source. Omitted lists surface and any budgets only. */
+    source?: Source;
     units: readonly string[];
     platformPools?: readonly string[];
 };
@@ -451,10 +603,12 @@ export type ReadResult<T> = ValidationFailure | {
 } | {
     outcome: "forbidden";
 };
-/** Data-only budget denial. A P1 implementation may wrap it in a runtime error class. */
+/** Data-only budget denial or warning. A P1 implementation may wrap it in a runtime error class. */
 export interface AllowanceExceeded {
     readonly code: "allowance_exceeded";
     readonly budget: Budget;
+    /** Which bound was crossed: limit warns on allow budgets and denies on block budgets; hardLimit always denies. */
+    readonly boundary: "limit" | "hardLimit";
     readonly used: Quantity;
     readonly reserved: Quantity;
     readonly resetsAt: string | null;
@@ -478,7 +632,8 @@ export type ExpireReservationsResult = ValidationFailure | {
  */
 export interface Meter {
     expireReservations(input: ExpireReservationsInput): Promise<ExpireReservationsResult>;
-    reserve(input: ReserveInput): Promise<ReserveResult>;
+    reserve(input: MeterReserveInput): Promise<ReserveResult>;
+    countRequest(input: CountRequestInput): Promise<CountRequestResult>;
     markDispatchIntent(input: DispatchIntentInput): Promise<DispatchGrant>;
     renewLease(input: LeaseRenewalInput): Promise<LeaseRenewal>;
     claimForRecovery(input: RecoveryClaimInput): Promise<RecoveryClaim>;
@@ -487,6 +642,8 @@ export interface Meter {
     releaseUndispatched(input: ReleaseInput): Promise<ReleaseResult>;
     getOperation(access: AccessContext, input: OperationRef): Promise<ReadResult<Operation | null>>;
     usage(access: AccessContext, query: UsageQuery): Promise<ReadResult<UsagePage>>;
+    listOperations(access: AccessContext, query: OperationsQuery): Promise<ReadResult<OperationsPage>>;
+    requestCounts(access: AccessContext, query: RequestCountsQuery): Promise<ReadResult<RequestCountsPage>>;
     definedBudgets(access: AccessContext, query: DefinedBudgetsQuery): Promise<ReadResult<readonly Budget[]>>;
     applicableBudgets(access: AccessContext, query: ApplicableBudgetsQuery): Promise<ReadResult<readonly BudgetStatus[]>>;
 }

package/dist/index.d.ts

@@ -1,9 +1,12 @@
-export type { Money, Quantity, AccessCredential, Scope, FundingSource, Surface, Source, BudgetWindow, BudgetScope, Budget, LifecycleState, Certainty, Measurement, Cost, Receipt, ReserveInput, ReserveResult, Operation, OperationRef, OperationCommand, Lease, DispatchGrant, DispatchIntentInput, LeaseRenewalInput, LeaseRenewal, RecoveryClaimInput, RecoveryClaim, Authority, SettleInput, ReleaseInput, CorrectionInput, SettleResult, ReleaseResult, UsageScope, AccessContext, UsageQuery, UsageRow, UsagePage, DefinedBudgetsQuery, ApplicableBudgetsQuery, BudgetStatus, ReadResult, AllowanceExceeded, Meter, } from "./contracts.js";
+export type { Money, Quantity, AccessCredential, Scope, FundingSource, Surface, Source, BudgetWindow, BudgetScope, Budget, BudgetAlert, BudgetAlertCrossed, LifecycleState, Certainty, Measurement, Cost, Receipt, ReserveInput, ReserveResult, Operation, OperationRef, OperationCommand, Lease, DispatchGrant, DispatchIntentInput, LeaseRenewalInput, LeaseRenewal, RecoveryClaimInput, RecoveryClaim, Authority, SettleInput, ReleaseInput, CorrectionInput, SettleResult, ReleaseResult, UsageScope, AccessContext, UsageQuery, UsageRow, UsagePage, OperationsQuery, OperationsPage, DefinedBudgetsQuery, ApplicableBudgetsQuery, BudgetStatus, ReadResult, AllowanceExceeded, Meter, MeterReserveInput, EstimateSource, RequestState, CountRequestInput, CountRequestResult, RequestCountsQuery, RequestCountRow, RequestCountsPage, } from "./contracts.js";
+export { requestStates } from "./policy.js";
 export { resolveWindow } from "./windows.js";
 export type { ResolvedWindow } from "./windows.js";
-export { fromDecimalString, toDecimalString, add as addMoney, sub as subtractMoney, compare as compareMoney, } from "./money.js";
-export { normalizeScale, add as addQuantity, compare as compareQuantity } from "./quantity.js";
+export { fromDecimalString, toDecimalString, formatMoney, add as addMoney, sub as subtractMoney, compare as compareMoney, } from "./money.js";
+export { normalizeScale, add as addQuantity, compare as compareQuantity, format as formatQuantity, } from "./quantity.js";
 export type { ValidationFailure, AdmissionPolicy, BudgetOwner } from "./contracts.js";
-export { defaultBudgetOrder } from "./policy.js";
+export { defaultBudgetOrder, sourcesOf, surfaceMatches, tagPattern, normalizeTags, } from "./policy.js";
 export type { ExpireReservationsInput, ExpireReservationsResult } from "./contracts.js";
 export { decodeMeterJson } from "./wire.js";
+export type { ProviderId, OperationId, ProviderAuth, BillingUnit, ProviderPlan, PriceRow, RequestMatch, ProviderOperation, BalanceProbe, PriceListSource, BillingExport, ProviderDescriptor, BalanceSnapshot, BillingLine, DescriptorProblem, PricingCatalog, ConnectionPolicy, TrackingPolicy, MeasuredPrice, } from "./providers.js";
+export { validateDescriptor } from "./providers.js";

package/dist/index.js

@@ -1,5 +1,7 @@
+export { requestStates } from "./policy.js";
 export { resolveWindow } from "./windows.js";
-export { fromDecimalString, toDecimalString, add as addMoney, sub as subtractMoney, compare as compareMoney, } from "./money.js";
-export { normalizeScale, add as addQuantity, compare as compareQuantity } from "./quantity.js";
-export { defaultBudgetOrder } from "./policy.js";
+export { fromDecimalString, toDecimalString, formatMoney, add as addMoney, sub as subtractMoney, compare as compareMoney, } from "./money.js";
+export { normalizeScale, add as addQuantity, compare as compareQuantity, format as formatQuantity, } from "./quantity.js";
+export { defaultBudgetOrder, sourcesOf, surfaceMatches, tagPattern, normalizeTags, } from "./policy.js";
 export { decodeMeterJson } from "./wire.js";
+export { validateDescriptor } from "./providers.js";

package/dist/money.d.ts

@@ -6,3 +6,5 @@ export declare function toDecimalString(m: Money): string;
 export declare const add: (a: Money, b: Money) => Money;
 export declare const sub: (a: Money, b: Money) => Money;
 export declare const compare: (a: Money, b: Money) => -1 | 0 | 1;
+/** Exact cents text with four fractional digits; a named alias of toDecimalString for views. */
+export declare const formatMoney: (m: Money) => string;

package/dist/money.js

@@ -15,3 +15,5 @@ export function toDecimalString(m) {
 export const add = (a, b) => ({ currency: "USD", units: a.units + b.units });
 export const sub = (a, b) => ({ currency: "USD", units: a.units - b.units });
 export const compare = (a, b) => a.units < b.units ? -1 : a.units > b.units ? 1 : 0;
+/** Exact cents text with four fractional digits; a named alias of toDecimalString for views. */
+export const formatMoney = toDecimalString;

package/dist/policy.d.ts

@@ -1,2 +1,12 @@
-import type { BudgetScope } from "./contracts.js";
+import type { BudgetScope, RequestState, Source, Surface } from "./contracts.js";
+/** Single source of the default admission order; hosts may permute it, never shorten it. */
 export declare const defaultBudgetOrder: readonly BudgetScope["kind"][];
+export declare const tagPattern: RegExp;
+/** Sorted unique tags, or null when the list breaks the 1..16 count, format or uniqueness rules. */
+export declare function normalizeTags(tags: readonly string[]): string[] | null;
+/** Sources a surface budget covers. Every Source belongs to exactly one Surface. */
+export declare const sourcesOf: (surface: Surface) => readonly Source[];
+/** True when a budget surface value bounds an operation with this surface and source. */
+export declare const surfaceMatches: (budgetSurface: Surface | Source | "any", surface: Surface, source?: Source) => boolean;
+/** Every counted request state, in display order. */
+export declare const requestStates: readonly RequestState[];

package/dist/policy.js

@@ -1,7 +1,36 @@
+/** Single source of the default admission order; hosts may permute it, never shorten it. */
 export const defaultBudgetOrder = Object.freeze([
     "platform_pool",
     "principal",
     "group",
+    "tag",
     "connection",
     "access_credential",
 ]);
+export const tagPattern = /^[a-z0-9][a-z0-9_.:-]{0,63}$/;
+/** Sorted unique tags, or null when the list breaks the 1..16 count, format or uniqueness rules. */
+export function normalizeTags(tags) {
+    if (!Array.isArray(tags) || tags.length < 1 || tags.length > 16)
+        return null;
+    if (tags.some((t) => typeof t !== "string" || !tagPattern.test(t)))
+        return null;
+    const sorted = [...tags].sort();
+    return sorted.some((t, n) => n > 0 && sorted[n - 1] === t) ? null : sorted;
+}
+const surfaceSources = Object.freeze({
+    app: Object.freeze(["app", "worker"]),
+    programmatic: Object.freeze(["api", "sdk", "cli", "mcp", "proxy"]),
+});
+/** Sources a surface budget covers. Every Source belongs to exactly one Surface. */
+export const sourcesOf = (surface) => surfaceSources[surface];
+/** True when a budget surface value bounds an operation with this surface and source. */
+export const surfaceMatches = (budgetSurface, surface, source) => budgetSurface === "any" ||
+    budgetSurface === surface ||
+    (source !== undefined && budgetSurface === source);
+/** Every counted request state, in display order. */
+export const requestStates = Object.freeze([
+    "passthrough",
+    "unpriced",
+    "cached",
+    "rate_limited",
+]);

package/dist/providers.d.ts

@@ -0,0 +1,256 @@
+import type { EstimateSource, Money, Quantity } from "./contracts.js";
+/**
+ * Provider descriptors: data that tells usagekit how to price, route, meter and reconcile one
+ * provider. Descriptors live in `@usagekit/providers`; the core contract does not depend on
+ * them. See docs/PROVIDERS.md.
+ */
+export type ProviderId = string;
+/**
+ * Operation identity is the pricing key. Manual overrides, tracking policy and budgets per
+ * operation all key on OperationId, never on a raw path.
+ */
+export type OperationId = string;
+export type ProviderAuth = {
+    kind: "query";
+    param: string;
+} | {
+    kind: "header";
+    name: string;
+    prefix?: string;
+} | {
+    kind: "basic";
+} | {
+    kind: "bearer";
+};
+export type BillingUnit = "cents" | "units" | "requests";
+/**
+ * allowanceMode mirrors how the provider behaves past the allowance: prepaid balances and
+ * no-overage plans are hard, plans that bill excess are soft.
+ */
+export type ProviderPlan = {
+    id: string;
+    label: string;
+    cycle: "monthly_plan" | "prepaid" | "trial" | "none";
+    allowance?: {
+        unit: BillingUnit;
+        value: bigint;
+    };
+    allowanceMode: "hard" | "soft";
+};
+/**
+ * One list price. The descriptor never holds negotiated prices, discounts or volume tiers beyond
+ * the public list; those are manual prices on the connection.
+ */
+export type PriceRow = {
+    /** ISO date. */
+    validFrom: string;
+    operation: OperationId;
+    /** Plan id; absent means any plan. */
+    plan?: string;
+    /** Request options that select this row. Options are request data, never guessed. */
+    option?: Readonly<Record<string, string>>;
+    /** Applies past the plan allowance. */
+    overage?: true;
+    unit: BillingUnit;
+    /** Exact nonnegative decimal in that unit. */
+    perUnit: string;
+    /** URL of the public price source. */
+    source: string;
+    /** ISO date of the last check against the source. */
+    checkedAt: string;
+};
+export type RequestMatch = {
+    method: "GET" | "POST" | "PUT" | "DELETE" | "ANY";
+    /** Path pattern with :params (one segment) and a trailing * (any rest). */
+    path: string;
+    query?: Readonly<Record<string, string | RegExp>>;
+};
+/**
+ * Free endpoints are operations too, with billable false. They are matched, counted and never
+ * reserved. A descriptor may advertise an operation only when at least one fixture exists for it.
+ */
+export type ProviderOperation = {
+    id: OperationId;
+    label: string;
+    billable: boolean;
+    match: readonly RequestMatch[];
+    /** Options that move the price; values are extracted from the request by `options`. */
+    optionKeys?: readonly string[];
+    /**
+     * Cost is known from the response body, only after a later call, or never per call.
+     * response: settle on stream close. deferred: settle with unknown cost, keep pending, resolve
+     * through the task-get operation or billing export. none: settle with the estimate as
+     * estimated, reconcile from balance deltas or export.
+     */
+    costEvidence: "response" | "deferred" | "none";
+    /** Idempotent replay is safe for this operation when the provider returns the same result. */
+    cacheable?: {
+        keyParams: readonly string[];
+        defaultTtlMs: number;
+    };
+};
+/** Account identity is returned to the host as data. Duplicate detection is a host decision. */
+export type BalanceProbe = {
+    /** The free account endpoint. */
+    operation: OperationId;
+    fields: {
+        /** JSON pointer. */
+        remaining?: string;
+        remainingUnit?: BillingUnit;
+        allowance?: string;
+        used?: string;
+        resetsAt?: string;
+        plan?: string;
+        /** E-mail or login, for duplicate detection. */
+        accountIdentity?: string;
+        rateLimitPerHour?: string;
+    };
+};
+/**
+ * A price list from an endpoint is a refresh source for prices, not a replacement: a pull
+ * request updates the rows with the fetched values and the check date; runtime never fetches
+ * prices to decide admission.
+ */
+export type PriceListSource = {
+    kind: "static";
+} | {
+    kind: "endpoint";
+    operation: OperationId;
+    pointer: string;
+    mapping: "provider-specific";
+};
+export type BillingExport = {
+    kind: "task-history" | "daily-csv" | "none";
+    /** For API-backed history. */
+    operation?: OperationId;
+    granularity: "per-request" | "per-day";
+    matchKey: "providerRequestId" | "window";
+};
+export type ProviderDescriptor = {
+    id: ProviderId;
+    label: string;
+    /** Origin and optional base path, for example "https://api.example.com". */
+    upstream: string;
+    auth: ProviderAuth;
+    stripRequestHeaders?: readonly string[];
+    billing: {
+        unit: BillingUnit;
+        cycle: ProviderPlan["cycle"];
+    };
+    plans: readonly ProviderPlan[];
+    prices: readonly PriceRow[];
+    priceList: PriceListSource;
+    operations: readonly ProviderOperation[];
+    balance?: BalanceProbe;
+    billingExport: BillingExport;
+    rateLimits?: readonly {
+        scope: "account";
+        perMinute?: number;
+        perHour?: number;
+    }[];
+    docs: {
+        pricing: string;
+        api: string;
+    };
+};
+/** Parsed balance probe. Every field is optional because providers report different subsets. */
+export type BalanceSnapshot = {
+    remaining?: Quantity;
+    allowance?: Quantity;
+    used?: Quantity;
+    /** UTC ISO timestamp of the next allowance reset. */
+    resetsAt?: string;
+    plan?: string;
+    accountIdentity?: string;
+    rateLimitPerHour?: number;
+};
+/** One matchable line of a provider billing export. */
+export type BillingLine = {
+    providerRequestId?: string;
+    operation?: OperationId;
+    occurredAt: string;
+    cost: Money;
+    /** Window of a per-day line, [from, to). */
+    window?: {
+        from: string;
+        to: string;
+    };
+};
+/** Per-connection choice per catalog operation; the default is metered. */
+export type TrackingPolicy = "metered" | "passthrough";
+/** Median of a connection's settled receipts for one operation, with its sample size. */
+export type MeasuredPrice = (operation: OperationId) => {
+    quantity: Quantity;
+    samples: number;
+} | undefined;
+/**
+ * Connection data a host resolves for the Meter: provider, selected plan, manual per-call prices,
+ * measured prices and tracking policy, all keyed by OperationId. overage is true when the host
+ * knows the plan allowance is exhausted.
+ */
+export type ConnectionPolicy = {
+    provider: ProviderId;
+    plan?: string;
+    manualPrices?: Readonly<Record<OperationId, Quantity>>;
+    measured?: MeasuredPrice;
+    tracking?: Readonly<Record<OperationId, TrackingPolicy>>;
+    overage?: boolean;
+};
+/**
+ * What the Meter needs from a provider catalog. `@usagekit/providers` createCatalog satisfies
+ * it; the Meter does not depend on that package. operationsOf lists the operations of an
+ * enabled provider and nothing for a disabled or unknown one.
+ */
+export type PricingCatalog = {
+    estimate(connection: Omit<ConnectionPolicy, "tracking"> & {
+        id: string;
+    }, operation: OperationId, options: Readonly<Record<string, string>>): {
+        quantities: Quantity[];
+        source: EstimateSource;
+        priceVersion?: string;
+    };
+    operationsOf(providerId: ProviderId): readonly ProviderOperation[];
+};
+export type DescriptorProblem = {
+    kind: "duplicate_operation";
+    operation: OperationId;
+} | {
+    kind: "duplicate_plan";
+    plan: string;
+} | {
+    kind: "missing_match";
+    operation: OperationId;
+} | {
+    kind: "unknown_price_operation";
+    row: number;
+    operation: OperationId;
+} | {
+    kind: "unknown_price_plan";
+    row: number;
+    plan: string;
+} | {
+    kind: "unknown_price_option";
+    row: number;
+    option: string;
+} | {
+    kind: "invalid_price";
+    row: number;
+    field: "perUnit" | "validFrom" | "checkedAt" | "source";
+} | {
+    kind: "unknown_probe_operation";
+    operation: OperationId;
+} | {
+    kind: "billable_probe";
+    operation: OperationId;
+} | {
+    kind: "unknown_price_list_operation";
+    operation: OperationId;
+} | {
+    kind: "unknown_export_operation";
+    operation: OperationId;
+};
+/**
+ * Structural problems of a descriptor, in a stable order: operations, plans, prices, probe,
+ * price list, billing export. An empty list means the catalog may load it.
+ */
+export declare function validateDescriptor(d: ProviderDescriptor): DescriptorProblem[];

package/dist/providers.js

@@ -0,0 +1,54 @@
+const isoDate = (text) => /^\d{4}-\d{2}-\d{2}/.test(text) && Number.isFinite(Date.parse(text));
+/**
+ * Structural problems of a descriptor, in a stable order: operations, plans, prices, probe,
+ * price list, billing export. An empty list means the catalog may load it.
+ */
+export function validateDescriptor(d) {
+    const problems = [];
+    const operations = new Map();
+    for (const op of d.operations) {
+        if (operations.has(op.id))
+            problems.push({ kind: "duplicate_operation", operation: op.id });
+        else
+            operations.set(op.id, op);
+    }
+    for (const op of d.operations)
+        if (op.match.length === 0 && operations.get(op.id) === op)
+            problems.push({ kind: "missing_match", operation: op.id });
+    const plans = new Set();
+    for (const plan of d.plans) {
+        if (plans.has(plan.id))
+            problems.push({ kind: "duplicate_plan", plan: plan.id });
+        plans.add(plan.id);
+    }
+    d.prices.forEach((row, index) => {
+        const op = operations.get(row.operation);
+        if (!op)
+            problems.push({ kind: "unknown_price_operation", row: index, operation: row.operation });
+        if (row.plan !== undefined && !plans.has(row.plan))
+            problems.push({ kind: "unknown_price_plan", row: index, plan: row.plan });
+        for (const key of Object.keys(row.option ?? {}))
+            if (op && !(op.optionKeys ?? []).includes(key))
+                problems.push({ kind: "unknown_price_option", row: index, option: key });
+        if (!/^\d+(\.\d+)?$/.test(row.perUnit))
+            problems.push({ kind: "invalid_price", row: index, field: "perUnit" });
+        if (!isoDate(row.validFrom))
+            problems.push({ kind: "invalid_price", row: index, field: "validFrom" });
+        if (!isoDate(row.checkedAt))
+            problems.push({ kind: "invalid_price", row: index, field: "checkedAt" });
+        if (!row.source.trim())
+            problems.push({ kind: "invalid_price", row: index, field: "source" });
+    });
+    if (d.balance) {
+        const probe = operations.get(d.balance.operation);
+        if (!probe)
+            problems.push({ kind: "unknown_probe_operation", operation: d.balance.operation });
+        else if (probe.billable)
+            problems.push({ kind: "billable_probe", operation: probe.id });
+    }
+    if (d.priceList.kind === "endpoint" && !operations.has(d.priceList.operation))
+        problems.push({ kind: "unknown_price_list_operation", operation: d.priceList.operation });
+    if (d.billingExport.operation !== undefined && !operations.has(d.billingExport.operation))
+        problems.push({ kind: "unknown_export_operation", operation: d.billingExport.operation });
+    return problems;
+}

package/dist/quantity.d.ts

@@ -2,3 +2,5 @@ import type { Quantity } from "./contracts.js";
 export declare function normalizeScale(q: Quantity, scale: number): Quantity;
 export declare function add(a: Quantity, b: Quantity): Quantity;
 export declare function compare(a: Quantity, b: Quantity): -1 | 0 | 1;
+/** Exact decimal text of value * 10^-scale, trailing fractional zeros trimmed, no trailing dot. */
+export declare function format(q: Quantity): string;

package/dist/quantity.js

@@ -17,3 +17,9 @@ export function compare(a, b) {
     const [x, y] = pair(a, b);
     return x.value < y.value ? -1 : x.value > y.value ? 1 : 0;
 }
+/** Exact decimal text of value * 10^-scale, trailing fractional zeros trimmed, no trailing dot. */
+export function format(q) {
+    const negative = q.value < 0n, digits = (negative ? -q.value : q.value).toString().padStart(q.scale + 1, "0"), whole = digits.slice(0, digits.length - q.scale), fraction = digits.slice(digits.length - q.scale).replace(/0+$/, "");
+    const text = fraction ? `${whole}.${fraction}` : whole;
+    return negative && text !== "0" ? `-${text}` : text;
+}

package/dist/wire.js

@@ -23,6 +23,12 @@ export function decodeMeterJson(text) {
             typeof v.costOwner === "string" &&
             decimal(v.unknownOperations))
             return { ...v, unknownOperations: BigInt(v.unknownOperations) };
+        if (keys.length === 3 &&
+            v.dimensions &&
+            typeof v.dimensions === "object" &&
+            ["passthrough", "unpriced", "cached", "rate_limited"].includes(String(v.state)) &&
+            decimal(v.count))
+            return { ...v, count: BigInt(v.count) };
         return value;
     });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usagekit/core",
-  "version": "0.1.0",
+  "version": "0.4.0",
   "type": "module",
   "license": "Apache-2.0",
   "description": "Exact quantities, ownership and pure domain types.",