Data Contracts¶
Reasoning output is modeled as a chain of typed, content-addressed records. A claim is not a free-standing string: it belongs to a problem and plan, appears in an ordered trace, points to exact support, and is evaluated by a verification report.
flowchart LR
Spec[ProblemSpec] --> Plan
Plan --> Step[PlanNode and StepSpec]
Step --> TraceEvent
TraceEvent --> Evidence[EvidenceRef]
TraceEvent --> Claim
Evidence --> Support[SupportRef]
Support --> Claim
Claim --> Report[VerificationReport]
Planning Records¶
ProblemSpec captures the description, constraints, expected output type, and
optional expected values and version. Its ID is derived from canonical content
when none is supplied.
A Plan points back to the spec and contains ordered PlanNode values plus
explicit edges. Each node has a reasoning kind—understand, gather, derive,
verify, or finalize—dependencies, parameters, and a typed StepSpec.
ToolRequest keeps the selected tool and JSON-compatible arguments inside the
plan rather than hiding them in runtime glue.
Trace Records¶
Trace declares runtime protocol, schema, canonicalization, and fingerprint
versions. Its event stream is a discriminated union:
| Event | Payload |
|---|---|
step_started |
step identity |
step_finished |
typed output for the step kind |
tool_called |
content-addressed call and arguments |
tool_returned |
call identity, success, result or error |
evidence_registered |
immutable evidence reference |
claim_emitted |
typed claim |
Finished steps cannot collapse to an arbitrary dictionary. Their output is one of the understood, gathered, derived, verified, finalized, or insufficient-evidence variants. This makes an explicit refusal for insufficient evidence distinguishable from a malformed or missing result.
Claims and Support¶
Claim records statement, status, confidence, type, optional structured data,
and support references. SupportRef identifies a claim, evidence item, or tool
call and requires both an exact byte span and a lowercase SHA-256 of the cited
snippet. EvidenceRef identifies its URI, whole-content hash, span, chunk, and
safe relative content path.
Evidence paths reject absolute paths, drive prefixes, backslashes, and parent
traversal. Construction validates support spans and snippet-hash syntax,
evidence spans, chunk-ID syntax, and path safety. EvidenceRef.sha256 is carried
as a string at model construction; the run builder establishes its meaning by
hashing the referenced file and requiring an exact match. Cross-record
verification then confirms that cited bytes and registered evidence agree.
Grounded Answer Citations¶
The credential-free grounded-answer path uses a closed chain of immutable records rather than accepting citation dictionaries from a caller:
retrieval artifact -> evidence packet -> normalized claim -> citation link
-> verification report -> evidence-aware admission
-> numbered presentation
Each citation link retains the exact retrieval, document, chunk, source, locator, quote, and source-byte identities plus the source descriptor used for bibliographic display. The verifier compares the link with both the evidence packet and the source descriptor. An invented coordinate, changed quote, stale retrieval identity, substituted source, or changed bibliography is a typed failure.
CitationPresentation deduplicates repeated use of one evidence item while
retaining all claim identities that cite it. A numbered entry includes the
exact quote and locator, hashes, title, authors, journal, date, DOI, URI,
license, provenance, format, and language when the immutable source descriptor
provides them. An admitted factual claim without a verified citation is
invalid; an abstention exposes no claims or citations. Bibliographic metadata
helps a reader identify the source but is never treated as evidence for the
claim.
GroundingEvidenceState binds admission to the installed retrieval outcome,
VEX witness or bounded exact fallback, selected-evidence count, packet
completeness, and any policy or budget refusal. The versioned admission policy
also measures direct-support coverage and confidence and rejects unresolved
opposition. Its typed evidence gaps distinguish out-of-scope requests, absent
evidence, inadequate support, unresolved conflicts, unsafe or unverified
evidence, retrieval failure or refusal, and policy or budget refusal. Every gap
retains a concrete remediation. An upstream refusal therefore cannot be
converted into an answer merely because a downstream synthesizer can form a
sentence.
The admitted answer is rendered from NuancedGroundingRepresentation, not
from the synthesizer's prose. Claims are grouped only when their explicit
population, method, and temporal scopes match. Findings, methods, reported
limitations, and counterevidence appear in separate sections with the same
numbered exact citations used by verification. A finding/counterevidence pair
is material conflict: omitting its conflict declaration makes the record
invalid, and the renderer states that ambiguity instead of selecting a
majority view.
Product limitations, assumptions, and interpretations are separate typed annotations labeled “not source-supported facts.” They carry provenance basis identities rather than exact-citation fields and never enter the source-supported findings section. Internal artifact and citation-link identifiers remain in the persisted graph but are not used as reader-facing prose.
ResearchAnswerRevisionService closes the RAR feedback loop over this same
grounding authority. It combines the prior immutable evidence packet with
classified new evidence, preserves source metadata and locators, and re-runs
synthesis, atomic normalization, citation linking, entailment verification,
context rendering, and admission. Its content-addressed result records typed
add, remove, qualify, split, merge, strengthen, abstain, or preserve actions.
Each action links prior claims, revised claims, exact evidence, and the
classification that caused it. Material ambiguity or unclassified evidence
produces a verified abstention instead of silently retaining the earlier
answer.
Validation Layers¶
Validation is intentionally cumulative:
| Boundary | What it establishes | What it does not establish |
|---|---|---|
| model construction | field shape, discriminators, span form, safe path syntax, content-derived IDs | file existence or semantic support |
| trace serialization | canonical header/event records and stable newline bytes | evidence-file integrity |
| run construction | registered file existence and whole-file SHA-256 equality | claim support correctness |
| trace verification | event order, references, spans, support hashes, plan and provenance relationships | external truth of a supported claim |
| manifest verification | retained file bytes match recorded digests | scientific or logical correctness |
A validated model can still name unavailable evidence. A manifest-valid run can still contain rejected claims or failed verification checks. Consumers must use the layer that answers their actual trust question.
Verification Records¶
VerificationReport contains individual checks, structured failures, summary
metrics, and the trace identity. Failures retain severity and, when known, the
violated invariant. A report with failures is still valuable evidence; callers
must not reduce it to the presence of a JSON file or a truthy object.
All core records inherit the frozen StableModel contract: unknown fields are
forbidden, defaults are validated, aliases are resolved explicitly, and models
cannot be mutated after validation. Changing ID inputs, discriminators, event
order, span meaning, or version fields is compatibility-sensitive.
Content-derived IDs identify typed semantic records; they are not substitutes for the exact-byte trace fingerprint or run manifest. Two serializations can represent the same semantic record while differing at the byte layer, and the artifact contract records both distinctions.
See Artifact Contracts for the canonical on-disk representation of these records.