kibi-core 0.17.3 → 0.18.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kibi-core",
-  "version": "0.17.3",
+  "version": "0.18.1",
   "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,10 +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),
-    \+ hidden_provenance_stub(Tags, Type, Props),
+    (provenance_stub_props(Type, Props) -> Stub = true ; Stub = false),
     matches_source(SourceFilter, Props),
     relationships_missing(Id, MissingRelationships),
     relationships_present(Id, PresentRelationships),

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

@@ -19,6 +19,7 @@ known_rule('symbol-coverage').
 known_rule('symbol-traceability').
 known_rule('no-dangling-refs').
 known_rule('source-relationship-parity').
+known_rule('branch-store-not-compiled').
 known_rule('source-path-dangling').
 known_rule('no-cycles').
 known_rule('required-fields').
@@ -58,12 +59,15 @@ 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).
 rule_enforcement_class('symbol-traceability', canonical).
 rule_enforcement_class('no-dangling-refs', canonical).
 rule_enforcement_class('source-relationship-parity', canonical).
+rule_enforcement_class('branch-store-not-compiled', canonical).
 rule_enforcement_class('source-path-dangling', canonical).
 rule_enforcement_class('no-cycles', canonical).
 rule_enforcement_class('required-fields', canonical).
@@ -103,12 +107,15 @@ 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).
 rule_implementation('symbol-traceability', prolog).
 rule_implementation('no-dangling-refs', prolog).
 rule_implementation('source-relationship-parity', typescript).
+rule_implementation('branch-store-not-compiled', typescript).
 rule_implementation('source-path-dangling', typescript).
 rule_implementation('no-cycles', prolog).
 rule_implementation('required-fields', prolog).
@@ -148,6 +155,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).
@@ -224,6 +233,7 @@ rule_description('symbol-coverage', 'Production symbols need qualifying coverage
 rule_description('symbol-traceability', 'Production symbols must directly implement requirements for ownership; covered_by is coverage only and executable_for is test identity only').
 rule_description('no-dangling-refs', 'All relationship targets must exist in the KB').
 rule_description('source-relationship-parity', 'Authored Markdown and relationship-shard edges must exactly match the compiled KB').
+rule_description('branch-store-not-compiled', 'The current branch\'s KB store must be compiled from the authored .kb/ sources; a missing or empty store is reported once, naming kibi sync, instead of every store-backed rule reading an empty KB').
 rule_description('source-path-dangling', 'An authored entity\'s source field must name an existing workspace path (a #anchor suffix is ignored), an existing entity id, or an http(s) URL; a missing source is allowed').
 rule_description('no-cycles', 'No circular dependency chains in requirements').
 rule_description('required-fields', 'All entities must have required fields').
@@ -263,3 +273,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').

package/src/semantic_quality.pl

@@ -363,7 +363,10 @@ implication_witness_violation(Witness, violation(
 % was minted as several facts so requirements about it never meet: more than
 % one active subject fact for the same subject_key, and more than one active
 % property_value fact stating the same claim: the same subject_key,
-% property_key, operator, typed value and unit.  Facts that differ in operator
+% property_key, operator, polarity (absent = require), typed value and unit.
+% A `forbid` fact states the opposite of its `require` twin, so the pair is
+% never one claim.  Facts linked only by superseded or deprecated requirements
+% are history, not live duplicates.  Facts that differ in operator
 % (the two bounds of a range) or in value (two requirements bounding the same
 % property differently) are distinct claims, which domain-contradictions and
 % domain-implication compare.  Each group is reported once, on its first fact
@@ -390,7 +393,8 @@ duplicate_subject_fact_violations(Violations) :-
     findall(
         SubjectKey-FactId,
         (   fact_subject_key_of_kind(FactId, subject, SubjectKey),
-            active_fact(FactId)
+            active_fact(FactId),
+            identity_live_fact(FactId)
         ),
         Pairs0
     ),
@@ -423,15 +427,17 @@ duplicate_subject_fact_violations(Violations) :-
 %% duplicate_property_fact_violations(-Violations)
 duplicate_property_fact_violations(Violations) :-
     findall(
-        key(SubjectKey, PropertyKey, Operator, Value)-FactId,
+        key(SubjectKey, PropertyKey, Operator, Polarity, Value)-FactId,
         (   fact_subject_key_of_kind(FactId, property_value, SubjectKey),
             kb_entity(FactId, fact, Props),
             memberchk(property_key=RawProperty, Props),
             normalize_term_atom(RawProperty, PropertyKey),
             memberchk(operator=RawOperator, Props),
             normalize_term_atom(RawOperator, Operator),
+            property_value_polarity(Props, Polarity),
             property_value_signature(Props, Value),
-            active_fact(FactId)
+            active_fact(FactId),
+            identity_live_fact(FactId)
         ),
         Pairs0
     ),
@@ -444,20 +450,55 @@ duplicate_property_fact_violations(Violations) :-
             Description,
             "Link every requirement to one shared fact and remove the duplicates (kb_delete) once nothing links them",
             Source,
-            _{subjectKey: SubjectKey, propertyKey: PropertyKey, operator: Operator, facts: FactIds}
+            _{subjectKey: SubjectKey, propertyKey: PropertyKey, operator: Operator, polarity: Polarity, facts: FactIds}
         ),
-        (   member(key(SubjectKey, PropertyKey, Operator, _)-FactIds, Groups),
+        (   member(key(SubjectKey, PropertyKey, Operator, Polarity, _)-FactIds, Groups),
             FactIds = [FirstId, _|_],
             length(FactIds, Count),
             atomic_list_concat(FactIds, ', ', FactText),
             format(string(Description),
-                "~w active property_value facts state the same claim on ~w ~w (operator ~w, same value) (~w), so one claim is minted as several facts",
-                [Count, SubjectKey, PropertyKey, Operator, FactText]),
+                "~w active property_value facts state the same claim on ~w ~w (operator ~w, polarity ~w, same value) (~w), so one claim is minted as several facts",
+                [Count, SubjectKey, PropertyKey, Operator, Polarity, FactText]),
             entity_text(FirstId, fact, source, Source)
         ),
         Violations
     ).
 
+%% property_value_polarity(+Props, -Polarity)
+% The polarity of a property_value fact; an absent polarity means require.
+% `forbid` states the opposite claim of `require` on the same tuple, so the
+% two never count as one claim minted twice.
+% implements REQ-kibi-subject-vocabulary
+property_value_polarity(Props, Polarity) :-
+    (   memberchk(polarity=Raw, Props),
+        normalize_term_atom(Raw, Polarity0),
+        Polarity0 \== ''
+    ->  Polarity = Polarity0
+    ;   Polarity = require
+    ).
+
+%% identity_live_fact(+FactId)
+% A fact still carried by the current requirement set: no requirement links
+% it (an orphan duplicate stays visible), or at least one current requirement
+% links it. A fact linked only by superseded or deprecated requirements is
+% history kept for the append-only supersedes chain, not a live duplicate.
+% `closed` means done, not retired, so a closed requirement still counts.
+% implements REQ-kibi-subject-vocabulary
+identity_live_fact(FactId) :-
+    findall(
+        ReqId,
+        (   member(LinkType, [constrains, requires_property, requires_predicate, requires_rule]),
+            kb_relationship(LinkType, ReqId, FactId)
+        ),
+        Linkers
+    ),
+    (   Linkers == []
+    ->  true
+    ;   member(ReqId, Linkers),
+        kb:current_req(ReqId)
+    ->  true
+    ).
+
 %% property_value_signature(+Props, -Signature)
 % The typed value and unit of a property_value fact, as Field-Value pairs in a
 % fixed field order, so two facts compare equal only when they store the same