DR-136 — @public is a claim about the code, not a way to quiet knip

DR-136 — @public is a claim about the code, not a way to quiet knip

Context

knip.config.ts carries tags: ['-public'], so a JSDoc @public on an export removes it from knip’s unused list. The config comment states what the tag means: “deliberate library/API surface that no current callsite consumes by name.”

S544 triaged 22 OKF/ontology findings. The first-pass reading — stated before any measurement — was that 11 of them were a knip artefact, because each type is referenced structurally (as a member of an exported parent, or an arm of an exported union) rather than by name, and that @public was therefore the appropriate disposition.

Measurement overturned that for 9 of the 11. bunx ast-dataflow references found zero out-of-file references for the seven lib/okf/bundle-graph.ts types and for BundleNavConcept; un-exporting all of them left bun run typecheck and bunx eslint clean. More decisively, bundle-graph.ts’s own header states the module runs server-side only and is “never imported into a client bundle” — so it is definitionally not library surface, and @public there would have written a false statement into the file while permanently muting the only automated signal at that seam.

Two of the eleven were not artefacts at all. OkfBundleNavConcept was surface a consumer had re-declared instead of importing (bundle-nav.tsx’s local NavRow, field-for-field identical); suppressing would have cemented a third copy. OkfConceptType had zero consumers since its birth commit and no place left to apply itself.

Decision

A knip unused-export finding is resolved by wiring, un-exporting, or deleting the symbol. @public is permitted only where the export genuinely is deliberate external surface and the requirement it serves can be named with its current source; a server-only module never qualifies.

UNDECIDABLE — the requirement cannot be named — is a valid outcome and leaves the finding open. It is not grounds for a suppression.

Alternatives Considered

Tag all eleven @public. One line each, count drops immediately. Rejected: it records the wrong reason the symbols are unreferenced. The true reason for nine of them is “the server half of a mirror nothing checks” (see DR-137), and tagging would have hidden that permanently.

Loosen the counts-only baseline instead. Rejected: the baseline is a ratchet, and raising it to accommodate findings nobody triaged is how the list grew in the first place.

Consequences

• The S544 sweep cleared 12 OKF/ontology types and 4 exports with zero suppressions added: exports 41 → 37, types 30 → 17.
• Un-exporting is now the expected disposition for a structurally-referenced internal type, so the count stays honest without the file lying about itself.
• The counts-only baseline cannot enforce this. .knip-baseline.json records totals; a finding silenced by @public and one resolved by deletion move the number identically. This decision is the only thing distinguishing them, so it binds reviewers, not CI.
• Applies to any future tags:-based suppression added to knip.config.ts, not just @public.