Last reviewed: 2026-06-16
Financial Period Contract
Canonical objects: - FiscalCalendarProfile - FinancialPeriod
FiscalCalendarProfile required fields: - id - company_id - fiscal_year_end_month - fiscal_year_end_day - fiscal_year_end_day_rule - period_pattern - effective_from_fiscal_year - status - creation metadata
FinancialPeriod required fields: - id - company_id - period_type - label - start_date - end_date - parent_period_id when the period is nested - status - creation metadata - state-change history
Persistence fields:
fiscal_calendar_profile should persist:
- id
- company_id
- fiscal_year_end_month
- fiscal_year_end_day
- fiscal_year_end_day_rule
- period_pattern
- effective_from_fiscal_year
- status
- created_at
- created_by_actor_id
financial_period should persist:
- id
- company_id
- period_type
- label
- start_date
- end_date
- parent_period_id when the period is nested
- status
- created_at
- created_by_actor_id
financial_period_state_change should persist:
- id
- financial_period_id
- prior_status when the state change follows an existing status
- new_status
- actor_id
- changed_at
- reason
- audit_reference when available
Allowed statuses: - planned - open - soft_closed - hard_closed - reopened
Allowed period types: - fiscal_year - fiscal_quarter - fiscal_month
Allowed fiscal calendar profile statuses: - draft - active - retired
Allowed current period patterns: - calendar_month
Deferred period patterns: - retail_445
Retail and weekly-calendar fields are deferred until the weekly fiscal calendar contract is explicitly added.
Rules:
- Period dates are inclusive.
- A period must have start_date <= end_date.
- Period dates must not overlap for the same company, parent, and period type.
- A child period must fit fully inside its parent period.
- Standard generated fiscal months and fiscal quarters are direct children of the fiscal year.
- Fiscal quarters are derived from generated fiscal periods.
- For a standard 12-period calendar, each fiscal quarter consists of three fiscal periods.
- Fiscal year end date must equal the end date of the final fiscal quarter and final fiscal period.
- Monthly fiscal year end days must be day 1-27 or the final day of the selected month.
- Fiscal calendar profiles must preserve whether the selected fiscal year end day is a fixed day or month-end rule.
- Period identity must remain stable after creation.
- Boundary changes must be tightly restricted after postings, child periods, or close history exist.
- Posting must check period status through central period control.
- Routine posting is blocked in planned and hard-closed periods.
- Soft-closed periods block routine posting but may allow authorized close adjustments or corrections.
- Reopen requires authority, reason, and audit trail.
- Period state changes must be attributable and append-oriented.
- Persisted status and period type values must use stable snake_case contract values, not programming-language enum names.
- Financial period state-change rows must be appended, not overwritten, when a period changes state.
- A period's current status must be explainable from its append-oriented state-change history.
Validation expectations: - date ranges are valid and non-overlapping. - date-to-period lookup returns at most one controlling period for a posting date. - status transitions enforce soft close, hard close, and reopen rules. - parent periods cannot close before required child periods are closed according to close policy. - reopen preserves prior close history rather than overwriting it.
Required behavior: - define a fiscal calendar profile with fiscal year end date, period pattern, effective fiscal year, and lifecycle status; - generate monthly fiscal years with 12 fiscal month periods and 4 derived fiscal quarter periods; - define a period with explicit identity, type, dates, and status; - find the period containing a posting date; - evaluate whether a posting date is allowed, blocked, or requires override; - evaluate whether a period can be soft closed, hard closed, or reopened; - record close and reopen transitions with actor, reason, and audit reference. - map persisted financial-period rows and state-change rows to the canonical FinancialPeriod object without changing identity, date boundaries, status meaning, or history order. - map canonical FinancialPeriod objects to persistence rows using the stable status and period-type values defined by this contract.
Related truth pages:
- company.contract.md
- ../accounting/financial-periods.md
- ../accounting/close.md
- kernel.contract.md