QuoteForge/bible-local/decisions/2026-09-01-article-degraded-token-visibility.md

Decision: unparsed article tokens degrade to a visible category placeholder, never "UNK"

Date: 2026-09-01 Status: active

Context

internal/article builds each segment by parsing a spec token out of the lot_name (CPU model, memory size, GPU model, disk capacity, port speed, wattage). When a lot_name did not match the expected shape the generator failed silently or misleadingly:

• parseCPUModel / parseGPUModel fell back to normalizeModelToken or a literal "UNK" with no signal — and a partial parse (RTX_PRO_6000D → RTX_84GB) produced a plausible but wrong token indistinguishable from a real result;
• NET / PSU emitted UNKNET / UNKPSU;
• MEM / DISK dropped the segment or the capacity and emitted only a terse mem_unknown / disk_unknown warning;
• BuildResult.Warnings existed but nothing consumed it: the preview-article frontend ignored the field and the create/update paths discarded it.

So a new naming shape (a vendor renames a card family, moves memory ahead of the model, glues an architecture onto the token) would silently produce a wrong or truncated article and no one would notice.

A vendor/model catalog in the repo to validate tokens against was rejected — it violates bible/rules/patterns/no-hardcoded-vendors and needs constant upkeep. Detection is therefore limited to structural failure (the name doesn't fit {GROUP}_{VENDOR}_{MODEL}[_{SPEC}…]); semantic drift where a wrong token still parses cleanly cannot be caught automatically and is out of scope.

Decision

1. "UNK" / "UNKNET" / "UNKPSU" are gone. When a spec token can't be parsed the article carries the LOT's lot_category as the token (4xGPU, 2xCPU, 768G+MEM, …) via placeholderToken.
2. Each build*Segment returns a segmentResult{value, degraded, warnings}. Every degraded segment produces a warning that names the offending lot_name and states which category was written instead.
3. BuildResult gains Segments []ResultSegment{Group, Text, Recognized}. Recognized == false marks a segment whose token is a placeholder.
4. parseCPUModel / parseGPUModel return (token, ok); ok == false on the last-ditch fallback path.
5. Consumers surface it:
   • POST /api/configs/preview-article returns segments and warnings; the configurator's article line renders each not-recognized segment highlighted (amber) and lists the warnings beneath it (renderArticleDisplay in web/templates/index.html);
   • create / update / rollback log WARN "article generation degraded" with the server_model, article and warnings.
6. No list of real lot_names or model names is committed to the repo — not as a fixture, not as a golden table. Tests use synthetic names only.

Consequences

• An unrecognised LOT is always visible in the UI (highlighted token + warning) and in server logs — never a silent drop or a bare UNK.
• The stored article string still contains only the placeholder token; the recognized flags are not persisted (regenerated on next save / preview).
• compressArticle now returns []namedSeg (the caller re-joins) so the degraded flags survive compression.
• Structural detection only: a wrong-but-well-formed token (e.g. a future GTX where RTX was expected) still passes. Closing that needs a validation source, deferred pending a server-side structured-attribute contract.
• Covered by TestBuild_UnparseableModel_CategoryPlaceholder and TestParseGPUModel_VendorLetterSuffix.