CAM Reconciliation

Tenant Statement Generation and Dispute Routing

Generating a defensible tenant CAM reconciliation statement means turning finalized allocations into line items every tenant can trace to a pool, a denominator, and a rule version — then routing the disputes those statements provoke through a governed workflow. This is the output layer of the expense allocation logic and rule engines calculation core: it consumes finalized allocations and produces the tenant-facing document, then manages what happens when a tenant reads a number and pushes back. A statement is not a report the engine prints and forgets; it is a financial claim the landlord must be able to defend line by line, and the dispute-routing machinery is the structured path a challenge travels from the moment a tenant raises it to the moment the file is closed. Property managers live in the gap between “here is your reconciliation” and “we agree on the balance,” and the quality of that gap is decided by how transparent the statement is and how disciplined the resolution workflow behind it is.

The tenant dispute lifecycle as a state machine An issued statement transitions either to accepted and closed on the happy path, or to disputed and then under review. From under review the case transitions to adjusted and reissued or to upheld and closed. Each terminal state resolves to a closed file. Issued Disputed Under review Accepted & closed Adjusted & reissued Upheld & closed dispute triage accept adjust uphold
The dispute lifecycle: every issued statement travels a bounded set of transitions to a single closed outcome.

Prerequisites & Data Contracts

A statement is only as trustworthy as the run that produced it, so statement generation begins downstream of three settled inputs and refuses to start without all three. The first is the set of finalized allocations from the pro-rata allocation algorithm: a per-tenant, per-pool amount that has already survived the residual pass and reconciles exactly to each pool total. The generator never re-computes an allocation; it reads a frozen result and formats it, because any arithmetic performed at print time would be arithmetic no auditor watched happen. The second input is the resolved rule and version set that governed the run — the allocation method, the applied expense stop, the controllable cap schedule, and the exclusion registry, each pinned to the exact version in force at close. The third is the immutable audit trail written by the run, whose access and integrity controls are the province of CAM reconciliation security and access controls; the statement carries a reference to that trail so a tenant’s auditor can walk from a printed line back to a GL dollar without asking anyone how the number was made.

The contract between the allocation core and the statement layer is a line-item schema, and its discipline is what makes a statement defensible rather than merely tidy. Every charge line must expose four traceability fields: the pool it draws from, the denominator used to compute the tenant’s share, the rule version that governed the pool, and any stop or cap that modified the raw allocation. A line that says only “CAM — $18,240.00” is an invitation to dispute; a line that says “Landscaping pool L-04, tenant share 3.21% of 412,900 rentable SF, gross-up target 95%, controllable cap v7 applied, net recoverable $18,240.00” is a line a tenant can either accept or challenge on a specific, named ground. The statement also carries the reconciliation arithmetic a tenant expects to see: the estimated amounts already billed across the period, the reconciled actual obligation, and the resulting balance due or credit. That difference is where the year-end CAM reconciliation and true-ups logic surfaces to the tenant, and it is the single number most disputes are ultimately about.

Two contract invariants are non-negotiable before a statement may be emitted. The sum of the tenant’s charge lines must equal the tenant’s total reconciled obligation, and the sum across all tenants of any single pool’s charge lines must equal that pool’s recoverable amount. The first invariant protects the tenant from an arithmetic error; the second protects the landlord from over-recovering — billing out more than the pool actually cost, the fastest way to lose an audit. The generator asserts both before it will produce a document, and a failure routes the whole period back to the calculation core rather than emitting a statement the landlord cannot defend.

Algorithm or Rule Design

Statement assembly is a deterministic fold over finalized allocations, not a creative act. For a given tenant and period, the generator collects every pool the tenant participates in, emits one charge line per pool with its full traceability payload, appends the tenant’s estimated-billed total and any prior-period forward-dated adjustments that land in this period, and computes the closing balance. Because the underlying allocation is frozen, running the generator twice over the same inputs produces byte-identical statements — the same idempotency property the allocation core relies on, extended to the document layer so a reissued statement differs from the original only where an adjustment genuinely changed it.

The dispute-routing side is where the design earns its keep, and it is modeled explicitly as a finite state machine. A statement is a document; a dispute is a case, and every case occupies exactly one state at a time drawn from a small, closed set: ISSUED, ACCEPTED, DISPUTED, UNDER_REVIEW, ADJUSTED, UPHELD, and CLOSED. The value of a state machine here is that it makes the illegal transitions unrepresentable. A case cannot jump from ISSUED straight to ADJUSTED without passing through review; a closed case cannot silently reopen; an adjustment cannot be applied to a period that was never disputed. The allowed transitions form a directed graph with guards on each edge, and the guard is where the accounting rules live — the transition into ADJUSTED, for instance, is guarded by a check that the resolution produces a forward-dated correction entry rather than an in-place edit of the closed period.

The transitions are deliberately few. From ISSUED, a tenant either accepts (moving toward ACCEPTED and then CLOSED on the happy path) or disputes, moving the case to DISPUTED. Triage moves a DISPUTED case to UNDER_REVIEW, where an analyst examines the specific ground the tenant raised. Review has exactly two exits: ADJUSTED, which recomputes the tenant’s obligation and reissues a corrected statement, or UPHELD, which confirms the original figure with a written rationale. Both terminal outcomes converge on CLOSED, so every case that enters the system has a bounded, auditable path to resolution and no case can linger in an undefined limbo.

Triage is rule-driven rather than ad hoc, because the ground a tenant disputes determines who should look at it and what evidence resolves it. Four dispute types cover the overwhelming majority of real challenges. A measurement dispute contests the denominator — the tenant claims its rentable area, or the total allocable area, is wrong; it routes to whoever owns the lease abstraction and the BOMA-basis measurements. An exclusion dispute claims a cost that the tenant negotiated out of its obligation nonetheless appears on the statement; it routes to the exclusion registry owner. A cap dispute asserts that a controllable expense cap should have limited a pool and did not; it routes to the cap-schedule owner. A math dispute alleges the arithmetic itself is wrong — a share that does not reconcile, a stop applied twice; it routes to the calculation core, and it is the type most often resolved by simply replaying the audit trail. Classifying the dispute at intake is what lets the workflow attach the right evidence and the right reviewer instead of treating every challenge as a generic complaint.

Time is a first-class concern in the design. Each case carries an issued timestamp, a response deadline derived from the lease’s audit and dispute window, and an SLA clock that ages while the case sits in DISPUTED or UNDER_REVIEW. Aging is the metric that keeps the workflow honest: a case that has aged past its lease-granted window without a landlord response is a liability, and the routing layer surfaces those cases before they breach rather than after. A statement expressed as tenant_balance=reconciled_obligation−estimated_billedtenant\_balance = reconciled\_obligation - estimated\_billed is trivial arithmetic; the value the workflow adds is guaranteeing that when that balance is contested, the contest is classified, routed, aged, and resolved through transitions that leave a record.

Python Implementation

The data contracts come first. A StatementLine carries the money and the four traceability fields; a TenantStatement aggregates lines and enforces the reconciliation invariant; a DisputeState enum plus a transition function encode the legal moves of the case machine. All monetary values are decimal.Decimal, quantized to cents with an explicit rounding mode, because a statement that disagrees with the allocation by a rounding artifact is a statement a tenant will dispute on principle.

from __future__ import annotations

from decimal import Decimal, ROUND_HALF_UP
from enum import Enum

from pydantic import BaseModel, Field

CENTS = Decimal("0.01")


class StatementLine(BaseModel):
    """One charge line on a tenant statement, fully traceable to its origin.

    Every line binds a money amount to the pool it came from, the denominator
    used to compute the tenant's share, the rule version in force at close, and
    any stop or cap that modified the raw allocation. A line without these
    fields is not defensible under a lease audit right.
    """

    pool_id: str
    description: str
    tenant_share_pct: Decimal = Field(..., ge=0, le=1)   # fraction, not display %
    denominator_rsf: Decimal = Field(..., gt=0)          # BOMA total allocable area
    rule_version: int = Field(..., ge=1)
    modifier: str | None = None                          # e.g. "cap v7", "base-year stop"
    recoverable_amount: Decimal = Field(..., ge=0)

    def quantized(self) -> Decimal:
        """The line amount rounded to cents for display and tie-out."""
        return self.recoverable_amount.quantize(CENTS, ROUND_HALF_UP)


class TenantStatement(BaseModel):
    """A reconciliation statement for one tenant and one closed period."""

    tenant_id: str
    period: str                                          # e.g. "2025"
    lines: list[StatementLine]
    estimated_billed: Decimal = Field(..., ge=0)
    audit_ref: str                                       # pointer into the immutable trail

    def reconciled_obligation(self) -> Decimal:
        """Sum of all charge lines, quantized to cents."""
        total = sum((line.quantized() for line in self.lines), Decimal("0"))
        return total.quantize(CENTS, ROUND_HALF_UP)

    def balance(self) -> Decimal:
        """Positive = tenant owes a true-up; negative = tenant is owed a credit."""
        return (self.reconciled_obligation() - self.estimated_billed).quantize(
            CENTS, ROUND_HALF_UP
        )

The assembly function is a pure fold from finalized allocations to a statement. It never computes a share; it reads the frozen amount produced by the allocation core and attaches the traceability the contract requires.

from __future__ import annotations

from decimal import Decimal


class StatementTieOutError(Exception):
    """Raised when assembled lines do not reconcile to the expected obligation."""


def assemble_statement(
    tenant_id: str,
    period: str,
    allocations: list[StatementLine],
    estimated_billed: Decimal,
    audit_ref: str,
) -> TenantStatement:
    """Build a tenant statement from finalized allocation lines.

    The lines are formatted, not recomputed. The function asserts the
    per-tenant reconciliation invariant before returning, so a statement that
    does not tie out is never emitted to a tenant.
    """
    statement = TenantStatement(
        tenant_id=tenant_id,
        period=period,
        lines=allocations,
        estimated_billed=estimated_billed,
        audit_ref=audit_ref,
    )

    expected = sum((ln.quantized() for ln in allocations), Decimal("0")).quantize(CENTS)
    if statement.reconciled_obligation() != expected:
        raise StatementTieOutError(
            f"{tenant_id}: lines sum to {statement.reconciled_obligation()} "
            f"!= expected {expected}"
        )
    return statement

The dispute machine is a state enum and a guarded transition function. The transition table is the single source of truth for what is legal; the guards enforce the accounting discipline, most importantly that resolving a dispute on a closed period produces a forward-dated correction rather than mutating history.

from __future__ import annotations

from enum import Enum


class DisputeState(str, Enum):
    ISSUED = "issued"
    ACCEPTED = "accepted"
    DISPUTED = "disputed"
    UNDER_REVIEW = "under_review"
    ADJUSTED = "adjusted"
    UPHELD = "upheld"
    CLOSED = "closed"


# Allowed transitions: current state -> the states it may move to.
_ALLOWED: dict[DisputeState, frozenset[DisputeState]] = {
    DisputeState.ISSUED: frozenset({DisputeState.ACCEPTED, DisputeState.DISPUTED}),
    DisputeState.ACCEPTED: frozenset({DisputeState.CLOSED}),
    DisputeState.DISPUTED: frozenset({DisputeState.UNDER_REVIEW}),
    DisputeState.UNDER_REVIEW: frozenset({DisputeState.ADJUSTED, DisputeState.UPHELD}),
    DisputeState.ADJUSTED: frozenset({DisputeState.CLOSED}),
    DisputeState.UPHELD: frozenset({DisputeState.CLOSED}),
    DisputeState.CLOSED: frozenset(),   # terminal: a closed case never reopens
}


class IllegalTransition(Exception):
    """Raised when a dispute is moved along an edge the machine forbids."""


def transition(
    current: DisputeState,
    target: DisputeState,
    *,
    creates_forward_adjustment: bool = False,
) -> DisputeState:
    """Move a dispute case from one state to the next, or refuse.

    The move into ADJUSTED is guarded: an adjustment on a closed period must
    produce a new, forward-dated correction entry. Editing the closed period in
    place would corrupt recognized revenue under ASC 842, so the guard rejects
    any adjustment that does not carry a forward correction.
    """
    if target not in _ALLOWED[current]:
        raise IllegalTransition(f"{current.value} -> {target.value} is not allowed")

    if target is DisputeState.ADJUSTED and not creates_forward_adjustment:
        raise IllegalTransition(
            "adjustment must generate a forward-dated correction, not an in-place edit"
        )
    return target

The three properties that make this production-grade are the same ones the allocation core insists on. Money never touches float, so a statement always agrees with the run to the cent. The transition table makes illegal case moves impossible to express rather than merely discouraged. And the ADJUSTED guard turns the most important accounting rule in this domain — never edit a closed period in place — into code the workflow cannot bypass.

Validation Rules & Edge Cases

The defining edge case is a dispute against a period that has already closed, which is the normal case rather than the exception, because disputes arrive after statements go out and statements go out after periods close. The rule is absolute: a resolved adjustment never mutates the closed period. Instead it generates a new, forward-dated correction entry — a credit or an additional charge posted to an open period — that references the original statement and the dispute that produced it. This is not a stylistic preference; under FASB ASC 842 lease accounting guidelines, the reconciliation period is a recognized-revenue snapshot, and rewriting a closed period’s allocations after statements were issued corrupts recognized revenue and can force a restatement. The forward-dated correction preserves the original statement, its audit fingerprint, and its reproducibility while still making the tenant whole, which is exactly the balance an auditor expects to see.

Partial acceptance is common and must be modeled precisely. A tenant frequently accepts most of a statement and disputes a single pool — the landscaping cap, say, while agreeing the utilities and security lines are correct. The workflow treats the accepted lines as settled and opens a dispute case scoped to the contested pool only, so the undisputed balance can be collected while the narrow question is reviewed. Modeling partial acceptance at line granularity, rather than forcing an all-or-nothing response, keeps the aging clock running only on the genuinely contested amount and prevents a small challenge from freezing an entire true-up.

Audit-right timelines are a hard validation, not a courtesy. Most commercial leases grant the tenant a bounded window — often ninety to one hundred eighty days after the statement is issued — to request supporting documentation or file a dispute, and a matching window within which the landlord must respond. The workflow computes both deadlines from the issued date at intake and validates every incoming dispute against the tenant’s window: a dispute filed after the lease’s audit right has lapsed is recorded but flagged as out-of-window, and a landlord response approaching its own deadline is escalated before it breaches. Treating these windows as data attached to the case, rather than as tribal knowledge in a property manager’s inbox, is what prevents a missed deadline from becoming a waived right.

Duplicate disputes need explicit handling because tenants, and tenants’ auditors, resubmit. A second dispute against the same tenant, period, and pool while an existing case is open must not create a parallel case; the workflow deduplicates on that key and attaches the new correspondence to the existing case rather than spawning a rival state machine that could resolve two different ways. The final validation closes the loop back to the contract: any reissued statement produced by an ADJUSTED resolution must itself satisfy the reconciliation invariants — the tenant’s lines still sum to the corrected obligation, and the pool still ties out across all tenants once the correction is included — so an adjustment can never quietly break the arithmetic it was meant to fix.

Integration Points

The dispute workflow is not a terminus; its resolved outputs flow back into the calculation core and out to the ledger. When a case resolves as ADJUSTED, the forward-dated correction it produces is an input to year-end CAM reconciliation and true-ups: the correction becomes a reconciling item in the next true-up cycle, carrying its dispute reference so the true-up can explain exactly why a tenant’s forward balance differs from a naive estimate-versus-actual calculation. This is the mechanism by which a resolved dispute never disappears — it is preserved as a traceable adjustment that the year-end process consumes, rather than a manual credit memo that leaves no trail.

On the inbound side, the workflow does not wait for tenants to find every error. The variance bands that auto-flag suspicious lines before a statement is even issued come from threshold tuning for allocation accuracy: a line whose year-over-year movement or whose deviation from a portfolio benchmark exceeds a calibrated band is flagged for internal review, so the landlord catches a mis-mapped GL pool before the tenant does. A statement that has passed its variance gates is measurably less likely to generate a dispute, and a line that does get disputed is easier to resolve because the variance analysis already identified whether it is an outlier. The generator also draws its exclusion and cap context from the same rule set the allocation core resolved, so a cap or exclusion dispute is routed with the exact rule version already attached, and the reviewer opens the case with the evidence in hand rather than hunting for it.

The workflow’s own telemetry is an integration point in its own right. Each case emits its state, its dispute type, and its age, which lets a portfolio-level dashboard answer the questions that actually govern a reconciliation season: how many statements were accepted without challenge, which pools attract disproportionate measurement or cap disputes, and whether any case is aging toward a lease-window breach. A pool that generates disputes across many tenants is usually a signal that a rule needs attention upstream — a denominator that drifted, a cap that reset on the wrong boundary — rather than a coincidence of unhappy tenants, and feeding that pattern back to the rule owners is how the output layer improves the calculation core instead of merely absorbing its errors. The same telemetry also proves diligence: a landlord that can show every dispute was acknowledged, classified, and resolved inside the lease window has a far stronger position than one relying on an inbox and a memory.

Testing & Verification

Two families of tests protect this layer, and they map directly onto its two failure surfaces. The first family is statement tie-out: fixtures assert that assembled statements reconcile to the pool and to the tenant obligation. A representative fixture builds a small building — three tenants, two pools — runs the allocation core, assembles statements, and asserts that the sum of every tenant’s lines equals that tenant’s reconciled obligation and that the sum across tenants of each pool’s lines equals the pool’s recoverable amount. Tie-out tests catch the class of defect a tenant would otherwise catch for you.

from decimal import Decimal


def test_statement_ties_out_to_obligation() -> None:
    lines = [
        StatementLine(
            pool_id="L-04",
            description="Landscaping",
            tenant_share_pct=Decimal("0.0321"),
            denominator_rsf=Decimal("412900"),
            rule_version=7,
            modifier="controllable cap v7",
            recoverable_amount=Decimal("18240.00"),
        ),
        StatementLine(
            pool_id="U-02",
            description="Utilities",
            tenant_share_pct=Decimal("0.0321"),
            denominator_rsf=Decimal("412900"),
            rule_version=3,
            recoverable_amount=Decimal("9510.55"),
        ),
    ]
    stmt = assemble_statement(
        tenant_id="T-1007",
        period="2025",
        allocations=lines,
        estimated_billed=Decimal("26000.00"),
        audit_ref="run:2025:sha256:9f3c",
    )
    assert stmt.reconciled_obligation() == Decimal("27750.55")
    # Tenant under-paid its estimate, so a forward true-up balance is owed.
    assert stmt.balance() == Decimal("1750.55")

The second family is legal state-transition coverage: the machine must accept every legal edge and reject every illegal one, and the ADJUSTED guard must reject an adjustment that fails to carry a forward-dated correction. Rather than test a handful of paths by hand, the suite enumerates the full state cross-product and asserts that exactly the edges in the transition table succeed.

import pytest


def test_only_declared_edges_are_legal() -> None:
    for src in DisputeState:
        for dst in DisputeState:
            if dst in _ALLOWED[src]:
                # ADJUSTED needs the forward-correction guard satisfied.
                ok = transition(src, dst, creates_forward_adjustment=True)
                assert ok is dst
            else:
                with pytest.raises(IllegalTransition):
                    transition(src, dst, creates_forward_adjustment=True)


def test_adjustment_requires_forward_correction() -> None:
    with pytest.raises(IllegalTransition):
        transition(
            DisputeState.UNDER_REVIEW,
            DisputeState.ADJUSTED,
            creates_forward_adjustment=False,
        )

Enumerating the cross-product means a future edit that accidentally adds an edge — letting a CLOSED case reopen, say — fails the suite immediately, because the test derives its expectations from the same table the code enforces. Together the two families verify the arithmetic a tenant checks and the process a court would.

Frequently Asked Questions

What is a tenant actually entitled to audit on a CAM statement? Under a typical commercial lease audit right, a tenant may inspect the documentation supporting each recoverable charge: the pool the charge draws from, the denominator used to compute its share, the rule or lease provision that governed the pool, and any stop, cap, or exclusion applied. A defensible statement exposes all four on each line and points to an immutable audit trail, so the tenant’s auditor can trace a printed amount back to a general ledger dollar. The audit right is bounded by the lease’s window — commonly ninety to one hundred eighty days after issuance — after which the statement is generally deemed accepted.

How do you correct a statement that has already been issued? You do not edit it in place. A closed reconciliation period is a recognized-revenue snapshot under ASC 842, so a resolved correction generates a new, forward-dated adjustment entry — a credit or additional charge posted to an open period — that references the original statement and the dispute. The original statement, its numbers, and its audit fingerprint remain intact and reproducible, while the forward-dated correction makes the tenant whole in the next cycle. This is why the dispute machine’s transition into an adjusted state is guarded to reject any resolution that lacks a forward correction.

What service levels should govern CAM dispute resolution? The lease sets the outer bounds — the tenant’s dispute window and the landlord’s response window — and the workflow turns those into an SLA clock that ages while a case sits open. Practical targets are an acknowledgement within a few business days of a dispute being filed, a triage classification into a measurement, exclusion, cap, or math category shortly after, and a substantive response comfortably inside the lease’s response window. Aging reports surface cases approaching a breach before the deadline passes, because a missed response window can waive the landlord’s position.

What makes a CAM statement defensible in a dispute? Reproducibility. A defensible statement is one where every line ties to a pool, a denominator, and a versioned rule; where the tenant’s lines sum exactly to the obligation and every pool ties out across all tenants; and where the whole run can be reconstructed from an immutable audit trail without anyone reconstructing it from memory. When those conditions hold, a dispute becomes a narrow, named question — this denominator, this cap version — rather than a challenge to the landlord’s credibility, and most disputes resolve as upheld with a documented rationale rather than as an adjustment.

Closing

The output layer is where the discipline of the allocation core either pays off or falls apart in front of a tenant. A statement assembled as a pure fold over finalized allocations, with every line traceable to a pool, a denominator, and a rule version, converts a reconciliation from an assertion into an argument the landlord can win. The dispute machinery behind it — a closed set of states, guarded transitions, type-driven triage, and forward-dated corrections that never touch a closed period — turns the inevitable pushback into a bounded, aged, auditable process rather than a scramble in a property manager’s inbox. The generator draws its inputs from implementing pro-rata allocation algorithms and its early-warning flags from threshold tuning for allocation accuracy, and it feeds resolved adjustments forward into year-end CAM reconciliation and true-ups, closing the loop between what the engine computes and what the tenant ultimately pays.