kibi-core 0.12.0 → 0.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kibi-core",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "private": false,
   "description": "Core Prolog modules and RDF graph logic for Kibi",
   "type": "module",
@@ -8,10 +8,7 @@
     "node": ">=18"
   },
   "main": "./src/kb.pl",
-  "files": [
-    "src/**/*.pl",
-    "schema/**/*.pl"
-  ],
+  "files": ["src/**/*.pl", "schema/**/*.pl"],
   "license": "AGPL-3.0-or-later",
   "author": "Piotr Franczyk",
   "repository": {

package/src/checks.pl

@@ -10,6 +10,7 @@
     check_must_priority_coverage/1, % Returns list of must-priority violations
     check_symbol_coverage/1,        % Returns list of uncovered symbols
     check_symbol_traceability/2,    % Returns list of symbols lacking requirement traceability (ReqAdr option)
+    check_proof_contract_symbols/1, % Returns unresolved or unexpected required_proofs symbol issues
     check_no_dangling_refs/1,       % Returns list of dangling ref violations
     check_no_cycles/1,              % Returns list of cycle violations
     check_required_fields/1,        % Returns list of missing required field violations
@@ -70,6 +71,7 @@ check_all(ViolationsDict) :-
     check_rule_verifiability(RuleVerifiability),
     check_semantic_completeness(SemanticCompleteness),
     check_req_status_vocabulary(ReqStatusVocabulary),
+    check_proof_contract_symbols(ProofContractSymbols),
     ViolationsDict = _{
         must_priority_coverage: MustPriority,
         symbol_coverage: SymbolCoverage,
@@ -87,7 +89,8 @@ check_all(ViolationsDict) :-
         rule_safety: RuleSafety,
         rule_verifiability: RuleVerifiability,
         semantic_completeness: SemanticCompleteness,
-        req_status_vocabulary: ReqStatusVocabulary
+        req_status_vocabulary: ReqStatusVocabulary,
+        proof_contract_symbols: ProofContractSymbols
     }.
 
 %% check_must_priority_coverage(-Violations)
@@ -148,6 +151,17 @@ check_symbol_traceability(RequireAdr, Violations) :-
     ),
     sort(Violations0, Violations).
 
+symbol_traceability_violation(_RequireAdr, violation(
+    'symbol-traceability',
+    SymbolId,
+    "Symbol mixes executable_for test identity with production implements or covered_by.",
+    "Split the symbol: keep executable_for on the test-code symbol and use a separate production symbol for implements/covered_by.",
+    Source
+)) :-
+    kb_entity(SymbolId, symbol, _),
+    mixed_role_symbol(SymbolId),
+    violation_source(SymbolId, symbol, Source).
+
 symbol_traceability_violation(RequireAdr, violation(
     'symbol-traceability',
     SymbolId,
@@ -186,6 +200,118 @@ symbol_traceability_violation(RequireAdr, violation(
     ),
     violation_source(SymbolId, symbol, Source).
 
+%% check_proof_contract_symbols(-Violations)
+% Advisory integrity for proof_contract.required_proofs and optional
+% proof_bindings.source_file. Kibi does not infer TEST names from filenames.
+check_proof_contract_symbols(Violations) :-
+    findall(Violation, proof_contract_symbol_violation(Violation), Violations0),
+    sort(Violations0, Violations).
+
+proof_contract_symbol_violation(violation(
+    'proof-contract-symbols',
+    TestId,
+    Description,
+    Suggestion,
+    Source
+)) :-
+    kb_entity(TestId, test, Props),
+    memberchk(proof_contract=RawContract, Props),
+    parse_json_object(RawContract, Contract),
+    required_proof_symbol_id(Contract, SymbolId),
+    \+ kb_entity(SymbolId, symbol, _),
+    format(string(Description), "proof_contract.required_proofs names unresolved symbol ~w", [SymbolId]),
+    Suggestion = "Point required_proofs.symbol_id at an existing symbol entity; Kibi does not infer TEST names from source filenames.",
+    violation_source(TestId, test, Source).
+
+proof_contract_symbol_violation(violation(
+    'proof-contract-symbols',
+    TestId,
+    Description,
+    Suggestion,
+    Source
+)) :-
+    kb_entity(TestId, test, Props),
+    memberchk(proof_contract=RawContract, Props),
+    parse_json_object(RawContract, Contract),
+    required_proof_symbol_id(Contract, SymbolId),
+    kb_entity(SymbolId, symbol, SymbolProps),
+    memberchk(symbol_role=RawRole, SymbolProps),
+    normalize_term_atom(RawRole, 'type-shape'),
+    format(string(Description), "proof_contract.required_proofs names type-shape symbol ~w; required proofs must not target structural contracts", [SymbolId]),
+    Suggestion = "Required proofs identify executable proof symbols. Use a production or executable-test symbol, not a type-shape contract.",
+    violation_source(TestId, test, Source).
+
+proof_contract_symbol_violation(violation(
+    'proof-contract-symbols',
+    TestId,
+    Description,
+    Suggestion,
+    Source
+)) :-
+    kb_entity(TestId, test, Props),
+    memberchk(proof_bindings=RawBindings, Props),
+    parse_json_list(RawBindings, Bindings),
+    member(Binding, Bindings),
+    is_dict(Binding),
+    (get_dict(source_file, Binding, RawBindingSource) ; get_dict(sourceFile, Binding, RawBindingSource)),
+    normalize_term_atom(RawBindingSource, BindingSource),
+    BindingSource \= '',
+    (get_dict(symbol_id, Binding, RawSymbolId) ; get_dict(symbolId, Binding, RawSymbolId)),
+    normalize_term_atom(RawSymbolId, SymbolId),
+    SymbolId \= '',
+    kb_entity(SymbolId, symbol, SymbolProps),
+    (   memberchk(sourceFile=RawSymbolSource, SymbolProps)
+    ->  normalize_term_atom(RawSymbolSource, SymbolSource)
+    ;   SymbolSource = ''
+    ),
+    SymbolSource \= BindingSource,
+    format(string(Description), "proof_bindings.source_file for ~w is ~w but the symbol sourceFile is ~w", [SymbolId, BindingSource, SymbolSource]),
+    Suggestion = "Align proof_bindings.source_file with the symbol's sourceFile, or omit source_file. Kibi does not infer TEST names from filenames.",
+    violation_source(TestId, test, Source).
+
+required_proof_symbol_id(Contract, SymbolId) :-
+    (   get_dict(required_proofs, Contract, Raw)
+    ;   get_dict('required_proofs', Contract, Raw)
+    ),
+    parse_json_list(Raw, Entries),
+    member(Entry, Entries),
+    (   is_dict(Entry),
+        (get_dict(symbol_id, Entry, RawId) ; get_dict(symbolId, Entry, RawId))
+    ;   is_list(Entry),
+        memberchk(symbol_id=RawId, Entry)
+    ),
+    normalize_term_atom(RawId, SymbolId),
+    SymbolId \= ''.
+
+parse_json_object(^^(Value, _), Dict) :-
+    !,
+    parse_json_object(Value, Dict).
+parse_json_object(literal(type(_, Value)), Dict) :-
+    !,
+    parse_json_object(Value, Dict).
+parse_json_object(literal(Value), Dict) :-
+    !,
+    parse_json_object(Value, Dict).
+parse_json_object(Dict, Dict) :-
+    is_dict(Dict),
+    !.
+parse_json_object(Raw, Dict) :-
+    (atom(Raw) ; string(Raw)),
+    catch(atom_json_dict(Raw, Dict, [value_string_as(string)]), _, fail),
+    is_dict(Dict).
+
+parse_json_list(Raw, Entries) :-
+    is_list(Raw),
+    !,
+    Entries = Raw.
+parse_json_list(^^(Value, _), Entries) :-
+    !,
+    parse_json_list(Value, Entries).
+parse_json_list(Raw, Entries) :-
+    (atom(Raw) ; string(Raw)),
+    catch(atom_json_dict(Raw, Entries, [value_string_as(string)]), _, fail),
+    is_list(Entries).
+
 %% check_no_dangling_refs(-Violations)
 % Finds all relationships referencing non-existent entities.
 check_no_dangling_refs(Violations) :-
@@ -1478,7 +1604,8 @@ check_selected_dispatch(Rules, _{
     rule_safety: RuleSafety,
     rule_verifiability: RuleVerifiability,
     semantic_completeness: SemanticCompleteness,
-    req_status_vocabulary: ReqStatusVocabulary
+    req_status_vocabulary: ReqStatusVocabulary,
+    proof_contract_symbols: ProofContractSymbols
 }) :-
     selected_rule(Rules, 'must-priority-coverage', check_must_priority_coverage, MustPriority),
     selected_rule(Rules, 'symbol-coverage', check_symbol_coverage, SymbolCoverage),
@@ -1496,7 +1623,8 @@ check_selected_dispatch(Rules, _{
     selected_rule(Rules, 'rule-safety', check_rule_safety, RuleSafety),
     selected_rule(Rules, 'rule-verifiability', check_rule_verifiability, RuleVerifiability),
     selected_rule(Rules, 'semantic-completeness', check_semantic_completeness, SemanticCompleteness),
-    selected_rule(Rules, 'req-status-vocabulary', check_req_status_vocabulary, ReqStatusVocabulary).
+    selected_rule(Rules, 'req-status-vocabulary', check_req_status_vocabulary, ReqStatusVocabulary),
+    selected_rule(Rules, 'proof-contract-symbols', check_proof_contract_symbols, ProofContractSymbols).
 
 selected_rule(Rules, Name, Goal, Violations) :-
     (   memberchk(Name, Rules)
@@ -1552,6 +1680,7 @@ check_all_with_options(ViolationsDict, RequireAdr) :-
     check_rule_verifiability(RuleVerifiability),
     check_semantic_completeness(SemanticCompleteness),
     check_req_status_vocabulary(ReqStatusVocabulary),
+    check_proof_contract_symbols(ProofContractSymbols),
     ViolationsDict = _{
         must_priority_coverage: MustPriority,
         symbol_coverage: SymbolCoverage,
@@ -1569,7 +1698,8 @@ check_all_with_options(ViolationsDict, RequireAdr) :-
         rule_safety: RuleSafety,
         rule_verifiability: RuleVerifiability,
         semantic_completeness: SemanticCompleteness,
-        req_status_vocabulary: ReqStatusVocabulary
+        req_status_vocabulary: ReqStatusVocabulary,
+        proof_contract_symbols: ProofContractSymbols
     }.
 
 %% violations_dict_to_json(+ViolationsDict, -JsonDict)

package/src/discovery.pl

@@ -8,6 +8,9 @@
     coverage_report_json/11,
     coverage_report_json/12,
     coverage_evidence_json/5,
+    requirement_proof_json/5,
+    requirement_proof_json/7,
+    symbol_proof_json/7,
     graph_expand_json/8
 ]).
 
@@ -40,6 +43,58 @@ coverage_report_json(By, Tags, IncludePassing, IncludeTransitive, Limit, Offset,
 coverage_report_json(By, Tags, IncludePassing, IncludeTransitive, Limit, Offset, VerificationSnapshot, CheckedAt, MaxAgeSeconds, JsonString) :-
     coverage_report_json(By, Tags, IncludePassing, strict_snapshot, _{}, IncludeTransitive, Limit, Offset, VerificationSnapshot, CheckedAt, MaxAgeSeconds, JsonString).
 
+requirement_proof_json(ReqId, VerificationSnapshot, CheckedAt, MaxAgeSeconds, JsonString) :-
+    requirement_proof_json(ReqId, strict_snapshot, _{}, VerificationSnapshot, CheckedAt, MaxAgeSeconds, JsonString).
+
+requirement_proof_json(ReqId, BindingMode, TestBindings, VerificationSnapshot, CheckedAt, MaxAgeSeconds, JsonString) :-
+    requirement_proof_context(VerificationSnapshot, CheckedAt, MaxAgeSeconds, BindingMode, TestBindings, Context),
+    kb_entity(ReqId, req, Props),
+    requirement_proof(ReqId, Props, Context, Proof),
+    put_dict(id, Proof, ReqId, ProofWithId),
+    dict_json_string(ProofWithId, JsonString).
+
+symbol_proof_json(SymbolId, BindingMode, TestBindings, VerificationSnapshot, CheckedAt, MaxAgeSeconds, JsonString) :-
+    requirement_proof_context(VerificationSnapshot, CheckedAt, MaxAgeSeconds, BindingMode, TestBindings, Context),
+    kb_entity(SymbolId, symbol, _),
+    findall(ReqId,
+        (kb_relationship(implements, SymbolId, ReqId), kb_entity(ReqId, req, _)),
+        ReqIds0),
+    sort(ReqIds0, ReqIds),
+    maplist(requirement_proof_with_id(Context), ReqIds, Proofs),
+    symbol_explain_role(SymbolId, Role),
+    (kb:executable_test_symbol(SymbolId) -> ExecutableTest = true ; ExecutableTest = false),
+    findall(TestId, kb_relationship(executable_for, SymbolId, TestId), ExecutableFor0),
+    sort(ExecutableFor0, ExecutableFor),
+    findall(TestId, kb_relationship(covered_by, SymbolId, TestId), CoveredBy0),
+    sort(CoveredBy0, CoveredBy),
+    Response = _{
+        id: SymbolId,
+        symbolId: SymbolId,
+        role: Role,
+        executableTest: ExecutableTest,
+        implementingRequirements: ReqIds,
+        executableFor: ExecutableFor,
+        coveredBy: CoveredBy,
+        proofs: Proofs
+    },
+    dict_json_string(Response, JsonString).
+
+requirement_proof_with_id(Context, ReqId, ProofWithId) :-
+    kb_entity(ReqId, req, Props),
+    requirement_proof(ReqId, Props, Context, Proof),
+    put_dict(id, Proof, ReqId, ProofWithId).
+
+symbol_explain_role(SymbolId, executable_test) :-
+    kb:executable_test_symbol(SymbolId),
+    !.
+symbol_explain_role(SymbolId, Role) :-
+    kb_entity(SymbolId, symbol, Props),
+    memberchk(symbol_role=RawRole, Props),
+    kb:normalize_term_atom(RawRole, Role),
+    Role \= '',
+    !.
+symbol_explain_role(_SymbolId, unknown).
+
 % Slim per-requirement proof evidence for quality diagnostics (W1 push-down).
 % Projects only the fields the quality diagnostics consume - proof status,
 % the passing-e2e stage summary, and receipt-related gap codes - instead of

package/src/requirement_proof.pl

@@ -77,10 +77,10 @@ requirement_proof(ReqId, ReqProps, Context, Proof) :-
     logic_grounding_stage(ReqId, ReqProps, Inventory, Context, LogicStage),
     contradiction_stage(ReqId, LogicStage.status, Context, ContradictionStage),
     scenario_stage(ReqId, ScenarioStage, ScenarioIds),
-    scenario_test_stage(ScenarioIds, ScenarioTestStage, _ScenarioTests),
+    scenario_test_stage(ScenarioIds, ScenarioTestStage, ScenarioTests),
     passing_e2e_stage(ScenarioTestStage, Context, PassingE2eStage, PassingE2eTests),
     executable_symbol_stage(PassingE2eTests, ExecutableStage, ExecutableSymbols),
-    production_symbol_stage(ReqId, PassingE2eTests, ProductionStage, ProductionSymbols),
+    production_symbol_stage(ReqId, PassingE2eTests, ScenarioTests, PassingE2eStage.receiptEvidence, Context, ProductionStage, ProductionSymbols),
     source_coordinate_stage(ReqProps, ExecutableSymbols, ProductionSymbols, CoordinateStage),
     Stages = _{
         semanticInventory: SemanticStage,
@@ -103,7 +103,8 @@ requirement_proof(ReqId, ReqProps, Context, Proof) :-
         proofGaps: Gaps,
         proofAdvisories: Advisories,
         proofRepairs: Repairs,
-        proofStages: Stages
+        proofStages: Stages,
+        testResolutions: ScenarioTestStage.resolutions
     }.
 
 exempt_requirement_proof(Reason, Proof) :-
@@ -532,6 +533,7 @@ scenario_test_stage(ScenarioIds, Stage, ScenarioTests) :-
     ;   Status = passed
     ),
     maplist(entity_source_ref, ScenarioTests, Sources),
+    maplist(test_resolution_record, ScenarioTests, Resolutions),
     Stage = _{
         status: Status,
         scenarios: ScenarioIds,
@@ -539,7 +541,8 @@ scenario_test_stage(ScenarioIds, Stage, ScenarioTests) :-
         scenarioTestTargets: ScenarioTestTargets,
         invalidScenarioTestTargets: InvalidScenarioTestTargets,
         sources: Sources,
-        obligations: Obligations
+        obligations: Obligations,
+        resolutions: Resolutions
     }.
 
 scenario_test_obligation(ScenarioId, Obligation) :-
@@ -1069,6 +1072,14 @@ test_missing_executable_symbol(TestId) :-
     \+ (kb_relationship(executable_for, SymbolId, TestId), kb_entity(SymbolId, symbol, _)).
 
 production_symbol_stage(ReqId, PassingE2eTests, Stage, ProductionSymbols) :-
+    findall(TestId,
+        (kb_relationship(specified_by, ReqId, ScenarioId),
+         scenario_test(ScenarioId, TestId)),
+        ScenarioTests0),
+    sort(ScenarioTests0, ScenarioTests),
+    production_symbol_stage(ReqId, PassingE2eTests, ScenarioTests, [], _{}, Stage, ProductionSymbols).
+
+production_symbol_stage(ReqId, PassingE2eTests, ScenarioTests, ReceiptEvidence, Context, Stage, ProductionSymbols) :-
     findall(SymbolId,
         (kb_relationship(implements, SymbolId, ReqId),
          kb_entity(SymbolId, symbol, _),
@@ -1080,12 +1091,16 @@ production_symbol_stage(ReqId, PassingE2eTests, Stage, ProductionSymbols) :-
     include(symbol_not_covered_by_tests(PassingE2eTests), ProductionSymbols, UncoveredSymbols),
     production_stage_status(ProductionSymbols, StructuralSymbols, PassingE2eTests, UncoveredSymbols, Status, StatusReason),
     maplist(symbol_coordinate_ref, ProductionSymbols, Coordinates),
+    production_coverage_explanations(
+        ReqId, ProductionSymbols, StructuralSymbols, UncoveredSymbols,
+        PassingE2eTests, ScenarioTests, ReceiptEvidence, Context, Explanations),
     StageBase = _{
         status: Status,
         symbols: ProductionSymbols,
         structuralSymbols: StructuralSymbols,
         uncoveredSymbols: UncoveredSymbols,
-        coordinates: Coordinates
+        coordinates: Coordinates,
+        explanations: Explanations
     },
     (   Status == passed
     ->  Stage = StageBase
@@ -1127,6 +1142,271 @@ production_stage_status(ProductionSymbols, StructuralSymbols, PassingE2eTests, U
 symbol_not_covered_by_tests(Tests, SymbolId) :-
     \+ (member(TestId, Tests), kb_relationship(covered_by, SymbolId, TestId)).
 
+production_coverage_explanations(ReqId, ProductionSymbols, StructuralSymbols, UncoveredSymbols,
+        PassingE2eTests, ScenarioTests, ReceiptEvidence, Context, Explanations) :-
+    maplist(production_symbol_explanation(ReqId, UncoveredSymbols, PassingE2eTests, ScenarioTests, ReceiptEvidence, Context),
+            ProductionSymbols, ProductionExplanations),
+    maplist(structural_symbol_explanation(ReqId, PassingE2eTests, ScenarioTests, ReceiptEvidence, Context),
+            StructuralSymbols, StructuralExplanations),
+    append(ProductionExplanations, StructuralExplanations, Explanations).
+
+structural_symbol_explanation(ReqId, PassingE2eTests, ScenarioTests, ReceiptEvidence, Context, SymbolId, Explanation) :-
+    symbol_classification(SymbolId, Classification),
+    symbol_coverage_candidates(structural, PassingE2eTests, ScenarioTests, ReceiptEvidence, Context, SymbolId, Candidates),
+    explanation_reason_text(structural_unit_contract, ReasonText),
+    Explanation = _{
+        symbolId: SymbolId,
+        requirementId: ReqId,
+        classification: Classification,
+        status: covered,
+        reason: structural_unit_contract,
+        reasonText: ReasonText,
+        coverageCandidates: Candidates
+    }.
+
+production_symbol_explanation(ReqId, UncoveredSymbols, PassingE2eTests, ScenarioTests, ReceiptEvidence, Context, SymbolId, Explanation) :-
+    symbol_classification(SymbolId, Classification),
+    symbol_coverage_candidates(behavioral, PassingE2eTests, ScenarioTests, ReceiptEvidence, Context, SymbolId, Candidates),
+    production_symbol_rollup(UncoveredSymbols, PassingE2eTests, SymbolId, Candidates, Status, Reason),
+    explanation_reason_text(Reason, ReasonText),
+    Explanation = _{
+        symbolId: SymbolId,
+        requirementId: ReqId,
+        classification: Classification,
+        status: Status,
+        reason: Reason,
+        reasonText: ReasonText,
+        coverageCandidates: Candidates
+    }.
+
+production_symbol_rollup(_Uncovered, [], _SymbolId, _Candidates, uncovered, stage_blocked_no_passing_e2e) :-
+    !.
+production_symbol_rollup(UncoveredSymbols, _Passing, SymbolId, Candidates, uncovered, Reason) :-
+    memberchk(SymbolId, UncoveredSymbols),
+    !,
+    (Candidates == [] -> Reason = covered_by_missing ; Reason = no_qualifying_e2e_coverage).
+production_symbol_rollup(_Uncovered, _Passing, _SymbolId, _Candidates, covered, covered).
+
+symbol_classification(SymbolId, Classification) :-
+    kb_entity(SymbolId, symbol, Props),
+    memberchk(symbol_role=RawRole, Props),
+    normalize_atom(RawRole, Role),
+    Role \= '',
+    !,
+    Classification = Role.
+symbol_classification(_SymbolId, unknown).
+
+symbol_coverage_candidates(Mode, PassingE2eTests, ScenarioTests, ReceiptEvidence, Context, SymbolId, Candidates) :-
+    findall(TestId, kb_relationship(covered_by, SymbolId, TestId), TestIds0),
+    sort(TestIds0, TestIds),
+    maplist(coverage_candidate_dict(Mode, PassingE2eTests, ScenarioTests, ReceiptEvidence, Context), TestIds, Candidates).
+
+coverage_candidate_dict(Mode, PassingE2eTests, ScenarioTests, ReceiptEvidence, Context, TestId, Candidate) :-
+    coverage_candidate_qualification(Mode, PassingE2eTests, ScenarioTests, ReceiptEvidence, Context, TestId, Qualifies, Primary, Secondaries),
+    explanation_reason_text(Primary, ReasonText),
+    cheap_candidate_scope(TestId, Scope),
+    reused_receipt_state(ReceiptEvidence, TestId, ReceiptState),
+    CandidateBase = _{
+        testId: TestId,
+        relationship: covered_by,
+        qualifies: Qualifies,
+        reason: Primary,
+        reasonText: ReasonText,
+        secondaryReasons: Secondaries,
+        scope: Scope
+    },
+    (   ReceiptState == none
+    ->  Candidate = CandidateBase
+    ;   put_dict(receiptState, CandidateBase, ReceiptState, Candidate)
+    ).
+
+% Shared candidate evaluator. Mode selects the coverage contract:
+%   behavioral  — production symbols require passing scenario-backed E2E
+%   structural  — type-shape symbols may also qualify via a unit contract
+coverage_candidate_qualification(_Mode, PassingE2eTests, _ScenarioTests, _ReceiptEvidence, _Context, TestId, true, covered, []) :-
+    memberchk(TestId, PassingE2eTests),
+    !.
+coverage_candidate_qualification(_Mode, _Passing, _Scenario, _Evidence, _Context, TestId, false, missing_test_entity, []) :-
+    \+ kb_entity(TestId, test, _),
+    !.
+coverage_candidate_qualification(structural, _Passing, _Scenario, _Evidence, _Context, TestId, true, structural_unit_contract, []) :-
+    structural_unit_contract_test(TestId),
+    !.
+coverage_candidate_qualification(_Mode, _Passing, ScenarioTests, ReceiptEvidence, Context, TestId, false, Primary, Secondaries) :-
+    cheap_scope_reject_reason(TestId, ScopeReason),
+    (   \+ memberchk(TestId, ScenarioTests)
+    ->  Primary = test_not_in_requirement_scenario_chain,
+        maybe_singleton(ScopeReason, ScopeSecondaries),
+        reused_receipt_reject_reasons(ReceiptEvidence, TestId, ReceiptSecondaries),
+        append(ScopeSecondaries, ReceiptSecondaries, Secondaries)
+    ;   ScopeReason \= none
+    ->  Primary = ScopeReason,
+        reused_receipt_reject_reasons(ReceiptEvidence, TestId, Secondaries)
+    ;   receipt_reject_for_in_chain(ReceiptEvidence, Context, TestId, Primary, Secondaries)
+    ).
+
+structural_unit_contract_test(TestId) :-
+    kb_entity(TestId, test, TestProps),
+    test_scope(TestProps, unit),
+    memberchk(status=RawStatus, TestProps),
+    normalize_atom(RawStatus, Status),
+    memberchk(Status, [active, passing]).
+
+cheap_candidate_scope(TestId, Scope) :-
+    kb_entity(TestId, test, Props),
+    !,
+    test_scope(Props, Scope).
+cheap_candidate_scope(_TestId, unknown).
+
+cheap_scope_reject_reason(TestId, Reason) :-
+    cheap_candidate_scope(TestId, Scope),
+    scope_reject_reason(Scope, Reason).
+
+scope_reject_reason(unit, test_scope_is_unit) :- !.
+scope_reject_reason(end_to_end, none) :- !.
+scope_reject_reason(_Scope, test_scope_is_non_e2e).
+
+maybe_singleton(none, []) :- !.
+maybe_singleton(Reason, [Reason]).
+
+reused_receipt_state(Evidence, TestId, State) :-
+    member(Item, Evidence),
+    Item.testId == TestId,
+    !,
+    State = Item.state.
+reused_receipt_state(_Evidence, _TestId, none).
+
+reused_receipt_item(Evidence, TestId, Item) :-
+    member(Item, Evidence),
+    Item.testId == TestId,
+    !.
+
+reused_receipt_reject_reasons(Evidence, TestId, Reasons) :-
+    reused_receipt_item(Evidence, TestId, Item),
+    !,
+    receipt_item_reject_reason(Item, Reason),
+    maybe_singleton(Reason, Reasons).
+reused_receipt_reject_reasons(_Evidence, _TestId, []).
+
+receipt_reject_for_in_chain(Evidence, _Context, TestId, Primary, []) :-
+    reused_receipt_item(Evidence, TestId, Item),
+    !,
+    receipt_item_reject_reason(Item, Reason),
+    (Reason == none -> Primary = no_qualifying_e2e_coverage ; Primary = Reason).
+receipt_reject_for_in_chain(_Evidence, Context, TestId, Primary, []) :-
+    is_dict(Context),
+    Context \= _{},
+    test_receipt_evidence(Context, TestId, Evidence),
+    !,
+    receipt_item_reject_reason(Evidence, Reason),
+    (Reason == none -> Primary = no_qualifying_e2e_coverage ; Primary = Reason).
+receipt_reject_for_in_chain(_Evidence, _Context, _TestId, no_qualifying_e2e_coverage, []).
+
+receipt_item_reject_reason(Item, stale_proof_receipt) :-
+    Item.state == stale,
+    get_dict(codeSnapshot, Item, _),
+    !.
+receipt_item_reject_reason(Item, receipt_snapshot_mismatch) :-
+    Item.state == stale,
+    !.
+receipt_item_reject_reason(Item, Reason) :-
+    receipt_state_reject_reason(Item.state, Reason).
+
+receipt_state_reject_reason(missing, missing_proof_receipt) :- !.
+receipt_state_reject_reason(snapshot_unavailable, proof_snapshot_unavailable) :- !.
+receipt_state_reject_reason(contract_mismatch, receipt_contract_mismatch) :- !.
+receipt_state_reject_reason(invalid, invalid_proof_receipt) :- !.
+receipt_state_reject_reason(failed, failed_proof_receipt) :- !.
+receipt_state_reject_reason(not_end_to_end, none) :- !.
+receipt_state_reject_reason(stale, receipt_snapshot_mismatch) :- !.
+receipt_state_reject_reason(passed, none) :- !.
+receipt_state_reject_reason(none, none) :- !.
+receipt_state_reject_reason(_, none).
+
+explanation_reason_text(Reason, Text) :-
+    explanation_reason_text_def(Reason, Text),
+    !.
+explanation_reason_text(Reason, Reason) :-
+    atom(Reason).
+
+explanation_reason_text_def(covered, "Qualifying covered_by to a passing scenario-backed E2E test").
+explanation_reason_text_def(covered_by_missing, "No covered_by relationship to any test").
+explanation_reason_text_def(no_qualifying_e2e_coverage, "covered_by relationships exist but none qualify as passing scenario-backed E2E coverage").
+explanation_reason_text_def(structural_unit_contract, "type-shape symbol is satisfied by a unit structural contract").
+explanation_reason_text_def(executable_test, "Symbol is executable test code linked with executable_for").
+explanation_reason_text_def(stage_blocked_no_passing_e2e, "Production coverage cannot be evaluated because no passing E2E evidence is available for the current snapshot").
+explanation_reason_text_def(missing_test_entity, "covered_by target is not a test entity").
+explanation_reason_text_def(test_not_in_requirement_scenario_chain, "Test is not in this requirement's scenario chain").
+explanation_reason_text_def(test_scope_is_unit, "Test verification_scope is unit, which cannot cover behavioral production symbols").
+explanation_reason_text_def(test_scope_is_non_e2e, "Test verification_scope is not end_to_end").
+explanation_reason_text_def(proof_snapshot_unavailable, "Workspace snapshot is unavailable so receipt currency cannot be proven").
+explanation_reason_text_def(missing_proof_receipt, "Scenario-backed E2E test has no kibi.proof-receipt.v1").
+explanation_reason_text_def(receipt_snapshot_mismatch, "Receipts exist but none match the current snapshot or binding").
+explanation_reason_text_def(stale_proof_receipt, "Current-snapshot receipt is older than the allowed proof age").
+explanation_reason_text_def(receipt_contract_mismatch, "Receipt does not match the current proof contract hash or fingerprint").
+explanation_reason_text_def(invalid_proof_receipt, "Receipt evidence is malformed or otherwise uncheckable").
+explanation_reason_text_def(failed_proof_receipt, "Latest current receipt outcome is not passed").
+
+test_resolution_record(TestId, _{
+    testId: TestId,
+    requiredProofs: RequiredProofs,
+    executableFor: ExecutableFor
+}) :-
+    test_required_proof_refs(TestId, RequiredProofs),
+    test_executable_for_refs(TestId, ExecutableFor).
+
+test_required_proof_refs(TestId, Refs) :-
+    kb_entity(TestId, test, Props),
+    memberchk(proof_contract=RawContract, Props),
+    proof_contract_dict(RawContract, Contract),
+    contract_required_symbol_ids(Contract, SymbolIds),
+    !,
+    maplist(symbol_resolution_ref, SymbolIds, Refs).
+test_required_proof_refs(_TestId, []).
+
+contract_required_symbol_ids(Contract, SymbolIds) :-
+    (   get_dict(required_proofs, Contract, Raw)
+    ;   get_dict('required_proofs', Contract, Raw)
+    ),
+    !,
+    inventory_entries(Raw, Entries),
+    findall(SymbolId,
+        (member(Entry, Entries), required_proof_entry_symbol(Entry, SymbolId)),
+        SymbolIds0),
+    sort(SymbolIds0, SymbolIds).
+contract_required_symbol_ids(_, []).
+
+required_proof_entry_symbol(Entry, SymbolId) :-
+    (   inventory_entry_field(Entry, symbol_id, Raw)
+    ;   inventory_entry_field(Entry, symbolId, Raw)
+    ),
+    normalize_atom(Raw, SymbolId),
+    SymbolId \= ''.
+
+test_executable_for_refs(TestId, Refs) :-
+    findall(SymbolId,
+        (kb_relationship(executable_for, SymbolId, TestId), kb_entity(SymbolId, symbol, _)),
+        SymbolIds0),
+    sort(SymbolIds0, SymbolIds),
+    maplist(symbol_resolution_ref, SymbolIds, Refs).
+
+symbol_resolution_ref(SymbolId, Ref) :-
+    kb_entity(SymbolId, symbol, _),
+    !,
+    symbol_coordinate_ref(SymbolId, Coord),
+    symbol_classification(SymbolId, Role),
+    put_dict(_{role: Role, exists: true}, Coord, Ref).
+symbol_resolution_ref(SymbolId, _{
+    id: SymbolId,
+    sourceFile: '',
+    sourceLine: 0,
+    sourceColumn: 0,
+    sourceEndLine: 0,
+    sourceEndColumn: 0,
+    role: unresolved,
+    exists: false
+}).
+
 source_coordinate_stage(ReqProps, ExecutableSymbols, ProductionSymbols, Stage) :-
     append(ExecutableSymbols, ProductionSymbols, Symbols0),
     sort(Symbols0, Symbols),

package/src/rule_registry.pl

@@ -33,6 +33,7 @@ known_rule('strict-req-fact-pairing').
 known_rule('predicate-verifiability').
 known_rule('strict-readiness').
 known_rule('semantic-completeness').
+known_rule('proof-contract-symbols').
 
 rule_enforcement_class('must-priority-coverage', canonical).
 rule_enforcement_class('symbol-coverage', canonical).
@@ -53,6 +54,7 @@ rule_enforcement_class('strict-req-fact-pairing', advisory).
 rule_enforcement_class('predicate-verifiability', advisory).
 rule_enforcement_class('strict-readiness', migration).
 rule_enforcement_class('semantic-completeness', migration).
+rule_enforcement_class('proof-contract-symbols', advisory).
 
 rule_implementation('must-priority-coverage', prolog).
 rule_implementation('symbol-coverage', prolog).
@@ -73,6 +75,7 @@ rule_implementation('strict-req-fact-pairing', prolog).
 rule_implementation('predicate-verifiability', prolog).
 rule_implementation('strict-readiness', prolog).
 rule_implementation('semantic-completeness', prolog).
+rule_implementation('proof-contract-symbols', prolog).
 
 rule_predicate('must-priority-coverage', check_must_priority_coverage).
 rule_predicate('symbol-coverage', check_symbol_coverage).
@@ -91,6 +94,7 @@ rule_predicate('strict-req-fact-pairing', check_strict_req_fact_pairing).
 rule_predicate('predicate-verifiability', check_predicate_verifiability).
 rule_predicate('strict-readiness', check_strict_readiness).
 rule_predicate('semantic-completeness', check_semantic_completeness).
+rule_predicate('proof-contract-symbols', check_proof_contract_symbols).
 
 rule_predicate_arity('must-priority-coverage', 1).
 rule_predicate_arity('symbol-coverage', 1).
@@ -109,6 +113,7 @@ rule_predicate_arity('strict-req-fact-pairing', 1).
 rule_predicate_arity('predicate-verifiability', 1).
 rule_predicate_arity('strict-readiness', 1).
 rule_predicate_arity('semantic-completeness', 1).
+rule_predicate_arity('proof-contract-symbols', 1).
 
 rule_description('must-priority-coverage', 'Every must-priority requirement must have a scenario and a test').
 rule_description('symbol-coverage', 'Production symbols need qualifying coverage via covered_by plus a canonical requirement/scenario test path').
@@ -129,3 +134,4 @@ rule_description('strict-req-fact-pairing', 'Detect requirements with incomplete
 rule_description('predicate-verifiability', 'Detect requires_predicate links that do not target ground fact_kind: predicate facts').
 rule_description('strict-readiness', 'Report strict contradiction-readiness levels for requirements that are still prose-only or otherwise not contradiction-ready').
 rule_description('semantic-completeness', 'Every inventoried assertive proposition is modeled or explicitly classified').
+rule_description('proof-contract-symbols', 'Detect unresolved required_proofs.symbol_id values, type-shape required proofs, and proof_bindings.source_file disagreement with the named symbol sourceFile').