kibi-cli 1.0.1 → 2.0.0

package/src/public/operations/result-envelope.ts

@@ -36,6 +36,20 @@ function nextActions(value: unknown): KibiResult["nextActions"] {
   });
 }
 
+export function failedEffectStatus(
+  effect: OperationEffect,
+  failure: Record<string, unknown>,
+): KibiResult["effects"][number] {
+  return {
+    kind: effect,
+    status: "failed",
+    detail: failure.detail,
+    ...(typeof failure.errorCode === "string"
+      ? { errorCode: failure.errorCode }
+      : {}),
+  };
+}
+
 function effectStatus(
   effect: OperationEffect,
   data: Record<string, unknown> | undefined,
@@ -45,16 +59,7 @@ function effectStatus(
     const failure = failures.find(
       (entry) => record(entry) && entry.kind === effect,
     );
-    if (record(failure)) {
-      return {
-        kind: effect,
-        status: "failed",
-        detail: failure.detail,
-        ...(typeof failure.errorCode === "string"
-          ? { errorCode: failure.errorCode }
-          : {}),
-      };
-    }
+    if (record(failure)) return failedEffectStatus(effect, failure);
   }
   return { kind: effect, status: "completed" };
 }

package/src/public/operations/runtime-types.ts

@@ -1,3 +1,4 @@
+import type { PrologErrorRecord } from "../../prolog/error-terms.js";
 import type { BranchAttachment } from "../../utils/branch-resolver.js";
 import type { OperationEffect } from "./types.js";
 
@@ -7,6 +8,8 @@ export type PrologQueryResult = {
   readonly success: boolean;
   readonly bindings: Readonly<Record<string, string>>;
   readonly error?: string;
+  /** Structured error term when the failure crossed a kb.pl throw site. */
+  readonly errorRecord?: PrologErrorRecord;
 };
 
 export type PrologEntityQueryInput = Readonly<{
@@ -187,6 +190,8 @@ export type OperationContext = {
   readonly sourceFirst?: boolean;
   /** Internal apply-plan capability: source bytes were already approved/published. */
   readonly sourcePlanApplication?: boolean;
+  /** Internal apply-plan capability: caller holds the cooperative source lock. */
+  readonly sourceMutationLockHeld?: boolean;
   readonly git?: GitPort;
   readonly net?: NetworkPort;
   readonly branchAttachment?: BranchAttachment;

package/src/public/operations/specs/check-rules.generated.ts

@@ -0,0 +1,37 @@
+/*
+ * Kibi — repo-local, per-branch, queryable long-term memory for software projects
+ * Copyright (C) 2026 Piotr Franczyk
+ *
+ * This file is generated by scripts/generate-rule-registry.mjs from
+ * packages/core/schema/rule-registry.json. Do not edit it directly; edit the
+ * JSON source and regenerate.
+ */
+
+// implements REQ-006
+/** Every selectable kb_check rule name, registry order. */
+export const SELECTABLE_RULE_NAMES: readonly string[] = [
+  "must-priority-coverage",
+  "symbol-coverage",
+  "symbol-traceability",
+  "no-dangling-refs",
+  "source-relationship-parity",
+  "no-cycles",
+  "required-fields",
+  "deprecated-adr-no-successor",
+  "domain-contradictions",
+  "logic-coverage",
+  "rule-safety",
+  "rule-verifiability",
+  "query-plan-safety",
+  "req-status-vocabulary",
+  "strict-fact-shape",
+  "strict-req-fact-pairing",
+  "predicate-verifiability",
+  "strict-readiness",
+  "semantic-completeness",
+];
+
+// implements REQ-006
+/** Comma-separated "Allowed:" fragment for the kb_check rules description. */
+export const SELECTABLE_RULES_ALLOWED =
+  "must-priority-coverage, symbol-coverage, symbol-traceability, no-dangling-refs, source-relationship-parity, no-cycles, required-fields, deprecated-adr-no-successor, domain-contradictions, logic-coverage, rule-safety, rule-verifiability, query-plan-safety, req-status-vocabulary, strict-fact-shape, strict-req-fact-pairing, predicate-verifiability, strict-readiness, semantic-completeness";

package/src/public/operations/specs/check.ts

@@ -1,5 +1,9 @@
 import { executeCheck } from "../check-executor.js";
 import type { OperationSpec } from "../types.js";
+import {
+  SELECTABLE_RULES_ALLOWED,
+  SELECTABLE_RULE_NAMES,
+} from "./check-rules.generated.js";
 
 export const checkSpec = {
   name: "kb_check",
@@ -13,28 +17,9 @@ export const checkSpec = {
         type: "array",
         items: {
           type: "string",
-          enum: [
-            "must-priority-coverage",
-            "symbol-coverage",
-            "symbol-traceability",
-            "no-dangling-refs",
-            "source-relationship-parity",
-            "no-cycles",
-            "required-fields",
-            "deprecated-adr-no-successor",
-            "domain-contradictions",
-            "strict-fact-shape",
-            "strict-req-fact-pairing",
-            "predicate-verifiability",
-            "logic-coverage",
-            "rule-safety",
-            "rule-verifiability",
-            "semantic-completeness",
-            "query-plan-safety",
-          ],
+          enum: [...SELECTABLE_RULE_NAMES],
         },
-        description:
-          "Optional rule subset. Allowed: must-priority-coverage, symbol-coverage, symbol-traceability, no-dangling-refs, source-relationship-parity, no-cycles, required-fields, deprecated-adr-no-successor, domain-contradictions, strict-fact-shape, strict-req-fact-pairing, predicate-verifiability, logic-coverage, rule-safety, rule-verifiability, semantic-completeness, query-plan-safety. If omitted, server runs canonical and advisory rules plus the full-KB qualityDiagnostics audit scan, including usage telemetry acceptance when evidence exists; migration rules run only when explicitly selected. Advisory and migration findings are non-blocking qualityDiagnostics. If supplied, server preserves scoped validation and skips the full-KB advisory scan.",
+        description: `Optional rule subset. Allowed: ${SELECTABLE_RULES_ALLOWED}. If omitted, server runs canonical and advisory rules plus the full-KB qualityDiagnostics audit scan, including usage telemetry acceptance when evidence exists; migration rules run only when explicitly selected. Advisory and migration findings are non-blocking qualityDiagnostics. If supplied, server preserves scoped validation and skips the full-KB advisory scan.`,
       },
       sourceFiles: {
         type: "array",
@@ -68,6 +53,12 @@ export const checkSpec = {
         description:
           "Optional workspace root for impact diagnostics. Defaults to the MCP server workspace.",
       },
+      async: {
+        type: "boolean",
+        default: false,
+        description:
+          "When true, start the check as a background job and return a kibi.job.v1 receipt immediately instead of holding the request until the tool timeout. Poll kb_job_status with the returned jobId. Use for full checks on large KBs that exceed the configured tool timeout.",
+      },
     },
   },
   requiresProlog: true,

package/src/public/operations/specs/mutation-schemas.ts

@@ -1,7 +1,11 @@
 import {
-  VERIFICATION_CONTRACT_SCHEMA,
-  VERIFICATION_RECEIPT_SCHEMA,
-} from "../../verification-receipt.js";
+  PROOF_BINDINGS_SCHEMA,
+  PROOF_CONTRACT_SCHEMA,
+} from "../../proof-protocol.js";
+import {
+  MAX_PROOF_RECEIPTS,
+  PROOF_RECEIPT_SCHEMA,
+} from "../../proof-receipt.js";
 
 export const ENTITY_TYPES = [
   "req",
@@ -152,13 +156,22 @@ export const ENTITY_PROPERTIES_SCHEMA = {
       description:
         "Optional typed verification perspective for test entities. Example: 'consumer'.",
     },
-    verification_contract: VERIFICATION_CONTRACT_SCHEMA,
-    verification_receipts: {
+    proof_contract: {
+      ...PROOF_CONTRACT_SCHEMA,
+      description:
+        "Semantic proof contract binding this test to explicit proof obligations executed by one configured integration.",
+    },
+    proof_bindings: {
+      ...PROOF_BINDINGS_SCHEMA,
+      description:
+        "Optional native-runner bindings (native ids, aliases, source coordinates) for proof obligations. Bindings are provenance metadata and never replace the semantic contract.",
+    },
+    proof_receipts: {
       type: "array",
-      maxItems: 50,
-      items: VERIFICATION_RECEIPT_SCHEMA,
+      maxItems: MAX_PROOF_RECEIPTS,
+      items: PROOF_RECEIPT_SCHEMA,
       description:
-        "Append-only test execution evidence. Proof accepts only the newest valid passed receipt bound to the current code snapshot and within the seven-day freshness window.",
+        "Append-only proof evidence. Proof accepts only the newest valid passed receipt bound to the current code snapshot, current contract hash, and effective execution fingerprint within the seven-day freshness window. Ingest rotates the oldest entries at the cap.",
     },
     fact_kind: {
       type: "string",
@@ -323,7 +336,7 @@ export const ENTITY_PROPERTIES_SCHEMA = {
   allOf: [
     CLAIM_PROVENANCE_CONDITIONAL,
     {
-      if: { required: ["verification_receipts"] },
+      if: { required: ["proof_receipts"] },
       // biome-ignore lint/suspicious/noThenProperty: JSON Schema conditional keyword.
       then: { required: ["verification_scope"] },
     },

package/src/public/operations/specs/planning.ts

@@ -143,6 +143,13 @@ export const compileIntentSpec = {
             id: { type: "string" },
             title: { type: "string", minLength: 1 },
             body: { type: "string", minLength: 1 },
+            scenarioIds: {
+              type: "array",
+              items: { type: "string", minLength: 1 },
+              maxItems: 20,
+              description:
+                "Stable scenario draft IDs verified by this test. Required when multiple scenario drafts are supplied.",
+            },
             verificationScope: {
               type: "string",
               enum: ["unit", "integration", "end_to_end"],

package/src/public/operations/specs/proof.ts

@@ -0,0 +1,43 @@
+import {
+  type IngestProofArgs,
+  type IngestProofResult,
+  executeIngestProof,
+} from "../../../operations/proof/ingest-proof.js";
+import { PROOF_RUN_ARTIFACT_SCHEMA } from "../../proof-protocol.js";
+import type { OperationSpec } from "../types.js";
+
+export type {
+  IngestProofArgs,
+  IngestProofResult,
+} from "../../../operations/proof/ingest-proof.js";
+export { executeIngestProof } from "../../../operations/proof/ingest-proof.js";
+
+// implements REQ-kibi-proof-evidence-protocol
+export const ingestProofSpec = {
+  name: "kb_ingest_proof",
+  cliName: "ingest-proof",
+  description:
+    "Ingest a producer-emitted kibi.proof-run.v1 artifact and evaluate it against each selected test's kibi.proof-contract.v1 proof obligations. Revalidates the live workspace snapshot, integration command binding, run-level outcome, attempt history, success policy, and append-only proof-receipt history before deriving and appending idempotent kibi.proof-receipt.v1 receipts. Producers report what happened; Kibi evaluates proof. Prefer `kibi prove` so the configured producer runs automatically; direct ingestion is an integration path for custom producers and agents.",
+  businessInputSchema: {
+    type: "object",
+    required: ["snapshot", "artifact"],
+    properties: {
+      snapshot: {
+        type: "string",
+        pattern: "^[a-f0-9]{64}$",
+        description: "Workspace snapshot captured immediately before the run.",
+      },
+      artifact: PROOF_RUN_ARTIFACT_SCHEMA,
+      testIds: {
+        type: "array",
+        minItems: 1,
+        items: { type: "string", minLength: 1 },
+        description:
+          "Existing test entities with proof_contract.v1. Omit to evaluate every test contracted to the artifact's integration.",
+      },
+    },
+  },
+  requiresProlog: true,
+  effects: ["kb-read", "kb-write", "workspace-read"],
+  execute: executeIngestProof,
+} as const satisfies OperationSpec<IngestProofArgs, IngestProofResult>;

package/src/public/operations/specs/reporting.ts

@@ -1,4 +1,7 @@
-import { VERIFICATION_RECEIPT_MAX_AGE_SECONDS } from "../../verification-receipt.js";
+import { join } from "node:path";
+
+import { resolveBoundSymbolScope } from "../../../extractors/manifest.js";
+import { PROOF_RECEIPT_MAX_AGE_SECONDS } from "../../proof-receipt.js";
 import { executeStatus } from "../discovery-executors.js";
 import {
   type LegacyMigrationPlan,
@@ -17,7 +20,10 @@ import {
 } from "../prolog-json.js";
 import { type RepairPlan, buildRepairPlan } from "../repair-plan.js";
 import type { OperationContext } from "../runtime-types.js";
-import { buildSymbolRepairPlan } from "../symbol-repair-plan.js";
+import {
+  addCoordinateRepairEvidence,
+  buildSymbolRepairPlan,
+} from "../symbol-repair-plan.js";
 import type { OperationResult, OperationSpec } from "../types.js";
 import { readWorkspaceSnapshot } from "../workspace-snapshot.js";
 
@@ -53,6 +59,8 @@ export type CoverageInput = {
   readonly by?: "req" | "symbol" | "type";
   readonly tags?: readonly string[];
   readonly includePassing?: boolean;
+  /** Requirement proof-status filter (req mode). Implies include-passing. */
+  readonly statuses?: readonly string[];
   readonly includeTransitive?: boolean;
   readonly limit?: number;
   readonly offset?: number;
@@ -105,6 +113,22 @@ function validateEntityType(type?: string): void {
   }
 }
 
+const COVERAGE_PROOF_STATUSES: ReadonlySet<string> = new Set([
+  "proven",
+  "missing",
+  "unresolved",
+  "not_applicable",
+]);
+
+function validateCoverageStatus(status: string): string {
+  if (!COVERAGE_PROOF_STATUSES.has(status)) {
+    throw new Error(
+      `Invalid coverage status '${status}'. Valid statuses: ${[...COVERAGE_PROOF_STATUSES].join(", ")}.`,
+    );
+  }
+  return status;
+}
+
 export async function executeFindGaps(
   input: FindGapsInput,
   context: OperationContext,
@@ -161,6 +185,79 @@ export const findGapsSpec = {
   execute: executeFindGaps,
 } as const satisfies OperationSpec<FindGapsInput, FindGapsPayload>;
 
+/**
+ * Per-contract receipt binding (W2): compute the current binding hash for
+ * every receipt-bearing test (contract + receipt-stripped authored document
+ * + bound-symbol code scope) and hand the Prolog coverage stage a
+ * TestId -> BindingHash dict. This is the default binding mode since slice 3;
+ * KIBI_PROOF_BINDING_MODE=strict-snapshot opts out (receipts then match only
+ * against the whole-workspace snapshot they were proven on).
+ */
+// implements REQ-kibi-proof-evidence-protocol
+export function currentProofBindingMode(): "per_contract" | "strict_snapshot" {
+  return process.env.KIBI_PROOF_BINDING_MODE?.trim() === "strict-snapshot"
+    ? "strict_snapshot"
+    : "per_contract";
+}
+
+async function perContractTestBindings(
+  context: OperationContext,
+): Promise<string | null> {
+  if (currentProofBindingMode() !== "per_contract") return null;
+  const { loadEntities } = await import("../discovery-entities.js");
+  const { receiptBindingHash } = await import("../../proof-fingerprint.js");
+  const { removeFrontmatterBlock } = await import(
+    "../../../operations/proof/receipt-document.js"
+  );
+  let tests: Record<string, unknown>[];
+  try {
+    tests = await loadEntities(context.prolog as never, { type: "test" });
+  } catch {
+    return null;
+  }
+  const entries: string[] = [];
+  const manifestPath = join(context.workspaceRoot, ".kb", "symbols.yaml");
+  for (const test of tests) {
+    const testId = typeof test.id === "string" ? test.id : "";
+    const contract =
+      test.proof_contract !== undefined &&
+      test.proof_contract !== null &&
+      typeof test.proof_contract === "object"
+        ? (test.proof_contract as Record<string, unknown>)
+        : undefined;
+    const source = typeof test.source === "string" ? test.source : "";
+    if (testId === "" || contract === undefined || source === "") continue;
+    if (!/\.(md|mdx)$/i.test(source)) continue;
+    if (!context.fs) continue;
+    try {
+      const absolute = join(context.workspaceRoot, source);
+      const authored = await context.fs.readFile(absolute);
+      const stripped = removeFrontmatterBlock(authored, "proof_receipts");
+      const rawBindings: ReadonlyArray<{ symbol_id?: unknown }> = Array.isArray(
+        test.proof_bindings,
+      )
+        ? (test.proof_bindings as ReadonlyArray<{ symbol_id?: unknown }>)
+        : [];
+      const boundIds = rawBindings
+        .map((binding) =>
+          typeof binding.symbol_id === "string" ? binding.symbol_id : "",
+        )
+        .filter((id) => id !== "");
+      const codeScope = resolveBoundSymbolScope(manifestPath, boundIds);
+      const binding = receiptBindingHash(
+        contract as never,
+        stripped ?? authored,
+        codeScope,
+      );
+      entries.push(`${toPrologAtom(testId)}: ${toPrologAtom(binding)}`);
+    } catch {
+      // Unreadable documents keep strict semantics for that test.
+    }
+  }
+  if (entries.length === 0) return null;
+  return `_{${entries.join(", ")}}`;
+}
+
 export async function executeCoverage(
   input: CoverageInput,
   context: OperationContext,
@@ -171,13 +268,34 @@ export async function executeCoverage(
       ? snapshotEvidence.snapshot.hash
       : "unknown";
     const checkedAt = context.clock().toISOString();
+    const statuses = (input.statuses ?? []).map((status) =>
+      validateCoverageStatus(status),
+    );
+    const bindingsDict =
+      statuses.length === 0 && (input.by ?? "req") === "req"
+        ? await perContractTestBindings(context)
+        : null;
+    const goal =
+      bindingsDict !== null
+        ? `discovery:coverage_report_json('${input.by ?? "req"}', ${toPrologList(input.tags)}, ${input.includePassing ?? false}, per_contract, ${bindingsDict}, ${input.includeTransitive ?? true}, ${input.limit ?? 100}, ${input.offset ?? 0}, ${toPrologAtom(codeSnapshot)}, ${toPrologAtom(checkedAt)}, ${PROOF_RECEIPT_MAX_AGE_SECONDS}, JsonString)`
+        : statuses.length > 0
+          ? `discovery:coverage_report_json('${input.by ?? "req"}', ${toPrologList(input.tags)}, ${input.includePassing ?? false}, ${toPrologList(statuses)}, ${input.includeTransitive ?? true}, ${input.limit ?? 100}, ${input.offset ?? 0}, ${toPrologAtom(codeSnapshot)}, ${toPrologAtom(checkedAt)}, ${PROOF_RECEIPT_MAX_AGE_SECONDS}, JsonString)`
+          : `discovery:coverage_report_json('${input.by ?? "req"}', ${toPrologList(input.tags)}, ${input.includePassing ?? false}, ${input.includeTransitive ?? true}, ${input.limit ?? 100}, ${input.offset ?? 0}, ${toPrologAtom(codeSnapshot)}, ${toPrologAtom(checkedAt)}, ${PROOF_RECEIPT_MAX_AGE_SECONDS}, JsonString)`;
     const payload = await runOperationJsonQuery<CoveragePayload>(
       requireProlog(context),
       "discovery.pl",
-      `discovery:coverage_report_json('${input.by ?? "req"}', ${toPrologList(input.tags)}, ${input.includePassing ?? false}, ${input.includeTransitive ?? true}, ${input.limit ?? 100}, ${input.offset ?? 0}, ${toPrologAtom(codeSnapshot)}, ${toPrologAtom(checkedAt)}, ${VERIFICATION_RECEIPT_MAX_AGE_SECONDS}, JsonString)`,
+      goal,
       "Coverage execution",
     );
-    const repairPlan = buildRepairPlan(payload, input, codeSnapshot);
+    const rows =
+      (input.by ?? "req") === "req"
+        ? await addCoordinateRepairEvidence(payload.rows, context)
+        : payload.rows;
+    const repairPlan = buildRepairPlan(
+      { ...payload, rows },
+      input,
+      codeSnapshot,
+    );
     const symbolRepairPlan =
       input.by === "symbol"
         ? await buildSymbolRepairPlan(payload.rows, context)
@@ -212,7 +330,7 @@ export async function executeCoverage(
           : {}),
         workspaceSnapshot: codeSnapshot,
       },
-      evaluatedDomains: ["semantic", "verification", "symbol"],
+      evaluatedDomains: ["semantic", "proof", "symbol"],
       incompleteDomains:
         payload.meta?.scopeComplete === false ? ["coverage"] : [],
       actions: buildActionsFromCoverage({
@@ -231,23 +349,23 @@ export async function executeCoverage(
       : coveragePlan;
     const enrichedPayload = {
       ...payload,
+      rows,
       ...(repairPlan !== undefined ? { repairPlan } : {}),
       ...(legacyMigrationPlan !== undefined ? { legacyMigrationPlan } : {}),
       ...(symbolRepairPlan !== undefined ? { symbolRepairPlan } : {}),
       migrationPlan,
       meta: {
         ...(payload.meta ?? {}),
-        verificationReceiptMaxAgeSeconds: VERIFICATION_RECEIPT_MAX_AGE_SECONDS,
-        verificationSnapshot: codeSnapshot,
-        verificationSnapshotAvailable: snapshotEvidence.available,
+        proofReceiptMaxAgeSeconds: PROOF_RECEIPT_MAX_AGE_SECONDS,
+        proofSnapshot: codeSnapshot,
+        proofSnapshotAvailable: snapshotEvidence.available,
         ...(snapshotEvidence.available
           ? {
-              verificationSnapshotDirty: snapshotEvidence.snapshot.dirty,
-              verificationSnapshotFileCount:
-                snapshotEvidence.snapshot.fileCount,
-              verificationSnapshotVersion: snapshotEvidence.snapshot.version,
+              proofSnapshotDirty: snapshotEvidence.snapshot.dirty,
+              proofSnapshotFileCount: snapshotEvidence.snapshot.fileCount,
+              proofSnapshotVersion: snapshotEvidence.snapshot.version,
             }
-          : { verificationSnapshotError: snapshotEvidence.error }),
+          : { proofSnapshotError: snapshotEvidence.error }),
       },
     };
     const fullyCovered = Number(enrichedPayload.summary?.fullyCovered ?? 0);
@@ -279,6 +397,15 @@ export const coverageSpec = {
       by: { type: "string", enum: ["req", "symbol", "type"], default: "req" },
       tags: { type: "array", items: { type: "string" } },
       includePassing: { type: "boolean", default: false },
+      statuses: {
+        type: "array",
+        items: {
+          type: "string",
+          enum: ["proven", "missing", "unresolved", "not_applicable"],
+        },
+        description:
+          "Requirement proof-status filter (req mode): include only rows whose proofStatus is listed. Selecting statuses implies include-passing; not_applicable rows carry their typed applicability reason in proofStages.applicability.reason. The summary always reflects the whole KB.",
+      },
       includeTransitive: { type: "boolean", default: true },
       limit: { type: "integer", default: 100 },
       offset: { type: "integer", default: 0 },