Skip to content

Contract: Company identity and context

Status

Draft.

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 should include:

  • stable company identifier;
  • legal name or registered name;
  • display name;
  • status;
  • base or reporting currency;
  • 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.
  • 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.
  • 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 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