CAM Reconciliation

Managing Expense Caps and Controllable Limits

A controllable-expense cap is a promise written into a lease: the tenant’s share of the costs the landlord can influence will not grow faster than an agreed rate, no matter what the actual bill looks like. Enforcing that promise is where CAM reconciliation quietly goes wrong. Within the Expense Allocation Logic & Rule Engines pipeline, cap management is the stage that takes a tenant’s allocated controllable amount and clamps it to a lease-defined ceiling — a ceiling that compounds off a base year, sometimes carries unused room forward, and applies only to the controllable slice of the pool. Get the base year wrong, confuse a cumulative cap for a year-over-year one, or apply the ceiling to taxes and insurance that were never subject to it, and the statement overbills by thousands of dollars in a way that survives a casual review and detonates in an audit. This page specifies the data contracts a cap engine consumes, the ceiling math for each cap structure, a runnable typed implementation, and the edge cases that separate a cap that runs unattended from one that quietly overcharges.

Applying a controllable-expense cap during recovery The allocated controllable share (Pn) feeds a ceiling computation (Cn) driven by the cap structure, base year, and rate. A decision tests Pn against Cn: when Pn is at or below the ceiling the full share is recovered; when Pn exceeds the ceiling, recovery is clamped to Cn, carry-forward is tracked for cumulative caps, and the landlord absorbs the overage Pn minus Cn. Allocated controllable share (Pₙ) Compute ceiling (Cₙ) structure · base yr · rate Pₙ > Cₙ? Recover Pₙ in full no overage Clamp to Cₙ track carry-forward Landlord absorbs Pₙ − Cₙ no yes overage
The cap engine clamps each tenant's allocated controllable share to its lease ceiling: at or below the ceiling it recovers in full; above it, recovery is limited to the ceiling and the landlord absorbs the difference.

Prerequisites & Data Contracts

A cap engine computes nothing on its own — it clamps a number other stages produced, so it can only be as correct as the three inputs feeding it. Each must exist and be stable before the engine evaluates a single ceiling.

A controllable-only allocated amount. The engine must never see taxes, insurance, or capital charges. By the time a figure reaches cap logic it has already been split by handling controllable vs non-controllable CAM expenses, stripped of carve-outs by exclusion mapping for tenant-specific CAM, and distributed into a per-tenant share by implementing pro rata allocation algorithms. What arrives is a single Decimal: this tenant’s uncapped controllable recovery for the period. Feed the cap a pool that still contains non-controllable dollars and the ceiling clamps the wrong base, understating what the tenant genuinely owes on the controllable side while masking it behind an unrelated pass-through.

A tenant-scoped cap configuration. Caps are lease facts, keyed by (property_id, tenant_id) and read from the lease abstraction database. Each configuration names the cap structure (fixed, year-over-year, or cumulative), the annual cap rate, the base year the cap references, the base-year controllable amount, and the lease_version that produced it. Versioning is not optional: a reconciliation run reopened two years later must reproduce the exact ceiling in force during the period under review, and a cap rate silently edited in place makes every historical statement unreproducible.

A period history of prior recoveries. Every cap structure except a flat fixed ceiling is path-dependent — it needs to know what came before. A year-over-year cap references the prior year’s billed controllable; a cumulative cap references the base-year amount and the count of elapsed periods. The engine therefore consumes an ordered history of prior recoveries per tenant, and a gap in that history (a skipped reconciliation, an acquired property with no prior data) is a failure mode the engine must detect rather than paper over with a zero.

Rule Design & Cap Ceiling Math

Lease language describes caps in prose; the engine needs a ceiling as a number. Three structures cover almost every commercial lease, and the difference between them is entirely about how the ceiling for period nn is computed from the base year y0y_0, the base-year controllable amount BB, and the annual cap rate rr.

Fixed ceiling. The simplest cap is an absolute dollar limit — often expressed per rentable square foot and multiplied up to the tenant’s area. It does not compound and ignores history:

Cn=BfixedC_n = B_{\text{fixed}}

Year-over-year (non-cumulative) cap. The ceiling resets each year to the prior year’s billed controllable amount grown by the cap rate. Unused room is lost: if actual spend came in under the cap, next year’s ceiling is anchored to that lower actual, not to what the lease would have allowed.

Cn=An−1 (1+r)C_n = A_{n-1}\,(1 + r)

where An−1A_{n-1} is the controllable amount actually billed in the prior period.

Cumulative (compounding) cap. The ceiling compounds off the fixed base year regardless of what was actually billed in between, so unused room carries forward and the landlord can recapture it in a later high-spend year up to the compounded line:

Cn=B (1+r) n−y0C_n = B\,(1 + r)^{\,n - y_0}

The recoverable controllable amount is then the smaller of the actual allocated pool PnP_n and the ceiling, and any excess is absorbed by the landlord rather than passed through:

Rn=min⁡ ⁣(Pn,  Cn)On=max⁡ ⁣(Pn−Cn,  0)R_n = \min\!\left(P_n,\; C_n\right) \qquad O_n = \max\!\left(P_n - C_n,\; 0\right)

The distinction between the cumulative and year-over-year forms is the single most litigated point in cap accounting. On a 5% cap, a base of $100,000, and a year with actual controllable spend of $103,000 in year one, a cumulative cap permits $110,250 in year two (the base compounded twice) while a year-over-year cap permits only $108,150 (last year’s actual grown once). Over a ten-year term the two curves diverge by tens of thousands of dollars per tenant, and the lease says which one applies in a single clause that abstraction must capture exactly.

Cumulative versus year-over-year cap ceilings diverge over a ten-year term On a 5 percent cap with a 100,000 dollar base year, the cumulative ceiling compounds off the fixed base regardless of actuals and climbs to about 155,000 dollars by year ten. The year-over-year ceiling resets each year to the prior year's lower actual and climbs only to about 136,000 dollars. The shaded wedge between them widens from zero to roughly 18,800 dollars, the recoverable room a year-over-year structure permanently gives up. $100k $120k $140k $160k 1 2 3 4 5 6 7 8 9 10 lease year (compounding period since base year) 10-yr gap ≈ $18.8k Cumulative — compounds off fixed base year Year-over-year — resets to prior actual
Same 5% cap, same $100k base: a cumulative cap compounds off the fixed base year while a year-over-year cap re-anchors to each year's lower actual, so the two ceilings diverge into a gap of roughly $18.8k per tenant by year ten.

Python Implementation

The engine below is deterministic and typed, and every monetary value is a Decimal — binary float cannot represent cent amounts exactly, and a cap that compounds a drifting float over a ten-year term produces a ceiling that no longer ties to the lease. Cap configurations are pydantic models so a malformed lease export is rejected at the boundary rather than compounded silently. Compounding uses integer exponentiation from the standard library decimal module (docs.python.org/3/library/decimal.html).

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 CapType(str, Enum):
    """The cap structure a lease clause defines for controllable expenses."""
    NONE = "none"                 # no cap: full controllable share is recoverable
    FIXED = "fixed"               # absolute ceiling, no compounding, ignores history
    YEAR_OVER_YEAR = "yoy"        # ceiling = prior billed * (1 + rate); unused room lost
    CUMULATIVE = "cumulative"     # ceiling = base * (1 + rate) ** elapsed; room carries forward


class CapConfig(BaseModel):
    """Tenant-specific cap terms, read from the lease abstraction database."""
    property_id: str
    tenant_id: str
    lease_version: str
    cap_type: CapType
    cap_rate: Decimal = Decimal("0")        # e.g. Decimal("0.05") for a 5% annual cap
    base_year: int                          # lease-defined year the cap compounds from
    base_amount: Decimal = Decimal("0.00")  # controllable share in the base year
    fixed_ceiling: Decimal | None = None    # required only for CapType.FIXED


class CapResult(BaseModel):
    """The engine's verdict for one tenant-period, carrying an audit trail."""
    tenant_id: str
    period_year: int
    uncapped_amount: Decimal
    ceiling: Decimal | None                 # None when the lease imposes no cap
    recoverable_amount: Decimal
    landlord_absorbed: Decimal
    cap_type: CapType
    lease_version: str


def controllable_ceiling(
    config: CapConfig,
    period_year: int,
    prior_billed: Decimal | None,
) -> Decimal | None:
    """Return the controllable ceiling for a period, or None if uncapped.

    ``prior_billed`` is the controllable amount actually recovered in the
    immediately preceding period; it is required for a year-over-year cap
    and ignored by the fixed and cumulative structures.
    """
    if config.cap_type is CapType.NONE:
        return None

    if config.cap_type is CapType.FIXED:
        if config.fixed_ceiling is None:
            raise ValueError("FIXED cap requires a fixed_ceiling")
        return config.fixed_ceiling.quantize(CENTS, rounding=ROUND_HALF_UP)

    if config.cap_type is CapType.YEAR_OVER_YEAR:
        # Bootstrap from the base amount when no prior period has been billed yet.
        anchor = prior_billed if prior_billed is not None else config.base_amount
        return (anchor * (Decimal("1") + config.cap_rate)).quantize(
            CENTS, rounding=ROUND_HALF_UP
        )

    # CUMULATIVE: compound off the fixed base year, independent of prior actuals.
    elapsed = period_year - config.base_year
    if elapsed < 0:
        raise ValueError("period_year precedes the cap base_year")
    factor = (Decimal("1") + config.cap_rate) ** elapsed  # integer exponent, exact
    return (config.base_amount * factor).quantize(CENTS, rounding=ROUND_HALF_UP)


def apply_cap(
    config: CapConfig,
    period_year: int,
    uncapped_amount: Decimal,
    prior_billed: Decimal | None = None,
) -> CapResult:
    """Clamp a tenant's allocated controllable share to its lease ceiling.

    The recoverable amount is min(pool, ceiling); any excess is absorbed by
    the landlord and never passed through to the tenant.
    """
    ceiling = controllable_ceiling(config, period_year, prior_billed)

    if ceiling is None:
        recoverable = uncapped_amount
        absorbed = Decimal("0.00")
    else:
        recoverable = min(uncapped_amount, ceiling)
        absorbed = max(uncapped_amount - ceiling, Decimal("0.00"))

    return CapResult(
        tenant_id=config.tenant_id,
        period_year=period_year,
        uncapped_amount=uncapped_amount,
        ceiling=ceiling,
        recoverable_amount=recoverable.quantize(CENTS, rounding=ROUND_HALF_UP),
        landlord_absorbed=absorbed.quantize(CENTS, rounding=ROUND_HALF_UP),
        cap_type=config.cap_type,
        lease_version=config.lease_version,
    )

The engine returns a CapResult that records not just the recoverable number but the ceiling it was clamped to, the amount the landlord absorbed, and the lease_version that produced the ceiling. That last field is what makes the result defensible: when a tenant’s consultant disputes a year-end statement, the record replays the exact cap structure, rate, and base year the lease specified for that period.

Validation Rules & Edge Cases

The ceiling math is three formulas; the ways real portfolios break it are not. Each of the following is a failure mode the engine must handle explicitly rather than absorb into a wrong number.

  • Base-year drift. The most common and most expensive cap dispute is a ceiling compounded from the wrong base year. A cumulative cap is B * (1 + r) ** (n - y0); an off-by-one in y0 compounds an extra year of growth into every subsequent period. Pin the base year to the lease_version and never infer it from the earliest available data.
  • Compound versus simple growth. A “5% annual cap” almost always means compounding — (1 + r) ** k, not 1 + k*r. Implementing simple growth understates the ceiling and over-absorbs onto the landlord; implementing compounding when the lease specifies simple over-recovers. The clause governs; the engine must expose both and the abstraction must choose.
  • Cumulative carry-forward. A cumulative cap lets the landlord recapture room left unused in a lean year. A naive engine that clamps each year to that same year’s simple ceiling silently discards recoverable dollars the lease allows — the cumulative structure exists precisely so the compounded base, not the prior actual, is the line.
  • Missing prior-year data. A year-over-year cap needs the prior period’s billed amount. For the first reconciled year, or an acquired property with no history, bootstrap from base_amount rather than defaulting prior_billed to zero — a zero anchor collapses the ceiling to zero and absorbs the entire pool onto the landlord.
  • Caps applied to the wrong pool. A cap governs only controllable expenses. If a non-controllable dollar (property tax, insurance, structural capital) reaches the engine, the ceiling clamps a base the lease never subjected to it. This is why the controllable split and exclusion must both run upstream.
  • Gross-up ordering. When a lease grosses up controllable costs to a stabilized occupancy, the gross-up runs before the cap so the ceiling clamps the normalized figure. Capping first and grossing up second inflates the recovery past the ceiling the lease guarantees.
  • Negative or zero rate. A cap_rate of zero produces a flat ceiling equal to the base; a negative rate (rare, but seen in declining-market concessions) must still compound correctly. Guard against a negative elapsed — a period preceding the base year is a data error, not a ceiling of zero.

Integration Points

Cap management is a clamp late in the pipeline, and its position relative to the stages around it is load-bearing.

  • Runs after allocation. The engine consumes a per-tenant controllable share, so it executes after implementing pro rata allocation algorithms has distributed the pool. This is the second pass of the two-pass allocation model: distribute uncapped, then clamp each tenant to its ceiling.
  • Runs after exclusion. Caps must apply only to genuinely recoverable, controllable dollars, so exclusion mapping for tenant-specific CAM removes carve-outs before the ceiling is computed. Capping a pool still polluted with excluded capital understates the tenant’s true controllable exposure.
  • Feeds the tenant statement. The recoverable_amount is what appears on the year-end true-up statement, and landlord_absorbed is the overage the property owner eats. Both numbers, plus the ceiling and base year, are what a tenant’s audit right entitles them to inspect.
  • Feeds the audit log. Every CapResult carries its lease_version, so the reconciliation is replayable against the exact cap terms in force. Reconciling the ceiling back to the lease clause is the discipline described in best practices for CAM expense exclusion tracking.
  • Calibrates against thresholds. Whether a small overage is worth flagging for review, or a large one is worth a manual hold, is tuned alongside threshold tuning for allocation accuracy, which owns the materiality bands the cap overage is measured against. Cap outcomes are also governed by the recovery percentages standardized in standardizing CAM taxonomies across portfolios.

Testing & Verification

Cap bugs are invisible until a tenant’s lease consultant recomputes the ceiling by hand and finds it a year of compounding too high, so the engine is tested against small fixtures where the correct ceiling is known from the lease math.

from decimal import Decimal


def test_cumulative_compounds_off_base_year() -> None:
    config = CapConfig(
        property_id="P1", tenant_id="T1", lease_version="2026.1",
        cap_type=CapType.CUMULATIVE, cap_rate=Decimal("0.05"),
        base_year=2024, base_amount=Decimal("100000.00"),
    )
    # Two years elapsed: 100000 * 1.05 ** 2 = 110250.00
    result = apply_cap(config, period_year=2026, uncapped_amount=Decimal("115000.00"))
    assert result.ceiling == Decimal("110250.00")
    assert result.recoverable_amount == Decimal("110250.00")
    assert result.landlord_absorbed == Decimal("4750.00")


def test_year_over_year_resets_to_prior_actual() -> None:
    config = CapConfig(
        property_id="P1", tenant_id="T2", lease_version="2026.1",
        cap_type=CapType.YEAR_OVER_YEAR, cap_rate=Decimal("0.05"),
        base_year=2024, base_amount=Decimal("100000.00"),
    )
    # Prior year billed 103000; ceiling = 103000 * 1.05 = 108150.00
    result = apply_cap(
        config, period_year=2026,
        uncapped_amount=Decimal("112000.00"),
        prior_billed=Decimal("103000.00"),
    )
    assert result.ceiling == Decimal("108150.00")
    assert result.landlord_absorbed == Decimal("3850.00")


def test_under_ceiling_recovers_in_full() -> None:
    config = CapConfig(
        property_id="P1", tenant_id="T3", lease_version="2026.1",
        cap_type=CapType.CUMULATIVE, cap_rate=Decimal("0.05"),
        base_year=2026, base_amount=Decimal("80000.00"),
    )
    result = apply_cap(config, period_year=2026, uncapped_amount=Decimal("74500.00"))
    assert result.ceiling == Decimal("80000.00")
    assert result.recoverable_amount == Decimal("74500.00")
    assert result.landlord_absorbed == Decimal("0.00")
    # Conservation: recoverable + absorbed equals the uncapped pool, to the cent.
    assert result.recoverable_amount + result.landlord_absorbed == result.uncapped_amount

The assertions cover the properties that matter: a cumulative cap compounds off the fixed base year, a year-over-year cap resets to the prior actual, an under-ceiling pool passes through untouched, and no dollar is created or destroyed by the clamp. Because every amount is Decimal, the conservation check uses exact equality rather than a floating-point tolerance, so a one-cent leak in the split between recovery and landlord absorption fails the test instead of hiding under isclose.

Frequently Asked Questions

What is the difference between a cumulative cap and a year-over-year cap? A cumulative cap compounds off a fixed base year — the ceiling is the base-year controllable amount grown by the cap rate for every elapsed year, regardless of what was actually billed in between, so unused room in a lean year carries forward and can be recaptured later. A year-over-year cap resets each year to the prior year’s actual billed amount grown by the rate, so unused room is permanently lost. On a long lease the two structures diverge by tens of thousands of dollars per tenant, and the lease clause decides which applies.

Why do so many cap disputes trace back to the base year? Because the base year is the exponent’s anchor. In a cumulative cap the ceiling is base * (1 + rate) ** (year - base_year), so an off-by-one error in the base year compounds an extra full year of growth into every subsequent period. Pinning the base year to the abstracted lease_version, rather than inferring it from the earliest data on hand, is the single highest-leverage correctness control in cap accounting.

Do expense caps apply to property taxes and insurance? Almost never. Caps govern controllable expenses — the costs a landlord can influence, such as janitorial, landscaping, and management fees. Property taxes, insurance premiums, and structural capital are non-controllable pass-throughs and bypass the cap entirely. Letting a non-controllable dollar reach the cap engine clamps a base the lease never subjected to a ceiling, which is why the controllable split runs upstream.

Does a “5% cap” compound or grow simply? It almost always compounds: the ceiling is (1 + rate) raised to the number of elapsed years, not 1 + years * rate. Implementing simple growth understates the ceiling and over-absorbs the overage onto the landlord; implementing compounding when a rare lease specifies a simple cap over-recovers from the tenant. The engine should support both and the lease abstraction must record which the clause specifies.

Where does the capped overage go? When the allocated controllable share exceeds the ceiling, the excess is absorbed by the landlord and never billed to the tenant — that is the entire economic point of a cap. The engine records it as landlord_absorbed so the year-end statement and the audit log both show exactly how many dollars the ceiling shifted off the tenant.

Where This Fits

Cap management is the control point where a raw pro-rata share becomes a lease-honoring recovery — the stage that keeps the promise a tenant negotiated when it signed. By computing a ceiling from the correct cap structure, base year, and rate, clamping the allocated share to it, and recording the overage the landlord absorbs, the engine turns a compounding clause into a penny-exact, replayable number. It sits downstream of implementing pro rata allocation algorithms and exclusion mapping for tenant-specific CAM, reads its terms from the lease abstraction database, and hands its capped figure to the year-end true-up statement — with the correctness of every tenant’s bill riding on whether the ceiling was compounded off the right year.