Last reviewed: 2026-08-02

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 must 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 must 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 must persist: - id - financial_period_id - sequence_number, starting at 1 and increasing by 1 within the period - prior_status when the state change follows an existing status - new_status - actor_id - changed_at - reason - audit_reference when available - close_run_id when a CloseRun finalized soft_closed or hard_closed - close_reopen_id when a CloseReopen produced reopened

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. - Period dates are company-local business dates under the company's named accounting time zone. - When timestamp selection is required, resolve the inclusive dates through the Business Time Contract as a half-open interval. Preserve the named zone and resolved instants when the cutoff is durable evidence. - 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. - Soft-closed periods allow reversal and adjustment posting modes only through the dedicated protected correction actions and their required reason, evidence, preview, authorization, and audit behavior. - Hard-closed periods block routine, reversal, and adjustment posting modes until separately reopened. - Open and reopened periods allow reversal and adjustment posting modes when the Accounting Correction Contract is otherwise satisfied. - A correction target's period status does not select the new entry's period; the correction posting date resolves the controlling period. - Reopen requires authority, reason, and audit trail. - A new soft_closed or hard_closed transition requires the current eligible CloseRun, checks, waivers, report pack, authorization, and approval behavior defined by the Close Run Contract. - A new reopened transition requires a durable CloseReopen under that contract. - Low-level transition eligibility and persistence do not independently authorize close or reopen. - 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. - sequence_number is the authoritative causal order of a period's state changes. It must be unique and contiguous within that period. - changed_at records attribution time and must not be used with state-change identity as a substitute for causal order because timestamps may be equal. - 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. - period-cutoff resolution is deterministic across daylight-saving changes and fails visibly for an unavailable, invalid, or ambiguous boundary. - status transitions enforce soft close, hard close, and reopen rules. - parent periods cannot close before required child periods are closed according to close policy. - quarter constituent-month and fiscal-year constituent readiness follows the direct-child period-driven calendar rule in the Close Run Contract. - 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. - link close and reopen state changes to the exact CloseRun or CloseReopen decision that caused them. - 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. - evaluate routine and correction posting modes without treating a correction target's historical period as the new entry's posting period.

Related truth pages: - company.contract.md - ../accounting/financial-periods.md - ../accounting/close.md - kernel.contract.md - accounting-correction.contract.md - close-run.contract.md - business-time.contract.md