Last amended: 2026-07-30 Audience: product, accounting, developer

ADR 0029: Cross-Workflow Accounting Event Identity and Relationships

This ADR deliberately does not enumerate the complete account set, every source transaction, or workflow posting templates. Those belong to the workflow that owns the accounting meaning.

Context

Sales, Purchasing, Inventory, and Banking receive distinct but related source accounting events. A vendor invoice may be settled by a payment; a clearing event may later settle to bank; an Inventory event may use Sales shipment or Purchasing receipt evidence; and a statement match may explain an already posted direct-bank event.

The existing import identity contract already defines durable source-event identity and the accepted owning-workflow record. Cross-workflow linking should reuse that identity rather than create a second identity system.

Decision

Accepted accounting event reference

An accepted accounting event reference contains:

company id;
source system;
source object type;
external object id;
external event or version id;
owning workflow route;
durable owning-workflow record id;
fact type and source event stage;
source-world activity date or date range;
change type;
optional Summary batch and posted journal-entry references; and
human-visible workflow reference for display only.

The company, source-system, source-object, external-object, and external-event tuple remains the durable source identity defined by the Accounting Import Candidate contract. Workflow route, fact type, stage, accounts, amounts, and descriptions are meaning attached to that identity; they are not substitutes for it.

Accounting event relationship

An accounting event relationship contains:

stable relationship id and company id;
source accepted-event reference;
target source identity and, when resolved, target accepted-event reference;
versioned relationship type;
resolution status;
evidence or reviewed mapping reference;
created and resolved attribution and timestamps;
optional reconciliation amount and currency;
optional quantity and unit of measure; and
superseding relationship reference when corrected.

Relationships may be many-to-many and may cross source systems, but both sides must belong to the same BooksPlus company.

Initial relationship types:

Relationship type	Direction and meaning
`applies_to`	A receipt or payment amount applies to one or more invoice events.
`clears`	A later deposit or bank-settlement event clears a prior receipt- or disbursement-clearing event.
`statement_matches`	Statement evidence matches an event already posted directly to bank; the relationship is non-posting.
`settles_accrual`	A later ordinary event settles a specifically identified accrual or GRNI event without repeating the original expense or acquisition.
`adjusts_accrual`	An adjustment event changes the carrying amount of a specifically identified accrual without settling it. An Inventory-owned PPV event uses this relationship to adjust GRNI before invoice settlement.
`supports_inventory_consumption`	A Sales shipment or fulfillment event supplies evidence for a distinct Inventory-owned outflow and COGS event.
`supports_inventory_valuation`	A Purchasing receipt or acquisition event supplies quantity or valuation evidence for an Inventory-owned reconciliation or adjustment event.
`supports_purchase_price_variance`	Purchasing receipt and purchase-price evidence supports a distinct Inventory-owned PPV event.
`recognizes_prepayment`	A later Purchasing recognition event consumes an allocated amount from a specifically identified posted non-inventory prepayment acquisition.
`corrects`	An accepted imported adjustment event points to the accepted event whose posted journal entry it adjusts.
`reverses`	An accepted imported full-reversal event points to the accepted event whose posted journal entry it reverses.

The relationship vocabulary is provider-agnostic. Provider journal codes, account numbers, descriptions, document text, or equal amounts do not create a relationship.

Ownership and posting

Every accepted source accounting event has exactly one owning workflow.
Every event has at most one ordinary BooksPlus posting result.
Inventory Summary is the sole PPV posting owner. Purchasing may supply receipt, acquisition, purchase-price, and GRNI evidence, but neither a relationship nor a Purchasing template may post PPV.
A relationship never authorizes posting and never changes event ownership.
Each workflow's accepted template decides whether its own event posts.
A relationship required by a template, such as GRNI settlement, must resolve before that event becomes ready to post.
A support-only relationship, such as a later statement match, does not create or block an otherwise complete posting request.
Accounts and posting lines belong to workflow facts and templates, not to the identity or relationship contract.

For the accepted GRNI/PPV sequence:

supports_purchase_price_variance points from the accepted Purchasing receipt or acquisition evidence event to the Inventory-owned PPV event;
adjusts_accrual points from the Inventory-owned PPV event to the posted GRNI accrual whose carrying amount it changes; and
settles_accrual points from the later Purchasing invoice event to the adjusted GRNI accrual it settles.

The GRNI accrual must be accepted and posted before a nonzero PPV adjustment. That adjustment must be accepted and posted before the dependent invoice may settle GRNI. Zero variance needs no PPV event or adjusts_accrual relationship, but the zero reconciliation and settles_accrual relationship remain required.

For non-inventory prepayment recognition, recognizes_prepayment points from the later Purchasing-owned recognition event to the posted Purchasing-owned payable or direct-purchase event that acquired the prepaid-expense component. The acquisition must be accepted and posted before the dependent recognition may become ready. The relationship amount is the total company-currency amount recognized from that acquisition by the dependent event; workflow-owned allocations identify the exact prepaid component and expense destination.

For Banking and Finance:

clears points from the later Finance receipt- or disbursement-settlement event to each prior posted Sales or Purchasing event whose clearing balance it consumes;
applies_to points from a Finance-owned direct receipt to each posted Sales invoice whose trade-receivable balance it settles; and
statement_matches points from the later non-posting Finance match result to the accepted event already posted directly to the same bank account.

Detailed clearing, receivable, and statement allocations remain Finance-owned. Required posting allocations reserve and consume posted open balances; statement matches are support-only and consume no posting balance.

For Corrections:

the correction event is the relationship source and the corrected event is the target;
corrects applies only to adjustment and reverses applies only to full-entry reversal;
both accepted-event references must resolve to the same company and to the journal entries identified by the Accounting Correction record;
relationship version 1 is required for the launch correction boundary;
one target event may have at most one active posted reverses relationship; and
manual corrections do not manufacture external source identity merely to create an accepted-event relationship.

The Accounting Correction record's direct target journal-entry id remains authoritative. The accepted-event relationship is required only when both the correction and target originate from accepted accounting events.

Resolution and history

An intake may preserve a complete target source identity before the target event is accepted by BooksPlus. The relationship remains unresolved and visible until it resolves to a same-company accepted event.

Allowed resolution statuses are:

unresolved;
resolved;
invalid; and
superseded.

Accepted and resolved relationships are append-oriented. A changed relationship supersedes the prior record; it does not silently rewrite or delete it.

Validation rules

Source and target event identity must be complete.
A relationship cannot point an event to itself.
Duplicate active relationships with the same company, endpoints, type, and meaning are rejected or treated as exact replay.
Conflicting reuse of relationship identity is held for review.
Optional relationship amounts carry one explicit currency and reconcile where the owning workflow requires allocation or clearing totals.
Initial-release relationship amounts that support posting use the company currency. Foreign-currency evidence may be preserved but cannot supply a conversion or exchange-difference rule.
Optional quantities carry an explicit unit of measure.
Detailed allocations and reconciliation lines remain workflow-owned child records. A relationship may carry only an optional summarized amount or quantity needed to explain or validate the link.
corrects and reverses must match adjustment and reversal kind, respectively, and must resolve to the direct journal-entry target required by the Accounting Correction Contract.
Neither relationship type authorizes posting or replaces correction evidence, period, reconciliation, permission, step-up, or central-posting validation.
An unresolved required relationship blocks only the dependent workflow event, not the already accepted related event.
An unresolved support-only relationship remains visible but does not block an otherwise complete event unless its owning workflow explicitly requires that evidence.
A relationship cannot create a second posting result for either endpoint.
A PPV relationship resolves only to an Inventory-owned PPV event and cannot authorize a Purchasing-owned PPV posting.
GRNI accrual, PPV adjustment, and invoice-settlement relationship amounts and workflow-owned allocations must reconcile exactly. Partial and many-to-many relationships are valid only when their allocations sum to each affected endpoint amount without overlap.
Prepayment-recognition relationship amounts must equal their workflow-owned allocations by acquisition endpoint. Partial and many-to-many recognition is valid only when allocations identify posted prepaid components and do not overlap or exceed their available balances.
Finance clearing and direct-receipt relationship amounts must equal their workflow-owned allocations. Ready posting allocations cannot overlap or exceed the prior event's posted open clearing or receivable balance.
A statement match requires the same company, bank account, currency, and exactly reconciled amount as the already posted direct-bank event. It is non-posting and cannot reserve or consume a clearing balance.

Consequences

Purchasing persistence can link later Inventory and Banking events without knowing their complete posting templates.
New account roles and workflow fact types do not require a new identity scheme.
Cross-source reconciliation remains possible without provider vocabulary becoming BooksPlus accounting meaning.
The accepted-candidate identity and owning-workflow link remain the one durable intake boundary.
GRNI adjustment and settlement have distinct relationship meaning and enforceable ordering without moving PPV posting authority into Purchasing.
Prepayment acquisition and later expense recognition retain separate source event identity while remaining exactly reconcilable within Purchasing.

Acceptance record

Accepted with these confirmations:

The initial relationship vocabulary above is accepted, including distinct inventory-consumption, inventory-valuation, PPV-support, accrual-adjustment, and accrual-settlement relationships.
Same-company relationships may cross source systems.
Complete unresolved target identities may be retained and resolved later. Blocking is determined by the dependent workflow's accepted template.
Relationship history is append-oriented. A changed accepted relationship supersedes its predecessor and does not silently rewrite or delete it.
Detailed amounts, quantities, allocations, and reconciliation lines remain workflow-owned child records; relationships carry only the summarized amount or quantity needed to explain and validate the link.
A relationship never authorizes posting, changes event ownership, or creates another posting result.
The accepted GRNI/PPV relationship direction and ordering are those stated above.

Amended on 2026-07-28 to accept recognizes_prepayment, directed from the later Purchasing recognition event to the posted Purchasing prepayment acquisition. Detailed component allocations and open-balance controls remain owned by the Purchasing fact contract.

Amended on 2026-07-29 to fix Finance relationship direction and ownership: later Finance settlements and matches are relationship sources; prior posted Sales or Purchasing events are targets. Finance-owned allocations control open balance consumption, while statement matching remains support-only.

Amended on 2026-07-30 to activate corrects and reverses for imported Accounting Correction events. The correction event is the source, the corrected event is the target, and the direct journal-entry relationship remains authoritative.

0007-provider-agnostic-import-boundaries.md
0022-reviewable-accounting-file-intake.md
0024-operational-summary-workflow-boundaries-and-purchasing-facts.md
0026-initial-release-single-currency-boundary.md
0028-standard-cost-inventory-period-summaries.md
../../contracts/accounting-import-candidate.contract.md
../../contracts/inventory-period-summary-fact.contract.md
../../contracts/banking-and-finance-summary-fact.contract.md
../../contracts/purchasing-and-payables-summary-fact.contract.md
../../contracts/summary-accounting-batch.contract.md
../../contracts/accounting-correction.contract.md