Skip to content

Last reviewed: 2026-07-29

Account Role Contract

Canonical object: AccountRoleAssignment

Purpose: - Account roles let workflows ask for stable business meaning without depending on visible account codes.

Required fields: - id - company_id - account_id - role_key - cardinality - assigned_by_actor_id - assigned_at

Allowed cardinality values: - required_singleton - singleton - repeatable - optional_repeatable

Rules: - Account roles describe stable business meaning, not account numbers. - Role assignments are scoped to one company. - Singleton and required-singleton roles may be assigned to only one account per company. - Repeatable roles may be assigned to multiple accounts. - Role assignment must not silently duplicate an existing singleton business role. - Required-singleton means a role is expected for a complete starter chart or setup checklist; it does not make every incomplete company invalid. - Role resolution for routine posting must reject missing, inactive, retired, non-posting, wrong-company, and duplicate singleton role targets explicitly. - Role resolution must return account identity, not account code. - Role assignment and role resolution must not infer account type, normal balance, or posting behavior from account-number patterns.

Launch role keys: - cash.on_hand - bank.operating - clearing.receipts_for_deposit - receivable.trade - liability.unapplied_customer_cash - inventory.general - inventory.input - inventory.output - asset.prepaid_inventory - asset.prepaid_expenses - payable.trade - liability.accrued_expenses - liability.goods_received_not_invoiced - tax.sales_tax_payable - liability.customer_deposits - equity.default - equity.retained_earnings - revenue.product - revenue.service - expense.cost_of_goods_sold - expense.inventory_adjustment - expense.purchase_price_variance - clearing.inventory_fallback - clearing.payment_disbursements - expense.operating - liability.credit_card - expense.finance_charges - revenue.interest

Capital-project, fixed-asset, accumulated-depreciation, and depreciation-expense roles are deferred beyond the initial release.

Required launch readiness roles: - receivable.trade - payable.trade - tax.sales_tax_payable - equity.retained_earnings - revenue.product - expense.cost_of_goods_sold - expense.inventory_adjustment - expense.purchase_price_variance - clearing.inventory_fallback

Inventory Summary role rules:

  • inventory.output supplies the inventory credit for accepted consumption and COGS components.
  • inventory.general supplies ordinary inventory adjustments, standard-cost revision adjustments, and the inventory side of PPV when no GRNI accrual is adjusted.
  • inventory.input preserves the distinct operational input mapping and participates in deduplicated inventory-control reconciliation; it does not authorize Inventory to repost a Purchasing-owned acquisition.
  • Ending inventory-control reconciliation deduplicates immutable account ids when inventory.general, inventory.input, and inventory.output resolve to the same account.
  • clearing.inventory_fallback is review clearing for unresolved operational output. It is not an ordinary Inventory posting template and cannot suppress a held result.

Banking and Finance Summary role rules:

  • bank.operating, cash.on_hand, clearing.receipts_for_deposit, clearing.payment_disbursements, receivable.trade, liability.customer_deposits, liability.unapplied_customer_cash, liability.credit_card, expense.operating, expense.finance_charges, and revenue.interest resolve only when selected by the canonical Finance fact and component.
  • liability.credit_card is repeatable because a company may review several card liability accounts.
  • expense.finance_charges is repeatable so reviewed bank and card charges may use approved finance-expense destinations.
  • revenue.interest is a singleton initial interest-income destination.
  • Account-reconciliation balance aggregation uses the one selected immutable account id. Role assignments do not authorize combining several accounts into one false closing balance.

Related truth pages: - account.contract.md - ../accounting/accounts.md - ../decisions/accepted/0017-chart-maintenance-surrounds-accounting-kernel.md - ../decisions/accepted/0024-operational-summary-workflow-boundaries-and-purchasing-facts.md - inventory-period-summary-fact.contract.md - banking-and-finance-summary-fact.contract.md