NODEDC_1C/docs/ARCH/11 - architecture_turnaround/04 - coverage_evidence_truth_gate.md

04 - Coverage Evidence Truth Gate

Purpose

This document defines the missing architectural layer between:

• exact execution lane

and

• answer policy / packaging

This layer must exist as a first-class object because the system already needs to answer questions such as:

• do we have enough evidence;
• is the result full, partial, or blocked;
• may this result power follow-up carryover;
• is limited mode required;
• can the assistant speak as confirmed truth or only as bounded evidence.

Architectural Position

The target runtime stack should be read as:

1. route and transition policy
2. exact execution lane
3. coverage / evidence / truth gate
4. answer policy
5. packaging and debug

Answer policy must not own the truth gate.

Current Code Owners

The gate is no longer only a fragmented idea.

The current explicit owners are:

• addressTruthGatePolicy.ts
• addressCoverageEvidencePolicy.ts
• assistantRuntimeContractResolver.ts
• assistantTruthAnswerPolicyRuntimeAdapter.ts

These contracts are currently named:

• address_truth_gate_v1
• address_coverage_evidence_v1

Residual gate-related pressure still exists in:

• addressQueryService.ts
• composeStage.ts

The current architectural problem is no longer absence.

It is incomplete end-to-end isolation of truth semantics from final answer shaping.

Gate Inputs

The gate should consume:

• exact runtime result
• normalized retrieval result
• evidence items
• candidate evidence items
• coverage report
• route expectation outcome
• current frame state
• requested truth mode

Gate Outputs

The gate should produce:

• coverage_status
• grounding_status
• truth_mode
• carryover_eligibility
• reason_codes
• evidence_grade
• blocked_or_limited_explanation

These outputs must be machine-readable.

Status Classes

1. full_confirmed

Meaning:

• coverage is sufficient;
• evidence is admissible;
• route expectation passed;
• answer may speak in confirmed mode.

2. partial_supported

Meaning:

• some evidence exists;
• some requirements remain uncovered or weakly covered;
• answer must remain bounded and explicit about limitations.

3. blocked_missing_anchor

Meaning:

• exact execution cannot safely complete because required anchors are unresolved.

4. blocked_route_expectation_failure

Meaning:

• route was attempted, but the route contract itself did not pass baseline expectations.

5. blocked_execution_error

Meaning:

• system failure or execution failure prevents reliable business answer.

6. limited_temporal_or_contextual

Meaning:

• the system can say something useful, but only within a narrow and explicit evidence window.

Carryover Eligibility Contract

The gate must also determine follow-up eligibility.

Allowed values:

• full
• root_only
• object_only
• meta_only
• none

Examples:

• full_confirmed result from root stock snapshot may often allow full or root_only
• selected-object provenance with weak buyer evidence may allow object_only or meta_only
• blocked route expectation should usually allow none

Truth Rules

Rule 1. Answer Policy May Downgrade, But Not Upgrade

Answer policy may choose a clearer wording.

Answer policy may not:

• turn blocked into confirmed;
• turn partial into full;
• suppress critical truth reason codes.

Rule 2. Limited Mode Must Remain Truthful

If evidence is insufficient, limited mode must be explicit about:

• what is confirmed;
• what is not confirmed;
• why the system is limited.

Rule 3. Carryover Must Respect The Gate

Follow-up policy may not assume that every previous answer is equally reusable.

Carryover must obey:

• gate-produced eligibility;
• evidence window;
• blocked or limited reason codes.

Rule 4. Route Expectation Failure Is A Truth Event

If route expectation fails, this is not just a technical footnote.

It is a first-class truth gate outcome.

Required Gate Artifacts

Every gated answer should be traceable through these artifacts:

• evidence_bundle
• coverage_contract
• grounding_check
• truth_mode
• carryover_eligibility
• reason_codes

Non-Goals

This gate is not responsible for:

• model wording style;
• cosmetic answer formatting;
• provider selection;
• UI packaging details.

Done Criteria

This layer is considered architecturally established only when:

• it is documented as separate from answer policy;
• its outputs are explicit inputs to answer shaping;
• carryover policy depends on gate output rather than hidden heuristics;
• scenario acceptance can fail specifically on gate behavior, not only on final wording.

Honest Current Status (2026-04-17)

This layer is mostly established, but not complete.

What is already true:

• exact-lane truth and coverage/evidence contracts are explicit and machine-readable;
• runtime adapters consume those contracts directly;
• scenario acceptance can already fail on truth/coverage invariants.

What is still not fully true:

• user-facing blocked/limited semantics are still partly coupled to final packaging branches;
• composeFactualReply() still carries too much architectural weight;
• not every business contour is equally mature in explicit truth/coverage signaling.