CNA-BUG-058: LIMITATIONS.md omits the 631 planned public C++ declarations and RELEASE_GATE.md still attributes 654 declarations to CBIND-117

CNA snapshot c1c316b9  ·  Known Issues › Current bugs  ·  source links pinned to c1c316b9

The generated C API limitations document partitions 7,511 of the 8,142 declarations it counts and never mentions the 631 planned ones, and the release-gate note still says the Content Pipeline task owns 654 declarations where the plan records 134.

Identifier

CNA-BUG-058

Category

Bug

Subsystem

Documentation & release tooling

Status

Narrowed (partially fixed; describes only what survives)

Verified against

CNA c1c316b9 (c1c316b9c7a846ce8002809c151fcd1af14942c9)

Severity

Low (a triage suggestion, not a project priority)

Evidence basis

Source-verified: read at TARGET, not executed

Tests touching this area

Yes: see Current tests

Affected contract

docs/c-api/LIMITATIONS.md (generated by tools/c-api/generate_limitations.py) and docs/c-api/RELEASE_GATE.md (generated from tools/c-api/release_gate.json)

Expected behaviour

LIMITATIONS.md is “the document a consumer reads to decide whether to adopt the ABI at all” (release_gate.json) and says it records every declaration that “did not become a callable C route”. Its counts should add up to the inventory total, and the release-gate note should name the live owners of the unmapped backlog as the plan and inventory record them.

Actual behaviour at TARGET

• LIMITATIONS.md says the full matrix records 8,142 declarations, then partitions Fully mapped 7,053, Partially mapped 15 and No C form 443: 7,511. The 631 planned declarations, which have no C route either, appear nowhere, because generate_limitations.py read_rows() keeps only partial and not-applicable rows.
• RELEASE_GATE.md uses “unmapped” for two different sets in adjacent rows: “631 public symbols are still unmapped” (planned) and “443 unmapped in 86 groups” (not applicable).
• The release note (from release_gate.json) says “Content Pipeline continuation records 654 public C++ build-time declarations under open CBIND-117” and names CBIND-120, -121 and -122. plans/plan_binding.md records CBIND-117 as still owning 134 rows after the CBIND-126 scope decision moved the pipeline out of scope (COVERAGE.md lists modules/content-pipeline as excluded), and its open rows as 134 + 3 + 1 + 5 + 5 (CBIND-125) + 320 (CBIND-127) = 468, while COVERAGE.md now counts 631 planned rows; the note omits CBIND-125 and CBIND-127.

Fixed since first recorded: the total is no longer a hand-written 6,415. analyze() takes it from the inventory and render() prints it, so LIMITATIONS.md and COVERAGE.md now state the same 8,142.

Source locations

• docs/c-api/LIMITATIONS.md — The shape of it table and the 9,355 sentence
• tools/c-api/generate_limitations.py — read_rows drops planned rows; analyze and render take the total from the inventory
• docs/c-api/RELEASE_GATE.md — release note and the two 'unmapped' criterion rows
• tools/c-api/release_gate.json — release.note with the 654 figure
• plans/plan_binding.md — row counts of CBIND-117, CBIND-120, CBIND-121, CBIND-122, CBIND-125, CBIND-127
• docs/c-api/COVERAGE.md — module table (631 planned) and the content-pipeline exclusion

Evidence

Checked by reading LIMITATIONS.md, RELEASE_GATE.md, generate_limitations.py and plan_binding.md at c1c316b9. Not executed; the arithmetic is taken from the committed generated documents (COVERAGE.md snapshot: 469 headers, 8142 symbols, 7053 implemented, 15 partial, 631 planned, 443 not applicable). Whether leaving planned rows out was intended is not recorded; the generator's docstring speaks of collapsing “partially mapped and unmapped symbols”, where “unmapped” means not applicable, while the document's first paragraph promises every declaration that did not become a route. Separate entries cover the same document's “Four of the 49 renderers” row and the “0.1.0” labels in FEATURE_MATRIX.md and README.md.

Re-verified at c1c316b9: the committed counts moved (7,053 implemented, 631 planned, 443 not applicable; 1cac65958, bf410474b, 0fc33dac1), but read_rows() still drops planned rows and the release note still says 654 under CBIND-117. Not executed.

Focused reproduction

No focused reproduction is known. Nothing has been invented here; the evidence above is what exists.

Current tests

CApiLimitations (generate_limitations.py --check) proves the document matches its generator and enforces themes, live owners and inventory-derived counts; no rule requires the partition to sum to the total or planned rows to be listed. CApiReleaseGate checks that RELEASE_GATE.md renders from release_gate.json, not that its prose note matches the plan.

Regression test

In generate_limitations.py, add a “Planned” row (with its owning tasks) and assert that the shape table sums to inventory_symbols; in check_release_gate.py, derive the backlog sentence from the plan's row counts instead of prose.

Blast radius

Readers deciding whether to adopt the C ABI; no behaviour is affected.

Workaround

Use COVERAGE.md's module table for the planned backlog and plans/plan_binding.md for its owners.