@abloatai/transaction 0.39.0 → 0.41.0

package/src/errorCodes.ts

@@ -139,11 +139,16 @@ const wire = (
   recovery?: RecoveryClass
 ): ErrorCodeSpec => ({ category, surface: 'wire', httpStatus, retryable, message, recovery });
 
-const client = (category: ErrorCategory, message: string): ErrorCodeSpec => ({
+const client = (
+  category: ErrorCategory,
+  message: string,
+  recovery?: RecoveryClass
+): ErrorCodeSpec => ({
   category,
   surface: 'client',
   retryable: false,
   message,
+  ...(recovery !== undefined ? { recovery } : {}),
 });
 
 /**
@@ -575,6 +580,22 @@ export const ERROR_CODES = {
     'validation',
     'The CLI was invoked with an unknown flag or a malformed flag value.'
   ),
+  // recovery `none`: no credential EXISTS yet, so the auth-category default
+  // ('auth_blocked' — "the credential was rejected") would tell the reader to
+  // inspect a key they don't have. The message carries the actual next step.
+  cli_api_key_missing: client(
+    'auth',
+    'The command needs an API key and none was found on this machine. Run `ablo login` (or set ABLO_API_KEY), then re-run the command.',
+    'none'
+  ),
+  cli_database_url_missing: client(
+    'validation',
+    'The command needs a database connection string and none was found — no DATABASE_URL in the process environment, .env.local, or .env, and no --url flag.'
+  ),
+  cli_database_unreachable: client(
+    'transport',
+    'The database named by the connection string could not be reached from this machine. The host, port, network, or credential refused the dial before any statement ran.'
+  ),
   commit_operation_required: wire(
     'validation',
     400,
@@ -1029,6 +1050,14 @@ export const ERROR_CODES = {
     'transport',
     'This environment provides no `fetch` implementation, so HTTP requests cannot be made. Run on a platform with `fetch` (Node 18+, modern browsers) or supply a polyfill.'
   ),
+  api_unreachable: client(
+    'transport',
+    'The Ablo API could not be reached from this machine — the dial failed before any request arrived. Check the network, any proxy, and an ABLO_API_URL override, then retry.'
+  ),
+  response_unrecognized: client(
+    'transport',
+    'The server answered successfully, but with a body this client does not recognize. The client may be older than the server — update it and retry.'
+  ),
   base_url_missing: client(
     'transport',
     'The client has no base URL configured, so it cannot address the server. Set the base URL when constructing the client.'

package/src/errors.ts

@@ -810,10 +810,13 @@ const ENVELOPE_KEYS: ReadonlySet<string> = new Set([
   'request_id',
   // Read into typed properties below, so they are not detail as well.
   'error',
-  'reason',
   'requiredCapability',
   'claims',
   'heldByClaim',
+  // `reason` is deliberately NOT here: it is domain detail (a driver's words
+  // beside the server's message), not an envelope field — the canonical
+  // envelope schema has no such key — so it must survive into `details` for a
+  // consumer that renders it as a secondary line.
 ]);
 
 /** The non-envelope remainder of an error body — what `details` was before it
@@ -839,10 +842,14 @@ export function translateHttpError(
       : undefined;
   const flatError = typeof parsed.error === 'string' ? parsed.error : undefined;
   const code = parsed.code ?? nested?.code ?? flatError;
+  // The producer's `message` outranks a `reason`: the message is the sentence a
+  // server wrote for a person (what happened and the remedy), while `reason` is
+  // raw diagnostic text — a database driver's words — attached beside it. A body
+  // that carries only `reason` still reads it, as older endpoints did.
   const message =
     nested?.message ??
-    parsed.reason ??
     parsed.message ??
+    parsed.reason ??
     flatError ??
     (typeof body === 'string' ? body : `HTTP ${status}`);
   const requiredCapability =

package/src/index.ts

@@ -47,6 +47,10 @@ export type { ModelData } from './types/modelData.js';
 // The error hierarchy and its wire/recovery helpers.
 export * from './errors.js';
 
+// The price of the product: tiers, rate card, and the bill arithmetic the
+// published pricing page and the runtime caps both derive from.
+export * from './pricing.js';
+
 // Pre-seam leaf surfaces, kept for compatibility with the first extraction.
 export * from './errorCodes.js';
 export * from './environment.js';

package/src/policy/types.ts

@@ -107,8 +107,16 @@ export type ConflictDecision =
    *
    * The monotonic `sync_id` landing order decides who yields: the stale
    * committer always recomputes against the newer value, an asymmetry that
-   * prevents two notifying writers from looping against each other. Retries are
-   * bounded by the client's reconciliation retry cap.
+   * prevents two notifying writers from looping against each other.
+   *
+   * That rules out livelock, and NOT starvation. Each round adopts a newer
+   * `observedSyncId`, so no baseline repeats — but a peer writing faster than
+   * the committer's read→decide→write gap keeps winning, and the rounds are
+   * unbounded because the engine does not re-issue: the actor does. Progress in
+   * the watermark is not progress in the work. The functional `update(id, fn)`
+   * bounds its own loop; a hand-rolled one must bound itself. To stop an actor
+   * writing at all while a belief it holds is stale, gate the belief —
+   * `track(..., { onStale: 'reject' })` — rather than the write.
    */
   | { readonly action: 'notify'; readonly reason?: string };
 

package/src/pricing.ts

@@ -0,0 +1,350 @@
+/**
+ * What Ablo costs, expressed as arithmetic rather than as a table someone
+ * retypes. This module owns the price: the tiers, the rate card the meter is
+ * charged against, and the functions that turn a month of usage into a bill.
+ * The published pricing page, the plan seeds, and the runtime caps all derive
+ * from here; nothing restates it.
+ *
+ * The shape has three parts, and each one exists because a different cost does.
+ *
+ *   - A monthly floor per tier. Serving an organization costs money before it
+ *     sends a single request: a lane of the commit engine, a replication reader
+ *     per registered source, and the log it appends to. The floor pays for that
+ *     standing capacity, and usage is charged against it rather than added to
+ *     it. An organization pays the greater of the two, never both.
+ *   - A metered rate on `ops`, the one number that collapses commits, reads,
+ *     and claim creates. Marginal service is cheap enough that a second axis
+ *     would buy precision nobody wants: at the measured 79.5 microseconds of
+ *     CPU per delta, a vCPU-hour serves roughly 45 million of them. The cost
+ *     that scales is the log those operations leave behind, and it scales with
+ *     all three of them together.
+ *   - A concurrent-connection cap, which is a limit and not a meter. A held
+ *     socket is a real reservation whether or not it is busy, so it is bounded
+ *     rather than billed.
+ *
+ * The allowance a tier advertises is DERIVED, never stored: "the floor covers
+ * 49.5M operations" is {@link opsForUsd} applied to the floor. Storing it
+ * alongside the floor is how a published price silently stops matching the
+ * invoice, because raising one number does not fail anything that pins the
+ * other.
+ *
+ * Storage is deliberately absent from {@link billableAxisSchema}. It is a real
+ * recurring cost and it is quoted per tier as a ceiling, but no per-organization
+ * bytes sampler emits it yet, and pricing a dimension nothing measures would be
+ * a claim the invoice cannot support. Add the axis when the sampler ships.
+ */
+
+import { z } from 'zod';
+import { meterEventSchema, planTierSchema, rateBracketSchema } from './wire/pricing.js';
+import type { MeterEvent, PlanTier, RateBracket } from './wire/pricing.js';
+
+export { meterEventSchema, planTierSchema, rateBracketSchema };
+export type { MeterEvent, PlanTier, RateBracket };
+
+/**
+ * The version of the pricing contract: the tiers, the rate card, and the way a
+ * bill is computed from them. Date-based, and changed only when a customer
+ * could observe the difference. It is emitted into the generated pricing
+ * documentation so a stale copy is identifiable on sight.
+ */
+export const PRICING_VERSION = '2026-07-27';
+
+/**
+ * Resolve a stored plan string (`stripe_subscription.plan`) to a tier.
+ *
+ * Anything unrecognized resolves to `free` rather than throwing, so an unknown
+ * plan degrades to the safest caps instead of taking down the request path.
+ *
+ * There are deliberately no aliases. A name this enum does not carry belongs to
+ * some other product's tier vocabulary, and translating it here is how one
+ * product's subscription came to grant another product's entitlements. The
+ * caller filters to plans this contract names; see `resolveOrgTier`.
+ */
+export function toPlanTier(plan: string | null | undefined): PlanTier {
+  const raw = (plan ?? 'free').trim().toLowerCase();
+  return planTierSchema.catch('free').parse(raw);
+}
+
+/**
+ * The axes a bill is actually computed from: `ops` is metered, `connections` is
+ * capped. Storage is quoted but not billed, so it is not here.
+ */
+export const billableAxisSchema = z.enum(['ops', 'connections']);
+export type BillableAxis = z.infer<typeof billableAxisSchema>;
+
+/** Which billable axis each meter rolls into. `null` is recorded but unpriced. */
+export const METER_EVENT_AXIS: Record<MeterEvent, BillableAxis | null> = {
+  'api.commit_ops': 'ops',
+  'api.model_reads': 'ops',
+  'api.claim_creates': 'ops',
+  'api.bootstraps': null,
+};
+
+/** How each meter reads on an invoice line and in the pricing table. */
+export const METER_EVENT_LABEL: Record<MeterEvent, string> = {
+  'api.commit_ops': 'commit operations',
+  'api.model_reads': 'model reads',
+  'api.claim_creates': 'claim creates',
+  'api.bootstraps': 'bootstraps',
+};
+
+/** The meters a customer is charged for, in declaration order. */
+export const BILLABLE_METER_EVENTS: readonly MeterEvent[] = (
+  meterEventSchema.options as readonly MeterEvent[]
+).filter((event) => METER_EVENT_AXIS[event] !== null);
+
+export const planFeatureSchema = z.enum([
+  'sso',
+  'auditExport',
+  'cmek',
+  'privateNetworking',
+  'customCaps',
+]);
+export type PlanFeature = z.infer<typeof planFeatureSchema>;
+
+/** How each feature reads on the pricing page. */
+export const PLAN_FEATURE_LABEL: Record<PlanFeature, string> = {
+  sso: 'Single sign-on',
+  auditExport: 'Audit log export',
+  cmek: 'Customer-managed encryption keys',
+  privateNetworking: 'Private networking',
+  customCaps: 'Custom limits',
+};
+
+/**
+ * The rate card, validated as a card rather than as three unrelated objects:
+ * ceilings ascend, rates never increase as volume grows, and exactly one
+ * unbounded step closes it. A malformed card fails at module load, which is the
+ * only moment it can fail safely.
+ */
+const rateCardSchema = z
+  .array(rateBracketSchema)
+  .min(1)
+  .superRefine((brackets, ctx) => {
+    let previousCeiling = 0;
+    let previousRate = Number.POSITIVE_INFINITY;
+    brackets.forEach((bracket, index) => {
+      const isLast = index === brackets.length - 1;
+      if (isLast !== (bracket.throughOps === null)) {
+        ctx.addIssue({
+          code: 'custom',
+          message: `bracket ${index}: only the final bracket may be unbounded`,
+        });
+        return;
+      }
+      if (bracket.throughOps !== null) {
+        if (bracket.throughOps <= previousCeiling) {
+          ctx.addIssue({
+            code: 'custom',
+            message: `bracket ${index}: ceiling ${bracket.throughOps} does not exceed ${previousCeiling}`,
+          });
+        }
+        previousCeiling = bracket.throughOps;
+      }
+      if (bracket.usdPerMillionOps > previousRate) {
+        ctx.addIssue({
+          code: 'custom',
+          message: `bracket ${index}: rate rises with volume`,
+        });
+      }
+      previousRate = bracket.usdPerMillionOps;
+    });
+  });
+
+/**
+ * The published rate card for sync operations. These numbers are the tunable
+ * knob; the bracket structure is the contract.
+ */
+export const OPS_RATE_CARD: readonly RateBracket[] = rateCardSchema.parse([
+  { throughOps: 50_000_000, usdPerMillionOps: 2.0 },
+  { throughOps: 500_000_000, usdPerMillionOps: 1.2 },
+  { throughOps: null, usdPerMillionOps: 0.6 },
+]);
+
+/**
+ * A tier. `null` on a floor, a cap, or a quota means negotiated rather than
+ * unlimited, and the runtime treats it as "no typed default, use the operator's
+ * configured value".
+ */
+export const planDefinitionSchema = z.object({
+  tier: planTierSchema,
+  label: z.string(),
+  /** One line on the pricing page saying who the tier is for. */
+  summary: z.string(),
+  /**
+   * The monthly floor in USD. Usage is charged against it, not added to it, so
+   * an organization pays this or its metered usage, whichever is greater.
+   * `null` means the floor is set in the contract.
+   */
+  monthlyMinimumUsd: z.number().nonnegative().nullable(),
+  /**
+   * A hard monthly stop on operations. Set only where the tier is not billed at
+   * all: Free is capped rather than metered, so exceeding it is refused instead
+   * of invoiced. `null` on every metered tier.
+   */
+  hardCapOps: z.number().int().positive().nullable(),
+  /**
+   * A hard daily stop, which is a burst guard rather than an allowance. A month
+   * of operations is a comfortable month of building and about ten minutes of
+   * one agent at full rate, so a monthly cap alone lets a runaway loop erase the
+   * whole month before anyone notices. The daily figure is what turns that into
+   * a floor on how fast the month can be spent. `null` on metered tiers, which
+   * are billed rather than stopped.
+   */
+  hardCapOpsPerDay: z.number().int().positive().nullable(),
+  /** Quoted ceiling on stored data, in GiB. Not billed. `null` is negotiated. */
+  storageGib: z.number().positive().nullable(),
+  /** Hard concurrent-connection cap, the real Free to Scale boundary. */
+  maxConcurrentConnections: z.number().int().positive().nullable(),
+  /** True when the terms are set in a contract rather than published in full. */
+  contractPriced: z.boolean(),
+  features: z.array(planFeatureSchema),
+});
+export type PlanDefinition = z.infer<typeof planDefinitionSchema>;
+
+export const PLANS = z
+  .object({
+    free: planDefinitionSchema,
+    scale: planDefinitionSchema,
+    enterprise: planDefinitionSchema,
+  })
+  .parse({
+    free: {
+      tier: 'free',
+      label: 'Free',
+      summary: 'Build against the real engine without a card.',
+      monthlyMinimumUsd: 0,
+      hardCapOps: 1_000_000,
+      hardCapOpsPerDay: 100_000,
+      storageGib: 1,
+      maxConcurrentConnections: 25,
+      contractPriced: false,
+      features: [],
+    },
+    scale: {
+      tier: 'scale',
+      label: 'Scale',
+      summary: 'Production traffic, metered above a monthly floor.',
+      monthlyMinimumUsd: 99,
+      hardCapOps: null,
+      hardCapOpsPerDay: null,
+      storageGib: 50,
+      maxConcurrentConnections: 1_000,
+      contractPriced: false,
+      features: ['auditExport'],
+    },
+    enterprise: {
+      tier: 'enterprise',
+      label: 'Enterprise',
+      summary: 'Committed volume, private networking, and an uptime guarantee.',
+      monthlyMinimumUsd: 2_000,
+      hardCapOps: null,
+      hardCapOpsPerDay: null,
+      storageGib: null,
+      maxConcurrentConnections: null,
+      contractPriced: true,
+      features: ['sso', 'auditExport', 'cmek', 'privateNetworking', 'customCaps'],
+    },
+  }) satisfies Record<PlanTier, PlanDefinition>;
+
+/** The tiers in the order they are presented, cheapest first. */
+export const PLAN_ORDER: readonly PlanTier[] = ['free', 'scale', 'enterprise'];
+
+/** Round to whole cents. Money that is not rounded at the boundary is money
+ *  that disagrees with the invoice by a fraction nobody can explain. */
+function roundUsd(usd: number): number {
+  return Math.round(usd * 100) / 100;
+}
+
+/**
+ * What a month of `ops` costs at the rate card, before any floor is applied.
+ * Marginal across brackets: the first 50 million are charged at the first rate
+ * whatever the total turns out to be.
+ */
+export function usdForOps(ops: number): number {
+  if (!Number.isFinite(ops) || ops <= 0) return 0;
+  let remaining = ops;
+  let previousCeiling = 0;
+  let usd = 0;
+  for (const bracket of OPS_RATE_CARD) {
+    const span =
+      bracket.throughOps === null
+        ? Number.POSITIVE_INFINITY
+        : bracket.throughOps - previousCeiling;
+    const charged = Math.min(remaining, span);
+    usd += (charged / 1_000_000) * bracket.usdPerMillionOps;
+    remaining -= charged;
+    if (remaining <= 0) break;
+    if (bracket.throughOps !== null) previousCeiling = bracket.throughOps;
+  }
+  return roundUsd(usd);
+}
+
+/**
+ * The inverse: how many operations a given spend buys at the rate card. This is
+ * what turns a floor into the allowance a tier advertises, which is why the
+ * allowance can never drift from the floor.
+ */
+export function opsForUsd(usd: number): number {
+  if (!Number.isFinite(usd) || usd <= 0) return 0;
+  let remaining = usd;
+  let previousCeiling = 0;
+  let ops = 0;
+  for (const bracket of OPS_RATE_CARD) {
+    const span =
+      bracket.throughOps === null
+        ? Number.POSITIVE_INFINITY
+        : bracket.throughOps - previousCeiling;
+    if (bracket.usdPerMillionOps === 0) return Number.POSITIVE_INFINITY;
+    const spanCost = (span / 1_000_000) * bracket.usdPerMillionOps;
+    if (remaining <= spanCost) {
+      return Math.floor(ops + (remaining / bracket.usdPerMillionOps) * 1_000_000);
+    }
+    ops += span;
+    remaining -= spanCost;
+    if (bracket.throughOps !== null) previousCeiling = bracket.throughOps;
+  }
+  return Math.floor(ops);
+}
+
+/**
+ * The operations a tier includes, as shown on the pricing page. A capped tier
+ * shows its cap; a metered tier shows what its floor covers, computed from the
+ * floor rather than stored beside it. `null` where the terms are contractual.
+ */
+export function monthlyOpsAllowance(tier: PlanTier): number | null {
+  const plan = PLANS[tier];
+  if (plan.hardCapOps !== null) return plan.hardCapOps;
+  if (plan.contractPriced || plan.monthlyMinimumUsd === null) return null;
+  return opsForUsd(plan.monthlyMinimumUsd);
+}
+
+/**
+ * The invoice for a month: the floor, or the metered usage, whichever is
+ * greater. A capped tier is never billed above its floor because the cap is
+ * enforced before the usage exists. `null` where the terms are contractual.
+ */
+export function monthlyBillUsd(tier: PlanTier, ops: number): number | null {
+  const plan = PLANS[tier];
+  if (plan.contractPriced || plan.monthlyMinimumUsd === null) return null;
+  if (plan.hardCapOps !== null) return plan.monthlyMinimumUsd;
+  return roundUsd(Math.max(plan.monthlyMinimumUsd, usdForOps(ops)));
+}
+
+/**
+ * The daily operations cap for a tier: the typed default the quota gate falls
+ * back to when no `plan_limit` row sets one. `null` means the tier is metered
+ * rather than stopped.
+ */
+export function dailyOpsCapForTier(tier: PlanTier): number | null {
+  return PLANS[tier].hardCapOpsPerDay;
+}
+
+/**
+ * The concurrent-connection cap for a tier: the typed default the Hub's
+ * resolver falls back to when no `plan_limit` override row exists. `null` means
+ * negotiated, which the Hub reads as its configured floor.
+ */
+export function connectionCapForTier(tier: PlanTier): number | null {
+  return PLANS[tier].maxConcurrentConnections;
+}

package/src/resources/functionalUpdate.ts

@@ -53,6 +53,17 @@ export interface ContentionOptions {
 /** Reconcile rounds before a hot row is declared permanently contended. */
 export const DEFAULT_CONTENTION_RETRIES = 16;
 
+const sleep = (ms: number): Promise<void> =>
+  new Promise((resolve) => setTimeout(resolve, ms));
+
+/**
+ * Jittered backoff so N reconcilers retrying at once don't lock-step straight
+ * back into the same collision. Bounded; grows mildly with the attempt.
+ */
+function backoffMs(attempt: number): number {
+  return 60 + attempt * 40 + Math.floor(Math.random() * 60);
+}
+
 /**
  * Reports whether a thrown error means "another writer moved the row — re-read
  * and retry" rather than a genuine failure to surface. These are the
@@ -69,17 +80,6 @@ export function isReconcilableConflict(err: unknown): boolean {
   return false;
 }
 
-const sleep = (ms: number): Promise<void> =>
-  new Promise((resolve) => setTimeout(resolve, ms));
-
-/**
- * Jittered backoff so N reconcilers retrying at once don't lock-step straight
- * back into the same collision. Bounded; grows mildly with the attempt.
- */
-function backoffMs(attempt: number): number {
-  return 60 + attempt * 40 + Math.floor(Math.random() * 60);
-}
-
 /**
  * The transport-specific read and write that the shared loop drives. Each client
  * injects its own pair — the one thing that differs between the HTTP and

package/src/schema/index.ts

@@ -170,6 +170,7 @@ export {
   type RoleSource,
   type RoleContext,
   type SyncGroup,
+  type SyncGroupRef,
   type SyncGroupInput,
   identityRole,
   entityRole,
@@ -177,6 +178,7 @@ export {
   extractEntityIds,
   syncGroup,
   syncGroupSchema,
+  syncGroupRefSchema,
   syncGroupInputSchema,
   isSyncGroupInput,
   identityRoleSchema,

package/src/schema/roles.ts

@@ -31,9 +31,32 @@ import { z } from 'zod';
  * {@link syncGroup}. Because the brand is an intersection it's still assignable
  * *to* `string`, so existing `string[]` plumbing keeps working unchanged.
  */
-export const syncGroupSchema = z
-  .templateLiteral([z.string().regex(/^[a-z][a-z0-9_]*$/), ':', z.string().min(1)])
-  .brand<'SyncGroup'>();
+/**
+ * The `kind:id` shape itself, unbranded — what a CALLER writes.
+ *
+ * Input and output want different strictness from one format, so the format is
+ * declared once here and viewed two ways. This view rejects `'nonsense'` at
+ * compile time (no colon ⇒ matches no group) while still accepting
+ * `` `org:${orgId}` `` written inline, which is the whole point of
+ * {@link SyncGroupInput}. Requiring the constructor on an input field buys no
+ * safety this does not already give and costs every call site a helper import.
+ */
+export const syncGroupRefSchema = z.templateLiteral([
+  z.string().regex(/^[a-z][a-z0-9_]*$/),
+  ':',
+  z.string().min(1),
+]);
+
+export type SyncGroupRef = z.infer<typeof syncGroupRefSchema>;
+
+/**
+ * The same format, branded — what the SERVER hands back.
+ *
+ * The brand earns its keep on the way out, where Ablo is the author: a consumer
+ * that receives a `SyncGroup` knows it was minted, and a raw string cannot
+ * masquerade as one.
+ */
+export const syncGroupSchema = syncGroupRefSchema.brand<'SyncGroup'>();
 
 export type SyncGroup = z.infer<typeof syncGroupSchema>;
 

package/src/schema/schema.ts

@@ -41,6 +41,7 @@ export {
   type RoleSource,
   type RoleContext,
   type SyncGroup,
+  type SyncGroupRef,
   type SyncGroupInput,
   identityRole,
   entityRole,
@@ -51,6 +52,7 @@ export {
   intersectRequestedWithAllowed,
   syncGroup,
   syncGroupSchema,
+  syncGroupRefSchema,
   syncGroupInputSchema,
   isSyncGroupInput,
   identityRoleSchema,

package/src/transport/wsFrameHandlers.ts

@@ -180,10 +180,16 @@ const handleMutationResult: WsFrameHandler = (session, message) => {
       const event = {
         clientTxId: txId,
         rows: receipt.notifications.map((n) => ({
-          model: n.model,
-          id: n.id,
-          fields: n.conflictingFields,
+          // The row that moved, in both scopes. A group notification used to
+          // report its group key here, so the log named a row that does not
+          // exist; the premise it breached is reported as `group` instead.
+          model: n.target.model,
+          id: n.target.id,
+          fields: n.target.fields ?? [],
           writtenBy: n.writtenBy.kind,
+          ...(n.scope === 'group'
+            ? { group: n.group, ...(n.propagation ? { via: n.propagation.via } : {}) }
+            : {}),
         })),
       };
       const message = formatConflict(event);

package/src/wire/accountResponses.ts

@@ -19,6 +19,9 @@ import { z } from 'zod';
 // response exists to stop withholding.
 import { fieldMetaSchema, relationMetaSchema } from './modelShape.js';
 import { onStaleModeSchema } from '../coordination/schema.js';
+// The price's own vocabulary. A dashboard that restated the tier names or the
+// meter set would be a second definition of what the invoice is computed from.
+import { meterEventSchema, planTierSchema, rateBracketSchema } from './pricing.js';
 import type { SyncDeltaAction } from './delta.js';
 import { deltaSchema } from './delta.js';
 // Kept for the {@link ListEnvelope} references below; `GET /v1/logs`'s own
@@ -325,3 +328,76 @@ export const usageReportResponseSchema = z.object({
   data_freshness_seconds: z.number(),
 });
 export type UsageReportResponse = z.infer<typeof usageReportResponseSchema>;
+
+/**
+ * One meter's month-to-date usage, as a management surface shows it.
+ *
+ * `eventName` is the pricing contract's closed set rather than a free string,
+ * so a surface cannot render a meter the price does not recognise. `billable`
+ * says whether the meter reaches an invoice at all: bootstraps are recorded and
+ * gated but never charged, and a usage table that does not say so reads as a
+ * bill nobody sent.
+ */
+export const meterUsageSchema = z.object({
+  eventName: meterEventSchema,
+  displayName: z.string(),
+  /** Operations counted this period. */
+  total: z.number(),
+  /** Requests behind that total. A commit of 500 operations counts once here. */
+  count: z.number(),
+  /** The plan's monthly allowance for this meter; null where it is ungated. */
+  monthlyMax: z.number().nullable(),
+  billable: z.boolean(),
+});
+export type MeterUsage = z.infer<typeof meterUsageSchema>;
+
+/**
+ * What the period costs, computed once by the server from the pricing contract.
+ *
+ * The client renders these rather than recomputing them. A dashboard that does
+ * its own arithmetic is a second implementation of the price, and the one a
+ * customer reads before they are billed, so it is the copy that has to be
+ * right and the one nothing checks.
+ */
+export const billingSummarySchema = z.object({
+  tier: planTierSchema,
+  /** The tier as it reads on the pricing page. */
+  label: z.string(),
+  /** The monthly floor in USD; null where terms are contractual. */
+  monthlyMinimumUsd: z.number().nullable(),
+  /** Operations the floor already covers, or the hard cap on a capped tier. */
+  includedOps: z.number().nullable(),
+  /** Where the tier stops rather than bills; null on every metered tier. */
+  hardCapOps: z.number().nullable(),
+  /** The daily burst guard; null on every metered tier. */
+  dailyCapOps: z.number().nullable(),
+  /** Every billable meter, collapsed into the one number the price uses. */
+  opsUsed: z.number(),
+  /** The floor or the metered usage, whichever is greater. null = contract. */
+  projectedBillUsd: z.number().nullable(),
+  /** True where the published card is a starting point, not the terms. */
+  contractPriced: z.boolean(),
+  /**
+   * The rate card in force, so a surface can show what the next operation
+   * costs without shipping a copy of the price to the browser.
+   */
+  rateCard: z.array(rateBracketSchema).readonly(),
+});
+export type BillingSummary = z.infer<typeof billingSummarySchema>;
+
+/**
+ * `GET /v1/dashboard/usage-summary` — month-to-date usage and what it costs.
+ *
+ * Distinct from {@link usageReportResponseSchema}, which answers the public
+ * `GET /v1/usage` with daily buckets for a caller doing its own analysis. This
+ * one answers the question a person opens a dashboard to ask: what have I used,
+ * and what will it cost.
+ */
+export const usageSummaryResponseSchema = z.object({
+  plan: planTierSchema,
+  /** Start of the billing period the numbers cover, ISO-8601. */
+  periodStart: z.string(),
+  meters: z.array(meterUsageSchema).readonly(),
+  billing: billingSummarySchema,
+});
+export type UsageSummaryResponse = z.infer<typeof usageSummaryResponseSchema>;