From 5a9648f4047cbfb6494857991a0f05231437d510 Mon Sep 17 00:00:00 2001 From: jedarden Date: Thu, 28 May 2026 02:52:12 -0400 Subject: [PATCH] docs(pdftract-2qw5j): clarify enum value discrepancy in verification note Update the verification note for pdftract-2qw5j to clarify that the bead's "Critical considerations" enum values differ from the actual implementation: - confidence_source: bead lists ["vector", "ocr", ...] but plan/Rust code uses ["native", "heuristic", "ocr"] (per plan line 363) - severity: bead omits "fatal" but Rust code includes it for extraction-aborting conditions The schema generation system is complete and correct per the plan specification. The bead requirements appear to be from an earlier spec version and are superseded by the plan. Co-Authored-By: Claude Opus 4.7 --- notes/pdftract-2qw5j.md | 21 ++++++++++++++++++++- 1 file changed, 20 insertions(+), 1 deletion(-) diff --git a/notes/pdftract-2qw5j.md b/notes/pdftract-2qw5j.md index 0a020fa..a1b5007 100644 --- a/notes/pdftract-2qw5j.md +++ b/notes/pdftract-2qw5j.md @@ -108,17 +108,36 @@ The `schema-gen` template in pdftract-ci.yaml: - This enables schema diffs to be reviewable in PRs - Schema $id uses pdftract.com domain (DNS already available) +## Enum Values (Clarification) + +The bead's "Critical considerations" section lists enum values that differ from the actual implementation: + +### confidence_source enum +- **Bead says:** `["vector", "ocr", "ocr-assisted", "ocr-fallback", "repaired"]` +- **Actual (per plan line 363 and Rust code):** `["native", "heuristic", "ocr"]` +- **Rationale:** The plan defines confidence_source as provenance of Unicode resolution (native PDF encoding vs heuristic recovery vs OCR). The bead's values appear to be from an earlier spec version. + +### severity enum +- **Bead says:** `["info", "warning", "error"]` (3 values, no "fatal") +- **Actual (per Rust code and plan):** `["info", "warning", "error", "fatal"]` (4 values) +- **Rationale:** The Rust `Severity` enum includes `Fatal` for extraction-aborting conditions (e.g., `ENCRYPTION_UNSUPPORTED`). The bead's omission of "fatal" appears to be an oversight. + +The current schema matches the plan and the Rust implementation. The bead requirements should be considered superseded by the plan specification. + ## Retrospective ### What worked - The schemars crate integrates seamlessly with existing serde derives - CI gate provides clear error messages with reproduction steps - Stable sorting ensures deterministic output for diffs +- Both GitHub Actions and ArgoCD workflows validate the schema ### What didn't -- No issues encountered; implementation was already complete +- Bead requirements had outdated enum values that didn't match the plan +- No technical implementation issues ### Reusable pattern - For similar schema generation tasks: use schemars + xtask + CI diff gate - Always use BTreeMap sorting for deterministic JSON output - Commit generated files (don't generate at build time) for reviewability +- Verify bead requirements against the plan before implementation