@book.dev/sdk 3.8.0 → 3.9.0

package/dist/ledgerExportSection.d.ts

@@ -0,0 +1,160 @@
+/**
+ * LX-2: the machine-readable **ledger section** an owner-initiated site export
+ * embeds alongside its pages/databases, and the read-authorized capture that
+ * builds it.
+ *
+ * ## Payload shape (the island's `ledger` key)
+ * Ledger records live OUTSIDE the document (four managed databases behind a
+ * restricted host page), so the export crawl never discovers them. When the
+ * export set shows ledger blocks and the exporter opted in, the site island
+ * carries a {@link LedgerExportSection}:
+ *
+ *  - `settings` — raw settings rows by key, the SAME keys the whole-space
+ *    backup's {@link LedgerBackupSection} uses: `ledgerDb` (the seeded ids,
+ *    reconstructed in the stored `LedgerIds` shape) and `ledgerPeriods` (the
+ *    `LedgerPeriod[]` array, verbatim). `ledgerEntrySeq` is NOT carried — it
+ *    has no client read surface; an importer can re-derive it from the highest
+ *    entry number (LX-4's concern).
+ *  - `library` — the ledger's own records in {@link LibrarySnapshot} shape
+ *    (exactly how they travel in a backup bundle): the restricted root host
+ *    page, the four child host pages, the four managed {@link StoredDatabase}s
+ *    (full schema), and every row page.
+ *  - `auditHead` — the newest audit event's `seq` + its chain hash
+ *    ({@link ledgerAuditEventHash}): a cheap tamper-evidence ANCHOR. The full
+ *    audit stream is deliberately NOT exported (a document export is not a
+ *    backup; the stream can dwarf the books). Holding the anchor, a verifier
+ *    with live access can prove the exported head is (or was) the real chain
+ *    head; offline chain verification needs a real backup (LGR-15).
+ *
+ * ## Authorization (no escalation through export)
+ * Every read below goes through the exporting principal's OWN {@link DataClient}
+ * read paths — the same routes/guards that gate the ledger UI. A principal who
+ * cannot read the ledger sees `ledgerInfo() → {exists:false}` (the server's
+ * existence-hiding body) or 404s on the restricted pages; either way the
+ * capture returns `null` and the export simply carries no ledger section (the
+ * blocks render as placeholders, LX-1). Fail-closed: ANY partial read failure
+ * drops the whole section rather than embedding an incomplete book.
+ */
+import type { DataClient } from './client';
+import type { LibrarySnapshot } from './bookFolder';
+import { type LedgerAccountStatus, type LedgerAccountType, type LedgerClearedState, type LedgerPeriod, type LedgerReconciliationStatus, type LedgerTransactionState } from './ledger';
+/** The ledger records embedded in a site export's source island (LX-2). */
+export interface LedgerExportSection {
+    /** Raw settings rows by key: `ledgerDb` (seeded ids) and `ledgerPeriods`
+     *  (`LedgerPeriod[]`, present only when periods exist). Same keys as the
+     *  backup bundle's `LedgerBackupSection.settings` (LGR-15). */
+    settings: Record<string, unknown>;
+    /** The ledger's own pages + databases, {@link LibrarySnapshot} shape: root
+     *  host page, four child host pages, four managed databases, every row page. */
+    library: LibrarySnapshot;
+    /** Tamper-evidence anchor: the newest audit event's `seq` and chain hash.
+     *  `null` when the audit stream is empty. The full stream is not exported. */
+    auditHead: {
+        seq: number;
+        hash: string;
+    } | null;
+}
+/**
+ * Capture the {@link LedgerExportSection} through the exporting principal's own
+ * read paths, or `null` when there is nothing to include: no seeded ledger,
+ * a principal who cannot read it, or any partial read failure (fail-closed —
+ * never embed half a book).
+ */
+export declare function gatherLedgerExportSection(client: DataClient): Promise<LedgerExportSection | null>;
+/** One account as the section records it (source ids kept for mapping). */
+export interface LedgerSectionAccount {
+    id: string;
+    name: string;
+    type: LedgerAccountType;
+    status: LedgerAccountStatus;
+    currency: string;
+    evidenceRequired: boolean;
+}
+/** One posting as the section records it. */
+export interface LedgerSectionPosting {
+    id: string;
+    accountId: string;
+    amountMinor: number;
+    cleared: LedgerClearedState;
+    reconciliationId: string | null;
+    memo: string | null;
+}
+/** One journal entry as the section records it. */
+export interface LedgerSectionTransaction {
+    id: string;
+    date: string;
+    description: string;
+    state: LedgerTransactionState;
+    reverses: string | null;
+    entryNo: number | null;
+    kind: 'closing' | null;
+    /** Evidence manifest items recorded on the entry. An HTML export carries no
+     *  evidence BYTES, so a restore drops these (counted, surfaced, never silent). */
+    evidenceCount: number;
+    postings: LedgerSectionPosting[];
+    createdAt: string;
+}
+/** One statement reconciliation as the section records it. */
+export interface LedgerSectionReconciliation {
+    id: string;
+    accountId: string;
+    statementDate: string;
+    statementBalanceMinor: number;
+    status: LedgerReconciliationStatus;
+    createdAt: string;
+}
+/** The typed book a valid section parses to — the replay plan's input. */
+export interface LedgerSectionBook {
+    accounts: LedgerSectionAccount[];
+    /** Sorted for replay: posted/void entries by entry number, drafts last. */
+    transactions: LedgerSectionTransaction[];
+    reconciliations: LedgerSectionReconciliation[];
+    /** Period records verbatim from `settings.ledgerPeriods` ([] when absent). */
+    periods: LedgerPeriod[];
+    auditHead: LedgerExportSection['auditHead'];
+    /** Total evidence manifest items the section records (not restorable from HTML). */
+    evidenceDropped: number;
+}
+export type LedgerSectionParseResult = {
+    ok: true;
+    book: LedgerSectionBook;
+} | {
+    ok: false;
+    reason: string;
+};
+/** What a section restore reports back (see the server's `restoreExportSection`). */
+export interface LedgerSectionRestoreResult {
+    restored: {
+        accounts: number;
+        transactions: number;
+        postings: number;
+        reconciliations: number;
+        periods: number;
+    };
+    /** Evidence manifest items that could not be restored — an HTML export
+     *  carries no evidence bytes; recover them from a backup bundle (LGR-15). */
+    evidenceDropped: number;
+    /** Finished reconciliations whose exact freeze could not be reproduced
+     *  (exotic reopen histories) and were replayed as ABANDONED instead —
+     *  workflow metadata only; the postings and report numbers are unaffected. */
+    reconciliationsDowngraded: number;
+}
+/**
+ * Parse + deep-validate a {@link LedgerExportSection} into a replayable
+ * {@link LedgerSectionBook}, or refuse with a reason. Refusals are TOTAL —
+ * a section is either a coherent book or it is not restored at all (never a
+ * partial parse the writer then trips over halfway).
+ *
+ * Validated here (beyond the island reader's shape check):
+ *  - the `ledgerDb` ids resolve to four DISTINCT databases the section carries;
+ *  - every row page belongs to one of the four (host pages are pass-through);
+ *  - enums, dates, and amounts are valid; posted/void entries balance to zero
+ *    with ≥2 postings; postings reference known accounts/transactions;
+ *  - the reversal graph is coherent: every `void` entry has exactly one
+ *    reversal, every reversal negates its original leg-for-leg;
+ *  - reconciliation invariants: `reconciled` ⇔ frozen by a FINISHED
+ *    reconciliation on the same account, at most one OPEN per account;
+ *  - period records are well-formed, closing entries are referenced by
+ *    exactly one period, and closed ranges do not overlap.
+ */
+export declare function parseLedgerExportSection(section: LedgerExportSection): LedgerSectionParseResult;