kibi-core 0.12.0 → 0.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kibi-core",
-  "version": "0.12.0",
+  "version": "0.14.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/schema/entities.pl

@@ -65,6 +65,9 @@ entity_property(fact, predicate_arity, integer).
 entity_property(fact, argument_names, list).
 entity_property(fact, argument_types, list).
 entity_property(fact, argument_descriptions, list).
+% Predicate-schema vocabularies are JSON objects serialized as strings.
+entity_property(fact, argument_constants, string).
+entity_property(fact, argument_aliases, string).
 entity_property(fact, aliases, list).
 entity_property(fact, examples, list).
 entity_property(fact, predicate_args, list).

package/schema/relationships.pl

@@ -17,6 +17,7 @@ relationship_type(publishes).
 relationship_type(consumes).
 relationship_type(relates_to).
 relationship_type(supersedes).
+relationship_type(restates).
 relationship_type(constrains).
 relationship_type(requires_property).
 relationship_type(requires_predicate).
@@ -49,6 +50,13 @@ valid_relationship(requires_rule, req, fact).
 %% OldAdrId's status should be archived or deprecated as a consequence.
 valid_relationship(supersedes, adr, adr).
 valid_relationship(supersedes, req, req).
+
+%% restates(+ReqId, +OtherReqId)
+%% ReqId intentionally restates OtherReqId (for example a product requirement
+%% echoed in a platform requirement). Both stay current; the pair is exempt
+%% from domain-redundancy. Use supersedes when one replaces the other.
+% implements REQ-kibi-restates-relationship
+valid_relationship(restates, req, req).
 % escape hatch - allow any to any
 valid_relationship(relates_to, _, _).
 

package/schema/validation.pl

@@ -105,6 +105,8 @@ is_fact_only_field(predicate_arity).
 is_fact_only_field(argument_names).
 is_fact_only_field(argument_types).
 is_fact_only_field(argument_descriptions).
+is_fact_only_field(argument_constants).
+is_fact_only_field(argument_aliases).
 is_fact_only_field(aliases).
 is_fact_only_field(examples).
 is_fact_only_field(predicate_args).

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
@@ -26,15 +27,33 @@
     check_rule_verifiability/1,
     check_semantic_completeness/1,
     check_req_status_vocabulary/1,
+    check_entity_id_style/1,
+    check_domain_redundancy/1,
+    check_domain_implication/1,
+    check_subject_key_identity/1,
+    check_subject_key_shape/1,
+    check_ontology_quality/1,
     run_checks_json/0,              % Entry point for JSON output
     violation_id_text/2             % Extract text from entity ID term (exported for testing)
 ]).
 
+% Source contains non-ASCII text; do not depend on the host locale.
+:- encoding(utf8).
+
 :- use_module(library(http/json)).
 :- use_module(library(http/json_convert)).
 :- use_module('kb.pl').
 :- use_module('../schema/entities.pl', [entity_type/1, required_property/2]).
 :- use_module('../schema/relationships.pl', [relationship_type/1]).
+:- use_module('semantic_quality.pl', [
+    logical_ground_signature/2,
+    check_entity_id_style/1,
+    check_domain_redundancy/1,
+    check_domain_implication/1,
+    check_subject_key_identity/1,
+    check_subject_key_shape/1,
+    check_ontology_quality/1
+]).
 :- use_module('logic_ir.pl', [logic_rule_safety/2, logic_rule_from_props/2, logic_rule_conflict/3, logic_rule_conflict_witness/3, logic_rules_stratified/1]).
 % GENERATED registry facts; single source is schema/rule-registry.json.
 :- use_module('rule_registry.pl', [known_rule/1]).
@@ -45,7 +64,7 @@ required_fields([id, title, status, created_at, updated_at, source]).
 % Relationship types to check for dangling references
 all_relationship_types([
     depends_on, verified_by, validates, specified_by,
-    constrains, requires_property, requires_predicate, requires_rule, supersedes, relates_to
+    constrains, requires_property, requires_predicate, requires_rule, supersedes, restates, relates_to
 ]).
 
 %% check_all(-ViolationsDict)
@@ -70,6 +89,13 @@ check_all(ViolationsDict) :-
     check_rule_verifiability(RuleVerifiability),
     check_semantic_completeness(SemanticCompleteness),
     check_req_status_vocabulary(ReqStatusVocabulary),
+    check_proof_contract_symbols(ProofContractSymbols),
+    check_entity_id_style(EntityIdStyle),
+    check_domain_redundancy(DomainRedundancy),
+    check_domain_implication(DomainImplication),
+    check_subject_key_identity(SubjectKeyIdentity),
+    check_subject_key_shape(SubjectKeyShape),
+    check_ontology_quality(OntologyQuality),
     ViolationsDict = _{
         must_priority_coverage: MustPriority,
         symbol_coverage: SymbolCoverage,
@@ -87,7 +113,14 @@ check_all(ViolationsDict) :-
         rule_safety: RuleSafety,
         rule_verifiability: RuleVerifiability,
         semantic_completeness: SemanticCompleteness,
-        req_status_vocabulary: ReqStatusVocabulary
+        req_status_vocabulary: ReqStatusVocabulary,
+        proof_contract_symbols: ProofContractSymbols,
+        entity_id_style: EntityIdStyle,
+        domain_redundancy: DomainRedundancy,
+        domain_implication: DomainImplication,
+        subject_key_identity: SubjectKeyIdentity,
+        subject_key_shape: SubjectKeyShape,
+        ontology_quality: OntologyQuality
     }.
 
 %% check_must_priority_coverage(-Violations)
@@ -131,7 +164,7 @@ symbol_coverage_violation(SymbolId, violation(
     'symbol-coverage',
     SymbolId,
     "Production symbol lacks qualifying requirement coverage.",
-    "Add 'covered_by: TEST-xxx' for production coverage. If the requirement has specified_by a scenario, use verified_by(scenario,test) or validates(test,scenario). Direct verified_by(req,test) does not count when a scenario exists.",
+    "Add 'covered_by: TEST-<area>-<behavior>' for production coverage. If the requirement has specified_by a scenario, use verified_by(scenario,test) or validates(test,scenario). Direct verified_by(req,test) does not count when a scenario exists.",
     Source
 )) :-
     violation_source(SymbolId, symbol, Source).
@@ -148,6 +181,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,
@@ -175,17 +219,129 @@ symbol_traceability_violation(RequireAdr, violation(
     % Determine what is missing
     (   HasReq = false, HasAdr = false, RequireAdr = true ->
         Description = "Symbol has no direct requirement ownership and no ADR constraint.",
-        Suggestion = "Add a direct 'implements: REQ-xxx' link for ownership, use 'covered_by' only for production coverage, use 'executable_for' only for executable test code, and add 'constrained_by: ADR-xxx' in symbols.yaml."
+        Suggestion = "Add a direct 'implements: REQ-<area>-<behavior>' link for ownership, use 'covered_by' only for production coverage, use 'executable_for' only for executable test code, and add 'constrained_by: ADR-<decision>' in symbols.yaml."
     ;   HasReq = false ->
         Description = "Symbol has no direct requirement ownership.",
-        Suggestion = "Add a direct 'implements: REQ-xxx' link for ownership. Use 'covered_by' for production coverage and 'executable_for' for executable test code identity."
+        Suggestion = "Add a direct 'implements: REQ-<area>-<behavior>' link for ownership. Use 'covered_by' for production coverage and 'executable_for' for executable test code identity."
     ;   HasAdr = false ->
         Description = "Symbol has no ADR constraint.",
-        Suggestion = "Add 'constrained_by: ADR-xxx' in symbols.yaml."
+        Suggestion = "Add 'constrained_by: ADR-<decision>' in symbols.yaml."
     ;   fail  % No 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) :-
@@ -1181,32 +1337,6 @@ grounded_requirement_claim_fact(ReqId, ClaimKey, FactId) :-
     kb_relationship(requires_rule, ReqId, FactId),
     ground_fact_claim_key(FactId, rule, ClaimKey).
 
-logical_ground_signature(FactId, predicate(Namespace, Name, Args, Polarity)) :-
-    kb:predicate_fact(FactId, Namespace, Name, Args, Polarity).
-logical_ground_signature(
-    FactId,
-    property(Subject, Property, Operator, ValueType, Value, Unit, Scope, Polarity)
-) :-
-    kb:fact_property_tuple(
-        FactId,
-        Subject,
-        Property,
-        Operator,
-        ValueType,
-        Value,
-        Unit,
-        Scope,
-        Polarity
-    ).
-logical_ground_signature(FactId, rule(SemanticKey)) :-
-    kb_entity(FactId, fact, Props),
-    memberchk(fact_kind=RawKind, Props),
-    normalize_term_atom(RawKind, rule),
-    (   memberchk(semantic_key=RawKey, Props)
-    ->  normalize_term_atom(RawKey, SemanticKey)
-    ;   memberchk(rule_hash=RawKey, Props), normalize_term_atom(RawKey, SemanticKey)
-    ).
-
 ground_fact_claim_key(FactId, ExpectedKind, ClaimKey) :-
     kb_entity(FactId, fact, Props),
     memberchk(fact_kind=RawKind, Props),
@@ -1478,7 +1608,14 @@ 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,
+    entity_id_style: EntityIdStyle,
+    domain_redundancy: DomainRedundancy,
+    domain_implication: DomainImplication,
+    subject_key_identity: SubjectKeyIdentity,
+    subject_key_shape: SubjectKeyShape,
+    ontology_quality: OntologyQuality
 }) :-
     selected_rule(Rules, 'must-priority-coverage', check_must_priority_coverage, MustPriority),
     selected_rule(Rules, 'symbol-coverage', check_symbol_coverage, SymbolCoverage),
@@ -1496,7 +1633,14 @@ 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, 'entity-id-style', check_entity_id_style, EntityIdStyle),
+    selected_rule(Rules, 'domain-redundancy', check_domain_redundancy, DomainRedundancy),
+    selected_rule(Rules, 'domain-implication', check_domain_implication, DomainImplication),
+    selected_rule(Rules, 'subject-key-identity', check_subject_key_identity, SubjectKeyIdentity),
+    selected_rule(Rules, 'subject-key-shape', check_subject_key_shape, SubjectKeyShape),
+    selected_rule(Rules, 'ontology-quality', check_ontology_quality, OntologyQuality).
 
 selected_rule(Rules, Name, Goal, Violations) :-
     (   memberchk(Name, Rules)
@@ -1552,6 +1696,13 @@ check_all_with_options(ViolationsDict, RequireAdr) :-
     check_rule_verifiability(RuleVerifiability),
     check_semantic_completeness(SemanticCompleteness),
     check_req_status_vocabulary(ReqStatusVocabulary),
+    check_proof_contract_symbols(ProofContractSymbols),
+    check_entity_id_style(EntityIdStyle),
+    check_domain_redundancy(DomainRedundancy),
+    check_domain_implication(DomainImplication),
+    check_subject_key_identity(SubjectKeyIdentity),
+    check_subject_key_shape(SubjectKeyShape),
+    check_ontology_quality(OntologyQuality),
     ViolationsDict = _{
         must_priority_coverage: MustPriority,
         symbol_coverage: SymbolCoverage,
@@ -1569,7 +1720,14 @@ 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,
+        entity_id_style: EntityIdStyle,
+        domain_redundancy: DomainRedundancy,
+        domain_implication: DomainImplication,
+        subject_key_identity: SubjectKeyIdentity,
+        subject_key_shape: SubjectKeyShape,
+        ontology_quality: OntologyQuality
     }.
 
 %% violations_dict_to_json(+ViolationsDict, -JsonDict)
@@ -1588,7 +1746,12 @@ pairs_to_json_pairs([Key-Violations|Rest], [Key-JsonViolations|JsonRest]) :-
 
 %% violation_to_json(+Violation, -JsonDict)
 % Converts a violation(Rule, EntityId, Description, Suggestion, Source) term
-% to a JSON-compatible dict.
+% to a JSON-compatible dict. violation/6 carries precomputed JSON-safe
+% evidence (witnesses) as its sixth argument.
+violation_to_json(violation(Rule, EntityId, Description, Suggestion, Source, Evidence), JsonDict) :-
+    !,
+    violation_term_to_dict(violation(Rule, EntityId, Description, Suggestion, Source), BaseDict),
+    put_dict(evidence, BaseDict, Evidence, JsonDict).
 violation_to_json(Violation, JsonDict) :-
     violation_term_to_dict(Violation, BaseDict),
     (   contradiction_violation_witnesses(Violation, Witnesses),

package/src/discovery.pl

@@ -8,15 +8,22 @@
     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
 ]).
 
+% Source contains non-ASCII text; do not depend on the host locale.
+:- encoding(utf8).
+
 :- use_module(library(http/json)).
 :- use_module(library(aggregate)).
 :- use_module(library(apply)).
 :- use_module(library(lists)).
 :- use_module(library(pairs)).
 :- use_module('kb.pl').
+:- use_module(library(semweb/rdf_db), [rdf_generation/1]).
 :- use_module('requirement_proof.pl', [requirement_proof_context/1, requirement_proof_context/4, requirement_proof_context/6, requirement_proof/4]).
 :- use_module('status.pl', [status_meta_dict/1]).
 :- use_module('../schema/relationships.pl', [relationship_type/1]).
@@ -40,6 +47,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
@@ -98,11 +157,11 @@ coverage_evidence_receipt_gap(Gap) :-
 coverage_report_json(By, Tags, IncludePassing, BindingMode, TestBindings, IncludeTransitive, Limit, Offset, VerificationSnapshot, CheckedAt, MaxAgeSeconds, JsonString) :-
     % Binding mode applies to requirement rows only; other By values keep
     % their snapshot-era arity so type/symbol reports are unchanged.
-    (   By == req
-    ->  coverage_rows(req, Tags, IncludePassing, IncludeTransitive, VerificationSnapshot, CheckedAt, MaxAgeSeconds, BindingMode, TestBindings, Rows0, Summary)
-    ;   coverage_rows(By, Tags, IncludePassing, IncludeTransitive, VerificationSnapshot, CheckedAt, MaxAgeSeconds, Rows0, Summary)
-    ),
-    sort_dict_rows(Rows0, SortedRows),
+    memo_sorted_coverage(
+        binding(By, Tags, IncludePassing, BindingMode, TestBindings, IncludeTransitive, VerificationSnapshot, CheckedAt, MaxAgeSeconds),
+        binding_coverage_rows(By, Tags, IncludePassing, BindingMode, TestBindings, IncludeTransitive, VerificationSnapshot, CheckedAt, MaxAgeSeconds),
+        SortedRows,
+        Summary),
     paginate_rows(SortedRows, Offset, Limit, Rows),
     status_meta_dict(Meta),
     Response = _{summary: Summary, rows: Rows, meta: Meta},
@@ -116,13 +175,44 @@ coverage_report_json(By, Tags, IncludePassing, BindingMode, TestBindings, Includ
 % reason — without diffing full exports by hand. The summary is always
 % computed over all rows so filtered responses keep whole-KB counts.
 coverage_report_json(By, Tags, IncludePassing, StatusFilter, IncludeTransitive, Limit, Offset, VerificationSnapshot, CheckedAt, MaxAgeSeconds, JsonString) :-
-    status_filtered_coverage_rows(By, Tags, IncludePassing, StatusFilter, IncludeTransitive, VerificationSnapshot, CheckedAt, MaxAgeSeconds, MatchedRows0, Summary),
-    sort_dict_rows(MatchedRows0, SortedRows),
+    memo_sorted_coverage(
+        status(By, Tags, IncludePassing, StatusFilter, IncludeTransitive, VerificationSnapshot, CheckedAt, MaxAgeSeconds),
+        status_filtered_coverage_rows(By, Tags, IncludePassing, StatusFilter, IncludeTransitive, VerificationSnapshot, CheckedAt, MaxAgeSeconds),
+        SortedRows,
+        Summary),
     paginate_rows(SortedRows, Offset, Limit, Rows),
     status_meta_dict(Meta),
     Response = _{summary: Summary, rows: Rows, meta: Meta},
     dict_json_string(Response, JsonString).
 
+binding_coverage_rows(req, Tags, IncludePassing, BindingMode, TestBindings, IncludeTransitive, VerificationSnapshot, CheckedAt, MaxAgeSeconds, Rows, Summary) :-
+    !,
+    coverage_rows(req, Tags, IncludePassing, IncludeTransitive, VerificationSnapshot, CheckedAt, MaxAgeSeconds, BindingMode, TestBindings, Rows, Summary).
+binding_coverage_rows(By, Tags, IncludePassing, _BindingMode, _TestBindings, IncludeTransitive, VerificationSnapshot, CheckedAt, MaxAgeSeconds, Rows, Summary) :-
+    coverage_rows(By, Tags, IncludePassing, IncludeTransitive, VerificationSnapshot, CheckedAt, MaxAgeSeconds, Rows, Summary).
+
+:- dynamic coverage_memo/3.
+
+%% memo_sorted_coverage(+Args, :Compute, -SortedRows, -Summary)
+% Large coverage reports are fetched in bounded pages so no single answer
+% approaches the engine's output cap. Every page would otherwise recompute
+% the whole report; keep the most recent sorted result for the exact
+% arguments, graph, and RDF generation. Coverage reads only the store and its
+% arguments, so the memo is invalidated by any store change.
+memo_sorted_coverage(Args, Compute, SortedRows, Summary) :-
+    (kb:kb_graph(Graph) -> true ; Graph = none),
+    rdf_generation(Generation),
+    Key = key(Args, Graph, Generation),
+    (   coverage_memo(Stored, StoredRows, StoredSummary),
+        Stored =@= Key
+    ->  SortedRows = StoredRows,
+        Summary = StoredSummary
+    ;   call(Compute, Rows0, Summary),
+        sort_dict_rows(Rows0, SortedRows),
+        retractall(coverage_memo(_, _, _)),
+        assertz(coverage_memo(Key, SortedRows, Summary))
+    ).
+
 status_filtered_coverage_rows(By, Tags, IncludePassing, [], IncludeTransitive, VerificationSnapshot, CheckedAt, MaxAgeSeconds, Rows, Summary) :-
     !,
     coverage_rows(By, Tags, IncludePassing, IncludeTransitive, VerificationSnapshot, CheckedAt, MaxAgeSeconds, Rows, Summary).