Catalog feedback and bug reports¶

Use this file to send reproducible problems back to the Green Guides maintainers. Append one report per distinct issue, keeping existing reports and IDs. Fill in what you know; use Unknown for information you cannot establish. Record an uncertain interpretation as Needs review, rather than calling it a confirmed source error.

Include the source edition and precise location. A question, the incorrect result, and the original PDF page or worksheet cell are more useful than a general description such as "the table is wrong." Relevant catalog document and record IDs help the maintainers find the same evidence after a rebuild.

When finished, send this bugs.md back with the relevant excerpt, cropped page, or screenshot if needed. Include only the project details needed to reproduce the issue. The file can be shared on its own; it does not automatically submit reports or require uploading the entire knowledge base.

Reports and resolutions¶

BUG-20261028-01: Broken references in the original recharge workbook¶

Status: Open
Reported: 2026-10-28
Impact: 79 broken buffer-calculation formulas; the checked sample recharge/BMP outputs recalculate without these errors
Origin: Original source workbook; preserved by V2
Source: New Jersey Groundwater Recharge Spreadsheet, April 2004, version 2.0
Document ID: workbook__410f8473cf6e55b8
Source file: SOURCE.xls
Reading view: Workbook notes
Snapshot: workbook.json
Location: Worksheet event calc table, cell R3 is one verified example
Source SHA-256: e840c5821c43340c005bbc90b210327bf2aa60701b160dbcfae5e85a361853ac

Observed: The source snapshot contains 79 formulas with literal #REF! references and stored #REF! error results. For example, R3 contains:

=+IF(Q3<=0.2*#REF!$C$29,0,(Q3-0.2*#REF!$C$29)^2/(Q3+0.8*#REF!$C$29))

Expected: A working calculation references the intended input cells. The correct replacement references have not been established by the V2 conversion.

Reproduce: In workbook.json, locate sheet event calc table, then cell R3. Inspect its formula and cached_value. The original workbook can be compared read-only; the source copy's hash matches the catalog input.

Official-download comparison, 2026-10-28: Both formats listed under Chapter 6 of the NJDEP 2026 BMP Manual were checked using fresh browser downloads provided by the user. Their Windows download-origin metadata identifies the following official files:

Excel 2002 download: april2004public_excel2002njgrs_v2_0.xls, 312,832 bytes. SHA-256 e840c5821c43340c005bbc90b210327bf2aa60701b160dbcfae5e85a361853ac. This is byte-for-byte identical to the existing catalog source.
Excel 97 download: feb2004public_excel_njgrs_v2_0.xls, 310,784 bytes. SHA-256 1477949df898c68898ccaf04b1866495bf1722f2c0fd94596b8804616a48bbf4. It contains the same 79 broken cell formulas, so it is not a clean replacement.

All 1,250 cell-formula strings match between the two variants. Their populated cell sets also match; numeric values differ by no more than approximately 1.02e-10 in the inspected snapshots.

Scope and native Excel verification: All 79 cell errors occur at event calc table!R3:R81, below the P_Q calcs for Buffers heading. Neither the other 1,171 cell formulas nor the workbook's defined names reference this column. The formula scan found no INDIRECT, OFFSET, RTD or CALL formulas that would obscure that dependency check. There are also 26 defined names with #REF! targets and an unused _xlfn.RTD compatibility name with #NAME?; none is used by a cell formula. These findings indicate orphaned buffer calculations, but do not establish the missing worksheet or replacement inputs.

Each file was opened read-only in an isolated Excel instance, with macros and external-link updates disabled, and subjected to CalculateFullRebuild. Both retained exactly the same 79 cell errors and unchanged checked sample outputs. BMP Calculations!J11:J13 returned OK; the required and provided sample volumes at C14 and G14 agreed within 1e-8. Neither file had external workbook links. Both source hashes were unchanged after closing without saving.

Maintainer next step: Keep the current official source and this qualification. No clean replacement was found among the two currently linked formats. Restoring the missing buffer references requires authoritative clarification; do not guess the original worksheet or inputs. Any separately requested repaired derivative must retain the original source and document its ownership and validation.

Resolution / verification: Open. Official-source identity and the error scope are verified; the 79 references remain broken. The as-provided sample recalculation does not validate all project inputs, workbook features or regulatory applicability. No source workbook was modified or replaced.

BUG-20261028-02: 2026 NJAC table index merges three differently classified BMP tables¶

Status: Resolved
Reported: 2026-10-28
Impact: Medium. Named-table retrieval loses the distinction between the general GI table and tables with waiver/variance qualifications.
Origin: Structured table extraction/indexing; the source PDFs retain the tables
Sources: N.J.A.C. 7:8, January 20, 2026 and September 21, 2026 editions
Document IDs: njac_7_8, njac_7_8_2026_09_21
Citation: NJAC 7.8-5.2(f), Tables 5-1, 5-2 and 5-3
Affected records: njac_7_8__table__00001 and njac_7_8_2026_09_21__table__00001, each at JSONL line 1
Record files: January tables.jsonl, September tables.jsonl
Original pages: January PDF, pp. 30-32 and September PDF, pp. 28-30
January source SHA-256: da8d697df823b73f6fedec25b3a80765ae2b176d8b58281d5f982a1b1365ca0f
September source SHA-256: adcab694fd4639d8655c9587210f5808d3b11cdc2e99d3fbedeeb2fde4be0bcd

Question that exposed the issue: Can Tables 5-2 and 5-3 be retrieved as separate named tables in each 2026 edition?

Reproduce:

In catalog.json, filter tables by either affected document_id.
Search table_title for a title beginning Table 5-2 or Table 5-3. Neither has a separate index entry.
Open line 1 of the corresponding tables.jsonl. Before the repeated "Source context and notes" section, its table body contains all three captions and the Blue Roof row from Table 5-3, under metadata naming Table 5-1.
Compare the PDFs: Table 5-2 begins on January PDF page 31 / September page 29; Table 5-3 is on January page 32 / September page 30. They are visibly separate tables with different qualification headings.

Expected result and evidence: Three independently indexed tables with their printed titles, rows, applicability headings, and shared footnotes. The July 2023 catalog already has separate entries for these three tables. The 2026 content is merged, rather than absent from the PDF or wholly lost.

Maintainer next step: Review knowledge_assets.py table-boundary detection for captions represented as pipe-table rows. Split these named tables without losing their notes or changing the source PDFs. Verify lookup of Table 5-2 and Table 5-3 by title in both 2026 editions, and review the resulting record-ID and index migration.

Resolution / verification: Resolved on 2026-10-28. Named caption rows now create three independent tables in both 2026 editions, with shared notes retained. Table 5-1 keeps its existing record ID; Tables 5-2 and 5-3 use new IDs ending __00006 and __00007. Existing IDs and table-N anchors are retained; table_order supplies reading order. The split preserves every original data/header row. All eight question checks pass.

BUG-20261028-03: Soil-testing Table 12-9 caption substitutes alpha for Latin a¶

Status: Resolved
Reported: 2026-10-28
Impact: Low. The caption misidentifies a formula coefficient; the tested numerical coefficients and formula remain correct.
Origin: Inherited OCR symbol error preserved in the structured catalog
Source: BMP Chapter 12, Soil Testing Criteria, March 2024
Document IDs: 2023_BMP_12, 2026_BMP_12; both collection folders hold the March 2024 revision
Citation: BMP 2024, Ch 12, p. 35, Table 12-9
Affected table records: 2023_BMP_12__table__00020 and 2026_BMP_12__table__00020, JSONL line 20 in each tables.jsonl
Primary records: 2023_BMP_12__0035__001 and 2026_BMP_12__0035__001
Original pages: 2023 collection PDF, p. 35, 2026 collection PDF, p. 35
2023 collection source SHA-256: 13fa41917bf158483d9d0e95e77008b9ad089efeb05b492c24514f55db3f942f
2026 collection source SHA-256: 48efcbdb1dd830ff23aa42447a562b402890b03209b02c2343af727e2ee6823d

Question that exposed the issue: For a 10-inch circular test hole and Pm = 3 min/in, what coefficient and hydraulic conductivity does Table 12-9 give, and which chapter revision supplies the table?

Observed: Both extracted table captions contain an alpha TeX command, while the original PDF caption, formula and coefficient row identify Latin a. The extracted formula and numeric row still use a. For example, the 10-inch column is 27.27, giving Ks = a / Pm = 9.09 in/hr for this test input, before other design factors or limits are considered.

Reproduce: Read either affected table record or search the Chapter 12 reading view for Table 12-9. Compare the caption and coefficient notation against the included PDF on page 35.

Expected result and evidence: The caption must identify the same Latin a used in Ks = a / Pm and in the table's second row. The PDF footer identifies March 2024; the collection's 2023 folder name is not the revision year.

Maintainer next step: Apply a narrowly documented OCR correction to this verified caption in the conversion pipeline, preserving the legacy evidence and original PDF bytes. Verify both collection copies and avoid a global replacement of legitimate Greek alpha symbols elsewhere.

Resolution / verification: Resolved on 2026-10-28. A correction scoped to the two verified source PDF hashes changes this caption to Latin a in the reading views, primary records, table records and catalog. Other alpha symbols and original files remain unchanged. Regression checks verify both collection copies, the coefficient row and the 9.09 in/hr test calculation.

BUG-20261028-04: January 2026 safety-ledge figure is displayed twice from extraction aliases¶

Status: Resolved
Reported: 2026-10-28
Impact: Low. Redundant figure display and ambiguous repeated image labels; no missing or corrupt image was found.
Origin: Presentation of preserved legacy extraction aliases
Source: N.J.A.C. 7:8, January 20, 2026, Appendix A, PDF/printed page 51
Document ID: njac_7_8
Record: njac_7_8__0192__001, records.jsonl line 259, citation NJAC 7.8, p. 51
Views: Source reading view, image gallery, image index, original PDF, p. 51
Source SHA-256: da8d697df823b73f6fedec25b3a80765ae2b176d8b58281d5f982a1b1365ca0f
Shared crop SHA-256: 25c501d458543cafb20353c93e79f9283be87af81b6697655b2b1fc419d7422e

Question that exposed the issue: Can the safety-ledge illustration be retrieved at the correct page without showing duplicate copies?

Reproduce: Filter images.json to pdf_page: 51. The two assets end in __a303105c and __ab56a7ad, with local filenames page-0051-img-01.jpg and page-0051-img-01--ab56a7ad.jpg. They have identical crop bytes, coordinates and OCR image ID. The record embeds both copies as OCR image: img-0.jpeg. The original PDF page has one safety-ledge illustration.

Expected result and evidence: Preserve both provenance aliases, while considering one visible figure per identical source/page/crop in reading views and galleries. The aliases are n.j.a.c.7-8-jan-2026 and njac7_8_OCR; they refer to the same PDF, rather than two rule editions. The figure's permanent-pool qualification and source page are correctly preserved.

Maintainer next step: Decide whether to de-duplicate presentation using document, PDF page, crop bounds and image hash, while retaining both extraction paths and asset identities. Do not remove original legacy evidence or merge different source editions merely because some images match.

Resolution / verification: Resolved on 2026-10-28. The record and gallery display one representative crop, and both original files, asset IDs and legacy extraction paths remain indexed. Aliases point to display_asset_id; both previous gallery anchors remain usable. Tests keep identical crops on different pages, in different locations or in different editions separate. The catalog retains 779 original assets and shows 778 distinct crops.

BUG-20261028-05: Manning coefficient table caption was taken from nearby prose¶

Status: Resolved
Reported: 2026-10-28
Impact: Low; misleading table-title metadata, with coefficient cells intact
Origin: Table-caption selection in the extraction pipeline
Source: BMP Chapter 5, July 2023, PDF/printed page 24, Figure 5-12
Document ID: 2023_BMP_5
Record: 2023_BMP_5__table__00011, JSONL line 11
Citation: BMP 2023, Ch 5, p. 24; the figure reprints NEH Table 15-1
Source: Original PDF, p. 24
Source SHA-256: 886b17df97b0fae08f85d3061089e1075d21ce800fe625a52a64b5efb0eda847

Observed before repair: The catalog selected the preceding sentence beginning "Table 15-1 in NEH, Part 630, Chapter 15 lists additional values" instead of the printed caption in the current table's first row. The PDF shows Figure 5-12 and its reprinted Table 15-1, headed "Manning's roughness coefficients for sheet flow (flow depth generally <= 0.1 ft)."

Resolution / verification: The current table's own explicit caption now wins over earlier prose. The record ID is unchanged. The original coefficient cells are unchanged, and a PDF-backed neighbor check verifies the title and Figure 5-12 source location.

BUG-20261028-06: Image association order depended on Python hash randomization¶

Status: Resolved
Reported: 2026-10-28
Impact: Low; unstable image-index/catalog bytes and export hashes despite unchanged source content
Origin: Export ordering in visual_assets.py, across the catalog

Observed before repair: attach_visuals traversed a set of record-file paths. PYTHONHASHSEED=1 and 2 listed an example's records.jsonl before tables.jsonl; seeds 3 and 4 reversed them. The traversal appends image record associations in that order, which could change JSON arrays and hashes.

Expected: Identical source inputs produce associations in a repeatable order, regardless of the interpreter's hash seed.

Resolution / verification: Record-file traversal is sorted. A subprocess regression fixture verifies the same generated association order under hash seeds 1, 2, 3 and 4. This changes export ordering, not source values, file bytes or asset identities.

Initial question-based catalog test, 2026-10-28¶

Baseline tested: commit 053ac76. Eight file/catalog retrieval questions were checked against the included PDFs; selected tables and figures were visually reviewed. Five cases passed cleanly and three exposed the reports above. No incorrect section/page citation was found in the selected answers. This does not establish exhaustive citation accuracy, project applicability, or external vector-database retrieval performance.

Test	Question	Result
Q1	Does a green roof receive TSS or groundwater-recharge credit?	Pass: January 2026 Table 5-1 gives 0% TSS, quantity Yes, recharge No; BMP summary agrees.
Q2	Are NJAC Tables 5-2 and 5-3 separately discoverable in both 2026 editions?	Issue: merged index entries; BUG-20261028-02.
Q3	What are the WQDS depth/duration and cumulative rainfall at 60/120 minutes?	Pass: 1.25 inches in two hours; 0.6250/1.2500 inches. All 120 distribution values matched the PDF grid.
Q4	What recharge alternatives does 5.4(b)1 provide in July 2023 and January 2026?	Pass: either 100% of average annual pre-construction recharge or infiltration of the projected two-year runoff-volume increase, with stated exceptions/prohibitions.
Q5	What are the small-scale infiltration basin drainage-area/drain-time criteria?	Pass: 2.5 acres and 72 hours; 24 hours is the pedestrian-area recommendation, preserving "should".
Q6	Can cistern reuse sizing use an average weekly demand?	Pass: the chapter requires the lowest consecutive three-day volume need during the year, with its secondary-storage provisions.
Q7	For a 10-inch circular hole and Pm=3 min/in, what are a and Ks, and which revision applies?	Numeric/revision answer passes: a=27.27, Ks=9.09 in/hr, March 2024. Caption-symbol issue: BUG-20261028-03.
Q8	Can green-roof layers and safety ledges be opened at the correct source pages without duplicates?	Intended figures and pages pass; duplicate January safety-ledge display: BUG-20261028-04.

All 779 indexed images passed local-file, SHA-256, decode, bounding-box and direct record-link checks. The green-roof layer diagram and safety-ledge illustration were also compared visually with the source pages. The initial audit left original source binaries, structured records and published ZIPs unchanged. Its findings above now include the subsequent repair status.

Repair verification, 2026-10-28¶

The three question-audit defects are repaired, together with the nearby Manning caption and nondeterministic association-order issues. All eight original question cases now pass. The schema/source/hash/link checks pass with 97 documents, 7,047 records and 1,078 table records. All 7,043 existing record IDs are retained, with four new table records. The 1,072 existing table grids outside the two split groups retain their exact cell text; both split groups retain all original rows and their shared qualifications. All 779 source crop files remain unchanged, with 778 distinct display crops.

The original recharge workbook report, BUG-20261028-01, remains open: its correct replacement formula references have not been established. The catalog keeps that original workbook and its errors rather than guessing replacement inputs.

These repairs are included in this catalog snapshot. This verification does not establish exhaustive semantic accuracy or external vector-database retrieval performance.

Validity audit findings, 2026-10-29¶

The following findings were checked against the preserved source PDFs. The audit initially left these findings open. The subsequent authorized repair corrects the exporter and regenerates the catalog, preserving original binaries.

BUG-20261029-01: SESC riprap-apron equation loses equality and scrambles an exponent¶

Status: Resolved
Reported: 2026-10-29
Impact: High. Extracted equation text can produce the wrong branch boundary or denominator if used in a calculation.
Origin: PDF text extraction and layout reconstruction
Sources: SESC January 2014 seventh edition and its July 2017 revision
Document IDs: soil_erosion_standards__8eedbb0eb5071298 and soil_erosion_standards__cb4640485953e9d0
Location: PDF page 75, printed page 12-2, riprap apron at an unconfined outlet
Original pages: 2014 PDF and 2017 PDF
Primary records: Each document's __page__00075 record, line 75 of 2014 records.jsonl or 2017 records.jsonl
Repeated context: Each document's __table__00016 record, line 16 of its tables.jsonl, and the corresponding reading views
2014 source SHA-256: f1fc082c3954a32b58cdcd71bef26b6ef4af2707b7f18a1ab0aa80752d205b12
2017 source SHA-256: 770dd1f90d8171dd8d8acfe6f1170b86c1d2da15ebb5b2d29e57fc34234ad6c6

Observed: The second branch is extracted as TW > ½ Do, and the denominator exponent appears as 5.0 in the disrupted equation layout. Both original page images show TW ≥ ½ D_o and L_a = 3(q / D_o^0.5). The first branch uses TW < ½ D_o; losing equality leaves the boundary uncovered.

Reproduce: Open either primary JSONL record or README at PDF page 75, then compare the second equation with the original PDF at high magnification. The numerical riprap lookup table below the equations was preserved in the checked sample; that does not validate the equation text above it.

Maintainer next step: Correct the verified equation in the owning extraction step, scoped to these source hashes/pages, or explicitly suppress unreliable equation text and point readers to the original. Preserve the original PDFs and record IDs. Verify both branches, exponent placement, and repeated table context.

Resolution / verification: Resolved on 2026-10-29. A source-hash/page-scoped correction restores both complete branches, including the equality and exponent, in primary records, reading views and table context. No source PDF or workbook was changed. Regression checks exercise both editions and preserve the table cells.

BUG-20261029-02: Twenty reference documents omit available printed dates¶

Status: Resolved
Reported: 2026-10-29
Impact: Medium. Edition filtering and precise source selection lose dates that are available in the original documents.
Origin: Reference-document metadata export
Location: catalog.json, reference README files, and associated records
Scope: 20 of the 21 table_reference documents labeled version_year: undated and Printed revision not established

Observed and expected: The following original PDF cover pages contain dates that are omitted from their catalog metadata. Preserve the date's stated meaning; a readoption date is not necessarily the last amendment date.

Reference group	Documents	Printed date or event
Meeting the GI Requirement, both collection copies	2	June 2022
Appendix D, full/simplified/strikethrough copies	3	January 2026
Appendix A and B in the 2026 collection	2	February 2004
Appendix C in the 2026 collection	1	January 2026
Employee Participation fact sheet	1	March 16, 2007
Earthen Secondary Containment soil-testing guidance	1	Issued November 2013
N.J.A.C. 7:1E, 7:10, 7:13, and 7:9D	4	Last amended January 20, 2026
N.J.A.C. 7:12	1	Last amended September 19, 2016
N.J.A.C. 7:1D	1	Last amended December 2, 2019
N.J.A.C. 7:9A	1	Readopted December 2, 2025
N.J.A.C. 7:9B	1	Last amended December 18, 2023
N.J.A.C. 7:9C	1	Last amended February 3, 2025
N.J.A.C. 7:9E	1	Last amended June 1, 2020

Reproduce: Filter catalog.json to the scope above and inspect page 1 of each matching source_file. The remaining undated Bureau of Release Prevention audit checklist is not included in this confirmed finding.

Maintainer next step: Add reviewed source-identity metadata in the owning registry/exporter. knowledge_assets.py currently takes printed_revision from the registry or assigns the unknown fallback. Do not infer revisions from the collection folder or use unrelated dates mentioned in body text. Verify the catalog, reading views, and record metadata together after regeneration.

Resolution / verification: Resolved on 2026-10-29. Twenty hash-verified cover-date overrides now populate catalog and record metadata and reading views. Readoption remains labeled as readoption. This does not certify latest-edition status.

BUG-20261029-03: Named SESC tables have generic catalog titles¶

Status: Resolved
Reported: 2026-10-29
Impact: Medium. Searching the table index by printed table number can miss existing evidence, although the table cells and original PDFs are present.
Origin: SESC table-caption extraction/indexing
Confirmed examples: Table 12-1 on 2014 PDF page 75 and Table 19-1, Maximum Dry Bulk Densities, on 2017 PDF page 111
Records: soil_erosion_standards__8eedbb0eb5071298__table__00016 at tables.jsonl line 16; soil_erosion_standards__cb4640485953e9d0__table__00027 at line 27
Original pages: 2014 Table 12-1 and 2017 Table 19-1

Observed: The entries have source_table_id: null and titles such as Table on PDF page 111, item 1 instead of the visible printed identifiers. The checked density values and riprap lookup values match the original pages. This title finding is separate from the corrupted equation context in BUG-20261029-01.

Reproduce: Filter catalog.json to the records above and compare source_table_id and table_title with the cited PDF captions.

Maintainer next step: Associate nearby printed captions with extracted table bounds, preserving record IDs, table_number, and anchors. Review other candidate captions before assigning them; page co-occurrence alone is insufficient.

Resolution / verification: Resolved for the confirmed cases on 2026-10-29. Table 12-1 is named in both editions and Table 19-1 in 2017; existing record IDs and anchors are preserved. The subsequent complete review of all 65 candidates confirmed 62 further caption gaps, now corrected. Reviewed fragments share their printed caption; the source's two differently titled Table 26-3 entries retain their printed numbers. All captions were checked visually against the original pages, with unchanged table cells, record IDs, bounding boxes, and anchors. No candidates remain unreviewed in this identified set; this is not an exhaustive new-table scan.

Copy this template for a new report¶

Use the next available BUG-YYYYMMDD-NN ID and place the completed report above this template. Suggested impact levels: High for wrong technical values or calculations, Medium for missing/unusable evidence, Low for presentation.

### BUG-YYYYMMDD-NN: Short description

- Status: Open / Needs review / Resolved
- Reported date:
- Impact: High / Medium / Low, with a short explanation
- Origin: V2 extraction / Original source / Broken link or missing file /
  Retrieval or answer / Applicability or interpretation / Unknown
- Source title and printed revision:
- Relative source-folder path:
- Catalog document_id:
- Record_id and JSONL line, if known:
- Citation or section/table number:
- PDF file page and printed page, or worksheet name and cell/range:
- Source SHA-256, if available from catalog.json:

**Question or action that exposed the issue:**

**Steps to reproduce:**
1.
2.

**Observed result:**
Quote the exact value, text, error, or broken link. Include units and operators.

**Expected result and evidence:**
Identify the original page/cell supporting the expectation. If not confirmed,
state what needs checking instead of proposing a replacement value as fact.

**Attachments or excerpts:**
Include the surrounding table headings, footnotes, conditions, and edition.

**Maintainer notes / proposed correction:**

**Resolution / verification:**
Record the changed source or extraction step and the check proving the fix.