# 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](/x:/1C/NDC_1C/llm_normalizer/backend/src/services/addressTruthGatePolicy.ts:1)
- [addressCoverageEvidencePolicy.ts](/x:/1C/NDC_1C/llm_normalizer/backend/src/services/addressCoverageEvidencePolicy.ts:1)
- [assistantRuntimeContractResolver.ts](/x:/1C/NDC_1C/llm_normalizer/backend/src/services/assistantRuntimeContractResolver.ts:256)
- [assistantTruthAnswerPolicyRuntimeAdapter.ts](/x:/1C/NDC_1C/llm_normalizer/backend/src/services/assistantTruthAnswerPolicyRuntimeAdapter.ts:127)

These contracts are currently named:

- `address_truth_gate_v1`
- `address_coverage_evidence_v1`

Residual gate-related pressure still exists in:

- [addressQueryService.ts](/x:/1C/NDC_1C/llm_normalizer/backend/src/services/addressQueryService.ts:3082)
- [composeStage.ts](/x:/1C/NDC_1C/llm_normalizer/backend/src/services/address_runtime/composeStage.ts:2684)

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.