Structura: preserving evidence before documents become embeddings

The citation problem starts at ingestion

A retrieval system can return the right paragraph and still leave the reader unable to verify the answer. The paragraph might have come from a superseded document, lost a table heading during extraction, or acquired a citation that points only to a filename. Improving the embedding model does not repair those failures. They concern the identity and meaning of the material supplied to the model.

Structura approaches this problem through explicit intermediate records. The repository's shared Rust model defines Input, Candidate, Evidence, and Decision shapes. Candidates retain a location and the stage that produced them; evidence can carry a model or rule version. These are implementation choices visible in the code, not proof that every ingestion connector preserves every source correctly. They are useful because they make information loss inspectable.

The design question is therefore narrower than building a better RAG platform: what must survive every transformation so that an answer can be checked against the material that justified it? I want the retrieval unit to remain connected to a particular source revision, an intelligible location, and the operation that created it. Embeddings can then serve discovery without becoming the only surviving representation of the document.

Give the source and the transformation separate identities

Consider an illustrative maintenance manual containing a table of inspection intervals. The original PDF is one artifact. Extracted text is another. A normalized table, a retrieval passage, and its embedding are further artifacts. Reusing one identifier for all five makes it difficult to answer a basic question: did the source change, or did the parser change its interpretation?

A practical manifest needs a source digest, an extraction configuration digest, a parser version, and an output digest. Structura's Input includes a BLAKE3 content hash, while the evidence builder records stage-specific information. A content hash identifies bytes under a chosen encoding; it does not establish that the bytes are authoritative or that the extraction is faithful. JSON canonicalization also needs a declared policy. The inspected low-level Input implementation distinguishes its ordinary serialization from the stricter canonicalization helper expected at higher layers.

That distinction becomes operational when a parser upgrade fixes merged cells. The PDF hash stays stable, but the extracted table and its descendants must change. If the cache key contains only the PDF hash, an apparently successful reindex can keep serving the old interpretation. Content identity and transformation identity should meet in the manifest rather than being confused in one opaque identifier.

An atom needs enough context to mean something

Small retrieval units are attractive because they fit into bounded contexts and support precise citations. Smallness alone is not a useful contract. The value “30” means little without its unit, row label, column heading, applicability, and nearby qualification. An atom should be a bounded evidence unit whose interpretation remains recoverable, not merely a short string.

Structura's location variants illustrate the variety involved: a bounding box for a PDF page, a JSON path, a database row, an object-store reference, or a more detailed web locator. Each source type needs its own locator semantics. A page-relative box should declare its coordinate system; a database locator should bind a revision or snapshot when values can change. A URL without capture information is a weak anchor for mutable web content.

The following record is an illustrative contract, not a copy of Structura's schema. Its purpose is to make the dependency on the table heading explicit. A system may retrieve the row alone for ranking, then expand its context for interpretation. That expansion must retain the distinction between directly cited material and context supplied to disambiguate it.

1{
2  "sourceRevision": "manual-revision-c",
3  "locator": {"page": 12, "table": "inspection-intervals", "row": 3},
4  "content": "Inspection interval: 30 operating hours",
5  "contextRefs": ["table-heading", "applicability-note"],
6  "extractionVersion": "table-parser-v2",
7  "evidenceType": "source-statement"
8}

Retrieve candidates without erasing their differences

Lexical and dense retrieval answer different questions about a query. A precise part identifier benefits from exact text. A paraphrased question may benefit from a semantic representation. Combining their candidate lists can be useful, but the combined rank should not erase how each candidate entered the list or which source boundary it belongs to.

The shared Structura evidence builder includes separate BM25, semantic, structural, fuzzy, and validation records. Its semantic helper attaches an embedding model version, and its validation helper attaches a rule version. This provides a place to record a chain of reasoning through the software. It does not make normalized stage scores interchangeable probabilities. A BM25 score and a cosine similarity still require their own interpretation.

For the manual example, the useful result is not simply “row 3 ranked first.” It is that an identifier match found the relevant table, a semantic query found the surrounding inspection explanation, and a source constraint excluded a superseded revision. Keeping those contributions separate makes a disagreement debuggable. The retriever can be wrong because it missed the right candidate, and the final selector can be wrong despite receiving that candidate.

Bind the answer to the evidence actually used

A final answer needs claim-level accounting. If it contains three factual claims, a single citation at the paragraph's end may hide that only one has support. A useful assembly step records which source spans support each claim and whether the support is direct, inferred, or absent. The last category should lead to removal, qualification, or an explicit request for more evidence.

For the manual example, “the interval is 30 operating hours” may be directly supported. “This component is safe until the next inspection” is a separate conclusion that the table alone cannot establish. A generator can make that leap fluently. A citation verifier must ask whether the cited material supports the actual scope of the sentence, including its conditions, rather than whether the sentence shares keywords with the source.

Provenance vocabulary can help describe these relationships. W3C PROV-O distinguishes entities, activities, and agents so that derivation has an explicit representation. Using that vocabulary does not validate the underlying claim. The implementation still needs to preserve source access, version bindings, and the distinction between a source statement and a model's inference.

Test the loss of evidence, not only answer quality

The most revealing tests deliberately break the evidence chain. Change the PDF without changing its name. Delete the applicability note. Reorder a table's columns. Revoke access to the source after indexing. Upgrade the parser while keeping the embedding model fixed. Each case should have an expected invalidation or refusal behavior before it becomes a benchmark query.

Evaluate ingestion fidelity separately from retrieval coverage, citation correctness, and answer usefulness. A source-location test can pass while an answer remains misleading; a human can like an answer whose cited text is stale. Report these dimensions independently and preserve the failed cases. If a single overall score is needed for a decision, keep its component measurements available and state the weighting.

This implementation note does not establish production reliability or a measured retrieval advantage for Structura. It identifies a testable architectural commitment: evidence should remain a first-class object throughout the pipeline. The next convincing artifact is a small, adversarial document corpus with expected source spans and revision transitions. A reader should be able to inspect why a case passes, not merely accept that the dashboard turned green.