Response evidence and confidence

Every public query uses a common envelope so a developer or agent can reason about both the fact and its evidentiary limits.

Status answers “what happened?”

A response status is one of:

• ok — a result was produced;
• not_found — no matching parsed fact was found;
• validation_error — the input failed deterministic validation.

Status does not tell you whether an ok result is normative, explanatory, fully decidable, or high confidence. Read the classification and confidence fields too.

Classification has three dimensions

Normativity

• normative — the response represents parsed normative structures.
• explanatory — the response is a retrieved or synthesized explanation.
• derived — a result derives from other stored facts.
• heuristic — a bounded non-normative heuristic was used.
• unsupported — the requested result was not established.

Non-ok responses are classified as unsupported.

Evidence level

• parsed_registry
• parsed_table
• parsed_cross_reference
• retrieved_text
• external_comparison

The value names the primary evidence source, not every record touched during resolution.

Machine decidability

• decidable
• partially_decidable
• not_decidable
• not_applicable

Contextual attribute resolution is partially decidable because parsed rows can support a bounded type result while broader condition semantics can remain context dependent.

Parse confidence is independent

Parse confidence has:

• level: high, medium, low, or unknown;
• source: the evidence source or validation stage;
• optional notes.

Typical behavior includes:

• structured successful lookups without warnings: high;
• contextual resolution or warning-bearing results: medium;
• retrieved text: low;
• validation errors: unknown;
• not-found results: medium with a note that no parsed fact matched.

A low-confidence text result can still point to the correct section; it simply should not be treated as an automatically parsed normative decision.

Warnings are result specific

Warnings can report:

• unresolved graph relationships;
• ambiguous candidates;
• parser limitations;
• bounded heuristic notes;
• conflicting type-override prose;
• missing optional context.

Do not discard them when serializing, logging, or prompting a model.

References connect facts to the standard

A reference can include:

• part;
• section;
• table;
• anchor;
• official URL;
• concrete edition.

A response can carry multiple references when a result combines registry, table, and graph facts.

Trace connects the query to the build

Trace metadata includes:

• a unique query id;
• a UTC resolution timestamp;
• the source-manifest SHA-256 when available.

Together with edition, this lets an application record which local source state produced the response.

Safe consumption rule

A downstream system should never use only result. At minimum, retain:

edition
status
result
classification
parse_confidence
refs
warnings
trace

An agent should cite the references, distinguish explanatory text from parsed facts, and state unresolved boundaries rather than converting them into a confident answer.