@usagekit/core 0.1.0 → 0.3.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.
  */
@@ -205,11 +245,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;
@@ -341,6 +383,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 +433,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 +462,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 +496,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 +521,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;
@@ -487,6 +559,7 @@ 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>>;
     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,9 @@
-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, } from "./contracts.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";

package/dist/index.js

@@ -1,5 +1,5 @@
 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";

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,10 @@
-import type { BudgetScope } from "./contracts.js";
+import type { BudgetScope, 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;

package/dist/policy.js

@@ -1,7 +1,29 @@
+/** 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);

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/package.json

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