Keep source navigation tied to exact code.

The problem

The advertised ingest/query/evaluation commands were TODOs. Citation validation accepted broad spans and ambiguous basenames, while the parser missed continued routine declarations.

My contribution

I connected ingestion, real local embeddings, pgvector retrieval, source validation, CLI/API workflows and versioned evaluation. A parser repair restores physical declaration spans without changing source text.

How it works

1. Pinned Git snapshot
2. Source-aligned chunks + BGE vectors
3. Symbol/file navigation + vector search
4. Exact citations or abstention

Decisions that shaped the release

• The corpus, model artifacts and chunker each have an identity. Re-ingestion validates stored content and preserves completed work.
• Explicit identifiers use literal symbol/file lookup with labeled origins; conceptual questions retain the measured vector baseline.
• Literal citation grounding, source-navigation contracts and semantic relevance have separate reports and denominators.

Measured results

Both strategies were measured on the same 28-file, 4,597-vector index. The ten answerable development questions have representative, nonexhaustive evidence labels.

A failure worth inspecting

A three-line declaration needs three physical source lines.

The query returns the actual declaration and leading documentation. Out-of-range spans, conflicting text and ambiguous basenames are rejected. An independent inventory recovered 100 declarations missed by the original parser.

{
  "file": "src/hazFXnga13l.f",
  "declaration_lines": [
    9744,
    9746
  ],
  "symbol": "CY201305_NGA",
  "origin": "symbol_definition",
  "old_parser": "missed the continued declaration",
  "repaired_parser": "preserves all three physical lines",
  "source_excerpt": "        subroutine CY201305_NGA(ip,iprd, M, R_Rup, R_JB, R_x, V_S30,\n     1            F_Measured, F_Inferred, deltaZ1, DELTA, Z_TOR,\n     1            F_RV, F_NM, cDPP,gndout, tau, sigma_NL0, sigmaf)",
  "public_source": "https://github.com/usgs/nshmp-haz-fortran/blob/9f78db0c3d9cd66f90d7aeda6b1082e6dad71502/src/hazFXnga13l.f#L9744-L9746",
  "citation_controls": [
    {
      "reference": "src/hazFXnga13l.f:9744-9746",
      "decision": "accepted",
      "reason": "Exact visible source span"
    },
    {
      "reference": "src/hazFXnga13l.f:9739-9746",
      "decision": "rejected",
      "reason": "Reference is outside the visible retrieved source"
    },
    {
      "reference": "hazFXnga13l.f:9744-9746",
      "decision": "rejected",
      "reason": "Reference is outside the visible retrieved source"
    }
  ]
}

Inspect the pinned public source lines

Limits and next questions

• Exact-span judgments are representative, not exhaustive; zero selected-span recovery is not zero global relevance.
• The semantic development results remain weak. This release supports grounded source navigation, not unrestricted scientific explanation.
• The implementation stays private. Cloud answer quality and browser interaction were not measured.