11 — Rules reference (the policy catalog)

Status: draft Purpose: One place for the rules that drive recognition, allocation, modifications, credits, close, and journals. Use this to make product decisions and to configure a tenant. Principle: Rules are named config + policy, resolved deterministically — not logic buried in joins or spreadsheet branches.

Read with: 01-domain-asc606.md (why) · 03-event-catalog.md (policy ids) · 04-engine-scenarios.md (numbers) · 10-use-cases-and-flows.md (where rules fire)

Naming/precedence here are design proposals. Lock any rule that affects a booked number via an ADR.

0. Rule resolution order (precedence)

When multiple levels set a rule, the most specific wins:

line override  >  contract/PO  >  product/SKU  >  org default  >  system default

Every effective rule value is stamped on the entity it affects, so audit (F5) can show which rule applied and from which level.

1. Recognition method rules (Step 5)

recog.method — when/how control transfers.

Calendar sub-rule: daily (precise proration) vs monthly (simpler). Pick per tenant; affects amendment/cancel proration. Lock in ADR.

2. Transaction price rules (Step 3)

TP source order (Chargebee): subscription/item price → contract amount → read first invoice amount as an input (never as contract creator). See 03 §3.1 open question.

3. Allocation rules (Step 4)

SSP source (config): observable list price → adjusted market → residual. SSP library is tenant config; multi-PO is a deferred feature (08 §8).

4. Modification rules (contract changes)

Decision tree for amend_contract (ASC 606-10-25-10..13):

Is added scope a distinct good/service AT its SSP?
  YES → separate contract (new PO, no touch to existing)
  NO  → is remaining scope distinct from what's transferred?
          YES → PROSPECTIVE  (reallocate remaining TP over remaining POs; no restatement)
          NO  → CUMULATIVE CATCH-UP (adjust revenue-to-date immediately)

MVP does prospective only; cumulative + separate-contract are ADR-gated additions.

5. Credit note / return rules

record_credit resolves a CB reason_code → named policy (config map, not join logic).

Overflow rule (CN > unrecognized): define whether excess reverses recognized revenue or becomes AR credit — ADR (08 §4.5). Steal ideas from Hotglue apply_accounting_treatment; do not steal its control flow.

6. Cancellation / termination rules

terminate with policy term.cancel:

Proration to effective date follows the recognition calendar (§1). Default is ADR-gated — do not hardcode.

7. Contract-existence rules (Step 1 gate)

A contract is recognized only when ASC 606-10-25-1 criteria hold, notably collectibility probable.

This is the clean home for today’s payment_required_for_revenue_recognition flag and "Delayed Revenue" — a Step-1 policy, not a pipeline hack.

8. Period & close rules

State machine: OPEN → READY → RECOGNIZED → POSTED → LOCKED (see 10 §5).

9. Currency & rounding rules

Invariant: ∑ recognized + deferred_remaining = allocated TP (after amendments/credits per policy), to the cent.

10. Journal / account mapping rules

post_journals(period) maps subledger movements to GL accounts (config per tenant).

Only summarized batches post to GL; line-level detail stays in the subledger (that’s the "subledger" promise in 00).

11. Config surface (what an admin sets per tenant)

Rule of thumb: if a behavior changes a booked number, it must be (a) a named rule here, (b) settable as config, and (c) covered by a golden scenario in 04.

12. Rules → scenarios coverage

Any new rule needs a scenario before it ships.