@classytic/ledger 0.1.3

package/docs/reports.md

@@ -0,0 +1,154 @@
+# Reports
+
+All reports are generated from live aggregation pipelines — no cached balances. Multi-tenant isolation is enforced automatically.
+
+## Using via Engine
+
+```typescript
+const reports = accounting.createReports({ Account, JournalEntry });
+```
+
+All report methods accept:
+
+```typescript
+{
+  organizationId?: unknown;  // required in multi-tenant mode
+  dateOption: 'month' | 'quarter' | 'year' | 'custom';
+  dateValue: unknown;        // month: '2025-03', quarter: '2025-Q1', year: 2025, custom: { start, end }
+  filters?: Record<string, unknown>;  // dimension filters (see below)
+}
+```
+
+### Dimension Filters
+
+All reports accept an optional `filters` parameter for filtering by custom dimension fields on journal items:
+
+```typescript
+const bs = await reports.balanceSheet({
+  organizationId: orgId,
+  dateOption: 'year',
+  dateValue: 2025,
+  filters: {
+    'journalItems.departmentId': departmentId,
+    'journalItems.projectId': { $in: [proj1, proj2] },
+  },
+});
+```
+
+Filters are injected into aggregation `$match` stages after `$unwind`. Dangerous MongoDB operators (`$where`, `$expr`, `$function`, `$accumulator`, `$merge`, `$out`, `$unionWith`) are blocked by `buildItemFilters()`. Top-level `$`-prefixed keys are also blocked to prevent query injection.
+
+### Account Identity in Reports
+
+Reports use the **actual account row** for display names and codes, not the account type template. When `acc.name` or `acc.accountNumber` is set on the account document, that value is used. Falls back to `accountType.name` / `accountType.code` from the country pack when the account row doesn't have these fields.
+
+This means tenants with multiple accounts under one type (e.g. three bank accounts all typed as "1000-Cash") will see their distinct names in report output.
+
+## Trial Balance
+
+```typescript
+const tb = await reports.trialBalance({
+  organizationId: orgId,
+  dateOption: 'year',
+  dateValue: 2025,
+});
+```
+
+Three-column report: initial balance + current period activity + ending balance. Returns `TrialBalanceReport` with `rows: TrialBalanceRow[]` and `period`.
+
+## Balance Sheet
+
+```typescript
+const bs = await reports.balanceSheet({
+  organizationId: orgId,
+  dateOption: 'year',
+  dateValue: 2025,
+  businessName: 'Acme Corp',
+});
+```
+
+Returns `BalanceSheetReport` with `assets`, `liabilities`, `equity` categories, each containing groups of accounts. Net income is computed from income statement accounts for the fiscal year and injected into equity as retained earnings.
+
+## Income Statement
+
+```typescript
+const is = await reports.incomeStatement({
+  organizationId: orgId,
+  dateOption: 'quarter',
+  dateValue: '2025-Q1',
+});
+```
+
+Returns `IncomeStatementReport` with revenue, cost of sales, operating expenses, and net income.
+
+## General Ledger
+
+```typescript
+const gl = await reports.generalLedger({
+  organizationId: orgId,
+  dateOption: 'month',
+  dateValue: '2025-01',
+  accountId: optionalAccountId, // filter to single account
+});
+```
+
+Returns `GeneralLedgerReport` with per-account transaction listings and running balances.
+
+## Cash Flow
+
+```typescript
+const cf = await reports.cashFlow({
+  organizationId: orgId,
+  dateOption: 'year',
+  dateValue: 2025,
+});
+```
+
+Groups posted transactions by `cashFlowCategory` from the country pack's account type definitions. Returns `CashFlowReport` with three sections — Operating, Investing, Financing — and `netCashFlow`.
+
+**Scope and limitations:** The cash flow statement is derived from the `cashFlowCategory` assigned to account types in the country pack. It works by summing journal items posted to accounts that have a cash flow category defined. This is an **indirect method** classification — it does not perform direct method cash flow analysis. For the report to be meaningful, the country pack must assign `cashFlowCategory` values to the relevant account types.
+
+## Fiscal Period Close
+
+```typescript
+import { closeFiscalPeriod } from '@classytic/ledger';
+
+const result = await closeFiscalPeriod(
+  { AccountModel, JournalEntryModel, FiscalPeriodModel, country, orgField },
+  { periodId, organizationId, closedBy: 'admin' },
+);
+// result: { periodId, netIncome, closingEntryId, accountsClosed, closedAt }
+```
+
+- Zeroes all income/expense account balances via a `YEAR_END` closing journal entry
+- Transfers net income to retained earnings (default code: `3660`, configurable via `retainedEarningsCode`)
+- Marks period as `closed: true`
+- Atomic by default (internal transaction)
+
+## Fiscal Period Reopen
+
+```typescript
+import { reopenFiscalPeriod } from '@classytic/ledger';
+
+const result = await reopenFiscalPeriod(
+  { JournalEntryModel, FiscalPeriodModel, orgField },
+  { periodId, organizationId, reopenedBy: 'admin' },
+);
+// result: { periodId, deletedEntryId, reopenedAt }
+```
+
+- Validates no later period is already closed (cascade protection)
+- Deletes the closing journal entry
+- Records audit trail (`reopenedAt`, `reopenedBy`)
+
+## Using Standalone Functions
+
+Reports can also be used without the engine:
+
+```typescript
+import { generateTrialBalance } from '@classytic/ledger/reports';
+
+const tb = await generateTrialBalance(
+  { AccountModel, JournalEntryModel, country, orgField, fiscalYearStartMonth },
+  { organizationId, dateOption: 'year', dateValue: 2025, filters: { 'journalItems.departmentId': deptId } },
+);
+```

package/docs/repositories.md

@@ -0,0 +1,239 @@
+# Repositories
+
+Repository wiring adds domain methods onto mongokit `Repository` instances.
+
+## Journal Entry Repository
+
+### Recommended: Engine Factory (secure by default)
+
+```typescript
+import { createRepository } from '@classytic/mongokit';
+
+const journalRepo = accounting.createJournalEntryRepository(
+  createRepository,
+  { JournalEntryModel: JournalEntry, AccountModel: Account, FiscalPeriodModel: FiscalPeriod },
+);
+```
+
+This creates a repository with double-entry validation, account existence + tenant integrity checks, fiscal lock enforcement, idempotency (when enabled), and wired domain methods — all configured securely from the engine's settings.
+
+### Manual Wiring (advanced)
+
+If you need custom plugin ordering or additional plugins:
+
+```typescript
+import { createRepository } from '@classytic/mongokit';
+import { doubleEntryPlugin, fiscalLockPlugin } from '@classytic/ledger';
+
+const journalRepo = createRepository(JournalEntry, [
+  doubleEntryPlugin({
+    JournalEntryModel: JournalEntry,
+    AccountModel: Account,       // required — fail-closed on posted creates
+    orgField: 'business',        // validates tenant-account integrity
+  }),
+  fiscalLockPlugin({ FiscalPeriodModel: FiscalPeriod, JournalEntryModel: JournalEntry, orgField: 'business' }),
+]);
+
+accounting.wireJournalEntryRepository(journalRepo, JournalEntry);
+```
+
+> **Important:** `AccountModel` is required. The double-entry plugin will throw on posted creates if `AccountModel` is not provided.
+
+### `repo.post(id, orgId?, options?)`
+
+Transitions a draft entry to posted state.
+
+```typescript
+const posted = await journalRepo.post(entryId, orgId);
+
+// With strictness options
+const posted = await journalRepo.post(entryId, orgId, { actorId: userId });
+```
+
+**Validates:**
+- Entry exists and belongs to org (multi-tenant)
+- Entry is in `draft` state
+- At least 2 journal items
+- Every item has a valid account
+- Every item has debit or credit > 0 (not both)
+- Total debits === total credits (exact integer match)
+- `actorId` is present (when `strictness.requireActor` enabled)
+- `approvedBy` AND `approvedAt` are set (when `strictness.requireApproval` enabled)
+
+**Options:** `{ session?: ClientSession, actorId?: unknown }`
+
+### `repo.unpost(id, orgId?, options?)`
+
+Transitions a posted entry back to draft state, allowing re-editing.
+
+```typescript
+const draft = await journalRepo.unpost(entryId, orgId);
+```
+
+**Behavior:**
+- Sets state to `draft`, clears `reversed`/`reversedBy` flags
+- Disabled when `strictness.immutable` is enabled (throws error)
+
+**Options:** `{ session?: ClientSession, actorId?: unknown }`
+
+### `repo.archive(id, orgId?, options?)`
+
+Archives a draft entry (draft → archived). Used to discard unneeded drafts without deleting them, preserving the audit trail.
+
+```typescript
+const archived = await journalRepo.archive(entryId, orgId);
+```
+
+**Behavior:**
+- Only `draft` entries can be archived (posted and already-archived entries are rejected)
+- Sets state to `archived` and updates `stateChangedAt`
+- Archived entries do not appear in reports (reports filter `state: 'posted'`)
+
+**Options:** `{ session?: ClientSession, actorId?: unknown }`
+
+### `repo.reverse(id, orgId?, options?)`
+
+Creates a mirror entry with flipped debits/credits. Marks the original as reversed.
+
+```typescript
+const { original, reversal } = await journalRepo.reverse(entryId, orgId);
+
+// With actor tracking
+const { original, reversal } = await journalRepo.reverse(entryId, orgId, { actorId: userId });
+```
+
+**Behavior:**
+- Creates a new `posted` entry with swapped debit/credit on each line
+- **Preserves all dimension fields** (departmentId, projectId, locationId, etc.) on reversal items
+- Sets `reversed: true` and `reversedBy` on the original
+- Sets `reversalOf` on the reversal entry
+- Stamps `postedBy` on reversal and `reversedByUser` on original (when `actorId` provided)
+- Routes through `repository.create()` so all plugins (fiscal-lock, double-entry) run
+- Atomic by default (internal transaction). Falls back to non-atomic on standalone MongoDB
+
+**Options:** `{ session?: ClientSession, reversalDate?: Date, actorId?: unknown }`
+
+### `repo.duplicate(id, orgId?, options?)`
+
+Creates a copy of an entry as a new draft.
+
+```typescript
+const copy = await journalRepo.duplicate(entryId, orgId);
+```
+
+**Behavior:**
+- Copies journal type, label, and all journal items as a new `draft`
+- **Preserves all dimension fields** (departmentId, projectId, locationId, etc.) on duplicated items
+- Does NOT copy `_id`, `id`, `referenceNumber`, `state`, or reversal flags
+- Sets date to today, prefixes label with "Copy of"
+- Routes through `repository.create()` so all plugins run
+
+**Options:** `{ session?: ClientSession }`
+
+### Posted-Entry Protection
+
+The double-entry plugin blocks direct modifications to posted entries through `repository.update()`:
+- Blocks any field change on a posted entry except idempotent `state: 'posted'`
+- Blocks any state transition away from `posted` (e.g. `{ state: 'draft' }`) via the update path
+
+To correct a posted entry, use `reverse()` to create a correcting entry. When `strictness.immutable` is **not** enabled, `unpost()` is also available to transition back to draft for re-editing. When `strictness.immutable` is enabled, `unpost()` is disabled and `reverse()` is the only correction path.
+
+### Strictness Configuration
+
+When the engine is configured with `strictness`, all domain methods enforce additional rules:
+
+```typescript
+const accounting = createAccountingEngine({
+  // ...
+  strictness: {
+    immutable: true,      // unpost() disabled — correction only via reverse()
+    requireActor: true,   // actorId required on post/reverse/unpost
+    requireApproval: true, // approvedBy + approvedAt required before posting
+  },
+});
+```
+
+| Rule | Effect |
+|---|---|
+| `immutable` | `unpost()` throws. Only `reverse()` can correct posted entries. |
+| `requireActor` | `post()`, `reverse()`, `unpost()` require `options.actorId`. |
+| `requireApproval` | `post()` requires both `approvedBy` and `approvedAt` to be set on the entry before it can be posted. |
+
+## Account Repository
+
+```typescript
+const accountRepo = createRepository(Account, []);
+accounting.wireAccountRepository(accountRepo, Account);
+```
+
+### `repo.seedAccounts(orgId, options?)`
+
+Seeds standard posting accounts from the country pack for an organization.
+
+```typescript
+const { created, skipped } = await accountRepo.seedAccounts(orgId);
+```
+
+- Deduplicates by `accountNumber` (not `accountTypeCode`)
+- Only creates posting accounts (not groups or totals)
+- Sets `accountNumber = code` and `name = typeName` from country pack
+
+**Options:** `{ session?: ClientSession }`
+
+### `repo.bulkCreate(accounts, orgId)`
+
+Bulk creates accounts with validation and skip-if-exists logic.
+
+```typescript
+const result = await accountRepo.bulkCreate([
+  { accountTypeCode: '1000', accountNumber: 'CASH-001', name: 'Main Cash' },
+  { accountTypeCode: '1000', accountNumber: 'CASH-002', name: 'Petty Cash' },
+], orgId);
+```
+
+**Returns:**
+```typescript
+{
+  summary: { total, created, skipped, errors },
+  created: [...],
+  skipped: [...],
+  errors: [...]
+}
+```
+
+- Validates `accountTypeCode` against country pack (must be a posting account)
+- Single batch query for dedup (no N+1)
+- `ordered: false` on insertMany for concurrent safety
+- `accountNumber` defaults to `accountTypeCode` if omitted
+- `name` defaults to country pack type name if omitted
+
+## Multi-Tenant Enforcement
+
+When `orgField` is configured, `post()`, `reverse()`, `duplicate()`, and `unpost()` require `orgId`. Calling without it throws:
+
+```
+organizationId is required when multi-tenant mode is configured
+```
+
+This is fail-closed: unscoped queries are blocked, not silently allowed.
+
+## Session Management
+
+`reverse()` and fiscal operations use shared session helpers:
+
+```typescript
+import { acquireSession, finalizeSession } from '@classytic/ledger';
+```
+
+- **With replica set:** Creates internal transaction, commits on success, aborts on error
+- **Standalone MongoDB:** Detects topology proactively, falls back to non-atomic with a warning
+- **External session:** Pass `{ session }` in options to join a caller-managed transaction
+
+## What the ledger does NOT do
+
+The ledger provides the core accounting engine — double-entry posting, validation, and reporting. It does **not** implement:
+
+- **Subledger business logic** — invoice workflows, inventory costing, payroll calculations. These belong in your app layer or dedicated subledger packages. See [Subledger Integration](subledger-integration.md) for the contract pattern.
+- **Account resolution** — mapping subledger codes to account ObjectIds. The app layer resolves account references before calling `repository.create()`.
+- **Approval workflows** — the ledger enforces that `approvedBy`/`approvedAt` are set (when `requireApproval` is enabled), but the approval UI and routing logic belong to the app.
+- **Tax calculation** — the ledger stores `taxDetails` on journal items as an audit trail, but tax computation (rates, jurisdiction rules) belongs to the country pack or tax engine.

package/docs/schemas.md

@@ -0,0 +1,146 @@
+# Schemas
+
+Schema factories create Mongoose schemas configured for your engine. They handle multi-tenant fields, indexes, and validation automatically.
+
+## Account Schema
+
+```typescript
+const AccountSchema = accounting.createAccountSchema({
+  indexes: true,        // default
+  extraFields: {},      // merge additional fields
+  extraIndexes: [],     // add custom indexes
+});
+const Account = mongoose.model('Account', AccountSchema);
+```
+
+### Fields
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `accountTypeCode` | String | Yes | Classification code from country pack (e.g. GIFI code) |
+| `accountNumber` | String | Yes | Unique business-facing identifier per org |
+| `name` | String | Yes | User-facing display name |
+| `active` | Boolean | No | Default `true` |
+| `isCashAccount` | Boolean | No | Default `false`. Used by cash flow report |
+| `{orgField}` | ObjectId | Multi-tenant only | Organization reference |
+
+### Indexes (when enabled)
+
+- `(orgField, accountNumber)` — unique per org
+- `(orgField, accountTypeCode)` — non-unique, for classification queries
+
+### Validation
+
+- `accountTypeCode` is validated against the country pack on save
+- Pre-validate hook auto-populates `accountNumber` (from `accountTypeCode`) and `name` (from country pack type name) if not explicitly set
+
+## Journal Entry Schema
+
+```typescript
+const JournalEntrySchema = accounting.createJournalEntrySchema('Account', {
+  autoReference: true,  // auto-generate reference numbers
+  textSearch: true,     // text index on reference + label
+  extraItemFields: {    // custom dimension fields on journal items
+    departmentId: { type: mongoose.Schema.Types.ObjectId, ref: 'Department' },
+    projectId: { type: mongoose.Schema.Types.ObjectId, ref: 'Project' },
+  },
+});
+const JournalEntry = mongoose.model('JournalEntry', JournalEntrySchema);
+```
+
+### Fields
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `journalType` | String | Yes | One of: `GENERAL`, `SALES`, `PURCHASE`, `CASH_RECEIPT`, `CASH_DISBURSEMENT`, `PAYROLL`, `ADJUSTMENT`, `YEAR_END`, `MISC` |
+| `referenceNumber` | String | Auto | Auto-generated (e.g. `GJ-0001`). Unique per org |
+| `label` | String | No | Description/memo |
+| `date` | Date | No | Defaults to `new Date()` |
+| `state` | String | No | `draft` (default), `posted`, or `archived` |
+| `stateChangedAt` | Date | No | Set when state changes |
+| `journalItems` | Array | Yes | Embedded items (see below) |
+| `totalDebit` | Number | No | Synced by double-entry plugin |
+| `totalCredit` | Number | No | Synced by double-entry plugin |
+| `reversed` | Boolean | No | Set by `reverse()` |
+| `reversedBy` | ObjectId | No | Points to reversal entry |
+| `reversalOf` | ObjectId | No | Points to original entry (on the reversal) |
+| `{orgField}` | ObjectId | Multi-tenant only | Organization reference |
+
+**Conditional fields** (added when engine config enables them):
+
+| Field | Condition | Description |
+|---|---|---|
+| `createdBy` | `audit.trackActor` | Actor who created the entry |
+| `postedBy` | `audit.trackActor` | Actor who posted the entry |
+| `reversedByUser` | `audit.trackActor` | Actor who reversed the entry |
+| `approvedBy` | `audit.trackActor` or `strictness.requireApproval` | Actor who approved the entry |
+| `approvedAt` | `audit.trackActor` or `strictness.requireApproval` | Timestamp of approval |
+| `idempotencyKey` | `idempotency: true` | Unique key for at-most-once posting (sparse index) |
+
+### Journal Item Sub-document
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `account` | ObjectId ref | Yes | Reference to Account model |
+| `label` | String | No | Line-level description |
+| `date` | Date | No | Line-level date override |
+| `debit` | Number | No | Default 0, non-negative integer (cents) |
+| `credit` | Number | No | Default 0, non-negative integer (cents) |
+| `taxDetails` | Array | No | `[{ taxCode, taxName }]` audit trail |
+
+**Custom dimension fields:** Pass `extraItemFields` in schema options to add fields like `departmentId`, `projectId`, `locationId` to the journal item sub-document. These fields are preserved through `duplicate()` and `reverse()` operations and can be filtered on in reports via the `filters` parameter.
+
+### Validation Rules
+
+- Each line must have debit OR credit > 0, not both (mutual exclusion)
+- Amounts must be non-negative integers (cents). Use `Money.fromDecimal()` to convert from dollars at the API boundary
+- Posted entries must have >= 2 items and sum(debits) === sum(credits)
+
+## Fiscal Period Schema
+
+```typescript
+const FiscalPeriodSchema = accounting.createFiscalPeriodSchema();
+const FiscalPeriod = mongoose.model('FiscalPeriod', FiscalPeriodSchema);
+```
+
+### Fields
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `name` | String | Yes | e.g. "FY 2025" |
+| `startDate` | Date | Yes | Period start |
+| `endDate` | Date | Yes | Period end |
+| `closed` | Boolean | No | Default `false` |
+| `closedAt` | Date | No | Timestamp of closing |
+| `closedBy` | String | No | User who closed |
+| `closingEntryId` | ObjectId | No | Reference to YEAR_END journal entry |
+| `reopenedAt` | Date | No | Timestamp of last reopen |
+| `reopenedBy` | String | No | User who reopened |
+
+### Overlap Protection
+
+The schema includes a `pre('validate')` hook that prevents overlapping date ranges within a tenant. If a new period's date range overlaps with an existing period (same org in multi-tenant mode), validation fails with a descriptive error message.
+
+This prevents fiscal lock/close from becoming inconsistent — two overlapping periods could otherwise both claim authority over the same date range.
+
+### Schema Options
+
+All schema factories accept:
+
+```typescript
+interface SchemaOptions {
+  indexes?: boolean;              // default true
+  extraFields?: Record<string, unknown>;
+  extraIndexes?: Array<{ fields: Record<string, 1 | -1>; options?: Record<string, unknown> }>;
+}
+```
+
+Journal entry schema also accepts:
+
+```typescript
+interface JournalSchemaOptions extends SchemaOptions {
+  autoReference?: boolean;        // default true
+  textSearch?: boolean;           // default true
+  extraItemFields?: Record<string, unknown>;  // custom fields on journal items
+}
+```