Last reviewed: 2026-08-13

Close Run Contract

Canonical objects:

CloseRun
CloseCheckSnapshot
CloseWaiver
CloseApproval
CloseReportPack
CloseReopen

Purpose:

evaluate one financial period for soft close or hard close;
preserve what was checked, what blocked close, what was waived, what was approved, and which evidence and reports supported the decision;
permit period-state mutation only from a current protected close or reopen decision; and
preserve reviewable close and reopen history without making Close a second ledger, reporting engine, evidence store, or posting path.

Stable values

Close modes:

soft_close
hard_close

Close-run statuses:

evaluated
ready
approved
finalized
superseded
abandoned

Check severities:

blocker
warning
informational

Check outcomes:

passed
failed
not_applicable

Waiver statuses:

active
revoked

Approval statuses:

approved
invalidated

Close-run identity and required fields

A CloseRun requires:

id;
company id;
company-scoped close-run number;
target financial-period id and recognizable label;
close mode;
close-policy version;
evaluation fingerprint;
target period status and latest state-change id at evaluation;
evaluation cutoff timestamp;
status;
created timestamp and actor;
evaluated timestamp and actor;
updated timestamp and actor;
immutable check snapshots;
evidence links;
report-pack id when captured;
active waiver references;
approval reference when hard-close approval exists;
finalized timestamp, actor, period-state-change id, and audit reference when finalized; and
abandonment or supersession reason and attribution when applicable.

The evaluation cutoff timestamp is the exact instant at which source state was evaluated. It is not the target period's close date or exclusive accounting cutoff. The target FinancialPeriod's inclusive business dates and any resolved timestamp interval follow the Business Time Contract.

Close-run numbers are positive, increasing, immutable, and unique within a company. Their display format is CL- followed by the number padded to at least six digits, such as CL-000001. The number is a human-visible reference; the close-run id remains the durable identity.

A close run targets exactly one same-company financial period and one mode. The launch contract allows fiscal month, fiscal quarter, and fiscal year targets. Close meaning does not depend on a period label, screen position, calendar date alone, provider field, or mutable workflow description.

Period and hierarchy policy

soft_close evaluates an open or reopened target and finalizes it to soft_closed.
hard_close evaluates a soft_closed target and finalizes it to hard_closed.
Direct open to hard_closed, reopened to hard_closed, or repeated same-status finalization is blocked.
A fiscal month has no constituent-period prerequisite.
A fiscal quarter's constituent periods are the generated fiscal months contained by its inclusive date range. Months and quarters remain direct children of the fiscal year; Close must not invent a nested year -> quarter -> month hierarchy.
A fiscal year's constituents are its direct generated fiscal months and fiscal quarters.
Soft-closing a quarter or year requires every constituent period to be soft_closed or hard_closed.
Hard-closing a quarter or year requires every constituent period to be hard_closed.
A planned, missing, ambiguous, cross-company, or incompatible target or constituent period is a non-waivable blocker.
Finalization appends one attributable financial-period state change. It never overwrites prior close, reopen, or creation history.

Only the protected Close finalization boundary may drive a new soft_closed or hard_closed transition. A low-level period status method, registered action name, existing screen, or fixture does not establish Close readiness and must not bypass the current CloseRun.

Check snapshots and launch check catalog

A CloseCheckSnapshot requires:

id and close-run id;
stable check code and evaluator version;
severity;
outcome;
whether the check is waivable;
short summary and review detail;
source object references and source version or fingerprint when applicable;
evaluated timestamp; and
the effective disposition after any active waiver, without changing the original outcome.

Check snapshots are immutable facts about one evaluation. A later evaluation creates another close run; it does not rewrite an earlier snapshot.

The launch minimum check catalog is:

Check code	Required meaning	Minimum policy
`target_period_eligible`	Target exists in the company, has an allowed type and current status, and matches the requested mode.	Non-waivable blocker.
`constituent_periods_eligible`	Required generated constituent periods have compatible close states under the period-driven calendar rule.	Non-waivable blocker.
`trial_balance_balanced`	Posted ledger debits and credits balance for the company and covered period under the Reporting trial-balance contract.	Non-waivable blocker.
`ready_posting_work_complete`	Accepted or ready accounting work assigned to the covered period has either posted through central Accounting or reached an explicit non-posting terminal result.	Non-waivable blocker.
`workflow_exceptions_reviewed`	Staged, held, failed, or otherwise unresolved workflow support items affecting the covered period are visible and reviewed.	Blocker; waivable only under explicit close policy.
`required_reconciliations_complete`	Reconciliations required by applicable active workflow contracts and close policy are complete and exact.	Blocker; waivable only under explicit close policy.
`close_evidence_complete`	Required same-company close evidence references resolve and remain reviewable.	Non-waivable blocker.
`close_report_pack_complete`	The required close report pack and its report-run references are captured for the exact run.	Non-waivable blocker at finalization.
`later_corrections_disclosed`	Posted corrections targeting entries in the covered period are disclosed from immutable ledger relationships.	Informational; never changes ledger truth.
`sales_tax_accounting_reconciled`	Seller-owned tax affecting the covered period reconciles exactly from accepted Sales facts to posted Sales Tax Payable activity, with facilitator-remitted amounts excluded.	Non-waivable blocker when applicable.
`sales_tax_filing_support_eligible`	Seller-owned filing obligations due by the evaluation cutoff have complete filing-summary capability, registration, jurisdiction, basis, period, and evidence.	Non-waivable blocker when applicable.
`sales_tax_return_control_complete`	Due return controls are current, externally filed with active evidence, and complete or have a current remittance in progress.	Non-waivable blocker when applicable.
`sales_tax_remittance_control_complete`	Due positive remittances have external-payment evidence and one posted remittance; accepted zero or credit/refund dispositions have evidence and no remittance posting.	Non-waivable blocker when applicable.
`sales_tax_bank_match_complete`	Posted remittances covered by an available statement period have an exact non-posting Finance match.	Blocker waivable only under explicit close policy when applicable.

A close-policy version may add checks, raise severity, or make a waivable check non-waivable. It must not remove or weaken the launch minimum checks without a new accepted truth change.

Warnings and informational results remain visible. They do not independently block finalization and are never silently converted to passed results.

Readiness, freshness, and supersession

Lifecycle:

a new evaluation is ready when every readiness rule already passes; otherwise it is evaluated;
adding the final required valid waiver may move evaluated to ready;
revoking a required waiver moves ready or approved back to evaluated and invalidates approval;
hard-close approval moves ready to approved;
soft-close finalization requires ready; hard-close finalization requires approved; successful finalization moves the run to finalized;
a newer accepted evaluation moves an older unfinalized run to superseded;
a reasoned protected abandonment may move evaluated, ready, or approved to abandoned and invalidates approval; and
finalized, superseded, and abandoned are terminal and immutable.

A run is ready only when:

every required check was evaluated;
no failed non-waivable blocker remains;
every failed waivable blocker has one active valid waiver;
required evidence and report-pack references are present;
the target and constituent periods still match the evaluated state; and
the evaluation fingerprint still matches current relevant source state.

The evaluation fingerprint is deterministic and versioned. It covers at least:

company, target period, and close mode;
close-policy and evaluator versions;
target and constituent period status and latest state-change identity;
posted-ledger state affecting the covered period;
accepted or ready posting work assigned to the period;
unresolved workflow exceptions;
required reconciliation identities and versions;
close evidence identities and supersession state;
report-pack and report-run identities and versions;
posted correction relationships targeting covered-period entries; and
sales-tax capability, result, return-control, remittance, evidence, and Finance bank-match identities and versions required by the Sales Tax Accounting and Remittance Contract.

Actor, display labels, close-run number, timestamps, and UI state do not create accounting or Close meaning.

Any relevant change after evaluation makes an unfinalized run stale and blocks approval or finalization. Examples include a posting, correction, changed period state, new or changed reconciliation, evidence supersession, changed report input, or changed check-policy version. Recovery must re-evaluate into a new run rather than silently refreshing old snapshots. A waiver changes the run's effective readiness and invalidates approval, but it does not rewrite the evaluation fingerprint or original check snapshots.

For one company, target period, and mode, the latest non-abandoned evaluation is the only run eligible for new approval or finalization. A newer evaluation supersedes older unfinalized runs and invalidates their approvals without deleting them. A finalized run remains immutable historical evidence even after reopen, later correction, or a later close cycle.

Waivers

A waiver targets exactly one failed waivable blocker snapshot on one close run.
It requires company, run, check code, actor, reason, timestamp, protected audit reference, and optional Source Document or other accepted evidence reference.
A waiver cannot target a passed, warning, informational, non-waivable, different-run, or different-company check.
A waiver preserves the failed check and explanation. It changes only the effective blocking disposition.
Waiver revocation is append-oriented, reasoned, attributable, and audited.
Adding or revoking a waiver changes run meaning and invalidates an existing approval.
A waiver is not authority to post, alter a reconciliation, change evidence, or mutate the target period outside finalization.

This contract does not require the waiver actor, approver, and finalizer to be different people. Production permission design may separate them, but role names alone never authorize these actions.

Approval and finalization

Soft close requires a ready current run and protected soft-close finalization. It does not require a separate CloseApproval record.
Hard close requires a ready current run, then a distinct protected approval step, then protected hard-close finalization.
A hard-close approval identifies the exact run version, evaluation fingerprint, active waiver set, evidence set, and report pack reviewed.
Approval requires actor, reason, timestamp, step-up confirmation, and succeeded audit evidence.
Approval does not change period state.
Any freshness or run-meaning change invalidates approval. Finalization may not reuse approval from another run or an earlier run version.
Finalization revalidates current company, period, hierarchy, checks, waivers, evidence, report pack, evaluation fingerprint, authorization, and approval where required before mutation.
Finalization atomically links the finalized CloseRun, the appended period state change, and succeeded audit evidence.
A failed or denied attempt creates no period state change and preserves the run for review or re-evaluation.

Close coordinates any required accounting work but creates no ledger line by itself in the launch contract. Manual entries, Summary results, corrections, or future close-generated entries must post through central Accounting before a new close evaluation can pass.

Report packs and evidence

A CloseReportPack requires:

id, company id, close-run id, period id, and close mode;
capture timestamp and actor;
close-run evaluation fingerprint;
check summary;
report-run references;
Source Document or other accepted evidence references; and
immutable captured status.

One captured report pack belongs to one close run and cannot be reused as the pack for another run. The launch minimum report reference is a persisted trial-balance report run for the covered period. Reporting owns report definitions, execution, parameters, and snapshot payloads. Close stores or references report-run identity and never synthesizes report truth from workflow tables.

The evaluation request supplies the evidence and report-run references to be reviewed. Evaluation validates those inputs and captures the CloseReportPack for the same new run as one durable operation. Evidence or report inputs are not attached to an already evaluated run; a changed input set requires a new evaluation, which avoids rewriting snapshots or reusing a pack across runs.

Source Documents owns close evidence identity, artifact handling, and supersession. Raw filesystem paths, filenames, provider vocabulary, or mutable screen state do not establish durable close evidence.

The Reporting Contract governs ReportRun definition, parameters, snapshot, currentness, authorization, audit, and recovery. The launch trial-balance run must identify the exact target financial period and its inclusive boundaries. Close consumes the Reporting-owned resolver result and must not infer a report type, period, or currentness from a report id alone.

Reopen

A CloseReopen requires:

id and company id;
target financial-period id;
current status and latest state-change id before reopen;
reference to the latest finalized CloseRun that established the current closed state;
nonblank reason;
optional accepted evidence references;
actor and timestamp;
resulting period-state-change id; and
protected audit reference.

Reopen:

applies only to soft_closed or hard_closed periods and results in reopened;
requires dedicated company-scoped permission, reason, step-up confirmation, and succeeded audit evidence;
never changes or deletes the prior finalized run, checks, waivers, approval, report pack, or period state changes;
invalidates use of prior approval for a later reclose;
requires a new close run before the period can close again; and
does not itself reverse, adjust, or otherwise mutate ledger entries.

Reopen follows the hierarchy in the opposite direction from close. A constituent period cannot reopen while a containing quarter or fiscal year remains closed. Containing periods must be reopened first; no automatic cascade is permitted.

Authorization and audit

Binding protected actions:

close_run.evaluate
close_run.waive_check
close_run.revoke_waiver
close_run.approve
close_run.abandon
financial_period.soft_close
financial_period.hard_close
financial_period.reopen

Requirements:

evaluation requires company-scoped authorization and succeeded or failed audit evidence;
waiver creation or revocation, approval, abandonment, soft close, hard close, and reopen require a nonblank reason;
waiver creation or revocation, approval, hard close, and reopen require step-up confirmation;
soft close does not require step-up under the launch contract;
succeeded, denied, and failed attempts preserve company, actor, action, target, result, reason when required, machine identity when available, and correlation id;
workflow actions target the CloseRun or check snapshot as applicable;
finalization and reopen audit events target the financial period and reference the CloseRun or CloseReopen identity; and
adding actions to a registry or development/test bundle does not grant them to a production role.

Replay, concurrency, and recovery

Each evaluate command carries a company-scoped request idempotency key.
Exact replay requires the same company, target period, mode, policy version, and normalized evaluation request and returns the existing run.
Conflicting reuse is rejected without overwriting the accepted run.
Waiver, revocation, approval, abandonment, finalization, and reopen commands have stable command identity and exact-replay behavior.
One run may finalize at most once, and one period state-change identity may link to at most one CloseRun or CloseReopen.
Concurrent evaluation may create only one accepted run for one idempotency identity.
Concurrent finalization or reopen may create only one accepted period state change from the expected prior state.
Recovery after interruption reuses existing run, waiver, approval, report pack, period state change, and audit identities. It never repeats a period transition or manufactures a second successful decision.

Review and downstream use

Close review must show:

recognizable close-run and period references;
mode, status, policy version, evaluation time, and freshness;
original check outcomes and effective waiver disposition;
waiver, approval, finalization, and reopen actor and audit evidence;
evidence and report-pack references;
period state-change history;
later corrections derived from posted ledger relationships; and
visible stale, superseded, abandoned, denied, failed, and blocked outcomes.

CloseRun, checks, waivers, approvals, and packs are Close control evidence. They do not become ledger or formal report truth. Financial-period current status remains explainable from append-oriented state changes. Formal reports remain derived from posted ledger truth and persisted Reporting snapshots.

Held or blocked outcomes

Visible blocked outcomes include:

missing, ambiguous, cross-company, planned, stale, or incompatible target;
incompatible or reopened constituent period;
unbalanced trial balance;
accepted or ready accounting work not posted or terminal;
unresolved workflow exceptions without an allowed waiver;
missing, stale, cross-company, or unreconciled required reconciliation;
missing, superseded, or cross-company evidence;
missing or mismatched report pack or report run;
missing, invalid, revoked, or wrong-run waiver;
missing, stale, invalidated, or wrong-run hard-close approval;
unauthorized, unconfirmed, or unreasoned protected action;
conflicting idempotency reuse;
changed evaluation fingerprint;
already-finalized or concurrently changed run or period;
reopen attempted in the wrong hierarchy order; and
unresolved or stale applicable sales-tax accounting, filing eligibility, return evidence, remittance evidence, or bank-match control.

Explicitly deferred

automatic accrual, deferral, allocation, depreciation, amortization, tax, or other close-generated journal entries;
prior-period-adjustment presentation;
automatic reopen cascades;
configurable production role templates or mandatory two-person approval;
arbitrary customer-authored check code or evaluator execution;
provider-specific close behavior;
report rendering and report-definition ownership;
evidence artifact storage outside Source Documents; and
UI implementation.

../accounting/close.md
financial-period.contract.md
business-time.contract.md
trial-balance.contract.md
reporting.contract.md
accounting-correction.contract.md
sales-tax-accounting-and-remittance.contract.md
source-document.contract.md
security/role-permission-contract.md
security/audit-event-contract.md
../decisions/accepted/0009-persisted-report-runs.md
../decisions/accepted/0010-close-runs-and-report-packs.md
../decisions/accepted/0020-initial-release-scope-and-financial-workflow-taxonomy.md