@pithy-sh/ledger 0.1.0

package/src/http/routes.ts

@@ -0,0 +1,336 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { D1Database } from "@cloudflare/workers-types";
+import { zValidator } from "@hono/zod-validator";
+import type { PithyHonoEnv } from "@pithy-sh/core/src/capability/capability";
+import type { ControlPlaneContext } from "@pithy-sh/core/src/controlPlane/context";
+import { requireControlPlane } from "@pithy-sh/core/src/controlPlane/http/guard";
+import type { ControlPlaneScope } from "@pithy-sh/core/src/controlPlane/scope/scope";
+import { InternalError } from "@pithy-sh/core/src/error/pithyError";
+import { validationHook } from "@pithy-sh/core/src/http/validation";
+import type { VerificationStrategy } from "@pithy-sh/core/src/http/verification";
+import type { Context, Hono } from "hono";
+import { listAccounts, listTransactions, readAccounts } from "../admin/read";
+import { type LedgerAuditAction, LedgerAuditActions } from "../audit/actions";
+import { type LedgerConfig, resolveCurrency } from "../config/config";
+import { LedgerCurrencyNotFoundError } from "../error/errors";
+import { openLedger } from "../ledger";
+import { requireAdmin, requireAuth } from "./guards";
+import type { LedgerAccountsResponse, LedgerTransactionsResponse, LedgerUserAccountsResponse } from "./responses";
+import {
+  AdminAccountParam,
+  AdminAccountsQuery,
+  AdminTransactionsQuery,
+  AdminUserParam,
+  AdminWrite,
+  CurrencyParam,
+} from "./schemas";
+import { LEDGER_ACCOUNTS_READ_SCOPE, LEDGER_TRANSACTIONS_READ_SCOPE } from "./scopes";
+import { accountView, transactionView } from "./view";
+
+/**
+ * The ledger routes, their declared verification strategies, and what each accepts. A player can always
+ * read their *own* balance and history; **moving funds over HTTP is server-authoritative** and requires
+ * the admin scope, because a ledger a client could credit itself is not a ledger; and a management
+ * client reads across every player through the control-plane seam:
+ *
+ *   GET  /ledger/:currency                                     → your balance                (bearer | session)                param: CurrencyParam
+ *   GET  /ledger/:currency/transactions                        → your recent ledger entries  (bearer | session)                param: CurrencyParam
+ *   POST /ledger/:currency/credit                              → add funds to a player       (bearer | session + admin scope)  param: CurrencyParam, json: AdminWrite
+ *   POST /ledger/:currency/debit                               → remove funds from a player  (bearer | session + admin scope)  param: CurrencyParam, json: AdminWrite
+ *   GET  /ledger/admin/accounts                                → every account, paged        (control-plane: ledger:accounts:read)      query: AdminAccountsQuery
+ *   GET  /ledger/admin/accounts/:userId                        → one player's balances       (control-plane: ledger:accounts:read)      param: AdminUserParam
+ *   GET  /ledger/admin/accounts/:userId/:currency/transactions → one account's entry log     (control-plane: ledger:transactions:read)  param: AdminAccountParam, query: AdminTransactionsQuery
+ *
+ * Most balance movement happens in-process (a game model calling {@link openLedger} directly), not over
+ * HTTP; these routes are the read surface players need, a trusted-server admin surface, and a read-only
+ * management surface. The user id on a player route comes from the core `AuthContext` seam, never a
+ * request body — a player's read is always scoped to the caller.
+ *
+ * ## The management surface is read-only, deliberately
+ *
+ * There is no `POST /admin/adjust`. Writing to a balance ledger from an admin console needs everything
+ * every other movement gets — an idempotency key so a double-click does not pay twice, a recorded
+ * reason, a reversal path — and a console route with none of those would be the one place the ledger's
+ * guarantees do not hold. So the seam reads and nothing else: balances, and the entries that explain
+ * them.
+ *
+ * ## Why the management routes sit under `admin/`
+ *
+ * `${base}/:currency` claims the entire one-segment space beneath the mount point, so a management route
+ * at `${base}/accounts` would be ambiguous with a currency called `accounts` and would sit behind
+ * whichever of the two Hono matched first — a route's gate decided by registration order. The extra
+ * static segment makes the two sets disjoint by construction: `${base}/admin/accounts` cannot collide
+ * with `${base}/:currency` (two segments against three) nor with `${base}/:currency/transactions` (the
+ * last segment differs), and the deeper ones are longer than anything the player surface mounts.
+ *
+ * ## `requireAuth()` is never on a management route
+ *
+ * The seam deliberately leaves `c.var.auth` null, so an auth gate on a control-plane route would deny
+ * every legitimate management call permanently and no credential could fix it. `requireControlPlane`
+ * **replaces** `requireAuth()` and `requireAdmin()` on those lines; it does not stack with them. See
+ * `guards.ts` for the whole argument.
+ *
+ * Validators sit **after** the guards on every route line: an unauthenticated, unscoped, or unverified
+ * caller is turned away before its payload is read, so a bad request can never downgrade a 401/403 to a
+ * 400 and tell a caller with no credential which requests were well-formed. They sit **before** the
+ * handler, which is why a malformed request on an *unconfigured* currency answers 400 rather than 404 —
+ * the request is rejected as unparseable before the currency is ever resolved.
+ */
+
+/**
+ * Where the ledger mounts when an adopter names nothing.
+ *
+ * Exported because two places must agree on it: the router below, and `ledgerAdminRoutes` in
+ * `capability.ts`. A default living only in the registrar would let the manifest advertise `/ledger/...`
+ * while the routes mounted somewhere else, and a management client composing its calls from the
+ * manifest would 404 with nothing to diagnose.
+ */
+export const LEDGER_DEFAULT_BASE_PATH = "/ledger";
+
+/**
+ * What every route this capability mounts declares: its path, its verification strategy, and the
+ * control-plane scope it checks when it has one.
+ *
+ * **Exported so a test can assert against the declaration rather than against a middleware count.**
+ * Counting middleware proves that *something* runs before the handler; it cannot prove *what*, and a
+ * bare `zValidator` satisfies a count. `routeContract.test.ts` checks this list against the routes Hono
+ * actually registered in both directions, so a route added without an entry and an entry naming a route
+ * nobody mounts both fail.
+ */
+export interface LedgerRouteDeclaration {
+  readonly method: "GET" | "POST";
+  /** The path relative to the configured `basePath`, e.g. `/admin/accounts`. */
+  readonly path: string;
+  readonly strategy: VerificationStrategy;
+  /** The control-plane scope this route checks, for a `control-plane` route. */
+  readonly scope?: ControlPlaneScope;
+}
+
+/** Every route, and how it is gated. */
+export const LEDGER_ROUTES: readonly LedgerRouteDeclaration[] = [
+  { method: "GET", path: "/:currency", strategy: "bearer" },
+  { method: "GET", path: "/:currency/transactions", strategy: "bearer" },
+  { method: "POST", path: "/:currency/credit", strategy: "bearer" },
+  { method: "POST", path: "/:currency/debit", strategy: "bearer" },
+  { method: "GET", path: "/admin/accounts", strategy: "control-plane", scope: LEDGER_ACCOUNTS_READ_SCOPE },
+  { method: "GET", path: "/admin/accounts/:userId", strategy: "control-plane", scope: LEDGER_ACCOUNTS_READ_SCOPE },
+  {
+    method: "GET",
+    path: "/admin/accounts/:userId/:currency/transactions",
+    strategy: "control-plane",
+    scope: LEDGER_TRANSACTIONS_READ_SCOPE,
+  },
+];
+
+export interface LedgerRoutesOptions {
+  config: LedgerConfig;
+  basePath?: string;
+}
+
+function db(c: Context<PithyHonoEnv>): D1Database {
+  const binding = (c.env as Record<string, unknown>).DB as D1Database | undefined;
+  if (!binding) {
+    throw new InternalError({
+      message: "The ledger is not configured.",
+      action: "Bind a D1 database named DB in wrangler.jsonc.",
+      detail: "Ledger requires a `DB` D1 binding; none was present on env.",
+    });
+  }
+  return binding;
+}
+
+/** Reject a request whose currency is not configured. */
+function currency(config: LedgerConfig, code: string): string {
+  if (!resolveCurrency(config, code))
+    throw new LedgerCurrencyNotFoundError({ detail: `No currency "${code}" is configured.` });
+  return code;
+}
+
+/**
+ * The verified management client behind a control-plane call.
+ *
+ * `requireControlPlane()` has run on every route that calls this, so `c.var.controlPlane` is populated
+ * by the time a handler reads it. The throw is a programming-error guard rather than a runtime path:
+ * reaching it would mean a management route was mounted without its gate, which is the one mistake this
+ * file is arranged to make impossible.
+ */
+function caller(c: Context<PithyHonoEnv>): ControlPlaneContext {
+  const context = c.var.controlPlane;
+  if (!context) {
+    throw new InternalError({
+      message: "The ledger could not identify the management caller.",
+      detail: "requireControlPlane() must run before a ledger management handler reads the caller.",
+    });
+  }
+  return context;
+}
+
+/**
+ * Record a management read.
+ *
+ * **Every read, not only writes.** There are no writes on this surface, so an unaudited one would leave
+ * the capability's whole management history blank — and a credential quietly paging every player's
+ * balance history is exactly the thing that leaves no other trace. Counts and identifiers only: no
+ * balance, no `ref`, no memo. Copying the ledger into the audit trail would make a second ledger with
+ * weaker access rules than the first.
+ */
+async function record(
+  c: Context<PithyHonoEnv>,
+  action: LedgerAuditAction,
+  resourceId: string | null,
+  metadata: Record<string, unknown>,
+): Promise<void> {
+  const who = caller(c);
+  await c.var.emit({
+    action,
+    outcome: "success",
+    actorType: "control-plane",
+    actorId: who.subject,
+    resourceType: "ledger_account",
+    resourceId,
+    requestId: c.req.header("cf-ray"),
+    ip: c.req.header("cf-connecting-ip"),
+    userAgent: c.req.header("user-agent"),
+    metadata: { connectionId: who.connectionId, ...metadata },
+  });
+}
+
+export function registerLedgerRoutes(options: LedgerRoutesOptions): (app: Hono<PithyHonoEnv>) => void {
+  const base = options.basePath ?? LEDGER_DEFAULT_BASE_PATH;
+  const { config } = options;
+
+  /**
+   * The caller's own id. `requireAuth()` has already run on every route that calls this, so a null
+   * `auth` is a wiring mistake rather than an unauthenticated request — hence `InternalError`, not a
+   * 401. Narrowing here rather than asserting non-null keeps the impossible case impossible to ignore.
+   */
+  const callerId = (c: Context<PithyHonoEnv>): string => {
+    const auth = c.var.auth;
+    if (!auth) {
+      throw new InternalError({ detail: "requireAuth() must run before a ledger handler reads the caller." });
+    }
+    return auth.userId;
+  };
+
+  return (app) => {
+    // The management surface: control-plane, read-only. Its paths are disjoint from the player routes
+    // by construction, so registering it first is presentation rather than semantics.
+
+    app.get(
+      `${base}/admin/accounts`,
+      requireControlPlane(LEDGER_ACCOUNTS_READ_SCOPE),
+      zValidator("query", AdminAccountsQuery, validationHook),
+      async (c) => {
+        const query = c.req.valid("query");
+        // A currency filter is still config-backed resolution: an operator who mistypes one gets the
+        // capability's own 404 rather than an empty pane they would read as "nobody holds any".
+        const code = query.currency === undefined ? undefined : currency(config, query.currency);
+        const page = await listAccounts(db(c), { ...query, currency: code });
+        await record(c, LedgerAuditActions.accountsListed, null, {
+          currency: code ?? null,
+          returned: page.items.length,
+          resumed: query.cursor !== undefined,
+        });
+        return c.json(
+          { accounts: page.items.map(accountView), nextCursor: page.nextCursor } satisfies LedgerAccountsResponse,
+          200,
+        );
+      },
+    );
+
+    app.get(
+      `${base}/admin/accounts/:userId`,
+      requireControlPlane(LEDGER_ACCOUNTS_READ_SCOPE),
+      zValidator("param", AdminUserParam, validationHook),
+      async (c) => {
+        const { userId } = c.req.valid("param");
+        const accounts = await readAccounts(db(c), userId);
+        await record(c, LedgerAuditActions.accountRead, userId, { userId, returned: accounts.length });
+        // A player with no account is an empty list, not a 404 — the honest answer, since an account is
+        // opened by its first credit and its absence is not a missing player. It also keeps this surface
+        // from being an existence oracle for user ids.
+        return c.json({ userId, accounts: accounts.map(accountView) } satisfies LedgerUserAccountsResponse, 200);
+      },
+    );
+
+    app.get(
+      `${base}/admin/accounts/:userId/:currency/transactions`,
+      requireControlPlane(LEDGER_TRANSACTIONS_READ_SCOPE),
+      zValidator("param", AdminAccountParam, validationHook),
+      zValidator("query", AdminTransactionsQuery, validationHook),
+      async (c) => {
+        const { userId, currency: requested } = c.req.valid("param");
+        const code = currency(config, requested);
+        const query = c.req.valid("query");
+        const page = await listTransactions(db(c), userId, code, query);
+        await record(c, LedgerAuditActions.transactionsRead, `${userId}:${code}`, {
+          userId,
+          currency: code,
+          returned: page.items.length,
+          resumed: query.cursor !== undefined,
+        });
+        return c.json(
+          {
+            userId,
+            currency: code,
+            transactions: page.items.map(transactionView),
+            nextCursor: page.nextCursor,
+          } satisfies LedgerTransactionsResponse,
+          200,
+        );
+      },
+    );
+
+    // The player surface: bearer or session, always scoped to the caller.
+
+    app.get(
+      `${base}/:currency/transactions`,
+      requireAuth(),
+      zValidator("param", CurrencyParam, validationHook),
+      async (c) => {
+        const code = currency(config, c.req.valid("param").currency);
+        const rows = await openLedger(db(c)).transactions(callerId(c), code, 50);
+        return c.json({ transactions: rows }, 200);
+      },
+    );
+
+    app.get(`${base}/:currency`, requireAuth(), zValidator("param", CurrencyParam, validationHook), async (c) => {
+      const code = currency(config, c.req.valid("param").currency);
+      return c.json(await openLedger(db(c)).balance(callerId(c), code), 200);
+    });
+
+    app.post(
+      `${base}/:currency/credit`,
+      requireAuth(),
+      requireAdmin(config.adminScope),
+      zValidator("param", CurrencyParam, validationHook),
+      zValidator("json", AdminWrite, validationHook),
+      async (c) => {
+        const code = currency(config, c.req.valid("param").currency);
+        const input = c.req.valid("json");
+        const balance = await openLedger(db(c)).credit(input.userId, code, input.amount, input.ref, {
+          memo: input.memo,
+        });
+        return c.json(balance, 200);
+      },
+    );
+
+    app.post(
+      `${base}/:currency/debit`,
+      requireAuth(),
+      requireAdmin(config.adminScope),
+      zValidator("param", CurrencyParam, validationHook),
+      zValidator("json", AdminWrite, validationHook),
+      async (c) => {
+        const code = currency(config, c.req.valid("param").currency);
+        const input = c.req.valid("json");
+        const balance = await openLedger(db(c)).debit(input.userId, code, input.amount, input.ref, {
+          memo: input.memo,
+        });
+        return c.json(balance, 200);
+      },
+    );
+  };
+}

package/src/http/schemas.ts

@@ -0,0 +1,107 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { MAX_PAGE_SIZE } from "@pithy-sh/core/src/data/cursor";
+import { z } from "zod";
+
+/**
+ * The HTTP boundary shapes for the ledger routes. Everything a client can send is declared here and
+ * parsed on the route line, so reading a route tells you what it accepts without opening the handler.
+ *
+ * {@link CurrencyParam} is deliberately a **shape** check, not an existence check. Whether a currency is
+ * configured is a config-time question the handler still answers through `resolveCurrency`, which raises
+ * `ledger/currency_not_found` — a 404, because an unconfigured `doubloons` is a missing resource, not a
+ * malformed request. Building this schema from the configured codes would collapse that distinction.
+ * Every currency shape below reuses the same field for exactly that reason.
+ *
+ * Note what is absent from {@link AdminWrite}: the currency (it is the path) and the caller (it is the
+ * AuthContext seam). A write names the *player whose balance moves*, which is why the route is gated on
+ * the admin scope — a client that could name any `userId` without it could credit itself.
+ *
+ * The `Admin*` shapes ending in `Query`/`Param` belong to the **control-plane** management routes, which
+ * take no bodies at all: the ledger's management surface is read-only, so there is nothing for a client
+ * to send but filters and a place to resume.
+ */
+
+/** Mirrors the config-time currency-code pattern: lowercase, digits, and dashes. */
+const CURRENCY_CODE_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
+
+/** A currency code, shape-checked. Whether it is configured stays the handler's 404. */
+const CurrencyCode = z
+  .string()
+  .min(1)
+  .max(64)
+  .regex(CURRENCY_CODE_PATTERN, "A currency code is lowercase, digits, and dashes.");
+
+/** A user id as a path segment — opaque to the ledger, which never issues one. */
+const UserId = z.string().min(1).max(255);
+
+/** Where a keyset page resumes. Opaque; a malformed one is a first page rather than an error. */
+const Cursor = z
+  .string()
+  .max(512)
+  .optional()
+  .describe("Where to resume, from the previous page's `nextCursor`. Opaque; a malformed one is a first page.");
+
+/** How many rows one page returns. Bounded, because a verified client can still have a bug. */
+const Limit = z.coerce
+  .number()
+  .int()
+  .min(1)
+  .max(MAX_PAGE_SIZE)
+  .optional()
+  .describe(`How many rows to return, from 1 to ${MAX_PAGE_SIZE}. Defaults to a page a dashboard can render.`);
+
+export const CurrencyParam = z
+  .object({
+    currency: CurrencyCode.describe(
+      "The currency this request applies to — the `:currency` path segment. A shape check only; whether the code is configured is the handler's 404.",
+    ),
+  })
+  .describe("The `:currency` path segment every ledger route carries.");
+export type CurrencyParam = z.infer<typeof CurrencyParam>;
+
+export const AdminAccountsQuery = z
+  .object({
+    currency: CurrencyCode.optional().describe(
+      "Restrict the listing to one currency. A shape check only; an unconfigured code is the handler's 404, so an operator who mistypes is told rather than shown an empty pane.",
+    ),
+    cursor: Cursor,
+    limit: Limit,
+  })
+  .describe("The account-listing query: which currency, and where to resume.");
+export type AdminAccountsQuery = z.infer<typeof AdminAccountsQuery>;
+
+export const AdminUserParam = z
+  .object({
+    userId: UserId.describe(
+      "The player whose balances to read — the `:userId` path segment. Opaque to the ledger: it is whatever id the adopter's auth capability issued.",
+    ),
+  })
+  .describe("The `:userId` path segment on the per-player management routes.");
+export type AdminUserParam = z.infer<typeof AdminUserParam>;
+
+export const AdminAccountParam = z
+  .object({
+    userId: UserId.describe("The player whose account this is — the `:userId` path segment."),
+    currency: CurrencyCode.describe(
+      "The currency the account is in — the `:currency` path segment. A shape check only; an unconfigured code is the handler's 404.",
+    ),
+  })
+  .describe("The `(userId, currency)` pair that addresses one account — the key the accounts table is on.");
+export type AdminAccountParam = z.infer<typeof AdminAccountParam>;
+
+export const AdminTransactionsQuery = z
+  .object({ cursor: Cursor, limit: Limit })
+  .describe("The entry-log query: where to resume, and how much of it to return.");
+export type AdminTransactionsQuery = z.infer<typeof AdminTransactionsQuery>;
+
+export const AdminWrite = z
+  .object({
+    userId: z.string().min(1).max(255).describe("The player whose balance moves."),
+    amount: z.number().int().positive().describe("A positive integer in the currency's minor unit."),
+    ref: z.string().min(1).max(255).describe("A unique idempotency key — a replay with the same ref is a no-op."),
+    memo: z.string().max(1000).optional().describe("An optional human-readable note."),
+  })
+  .describe("An admin credit/debit request.");
+export type AdminWrite = z.infer<typeof AdminWrite>;

package/src/http/scopes.ts

@@ -0,0 +1,95 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { AdminRoute } from "@pithy-sh/core/src/controlPlane/discovery/adminRoute";
+import type { ControlPlaneScope } from "@pithy-sh/core/src/controlPlane/scope/scope";
+
+/**
+ * The ledger's control-plane scopes, and the admin surface a manifest advertises.
+ *
+ * **Separate from `guards.ts` because a scope name is a client's business** (#315). A management
+ * client reads these to render what a connection may do, and `pithy-sh/dashboard`'s scope builder
+ * writes the `pithy dashboard connect --scope …` command from exactly these constants — in a browser
+ * program, with the DOM lib and no Workers types. While they sat beside the Hono middleware, naming
+ * one compiled `PithyHonoEnv`, which reached core's `capability.ts`, which named Worker globals that
+ * program has none of. **This module imports types and nothing else, and a gate holds it there**:
+ * `tooling/browser-scopes` compiles a DOM-only program against every scope the kit declares.
+ *
+ * ## Two scopes, not one admin flag
+ *
+ * `scopeCovers` matches exactly, with no prefix or wildcard rule, so these two confer nothing about
+ * each other — and they should not, because they disclose different things. A **balance** is a number:
+ * what an account holds right now. An **entry log** is a behavioral record: every wager placed, every
+ * payout taken, every purchase, in order, with whatever note the adopter's own code wrote on it. A
+ * balances pane and a support tool answering "why is my chip count wrong" need different halves of
+ * that, and an adopter who wants to hand out only the shallower one must have a way to say so.
+ *
+ * The names are constants rather than config: a configurable scope name is a way to misconfigure a
+ * default-denied gate into a differently-named one, and tooling that read the docs would then hold a
+ * scope nothing checks. They are also the join key with what `pithy dashboard connect` offers an
+ * adopter to grant, so they must be the same strings in both places.
+ *
+ * ## There is no write scope, and that is the whole design
+ *
+ * Nothing here grants a management client the ability to move a balance. Adjusting a ledger from an
+ * admin console needs the same care as any other movement — an idempotency key, an audited reason, a
+ * reversal path — and shipping a `POST /adjust` that has none of them would make the console the one
+ * place the ledger's guarantees do not hold. Balance movement stays server-authoritative: in-process
+ * through `openLedger`, or over the existing player-facing admin routes behind the auth scope.
+ */
+
+/** Read balances: the account list, and one player's position in each currency. A number, not a story. */
+export const LEDGER_ACCOUNTS_READ_SCOPE: ControlPlaneScope = "ledger:accounts:read";
+
+/**
+ * Read the append-only entry log behind a balance — every movement, in order, with its memo. Strictly
+ * more disclosure than the balance itself, which is why it is granted separately.
+ */
+export const LEDGER_TRANSACTIONS_READ_SCOPE: ControlPlaneScope = "ledger:transactions:read";
+
+/**
+ * Every control-plane scope the ledger defines — what `pithy dashboard connect` offers for this
+ * capability, and the list a manifest or a doc quotes rather than re-typing.
+ */
+export const LEDGER_CONTROL_PLANE_SCOPES: readonly ControlPlaneScope[] = [
+  LEDGER_ACCOUNTS_READ_SCOPE,
+  LEDGER_TRANSACTIONS_READ_SCOPE,
+];
+
+/**
+ * The ledger's management surface, as `GET /control-plane/manifest` reports it.
+ *
+ * Declared beside the scopes rather than in `routes.ts` so the scope a route demands and the scope a
+ * manifest advertises are the same constant, read from one place. `basePath` is a parameter and never a
+ * default: an adopter who mounted the ledger at `/wallet` must get a manifest naming
+ * `/wallet/admin/accounts`, or a management client composing its calls from it would 404 against
+ * exactly the adopters who customized anything.
+ *
+ * **Everything sits under an `admin/` segment because the player surface already owns the one-segment
+ * space.** `GET ${basePath}/:currency` matches any single segment, so a management route mounted at
+ * `${basePath}/accounts` would collide with a currency called `accounts` and, worse, would sit behind
+ * whichever of the two Hono matched first. The extra segment removes the ambiguity by construction
+ * rather than by registration order.
+ */
+export function ledgerAdminRoutes(basePath: string): AdminRoute[] {
+  return [
+    {
+      method: "GET",
+      path: `${basePath}/admin/accounts`,
+      scope: LEDGER_ACCOUNTS_READ_SCOPE,
+      summary: "Page every account holding a balance, newest first, optionally in one currency.",
+    },
+    {
+      method: "GET",
+      path: `${basePath}/admin/accounts/:userId`,
+      scope: LEDGER_ACCOUNTS_READ_SCOPE,
+      summary: "What one player holds, in every currency they have an account in.",
+    },
+    {
+      method: "GET",
+      path: `${basePath}/admin/accounts/:userId/:currency/transactions`,
+      scope: LEDGER_TRANSACTIONS_READ_SCOPE,
+      summary: "The entry log behind one balance — every movement, newest first, with its memo.",
+    },
+  ];
+}

package/src/http/view.ts

@@ -0,0 +1,74 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { LedgerAccount } from "../data/account";
+import type { LedgerTransaction } from "../data/transaction";
+import type { LedgerAccountView, LedgerTransactionView } from "./responses";
+
+/**
+ * What a management client is shown. Deliberate projections, never a raw row.
+ *
+ * ## What the ledger holds, and therefore what this can leak
+ *
+ * The ledger stores no names, no email addresses, and no payment instruments — it never has any. The
+ * only identity field on either table is `userId`, the opaque id the adopter's auth capability issued,
+ * and a management client already has to name one to read anything about a person. So the PII question
+ * here is not "which column is sensitive" but **"what does the shape of somebody's balance history say
+ * about them"**, and the answer is: a great deal. That is a scope decision rather than a projection one,
+ * and it is made in `guards.ts`.
+ *
+ * ## What is dropped, and why
+ *
+ * - **`id`, on both rows.** An autoincrement primary key, described in both schemas as internal. A
+ *   management client addresses an account by `(userId, currency)` and an entry by `ref`, both of which
+ *   are stable and meaningful; the surrogate key is neither, and putting it in a response is how a
+ *   client comes to depend on it. Position in the list is the cursor's job.
+ * - **`userId`, on an entry.** Every entry in a page came from one account, and the route named that
+ *   account. Repeating it on each row would be noise a client has to be trusted to ignore.
+ *
+ * ## What is kept, and why
+ *
+ * `ref`, `relatedRef`, and `memo` are adopter-authored strings, and they are the entire reason the
+ * entry log is worth reading: `ref` is what correlates a movement with the purchase or the hand that
+ * caused it, `relatedRef` is what ties a capture back to its hold and one side of a transfer to the
+ * other, and `memo` is the sentence an operator answering "why is my chip count wrong" actually needs.
+ * An adopter who writes something sensitive into a memo has put it in their own ledger; what this
+ * decides is that reading them is its own scope, not that they are unreadable.
+ *
+ * Dates render as ISO-8601 strings. They are ms-epoch integers in SQLite and `Date`s in TypeScript, and
+ * a JSON number would leave every client guessing which unit it was in.
+ */
+
+/**
+ * ## The field lists live in `responses.ts`
+ *
+ * Both view types are `z.output` of the Zod objects there, so there is one declaration of what a
+ * client receives rather than an interface here and a hand-written mirror of it in every management
+ * client. A field added to one and not the other does not compile.
+ */
+
+/** Project one account row for a management client. */
+export function accountView(account: LedgerAccount): LedgerAccountView {
+  return {
+    userId: account.userId,
+    currency: account.currency,
+    balance: account.balance,
+    held: account.held,
+    available: account.balance - account.held,
+    createdAt: account.createdAt.toISOString(),
+    updatedAt: account.updatedAt.toISOString(),
+  };
+}
+
+/** Project one ledger entry for a management client. */
+export function transactionView(entry: LedgerTransaction): LedgerTransactionView {
+  return {
+    ref: entry.ref,
+    kind: entry.kind,
+    currency: entry.currency,
+    amount: entry.amount,
+    relatedRef: entry.relatedRef,
+    memo: entry.memo,
+    createdAt: entry.createdAt.toISOString(),
+  };
+}

package/src/index.ts

@@ -0,0 +1,23 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+/**
+ * The package entrypoint — the surface `pithy add ledger` wires into `pithy.config.ts`. Deliberately
+ * narrow: the capability factory, its config and options types, the `openLedger` primitive other
+ * capabilities call in-process, and the read shapes an app renders. Every other module is by deep path
+ * (`@pithy-sh/ledger/src/...`); this is the documented contract, not a barrel over the package.
+ */
+
+export {
+  isLedgerCapability,
+  LEDGER_MIGRATION_ORDER,
+  type LedgerCapability,
+  type LedgerOptions,
+  ledger,
+} from "./capability";
+export { LedgerConfig, type LedgerConfigInput, LedgerCurrency, resolveCurrency } from "./config/config";
+export type { Balance } from "./data/account";
+export { LedgerAccount } from "./data/account";
+export { LedgerHold } from "./data/hold";
+export { LedgerTransaction, TransactionKind } from "./data/transaction";
+export { type Ledger, openLedger } from "./ledger";