@classytic/ledger 0.5.1 → 0.6.0

package/dist/index-BthGypsI.d.mts

@@ -0,0 +1,228 @@
+import { t as AccountType } from "./core-BkGjuVZj.mjs";
+
+//#region src/country/index.d.ts
+/**
+ * A single destination for a fraction of a tax amount. A `TaxCode` can declare
+ * multiple repartition lines so that one tax percentage produces multiple
+ * journal items (e.g. reverse-charge VAT books +100% to payable AND -100% to
+ * recoverable in the same entry). Factors sum across lines and the engine
+ * enforces balance inside the existing double-entry plugin.
+ *
+ * `accountRole` is a logical name looked up against the consumer's chart of
+ * accounts via the country pack's `resolveRepartitionAccount` helper — NOT a
+ * direct ObjectId, so the same country pack can drive any consumer's accounts.
+ * `gridCode` flows through to `taxDetails` for regulatory reporting (CRA
+ * schedule lines, HMRC VAT boxes, NBR Mushak grid, etc.).
+ */
+interface TaxRepartitionLine {
+  /**
+   * Signed multiplier applied to the base tax amount. Use `1` for the
+   * "normal" line, `-1` for a mirror (e.g. recoverable reverse-charge).
+   * Fractions (e.g. `0.5`) are allowed for split-destination taxes.
+   */
+  readonly factor: number;
+  /**
+   * Logical role resolved against the country pack. Standard roles:
+   *   - `'collected'` — tax collected from customer (liability)
+   *   - `'recoverable'` — tax paid to supplier, recoverable (asset)
+   *   - `'expense'` — tax paid, non-recoverable (expense)
+   *   - `'transition'` — temporary holding account for cash-basis exigibility
+   * Consumers can define custom roles and wire them in their country pack.
+   */
+  readonly accountRole: string;
+  /** Optional reporting grid code — propagated to `taxDetails` on the item. */
+  readonly gridCode?: string | number;
+  /** Optional human label surfaced in UI and audit trails. */
+  readonly label?: string;
+  /** Optional: only apply on these document types. Default: all. */
+  readonly documentTypes?: readonly ('invoice' | 'refund' | 'payment')[];
+}
+/**
+ * When a tax is realized into the books:
+ *   - `'accrual'` (default) — books at entry time (what 0.5.x did for everything)
+ *   - `'cash'` — books into a transition account at entry time, moves to the
+ *     real tax account when the invoice is reconciled against a payment
+ */
+type TaxExigibility = 'accrual' | 'cash';
+interface TaxCode {
+  readonly code: string;
+  readonly name: string;
+  readonly taxType: string;
+  readonly rate: number;
+  readonly direction: 'collected' | 'recoverable' | 'paid';
+  readonly province?: string;
+  readonly reportLines?: readonly number[];
+  readonly description: string;
+  readonly active: boolean;
+  /**
+   * Multi-line repartition — when present, `createRepartitionTaxGenerator`
+   * produces one journal item per line. When absent, the tax behaves as a
+   * single-line tax routed to the `direction`-implied account.
+   */
+  readonly repartition?: readonly TaxRepartitionLine[];
+  /**
+   * Accrual (default) or cash-basis exigibility. When `'cash'`, requires
+   * a `transition` repartition role in `repartition` OR a country-pack
+   * default transition account.
+   */
+  readonly exigibility?: TaxExigibility;
+}
+/**
+ * Declarative template that tells the engine which journals to seed for a
+ * new organization. Consumers call
+ * `engine.repositories.journals.seedDefaults(orgId)` which reads these from
+ * the country pack and creates one Journal document per template.
+ *
+ * Journals are *optional* — if a consumer never seeds journals, the legacy
+ * `journalType` enum on a journal entry still works. Consumers opting in
+ * get per-journal sequence prefixes, restricted payment methods, bank
+ * statement sources, etc.
+ */
+interface JournalTemplate {
+  /** Short stable identifier — e.g. `'SALES'`, `'PURCHASE'`, `'BANK'`. */
+  readonly code: string;
+  /** Display name. */
+  readonly name: string;
+  /**
+   * One of the registered `JOURNAL_TYPES` codes — connects this journal to
+   * the engine's reference-number generator and posting-contract system.
+   */
+  readonly journalType: string;
+  /** Reference-number prefix — defaults to `code` when omitted. */
+  readonly sequencePrefix?: string;
+  /** First sequence number — defaults to `1`. */
+  readonly sequenceStartNum?: number;
+  /**
+   * Logical source — pure ledgering (`'general'`), sale-side docs (`'sale'`),
+   * purchase-side docs (`'purchase'`), cash/bank movement (`'bank'`, `'cash'`).
+   * Drives default locks (sale-lock, purchase-lock) when they're wired.
+   */
+  readonly kind?: 'general' | 'sale' | 'purchase' | 'bank' | 'cash' | string;
+  /** Optional default debit/credit account roles for quick data entry. */
+  readonly defaultDebitAccountRole?: string;
+  readonly defaultCreditAccountRole?: string;
+}
+interface TaxCodesByRegion {
+  readonly [region: string]: readonly string[];
+}
+interface TaxReportLine {
+  readonly line: number | string;
+  readonly name: string;
+  readonly description: string;
+  readonly type: 'input' | 'calculated' | 'manual';
+  readonly calculate?: (data: Record<string | number, number>) => number;
+  readonly section: string;
+}
+interface TaxReportTemplate {
+  readonly name: string;
+  readonly lines: Readonly<Record<string | number, TaxReportLine>>;
+  calculate(inputData: Record<string | number, number>, manualData?: Record<string | number, number>): Record<string | number, number>;
+  summarize(calculated: Record<string | number, number>): Record<string, unknown>;
+}
+interface CountryPack {
+  /** ISO 3166-1 alpha-2 code (e.g., 'CA', 'US', 'GB') */
+  readonly code: string;
+  /** Country name */
+  readonly name: string;
+  /** Default currency code */
+  readonly defaultCurrency: string;
+  /**
+   * Full chart of accounts template — flat array of account type definitions.
+   * Includes both regular accounts and virtual tax sub-accounts.
+   */
+  readonly accountTypes: readonly AccountType[];
+  /** Tax codes indexed by code string */
+  readonly taxCodes: Readonly<Record<string, TaxCode>>;
+  /** Tax codes grouped by region/province/state */
+  readonly taxCodesByRegion: TaxCodesByRegion;
+  /** Available regions (provinces/states) */
+  readonly regions: readonly string[];
+  /** Tax report template (e.g., CRA GST/HST return) */
+  readonly taxReport?: TaxReportTemplate;
+  /**
+   * Optional journal templates seeded per organization. When a consumer
+   * calls `engine.repositories.journals.seedDefaults(orgId)`, the engine
+   * creates one Journal document per template. See `JournalTemplate`.
+   */
+  readonly journalTemplates?: readonly JournalTemplate[];
+  /**
+   * Map a logical `accountRole` string (e.g. `'collected'`, `'recoverable'`,
+   * `'transition'`) to the actual account-type code for this country. The
+   * repartition tax generator calls this for each repartition line so the
+   * same tax definition can resolve different account codes in BD vs CA.
+   *
+   * Default behavior when omitted: maps `'collected'` → account with
+   * direction='collected' in `taxCodes`, `'recoverable'` →
+   * direction='recoverable', etc. Consumers override for custom roles.
+   */
+  readonly resolveTaxRepartitionAccountCode?: (role: string, taxCode: TaxCode) => string | undefined;
+  /**
+   * The retained earnings account code — the account that holds accumulated
+   * retained earnings (e.g. '3600' CA, '3310' BD).
+   *
+   * On the balance sheet, this account is excluded from normal equity grouping
+   * and its balance is folded into the computed "Retained Earnings" section
+   * (opening RE = RE account balance + prior-year unclosed P&L).
+   *
+   * Inspired by Odoo's `equity_unaffected` account type.
+   */
+  readonly retainedEarningsAccountCode?: string;
+  /**
+   * Display code for the "Previous Years Retained Earnings" line on the
+   * balance sheet (e.g. '3660' for CA GIFI). Defaults to retainedEarningsAccountCode.
+   */
+  readonly retainedEarningsDisplayCode?: string;
+  /** Display code for current year net income line (e.g. '3680' CA, '3311' BD) */
+  readonly currentYearEarningsCode?: string;
+  /** Group label code used to identify Cost of Sales in the income statement */
+  readonly cogsGroupCode?: string;
+  /** Override default English report section names */
+  readonly reportLabels?: {
+    readonly assets?: string;
+    readonly liabilities?: string;
+    readonly equity?: string;
+    readonly revenue?: string;
+    readonly expenses?: string;
+  };
+  /** Get all account types that can be posted to (not groups, not totals) */
+  getPostingAccountTypes(): readonly AccountType[];
+  /** Get account type by code */
+  getAccountType(code: string): AccountType | undefined;
+  /** Validate an account type code exists */
+  isValidAccountType(code: string): boolean;
+  /** Check if an account type can receive postings */
+  isPostingAccount(code: string): boolean;
+  /** Get tax codes for a specific region */
+  getTaxCodesForRegion(region: string): TaxCode[];
+  /** Flatten hierarchical accounts (if needed) */
+  flattenAccountTypes(): readonly AccountType[];
+}
+interface CountryPackInput {
+  code: string;
+  name: string;
+  defaultCurrency: string;
+  accountTypes: readonly AccountType[];
+  taxCodes: Readonly<Record<string, TaxCode>>;
+  taxCodesByRegion: TaxCodesByRegion;
+  regions: readonly string[];
+  taxReport?: TaxReportTemplate;
+  journalTemplates?: readonly JournalTemplate[];
+  resolveTaxRepartitionAccountCode?: (role: string, taxCode: TaxCode) => string | undefined;
+  retainedEarningsAccountCode?: string;
+  retainedEarningsDisplayCode?: string;
+  currentYearEarningsCode?: string;
+  cogsGroupCode?: string;
+  reportLabels?: {
+    readonly assets?: string;
+    readonly liabilities?: string;
+    readonly equity?: string;
+    readonly revenue?: string;
+    readonly expenses?: string;
+  };
+}
+/**
+ * Factory to create a CountryPack with auto-generated helper methods.
+ */
+declare function defineCountryPack(input: CountryPackInput): CountryPack;
+//#endregion
+export { TaxCodesByRegion as a, TaxReportLine as c, TaxCode as i, TaxReportTemplate as l, CountryPackInput as n, TaxExigibility as o, JournalTemplate as r, TaxRepartitionLine as s, CountryPack as t, defineCountryPack as u };

package/dist/index.d.mts

@@ -1,10 +1,10 @@
 import { _ as TaxMetadata, a as Cents, c as DateRange, d as JournalType, f as MainType, g as TaxDetail, h as StatementType, i as CategoryKey, l as EntryState, m as ObjectId, n as CashFlowCategory, o as Currency, p as NormalBalance, s as DateOption, t as AccountType, u as JournalItem, v as TotalAccountOp } from "./core-BkGjuVZj.mjs";
 import { S as isValidCategory, a as getJournalTypeCodes, b as isBalanceSheet, c as CURRENCIES, d as isValidCurrency, f as CATEGORIES, i as getJournalType, l as getCurrency, n as JOURNAL_TYPES, o as isValidJournalType, p as CATEGORY_KEYS, r as getCustomJournalTypes, s as registerJournalType, t as JOURNAL_CODES, u as getMinorUnit, x as isIncomeStatement, y as getNormalBalance } from "./journals-C50E9mpo.mjs";
-import { a as TaxReportLine, i as TaxCodesByRegion, n as CountryPackInput, o as TaxReportTemplate, r as TaxCode, s as defineCountryPack, t as CountryPack } from "./index-GmfEFxVn.mjs";
+import { a as TaxCodesByRegion, c as TaxReportLine, i as TaxCode, l as TaxReportTemplate, n as CountryPackInput, o as TaxExigibility, r as JournalTemplate, s as TaxRepartitionLine, t as CountryPack, u as defineCountryPack } from "./index-BthGypsI.mjs";
 import { _ as PopulatedJournalEntry, a as exportToCsv, h as FlatJournalRow, i as quickbooksFieldMap, m as ExportFieldMap, p as ExportField, r as universalFieldMap, t as flattenJournalEntries } from "./index-D1ZjgVxn.mjs";
 import { Money, abs, add, allocate, equals, format, formatPlain, fromDecimal, isNegative, isPositive, isValid, isZero, max, min, multiply, negate, parseCents, percentage, round, splitTaxExclusive, splitTaxInclusive, subtract, toDecimal } from "./money.mjs";
-import { $ as AgedBucketConfig, A as BudgetVsActualReport, B as IncomeStatementReport, C as DimensionBreakdownReport, D as generateCashFlow, F as BalanceSheetReport, G as TaxReport, H as ReportAccount, I as CashFlowReport, J as TrialBalanceRow, K as TaxReturnSummary, L as CashFlowSection, M as generateBudgetVsActual, O as BudgetVsActualOptions, P as generateBalanceSheet, Q as AgedBalanceRow, R as GeneralLedgerAccount, S as DimensionBreakdownParams, T as generateDimensionBreakdown, U as ReportCategory, V as LedgerEntry, W as ReportGroup, X as AgedBalanceParams, Y as AgedBalanceOptions, Z as AgedBalanceReport, a as RevaluationReport, b as reopenFiscalPeriod, c as RevaluationRate, d as computeRevaluation, et as DEFAULT_BUCKETS, h as generateGeneralLedger, i as RevaluationParams, j as BudgetVsActualRow, k as BudgetVsActualParams, l as RevaluationResult, n as generateTrialBalance, nt as Logger, o as generateRevaluation, p as generateIncomeStatement, q as TrialBalanceReport, r as RevaluationOptions, rt as defaultLogger, s as AccountForeignBalance, tt as generateAgedBalance, u as buildRevaluationEntry, w as DimensionBreakdownRow, x as DimensionBreakdownOptions, y as closeFiscalPeriod, z as GeneralLedgerReport } from "./trial-balance-BZ7yOOFD.mjs";
-import { c as dateLockPlugin, i as fiscalLockPlugin, n as idempotencyPlugin, o as doubleEntryPlugin } from "./idempotency.plugin-WcQLZU9n.mjs";
+import { $ as TrialBalanceRow, A as generateDimensionBreakdown, B as BalanceSheetReport, D as DimensionBreakdownParams, E as DimensionBreakdownOptions, F as BudgetVsActualReport, G as IncomeStatementReport, H as CashFlowSection, I as BudgetVsActualRow, J as ReportCategory, K as LedgerEntry, L as generateBudgetVsActual, M as generateCashFlow, N as BudgetVsActualOptions, O as DimensionBreakdownReport, P as BudgetVsActualParams, Q as TrialBalanceReport, T as reopenFiscalPeriod, U as GeneralLedgerAccount, V as CashFlowReport, W as GeneralLedgerReport, X as TaxReport, Y as ReportGroup, Z as TaxReturnSummary, a as RevaluationReport, at as DEFAULT_BUCKETS, b as generateGeneralLedger, c as RevaluationRate, ct as defaultLogger, d as computeRevaluation, et as AgedBalanceOptions, f as PartnerLedgerLine, g as generatePartnerLedger, h as PartnerLedgerReport, i as RevaluationParams, it as AgedBucketConfig, k as DimensionBreakdownRow, l as RevaluationResult, m as PartnerLedgerParams, n as generateTrialBalance, nt as AgedBalanceReport, o as generateRevaluation, ot as generateAgedBalance, p as PartnerLedgerOptions, q as ReportAccount, r as RevaluationOptions, rt as AgedBalanceRow, s as AccountForeignBalance, st as Logger, tt as AgedBalanceParams, u as buildRevaluationEntry, v as generateIncomeStatement, w as closeFiscalPeriod, z as generateBalanceSheet } from "./trial-balance-s92GEvRR.mjs";
+import { A as JournalEntryRepository, B as SeedResult, D as AccountRepository, E as creditLimitPlugin, F as PostOptions, I as ReconciliationRepository, L as ReverseOptions, M as JournalRepository, N as MatchInput, O as BulkCreateInput, P as OpenItem, R as ReverseResult, S as fxRealizationPlugin, T as CreditLimitPluginOptions, _ as LockResolver, a as DailyLockPluginOptions, b as idempotencyPlugin, c as dailyLockPlugin, d as PeriodResolverOptions, f as periodResolver, g as LockHit, h as LockAccountSelector, i as watermarkResolver, j as JournalItemRef, k as BulkCreateResult, l as fiscalLockPlugin, m as CreateLockPluginOptions, n as TaxLineInput, o as FiscalLockPluginOptions, p as createLockPlugin, r as WatermarkResolverOptions, s as TaxLockPluginOptions, t as TaxLineGenerator, u as taxLockPlugin, v as LockResolverContext, w as doubleEntryPlugin, x as FxRealizationPluginOptions, z as SeedOptions } from "./tax-hooks-BnVenul5.mjs";
 import { ClientSession, Connection, Model } from "mongoose";
 import { PaginationConfig, PluginType, Repository } from "@classytic/mongokit";
 
@@ -16,6 +16,7 @@ interface LedgerRepositoryPlugins {
   fiscalPeriod?: PluginType[];
   budget?: PluginType[];
   reconciliation?: PluginType[];
+  journal?: PluginType[];
 }
 /** Pagination caps per repository. Omit a key to use mongokit defaults. */
 interface LedgerPaginationConfig {
@@ -24,6 +25,7 @@ interface LedgerPaginationConfig {
   fiscalPeriod?: PaginationConfig;
   budget?: PaginationConfig;
   reconciliation?: PaginationConfig;
+  journal?: PaginationConfig;
 }
 /** Multi-tenant configuration */
 interface MultiTenantConfig {
@@ -101,6 +103,7 @@ interface ModelNames {
   fiscalPeriod?: string;
   budget?: string;
   reconciliation?: string;
+  journal?: string;
 }
 /** Main engine configuration */
 interface AccountingEngineConfig {
@@ -118,6 +121,7 @@ interface AccountingEngineConfig {
     fiscalPeriod?: SchemaOptions;
     budget?: SchemaOptions;
     reconciliation?: SchemaOptions;
+    journal?: SchemaOptions;
   };
   /** Country pack providing account types, tax codes, and templates */
   country: CountryPack;
@@ -159,6 +163,7 @@ interface LedgerModels {
   FiscalPeriod: Model<unknown>;
   Budget: Model<unknown>;
   Reconciliation: Model<unknown>;
+  Journal: Model<unknown>;
 }
 interface ResolvedModelNames {
   account: string;
@@ -166,110 +171,11 @@ interface ResolvedModelNames {
   fiscalPeriod: string;
   budget: string;
   reconciliation: string;
+  journal: string;
 }
 declare function resolveModelNames(overrides?: ModelNames): ResolvedModelNames;
-/**
- * Create (or reuse) all ledger models on the given connection.
- *
- * If a model with the same name is already registered on the connection,
- * the existing model is reused — this allows multiple engine instances
- * to share models and prevents "OverwriteModelError".
- */
 declare function createModels(connection: Connection, config: AccountingEngineConfig): LedgerModels;
 //#endregion
-//#region src/types/repositories.d.ts
-interface PostOptions {
-  session?: ClientSession | null;
-  /** Actor performing this operation (required when strictness.requireActor is enabled) */
-  actorId?: unknown;
-}
-interface ReverseOptions extends PostOptions {
-  /** Date for the reversal entry (defaults to now) */
-  reversalDate?: Date;
-}
-interface SeedOptions {
-  session?: ClientSession | null;
-}
-interface SeedResult {
-  created: number;
-  skipped: number;
-}
-interface BulkCreateInput {
-  accountTypeCode?: string;
-  accountNumber?: string;
-  name?: string;
-  active?: boolean;
-  isCashAccount?: boolean;
-}
-interface BulkCreateResult {
-  summary: {
-    total: number;
-    created: number;
-    skipped: number;
-    errors: number;
-  };
-  created: Array<Record<string, unknown>>;
-  skipped: Array<Record<string, unknown>>;
-  errors: Array<Record<string, unknown>>;
-}
-interface ReverseResult {
-  original: Record<string, unknown>;
-  reversal: Record<string, unknown>;
-}
-interface ReconcileParams {
-  accountId: unknown;
-  journalEntryIds: unknown[];
-  organizationId?: unknown;
-  note?: string;
-  session?: ClientSession;
-}
-/**
- * Journal Entry Repository — extends mongokit Repository with accounting domain methods.
- *
- * Inherits ALL Repository<TDoc> methods: create, getById, getAll, update,
- * delete, count, exists, distinct, aggregate, withTransaction, etc.
- */
-interface JournalEntryRepository<TDoc = unknown> extends Repository<TDoc> {
-  /** Post an entry (draft → posted). Validates items, balance, and accounts. */
-  post(id: unknown, orgId?: unknown, options?: PostOptions): Promise<Record<string, unknown>>;
-  /** Unpost an entry (posted → draft). Resets state for re-editing. */
-  unpost(id: unknown, orgId?: unknown, options?: PostOptions): Promise<Record<string, unknown>>;
-  /** Archive a draft entry (draft → archived). Preserves audit trail. */
-  archive(id: unknown, orgId?: unknown, options?: PostOptions): Promise<Record<string, unknown>>;
-  /** Duplicate an entry as a new draft. Copies items, type, and label. */
-  duplicate(id: unknown, orgId?: unknown, options?: PostOptions): Promise<Record<string, unknown>>;
-  /** Reverse a posted entry. Creates mirror entry with flipped debits/credits. */
-  reverse(id: unknown, orgId?: unknown, options?: ReverseOptions): Promise<ReverseResult>;
-}
-/**
- * Account Repository — extends mongokit Repository with seed and bulk operations.
- */
-interface AccountRepository<TDoc = unknown> extends Repository<TDoc> {
-  /** Seed standard posting accounts for an org from the country pack. */
-  seedAccounts(orgId: unknown, options?: SeedOptions): Promise<SeedResult>;
-  /** Bulk create accounts with validation and skip-if-exists logic. */
-  bulkCreate(accounts: BulkCreateInput[], orgId: unknown): Promise<BulkCreateResult>;
-}
-/**
- * Reconciliation Repository — extends mongokit Repository with bank reconciliation methods.
- */
-interface ReconciliationRepository<TDoc = unknown> extends Repository<TDoc> {
-  /** Reconcile journal entries for a specific account. */
-  reconcile(params: ReconcileParams): Promise<Record<string, unknown>>;
-  /** Remove a reconciliation record. */
-  unreconcile(params: {
-    reconciliationId: unknown;
-    organizationId?: unknown;
-  }): Promise<{
-    success: boolean;
-  }>;
-  /** Get unreconciled journal entries for an account. */
-  getUnreconciled(params: {
-    accountId: unknown;
-    organizationId?: unknown;
-  }): Promise<Record<string, unknown>[]>;
-}
-//#endregion
 //#region src/repositories/factory.d.ts
 interface LedgerRepositories {
   accounts: AccountRepository<unknown>;
@@ -277,6 +183,7 @@ interface LedgerRepositories {
   fiscalPeriods: Repository<unknown>;
   budgets: Repository<unknown>;
   reconciliations: ReconciliationRepository<unknown>;
+  journals: JournalRepository<unknown>;
 }
 /**
  * Build all ledger repositories with plugins + domain methods pre-wired.
@@ -656,6 +563,39 @@ declare class AccountingEngine {
 }
 declare function createAccountingEngine(config: AccountingEngineConfig): AccountingEngine;
 //#endregion
+//#region src/utils/repartition-tax.d.ts
+/**
+ * Resolves an `accountRole` (e.g. `'collected'`, `'recoverable'`,
+ * `'transition'`) into the actual account ObjectId for the consumer's
+ * chart of accounts. Implementations typically close over an account
+ * cache loaded per organization at engine start.
+ */
+type RepartitionAccountResolver = (role: string, taxCode: TaxCode, input: TaxLineInput) => unknown;
+interface RepartitionGeneratorOptions {
+  /** Country pack — provides tax codes and optional resolver. */
+  country: CountryPack;
+  /** Required: resolve role → account id in the consumer's chart. */
+  resolveAccount: RepartitionAccountResolver;
+  /**
+   * Document type — determines which repartition lines apply. A line
+   * with `documentTypes: ['invoice']` is skipped when this is `'refund'`.
+   * Defaults to `'invoice'`.
+   */
+  documentType?: 'invoice' | 'refund' | 'payment';
+}
+/**
+ * Build a `TaxLineGenerator` that expands each hit `taxCode` into one
+ * journal item per repartition line. Taxes without `repartition` fall
+ * back to a single-line generator using the direction-implied account.
+ */
+declare function createRepartitionTaxGenerator(options: RepartitionGeneratorOptions): TaxLineGenerator;
+/**
+ * Helper for packs that want the standard "role → account-type code"
+ * mapping without writing their own resolver. Returns the function you
+ * stuff into `CountryPackInput.resolveTaxRepartitionAccountCode`.
+ */
+declare function defaultResolveTaxRepartitionAccountCode(country: CountryPack): (role: string, tax: TaxCode) => string | undefined;
+//#endregion
 //#region src/utils/account-helpers.d.ts
 /**
  * Check if an account type is a virtual tax sub-account.
@@ -789,7 +729,12 @@ declare const Errors: {
   readonly notFound: (msg: string, fields?: ReadonlyArray<FieldError>) => AccountingError;
   readonly conflict: (msg: string, fields?: ReadonlyArray<FieldError>) => AccountingError;
   readonly immutable: (msg: string, fields?: ReadonlyArray<FieldError>) => AccountingError;
-  readonly fiscal: (msg: string, fields?: ReadonlyArray<FieldError>) => AccountingError;
+  /**
+   * Period/scope lock violation. Replaces the old `fiscal` factory — use the
+   * `scope` argument to distinguish fiscal / tax / daily / bank / etc. The
+   * resulting error code is `PERIOD_LOCKED_{SCOPE}` (e.g. `PERIOD_LOCKED_FISCAL`).
+   */
+  readonly locked: (scope: string, msg: string, fields?: ReadonlyArray<FieldError>) => AccountingError;
 };
 //#endregion
 //#region src/utils/filter-builder.d.ts
@@ -871,4 +816,4 @@ interface PostingResult {
   idempotencyKeys?: string[];
 }
 //#endregion
-export { type AccountCode, type AccountForeignBalance, type AccountRepository, type AccountSummary, type AccountType, AccountingEngine, type AccountingEngineConfig, AccountingError, type ActorContext, type AgedBalanceOptions, type AgedBalanceParams, type AgedBalanceReport, type AgedBalanceRow, type AgedBucketConfig, type AuditConfig, type BalanceSheetReport, type BudgetVsActualOptions, type BudgetVsActualParams, type BudgetVsActualReport, type BudgetVsActualRow, type BulkCreateInput, type BulkCreateResult, CATEGORIES, CATEGORY_KEYS, CURRENCIES, type CashFlowCategory, type CashFlowReport, type CashFlowSection, type CategoryKey, type Cents, type CountryPack, type CountryPackInput, type Currency, DEFAULT_BUCKETS, type DateOption, type DateRange, type DimensionBreakdownOptions, type DimensionBreakdownParams, type DimensionBreakdownReport, type DimensionBreakdownRow, type DimensionDefinition, type EntryState, Errors, type ExportField, type ExportFieldMap, type FieldError, type FiscalPeriodSummary, type FlatJournalRow, type GeneralLedgerAccount, type GeneralLedgerReport, type IncomeStatementReport, type IntrospectAPI, JOURNAL_CODES, JOURNAL_TYPES, type JournalEntryRepository, type JournalItem, type JournalSchemaOptions, type JournalType, type LedgerEntry, type LedgerModels, type LedgerPaginationConfig, type LedgerRepositories, type LedgerRepositoryPlugins, type Logger, type MainType, type ModelNames, Money, type MultiCurrencyConfig, type MultiTenantConfig, type NormalBalance, type PopulatedJournalEntry, type PostOptions, type PostingContract, type PostingResult, type ReconcileParams, type ReconciliationRepository, type RecordAPI, type RecordAdjustmentInput, type RecordAdjustmentLine, type RecordExpenseInput, type RecordOptions, type RecordPaymentInput, type RecordSaleInput, type RecordTransferInput, type ReportAccount, type ReportCategory, type ReportDescriptor, type ReportGroup, type ResolvedModelNames, type RevaluationOptions, type RevaluationParams, type RevaluationRate, type RevaluationReport, type RevaluationResult, type ReverseOptions, type ReverseResult, type SchemaOptions, type SeedOptions, type SeedResult, type Cents$1 as SemanticCents, type SessionResult, type StatementType, type StrictnessConfig, type SubledgerJournalItem, type SubledgerPostingInput, type TaxCode, type TaxCodesByRegion, type TaxDetail, type TaxInput, type TaxMetadata, type TaxReport, type TaxReportLine, type TaxReportTemplate, type TaxReturnSummary, type TotalAccountOp, type TrialBalanceReport, type TrialBalanceRow, acquireSession, add, allocate, buildAccountTypeMap, buildDimensionFields, buildDimensionIndexes, buildItemFilters, buildRevaluationEntry, calculateTotal, closeFiscalPeriod, computeEndingBalance, computeRevaluation, createAccountingEngine, createModels, createRepositories, dateLockPlugin, defaultLogger, defineCountryPack, doubleEntryPlugin, exportToCsv, finalizeSession, fiscalLockPlugin, flattenJournalEntries, format, formatPlain, fromDecimal, generateAgedBalance, generateBalanceSheet, generateBudgetVsActual, generateCashFlow, generateDimensionBreakdown, generateGeneralLedger, generateIncomeStatement, generateRevaluation, generateTrialBalance, getCurrency, getCustomJournalTypes, getDateRange, getFiscalYearStart, getJournalType, getJournalTypeCodes, getMinorUnit, getNormalBalance, idempotencyPlugin, isBalanceSheet, isIncomeStatement, isValidCategory, isValidCurrency, isValidJournalType, isVirtualTaxAccount, multiply, parseCents, percentage, quickbooksFieldMap, registerJournalType, reopenFiscalPeriod, resolveModelNames, splitTaxExclusive, splitTaxInclusive, subtract, toDecimal, universalFieldMap };
+export { type AccountCode, type AccountForeignBalance, type AccountRepository, type AccountSummary, type AccountType, AccountingEngine, type AccountingEngineConfig, AccountingError, type ActorContext, type AgedBalanceOptions, type AgedBalanceParams, type AgedBalanceReport, type AgedBalanceRow, type AgedBucketConfig, type AuditConfig, type BalanceSheetReport, type BudgetVsActualOptions, type BudgetVsActualParams, type BudgetVsActualReport, type BudgetVsActualRow, type BulkCreateInput, type BulkCreateResult, CATEGORIES, CATEGORY_KEYS, CURRENCIES, type CashFlowCategory, type CashFlowReport, type CashFlowSection, type CategoryKey, type Cents, type CountryPack, type CountryPackInput, type CreateLockPluginOptions, type CreditLimitPluginOptions, type Currency, DEFAULT_BUCKETS, type DailyLockPluginOptions, type DateOption, type DateRange, type DimensionBreakdownOptions, type DimensionBreakdownParams, type DimensionBreakdownReport, type DimensionBreakdownRow, type DimensionDefinition, type EntryState, Errors, type ExportField, type ExportFieldMap, type FieldError, type FiscalLockPluginOptions, type FiscalPeriodSummary, type FlatJournalRow, type FxRealizationPluginOptions, type GeneralLedgerAccount, type GeneralLedgerReport, type IncomeStatementReport, type IntrospectAPI, JOURNAL_CODES, JOURNAL_TYPES, type JournalEntryRepository, type JournalItem, type JournalItemRef, type JournalRepository, type JournalSchemaOptions, type JournalTemplate, type JournalType, type LedgerEntry, type LedgerModels, type LedgerPaginationConfig, type LedgerRepositories, type LedgerRepositoryPlugins, type LockAccountSelector, type LockHit, type LockResolver, type LockResolverContext, type Logger, type MainType, type MatchInput, type ModelNames, Money, type MultiCurrencyConfig, type MultiTenantConfig, type NormalBalance, type OpenItem, type PartnerLedgerLine, type PartnerLedgerOptions, type PartnerLedgerParams, type PartnerLedgerReport, type PeriodResolverOptions, type PopulatedJournalEntry, type PostOptions, type PostingContract, type PostingResult, type ReconciliationRepository, type RecordAPI, type RecordAdjustmentInput, type RecordAdjustmentLine, type RecordExpenseInput, type RecordOptions, type RecordPaymentInput, type RecordSaleInput, type RecordTransferInput, type RepartitionAccountResolver, type RepartitionGeneratorOptions, type ReportAccount, type ReportCategory, type ReportDescriptor, type ReportGroup, type ResolvedModelNames, type RevaluationOptions, type RevaluationParams, type RevaluationRate, type RevaluationReport, type RevaluationResult, type ReverseOptions, type ReverseResult, type SchemaOptions, type SeedOptions, type SeedResult, type Cents$1 as SemanticCents, type SessionResult, type StatementType, type StrictnessConfig, type SubledgerJournalItem, type SubledgerPostingInput, type TaxCode, type TaxCodesByRegion, type TaxDetail, type TaxExigibility, type TaxInput, type TaxLockPluginOptions, type TaxMetadata, type TaxRepartitionLine, type TaxReport, type TaxReportLine, type TaxReportTemplate, type TaxReturnSummary, type TotalAccountOp, type TrialBalanceReport, type TrialBalanceRow, type WatermarkResolverOptions, acquireSession, add, allocate, buildAccountTypeMap, buildDimensionFields, buildDimensionIndexes, buildItemFilters, buildRevaluationEntry, calculateTotal, closeFiscalPeriod, computeEndingBalance, computeRevaluation, createAccountingEngine, createLockPlugin, createModels, createRepartitionTaxGenerator, createRepositories, creditLimitPlugin, dailyLockPlugin, defaultLogger, defaultResolveTaxRepartitionAccountCode, defineCountryPack, doubleEntryPlugin, exportToCsv, finalizeSession, fiscalLockPlugin, flattenJournalEntries, format, formatPlain, fromDecimal, fxRealizationPlugin, generateAgedBalance, generateBalanceSheet, generateBudgetVsActual, generateCashFlow, generateDimensionBreakdown, generateGeneralLedger, generateIncomeStatement, generatePartnerLedger, generateRevaluation, generateTrialBalance, getCurrency, getCustomJournalTypes, getDateRange, getFiscalYearStart, getJournalType, getJournalTypeCodes, getMinorUnit, getNormalBalance, idempotencyPlugin, isBalanceSheet, isIncomeStatement, isValidCategory, isValidCurrency, isValidJournalType, isVirtualTaxAccount, multiply, parseCents, percentage, periodResolver, quickbooksFieldMap, registerJournalType, reopenFiscalPeriod, resolveModelNames, splitTaxExclusive, splitTaxInclusive, subtract, taxLockPlugin, toDecimal, universalFieldMap, watermarkResolver };