Adoption Is Not Deployment

Two Documents, Two Questions

The manifest says what should be deployed where. It is machine-read and it drives the sync, so it is the declaration of intent. What it does not report is what is actually on disk: a consumer that is not checked out on this machine is skipped with a printed note, so a listed file can be absent for a reason that is nobody's mistake.

The ledger says what is used. And those genuinely differ, in both directions:

A file may be vendored only because another shared file imports it. Present, never called by the app.
A file may be vendored ahead of an intended adoption that has not been wired yet. Present, and the app still has its own implementation.
A surface may be deliberately not a target at all.

So the ledger carries a legend distinguishing has-a-call-site from vendored-as-a-dependency from vendored-and-intended from not-a-target, and it says out loud: read the manifest for what is deployed, read this for what is used.

Why the Distinction Is Not Pedantry

Conflate them and you misreport the system in both directions at once. A full column of deployments looks like full adoption, so the remaining integration work becomes invisible and nobody schedules it. Meanwhile a shared surface that is present everywhere but called in one place looks widely used, so a change to it looks riskier than it is, and it never gets improved.

The precise version costs one legend and a bit of honesty per cell, and it means the table can be used to answer a question rather than to feel good.

A hand-maintained table with columns can lie by exactly one column and look completely normal. A consumer was added as a new column and the rows were never extended, so every row was one value short of its own header — and each row's last two values were read one column to the left. Two surfaces were credited to the wrong application until somebody re-derived the table against real call sites — about a day and a half. Nothing was malformed, nothing rendered oddly, and no reader noticed, because a table with a missing trailing cell looks exactly like a table.

The Fix That Actually Holds

The immediate repair was to re-derive every cell from real call sites rather than from the previous version of the table. That is the right repair, and it is not the durable one — the same error will recur the next time a column is added, because adding a column is one edit and extending the rows is many.

What holds is a check: assert that every row has exactly as many cells as the header, and that every consumer appearing in the manifest appears in the ledger. Both are a handful of lines against a document that is already structured, and both fail loudly on precisely the mistake that is otherwise invisible. A table that describes a system should be checked against that system, or it is a snapshot of somebody's belief on the day they wrote it.

Code

The two checks that make a hand-maintained ledger trustworthy·python

import re


def parse_table(markdown: str) -> tuple[list[str], list[list[str]]]:
    """Header cells and body rows from one markdown table."""
    lines = [ln for ln in markdown.splitlines() if ln.strip().startswith("|")]
    cells = lambda ln: [c.strip() for c in ln.strip().strip("|").split("|")]
    header, rows = cells(lines[0]), [cells(ln) for ln in lines[2:]]
    return header, rows


def test_every_row_matches_the_header(ledger_markdown: str):
    """The failure this catches: a column was added and the rows were
    not extended, so every row's last two values were read one column
    to the LEFT. Nothing was malformed. Nothing rendered oddly. A
    table with a missing trailing cell looks exactly like a table -
    which is why it survived until somebody rebuilt the table from
    real call sites rather than from its previous version.
    """
    header, rows = parse_table(ledger_markdown)
    for row in rows:
        assert len(row) == len(header), (
            f"row {row[0]!r} has {len(row)} cells, header has {len(header)}"
        )


def test_every_deployed_consumer_appears_in_the_ledger(manifest, ledger_md):
    """Deployment and adoption are different questions, but a consumer
    that receives files and appears in NO adoption row is not a
    distinction - it is an omission."""
    header, _ = parse_table(ledger_md)
    deployed = {repo for e in manifest["files"] for repo in e["targets"]}
    for repo in sorted(deployed):
        assert repo in header, f"{repo} receives files but has no column"


# LEGEND - the reason the table can be honest at all:
#
#   ✅ has a real call site in the app
#   ⚙️ vendored ONLY because another shared file imports it
#   ⏳ vendored and intended, not yet wired
#   —  not a target (a reason is required in the cell)
#
# Without these four, every present file reads as an adoption, which
# hides remaining work AND overstates the blast radius of a change.

Exercise

Find a hand-maintained table in your documentation that describes a system — a service matrix, an ownership map, a feature-support grid. Write two assertions against it: every row has the same number of cells as the header, and every entity in the underlying system appears. Run them. Report what you find even if it is nothing.

Hint

Check the most recently added column first. The error enters when a column is appended, and the rows most likely to be short are the ones nobody has edited since — which are also the rows that look most settled and therefore get read most trustingly.