@hachej/boring-core 0.1.41 → 0.1.43

package/README.md

@@ -7,314 +7,63 @@
 
 </div>
 
-The foundation package for boring-ui apps: Postgres/Drizzle database schema, email/password auth (better-auth), config loader, Fastify HTTP app factory, and React frontend shell. Every child app imports core first.
+The foundation package for boring-ui v2 apps: Postgres/Drizzle database, better-auth
+(email/password, verification, password reset, magic links, optional Google), TOML+env
+config loader, Fastify HTTP app factory, and a React frontend shell with auth/workspace
+gating. Every child app imports core first; domain logic, agent runtime, and workspace UI
+come from the sibling `@hachej/boring-*` packages.
 
 ```bash
 pnpm add @hachej/boring-core
 ```
 
----
-
-## TL;DR
-
-**The Problem**: Building a multi-user agent-powered app means re-implementing auth, sessions, workspaces, invites, email flows, and an app shell every single time. These are the same across every deployment.
-
-**The Solution**: `@hachej/boring-core` provides a complete app skeleton — Postgres DB, better-auth with email verification + password reset + magic links, workspace membership with roles, email transport (Resend/SMTP/console), and a `<BoringApp>` React shell with auth pages. You bring the domain logic.
-
-### Why Use @hachej/boring-core?
-
-| Feature | What It Does |
-|---------|--------------|
-| **Full auth suite** | Email/password + email verification + password reset + magic links (better-auth) |
-| **Workspace management** | Create, update, delete workspaces; member roles (owner/editor/viewer); invites |
-| **Fastify app factory** | Pre-wired with helmet, CORS, rate limiting, secret redaction, graceful shutdown |
-| **Drizzle + Postgres** | Ready-to-run schema for users, workspaces, members, invites, settings |
-| **Email transport** | Resend (default), SMTP, or console — pluggable via URL scheme |
-| **<BoringApp> shell** | Client-rendered React shell with auth gate, theme toggle, workspace switcher |
-| **Config loader** | TOML + env vars merged, Zod-validated, redacted for frontend |
+## Usage essentials
 
----
-
-## Quick Example
+Most apps use the composed `app/*` surfaces, which fuse core + workspace + agent:
 
 ```ts
-// Server — 4 lines to a full app
-import { createCoreApp, loadConfig } from "@hachej/boring-core/server"
-
-const config = await loadConfig()
-const app = await createCoreApp(config)  // Fastify + DB + auth + routes
+// server entry
+import { createCoreWorkspaceAgentServer } from "@hachej/boring-core/app/server"
 
+const app = await createCoreWorkspaceAgentServer({ plugins })
 await app.listen({ port: 3000 })
 ```
 
 ```tsx
-// Frontend — mount auth gate + workspace routing
-<BoringApp>
-  <Route path="/workspace/:id" element={<WorkspaceRoute />} />
-  <Route path="/settings" element={<Settings />} />
-</BoringApp>
-```
-
-```tsx
-// In your components — typed auth + workspace access
-const user = useUser()
-const workspace = useCurrentWorkspace()
-const role = useWorkspaceRole()  // 'owner' | 'editor' | 'viewer'
-```
-
----
-
-## Design Philosophy
-
-1. **Core owns persistence and identity** — DB tables, auth, sessions, workspaces, invites. Everything else injects stores via interfaces.
-2. **One config source** — `boring.app.toml` + environment variables merged, Zod-validated at boot. No scattered config.
-3. **Email flows are real, not stubs** — password reset, email verification, magic links, workspace invites — all shipped with React Email templates.
-4. **Swap seams, not rewrites** — `AuthProvider`, `UserStore`, `WorkspaceStore` are interfaces. The default impl is Postgres; swap via `createCoreApp({ authProvider })`.
-5. **Fail closed on auth** — config fetch failure throws a `ConfigFetchError` with retries. Users see "Cannot reach server" not a blank page.
-
----
-
-## Installation
-
-```bash
-# pnpm
-pnpm add @hachej/boring-core @hachej/boring-workspace
-
-# npm
-npm install @hachej/boring-core @hachej/boring-workspace
-
-# from source
-git clone https://github.com/hachej/boring-ui.git
-cd boring-ui && pnpm install
-pnpm --filter @hachej/boring-core build
-```
-
-### Dependencies
-
-Postgres is required for production. For dev, set `CORE_STORES=local` and core runs in-memory (state resets on restart).
-
----
-
-## Quick Start
-
-### 1. Set Environment
-
-```bash
-# .env
-DATABASE_URL=postgres://user:pass@localhost:5432/myapp
-BETTER_AUTH_SECRET=<32-byte random hex>
-BETTER_AUTH_URL=http://localhost:3000
-WORKSPACE_SETTINGS_ENCRYPTION_KEY=<32-byte hex>
-MAIL_FROM=noreply@myapp.dev
-MAIL_TRANSPORT_URL=resend://re_xxxxxxxxxxxxxxxx
-```
-
-### 2. Create Config File
-
-```toml
-# boring.app.toml
-[app]
-id = "my-app"
-
-[frontend.branding]
-name = "My App"
-logo = "/logo.svg"
-
-[features]
-invites_enabled = true
-invite_ttl_days = 7
-```
-
-### 3. Run Migrations
-
-```bash
-pnpm drizzle-kit generate --config node_modules/@hachej/boring-core/drizzle.config.ts
-pnpm drizzle-kit migrate --config node_modules/@hachej/boring-core/drizzle.config.ts
-```
-
-### 4. Server Entry
-
-```ts
-import { createCoreApp, loadConfig } from "@hachej/boring-core/server"
-
-const config = await loadConfig()
-const app = await createCoreApp(config)
-
-// add child-app routes
-app.get("/api/v1/my-thing", async () => ({ ok: true }))
-
-await app.listen({ port: config.port })
-```
-
-### 5. Frontend Entry
-
-```tsx
+// frontend entry
 import { createRoot } from "react-dom/client"
-import { BoringApp } from "@hachej/boring-core/front"
-import { Route } from "react-router-dom"
-import "@hachej/boring-core/theme.css"
+import { CoreWorkspaceAgentFront } from "@hachej/boring-core/app/front"
+import "@hachej/boring-core/app/front/styles.css"
 
 createRoot(document.getElementById("root")!).render(
-  <BoringApp>
-    <Route path="/" element={<Dashboard />} />
-  </BoringApp>,
+  <CoreWorkspaceAgentFront apiBaseUrl="" chatEntryMode="chat-first" plugins={plugins} />,
 )
 ```
 
----
-
-## Package Surfaces
+For a core-only app (no agent/workspace), use `createCoreApp(config)` from
+`@hachej/boring-core/server` and `CoreFront` from `@hachej/boring-core/front`.
 
-| Import | Environment | What You Get |
-|--------|-------------|--------------|
-| `@hachej/boring-core/server` | Node | `createCoreApp`, `loadConfig`, auth, stores, routes |
-| `@hachej/boring-core/server/db` | Node | Drizzle schema, migrations, store interfaces |
-| `@hachej/boring-core/front` | Browser | `<BoringApp>`, hooks, auth pages, components |
-| `@hachej/boring-core/shared` | Any | `User`, `Workspace`, `HttpError`, `ErrorCode` types |
-| `@hachej/boring-core/theme.css` | Browser | CSS theme tokens for the frontend shell |
-| `@hachej/boring-core/app/front` | Browser | App composition helpers (`WorkspaceAgentFront`, etc.) |
-| `@hachej/boring-core/app/server` | Node | App composition helpers (`createWorkspaceAgentApp`) |
+### Required environment (production)
 
----
+`DATABASE_URL`, `BETTER_AUTH_SECRET`, `BETTER_AUTH_URL`,
+`WORKSPACE_SETTINGS_ENCRYPTION_KEY`, `MAIL_FROM`, `MAIL_TRANSPORT_URL`
+(`resend://…`, `smtp://…`, or `console://`), `CORS_ORIGINS`. Config is also read from
+`boring.app.toml`. For dev without Postgres, set `CORE_STORES=local` (in-memory, resets
+on restart; not supported by `createCoreWorkspaceAgentServer`).
 
-## Configuration
+Migrations live in `drizzle/`; run them with `drizzle-kit migrate` against
+`drizzle.config.ts`.
 
-### Environment Variables
+## Documentation
 
-| Variable | Required | Description |
-|----------|----------|-------------|
-| `DATABASE_URL` | Yes (prod) | Postgres connection string |
-| `BETTER_AUTH_SECRET` | Yes | 32-byte hex — signs session cookies |
-| `BETTER_AUTH_URL` | Yes | Public URL for OAuth callbacks |
-| `WORKSPACE_SETTINGS_ENCRYPTION_KEY` | Yes (prod) | 32-byte hex — encrypts workspace settings |
-| `MAIL_FROM` | Yes (prod) | Sender address for auth emails |
-| `MAIL_TRANSPORT_URL` | Yes (prod) | `resend://key`, `smtp://host`, or `console://` |
-| `CORE_STORES` | No | `postgres` (default) or `local` (in-memory dev) |
-| `CORS_ORIGINS` | Yes (prod) | Comma-separated allowlist |
-| `SEND_WELCOME_EMAIL` | No | Default `true` — suppress with `false` |
-| `SESSION_TTL_SECONDS` | No | Default 2,592,000 (30 days) |
-
----
-
-## Architecture
-
-```
-┌──────────────────────┐
-│   Browser Client     │
-│  /auth/* + /me +     │
-│  /workspaces/*       │
-└──────────┬───────────┘
-           │ HTTP (typed, cookie auth)
-┌──────────▼───────────┐
-│   Fastify App        │
-│  ├── authHook (req.user)
-│  ├── helmet + CORS   │
-│  ├── rate limits     │
-│  ├── secret redaction│
-│  └── graceful shutdown
-└──────────┬───────────┘
-           │
-┌──────────▼───────────┐
-│  better-auth          │
-│  (sessions, email,    │
-│   password reset)     │
-└──────────┬───────────┘
-           │
-┌──────────▼───────────┐
-│   Drizzle + Postgres │
-│  users, sessions,     │
-│  workspaces, members, │
-│  invites, settings    │
-└──────────────────────┘
-```
-
-### Error Handling Contract
-
-All errors flow through a single `setErrorHandler`:
-
-| Condition | Status | Code |
-|-----------|--------|------|
-| No/expired session | 401 | `unauthorized` |
-| Insufficient role | 403 | `forbidden` / `not_member` |
-| Zod validation fail | 400 | `validation_failed` |
-| Rate limited | 429 | `rate_limited` + `Retry-After` |
-| DB ping fails | 503 | `db_unavailable` |
-| Everything else | 500 | `internal_error` |
-
-Every response includes `{ error, code, message, requestId }`. Client-side `apiFetch` parses this into `HttpError` instances.
-
----
-
-## How @hachej/boring-core Compares
-
-| Feature | @hachej/boring-core | Supabase + custom | Firebase | Roll your own |
-|---------|---------------------|-------------------|----------|---------------|
-| Auth flows | ✅ email + reset + magic link | ✅ OAuth only | ✅ OAuth/phone | Weeks to build |
-| Workspaces + invites | ✅ owner/editor/viewer roles | ❌ Custom tables | ❌ Custom rules | ~1 week |
-| Email templates | ✅ 5 React Email templates | ❌ You write them | ❌ SendGrid setup | ~3 days |
-| App shell | ✅ `<BoringApp>` + hooks | ❌ DIY | ❌ DIY | ~1 week |
-| Rate limiting | ✅ pre-wired routes | ❌ Edge functions | ⚠️ Cloud rules | ~2 days |
-| Config validation | ✅ TOML + env + Zod | ❌ dotenv only | ⚠️ Remote config | Custom |
-
-**When to use @hachej/boring-core:**
-- Building a multi-user app around an AI agent
-- You need auth + workspaces + invites in days, not weeks
-- You're deploying to Fly.io, Render, Railway, or any Postgres-capable host
-
-**When it might not fit:**
-- You need server-side rendering (client-rendered only)
-- You want SQLite (Postgres-only with Drizzle)
-- You need Google/Apple/Discord OAuth (planned for v1.x)
-- You need billing/Stripe integration (future `@boring/cloud` package)
-
----
-
-## Troubleshooting
-
-| Error | Cause | Fix |
-|-------|-------|-----|
-| `ConfigValidationError` at boot | Missing required env var | Check `.env` has all required vars |
-| `config_fetch_failed` in browser | API server not reachable | Verify `BETTER_AUTH_URL` matches |
-| `mail_disabled` warning at boot | `MAIL_FROM` not set | Set `MAIL_TRANSPORT_URL=console://` for dev |
-| `unauthorized` on `/api/v1/me` | No session cookie | Check `BETTER_AUTH_URL` and `CORS_ORIGINS` |
-| `db_unavailable` on `/health` | Postgres can't connect | Verify `DATABASE_URL` and network access |
-
----
-
-## Limitations
-
-- **Postgres only** — No SQLite/libsql support in v1.
-- **Client-rendered only** — `<BoringApp>` mounts client-side. No SSR.
-- **GitHub OAuth deferred** — Planned for v1.x, bundled with agent's GitHub App install.
-- **No billing** — Stripe integration planned for `@boring/cloud` package.
-- **In-memory stores are dev-only** — `CORE_STORES=local` resets on restart. Not for production.
-- **Partial swap seams** — `AuthProvider` is swappable, but the React auth surfaces (`useSession`, sign-in pages) are better-auth-shaped.
-
----
-
-## FAQ
-
-**Q: Can I use this without Postgres?**  
-A: In dev, yes — set `CORE_STORES=local`. State is in-memory and resets on restart. For production, Postgres is required.
-
-**Q: How do I add Google/Discord OAuth?**  
-A: better-auth supports these out of the box. Add the provider config to `createAuth()` in the core source. Official v1.x support planned.
-
-**Q: Can I swap better-auth for Clerk/Neon?**  
-A: The `AuthProvider` interface is designed as a swap seam. You'll need to re-implement the React auth surfaces (`SignInPage`, `useSession`, etc.) and preserve the `users.id` continuity invariant.
-
-**Q: How do email templates work?**  
-A: Five React Email components (`VerifyEmail`, `ResetPassword`, `MagicLink`, `WorkspaceInvite`, `Welcome`) rendered via `@react-email/render`. CSS is inlined. Swap them by providing your own mail transport.
-
-**Q: What's the difference between `@hachej/boring-core/server` and `@hachej/boring-core/server/db`?**  
-A: `server` includes the full Fastify app, routes, auth, and stores. `server/db` is the Drizzle schema + connection + store interfaces only — useful for migration tooling and type-only imports.
+See [`docs/README.md`](./docs/README.md) for the architecture overview, public API
+surface, key abstractions, and links to the gating, plugin, and deployment docs. The
+reference app is [`apps/full-app`](../../apps/full-app/).
 
 ---
 
 *About Contributions:* Please don't take this the wrong way, but I do not accept outside contributions for any of my projects. I simply don't have the mental bandwidth to review anything, and it's my name on the thing, so I'm responsible for any problems it causes; thus, the risk-reward is highly asymmetric from my perspective. I'd also have to worry about other "stakeholders," which seems unwise for tools I mostly make for myself for free. Feel free to submit issues, and even PRs if you want to illustrate a proposed fix, but know I won't merge them directly. Instead, I'll have Claude or Codex review submissions via `gh` and independently decide whether and how to address them. Bug reports in particular are welcome. Sorry if this offends, but I want to avoid wasted time and hurt feelings. I understand this isn't in sync with the prevailing open-source ethos that seeks community contributions, but it's the only way I can move at this velocity and keep my sanity.
 
----
-
 ## License
 
 MIT

package/dist/PostgresMeteringStore-CzNv6xil.d.ts

@@ -0,0 +1,224 @@
+import { C as CoreConfig } from './types-CWtJ4kgd.js';
+import { PostgresJsDatabase } from 'drizzle-orm/postgres-js';
+
+interface RunMigrationsOptions {
+    migrationsFolder?: string;
+}
+declare function runMigrations(config: CoreConfig, options?: RunMigrationsOptions): Promise<void>;
+
+declare class InsufficientCreditError extends Error {
+    readonly availableMicros: number;
+    readonly requiredMicros: number;
+    readonly statusCode = 402;
+    readonly code = "PAYMENT_REQUIRED";
+    constructor(availableMicros: number, requiredMicros: number);
+}
+interface MeteringBalance {
+    userId: string;
+    grantedMicros: number;
+    usedMicros: number;
+    remainingMicros: number;
+    activeReservedMicros: number;
+    /** remainingMicros minus activeReservedMicros; what a new reservation sees. */
+    availableMicros: number;
+}
+type CreditLedgerKind = 'grant' | 'purchase' | 'usage' | 'refund' | 'fallback';
+/** One normalized, display-safe credit-ledger row for the account activity view.
+ * `amountMicros` is SIGNED: positive = credits added (grant/purchase), negative =
+ * consumed/removed (usage/refund). `description` is generic — no prompt/repo/model/
+ * provider/order/session details. */
+interface CreditLedgerEntry {
+    id: string;
+    kind: CreditLedgerKind;
+    amountMicros: number;
+    createdAt: string;
+    description: string;
+}
+interface GrantOnceInput {
+    userId: string;
+    /** Unique per (userId, reason); repeat calls with the same reason are no-ops. */
+    reason: string;
+    amountMicros: number;
+    expiresAt?: Date;
+}
+interface ReserveInput {
+    userId: string;
+    workspaceId?: string;
+    sessionId?: string;
+    /** Stable run id; at most one active reservation may exist per runId. */
+    runId: string;
+    source?: string;
+    amountMicros: number;
+    ttlSeconds: number;
+    /**
+     * Reject when the user's available balance (remaining minus active
+     * reservations) is below this floor. Defaults to amountMicros, i.e. the
+     * reservation must fit entirely.
+     */
+    minAvailableMicros?: number;
+}
+interface ReserveResult {
+    reservationId: string;
+}
+interface RecordUsageInput {
+    /** Stable idempotency key; a second insert with the same id is a no-op. */
+    usageId: string;
+    userId: string;
+    workspaceId?: string;
+    sessionId?: string;
+    runId?: string;
+    messageId?: string;
+    source?: string;
+    provider?: string;
+    model?: string;
+    inputTokens?: number;
+    outputTokens?: number;
+    cacheReadTokens?: number;
+    cacheWriteTokens?: number;
+    /** Provider-reported cost, in micros, before host pricing policy. */
+    providerCostMicros?: number;
+    /** Host-priced cost actually charged against the balance. */
+    billedCostMicros: number;
+    stopReason?: string;
+    metadata?: Record<string, unknown>;
+}
+interface RecordUsageResult {
+    inserted: boolean;
+}
+type ReservationFinalStatus = 'settled' | 'released';
+interface FinishReservationInput {
+    /** Preferred key: the id returned by reserve(). */
+    reservationId?: string;
+    /** Fallback key; pair with userId to scope across tenants. */
+    runId?: string;
+    userId?: string;
+}
+declare class PostgresMeteringStore {
+    private db;
+    constructor(db: PostgresJsDatabase);
+    /** Idempotently create a grant keyed by (userId, reason). */
+    grantOnce(input: GrantOnceInput): Promise<{
+        created: boolean;
+    }>;
+    /**
+     * Credit a purchase exactly once GLOBALLY per order id. The order id is the
+     * primary key, so a webhook retry or a delivery misrouted to a different user
+     * can never double-credit. A per-order advisory lock serializes this against
+     * revokePurchase so a refund that arrives BEFORE order_created (out-of-order
+     * delivery) leaves a 'refunded' tombstone that blocks this grant — the user
+     * never keeps credits for a refunded order. Returns `granted: false` when the
+     * order was already processed or has been refunded.
+     */
+    grantPurchaseOnce(input: {
+        orderId: string;
+        userId: string;
+        amountMicros: number;
+        source?: string;
+        storeId?: string;
+        testMode?: boolean;
+        currency?: string;
+        variantId?: string;
+    }): Promise<{
+        granted: boolean;
+    }>;
+    /**
+     * Revoke a refunded/disputed purchase. Under the same per-order advisory lock
+     * as grantPurchaseOnce, supports repeated PARTIAL refunds:
+     *  - `refundFraction` is the cumulative fraction of the order (by money) that
+     *    has been refunded — i.e. LS `refunded_amount / total` (both tax-inclusive),
+     *    which maps the refund onto the same basis as the credited amount. The
+     *    revoked credits = round(creditedMicros × fraction), capped at credited.
+     *    The method debits only the delta since the last refund. Omit (undefined)
+     *    for a full refund of the entire credited amount.
+     *  - granted order  → debit the delta, track cumulative `refunded_micros`, and
+     *    mark 'refunded' once fully revoked; returns revoked=true when a debit was
+     *    posted.
+     *  - not yet seen   → write a 'refunded' tombstone so a later order_created
+     *    cannot grant; returns revoked=false (nothing was credited yet).
+     *  - already fully refunded / no new delta → no-op; returns revoked=false.
+     */
+    revokePurchase(orderId: string, opts?: {
+        refundFraction?: number;
+        source?: string;
+        allowTombstone?: boolean;
+        expectedStoreId?: string;
+        expectedTestMode?: boolean;
+        expectedCurrency?: string;
+    }): Promise<{
+        revoked: boolean;
+    }>;
+    /**
+     * Insert a refund debit idempotently by id. If the id already exists (manual
+     * repair / corrupted retry), VERIFY the existing row is the same debit (user +
+     * amount) — throw on mismatch so a caller never records a refund the balance was
+     * not actually debited for. Returns true iff a new debit row was written.
+     */
+    private insertVerifiedLedgerDebit;
+    /** Total billed micros already recorded for a run (for fallback top-up so a
+     * partial-success run isn't charged the hold ON TOP of its real usage). */
+    billedMicrosForRun(userId: string, runId: string): Promise<number>;
+    /** Total billed micros for a specific RESERVATION (run attempt). Preferred over
+     * billedMicrosForRun for fallback top-up: runId is reused on client-nonce
+     * replay, so summing by runId would count a prior attempt's billing and let a
+     * later reusing attempt settle free. */
+    billedMicrosForReservation(userId: string, reservationId: string): Promise<number>;
+    /** Durably record that an ACTIVE reservation must be charged the fallback hold if
+     * it expires, BEFORE attempting the actual fallback charge. Committed on its own so
+     * the intent survives a subsequent failed charge write — the expiry sweep then
+     * charges a marked reservation even with zero billed rows (no free started run on a
+     * brief finalization-time DB outage). Idempotent; a no-op on a non-active row. */
+    markReservationFallbackCharge(userId: string, reservationId: string): Promise<void>;
+    getBalance(userId: string, now?: Date): Promise<MeteringBalance>;
+    /** Most-recent credit ledger for the account activity view: grants/purchases
+     * (positive) merged with usage/refund/fallback debits (negative), newest first,
+     * scoped to the user and capped at `limit` (clamped 1..50). Descriptions are
+     * generic/sanitized; zero-amount usage rows (zero-token) are omitted as noise. */
+    listLedger(userId: string, limit: number): Promise<CreditLedgerEntry[]>;
+    /**
+     * Reserve credit for a run. Serialized per user (advisory transaction
+     * lock) so concurrent reservations cannot jointly overdraw. Idempotent per
+     * runId: re-reserving while a reservation is still active returns the
+     * existing reservation instead of double-holding. Throws
+     * InsufficientCreditError when the available balance is below
+     * minAvailableMicros (default: the reservation amount itself).
+     */
+    reserve(input: ReserveInput, now?: Date): Promise<ReserveResult>;
+    /** Idempotent ledger insert; returns whether a new row was written. Serialized
+     * under the user's advisory lock so a positive debit is ordered with that user's
+     * reserve()/expiry: a debit that pushes the balance below the floor is visible to a
+     * concurrent reserve (which then waits and is refused), keeping the documented
+     * "overshoot → next run refused" boundary even for over-budget/misrouted runs. */
+    recordUsage(input: RecordUsageInput): Promise<RecordUsageResult>;
+    /**
+     * Finish a reservation. Settling also recovers reservations that expired
+     * before a delayed settlement retry, so charged usage never leaves a
+     * reservation dangling. Releasing only touches active rows. Idempotent:
+     * repeat calls are no-ops.
+     *
+     * A runId may have more than one row (an expired row plus a fresh active
+     * retry), so the runId fallback resolves to the single newest matching row
+     * — a settle never flips both the dead and the live reservation together.
+     */
+    finishReservation(input: FinishReservationInput, status: ReservationFinalStatus): Promise<{
+        updated: boolean;
+    }>;
+    /** Expire stale active reservations without charging. Returns the count. */
+    expireStaleReservations(now?: Date): Promise<number>;
+    /**
+     * Expire one user's stale active reservations under the SINGLE charge-aware
+     * policy. CALLER MUST already hold pg_advisory_xact_lock(hashtext(userId)).
+     * A reservation that reached TTL without an explicit settle/release had a failed
+     * finalization: if it has POSITIVE billed usage (`billedTotal > 0`) OR carries the
+     * durable `charge_on_expire` marker, the run did chargeable work, so top it up to
+     * the hold (idempotent) rather than free it; a reservation with only zero-billed
+     * rows and no marker is a non-billable/pre-execution abandon and is freed (so a
+     * user who closed the tab isn't over-charged).
+     */
+    private expireUserStaleReservations;
+    private computeBalance;
+    private sumGrants;
+    private sumUsage;
+    private sumActiveReservations;
+}
+
+export { type CreditLedgerEntry as C, type FinishReservationInput as F, type GrantOnceInput as G, InsufficientCreditError as I, type MeteringBalance as M, PostgresMeteringStore as P, type RecordUsageInput as R, type RecordUsageResult as a, type ReservationFinalStatus as b, type ReserveInput as c, type ReserveResult as d, type RunMigrationsOptions as e, runMigrations as r };