@pithy-sh/ledger 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pithy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,17 @@
+# @pithy-sh/ledger
+
+A per-user balance ledger for your app's economy — chips, gold, gems, credits, tokens — in your own D1. Currency-agnostic, and correct by construction.
+
+Every game with an economy needs this, not just gambling. It is the primitive under in-game currency, rewards, buy-ins, prize pools and wagers.
+
+```sh
+pithy add ledger
+```
+
+**Documentation: [pithy.sh/docs/capabilities/ledger](https://pithy.sh/docs/capabilities/ledger).** Overview, adding it, using it, and the reference: currencies, holds, idempotency, the invariants.
+
+_Everything else is on the site. `pithy.sh/docs` is canonical — new prose goes there, not here._
+
+## License
+
+MIT — adopter-side app value. The root `LICENSE` covers it.

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@pithy-sh/ledger",
+  "version": "0.1.0",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pithy-sh/pithy.git",
+    "directory": "packages/ledger"
+  },
+  "files": [
+    "src",
+    "pithy.manifest.json",
+    "!src/**/*.test.*"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "exports": {
+    "./src/*": "./src/*.ts"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json --noEmit false --outDir dist",
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "test:node": "vitest run --project=node",
+    "test:workers": "vitest run --project=workers",
+    "clean": "rm -rf dist .turbo",
+    "reset": "bun run clean && rm -rf node_modules"
+  },
+  "dependencies": {
+    "@cloudflare/workers-types": "^5.20260729.1",
+    "@hono/zod-validator": "^0.9.0",
+    "@pithy-sh/core": "workspace:*",
+    "hono": "^4.13.2",
+    "kysely": "^0.29.0",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@cloudflare/vitest-plugin": "^1.0.0",
+    "@pithy-sh/tsconfig": "workspace:*",
+    "@types/node": "^22.15.0",
+    "@vitest/coverage-v8": "^4.1.0",
+    "kysely-d1": "^0.4.0",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.0",
+    "wrangler": "^4.115.0"
+  }
+}

package/pithy.manifest.json

@@ -0,0 +1,30 @@
+{
+  "name": "ledger",
+  "package": "@pithy-sh/ledger",
+  "requiredBindings": [{ "type": "d1", "name": "DB" }],
+  "peerCapabilities": [],
+  "optionalCapabilities": ["auth", "controlplane", "audit"],
+  "migrationNamespace": "ledger",
+  "whenToEnable": "Give every player a balance. A per-user ledger for whatever your economy runs on — chips, gold, gems, credits, tokens — in your own D1, currency-agnostic. Every movement is atomic (the ledger entry and the balance change commit together), idempotent (a replayed operation applies once, so a payout delivered twice pays once), and overdraft-safe (a database CHECK constraint makes a balance that can go negative impossible). It has holds — reserve a player's stake the moment a bet is placed, then release it or capture it when the outcome lands — which is what makes wagering safe, so it pairs naturally with @pithy-sh/multiplayer. It takes no position on whether your units map to money; that, and any regulation it implies, is yours. Reads are scoped to the caller; moving another player's balance over HTTP is server-authoritative and needs the admin scope, so add auth too.",
+  "scaffold": [
+    "Add a `ledger({ currencies: [...] })` block to pithy.config.ts and declare at least one currency.",
+    "Give each currency a `code` (a lowercase id like `chips`), a `name`, and optionally `decimals` (display scale — balances are always stored as integers in the minor unit).",
+    "Bind a D1 database named DB in wrangler.jsonc — the same app database your other capabilities use.",
+    "Run `pithy migrate` to create pithy_ledger_accounts, pithy_ledger_transactions, and pithy_ledger_holds.",
+    "Add `@pithy-sh/auth` if it is not already installed. Balance reads scope to the authenticated user; admin credit/debit routes need the `ledger:admin` scope, minted for your trusted server.",
+    "Move balances in-process from your own code with `openLedger(env.DB)` — credit, debit, transfer, hold, release, capture — passing a unique `ref` for each operation so retries are safe.",
+    "Add `controlplane()` if you want a dashboard to read balances and entry logs. The ledger's management surface is read-only — `ledger:accounts:read` for balances, `ledger:transactions:read` for the history behind them — and grants nothing that can move money."
+  ],
+  "configOptions": [
+    {
+      "key": "currencies",
+      "default": [{ "code": "chips", "name": "Chips" }],
+      "describe": "Every currency this app's ledger holds. Replace this example — one currency is the smallest ledger that does anything, and `chips` is the schema's own first example of a unit that is plainly not money. `code` is a lowercase id, used as a URL path segment and an account key; `name` is what a player sees; optional `decimals` is display scale only, because a balance is always stored as an integer in the minor unit (`decimals: 2` shows a stored 150 as 1.50). At least one currency is required."
+    },
+    {
+      "key": "adminScope",
+      "default": "ledger:admin",
+      "describe": "The scope a session must carry to credit or debit another player's balance over HTTP. Balance-moving writes are server-authoritative — mint it for your trusted server's token, never a player's."
+    }
+  ]
+}

package/src/admin/read.ts

@@ -0,0 +1,150 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { D1Database } from "@cloudflare/workers-types";
+import { decodeCursor, type PageCursor, pageLimit, toPage } from "@pithy-sh/core/src/data/cursor";
+import { LedgerAccount } from "../data/account";
+import { LEDGER_ACCOUNTS_TABLE, LEDGER_TRANSACTIONS_TABLE, ledgerDatabase } from "../data/tables";
+import { LedgerTransaction } from "../data/transaction";
+
+/**
+ * The management read model — the queries behind the control-plane routes, and nothing else.
+ *
+ * **It lives beside `ledger.ts` rather than inside it.** The `Ledger` interface is the
+ * server-authoritative movement primitive: everything on it changes a balance or reads the caller's
+ * own. These read across *every* player, which is a different operation with a different blast radius,
+ * and keeping it out of the primitive means an in-process caller cannot reach it by accident.
+ *
+ * ## Keyset, never offset
+ *
+ * Both listings paginate on `id`, descending, through the shared cursor helper in
+ * `@pithy-sh/core/src/data/cursor`. `id` is an autoincrement primary key on both tables, so it is
+ * monotonic and unique — which makes it a sufficient keyset position on its own, with the cursor's
+ * `sort` and `id` carrying the same value. `OFFSET` would shift under a reader the moment any balance
+ * moves, and on a ledger something is always moving: a page 2 fetched a second later would repeat rows
+ * it already showed and skip rows it never did.
+ *
+ * ## The indexes these were written for
+ *
+ * `pithyLedgerTransactionsOwnerIdx` is `(userId, currency, id)`, which is exactly the shape
+ * {@link listTransactions} needs — both filters are equalities and the ordering column is the index's
+ * tail, so the page is a range scan and the `LIMIT` genuinely stops it. That is why the route requires
+ * a currency rather than offering "everything this player did": without it the index gives no ordering
+ * and the database sorts the player's whole history to return twenty-five rows.
+ *
+ * {@link listAccounts} orders by the accounts table's primary key for the same reason — it is the only
+ * indexed monotonic column on that table. `updatedAt` would be the more useful sort for an operator
+ * ("who moved most recently"), and it has no index; adding one is a migration a read-only pane does not
+ * justify, so the order is account-opened order and this says so rather than pretending otherwise.
+ */
+
+/** One page of a keyset listing, and where the next one resumes. */
+export interface LedgerPage<T> {
+  /** The rows, newest first. */
+  items: T[];
+  /** The cursor for the next page, or null at the end of the list. Opaque; hand it back verbatim. */
+  nextCursor: string | null;
+}
+
+/** What {@link listAccounts} accepts. */
+export interface AccountsQuery {
+  /** Restrict to one currency code. Already resolved against config by the handler. */
+  currency?: string;
+  /** Where to resume, from a previous page's `nextCursor`. A malformed one is a first page. */
+  cursor?: string;
+  /** How many rows to return, clamped by `pageLimit`. */
+  limit?: number;
+}
+
+/** What {@link listTransactions} accepts, beyond the account it is for. */
+export interface TransactionsQuery {
+  /** Where to resume, from a previous page's `nextCursor`. A malformed one is a first page. */
+  cursor?: string;
+  /** How many rows to return, clamped by `pageLimit`. */
+  limit?: number;
+}
+
+/** A row's keyset position. `id` is monotonic on both tables, so it is both the sort and the tiebreak. */
+function position(row: { id: number }): PageCursor {
+  return { sort: row.id, id: row.id };
+}
+
+/**
+ * The `id` a page resumes before, or undefined for the first page.
+ *
+ * A cursor whose `id` is not a number was not one of ours — a truncated value, a cursor from another
+ * listing, a hand-built guess. It resolves to the first page rather than to an error, which is what
+ * core's `decodeCursor` promises and what stops a bad cursor from being a probe.
+ */
+function resumeBefore(cursor: string | undefined): number | undefined {
+  const decoded = decodeCursor(cursor);
+  return typeof decoded?.id === "number" ? decoded.id : undefined;
+}
+
+/**
+ * Every account holding a balance, newest first, optionally in one currency.
+ *
+ * The rows are parsed through {@link LedgerAccount}, so dates decode and the shape is validated on the
+ * way out of D1 exactly as it is on the way in.
+ */
+export async function listAccounts(d1: D1Database, query: AccountsQuery = {}): Promise<LedgerPage<LedgerAccount>> {
+  const limit = pageLimit(query.limit);
+  const before = resumeBefore(query.cursor);
+  let selection = ledgerDatabase(d1)
+    .selectFrom(LEDGER_ACCOUNTS_TABLE)
+    .selectAll()
+    .orderBy("id", "desc")
+    // One more than asked for: the extra row is how "is there another page" is answered without a
+    // COUNT, which on this table would be a full scan on every page load.
+    .limit(limit + 1);
+  if (query.currency !== undefined) selection = selection.where("currency", "=", query.currency);
+  if (before !== undefined) selection = selection.where("id", "<", before);
+  const rows = await selection.execute();
+  return toPage(
+    rows.map((row) => LedgerAccount.parse(row)),
+    limit,
+    position,
+  );
+}
+
+/**
+ * Every account one player holds, ordered by currency code.
+ *
+ * Unpaginated on purpose: an account is keyed `(userId, currency)` and currencies are config rather
+ * than rows, so this returns at most one row per configured currency. A cursor over a list bounded by
+ * the adopter's own config would be ceremony.
+ */
+export async function readAccounts(d1: D1Database, userId: string): Promise<LedgerAccount[]> {
+  const rows = await ledgerDatabase(d1)
+    .selectFrom(LEDGER_ACCOUNTS_TABLE)
+    .selectAll()
+    .where("userId", "=", userId)
+    .orderBy("currency", "asc")
+    .execute();
+  return rows.map((row) => LedgerAccount.parse(row));
+}
+
+/** One account's entry log, newest first — the history that explains its balance. */
+export async function listTransactions(
+  d1: D1Database,
+  userId: string,
+  currency: string,
+  query: TransactionsQuery = {},
+): Promise<LedgerPage<LedgerTransaction>> {
+  const limit = pageLimit(query.limit);
+  const before = resumeBefore(query.cursor);
+  let selection = ledgerDatabase(d1)
+    .selectFrom(LEDGER_TRANSACTIONS_TABLE)
+    .selectAll()
+    .where("userId", "=", userId)
+    .where("currency", "=", currency)
+    .orderBy("id", "desc")
+    .limit(limit + 1);
+  if (before !== undefined) selection = selection.where("id", "<", before);
+  const rows = await selection.execute();
+  return toPage(
+    rows.map((row) => LedgerTransaction.parse(row)),
+    limit,
+    position,
+  );
+}

package/src/audit/actions.ts

@@ -0,0 +1,30 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+/**
+ * The audit actions this capability emits, through the core `emit()` seam.
+ *
+ * **Every one of these is a read, and every one is audited anyway.** A ledger is a record of what
+ * people own and what they did to earn or spend it; a management credential that can page through it
+ * can reconstruct a player's whole economic history. "Who pulled the balances for every account on the
+ * ninth, and whose transaction log did they open afterwards" is a question with an answer, and these
+ * are what make it one. An unaudited read surface over other people's money is how a leaked dashboard
+ * credential stays invisible — nothing changes, so nothing shows up.
+ *
+ * Emitted with `c.var.emit`, never by importing `@pithy-sh/audit` — the seam is always present
+ * (`noopEmit` when no audit capability is composed), so there is no null check and no hard dependency.
+ * Identifiers and counts only in metadata: never a balance, never a memo, never a `ref`. The trail is
+ * queryable and long-lived, and copying the ledger into it would just make a second ledger with weaker
+ * access rules than the first.
+ */
+export const LedgerAuditActions = {
+  /** A management client paged the account list — every holder of a balance, or of one currency's. */
+  accountsListed: "ledger/accounts_listed",
+  /** A management client read one player's balances. */
+  accountRead: "ledger/account_read",
+  /** A management client paged one account's entry log — the history behind the number. */
+  transactionsRead: "ledger/transactions_read",
+} as const;
+
+/** One of the ledger capability's audit actions. */
+export type LedgerAuditAction = (typeof LedgerAuditActions)[keyof typeof LedgerAuditActions];

package/src/capability.ts

@@ -0,0 +1,97 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { BindingSpecInput } from "@pithy-sh/core/src/capability/bindings";
+import { type Capability, defineCapability } from "@pithy-sh/core/src/capability/capability";
+import type { Migration } from "kysely/migration";
+import { LedgerConfig, type LedgerConfigInput } from "./config/config";
+import { ledgerTables } from "./data/tables";
+import { LEDGER_DEFAULT_BASE_PATH, registerLedgerRoutes } from "./http/routes";
+import { ledgerAdminRoutes } from "./http/scopes";
+import { ledger_0001_accounts } from "./migrations/0001_accounts";
+import { ledgerExampleSeed } from "./seeds/example";
+import { PACKAGE_VERSION } from "./version.generated";
+
+/**
+ * Where ledger's migrations sort in the app database. Unique per database; the registry composes keys like
+ * `0650_ledger_0001_accounts`. Sits after rating (600).
+ *
+ * Ledger was also at 600 until this was corrected — `pithy migrate` threw `duplicate migration order 600
+ * in database "app"` for any project composing both. Nothing orders ledger against rating in particular;
+ * rating simply kept the slot, and the two tables do not reference each other.
+ */
+export const LEDGER_MIGRATION_ORDER = 650;
+
+export type LedgerOptions = LedgerConfigInput & {
+  /** Mount the routes somewhere other than `/ledger`. Moves the management surface with them. */
+  basePath?: string;
+};
+
+export interface LedgerCapability extends Capability {
+  ledgerConfig: LedgerConfig;
+}
+
+/**
+ * The ledger capability: a per-user balance ledger for an app's economy — chips, gold, credits, tokens.
+ *
+ * Fully optional. Config, migrations, routes, and bindings arrive only on `pithy add ledger`, and
+ * `pithy remove ledger` is the clean inverse. The store is D1, always: the ledger's correctness — atomic
+ * movements, idempotent operations, overdraft protection — is enforced by D1's own transactions and `CHECK`
+ * constraints (see `ledger.ts`), which is exactly what a balance store must guarantee.
+ *
+ * It is currency-agnostic and takes no position on whether an app's units map to money — that, and any
+ * regulation it implies, is the adopter's concern. Pithy provides the ledger; the adopter provides the
+ * compliance.
+ *
+ * `dependsOn` is deliberately empty. Auth is a seam, not a peer: reads scope to `c.var.auth.userId` and
+ * admin writes require a scope, so without `@pithy-sh/auth` every player route is denied. The ledger
+ * itself is a server-authoritative primitive other capabilities call in-process —
+ * `@pithy-sh/multiplayer` uses it to escrow wagers and settle payouts.
+ *
+ * The control-plane seam is the same kind of optional: `adminRoutes` are always declared and always
+ * mounted, and with `controlplane()` uncomposed each one denies with `controlplane/not_connected`
+ * rather than being absent. A management surface that appears only when something else is installed is
+ * a surface nobody can discover; one that is always there and always default-denied is.
+ */
+export function ledger(options: LedgerOptions = { currencies: [] }): LedgerCapability {
+  const { basePath, ...configInput } = options;
+  // Parse the currency set at assembly — a duplicate code or a bad currency fails on deploy, not on the
+  // first transaction.
+  const resolved = LedgerConfig.parse(configInput);
+  // Resolved once, here, and handed to both the router and the manifest. The fallback used to live only
+  // inside `registerLedgerRoutes`, which would have let the advertised admin paths and the mounted ones
+  // disagree the moment either side changed its mind about the default.
+  const mountPath = basePath ?? LEDGER_DEFAULT_BASE_PATH;
+
+  const migrations: Record<string, Migration> = { "0001_accounts": ledger_0001_accounts };
+  const requiredBindings: BindingSpecInput[] = [{ type: "d1", name: "DB" }];
+
+  const capability = defineCapability({
+    name: "ledger",
+    // The package version this capability ships at, stamped by `scripts/stampVersions.ts` — a Worker
+    // cannot read its own package.json. Reported per capability by the control-plane manifest.
+    version: PACKAGE_VERSION,
+    requiredBindings,
+    config: LedgerConfig,
+    databases: {
+      app: {
+        binding: "DB",
+        tables: ledgerTables(),
+        migrationOrder: LEDGER_MIGRATION_ORDER,
+        migrations,
+      },
+    },
+    routes: registerLedgerRoutes({ config: resolved, basePath: mountPath }),
+    // Built from the resolved mount path, never the default: an adopter who mounts the ledger at
+    // `/wallet` gets a manifest naming `/wallet/admin/accounts`, which is what a management client
+    // composes its calls from.
+    adminRoutes: ledgerAdminRoutes(mountPath),
+    seeds: [ledgerExampleSeed],
+  });
+
+  return Object.assign(capability, { ledgerConfig: resolved });
+}
+
+export function isLedgerCapability(capability: Capability): capability is LedgerCapability {
+  return capability.name === "ledger" && "ledgerConfig" in capability;
+}

package/src/cloudflare-test.d.ts

@@ -0,0 +1,12 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+/// <reference types="@cloudflare/vitest-plugin/types" />
+
+// Bindings the Workers-runtime test project provides to `*.workers.test.ts`, matching the Miniflare config
+// in `vitest.workers.config.ts`: the app `DB` database the `pithy_ledger_*` tables live in.
+declare namespace Cloudflare {
+  interface Env {
+    DB: D1Database;
+  }
+}

package/src/config/config.ts

@@ -0,0 +1,73 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+
+/**
+ * The ledger capability's config — the thin, user-owned surface in `pithy.config.ts`. Every field is
+ * `.describe()`d: the descriptions feed the self-documenting CLI (CLAUDE.md §Config).
+ *
+ * The ledger keeps a per-user balance for whatever an app's economy runs on — chips, gold, gems,
+ * credits, tokens. It is currency-agnostic and holds no opinion about whether those units map to money;
+ * that (and any regulation around it) is the adopter's concern. **Amounts are integers in a currency's
+ * minor unit** — never floats — so arithmetic is exact; a currency's `decimals` only says how to *display*
+ * them. Every mutation is atomic, idempotent on a caller-supplied `ref`, and overdraft-protected by a
+ * database `CHECK` constraint, because a ledger that can double-spend or go negative is not a ledger.
+ */
+
+/** A currency code is a short identifier used in URLs and keys, so it is lowercase, digits, and dashes. */
+const CURRENCY_CODE_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
+
+export const LedgerCurrency = z
+  .object({
+    code: z
+      .string()
+      .regex(CURRENCY_CODE_PATTERN, "A currency code is lowercase, digits, and dashes.")
+      .describe("The currency's stable id — `chips`, `gold`, `credits`. A path segment and an account key."),
+    name: z.string().min(1).describe("The human-readable name shown to players — `Casino Chips`, `Gold`."),
+    decimals: z
+      .number()
+      .int()
+      .min(0)
+      .default(0)
+      .describe(
+        "How many decimal places this currency displays. Balances are always stored as integers in the minor unit; `decimals: 2` means a stored `150` displays as `1.50`. Whole chips are `0`.",
+      ),
+  })
+  .describe("One currency an app's economy runs on — a code, a display name, and a display scale.");
+export type LedgerCurrency = z.output<typeof LedgerCurrency>;
+
+export const LedgerConfig = z
+  .object({
+    currencies: z
+      .array(LedgerCurrency)
+      .min(1, "A ledger with no currencies does nothing — configure at least one.")
+      .describe("Every currency this app's ledger holds. Currencies are config, not database rows."),
+    adminScope: z
+      .string()
+      .min(1)
+      .default("ledger:admin")
+      .describe(
+        "The AuthContext scope a session must carry to credit or debit another player's balance over HTTP. Balance-moving writes are server-authoritative — mint this scope for your trusted server's token, never a player's. Players can always read their own balance without it.",
+      ),
+  })
+  .describe("Configuration for the ledger capability — the set of currencies an app's economy runs on.")
+  .check((ctx) => {
+    const codes = ctx.value.currencies.map((currency) => currency.code);
+    const duplicates = [...new Set(codes.filter((code, i) => codes.indexOf(code) !== i))];
+    if (duplicates.length > 0) {
+      ctx.issues.push({
+        code: "custom",
+        input: ctx.value,
+        path: ["currencies"],
+        message: `Duplicate currency codes: ${duplicates.join(", ")}. Two currencies sharing a code would merge their balances.`,
+      });
+    }
+  });
+export type LedgerConfig = z.output<typeof LedgerConfig>;
+export type LedgerConfigInput = z.input<typeof LedgerConfig>;
+
+/** The currency with this code, or undefined. Codes come from config, so an unknown code is a 404. */
+export function resolveCurrency(config: LedgerConfig, code: string): LedgerCurrency | undefined {
+  return config.currencies.find((currency) => currency.code === code);
+}

package/src/data/account.ts

@@ -0,0 +1,43 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { SQLiteDate } from "@pithy-sh/core/src/data/codecs";
+import { z } from "zod";
+
+/**
+ * One player's balance in one currency — the row in `pithy_ledger_accounts`, keyed `(userId, currency)`.
+ *
+ * `balance` is everything the player owns; `held` is the portion reserved by open holds (escrowed wagers).
+ * `available = balance - held` is what they can spend. All three are integers in the currency's minor unit.
+ * A database `CHECK (balance >= 0 AND held >= 0 AND held <= balance)` is the overdraft guard — a debit or
+ * hold that would break it aborts its transaction, so an account can never go negative or over-reserve.
+ */
+export const LedgerAccount = z
+  .object({
+    id: z
+      .number()
+      .int()
+      .describe("Autoincrement primary key. Internal only; accounts are addressed by (userId, currency)."),
+    userId: z.string().describe("The account owner — an authenticated user id."),
+    currency: z.string().describe("The currency code this balance is in, from `currencies` in pithy.config.ts."),
+    balance: z.number().int().describe("Total owned, in the currency's minor unit. Never negative."),
+    held: z
+      .number()
+      .int()
+      .describe("The portion reserved by open holds. `available = balance - held`. Never exceeds balance."),
+    createdAt: SQLiteDate.describe("When the account was first opened."),
+    updatedAt: SQLiteDate.describe("When the balance last changed."),
+  })
+  .describe("One player's balance in one currency — the row in `pithy_ledger_accounts`.");
+export type LedgerAccount = z.output<typeof LedgerAccount>;
+export type LedgerAccountRow = z.input<typeof LedgerAccount>;
+
+/** A player's spendable position in a currency — the shape a balance read returns. */
+export interface Balance {
+  /** Total owned. */
+  balance: number;
+  /** Reserved by open holds. */
+  held: number;
+  /** Spendable now (`balance - held`). */
+  available: number;
+}

package/src/data/hold.ts

@@ -0,0 +1,39 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { SQLiteDate } from "@pithy-sh/core/src/data/codecs";
+import { z } from "zod";
+
+/** The lifecycle of a hold. Terminal states (`released`, `captured`) never change again. */
+export const HoldStatus = z
+  .enum(["open", "released", "captured"])
+  .describe(
+    "A hold's state: `open` (funds reserved), `released` (canceled, funds returned), `captured` (finalized, funds taken).",
+  );
+export type HoldStatus = z.infer<typeof HoldStatus>;
+
+/**
+ * An escrow on a player's funds — the row in `pithy_ledger_holds`. A hold reserves part of a balance (a
+ * placed wager) without spending it: the amount moves from `available` to `held` on the account. It later
+ * resolves — `release`d back to the player, or `capture`d (spent, e.g. a lost bet). Holds are what make
+ * wagering safe: the stake is locked the moment a bet is placed, so it cannot be spent twice while the
+ * outcome is pending.
+ *
+ * `ref` is the hold's stable id and idempotency key; `release`/`capture` reference it.
+ */
+export const LedgerHold = z
+  .object({
+    id: z.number().int().describe("Autoincrement primary key. Internal only; holds are addressed by ref."),
+    ref: z
+      .string()
+      .describe("The caller-supplied idempotency key, unique across holds. Used to release or capture this hold."),
+    userId: z.string().describe("The account owner whose funds are held."),
+    currency: z.string().describe("The currency code this hold is in."),
+    amount: z.number().int().describe("The reserved amount in the currency's minor unit."),
+    status: HoldStatus.describe("The hold's current state."),
+    createdAt: SQLiteDate.describe("When the hold was placed."),
+    resolvedAt: SQLiteDate.nullable().describe("When the hold was released or captured, or null while open."),
+  })
+  .describe("An escrow on a player's funds — the row in `pithy_ledger_holds`.");
+export type LedgerHold = z.output<typeof LedgerHold>;
+export type LedgerHoldRow = z.input<typeof LedgerHold>;

package/src/data/tables.ts

@@ -0,0 +1,43 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { D1Database } from "@cloudflare/workers-types";
+import { createDatabase, type DatabaseSchema } from "@pithy-sh/core/src/data/db";
+import type { Kysely } from "kysely";
+import type { z } from "zod";
+import { LedgerAccount } from "./account";
+import { LedgerHold } from "./hold";
+import { LedgerTransaction } from "./transaction";
+
+/** The accounts table. `CamelCasePlugin` snake-cases it to `pithy_ledger_accounts`. */
+export const LEDGER_ACCOUNTS_TABLE = "pithyLedgerAccounts";
+/** The append-only entry log. `CamelCasePlugin` snake-cases it to `pithy_ledger_transactions`. */
+export const LEDGER_TRANSACTIONS_TABLE = "pithyLedgerTransactions";
+/** The holds table. `CamelCasePlugin` snake-cases it to `pithy_ledger_holds`. */
+export const LEDGER_HOLDS_TABLE = "pithyLedgerHolds";
+
+/** The ledger tables map. All are always present — none is behind a config flag. */
+export function ledgerTables(): Record<string, z.ZodObject> {
+  return {
+    [LEDGER_ACCOUNTS_TABLE]: LedgerAccount,
+    [LEDGER_TRANSACTIONS_TABLE]: LedgerTransaction,
+    [LEDGER_HOLDS_TABLE]: LedgerHold,
+  };
+}
+
+/** The typed Kysely database over the ledger tables. */
+export type LedgerTables = {
+  [LEDGER_ACCOUNTS_TABLE]: typeof LedgerAccount;
+  [LEDGER_TRANSACTIONS_TABLE]: typeof LedgerTransaction;
+  [LEDGER_HOLDS_TABLE]: typeof LedgerHold;
+};
+export type LedgerDatabase = Kysely<DatabaseSchema<LedgerTables>>;
+
+/** Build the ledger database from the `DB` binding (CamelCasePlugin installed). */
+export function ledgerDatabase(d1: D1Database): LedgerDatabase {
+  return createDatabase(d1, {
+    [LEDGER_ACCOUNTS_TABLE]: LedgerAccount,
+    [LEDGER_TRANSACTIONS_TABLE]: LedgerTransaction,
+    [LEDGER_HOLDS_TABLE]: LedgerHold,
+  }) as unknown as LedgerDatabase;
+}