A Placeholder Is a Promise

The last pass gave a failing quality check a way to say the user has not given me this yet rather than the draft is wrong, and used it once. This pass swept the rest of the packs for the same shape, and then went after something the sweep before it had tripped over: a field in the module catalog that had been empty since the day it was declared.

Sweeping for the shape, and rejecting the near-misses

The new field is narrow on purpose. A failing check may set it only when the draft contains nothing at all to judge — a check that has something in front of it and finds it wanting must not. That restriction is the whole safety property: widen it into a general softener and every genuine failure gains a way to describe itself as someone else's fault.

Thirty-six checks in the library have the fatal shape — one deterministic check, no model checks, so the test's verdict is the check's verdict and a miss is a hard fail. We read each one against the handler that gates it. Exactly one more qualified.

The rejections were more instructive than the match. The closest miss was a proof-point density check on the value-prop builder: on paper, a check that can only pass on evidence the module never invents. But the handler returns early — "no customer interviews or upload evidence found" — before verification ever runs. The check can only fire where evidence does exist, which makes every failure it reports an ordinary one. The field would have been dead code that looked like a safety property. A survey check reading twelve responses and wanting more is judging something. So is a report check whose numbers do not tie. In each case the draft is not empty; it is wanting. The distinction survived the sweep intact, which is the outcome we wanted more than a large count.

The field that was {} sixty times

The previous pass built a guard that maps a pack's checks to the item types a module writes. It wanted field -> item_type on the write side. The catalog appeared to offer exactly that: every declared item type carried a schema: Record<string, unknown>. It was {}. On all sixty entries, across both catalogs, for as long as the field had existed. Nothing in the codebase ever read it — every consumer takes the name and the label. So the guard fell back to module granularity, and one check passes today on a coincidence rather than a match.

Two honest moves: fill it, and the guard becomes exact while the catalog gains a real contract; delete it, and the codebase stops promising a shape it does not have. The rule going in was to measure the fill first, and never to land a half-filled catalog — worse than either, because it reads as a contract in the places where it happens to be complete.

The shape an item type has is whatever its writers put in the row. Measured against the development database, per declared type: how many rows, how many distinct keys, and how many keys appear on every row — the only keys a required-field contract could name.

Thirteen of the forty-nine declared types with live rows have zero such keys. Not one key present on every row. They are the highest-volume types in the product: the pain type has four hundred rows, thirty-four distinct keys, and twenty-one of them on fewer than one row in ten. One type carries two hundred and eighty-one distinct keys over twenty-two rows. Meanwhile nine declared types have no rows at all — shapes no writer has ever produced — and seventeen types the product writes every day are not in the catalog.

Thirty-six of the types are tractable. That is exactly what makes a partial fill tempting, and exactly why the rule existed.

What the fill actually costs

Writing the schema is the small part. The work is deciding a shape for the thirteen that do not have one — which means reconciling writers that disagree today, a component and an extractor and a seeder each building the row their own way. It means closing the enumeration in both directions. And it means deriving the result, because every honest map in this codebase is regeneration-clean and checked in CI; a hand-maintained catalog with no derivation is the same artifact the placeholder already was, one edit later.

That is a data-modelling program whose every step is a product decision about what an item type is, not a transcription of what it currently happens to be.

So: deleted, with the measurement written down beside it. The type is now the guard — the key no longer compiles, so the placeholder cannot drift back without the work that would make it true.

The general shape

A field that is empty everywhere is not neutral. It reads as a contract to the next person who needs one, and the sweep that trusted it silently lost its precision rather than failing. The cheapest thing a codebase can do is promise something in a type and never deliver it, because nothing goes red — the next tool built on top just quietly grades at the wrong granularity.

Both halves of this pass are the same instinct pointed at different layers: say the true thing about what you have. A check that cannot be met yet should say so instead of failing the draft. A catalog that has no shape to declare should not declare one.