A cap table answers one question: how far can volume fall before a margin line breaks. Most of the ones I have read this year cannot answer it, and not because the arithmetic is wrong. It is because the table contains rows that are not caps, and nothing in the table says which ones.
The test fits in one line.
A step caps a distance only if its trigger is a function of the axis variable.
If the axis is completed payments per month, a row can bound a distance in completed payments only if the thing that fires it moves with completed payments. A condition that can be true at any volume cannot say how far you can go.
Three rows that look identical in a spreadsheet, axis N = completed payments per month:
| row | trigger | bounds a distance in N? |
|---|---|---|
| volume tier: above 20,000 completions, lower fee | N |
yes, the trigger is the axis |
| accounts over 50 seats get 10% off | headcount | no, fires at N = 400 or N = 90,000 |
| commitment renews 1 April | a date | no, fires at any N |
The second and third are real terms. They are not caps. A row that says "cap" and triggers on headcount is worse than no row at all, because it occupies the place where the answer should be and nobody goes looking for the missing one.
What replaces it is a second table. Which is the rest of this post.
A cap row has one job: it measures an interval
Take a merchant acquirer with three invented numbers:
-
N0 = 25,000completions per month -
p0 = 9.0pmargin per completion -
F = 180,000pfixed cost per month (£1,800)
Break-even volume is where N * p = F, so N = F / p = 20,000. Distance down is 25,000 - 20,000 = 5,000 completions. That is the row.
Now add the volume tier: above 20,000 completions the fee drops and the margin per completion is 8.0p. If that 8.0p applies to all volume once the threshold is crossed (a blended tier), break-even becomes 180,000 / 8.0 = 22,500 and the distance is 2,500. If it applies only above the threshold (a marginal tier), the break-even does not move at all: 20,000 * 9.0 = 180,000p is exactly the fixed cost, so the distance stays 5,000.
The table that prints 5,000 is not miscalculated. Every number in it is correct. Under the blended shape it measured an interval in which 9.0p applies to no completion at all: from 22,500 up to 25,000, every payment earns 8.0p. The row was computed with the margin at the top of the page rather than the margin in force over the range it claims to measure.
That is the whole defect in one row. A cap row may only use a p that holds over the entire interval between the break-even and the volume you are at. If p changes inside that interval, the row is not approximate. It is measuring nothing.
The same thing happens across time, which is harder to see. Raise a rail cost by 0.4p on 15 March and p goes from 9.0 to 8.6. The distance becomes 4,070. Now the table has three numbers, 5,000 and 4,070 and 2,500, all correct, and no two of them comparable:
| row | p in force | distance down | what the reader is told |
|---|---|---|---|
| pre-March, no tier | 9.0p | 5,000 | right for a merchant that no longer exists |
| post-March, no tier | 8.6p | 4,070 | right as of a date the row does not print |
| pre-March, tier above 20,000 | 8.0p | 2,500 blended / 5,000 marginal | right, and half of the flat row only if the tier is blended |
| post-March, tier above 20,000 | 7.6p | 1,316 blended / 3,947 marginal | right only if the tier is blended, and then about a third of the flat row |
A single p for the whole table cannot show that rows either side of a revision are incomparable, because the thing that changed is in no row. Two true numbers, a meaningless pair.
Two tables, two readers, two different times
The fix is not a better column. It is two tables with different keys, read by different people at different moments.
The cap table, keyed on N. Columns: from_N, the p in force as of that row's date, the distance, and valid_until. Read once, by whoever is deciding how far they can go.
The revision log, keyed on a date. Columns: the date, which component of p moved, old value, new value. Read at settlement, by whoever is reconciling a row against what actually happened.
The readers do not overlap. The cap table answers "how far can we go". The revision log answers "which p did this row use". One table cannot do both jobs, because the first is keyed on volume and the second on time, and a row with two keys is a row that can disagree with itself.
Each cap row then carries p as of its own date, not the table's. That is boring, it is what an as-of stamp is for, and it is the part that gets skipped because nothing fails in a demo.
The validity column carries an owner
valid_until on its own lies quietly, because three parties set the clocks and they do not agree:
- the source sets the fact revision (
pis only true while the rail cost behind it holds) - the issuer sets the authorisation window on a card payment
- the contract sets its own renewal date
- your own model sets the window you invented
So the column is valid_until plus owner. When a row's expiry is owned by a party other than the one the row is being compared against, the honest render is NOT_COMPARABLE reason=expiry_owner_mismatch, not expired. And when the next non-volume step is not known yet, the row prints unknown. It does not borrow a date from the renewal clause to look finished. A borrowed date is a claim the row cannot support.
Five things to check before a table is a table
- Every row triggers on the axis variable. Rows that trigger on headcount or a date move to the terms log.
- Every row names the
pin force over its own interval, the interval does not cross a change inp, and a tier row names its shape: blended or marginal, because the same threshold moves the break-even in one and not the other. - Every row carries an as-of date for its
p. - Every row's expiry names its owner, and prints
unknownwhen there is none. - The delta column is not stored. Distances and differences are derived at read time, because a stored third number is one that can disagree with the two it came from.
A table that passes the first four and fails the fifth will still print numbers. It will print them until somebody reconciles one and finds the pair was never comparable. That is the failure mode worth naming: nothing errors, the row looks the same, and the only person who can see it is the one who asks which p the row was measured with.
Correction, 13 November
The paragraph that halves the distance was written as if "a tier above 20,000" settled the arithmetic. It does not. A blended tier gives 2,500 and a marginal tier gives 5,000, and a reader cannot tell which one they have from the word "tier". So the sentence it measured an interval in which 9.0p applies to no completion at all is true for a blended tier and false for a marginal one, where the row is simply right.
Arun rajkumar caught it the next morning, and the consequence is his rather than mine: being keyed on the axis is necessary and not sufficient, because a marginal tier's trigger is a function of N and still does not move the break-even when the threshold sits on it. The table needs the shape before any row in it means anything.
Where this came from
This is the second half of an argument running under arun rajkumar's piece on payment webhooks and reconciliation. His break-even distances were the raw material; the axis test and the owner column came out of that thread and he took the corrections further than I did. The reconciliation version of the same defect is in the intent-record thread, where it renders as reference_mismatch: every number right, the pair meaningless.
If you have a cap table that passes item 1 and fails item 2, send me the row. That is the case I want to see, and it is one line to check.
Appendix: the harness
The expiry-owner relation above is not a preference. It is a file that runs, and the file is below so you can run it without asking me for anything: python3 settlement.py, standard library only, exit code 0 only if every invariant holds.
Two of the four mutants I built against it are invisible to render(). A render catches a wrong verdict. Only a schema assertion catches a wrong record. That is why the file has both, and why the no-op mutation has to survive: a harness that reports its own no-op as caught is measuring itself, not the tests.
"""
Settlement record + render, and a mutation harness that actually runs the tests.
Four-field settlement (call_id, reference_rev, settled_at, value), verdict derived
at read time by render() over the (commit, settlement) pair. Expiry carries an
owner; the owner bounds the comparison only if that owner can invalidate the basis.
The harness below is the point of this file: every mutant is a variant
implementation executed against the same test list. A mutant is caught when at
least one test fails, not when the mutant's own function says so. A no-op
mutation must survive; if it is reported caught, the harness is broken.
Run: python3 settlement.py (exit 0 iff every invariant holds)
"""
import inspect
from dataclasses import dataclass, fields
from decimal import Decimal
from datetime import datetime, timedelta
SETTLEMENT_FIELDS = {"call_id", "reference_rev", "settled_at", "value"}
# --------------------------------------------------------------------------
# the implementation under test
# --------------------------------------------------------------------------
SOURCE = r'''
from dataclasses import dataclass, fields
from decimal import Decimal
from datetime import datetime, timedelta
SETTLEMENT_FIELDS = {"call_id", "reference_rev", "settled_at", "value"}
def dt(s):
return datetime.fromisoformat(s.replace("Z", "+00:00"))
@dataclass(frozen=True)
class Expiry:
at: datetime
owner: str
@dataclass(frozen=True)
class Commit:
call_id: str
reference_rev: int
observed_at: datetime
value: Decimal
expiry: Expiry = None
@dataclass(frozen=True)
class Settlement:
call_id: str
reference_rev: int
settled_at: datetime
value: Decimal
@dataclass(frozen=True)
class Ack:
digest: str
holder: str
def render(commit, settlement, now, invalidators):
"""now and invalidators are required: the function under test does not
supply the clock, and does not default the parties that can invalidate
the basis."""
if settlement is None or settlement.call_id != commit.call_id:
age = int((now - commit.observed_at).total_seconds() // 60)
return "NO_SETTLEMENT basis=%d age=%dm" % (commit.reference_rev, age)
if settlement.reference_rev != commit.reference_rev:
return ("NOT_COMPARABLE reason=reference_mismatch %d:%d"
% (commit.reference_rev, settlement.reference_rev))
if commit.expiry is not None and settlement.settled_at > commit.expiry.at:
if commit.expiry.owner in invalidators:
return ("NOT_COMPARABLE reason=expired owner=%s at=%s"
% (commit.expiry.owner, commit.expiry.at.isoformat()))
return ("NOT_COMPARABLE reason=expiry_owner_cannot_invalidate owner=%s"
% commit.expiry.owner)
delta = settlement.value - commit.value
if delta == 0:
return "PASS basis=%d delta=0.00 settled_in_window" % commit.reference_rev
return "FAIL basis=%d delta=%s" % (commit.reference_rev, delta)
def provenance(digest, ack, attempts):
if ack is not None and ack.digest == digest and ack.holder != "operator":
return "witnessed"
if attempts:
return "issued"
return "self_attested"
'''
def load(source):
ns = {}
exec(compile(source, "<variant>", "exec"), ns)
return ns
# --------------------------------------------------------------------------
# fixtures and tests, written against a namespace so they can run on any variant
# --------------------------------------------------------------------------
def fixtures(ns):
C = ns["Commit"]("c1", 8812, ns["dt"]("2026-11-12T06:00:00Z"), ns["Decimal"]("100.00"),
ns<a href="ns["dt"]("2026-11-12T06:15:00Z"">"Expiry"</a>, "issuer"))
S = ns["Settlement"]
return dict(
C=C,
S_OK=S("c1", 8812, ns["dt"]("2026-11-12T06:04:12Z"), ns["Decimal"]("100.00")),
S_LOW=S("c1", 8812, ns["dt"]("2026-11-12T06:04:12Z"), ns["Decimal"]("97.00")),
S_STALE=S("c1", 8900, ns["dt"]("2026-11-12T06:04:12Z"), ns["Decimal"]("100.00")),
S_LATE=S("c1", 8812, ns["dt"]("2026-11-12T07:41:03Z"), ns["Decimal"]("100.00")),
t=ns["dt"],
D=ns["Decimal"],
)
def test_equal(ns):
f = fixtures(ns)
assert ns["render"](f["C"], f["S_OK"], f["t"]("2026-11-12T06:10:00Z"),
{"issuer"}) == "PASS basis=8812 delta=0.00 settled_in_window"
def test_unequal(ns):
f = fixtures(ns)
assert ns["render"](f["C"], f["S_LOW"], f["t"]("2026-11-12T06:10:00Z"),
{"issuer"}) == "FAIL basis=8812 delta=-3.00"
def test_no_settlement_3a(ns):
# case 3a: read at 06:20 against a commit observed at 06:00 is 20 minutes
f = fixtures(ns)
assert ns["render"](f["C"], None, f["t"]("2026-11-12T06:20:00Z"),
{"issuer"}) == "NO_SETTLEMENT basis=8812 age=20m"
def test_no_settlement_clock_is_the_callers(ns):
f = fixtures(ns)
a = ns["render"](f["C"], None, f["t"]("2026-11-12T06:20:00Z"), {"issuer"})
b = ns["render"](f["C"], None, f["t"]("2026-11-12T06:35:00Z"), {"issuer"})
assert a.endswith("age=20m") and b.endswith("age=35m")
def test_reference_mismatch(ns):
f = fixtures(ns)
assert ns["render"](f["C"], f["S_STALE"], f["t"]("2026-11-12T06:10:00Z"),
{"issuer"}).startswith("NOT_COMPARABLE reason=reference_mismatch 8812:8900")
def test_expired_issuer_bounds_merchant_basis(ns):
# the issuer's authorisation clock governs a merchant comparison because the
# issuer can invalidate the basis, even though the issuer is not the counterparty
f = fixtures(ns)
assert ns["render"](f["C"], f["S_LATE"], f["t"]("2026-11-12T08:00:00Z"),
{"issuer", "rail"}).startswith("NOT_COMPARABLE reason=expired owner=issuer")
def test_expiry_owner_who_cannot_invalidate(ns):
f = fixtures(ns)
assert ns["render"](f["C"], f["S_LATE"], f["t"]("2026-11-12T08:00:00Z"),
{"rail"}).startswith("NOT_COMPARABLE reason=expiry_owner_cannot_invalidate")
def test_settlement_is_four_fields(ns):
assert {x.name for x in ns["fields"](ns["Settlement"])} == ns["SETTLEMENT_FIELDS"]
def test_commit_has_no_label(ns):
assert "provenance" not in {x.name for x in ns["fields"](ns["Commit"])}
def test_settlement_has_no_verdict(ns):
names = {x.name for x in ns["fields"](ns["Settlement"])}
assert not names & {"verdict", "status", "delta"}
def test_render_takes_no_defaults(ns):
# a default clock or a default invalidator set is a record that supplies its
# own basis; no call that always passes them can fail on it
sig = inspect.signature(ns["render"])
for name in ("now", "invalidators"):
assert sig.parameters[name].default is inspect.Parameter.empty
def test_render_refuses_a_missing_clock(ns):
# a fallback clock is invisible to every test that always supplies one, so the
# suite needs the test where the argument is absent and refusal is the answer
f = fixtures(ns)
try:
ns["render"](f["C"], None, None, {"issuer"})
except (TypeError, ValueError):
return
raise AssertionError("render invented a clock instead of refusing")
def test_provenance_degrades(ns):
P, Ack = ns["provenance"], ns["Ack"]
assert P("d1", None, 0) == "self_attested"
assert P("d1", None, 3) == "issued"
assert P("d1", Ack("d1", "operator"), 1) == "issued" # holder is the writer
assert P("d1", Ack("d1", "client-a"), 1) == "witnessed"
assert P("d1", Ack("d2", "client-a"), 1) == "issued" # digest mismatch
TESTS = [
test_equal, test_unequal, test_no_settlement_3a, test_no_settlement_clock_is_the_callers,
test_reference_mismatch, test_expired_issuer_bounds_merchant_basis,
test_expiry_owner_who_cannot_invalidate, test_settlement_is_four_fields,
test_commit_has_no_label, test_settlement_has_no_verdict,
test_render_takes_no_defaults, test_render_refuses_a_missing_clock, test_provenance_degrades,
]
# --------------------------------------------------------------------------
# mutations: source substitutions, each applied to the module text
# --------------------------------------------------------------------------
MUTATIONS = [
("rev rewritten to match at settlement",
'if settlement.reference_rev != commit.reference_rev:',
'if False:'),
("one window for every party",
'if commit.expiry is not None and settlement.settled_at > commit.expiry.at:',
'if commit.expiry is not None and settlement.settled_at > commit.expiry.at + timedelta(minutes=120):'),
("stored delta",
' value: Decimal\n\n\n@dataclass(frozen=True)\nclass Ack:',
' value: Decimal\n delta: Decimal = Decimal("0.00")\n\n\n@dataclass(frozen=True)\nclass Ack:'),
("provenance label written by the writer",
' expiry: Expiry = None',
' expiry: Expiry = None\n provenance: str = "witnessed"'),
("render supplies its own clock",
' if settlement is None or settlement.call_id != commit.call_id:\n age',
' now = now or commit.observed_at + timedelta(minutes=30)\n if settlement is None or settlement.call_id != commit.call_id:\n age'),
("expiry owner ignored, counterparty rule back",
'if commit.expiry.owner in invalidators:',
'if True:'),
("holder check dropped",
'and ack.holder != "operator"',
''),
("verdict field stored on the settlement",
' settled_at: datetime\n value: Decimal\n\n\n@dataclass(frozen=True)\nclass Ack:',
' settled_at: datetime\n value: Decimal\n verdict: str = "PASS"\n\n\n@dataclass(frozen=True)\nclass Ack:'),
]
def run_suite(ns):
failures = []
for t in TESTS:
try:
t(ns)
except AssertionError as e:
failures.append((t.__name__, str(e)))
except Exception as e:
failures.append((t.__name__, "error: %r" % (e,)))
return failures
def main():
base = load(SOURCE)
base_fail = run_suite(base)
print("baseline: %d/%d pass" % (len(TESTS) - len(base_fail), len(TESTS)))
for n, m in base_fail:
print(" baseline failure %s: %s" % (n, m))
escaped, caught = [], []
for name, old, new in MUTATIONS:
if old not in SOURCE:
raise SystemExit("mutation did not apply, so it proves nothing: %s" % name)
src = SOURCE.replace(old, new, 1)
fails = run_suite(load(src))
if fails:
caught.append((name, [f[0] for f in fails]))
else:
escaped.append(name)
# the no-op mutation must escape. a harness that reports this caught is
# measuring itself, not the tests.
noop_src = "# a mutation that changes no behaviour\n" + SOURCE
noop_caught = bool(run_suite(load(noop_src)))
print("mutants caught: %d/%d" % (len(caught), len(MUTATIONS)))
for name, ts in caught:
print(" caught %-45s by %s" % (name, ", ".join(ts[:3])))
print("escaped: %s" % (escaped or "none"))
print("no-op mutation escaped (harness is not self-agreeing): %s" % (not noop_caught))
ok = not base_fail and not escaped and not noop_caught
print("RESULT:", "OK" if ok else "BROKEN")
return 0 if ok else 1
if __name__ == "__main__":
raise SystemExit(main())
If it prints RESULT: OK on a case you believe is wrong, put the case in the replies. That is the reply I am looking for.
Top comments (0)