map: one versioned capability contract instead of five copies

[patchstackdave]

Stacked on #136 — base is davejong/map-import-inventory, so this diff shows only its own change. Rebase after #136 squash-merges.

Why

The closed vocabularies that describe what the map can see — sink kinds, argument roles, candidate families, confidence tiers — were declared independently in five places: the TypeScript unions here, plus separate copies in the layers that consume the map (rule authoring, and the platform that binds a coordinate into a rule).

Adding a capability meant editing all of them, and missing one fails silently: a sink kind this side emits but an authoring layer rejects makes the capability unauthorable; one the binding layer doesn't know makes every flow of that kind unusable. Nothing throws — the capability just never matches, which reads exactly like "not reachable".

That is the same shape as the wrong-pin bugs in the map hardening track: three instances, one lossy representation. The fix is the representation, not a third patch.

What

• src/map/capabilities.ts is the single definition, versioned, with the reasoning that a new member is a contract change rather than a list edit — and that a new sink family owes adversarial corpus cases before it may generate rules, since one capability admits a whole package family at once.
• The TypeScript unions are derived from it ((typeof SINK_KINDS)[number]) rather than declared beside it, which would have been a second copy with the same drift risk.
• capabilities.json is generated and committed, so a vocabulary change shows up as a reviewable diff in the contract instead of appearing silently in dist. npm run capabilities regenerates; --check verifies.
• Deliberately not added to package.json files. The consumers vendor it from source, and the published surface is separately reviewed — the existing pack-safety test caught my first attempt at widening it, which was the correct outcome.

Verification

977 tests, typecheck clean. The drift guard was verified by actually causing drift: adding a member to SINK_KINDS without regenerating fails with "capabilities.json is stale — run npm run capabilities".

The tests defend the contract rather than the values: the manifest must be byte-identical to the emitter's output, must agree with the TS member for member, the auto-promotable tier must remain the single strongest proven tier, and everything the extractor actually emits must fall inside the vocabulary — with a non-vacuity check first, since a fixture producing no sinks would satisfy that trivially.

Consuming layers

The vocabulary is consumed outside this repo. Those layers now vendor capabilities.json and assert conformance against it, so a stale copy is a test failure rather than a silent mismatch. One consumer is still a hand-maintained copy and is tracked separately — until it reads the manifest, it remains the one place drift can occur.

[coderbuds]

Cohesively centralizes and version-controls the capability contract with robust codegen and tests.

🎯 Quality: 94% Elite · 📦 Size: Large — consider splitting if possible

📈 This month: Your 57th PR — above team average · Averaging Excellent

_{See how your team is trending →}

[patchstackdave]

/review