Skip to content

Contract: Company identity and context

Status

Canonical.

Purpose

This contract defines the minimum identity and context guarantees for BooksPlus companies.

Contract

A company is the accounting entity whose books are maintained in BooksPlus.

Company identity scopes accounting records, fiscal setup, permissions, audit events, reporting, backup, restore, and sensitive company-data operations.

Required fields

A BooksPlus company must include:

  • stable company identifier;
  • legal name or registered name;
  • display name;
  • status;
  • base or reporting currency;
  • accounting time-zone id;
  • fiscal setup reference when configured;
  • created timestamp;
  • created by actor;
  • retired timestamp when applicable;
  • retired by actor when applicable.

Allowed statuses:

  • draft;
  • active;
  • retired.

Rules

  • Company identity must remain stable after creation.
  • A company must have one named IANA accounting time-zone id. UTC is allowed; a customer-maintained fixed UTC offset is not a time-zone id.
  • The company accounting time zone controls timestamp resolution for its FinancialPeriod boundaries. A user, device, source, or operational-location zone must not silently override it.
  • Accounting records must be scoped to a company.
  • Fiscal calendar profiles and financial periods must belong to a company.
  • Chart-of-accounts records must belong to a company.
  • Company-scoped protected actions must resolve actor and company context before execution.
  • Company creation and company selection flows may begin without an existing company context, but protected actions inside those flows must still be attributable to an actor when actor identity is available.
  • Company-scoped permissions must be evaluated against the target company.
  • Company-scoped audit events must preserve company identity.
  • Backup and restore preserve the stable company identifier. Restore may replace the company having that exact identifier or recover it when absent, but may not remap, clone, or merge it into another company.
  • A company restore must not change another company's records, authorization assignments, evidence, or audit history.
  • In the initial release, a company's base or reporting currency is the only currency permitted for its posted journal entries and formal statements.
  • Used companies must be retired rather than deleted.
  • Retired companies must remain visible where historical accounting records, audit events, backups, or reports reference them.
  • BooksPlus Test Company is development/test seed data only and must not be created or activated in production mode unless explicit development or test mode is active.

Acceptance criteria

  • An account references a company.
  • A financial period references a company.
  • A company-scoped protected action without company context is rejected before domain mutation.
  • A company-scoped audit event records the company identifier.
  • A posting in a currency other than the company's base or reporting currency is rejected.
  • Company creation rejects an unavailable or invalid accounting time-zone id.
  • A retired company remains visible in historical audit and reporting contexts.
  • Development/test seeding can create BooksPlus Test Company only in explicit development/test mode.
  • account.contract.md
  • financial-period.contract.md
  • kernel.contract.md
  • security/role-permission-contract.md
  • security/audit-event-contract.md
  • security/company-backup-snapshot.contract.md
  • reporting.contract.md
  • ../decisions/accepted/0026-initial-release-single-currency-boundary.md
  • business-time.contract.md
  • ../decisions/accepted/0033-company-accounting-time-and-period-cutoffs.md