kibi-core 0.17.2 → 0.18.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kibi-core",
-  "version": "0.17.2",
+  "version": "0.18.0",
   "private": false,
   "description": "Core Prolog modules and RDF graph logic for Kibi",
   "type": "module",

package/src/discovery.pl

@@ -32,18 +32,32 @@
 :- use_module('../schema/relationships.pl', [relationship_type/1]).
 
 find_gaps_json(TypeFilter, MissingRelationships, PresentRelationships, Tags, SourceFilter, Limit, Offset, JsonString) :-
+    % One pass over the entities: every candidate carries whether it is a
+    % provenance stub, so the rows and the stub count share the enumeration.
     findall(
-        Row,
-        matching_gap_row(TypeFilter, MissingRelationships, PresentRelationships, Tags, SourceFilter, Row),
-        Rows0
+        Row-Stub,
+        matching_gap_candidate(TypeFilter, MissingRelationships, PresentRelationships, Tags, SourceFilter, Row, Stub),
+        Candidates
     ),
+    findall(Row, (member(Row-Stub, Candidates), gap_row_visible(Tags, Stub)), Rows0),
     sort_dict_rows(Rows0, SortedRows),
     paginate_rows(SortedRows, Offset, Limit, Rows),
     length(SortedRows, Count),
+    % Provenance stubs that match the same filters are counted apart
+    % (summary.provenanceStubs) whether or not the requested tags let them
+    % into the rows, so a caller can tell "no gaps" from "only stubs".
+    % implements REQ-bootstrap-provenance-stubs
+    aggregate_all(count, member(_-true, Candidates), StubCount),
+    Summary = _{total: Count, provenanceStubs: StubCount},
     status_meta_dict(Meta),
-    Response = _{rows: Rows, count: Count, meta: Meta},
+    Response = _{rows: Rows, count: Count, summary: Summary, meta: Meta},
     dict_json_string(Response, JsonString).
 
+% A stub enters the rows only when the caller asked for its tag.
+gap_row_visible(_Tags, false).
+gap_row_visible(Tags, true) :-
+    memberchk('bootstrap:provenance-stub', Tags).
+
 coverage_report_json(By, Tags, IncludePassing, IncludeTransitive, Limit, Offset, JsonString) :-
     coverage_report_json(By, Tags, IncludePassing, IncludeTransitive, Limit, Offset, unknown, '1970-01-01T00:00:00Z', 604800, JsonString).
 
@@ -458,9 +472,15 @@ graph_expand_json(SeedIds, Relationships, Direction, Depth, EntityTypes, MaxNode
     dict_json_string(Response, JsonString).
 
 matching_gap_row(TypeFilter, MissingRelationships, PresentRelationships, Tags, SourceFilter, Row) :-
+    matching_gap_candidate(TypeFilter, MissingRelationships, PresentRelationships, Tags, SourceFilter, Row, Stub),
+    gap_row_visible(Tags, Stub).
+
+% implements REQ-bootstrap-provenance-stubs
+matching_gap_candidate(TypeFilter, MissingRelationships, PresentRelationships, Tags, SourceFilter, Row, Stub) :-
     kb_entity(Id, Type, Props),
     matches_type(TypeFilter, Type),
     matches_tags(Tags, Props),
+    (provenance_stub_props(Type, Props) -> Stub = true ; Stub = false),
     matches_source(SourceFilter, Props),
     relationships_missing(Id, MissingRelationships),
     relationships_present(Id, PresentRelationships),
@@ -477,6 +497,22 @@ matching_gap_row(TypeFilter, MissingRelationships, PresentRelationships, Tags, S
         source: Source
     }.
 
+%% provenance_stub_props(+Type, +Props)
+% A bootstrap provider fact that records only where an entry came from
+% (tagged bootstrap:provenance-stub). It is not knowledge: gap rows and
+% type coverage counts leave it out unless the caller asks for the tag.
+% implements REQ-bootstrap-provenance-stubs
+provenance_stub_props(fact, Props) :-
+    memberchk(tags=Tags, Props),
+    is_list(Tags),
+    member(Tag, Tags),
+    kb:normalize_term_atom(Tag, 'bootstrap:provenance-stub'),
+    !.
+
+hidden_provenance_stub(RequestedTags, Type, Props) :-
+    \+ memberchk('bootstrap:provenance-stub', RequestedTags),
+    provenance_stub_props(Type, Props).
+
 relationships_missing(_Id, []).
 relationships_missing(Id, [Relationship|Rest]) :-
     relationship_count(Id, Relationship, 0),
@@ -537,7 +573,8 @@ coverage_rows(type, _Tags, _IncludePassing, _IncludeTransitive, _VerificationSna
         Pairs),
     maplist(type_pair_row, Pairs, Rows),
     length(Rows, Total),
-    Summary = _{total: Total}.
+    aggregate_all(count, provenance_stub_entity(_), StubCount),
+    Summary = _{total: Total, provenanceStubs: StubCount}.
 
 coverage_rows(req, Tags, IncludePassing, IncludeTransitive, VerificationSnapshot, CheckedAt, MaxAgeSeconds, Rows, Summary) :-
     !,
@@ -890,10 +927,16 @@ must_priority(Priority) :-
     downcase_atom(Priority, Lowercase),
     sub_atom(Lowercase, _, 4, 0, must).
 
+% Provenance stubs are counted apart (summary.provenanceStubs), never as facts.
+% implements REQ-bootstrap-provenance-stubs
 type_entity_count(Type, Count) :-
-    setof(Id, Props^kb_entity(Id, Type, Props), Ids),
+    setof(Id, Props^(kb_entity(Id, Type, Props), \+ provenance_stub_props(Type, Props)), Ids),
     length(Ids, Count).
 
+provenance_stub_entity(Id) :-
+    kb_entity(Id, fact, Props),
+    provenance_stub_props(fact, Props).
+
 type_pair_row(Type-Count, _{id: Type, type: Type, count: Count}).
 
 bfs_layers(_Frontier, SeenNodes, SeenEdges, _Relationships, _Direction, 0, _MaxNodes, _MaxEdges, SeenNodes, SeenEdges, false) :- !.

package/src/kb.pl

@@ -15,6 +15,7 @@
     kb_assert_entity_no_audit/2,
     kb_commit_upsert/5,
     kb_commit_upsert_batch/2,
+    kb_preview_upsert_contradiction/3,
     kb_log_entity_upsert/3,
     kb_retract_entity/1,
     kb_retract_entity/3,
@@ -1136,6 +1137,36 @@ kb_stage_upsert(Type, Props, Relationships, SkipContradiction, ChangeKind) :-
     kb_log_entity_upsert(ChangeKind, Type, Props),
     kb_commit_relationship_audits(Relationships).
 
+%% kb_preview_upsert_contradiction(+Type, +Properties, +Relationships)
+% implements REQ-kibi-operation-interface-parity
+% Stage one upsert in a transaction that is always rolled back and run the
+% commit-time requirement contradiction check against the staged KB, so a
+% kb_upsert dry run refuses exactly what the commit would refuse. Nothing is
+% written and nothing marks the branch dirty: the no-audit assertions only
+% touch the RDF store, which the transaction rolls back, and no audit entry,
+% snapshot save or journal flush follows. The entity index is not
+% transactional, so the staged id is re-indexed from the restored store.
+kb_preview_upsert_contradiction(Type, Props, Relationships) :-
+    memberchk(id=Id, Props),
+    with_kb_mutex(
+        call_cleanup(
+            catch(
+                rdf_transaction((
+                    kb_assert_entity_no_audit(Type, Props),
+                    kb_commit_relationships_no_audit(Relationships),
+                    kb_maybe_check_req_contradiction(Type, Id, false),
+                    throw(kibi_preview_rolled_back)
+                )),
+                Caught,
+                (   Caught == kibi_preview_rolled_back
+                ->  true
+                ;   throw(Caught)
+                )
+            ),
+            kb_refresh_entity_index(Id)
+        )
+    ).
+
 kb_stage_upserts([], []).
 kb_stage_upserts([
     upsert(Type, Props, Relationships, SkipContradiction)|Rest

package/src/requirement_proof.pl

@@ -705,13 +705,22 @@ unique_evidence_by_test(Evidence0, Evidence) :-
     sort(TestIds0, TestIds),
     maplist(first_evidence_for_test(Evidence0), TestIds, Evidence).
 
+% A test shared by scenarios with different accepted scopes keeps its receipt
+% state from any scenario that accepts its scope, independent of scenario order.
+% implements REQ-ui-pattern-component-proof
+first_evidence_for_test(Evidence, TestId, Item) :-
+    member(Item, Evidence),
+    Item.testId == TestId,
+    Item.state \== not_end_to_end,
+    !.
 first_evidence_for_test(Evidence, TestId, Item) :-
     member(Item, Evidence),
     Item.testId == TestId,
     !.
 
 scenario_passing_e2e_obligation(Context, TestObligation, Obligation) :-
-    maplist(test_receipt_evidence(Context), TestObligation.tests, Evidence),
+    scenario_accepted_scopes(TestObligation.scenarioId, AcceptedScopes),
+    maplist(test_receipt_evidence(Context, AcceptedScopes), TestObligation.tests, Evidence),
     include(e2e_evidence, Evidence, E2eEvidence),
     include(non_e2e_evidence, Evidence, NonEndToEndEvidence),
     evidence_tests_with_state(E2eEvidence, passed, PassingE2eTests),
@@ -734,6 +743,7 @@ scenario_passing_e2e_obligation(Context, TestObligation, Obligation) :-
         scenarioTestTargets: TestObligation.scenarioTestTargets,
         invalidScenarioTestTargets: TestObligation.invalidScenarioTestTargets,
         tests: TestObligation.tests,
+        acceptedScopes: AcceptedScopes,
         e2eTests: E2eTests,
         nonEndToEndTests: NonEndToEndTests,
         evidence: Evidence,
@@ -747,6 +757,42 @@ scenario_passing_e2e_obligation(Context, TestObligation, Obligation) :-
         snapshotUnavailableTests: SnapshotUnavailableTests
     }.
 
+%% scenario_accepted_scopes(+ScenarioId, -Scopes)
+% End-to-end evidence proves every scenario. A scenario whose specifying
+% requirements are all grounded only in component-scope UI pattern predicates
+% may also be proven by a unit or integration test that renders the component
+% in isolation, with the same receipt rules (valid, fresh, passing).
+% implements REQ-ui-pattern-component-proof
+scenario_accepted_scopes(ScenarioId, [unit, integration, end_to_end]) :-
+    component_scope_scenario(ScenarioId),
+    !.
+scenario_accepted_scopes(_ScenarioId, [end_to_end]).
+
+%% component_scope_predicate(?Name)
+% Built-in UI pattern predicates a component rendered in isolation can prove:
+% the pattern, its markers and variant parity are visible in the rendered
+% markup. Layout claims (ui_container, visual_layout_rule) depend on real
+% rendering and keep the end-to-end requirement.
+component_scope_predicate(ui_pattern).
+component_scope_predicate(same_pattern).
+component_scope_predicate(pattern_marker).
+
+component_scope_scenario(ScenarioId) :-
+    findall(ReqId, kb_relationship(specified_by, ReqId, ScenarioId), ReqIds0),
+    sort(ReqIds0, ReqIds),
+    ReqIds \= [],
+    forall(member(ReqId, ReqIds), component_scope_requirement(ReqId)).
+
+component_scope_requirement(ReqId) :-
+    findall(FactId, kb_relationship(requires_predicate, ReqId, FactId), FactIds),
+    FactIds \= [],
+    forall(member(FactId, FactIds),
+        (   predicate_fact(FactId, _Namespace, Name, _Args, _Polarity),
+            component_scope_predicate(Name)
+        )),
+    \+ kb_relationship(requires_property, ReqId, _),
+    \+ kb_relationship(requires_rule, ReqId, _).
+
 e2e_evidence(Item) :- Item.state \= not_end_to_end.
 non_e2e_evidence(Item) :- Item.state == not_end_to_end.
 
@@ -799,9 +845,15 @@ evidence_tests_with_state(Evidence, State, TestIds) :-
     sort(TestIds0, TestIds).
 
 test_receipt_evidence(Context, TestId, Evidence) :-
+    test_receipt_evidence(Context, [end_to_end], TestId, Evidence).
+
+% implements REQ-ui-pattern-component-proof
+% AcceptedScopes lists the verification scopes whose receipts count for the
+% scenario. Tests outside them keep the nonblocking not_end_to_end state.
+test_receipt_evidence(Context, AcceptedScopes, TestId, Evidence) :-
     kb_entity(TestId, test, Props),
     test_scope(Props, Scope),
-    (   Scope \= end_to_end
+    (   \+ memberchk(Scope, AcceptedScopes)
     ->  Evidence = _{testId: TestId, state: not_end_to_end, scope: Scope}
     ;   Context.proofSnapshot == unknown
     ->  Evidence = _{testId: TestId, state: snapshot_unavailable, scope: Scope}
@@ -1216,7 +1268,7 @@ type_shape_symbol_with_structural_contract(SymbolId) :-
     memberchk(Status, [active, passing]).
 
 % Stage status plus a typed reason, from a single total clause so status and
-% reason can never disagree (the Align stale-receipts case reported `blocked`
+% reason can never disagree (a test project's stale-receipts case reported `blocked`
 % with no indication that fresh receipts were the unblock). Clause order keeps
 % the historical precedence: no production symbols at all is `missing` even
 % when E2E evidence is also absent; only then does absent E2E evidence read

package/src/rule_registry.pl

@@ -58,6 +58,8 @@ known_rule('adr-proposed').
 known_rule('predicate-schema-conformance').
 known_rule('entity-context-missing').
 known_rule('entity-context-acknowledged').
+known_rule('policy-ownership').
+known_rule('policy-markers').
 
 rule_enforcement_class('must-priority-coverage', canonical).
 rule_enforcement_class('symbol-coverage', canonical).
@@ -103,6 +105,8 @@ rule_enforcement_class('adr-proposed', advisory).
 rule_enforcement_class('predicate-schema-conformance', advisory).
 rule_enforcement_class('entity-context-missing', canonical).
 rule_enforcement_class('entity-context-acknowledged', advisory).
+rule_enforcement_class('policy-ownership', canonical).
+rule_enforcement_class('policy-markers', canonical).
 
 rule_implementation('must-priority-coverage', prolog).
 rule_implementation('symbol-coverage', prolog).
@@ -148,6 +152,8 @@ rule_implementation('adr-proposed', prolog).
 rule_implementation('predicate-schema-conformance', typescript).
 rule_implementation('entity-context-missing', typescript).
 rule_implementation('entity-context-acknowledged', typescript).
+rule_implementation('policy-ownership', typescript).
+rule_implementation('policy-markers', typescript).
 
 rule_predicate('must-priority-coverage', check_must_priority_coverage).
 rule_predicate('symbol-coverage', check_symbol_coverage).
@@ -263,3 +269,5 @@ rule_description('adr-proposed', 'Informational: an ADR that is still proposed a
 rule_description('predicate-schema-conformance', 'Predicate facts match a predicate_schema (project-local, or the built-in catalog in the default namespace) and use its declared argument constants').
 rule_description('entity-context-missing', 'A current requirement, scenario, test, ADR or observation/meta fact must carry body context: at least 12 words of prose (requirements: under a Context, Rationale, Why, Background, Source, Notes or Evidence heading) that do not restate the title or semantic_text; entities tagged review:context-missing are acknowledged legacy and exempt').
 rule_description('entity-context-acknowledged', 'Informational: how many current entities carry the review:context-missing tag, so the legacy context backlog stays visible; one summary finding per check').
+rule_description('policy-ownership', 'When a plugin activated for kibi.check-policy.v1 declares ownership rules, every production symbol in a rule\'s file set must implement a current requirement grounded (requires_predicate) in one of the rule\'s predicates; projects without an activated check policy are unaffected').
+rule_description('policy-markers', 'When a plugin activated for kibi.check-policy.v1 declares marker rules, every file implementing a requirement grounded in the rule\'s pattern predicate (with its declared sibling files) must contain each marker the KB declares for that pattern').