Adjustment notes

Sub-ledger 6 was introduced by migration 0008; the current issuance authority is migration 0068_adjustment_note_proposals.

The idea

A supplier reduces a bill. A customer is credited for a return. A quantity was wrong. In a mutable system you edit the document. In GreatBook the original bill or invoice is never edited; a note references it and changes its derived due. This is the clearest place where immutability and derived balances pay off together. Because due is derived rather than stored, a note does not have to reach into the original and change a number. It adds a row, and the derivation accounts for it.

due = total - allocated - advance_applied + Σ(DEBIT notes) - Σ(CREDIT notes)

A CREDIT note lowers what is outstanding. A DEBIT note raises it.

Every new note is staged for a second person

AdjustmentNoteProposalService.propose derives the full note plan and stores it without posting. The proposal names its target obligation, credit/debit direction, source discrepancy basis and reference, exact decimal amounts, currency, proposer, reason, request key, and content fingerprint. Approval requires a different named person. The service normalizes identities before comparing them, so case, surrounding whitespace, or the email form cannot turn one person into two. Agent, service, placeholder, and same-person approvers are refused. The approval and note issue happen in one transaction. approved is therefore not a durable resting state: either the note, immutable journal, proposal attribution, and native links all commit, or the approval rolls back with the failed post. The original bill or invoice remains unchanged. Migration 0068 repeats the load-bearing rules in the database:

an approved or posted proposal must name a decider distinct from its proposer;
a staged proposal has no decider and every decided proposal does;
every proposal carries both a discrepancy basis and the specific source reference;
amounts are non-negative and total = amount_pretax + vat_amount;
historical notes are not backfilled with invented issuer or proposal evidence.

The engine service and migration are shipped, but this documentation cut did not find or exercise a public end-to-end adjustment-note proposal UI or API. The two-person issuance control is documented as an engine fact, not as a working production workflow claim.

The four shapes

Shape	Meaning	Entry
AP CREDIT	the supplier reduces what we owe	`Dr 2000` (VAS 331) / `Cr <pretax GL>` / `Cr 1300` (VAS 133)
AP DEBIT	the supplier increases what we owe	`Dr <pretax GL>` / `Dr 1300` / `Cr 2000`
AR CREDIT	we reduce what the customer owes	`Dr 4090` (VAS 521 contra-revenue) / `Dr 2100` (VAS 3331) / `Cr 1100`
AR DEBIT	we increase what the customer owes	`Dr 1100` / `Cr 4000` (VAS 511) / `Cr 2100`

Notice that every shape moves the VAT leg too. A credit note that reduces a bill also reduces the recoverable input VAT, so the VAT register and the 133 position stay tied. A note that touches a stock account also posts a matching stock movement, so the costing sub-ledger stays consistent with what was actually returned.

What a note may not do

Three checks constrain a note against the document it adjusts:

Rule	Check	Why
a note with a stated basis must link to a real source document	`ADJ-BASIS-LINK`	a note against nothing is an unexplained movement in AP or AR
the note’s quantity gap may not exceed the original document’s quantity	`ADJ-QTY-CEILING`	crediting more units than were ever bought is a data error, not a business event
the note’s VAT rate must match the original document’s rate	`ADJ-RATE-MATCH`	a rate change between document and note produces a VAT position neither party’s return will agree with

Plus ADJ-CATALOG (the direction and target type are in the catalog), ADJ-ORPHAN (no note against a document that does not exist), ADJ-AMOUNT (amount matches quantity times price) and ADJ-STOCK-COUNTERLEG (a stock-touching note posted its movement). Two explainable balances report the net adjustment impact on AP and on AR.

Where it is enforced

Concern	Code
the four shapes, and the ceiling and rate-match sources	`backend/app/logics/finance/adjustments.py`
the original note schema	migration `0008_adjustment_notes`
proposal lifecycle and two-person issuance	`backend/app/services/adjustment_note_proposal_service.py`
proposal schema and database constraints	migration `0068_adjustment_note_proposals`
the derivation of `due`	`derive.obligation_due`
the checks	`close_checks.run_adjustment_checks`

The test that would fail if it broke

backend/tests/test_adjustments.py covers all four shapes and the constraint checks, and ties to the v12 worked data: a credit note moves a bill’s due to 2,805,000 with the original document frozen, and a note against an invoice produces a negative due of 100 where the customer overpaid. backend/tests/test_adjustment_note_authority.py covers distinct-human approval, exact plan re-derivation, stale state, database constraints, replay, atomicity, and deliberately null historical attribution.

A negative due is a legitimate outcome, not a bug: it is an overpayment. The check surface reports it rather than clamping it to zero, because clamping loses the fact that money is owed back.