@book.dev/sdk 3.5.0 → 3.6.0

package/dist/backup.d.ts

@@ -11,7 +11,60 @@
  */
 import type { StoredPage } from './types';
 import type { StoredDatabase } from './database';
-export declare const BACKUP_VERSION = 1;
+import type { LedgerAuditEvent } from './ledger';
+/**
+ * Version 2 (LGR-15): the bundle MAY carry a {@link LedgerBackupSection} — the
+ * ledger's durability surface (audit stream, settings rows, evidence assets)
+ * that pages/databases alone cannot express. Additive: a v1 bundle (no
+ * `ledger` key) still imports; a v2 bundle read by an old server imports its
+ * pages/databases and ignores the extra key.
+ */
+export declare const BACKUP_VERSION = 2;
+/**
+ * One content-addressed asset carried by a backup (LGR-15): the evidence bytes
+ * behind a ledger transaction's manifest. `id` IS the SHA-256 of the bytes —
+ * the importer re-derives it and refuses a mismatch, so a bundle can never
+ * plant bytes under a hash they do not answer to.
+ */
+export interface LedgerBackupAsset {
+    /** Asset-store id: 64 lowercase hex chars, the SHA-256 of the bytes. */
+    id: string;
+    mime: string;
+    /** Byte count of the decoded content. */
+    size: number;
+    /** The raw bytes, base64-encoded (JSON cannot carry binary). */
+    bytesBase64: string;
+    /** Page ids holding an `asset_refs` edge to this asset (restored where the page exists). */
+    refs: string[];
+}
+/**
+ * The ledger durability surface of a backup (LGR-15). The ledger's ENTITIES
+ * (accounts/transactions/postings/reconciliations and their host pages) travel
+ * as ordinary pages/databases in the bundle; this section carries what those
+ * rows alone cannot restore:
+ *
+ *  - `settings` — the seeded ids (`ledgerDb`), the period records
+ *    (`ledgerPeriods`), and the entry-number sequence (`ledgerEntrySeq`),
+ *    verbatim as stored;
+ *  - `audit` — the FULL append-only audit stream, seq order, hashes included.
+ *    Restored verbatim so the tamper-evidence chain survives the round trip
+ *    (the LGR-7 verifier re-checks it against the restored rows);
+ *  - `assets` — the evidence bytes referenced by transaction manifests, so the
+ *    verifier's receipt re-hash check still has bytes to answer with.
+ *
+ * Restore semantics are deliberately narrow (see the server's `importBundle`):
+ * overwrite mode only, and ONLY into a library with no seeded ledger — a
+ * library that already has one keeps its LGR-3 protections and the section is
+ * skipped, reported via `ImportResult.ledger`.
+ */
+export interface LedgerBackupSection {
+    /** Raw `settings` rows by key: `ledgerDb`, `ledgerPeriods`, `ledgerEntrySeq` (when present). */
+    settings: Record<string, unknown>;
+    /** The full audit stream, ascending `seq`, verbatim (hashes included). */
+    audit: LedgerAuditEvent[];
+    /** Evidence assets referenced by ledger transaction manifests. */
+    assets: LedgerBackupAsset[];
+}
 export interface LibraryBackup {
     version: number;
     exportedAt: string;
@@ -19,6 +72,8 @@ export interface LibraryBackup {
     databases: StoredDatabase[];
     /** pageId → emoji icon (added client-side; ignored by the server). */
     icons?: Record<string, string>;
+    /** LGR-15: the ledger durability surface; absent when no ledger is seeded. */
+    ledger?: LedgerBackupSection;
 }
 export type ImportMode = 'copy' | 'overwrite';
 /** What the client sends to restore: the (already-selected) pages/databases + mode. */
@@ -26,7 +81,24 @@ export interface ImportRequest {
     pages: StoredPage[];
     databases: StoredDatabase[];
     mode: ImportMode;
+    /**
+     * LGR-15: the bundle's ledger section, forwarded on a full overwrite restore.
+     * Applied only when the target has no seeded ledger AND the selection carried
+     * the ledger's own pages/databases; otherwise skipped and reported.
+     */
+    ledger?: LedgerBackupSection;
 }
+/**
+ * What became of a bundle's {@link LedgerBackupSection} on import (LGR-15).
+ *  - `restored` — settings + audit stream + evidence assets applied;
+ *  - `skipped-existing-ledger` — the target already has a seeded ledger, whose
+ *    LGR-3 protections stand (restore ledger bundles into a FRESH library);
+ *  - `skipped-copy-mode` — copy mode re-ids every page, which would sever the
+ *    audit stream's entity references; the section only applies in overwrite;
+ *  - `skipped-incomplete` — the page selection did not carry the ledger's own
+ *    host pages/databases, so the section had nothing sound to attach to.
+ */
+export type LedgerRestoreOutcome = 'restored' | 'skipped-existing-ledger' | 'skipped-copy-mode' | 'skipped-incomplete';
 export interface ImportResult {
     /** New pages created (copy mode, or overwrite of a not-yet-existing id). */
     created: number;
@@ -36,6 +108,8 @@ export interface ImportResult {
     renamed: number;
     /** old page id → new page id (copy mode; identity in overwrite). */
     idMap: Record<string, string>;
+    /** LGR-15: outcome of the bundle's ledger section; absent when none was sent. */
+    ledger?: LedgerRestoreOutcome;
     /**
      * True when this apply was a **replay** of an already-imported bundle (ER-6):
      * the bundle's content hash matched a prior import, so nothing was written and

package/dist/backup.js

@@ -1,4 +1,11 @@
-export const BACKUP_VERSION = 1;
+/**
+ * Version 2 (LGR-15): the bundle MAY carry a {@link LedgerBackupSection} — the
+ * ledger's durability surface (audit stream, settings rows, evidence assets)
+ * that pages/databases alone cannot express. Additive: a v1 bundle (no
+ * `ledger` key) still imports; a v2 bundle read by an old server imports its
+ * pages/databases and ignores the extra key.
+ */
+export const BACKUP_VERSION = 2;
 export const BACKUP_CADENCES = ['daily', 'weekly', 'monthly', 'yearly'];
 /** Interval of each cadence, in milliseconds. */
 export const BACKUP_CADENCE_MS = {

package/dist/backup.js.map

@@ -1 +1 @@
-{"version":3,"file":"backup.js","sourceRoot":"","sources":["../src/backup.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"backup.js","sourceRoot":"","sources":["../src/backup.ts"],"names":[],"mappings":"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"}

package/dist/client.d.ts

@@ -4,9 +4,10 @@ import type { AgentChatEvent, AgentChatMessage, AgentChatOptions, AiConfig, AiPr
 import type { AclLevel, AgentEditsMode, AgentEditsPolicy, Member, MemberRole, MemberStatus, PageAcl, PageGraph, PageInput, PageMeta, PageVersionMeta, PageVisibility, StoredPage, StoredPageVersion } from './types';
 import type { InstanceConfig, InstanceInfo, StoredEdit } from './provenance';
 import type { AgentTokenMeta, AgentTokenScope } from './identity';
-import type { BackupCadence, BackupConfig, BackupStatus, ImportRequest, ImportResult } from './backup';
+import type { BackupCadence, BackupConfig, BackupStatus, ImportRequest, ImportResult, LedgerBackupSection } from './backup';
 import type { DatabaseInput, DatabaseRow, DatabaseUpdate, RowInput, RowUpdate, StoredDatabase } from './database';
 import type { CommentInput, StoredComment, StoredSuggestion, SuggestionInput, SuggestionStatus, SuggestionUpdate } from './suggestions';
+import type { LedgerAccount, LedgerAccountInput, LedgerAccountPatch, LedgerAuditEvent, LedgerClearedState, LedgerDraftInput, LedgerDraftPatch, LedgerInfo, LedgerPeriod, LedgerPeriodCloseInput, LedgerPeriodCloseResult, LedgerPeriodReopenResult, LedgerPosting, LedgerReconciliation, LedgerReconciliationInput, LedgerReconciliationPatch, LedgerReconciliationStatus, LedgerReconciliationSummary, LedgerReverseOptions, LedgerTransaction, LedgerTransactionState, LedgerVerifyReport } from './ledger';
 /** Handlers for a single page's live update stream. */
 export interface PageSubscription {
     /** A newer version of the page was saved (by anyone). */
@@ -170,10 +171,12 @@ export interface DataClient {
      * it. Resolves `true` if a live page was trashed.
      */
     deletePage(id: string): Promise<boolean>;
-    /** Export the whole space: every live page (full data) + every database. */
+    /** Export the whole space: every live page (full data) + every database —
+     *  plus the ledger durability section when a ledger is seeded (LGR-15). */
     exportLibrary(): Promise<{
         pages: StoredPage[];
         databases: StoredDatabase[];
+        ledger?: LedgerBackupSection;
     }>;
     /** Restore a (client-selected) set of pages/databases; see {@link ImportRequest}. */
     importLibrary(req: ImportRequest): Promise<ImportResult>;
@@ -289,6 +292,85 @@ export interface DataClient {
     reorderRows(databaseId: string, orderedIds: string[]): Promise<void>;
     /** Subscribe to a database's live row-list updates. Returns an unsubscribe fn. */
     subscribeRows(databaseId: string, onRows: (rows: DatabaseRow[]) => void): () => void;
+    /** Whether the ledger is initialized, and the seeded database/host ids. */
+    ledgerInfo(): Promise<LedgerInfo>;
+    /** Seed the four managed ledger databases + restricted host page (idempotent). */
+    ledgerInit(): Promise<LedgerInfo>;
+    /** List accounts (hierarchy is encoded in the colon-delimited names). */
+    ledgerListAccounts(): Promise<LedgerAccount[]>;
+    /** Create an account. `currency` defaults to `USD`. */
+    ledgerCreateAccount(input: LedgerAccountInput): Promise<LedgerAccount>;
+    /** Fetch one account, or `null` when it does not exist. */
+    ledgerGetAccount(id: string): Promise<LedgerAccount | null>;
+    /** Rename / close / reopen an account. Closing rejects at nonzero posted balance. */
+    ledgerUpdateAccount(id: string, patch: LedgerAccountPatch): Promise<LedgerAccount>;
+    /** List transactions with their postings (`state` filters; `limit` caps). */
+    ledgerListTransactions(opts?: {
+        state?: LedgerTransactionState;
+        limit?: number;
+    }): Promise<LedgerTransaction[]>;
+    /** Fetch one transaction (with postings), or `null` when it does not exist. */
+    ledgerGetTransaction(id: string): Promise<LedgerTransaction | null>;
+    /** Create a DRAFT transaction (with postings). Drafts are freely mutable. */
+    ledgerCreateDraft(input: LedgerDraftInput): Promise<LedgerTransaction>;
+    /** Update a DRAFT (posted/void transactions are immutable — typed rejection). */
+    ledgerUpdateDraft(id: string, patch: LedgerDraftPatch): Promise<LedgerTransaction>;
+    /** Delete a DRAFT and its postings (permanent, audited). Posted/void reject. */
+    ledgerDeleteDraft(id: string): Promise<boolean>;
+    /** Post a draft atomically (validates all invariants; assigns the entry number). */
+    ledgerPostTransaction(id: string): Promise<LedgerTransaction>;
+    /** Atomically create + post the reversing entry and void the original. */
+    ledgerReverseTransaction(id: string, opts?: LedgerReverseOptions): Promise<LedgerTransaction>;
+    /** Flip a posting between `pending`/`cleared` (`reconciled` is locked, LGR-11). */
+    ledgerSetPostingCleared(postingId: string, cleared: LedgerClearedState): Promise<LedgerPosting>;
+    /** List reconciliations, newest statement first. Filters are ANDed. */
+    ledgerListReconciliations(opts?: {
+        accountId?: string;
+        status?: LedgerReconciliationStatus;
+    }): Promise<LedgerReconciliation[]>;
+    /** One reconciliation with its live cleared balance + difference, or `null`. */
+    ledgerGetReconciliation(id: string): Promise<LedgerReconciliationSummary | null>;
+    /** START a reconciliation. Rejects `reconciliation-exists` if one is open. */
+    ledgerStartReconciliation(input: LedgerReconciliationInput): Promise<LedgerReconciliation>;
+    /** AMEND an OPEN reconciliation's statement date/balance (LGR-22) — the fix
+     *  for a mistyped target, which no amount of ticking can reach zero. Touches
+     *  no posting; returns the summary with the difference recomputed. */
+    ledgerAmendReconciliation(id: string, patch: LedgerReconciliationPatch): Promise<LedgerReconciliationSummary>;
+    /** ABANDON an OPEN reconciliation (LGR-22): end it without balancing it and
+     *  without posting anything. Terminal, audited, posting-neutral — every tick
+     *  keeps its cleared state, and the account is free to start a new one. */
+    ledgerAbandonReconciliation(id: string): Promise<LedgerReconciliation>;
+    /** Match (`cleared`) or unmatch (`pending`) one posting inside an OPEN one. */
+    ledgerToggleReconciliationPosting(id: string, postingId: string, cleared: 'pending' | 'cleared'): Promise<LedgerReconciliationSummary>;
+    /** FINISH — only at a difference of exactly 0; freezes the matched postings. */
+    ledgerFinishReconciliation(id: string): Promise<LedgerReconciliationSummary>;
+    /** REOPEN a finished reconciliation (explicit, audited); unfreezes its postings. */
+    ledgerReopenReconciliation(id: string): Promise<LedgerReconciliationSummary>;
+    /** Every period record — closed AND reopened history (LGR-12). */
+    ledgerListPeriods(): Promise<LedgerPeriod[]>;
+    /** CLOSE a period: closing entry + date-range lock; warns (never blocks) on
+     *  open reconciliations. Store-enforced — `period-closed` rejections for any
+     *  posting/reversal dated inside the range hold over both transports. */
+    ledgerClosePeriod(input: LedgerPeriodCloseInput): Promise<LedgerPeriodCloseResult>;
+    /** REOPEN a closed period (explicit, audited): voids the closing entry via a
+     *  reversal and restores postability for the range. */
+    ledgerReopenPeriod(id: string): Promise<LedgerPeriodReopenResult>;
+    /** Read the append-only audit log, newest first (`before` = seq cursor). */
+    ledgerListAudit(opts?: {
+        limit?: number;
+        before?: number;
+    }): Promise<LedgerAuditEvent[]>;
+    /** The whole ledger as the canonical postings CSV (LGR-7) — byte-stable:
+     *  same data ⇒ identical bytes over BOTH transports. */
+    ledgerExportCsv(): Promise<string>;
+    /** The whole ledger as a Beancount journal (LGR-13) — byte-stable like the
+     *  CSV, built from the same read model; `bean-check`/Fava re-verify it with
+     *  an independent implementation. */
+    ledgerExportBeancount(): Promise<string>;
+    /** The independent invariant verifier's report (LGR-7). Admin-gated over
+     *  HTTP (the report names entity ids across the whole book); the local
+     *  single-user store answers directly. */
+    ledgerVerify(): Promise<LedgerVerifyReport>;
     /** List a page's suggestions, newest first. `status` filters (e.g. only open). */
     listSuggestions(pageId: string, status?: SuggestionStatus): Promise<StoredSuggestion[]>;
     /** Persist a new suggestion (status defaults to `open`). */
@@ -554,6 +636,7 @@ export declare class HttpDataClient implements DataClient {
     exportLibrary(): Promise<{
         pages: StoredPage[];
         databases: StoredDatabase[];
+        ledger?: LedgerBackupSection;
     }>;
     importLibrary(req: ImportRequest): Promise<ImportResult>;
     listTrash(): Promise<PageMeta[]>;
@@ -619,6 +702,55 @@ export declare class HttpDataClient implements DataClient {
     updateRow(databaseId: string, rowId: string, patch: RowUpdate): Promise<DatabaseRow>;
     reorderRows(databaseId: string, orderedIds: string[]): Promise<void>;
     subscribeRows(databaseId: string, onRows: (rows: DatabaseRow[]) => void): () => void;
+    /**
+     * Like {@link request}, but re-materializes the server's `{error, code}` body
+     * into a typed {@link LedgerError} — so a caller catches the SAME error class
+     * over HTTP as it does against the in-process {@link PageStore} (local mode).
+     */
+    private ledgerRequest;
+    /** Re-materialize a non-2xx ledger response into a typed {@link LedgerError}. */
+    private throwLedgerError;
+    ledgerInfo(): Promise<LedgerInfo>;
+    ledgerInit(): Promise<LedgerInfo>;
+    ledgerListAccounts(): Promise<LedgerAccount[]>;
+    ledgerCreateAccount(input: LedgerAccountInput): Promise<LedgerAccount>;
+    ledgerGetAccount(id: string): Promise<LedgerAccount | null>;
+    ledgerUpdateAccount(id: string, patch: LedgerAccountPatch): Promise<LedgerAccount>;
+    ledgerListTransactions(opts?: {
+        state?: LedgerTransactionState;
+        limit?: number;
+    }): Promise<LedgerTransaction[]>;
+    ledgerGetTransaction(id: string): Promise<LedgerTransaction | null>;
+    ledgerCreateDraft(input: LedgerDraftInput): Promise<LedgerTransaction>;
+    ledgerUpdateDraft(id: string, patch: LedgerDraftPatch): Promise<LedgerTransaction>;
+    ledgerDeleteDraft(id: string): Promise<boolean>;
+    ledgerPostTransaction(id: string): Promise<LedgerTransaction>;
+    ledgerReverseTransaction(id: string, opts?: LedgerReverseOptions): Promise<LedgerTransaction>;
+    ledgerSetPostingCleared(postingId: string, cleared: LedgerClearedState): Promise<LedgerPosting>;
+    ledgerListReconciliations(opts?: {
+        accountId?: string;
+        status?: LedgerReconciliationStatus;
+    }): Promise<LedgerReconciliation[]>;
+    ledgerGetReconciliation(id: string): Promise<LedgerReconciliationSummary | null>;
+    ledgerStartReconciliation(input: LedgerReconciliationInput): Promise<LedgerReconciliation>;
+    ledgerAmendReconciliation(id: string, patch: LedgerReconciliationPatch): Promise<LedgerReconciliationSummary>;
+    ledgerAbandonReconciliation(id: string): Promise<LedgerReconciliation>;
+    ledgerToggleReconciliationPosting(id: string, postingId: string, cleared: 'pending' | 'cleared'): Promise<LedgerReconciliationSummary>;
+    ledgerFinishReconciliation(id: string): Promise<LedgerReconciliationSummary>;
+    ledgerReopenReconciliation(id: string): Promise<LedgerReconciliationSummary>;
+    ledgerListPeriods(): Promise<LedgerPeriod[]>;
+    ledgerClosePeriod(input: LedgerPeriodCloseInput): Promise<LedgerPeriodCloseResult>;
+    ledgerReopenPeriod(id: string): Promise<LedgerPeriodReopenResult>;
+    ledgerListAudit(opts?: {
+        limit?: number;
+        before?: number;
+    }): Promise<LedgerAuditEvent[]>;
+    /** Canonical postings CSV (LGR-7) — a ledger read that is text, not JSON. */
+    ledgerExportCsv(): Promise<string>;
+    /** Beancount journal (LGR-13) — text like the CSV, same error mapping. */
+    ledgerExportBeancount(): Promise<string>;
+    /** The independent verifier's report (admin-gated server-side). */
+    ledgerVerify(): Promise<LedgerVerifyReport>;
     listSuggestions(pageId: string, status?: SuggestionStatus): Promise<StoredSuggestion[]>;
     createSuggestion(input: SuggestionInput): Promise<StoredSuggestion>;
     updateSuggestion(id: string, patch: SuggestionUpdate): Promise<StoredSuggestion>;

package/dist/client.js

@@ -1,4 +1,5 @@
 import { API } from './routes';
+import { LEDGER_ERROR_CODES, LedgerError } from './ledger';
 /**
  * The global `fetch`, wrapped so it's safe to store on an object and call as a
  * property/method. WebKit (the desktop WKWebView) throws "Can only call
@@ -779,6 +780,176 @@ export class HttpDataClient {
     subscribeRows(databaseId, onRows) {
         return this.liveStream().onRows(databaseId, onRows);
     }
+    // ── Ledger: server-enforced double-entry accounting (LGR-3) ──────────────────
+    /**
+     * Like {@link request}, but re-materializes the server's `{error, code}` body
+     * into a typed {@link LedgerError} — so a caller catches the SAME error class
+     * over HTTP as it does against the in-process {@link PageStore} (local mode).
+     */
+    async ledgerRequest(method, path, body) {
+        const res = await this.authFetch(`${this.baseUrl}${path}`, {
+            method,
+            headers: body === undefined ? undefined : { 'Content-Type': 'application/json' },
+            body: body === undefined ? undefined : JSON.stringify(body),
+            cache: 'no-store',
+        });
+        if (!res.ok)
+            return this.throwLedgerError(res);
+        if (res.status === 204)
+            return undefined;
+        return (await res.json());
+    }
+    /** Re-materialize a non-2xx ledger response into a typed {@link LedgerError}. */
+    async throwLedgerError(res) {
+        let data = null;
+        try {
+            data = (await res.json());
+        }
+        catch {
+            data = null;
+        }
+        if (data?.code && LEDGER_ERROR_CODES.includes(data.code)) {
+            throw new LedgerError(data.code, data.error ?? `ledger request failed (${res.status})`);
+        }
+        throw new Error(`OpenBook request failed (${res.status} ${res.statusText})${data?.error ? `: ${data.error}` : ''}`);
+    }
+    ledgerInfo() {
+        return this.ledgerRequest('GET', API.ledger);
+    }
+    ledgerInit() {
+        return this.ledgerRequest('POST', API.ledger);
+    }
+    ledgerListAccounts() {
+        return this.ledgerRequest('GET', API.ledgerAccounts);
+    }
+    ledgerCreateAccount(input) {
+        return this.ledgerRequest('POST', API.ledgerAccounts, input);
+    }
+    async ledgerGetAccount(id) {
+        try {
+            return await this.ledgerRequest('GET', API.ledgerAccount(id));
+        }
+        catch (err) {
+            if (err instanceof LedgerError && err.code === 'not-found')
+                return null;
+            throw err;
+        }
+    }
+    ledgerUpdateAccount(id, patch) {
+        return this.ledgerRequest('PATCH', API.ledgerAccount(id), patch);
+    }
+    ledgerListTransactions(opts) {
+        const params = new URLSearchParams();
+        if (opts?.state)
+            params.set('state', opts.state);
+        if (opts?.limit != null)
+            params.set('limit', String(opts.limit));
+        const query = params.toString();
+        return this.ledgerRequest('GET', `${API.ledgerTransactions}${query ? `?${query}` : ''}`);
+    }
+    async ledgerGetTransaction(id) {
+        try {
+            return await this.ledgerRequest('GET', API.ledgerTransaction(id));
+        }
+        catch (err) {
+            if (err instanceof LedgerError && err.code === 'not-found')
+                return null;
+            throw err;
+        }
+    }
+    ledgerCreateDraft(input) {
+        return this.ledgerRequest('POST', API.ledgerTransactions, input);
+    }
+    ledgerUpdateDraft(id, patch) {
+        return this.ledgerRequest('PATCH', API.ledgerTransaction(id), patch);
+    }
+    async ledgerDeleteDraft(id) {
+        await this.ledgerRequest('DELETE', API.ledgerTransaction(id));
+        return true;
+    }
+    ledgerPostTransaction(id) {
+        return this.ledgerRequest('POST', API.ledgerTransactionPost(id));
+    }
+    ledgerReverseTransaction(id, opts) {
+        return this.ledgerRequest('POST', API.ledgerTransactionReverse(id), opts ?? {});
+    }
+    ledgerSetPostingCleared(postingId, cleared) {
+        return this.ledgerRequest('PUT', API.ledgerPostingCleared(postingId), { cleared });
+    }
+    // ── Statement reconciliation (LGR-11) ───────────────────────────────────────
+    ledgerListReconciliations(opts) {
+        const params = new URLSearchParams();
+        if (opts?.accountId != null)
+            params.set('accountId', opts.accountId);
+        if (opts?.status != null)
+            params.set('status', opts.status);
+        const query = params.toString();
+        return this.ledgerRequest('GET', `${API.ledgerReconciliations}${query ? `?${query}` : ''}`);
+    }
+    async ledgerGetReconciliation(id) {
+        try {
+            return await this.ledgerRequest('GET', API.ledgerReconciliation(id));
+        }
+        catch (err) {
+            if (err instanceof LedgerError && err.code === 'not-found')
+                return null;
+            throw err;
+        }
+    }
+    ledgerStartReconciliation(input) {
+        return this.ledgerRequest('POST', API.ledgerReconciliations, input);
+    }
+    ledgerAmendReconciliation(id, patch) {
+        return this.ledgerRequest('PATCH', API.ledgerReconciliation(id), patch);
+    }
+    ledgerAbandonReconciliation(id) {
+        return this.ledgerRequest('POST', API.ledgerReconciliationAbandon(id));
+    }
+    ledgerToggleReconciliationPosting(id, postingId, cleared) {
+        return this.ledgerRequest('PUT', API.ledgerReconciliationPosting(id, postingId), { cleared });
+    }
+    ledgerFinishReconciliation(id) {
+        return this.ledgerRequest('POST', API.ledgerReconciliationFinish(id));
+    }
+    ledgerReopenReconciliation(id) {
+        return this.ledgerRequest('POST', API.ledgerReconciliationReopen(id));
+    }
+    ledgerListPeriods() {
+        return this.ledgerRequest('GET', API.ledgerPeriods);
+    }
+    ledgerClosePeriod(input) {
+        return this.ledgerRequest('POST', API.ledgerPeriods, input);
+    }
+    ledgerReopenPeriod(id) {
+        return this.ledgerRequest('POST', API.ledgerPeriodReopen(id));
+    }
+    ledgerListAudit(opts) {
+        const params = new URLSearchParams();
+        if (opts?.limit != null)
+            params.set('limit', String(opts.limit));
+        if (opts?.before != null)
+            params.set('before', String(opts.before));
+        const query = params.toString();
+        return this.ledgerRequest('GET', `${API.ledgerAudit}${query ? `?${query}` : ''}`);
+    }
+    /** Canonical postings CSV (LGR-7) — a ledger read that is text, not JSON. */
+    async ledgerExportCsv() {
+        const res = await this.authFetch(`${this.baseUrl}${API.ledgerExportCsv}`, { cache: 'no-store' });
+        if (!res.ok)
+            return this.throwLedgerError(res);
+        return res.text();
+    }
+    /** Beancount journal (LGR-13) — text like the CSV, same error mapping. */
+    async ledgerExportBeancount() {
+        const res = await this.authFetch(`${this.baseUrl}${API.ledgerExportBeancount}`, { cache: 'no-store' });
+        if (!res.ok)
+            return this.throwLedgerError(res);
+        return res.text();
+    }
+    /** The independent verifier's report (admin-gated server-side). */
+    async ledgerVerify() {
+        return this.ledgerRequest('GET', API.ledgerVerify);
+    }
     // ── Suggestions + comments (the review layer) ────────────────────────────────
     async listSuggestions(pageId, status) {
         const path = status ? `${API.suggestions(pageId)}?status=${encodeURIComponent(status)}` : API.suggestions(pageId);