kibi-core 0.11.0 → 0.12.0

package/package.json

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

package/schema/entities.pl

@@ -37,6 +37,8 @@ entity_property(req, semantic_inventory_version, string).
 entity_property(req, semantic_source_field, string).
 entity_property(req, semantic_source_hash, string).
 entity_property(req, semantic_inventory, list_or_json).
+entity_property(req, proof_exempt, boolean).
+entity_property(req, proof_exempt_reason, string).
 
 % Typed fact fields - only valid for fact entities
 entity_property(fact, fact_kind, atom).
@@ -88,8 +90,9 @@ entity_property(symbol, sourceEndColumn, integer).
 % Typed test verification fields - only valid for test entities
 entity_property(test, verification_scope, atom).
 entity_property(test, verification_perspective, atom).
-entity_property(test, verification_contract, list_or_json).
-entity_property(test, verification_receipts, string).
+entity_property(test, proof_contract, list_or_json).
+entity_property(test, proof_bindings, string).
+entity_property(test, proof_receipts, string).
 
 % Required properties for all entity types
 required_property(Type, id) :- entity_type(Type).
@@ -113,10 +116,13 @@ optional_property(req, semantic_inventory_version).
 optional_property(req, semantic_source_field).
 optional_property(req, semantic_source_hash).
 optional_property(req, semantic_inventory).
+optional_property(req, proof_exempt).
+optional_property(req, proof_exempt_reason).
 optional_property(test, verification_scope).
 optional_property(test, verification_perspective).
-optional_property(test, verification_contract).
-optional_property(test, verification_receipts).
+optional_property(test, proof_contract).
+optional_property(test, proof_bindings).
+optional_property(test, proof_receipts).
 
 % Documentation helpers
 % list all entity types

package/schema/validation.pl

@@ -119,8 +119,9 @@ is_fact_only_field(claim_span_end).
 % is_test_only_field(+Key) - true if Key is a test-specific field
 is_test_only_field(verification_scope).
 is_test_only_field(verification_perspective).
-is_test_only_field(verification_contract).
-is_test_only_field(verification_receipts).
+is_test_only_field(proof_contract).
+is_test_only_field(proof_bindings).
+is_test_only_field(proof_receipts).
 
 % validate_fact_shape(+Kind, +Props)
 validate_fact_shape(subject, Props) :-

package/src/checks.pl

@@ -25,6 +25,7 @@
     check_rule_safety/1,
     check_rule_verifiability/1,
     check_semantic_completeness/1,
+    check_req_status_vocabulary/1,
     run_checks_json/0,              % Entry point for JSON output
     violation_id_text/2             % Extract text from entity ID term (exported for testing)
 ]).
@@ -35,6 +36,8 @@
 :- use_module('../schema/entities.pl', [entity_type/1, required_property/2]).
 :- use_module('../schema/relationships.pl', [relationship_type/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]).
 
 % Required fields for all entities
 required_fields([id, title, status, created_at, updated_at, source]).
@@ -66,6 +69,7 @@ check_all(ViolationsDict) :-
     check_rule_safety(RuleSafety),
     check_rule_verifiability(RuleVerifiability),
     check_semantic_completeness(SemanticCompleteness),
+    check_req_status_vocabulary(ReqStatusVocabulary),
     ViolationsDict = _{
         must_priority_coverage: MustPriority,
         symbol_coverage: SymbolCoverage,
@@ -82,7 +86,8 @@ check_all(ViolationsDict) :-
         logic_coverage: LogicCoverage,
         rule_safety: RuleSafety,
         rule_verifiability: RuleVerifiability,
-        semantic_completeness: SemanticCompleteness
+        semantic_completeness: SemanticCompleteness,
+        req_status_vocabulary: ReqStatusVocabulary
     }.
 
 %% check_must_priority_coverage(-Violations)
@@ -363,6 +368,39 @@ deprecated_adr_violation(violation(
     ;   Source = ""
     ).
 
+%% check_req_status_vocabulary(-Violations)
+% Rejects requirement statuses outside the canonical+legacy vocabulary.
+% Requirement documents carrying ADR vocabulary (e.g. `status: accepted`)
+% compile and pass schema validation, then silently fall out of
+% current_req/1 — the proof ladder reports them not_applicable with no
+% signal. This rule surfaces the vocabulary mismatch at check time instead.
+canonical_req_statuses([open, in_progress, closed]).
+legacy_req_statuses([active, approved]).
+
+check_req_status_vocabulary(Violations) :-
+    findall(
+        Violation,
+        req_status_vocabulary_violation(Violation),
+        Violations
+    ).
+
+req_status_vocabulary_violation(violation(
+    'req-status-vocabulary',
+    ReqId,
+    Description,
+    Suggestion,
+    Source
+)) :-
+    kb_entity(ReqId, req, Props),
+    memberchk(status=RawStatus, Props),
+    normalize_term_atom(RawStatus, StatusAtom),
+    canonical_req_statuses(Canonical),
+    legacy_req_statuses(Legacy),
+    \+ (memberchk(StatusAtom, Canonical) ; memberchk(StatusAtom, Legacy)),
+    format(string(Description), "Requirement status '~w' is not a current requirement status; it is silently excluded from the proof ladder", [StatusAtom]),
+    format(string(Suggestion), "Set status to one of open, in_progress, closed (legacy: active, approved). To park a current requirement out of E2E-proof scope, use proof_exempt: true with proof_exempt_reason instead of an ADR status", []),
+    violation_source(ReqId, req, Source).
+
 %% check_strict_fact_shape(-Violations)
 % Finds all strict facts (with fact_kind) that have malformed shape.
 % Only checks facts with fact_kind present; legacy facts without fact_kind are ignored.
@@ -1412,7 +1450,18 @@ check_selected_json(Rules, JsonString) :-
         JsonString
     ).
 
-check_selected(Rules, _{
+%% check_selected(+Rules, -ViolationsDict)
+% Run only the named aggregated checks. This is intentionally separate from
+% check_all/1 so focused diagnostics cannot evaluate unrelated rule queries.
+% Unknown rule names fail loudly: a typo must never masquerade as a clean,
+% violation-free run. Rules implemented on the TypeScript side (recorded in
+% rule_registry.pl with implementation typescript) are accepted here and
+% simply produce no Prolog-side violations.
+check_selected(Rules, ViolationsDict) :-
+    require_known_rules(Rules),
+    check_selected_dispatch(Rules, ViolationsDict).
+
+check_selected_dispatch(Rules, _{
     must_priority_coverage: MustPriority,
     symbol_coverage: SymbolCoverage,
     symbol_traceability: SymbolTraceability,
@@ -1428,7 +1477,8 @@ check_selected(Rules, _{
     logic_coverage: LogicCoverage,
     rule_safety: RuleSafety,
     rule_verifiability: RuleVerifiability,
-    semantic_completeness: SemanticCompleteness
+    semantic_completeness: SemanticCompleteness,
+    req_status_vocabulary: ReqStatusVocabulary
 }) :-
     selected_rule(Rules, 'must-priority-coverage', check_must_priority_coverage, MustPriority),
     selected_rule(Rules, 'symbol-coverage', check_symbol_coverage, SymbolCoverage),
@@ -1445,7 +1495,8 @@ check_selected(Rules, _{
     selected_rule(Rules, 'logic-coverage', check_logic_coverage, LogicCoverage),
     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, 'semantic-completeness', check_semantic_completeness, SemanticCompleteness),
+    selected_rule(Rules, 'req-status-vocabulary', check_req_status_vocabulary, ReqStatusVocabulary).
 
 selected_rule(Rules, Name, Goal, Violations) :-
     (   memberchk(Name, Rules)
@@ -1459,6 +1510,17 @@ selected_rule_with_options(Rules, Name, Goal, Violations) :-
     ;   Violations = []
     ).
 
+%% require_known_rules(+Rules)
+% Fail closed on names outside the generated registry so a typo or a
+% stale cross-version call surfaces as an error instead of an empty result.
+require_known_rules(Rules) :-
+    exclude(rule_registry:known_rule, Rules, Unknown),
+    (   Unknown == []
+    ->  true
+    ;   throw(error(domain_error(check_rule, Unknown),
+                context(check_selected, 'Unknown check rules requested')))
+    ).
+
 %% check_all_json_with_options(-JsonString, +RequireAdr)
 % Returns all violations as JSON string with options.
 % RequireAdr: if true, symbol-traceability also requires ADR constraints.
@@ -1489,6 +1551,7 @@ check_all_with_options(ViolationsDict, RequireAdr) :-
     check_rule_safety(RuleSafety),
     check_rule_verifiability(RuleVerifiability),
     check_semantic_completeness(SemanticCompleteness),
+    check_req_status_vocabulary(ReqStatusVocabulary),
     ViolationsDict = _{
         must_priority_coverage: MustPriority,
         symbol_coverage: SymbolCoverage,
@@ -1505,7 +1568,8 @@ check_all_with_options(ViolationsDict, RequireAdr) :-
         logic_coverage: LogicCoverage,
         rule_safety: RuleSafety,
         rule_verifiability: RuleVerifiability,
-        semantic_completeness: SemanticCompleteness
+        semantic_completeness: SemanticCompleteness,
+        req_status_vocabulary: ReqStatusVocabulary
     }.
 
 %% violations_dict_to_json(+ViolationsDict, -JsonDict)

package/src/discovery.pl

@@ -5,13 +5,19 @@
     find_gaps_json/8,
     coverage_report_json/7,
     coverage_report_json/10,
+    coverage_report_json/11,
+    coverage_report_json/12,
+    coverage_evidence_json/5,
     graph_expand_json/8
 ]).
 
 :- 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('requirement_proof.pl', [requirement_proof_context/1, requirement_proof_context/4, requirement_proof/4]).
+:- 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]).
 
@@ -32,13 +38,105 @@ coverage_report_json(By, Tags, IncludePassing, IncludeTransitive, Limit, Offset,
     coverage_report_json(By, Tags, IncludePassing, IncludeTransitive, Limit, Offset, unknown, '1970-01-01T00:00:00Z', 604800, JsonString).
 
 coverage_report_json(By, Tags, IncludePassing, IncludeTransitive, Limit, Offset, VerificationSnapshot, CheckedAt, MaxAgeSeconds, JsonString) :-
-    coverage_rows(By, Tags, IncludePassing, IncludeTransitive, VerificationSnapshot, CheckedAt, MaxAgeSeconds, Rows0, Summary),
+    coverage_report_json(By, Tags, IncludePassing, strict_snapshot, _{}, IncludeTransitive, Limit, Offset, VerificationSnapshot, CheckedAt, MaxAgeSeconds, JsonString).
+
+% 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
+% the full coverage row set, keeping the response small on large KBs.
+coverage_evidence_json(Tags, VerificationSnapshot, CheckedAt, MaxAgeSeconds, JsonString) :-
+    requirement_proof_context(VerificationSnapshot, CheckedAt, MaxAgeSeconds, ProofContext),
+    findall(Evidence,
+        (   kb_entity(Id, req, Props),
+            matches_tags(Tags, Props),
+            requirement_proof(Id, Props, ProofContext, Proof),
+            coverage_evidence_row(Id, Proof, Evidence)
+        ),
+        Evidences),
+    Response = _{rows: Evidences},
+    dict_json_string(Response, JsonString).
+
+coverage_evidence_row(Id, Proof, Evidence) :-
+    (   get_dict(proofStatus, Proof, ProofStatus)
+    ->  true
+    ;   ProofStatus = unknown
+    ),
+    (   get_dict(proofStages, Proof, Stages),
+        get_dict(passingE2e, Stages, PassingE2e),
+        get_dict(status, PassingE2e, PassingE2eStatus)
+    ->  (   get_dict(tests, PassingE2e, PassingE2eTests)
+        ->  true
+        ;   PassingE2eTests = []
+        )
+    ;   PassingE2eStatus = unknown,
+        PassingE2eTests = []
+    ),
+    (   get_dict(proofGaps, Proof, Gaps)
+    ->  include(coverage_evidence_receipt_gap, Gaps, ReceiptGapCodes)
+    ;   ReceiptGapCodes = []
+    ),
+    Evidence = _{
+        id: Id,
+        proofStatus: ProofStatus,
+        passingE2eStatus: PassingE2eStatus,
+        passingE2eTests: PassingE2eTests,
+        receiptGapCodes: ReceiptGapCodes
+    }.
+
+coverage_evidence_receipt_gap(Gap) :-
+    (   atom(Gap)
+    ->  Atom = Gap
+    ;   format(atom(Atom), "~w", [Gap])
+    ),
+    (   sub_atom(Atom, _, _, _, 'proof_receipt')
+    ;   sub_atom(Atom, _, _, _, 'proof_contract')
+    ;   sub_atom(Atom, _, _, _, 'proof_snapshot')
+    ).
+
+% Per-contract receipt binding (W2): BindingMode strict_snapshot | per_contract
+% with TestBindings mapping TestId -> current binding hash.
+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),
     paginate_rows(SortedRows, Offset, Limit, Rows),
     status_meta_dict(Meta),
     Response = _{summary: Summary, rows: Rows, meta: Meta},
     dict_json_string(Response, JsonString).
 
+% implements REQ-kibi-coverage-status-filter
+% Proof-status filtered report. The status filter selects requirement rows by
+% proofStatus (proven, missing, unresolved, not_applicable) and replaces the
+% default include-passing filtering, so callers can enumerate exactly one
+% slice — e.g. every not_applicable row together with its typed applicability
+% 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),
+    paginate_rows(SortedRows, Offset, Limit, Rows),
+    status_meta_dict(Meta),
+    Response = _{summary: Summary, rows: Rows, meta: Meta},
+    dict_json_string(Response, JsonString).
+
+status_filtered_coverage_rows(By, Tags, IncludePassing, [], IncludeTransitive, VerificationSnapshot, CheckedAt, MaxAgeSeconds, Rows, Summary) :-
+    !,
+    coverage_rows(By, Tags, IncludePassing, IncludeTransitive, VerificationSnapshot, CheckedAt, MaxAgeSeconds, Rows, Summary).
+status_filtered_coverage_rows(req, Tags, _IncludePassing, StatusFilter, IncludeTransitive, VerificationSnapshot, CheckedAt, MaxAgeSeconds, MatchedRows, Summary) :-
+    !,
+    coverage_rows(req, Tags, true, IncludeTransitive, VerificationSnapshot, CheckedAt, MaxAgeSeconds, Rows0, Summary),
+    include(req_row_proof_status_in(StatusFilter), Rows0, MatchedRows).
+status_filtered_coverage_rows(By, Tags, _IncludePassing, _StatusFilter, IncludeTransitive, VerificationSnapshot, CheckedAt, MaxAgeSeconds, Rows, Summary) :-
+    coverage_rows(By, Tags, true, IncludeTransitive, VerificationSnapshot, CheckedAt, MaxAgeSeconds, Rows, Summary).
+
+req_row_proof_status_in(StatusFilter, Row) :-
+    Status = Row.proofStatus,
+    memberchk(Status, StatusFilter).
+
 graph_expand_json(SeedIds, Relationships, Direction, Depth, EntityTypes, MaxNodes, MaxEdges, JsonString) :-
     sort(SeedIds, SeedSet),
     bfs_layers(SeedSet, SeedSet, [], Relationships, Direction, Depth, MaxNodes, MaxEdges, SeenNodes0, SeenEdges0, Truncated0),
@@ -100,9 +198,9 @@ relationship_count(Id, Relationship, Count) :-
         (kb_relationship(Relationship, Id, _); kb_relationship(Relationship, _, Id)),
         Count).
 
-coverage_rows(req, Tags, IncludePassing, IncludeTransitive, VerificationSnapshot, CheckedAt, MaxAgeSeconds, Rows, Summary) :-
+coverage_rows(req, Tags, IncludePassing, IncludeTransitive, VerificationSnapshot, CheckedAt, MaxAgeSeconds, BindingMode, TestBindings, Rows, Summary) :-
     !,
-    requirement_proof_context(VerificationSnapshot, CheckedAt, MaxAgeSeconds, ProofContext),
+    requirement_proof_context(VerificationSnapshot, CheckedAt, MaxAgeSeconds, BindingMode, TestBindings, ProofContext),
     findall(Row,
         requirement_coverage_row(Tags, IncludeTransitive, ProofContext, Row),
         AllRows),
@@ -140,6 +238,10 @@ coverage_rows(type, _Tags, _IncludePassing, _IncludeTransitive, _VerificationSna
     length(Rows, Total),
     Summary = _{total: Total}.
 
+coverage_rows(req, Tags, IncludePassing, IncludeTransitive, VerificationSnapshot, CheckedAt, MaxAgeSeconds, Rows, Summary) :-
+    !,
+    coverage_rows(req, Tags, IncludePassing, IncludeTransitive, VerificationSnapshot, CheckedAt, MaxAgeSeconds, strict_snapshot, _{}, Rows, Summary).
+
 requirement_coverage_row(Tags, IncludeTransitive, ProofContext, Row) :-
     kb_entity(Id, req, Props),
     matches_tags(Tags, Props),

package/src/kb.pl

@@ -71,6 +71,7 @@
 :- use_module(library(thread)).
 :- use_module(library(filesex)).
 :- use_module(library(readutil)).
+:- use_module(library(http/json)).
 :- use_module(library(aggregate), [aggregate_all/3]).
 :- use_module(library(lists), [sum_list/2]).
 :- use_module(library(ordsets)).
@@ -156,8 +157,14 @@ kb_attach_journaled(Directory) :-
     ;   make_directory_path(PersistencyDirectory)
     ),
     % rdf_persistency owns the database lock for the lifetime of the engine.
-    rdf_attach_db(PersistencyDirectory,
-                  [access(read_write), silent(true), concurrency(4)]),
+    % A failed attach throws a structured store_locked term carrying the
+    % ownership journal (if any) so callers can surface the holder or take
+    % over when the holder is provably dead.
+    catch(rdf_attach_db(PersistencyDirectory,
+                        [access(read_write), silent(true), concurrency(4)]),
+          error(permission_error(_, _, _), Original),
+          kb_throw_store_locked(PersistencyDirectory, Directory, Original)),
+    catch(kb_write_lock_owner(Directory), _, true),
     % Create RDF graph name from directory.  Do not unload a graph here:
     % rdf_attach_db has already restored it from its snapshot/journal.  A
     % staged migration can have been atomically moved after the graph was
@@ -229,6 +236,58 @@ kb_attach_legacy(Directory) :-
     kb_rebuild_indexes.
 
 
+%% Store lock ownership journal.
+% rdf_persistency holds the branch-store lock while an engine is attached, but
+% records nothing about the holder. The journal bridges that gap: kibi writes
+% who attached (pid, workspace, boot id, started at) next to the lock so a
+% later store_locked failure can surface the holder and self-heal when the
+% holder is provably dead (crash, kill, removed worktree).
+% implements REQ-core-journaled-engine-persistence
+
+kb_lock_owner_path(Directory, Path) :-
+    atom_concat(Directory, '/.kibi-lock-owner.json', Path).
+
+kb_write_lock_owner(Directory) :-
+    kb_lock_owner_path(Directory, Path),
+    current_prolog_flag(pid, Pid),
+    (   exists_file('/proc/sys/kernel/random/boot_id')
+    ->  catch((   read_file_to_string('/proc/sys/kernel/random/boot_id',
+                                 BootIdRaw, []),
+                  split_string(BootIdRaw, "\r\n", "\r\n", [BootId|_])),
+              _,
+              BootId = "")
+    ;   BootId = ""
+    ),
+    get_time(Now),
+    format_time(atom(StartedAt), '%FT%TZ', Now),
+    atom_concat(Path, '.tmp', TmpPath),
+    setup_call_cleanup(
+        open(TmpPath, write, Stream),
+        json_write_dict(Stream,
+                        json([pid:Pid,
+                              workspaceRoot:Directory,
+                              bootId:BootId,
+                              startedAt:StartedAt]),
+                        []),
+        (close(Stream), rename_file(TmpPath, Path))).
+
+kb_remove_lock_owner :-
+    (   kb_attached(Directory)
+    ->  kb_lock_owner_path(Directory, Path),
+        catch(delete_file(Path), _, true)
+    ;   true
+    ).
+
+kb_throw_store_locked(PersistencyDirectory, Directory, Original) :-
+    kb_lock_owner_path(Directory, Path),
+    (   exists_file(Path)
+    ->  catch(read_file_to_string(Path, OwnerJson, []), _, OwnerJson = "")
+    ;   OwnerJson = ""
+    ),
+    term_string(Original, OriginalText),
+    throw(error(permission_error(attach, kb_store, Directory),
+                kb_store_locked(OwnerJson, PersistencyDirectory, OriginalText))).
+
 %% kb_detach
 % Safely detach from KB without persisting pending changes.
 % Call kb_save/0 explicitly before kb_detach/0 when durability is required.
@@ -238,7 +297,8 @@ kb_detach :-
     ->  (
             (   kb_storage_mode(journaled)
             ->  catch(rdf_flush_journals([min_size(16384)]), _, true),
-                catch(rdf_detach_db, _, true)
+                catch(rdf_detach_db, _, true),
+                catch(kb_remove_lock_owner, _, true)
             ;   true
             ),
             % Unload RDF graph from memory to prevent duplication on reattach
@@ -1836,10 +1896,13 @@ integer_property_key(Key) :-
 literal_to_value(semantic_inventory, Literal, Value) :-
     !,
     structured_literal_value(Literal, Value).
-literal_to_value(verification_receipts, Literal, Value) :-
+literal_to_value(proof_receipts, Literal, Value) :-
+    !,
+    structured_literal_value(Literal, Value).
+literal_to_value(proof_contract, Literal, Value) :-
     !,
     structured_literal_value(Literal, Value).
-literal_to_value(verification_contract, Literal, Value) :-
+literal_to_value(proof_bindings, Literal, Value) :-
     !,
     structured_literal_value(Literal, Value).
 literal_to_value(_Key, Literal, Value) :-