@mohasinac/appkit 4.62.1 → 4.63.0

package/dist/features/ledger/repository/journal.repository.js

@@ -0,0 +1,312 @@
+/*
+ * WHY: The only write path into the books. Every rule that makes a ledger
+ *      trustworthy — balanced, append-only, period-locked — is enforced here
+ *      rather than asked of callers, because a caller who gets one wrong
+ *      produces a successful write and finds out at the next GST return.
+ *
+ * WHAT: JournalRepository — post, reverse, lock, read.
+ *
+ * @tag domain:ledger,finance
+ * @tag layer:repository
+ * @tag access:server
+ * @tag sideEffects:firestore
+ */
+/* The DIRECTORY barrel, which is where every other repository gets this
+ * from — `providers/db-firebase/base` exports only `FirebaseRepository`,
+ * and `BaseRepository` (the one with `this.db` and `mapDoc`) is composed
+ * one level up. */
+import { BaseRepository } from "../../../providers/db-firebase/index.js";
+import { unitOfWork } from "../../../core/unit-of-work.js";
+import { JOURNAL_ENTRIES_COLLECTION, ACCOUNTING_PERIODS_COLLECTION, LEDGER_FIELDS, } from "../schemas/firestore.js";
+import { assertBalanced, buildReversal, periodOf, UnbalancedEntryError, } from "../../../_internal/shared/features/ledger/posting.js";
+import { NotFoundError } from "../../../errors/not-found-error.js";
+import { ValidationError } from "../../../errors/validation-error.js";
+/**
+ * How many entries one period read may return.
+ *
+ * Sized against a plausible month rather than a round number: a few hundred
+ * orders, each posting two or three entries, plus settlements and expenses.
+ * 2,000 leaves real headroom and still fits comfortably inside a function's
+ * memory and the ~3-round-trip budget.
+ */
+export const JOURNAL_PERIOD_SCAN_LIMIT = 2000;
+export class JournalRepository extends BaseRepository {
+    /*
+     * 🛑 NO `SIEVE_FIELDS`, same reasoning as `obligations`. The reports read
+     * by period and by account code — two fixed shapes, both served by the
+     * automatic index — and an admin looking at a figure opens the ORDER it
+     * came from, not a filtered journal list. A Sieve surface nothing calls is
+     * the `route-schema-registry` pattern: 576 keys into a layer with no
+     * readers.
+     */
+    constructor() {
+        super(JOURNAL_ENTRIES_COLLECTION);
+    }
+    /**
+     * 🛑 APPEND-ONLY, and the method bodies refuse rather than a comment
+     * asking nicely.
+     *
+     * `inventoryMovements` takes the same stance for the same reason: a
+     * Firestore update succeeds silently, so a caller who edits history never
+     * finds out, and a ledger whose rows can be edited cannot be used as
+     * evidence of anything. The correction mechanism is `reverse()`.
+     */
+    async update() {
+        throw new Error("journalEntries is append-only. Correct an entry with reverse(), which posts the opposite legs and links the two — an edit would silently rewrite a period a GST return may already have been filed from.");
+    }
+    async delete() {
+        throw new Error("journalEntries is append-only. An entry that should not have been posted is reversed, not removed; the reversal is the record that it was wrong.");
+    }
+    /**
+     * Post one entry.
+     *
+     * 🛑 **The balance check and the lock check are INSIDE the transaction.**
+     * Reading the period's state first and writing after is a TOCTOU window: an
+     * admin filing a return between the two gets an entry in the period they
+     * just closed, which is the one outcome the lock exists to prevent. It is a
+     * narrow window and it is exactly the kind that shows up once, in the
+     * quarter it matters.
+     */
+    async post(input) {
+        const balanced = assertBalanced(input);
+        return unitOfWork.runTransaction(async (tx) => {
+            const db = this.db;
+            const periodRef = db
+                .collection(ACCOUNTING_PERIODS_COLLECTION)
+                .doc(`period-${balanced.period}`);
+            const snap = await tx.get(periodRef);
+            const period = snap.exists ? snap.data() : null;
+            /*
+             * 🛑 A period with NO row is OPEN, not closed.
+             *
+             * Fail-open here and fail-closed everywhere else is deliberate: a
+             * period is closed by someone filing a return, which is an action that
+             * writes a row. Treating absence as closed would mean the books refuse
+             * every posting until an admin opens each month by hand — and the
+             * first missed month silently stops the entire ingest, which looks
+             * like a broken job rather than a missing row.
+             */
+            if (period?.status === "locked") {
+                throw new ValidationError(`Period ${balanced.period} is closed and cannot accept new entries.`, {
+                    period: period.lockedReason ??
+                        "A return has been filed for this period. Post the correction to the open period instead.",
+                });
+            }
+            const ref = db.collection(JOURNAL_ENTRIES_COLLECTION).doc();
+            const now = new Date();
+            const doc = {
+                ...balanced,
+                id: ref.id,
+                createdAt: now,
+                updatedAt: now,
+            };
+            tx.set(ref, doc);
+            return doc;
+        });
+    }
+    /**
+     * Reverse an entry.
+     *
+     * 🛑 **Refuses a SECOND reversal of the same entry.** Without the check a
+     * double-click posts the opposite legs twice, and the books then show the
+     * original plus two reversals — a net position that is the mirror image of
+     * the truth, balanced, and wrong. `reversedByEntryId` is set inside the
+     * same transaction that reads it, so the second attempt loses the race
+     * rather than both succeeding.
+     */
+    async reverse(entryId, reason, at = new Date()) {
+        if (!reason.trim()) {
+            /*
+             * A reversal with no stated reason is the one thing a reader of the
+             * books cannot reconstruct later. The original entry says what was
+             * posted; only this says why it was wrong.
+             */
+            throw new ValidationError("A reversal needs a reason.", {
+                reason: "Say what was wrong with the original entry.",
+            });
+        }
+        return unitOfWork.runTransaction(async (tx) => {
+            const db = this.db;
+            const originalRef = db.collection(JOURNAL_ENTRIES_COLLECTION).doc(entryId);
+            const snap = await tx.get(originalRef);
+            if (!snap.exists)
+                throw new NotFoundError(`Journal entry ${entryId} not found.`);
+            const original = snap.data();
+            if (original.reversedByEntryId) {
+                throw new ValidationError(`Entry ${entryId} has already been reversed by ${original.reversedByEntryId}.`, { entryId: "Reversing it again would double the correction." });
+            }
+            if (original.sourceEvent === "reversal") {
+                /*
+                 * Reversing a reversal is re-instating the original, and saying so
+                 * is clearer than letting someone build a chain nobody can read. If
+                 * the original was right after all, post it again with a narration
+                 * that says why.
+                 */
+                throw new ValidationError(`Entry ${entryId} is itself a reversal.`, { entryId: "To re-instate the original, post it again with a narration explaining why." });
+            }
+            const reversalInput = buildReversal({ id: entryId, lines: original.lines, narration: original.narration }, at, reason.trim());
+            const balanced = assertBalanced(reversalInput);
+            /*
+             * The reversal's OWN period must be open. It is `at`'s period, not the
+             * original's — see `buildReversal`, which deliberately does not
+             * back-date. A correction found after a return was filed posts to the
+             * open month and references the closed one.
+             */
+            const periodRef = db
+                .collection(ACCOUNTING_PERIODS_COLLECTION)
+                .doc(`period-${balanced.period}`);
+            const periodSnap = await tx.get(periodRef);
+            const period = periodSnap.exists
+                ? periodSnap.data()
+                : null;
+            if (period?.status === "locked") {
+                throw new ValidationError(`Period ${balanced.period} is closed, so the correction has nowhere to post.`, { period: "Open the current period before reversing." });
+            }
+            const ref = db.collection(JOURNAL_ENTRIES_COLLECTION).doc();
+            const now = new Date();
+            const reversal = {
+                ...balanced,
+                id: ref.id,
+                reversesEntryId: entryId,
+                createdAt: now,
+                updatedAt: now,
+            };
+            tx.set(ref, reversal);
+            /*
+             * 🛑 The back-link is written with `tx.update` on the ORIGINAL, which
+             * is the one edit to a posted entry this class permits — and it adds a
+             * pointer rather than changing a figure. Without it `reverse()` has no
+             * way to refuse a second attempt, and nothing reading the original can
+             * tell it has been corrected.
+             */
+            tx.update(originalRef, { reversedByEntryId: ref.id, updatedAt: now });
+            return reversal;
+        });
+    }
+    /**
+     * Close a period.
+     *
+     * 🛑 Takes the reason and the actor, both required. "Who closed October
+     * and under which return" is the first question anyone asks when a figure
+     * disagrees with a filing, and a lock with no answer to it is a lock
+     * somebody will simply reopen.
+     */
+    async lockPeriod(period, lockedByUid, lockedReason) {
+        if (!/^\d{4}-\d{2}$/.test(period)) {
+            throw new ValidationError(`"${period}" is not a YYYY-MM period.`, {
+                period: "Expected a month such as 2026-10.",
+            });
+        }
+        if (!lockedReason.trim()) {
+            throw new ValidationError("Closing a period needs a reason.", {
+                lockedReason: "Name the return this period was filed under.",
+            });
+        }
+        await unitOfWork.runTransaction(async (tx) => {
+            const db = this.db;
+            const ref = db.collection(ACCOUNTING_PERIODS_COLLECTION).doc(`period-${period}`);
+            const snap = await tx.get(ref);
+            if (snap.data()?.status === "locked") {
+                /*
+                 * Idempotent rather than an error: a retried request must not read
+                 * as a failure, and re-closing a closed period changes nothing.
+                 */
+                return;
+            }
+            const now = new Date();
+            tx.set(ref, {
+                id: `period-${period}`,
+                period,
+                status: "locked",
+                lockedReason: lockedReason.trim(),
+                lockedAt: now,
+                lockedByUid,
+                createdAt: now,
+                updatedAt: now,
+            });
+        });
+    }
+    /**
+     * 🛑 There is deliberately NO `unlockPeriod`.
+     *
+     * Reopening a period a return was filed from is not an operation the
+     * system should make easy — the correct response to a late correction is a
+     * reversing entry in the OPEN period, which is what `resolvePostingPeriod`
+     * computes and what every accountant expects. If a period genuinely must
+     * be reopened (a return withdrawn, say), that is a deliberate act with a
+     * paper trail outside this system, and a console write is the right amount
+     * of friction for it.
+     *
+     * This method exists only to say so. Deleting it would leave the absence
+     * looking like an oversight somebody helpfully fills in.
+     */
+    /**
+     * Every entry in a period, for a trial balance or a return.
+     *
+     * 🛑 **BOUNDED, and truncation is REPORTED rather than silent.** An
+     * unbounded read is the Rule #6 violation, but the reason it matters here
+     * is sharper than cost: a trial balance computed from a silently truncated
+     * page is a trial balance that BALANCES — both sides lose the same
+     * entries — while being wrong. It would look perfect and reconcile to
+     * nothing.
+     *
+     * So `truncated` is part of the return type and callers must handle it.
+     * The same stance `listPublicProducts` takes with its own `truncated`
+     * flag: a floor rendered as "50+", never a figure presented as a total.
+     *
+     * The real answer at volume is a period rollup written by a scheduled job
+     * — the `revenueRollup` pattern — and this is deliberately NOT that, so
+     * the flag is what forces the question rather than hiding it.
+     */
+    async listByPeriod(period, limit = JOURNAL_PERIOD_SCAN_LIMIT) {
+        const snap = await this.db
+            .collection(JOURNAL_ENTRIES_COLLECTION)
+            .where(LEDGER_FIELDS.PERIOD, "==", period)
+            .orderBy(LEDGER_FIELDS.ENTRY_DATE)
+            .limit(limit + 1)
+            .get();
+        const docs = snap.docs.slice(0, limit);
+        return {
+            entries: docs.map((d) => this.mapDoc(d)),
+            truncated: snap.docs.length > limit,
+        };
+    }
+    /** Whether a period is closed. Absence means open — see `post`. */
+    async isPeriodLocked(period) {
+        const snap = await this.db
+            .collection(ACCOUNTING_PERIODS_COLLECTION)
+            .doc(`period-${period}`)
+            .get();
+        return snap.data()?.status === "locked";
+    }
+    /**
+     * The cutover entry.
+     *
+     * 🛑 **NOT a backfill.** Pre-cutover data here is seeded and test, so
+     * replaying it would post fixtures as trade — the first financial year is
+     * therefore split across the old rollups and this ledger, and the
+     * "pre-ledger estimate" label on the old reports is what keeps that
+     * honest rather than hiding it.
+     *
+     * 🛑 Refuses to run twice. An opening balance posted a second time doubles
+     * every starting figure, and because both entries balance nothing
+     * downstream would object.
+     */
+    async postOpeningBalances(at, lines) {
+        const existing = await this.db
+            .collection(JOURNAL_ENTRIES_COLLECTION)
+            .where(LEDGER_FIELDS.SOURCE_EVENT, "==", "opening-balance")
+            .limit(1)
+            .get();
+        if (!existing.empty) {
+            throw new UnbalancedEntryError("Opening balances have already been posted. Correct them with a reversing entry rather than posting a second opening.");
+        }
+        return this.post({
+            entryDate: at,
+            sourceEvent: "opening-balance",
+            narration: `Opening balances at cutover, ${periodOf(at)}`,
+            lines,
+        });
+    }
+}
+export const journalRepository = new JournalRepository();

package/dist/features/ledger/schemas/expenses.d.ts

@@ -0,0 +1,87 @@
+/**
+ * `vendors` + `expenses` — money that leaves the business for something
+ * other than a payout or a refund.
+ *
+ * ## 🛑 A VENDOR IS AN IDENTITY, which `supplierName` never was
+ *
+ * `ShipmentDocument.supplierName` is free text, so four shipments from one
+ * supplier are four unjoined strings and "what have we spent with Acme" is
+ * unanswerable. That is not a reporting nicety: it is also the join that
+ * makes input GST claimable per supplier, which is what a GSTR-2B
+ * reconciliation needs.
+ *
+ * ## 🛑 An expense is TRUTH; its journal entry is the projection
+ *
+ * Same split as orders and payouts. The expense row is what somebody
+ * actually paid for, with the bill attached; the ledger says how it was
+ * classified. Re-classifying an expense posts a reversal and a new entry —
+ * it never edits the old one — so the two stay reconcilable.
+ */
+import type { BaseDocument } from "../../../_internal/shared/types/base-document";
+export declare const VENDORS_COLLECTION = "vendors";
+export declare const EXPENSES_COLLECTION = "expenses";
+export interface VendorDocument extends BaseDocument {
+    /** `vendor-{slug}` — a pure slug, like every other named entity here. */
+    name: string;
+    /**
+     * 🛑 The GSTIN is what makes input tax claimable, and it is NOT PII.
+     *
+     * It is a business registration number, printed on every invoice the
+     * vendor issues and published in the GST portal's public search. Treating
+     * it as PII would mean encrypting the one field a GSTR-2B reconciliation
+     * has to match on — which would make the reconciliation impossible for no
+     * privacy gain.
+     */
+    gstin?: string;
+    /**
+     * Where the vendor is registered, for the place-of-supply rule.
+     *
+     * An intra-state purchase splits input tax into CGST + SGST and an
+     * inter-state one is IGST; they are different ledger accounts and a wrong
+     * one is a wrong return. Optional because a vendor with no GSTIN charges
+     * no GST and the question does not arise.
+     */
+    stateCode?: string;
+    notes?: string;
+    isActive: boolean;
+}
+/**
+ * What the money was for. Drives the expense account the posting hits.
+ *
+ * 🛑 A closed union rather than free text, and `other` is a real member
+ * precisely so the exception stays countable — "how much of our spend is
+ * unclassified" is one query, and a growing answer is the signal to add a
+ * category rather than a reason to allow typing one.
+ */
+export type ExpenseCategory = "freight" | "platform-software" | "wages" | "packaging" | "asset" | "other";
+export interface ExpenseDocument extends BaseDocument {
+    vendorId?: string;
+    /** As written on the bill, for the same reason `supplierName` survives. */
+    vendorName: string;
+    category: ExpenseCategory;
+    /** The date on the BILL, not when it was entered — the period follows this. */
+    billDate: Date;
+    billNumber?: string;
+    /** Excluding tax. */
+    amount: number;
+    /**
+     * Input GST on this bill, claimable as ITC.
+     *
+     * 🛑 Stored SEPARATELY from `amount` rather than as a rate, because the
+     * figure on the bill is authoritative and re-deriving it from a
+     * percentage reproduces the supplier's rounding wrongly about as often as
+     * it reproduces it rightly — and the difference is what a GSTR-2B
+     * mismatch is made of.
+     */
+    inputGst?: number;
+    /** Set once posted, so a re-run cannot double-post. */
+    journalEntryId?: string;
+    attachmentUrl?: string;
+    recordedByUid: string;
+}
+export declare const EXPENSE_FIELDS: {
+    readonly VENDOR_ID: "vendorId";
+    readonly CATEGORY: "category";
+    readonly BILL_DATE: "billDate";
+    readonly JOURNAL_ENTRY_ID: "journalEntryId";
+};

package/dist/features/ledger/schemas/expenses.js

@@ -0,0 +1,27 @@
+/**
+ * `vendors` + `expenses` — money that leaves the business for something
+ * other than a payout or a refund.
+ *
+ * ## 🛑 A VENDOR IS AN IDENTITY, which `supplierName` never was
+ *
+ * `ShipmentDocument.supplierName` is free text, so four shipments from one
+ * supplier are four unjoined strings and "what have we spent with Acme" is
+ * unanswerable. That is not a reporting nicety: it is also the join that
+ * makes input GST claimable per supplier, which is what a GSTR-2B
+ * reconciliation needs.
+ *
+ * ## 🛑 An expense is TRUTH; its journal entry is the projection
+ *
+ * Same split as orders and payouts. The expense row is what somebody
+ * actually paid for, with the bill attached; the ledger says how it was
+ * classified. Re-classifying an expense posts a reversal and a new entry —
+ * it never edits the old one — so the two stay reconcilable.
+ */
+export const VENDORS_COLLECTION = "vendors";
+export const EXPENSES_COLLECTION = "expenses";
+export const EXPENSE_FIELDS = {
+    VENDOR_ID: "vendorId",
+    CATEGORY: "category",
+    BILL_DATE: "billDate",
+    JOURNAL_ENTRY_ID: "journalEntryId",
+};

package/dist/features/ledger/schemas/firestore.d.ts

@@ -0,0 +1,183 @@
+/**
+ * `chartOfAccounts` + `journalEntries` — Part 4's double-entry books.
+ *
+ * ## 🛑 THE LEDGER IS A PROJECTION. Orders, payouts and expenses are truth.
+ *
+ * The same split `obligations` takes, and for the same reason. An order says
+ * what was sold; a journal entry is an accounting *statement about* that
+ * order. So: **never read a balance to make an operational decision.** Do not
+ * gate a payout on a ledger figure, do not refuse a refund because an account
+ * looks short — read the payout and the order. A projection that starts
+ * making decisions becomes a second source of truth, and then the two
+ * disagree with no way to say which is wrong.
+ *
+ * ## 🛑 Every entry is MACHINE-GENERATED from a business event
+ *
+ * This is the one constraint that makes the whole thing safe. If a human has
+ * to remember that a gateway fee is `Dr Bank Charges / Cr Bank`, it will
+ * eventually be posted the other way round; if the settlement ingest posts
+ * it, it cannot be. `sourceEvent` is REQUIRED and names the event, not the
+ * person — a hand-posted adjustment uses `"manual-journal"`, which is a
+ * distinguishable value precisely so the exception stays countable.
+ *
+ * ## 🛑 A correction is a REVERSING ENTRY, never an edit
+ *
+ * The invoice/credit-note rule, applied to the books. `journalEntries` rows
+ * are append-only: `reverse()` writes a NEW entry with the legs swapped and
+ * the two pointed at each other. An edit would silently rewrite a period a
+ * GST return has already been filed for, and nothing downstream could tell.
+ *
+ * ## 🛑 Money is DECIMAL RUPEES, matching every other money field here
+ *
+ * Rupees with two decimal places, like every other money field here. The
+ * 2026-05 migration moved the whole codebase off minor units and
+ * `audit-money-units` enforces it; a ledger in minor units would be the one
+ * place a reader has to remember a different scale, which is how a 100×
+ * error gets written (Root Cause #31).
+ */
+import type { BaseDocument } from "../../../_internal/shared/types/base-document";
+export declare const CHART_OF_ACCOUNTS_COLLECTION = "chartOfAccounts";
+export declare const JOURNAL_ENTRIES_COLLECTION = "journalEntries";
+export declare const ACCOUNTING_PERIODS_COLLECTION = "accountingPeriods";
+/**
+ * The five classical account types.
+ *
+ * Carried on the ACCOUNT rather than inferred from its code, because the
+ * normal-balance side and every report's sign convention derive from it —
+ * and a report that guesses the type from a code prefix breaks the first time
+ * somebody adds an account out of range.
+ */
+export type AccountType = "asset" | "liability" | "equity" | "income" | "expense";
+/**
+ * Which side INCREASES this account.
+ *
+ * Derived from `AccountType` by `normalBalanceFor`, never stored — a stored
+ * copy is a mirror that drifts the first time somebody types the wrong one
+ * (Root Cause #42), and the mapping is a fact about accounting rather than
+ * about this business.
+ */
+export type NormalBalance = "debit" | "credit";
+export declare function normalBalanceFor(type: AccountType): NormalBalance;
+export interface ChartAccountDocument extends BaseDocument {
+    /**
+     * Stable numeric code, e.g. `"1100"`. The id is `account-{code}`.
+     *
+     * 🛑 Codes are grouped by type in the conventional Indian small-business
+     * ranges (1xxx asset, 2xxx liability, 3xxx equity, 4xxx income, 5xxx
+     * expense) **so a CA can map them to Tally at a glance** — that is the
+     * entire reason for a numeric code rather than a slug. It is a convention
+     * for humans; nothing in the code derives `type` from the range, because a
+     * derivation would make adding an account outside it silently wrong.
+     */
+    code: string;
+    name: string;
+    type: AccountType;
+    /** A one-line note for whoever has to reconcile this against a bank statement. */
+    description?: string;
+    /**
+     * A closed account refuses new postings but keeps its history.
+     *
+     * Deliberately not a delete: an account with entries against it cannot be
+     * removed without orphaning them, and a closed row still has to appear in
+     * last year's trial balance.
+     */
+    isActive: boolean;
+}
+/**
+ * One side of one entry.
+ *
+ * 🛑 `debit` and `credit` are SEPARATE non-negative fields rather than one
+ * signed amount. A signed amount needs a sign convention, the convention
+ * differs per account type, and a reader then has to know the account's type
+ * to interpret the number — which is how a credit gets read as a debit. Two
+ * fields are unambiguous at the point of reading, which is where it matters.
+ *
+ * Exactly one of them is non-zero on any line; `assertBalanced` refuses both.
+ */
+export interface JournalLine {
+    accountCode: string;
+    debit: number;
+    credit: number;
+    /** Why this leg exists, for a human reading the entry a year later. */
+    memo?: string;
+    /**
+     * Who this leg is ABOUT, when that is a specific counterparty — a store for
+     * a seller payable, a vendor for a bill.
+     *
+     * Optional because most legs (bank, GST, sales) have no counterparty. Where
+     * it exists it is what makes a per-seller payable ageing possible without a
+     * separate ledger per store.
+     */
+    counterpartyId?: string;
+}
+/**
+ * What caused this entry. REQUIRED, and the closed list is the point.
+ *
+ * 🛑 `manual-journal` is a real member and must stay one. The alternative —
+ * letting a hand-posted entry claim an automated source — is how the "every
+ * entry is machine-generated" constraint stops being checkable. With it
+ * declared, "how many of our entries were typed by a person" is one query.
+ */
+export type JournalSourceEvent = "order-placed" | "order-delivered" | "order-refunded" | "payout-paid" | "settlement-ingest" | "expense-recorded" | "asset-purchased" | "opening-balance" | "manual-journal" | "reversal";
+export interface JournalEntryDocument extends BaseDocument {
+    /**
+     * The date the entry BELONGS TO, which is not when it was written.
+     *
+     * A settlement ingested on the 3rd for transactions on the 31st posts to
+     * the 31st. `createdAt` records when we learned; this records when it
+     * happened, and every report and the period lock read this one.
+     */
+    entryDate: Date;
+    /** `YYYY-MM`, derived from `entryDate` — the lock and the rollups key on it. */
+    period: string;
+    sourceEvent: JournalSourceEvent;
+    /**
+     * The record that caused this — an order id, a payout id, an expense id.
+     *
+     * Absent only for `opening-balance` and `manual-journal`, which have no
+     * causing record by definition. `verify-posting-rules` checks that pairing
+     * rather than trusting it.
+     */
+    sourceId?: string;
+    narration: string;
+    lines: JournalLine[];
+    /**
+     * Both totals, stored.
+     *
+     * 🛑 Redundant with `lines` ON PURPOSE, and this is the one place a mirror
+     * is right: a trial balance that had to sum every line of every entry is an
+     * unbounded read, and these two are written inside the same transaction
+     * that validated them. They cannot drift, because nothing can write an
+     * entry without going through `assertBalanced`.
+     */
+    totalDebit: number;
+    totalCredit: number;
+    /** Set on the entry this one reverses, and on the reversal, pointing both ways. */
+    reversedByEntryId?: string;
+    reversesEntryId?: string;
+}
+/**
+ * A period, and whether it is closed.
+ *
+ * Id is the period itself (`period-2026-10`), so the lock check is a single
+ * `get` by a key the caller already has — not a query.
+ */
+export interface AccountingPeriodDocument extends BaseDocument {
+    /** `YYYY-MM`. */
+    period: string;
+    status: "open" | "locked";
+    /** Set when locked — which GST return this period was filed under. */
+    lockedReason?: string;
+    lockedAt?: Date;
+    lockedByUid?: string;
+}
+export declare const LEDGER_FIELDS: {
+    readonly CODE: "code";
+    readonly TYPE: "type";
+    readonly IS_ACTIVE: "isActive";
+    readonly ENTRY_DATE: "entryDate";
+    readonly PERIOD: "period";
+    readonly SOURCE_EVENT: "sourceEvent";
+    readonly SOURCE_ID: "sourceId";
+    readonly STATUS: "status";
+};

package/dist/features/ledger/schemas/firestore.js

@@ -0,0 +1,69 @@
+/**
+ * `chartOfAccounts` + `journalEntries` — Part 4's double-entry books.
+ *
+ * ## 🛑 THE LEDGER IS A PROJECTION. Orders, payouts and expenses are truth.
+ *
+ * The same split `obligations` takes, and for the same reason. An order says
+ * what was sold; a journal entry is an accounting *statement about* that
+ * order. So: **never read a balance to make an operational decision.** Do not
+ * gate a payout on a ledger figure, do not refuse a refund because an account
+ * looks short — read the payout and the order. A projection that starts
+ * making decisions becomes a second source of truth, and then the two
+ * disagree with no way to say which is wrong.
+ *
+ * ## 🛑 Every entry is MACHINE-GENERATED from a business event
+ *
+ * This is the one constraint that makes the whole thing safe. If a human has
+ * to remember that a gateway fee is `Dr Bank Charges / Cr Bank`, it will
+ * eventually be posted the other way round; if the settlement ingest posts
+ * it, it cannot be. `sourceEvent` is REQUIRED and names the event, not the
+ * person — a hand-posted adjustment uses `"manual-journal"`, which is a
+ * distinguishable value precisely so the exception stays countable.
+ *
+ * ## 🛑 A correction is a REVERSING ENTRY, never an edit
+ *
+ * The invoice/credit-note rule, applied to the books. `journalEntries` rows
+ * are append-only: `reverse()` writes a NEW entry with the legs swapped and
+ * the two pointed at each other. An edit would silently rewrite a period a
+ * GST return has already been filed for, and nothing downstream could tell.
+ *
+ * ## 🛑 Money is DECIMAL RUPEES, matching every other money field here
+ *
+ * Rupees with two decimal places, like every other money field here. The
+ * 2026-05 migration moved the whole codebase off minor units and
+ * `audit-money-units` enforces it; a ledger in minor units would be the one
+ * place a reader has to remember a different scale, which is how a 100×
+ * error gets written (Root Cause #31).
+ */
+export const CHART_OF_ACCOUNTS_COLLECTION = "chartOfAccounts";
+export const JOURNAL_ENTRIES_COLLECTION = "journalEntries";
+export const ACCOUNTING_PERIODS_COLLECTION = "accountingPeriods";
+export function normalBalanceFor(type) {
+    return type === "asset" || type === "expense" ? "debit" : "credit";
+}
+export const LEDGER_FIELDS = {
+    CODE: "code",
+    TYPE: "type",
+    IS_ACTIVE: "isActive",
+    ENTRY_DATE: "entryDate",
+    PERIOD: "period",
+    SOURCE_EVENT: "sourceEvent",
+    SOURCE_ID: "sourceId",
+    STATUS: "status",
+};
+/*
+ * 🛑 `periodOf` LIVES IN `_internal/shared/features/ledger/posting.ts`, not
+ * here, and the reason is mechanical rather than taxonomic.
+ *
+ * `verify-posting-rules.mjs` imports the posting rules directly via Node's
+ * `--experimental-strip-types` so it exercises the shipped source rather
+ * than a build artefact (Root Cause #105). Type stripping erases
+ * `import type` entirely but cannot RESOLVE a runtime import — appkit source
+ * is written extensionless and the build adds `.js` — so a single runtime
+ * import in that file would make it unloadable and the audit would be a
+ * load-failure instead of a check.
+ *
+ * Deciding which period an entry belongs to is a posting rule anyway, and it
+ * is the one the audit most needs to exercise: a UTC derivation files every
+ * IST evening sale in the previous GST return.
+ */