kibi-cli 1.0.1 → 2.1.0

package/src/public/operations/catalog.ts

@@ -16,6 +16,7 @@ import {
   validateUpsertSpec,
 } from "./specs/mutation.js";
 import { applyPlanSpec, compileIntentSpec } from "./specs/planning.js";
+import { ingestProofSpec } from "./specs/proof.js";
 import { coverageSpec, findGapsSpec, graphSpec } from "./specs/reporting.js";
 import { semanticAdvisorSpec } from "./specs/semantic.js";
 import {
@@ -24,7 +25,6 @@ import {
   skillsReadSpec,
 } from "./specs/skills.js";
 import { sparqlRemoteSpec } from "./specs/sparql.js";
-import { ingestVerificationSpec } from "./specs/verification.js";
 import type {
   OperationName,
   OperationSpec,
@@ -52,7 +52,7 @@ export const OPERATION_CATALOG = [
   sparqlRemoteSpec,
   compileIntentSpec,
   applyPlanSpec,
-  ingestVerificationSpec,
+  ingestProofSpec,
 ] as const satisfies readonly OperationSpec[];
 
 function envelopeSchema(
@@ -183,14 +183,20 @@ const SPECS_BY_NAME: ReadonlyMap<OperationName, ResolvedOperationSpec> =
   );
 
 // implements REQ-kibi-operation-interface-parity
-export function getSpec(name: OperationName): ResolvedOperationSpec {
-  const spec = SPECS_BY_NAME.get(name);
+export function requireKnownSpec(
+  spec: ResolvedOperationSpec | undefined,
+  name: OperationName,
+): ResolvedOperationSpec {
   if (!spec) {
     throw new RangeError(`Unknown Kibi operation: ${name}`);
   }
   return spec;
 }
 
+export function getSpec(name: OperationName): ResolvedOperationSpec {
+  return requireKnownSpec(SPECS_BY_NAME.get(name), name);
+}
+
 // implements REQ-kibi-operation-interface-parity
 export function listSpecs(): readonly ResolvedOperationSpec[] {
   return OPERATION_CATALOG.map(withContractDefaults);

package/src/public/operations/check-executor.ts

@@ -127,7 +127,7 @@ export async function executeCheck(
     const workspaceRoot = args.workspaceRoot ?? context.workspaceRoot;
     const prolog = requireProlog(context);
     const snapshotEvidence = await readWorkspaceSnapshot(context);
-    const verificationSnapshot = snapshotEvidence.available
+    const proofSnapshot = snapshotEvidence.available
       ? snapshotEvidence.snapshot.hash
       : undefined;
     const checkedAt = context.clock().toISOString();
@@ -135,7 +135,7 @@ export async function executeCheck(
     // version. `args.rules` is an invocation-time diagnostic selector only.
     const rulesAllowlist = resolveCheckRules(args);
     const hasExplicitRules = args.rules !== undefined;
-    const impactResult = analyzeKbCheckImpact(workspaceRoot, args);
+    const impactResult = await analyzeKbCheckImpact(workspaceRoot, args);
     const impactQualityDiagnostics = qualityDiagnosticsFromImpact(impactResult);
     const maxDiagnosticsOption =
       args.maxDiagnostics !== undefined
@@ -152,9 +152,7 @@ export async function executeCheck(
             : await collectFullKbQualityDiagnostics({
                 prolog,
                 workspaceRoot,
-                ...(verificationSnapshot !== undefined
-                  ? { verificationSnapshot }
-                  : {}),
+                ...(proofSnapshot !== undefined ? { proofSnapshot } : {}),
                 checkedAt,
                 now: context.clock(),
                 ...maxDiagnosticsOption,
@@ -229,9 +227,7 @@ export async function executeCheck(
             prolog,
             hardViolationEntityIds: new Set(violations.map((v) => v.entityId)),
             workspaceRoot,
-            ...(verificationSnapshot !== undefined
-              ? { verificationSnapshot }
-              : {}),
+            ...(proofSnapshot !== undefined ? { proofSnapshot } : {}),
             checkedAt,
             now: context.clock(),
             ...maxDiagnosticsOption,

package/src/public/operations/check-helpers.ts

@@ -144,10 +144,10 @@ export function hasImpactOptions(args: CheckInput): boolean {
 }
 
 // implements REQ-mcp-tool-check
-export function analyzeKbCheckImpact(
+export async function analyzeKbCheckImpact(
   workspaceRoot: string,
   args: CheckInput,
-): ChangedFileImpactResult | undefined {
+): Promise<ChangedFileImpactResult | undefined> {
   if (!hasImpactOptions(args)) {
     return undefined;
   }

package/src/public/operations/contracts.ts

@@ -33,6 +33,25 @@ function objectData(
   };
 }
 
+/**
+ * kibi.job.v1 receipt returned by async-mode operations (kb_check with
+ * `async: true`) instead of the synchronous payload. Agents poll
+ * kb_job_status with the jobId. Declared as a union member of the operation
+ * data contract so hosts validating tool output against the declared schema
+ * accept the receipt without weakening the synchronous payload contract.
+ */
+const jobReceiptData: OperationJsonSchema = objectData(
+  {
+    kibiProtocol: { const: 1 },
+    jobVersion: { const: "kibi.job.v1" },
+    jobId: { type: "string" },
+    tool: { type: "string" },
+    status: { type: "string" },
+    pollWith: { const: "kb_job_status" },
+  },
+  ["kibiProtocol", "jobVersion", "jobId", "tool", "status", "pollWith"],
+);
+
 const stringValue: OperationJsonSchema = { type: "string" };
 const integerValue: OperationJsonSchema = { type: "integer" };
 const numberValue: OperationJsonSchema = { type: "number" };
@@ -45,7 +64,9 @@ const stringArray: OperationJsonSchema = {
 /** Preserve JSON Schema's nullable scalar/object representation in every
  * generated consumer contract.  Using a `type` union keeps the catalog
  * readable and lets the MCP bridge round-trip the same wire schema. */
-function nullable(schema: OperationJsonSchema): OperationJsonSchema {
+export function nullableJsonSchema(
+  schema: OperationJsonSchema,
+): OperationJsonSchema {
   const type = schema.type;
   if (typeof type === "string") {
     return { ...schema, type: [type, "null"] };
@@ -86,19 +107,23 @@ export const OPERATION_DATA_SCHEMAS: Readonly<
     syncState: stringValue,
     kbPath: stringValue,
     lastSyncSource: stringValue,
-    verificationSnapshot: stringValue,
-    verificationSnapshotAvailable: booleanValue,
-    verificationSnapshotDirty: booleanValue,
-    verificationSnapshotFileCount: integerValue,
-    verificationSnapshotVersion: stringValue,
-    verificationSnapshotError: stringValue,
+    attachedPath: stringValue,
+    attachedGeneration: stringValue,
+    attachedDev: integerValue,
+    attachedIno: integerValue,
+    proofSnapshot: stringValue,
+    proofSnapshotAvailable: booleanValue,
+    proofSnapshotDirty: booleanValue,
+    proofSnapshotFileCount: integerValue,
+    proofSnapshotVersion: stringValue,
+    proofSnapshotError: stringValue,
     staleReasons: recordArray,
     staleReasonCount: integerValue,
     staleReasonsTruncated: booleanValue,
     branchAttachment: recordValue,
-    verificationSnapshotChanges: recordArray,
-    verificationSnapshotChangeCount: integerValue,
-    verificationSnapshotChangesTruncated: booleanValue,
+    proofSnapshotChanges: recordArray,
+    proofSnapshotChangeCount: integerValue,
+    proofSnapshotChangesTruncated: booleanValue,
     branchStore: recordValue,
     engineStatus: recordValue,
     schemaStatus: recordValue,
@@ -129,6 +154,7 @@ export const OPERATION_DATA_SCHEMAS: Readonly<
   kb_semantic_advisor: objectData({
     receipt: recordValue,
     warnings: stringArray,
+    capabilityPlugins: recordValue,
   }),
   kb_model_requirement: objectData({
     statement: stringValue,
@@ -204,8 +230,8 @@ export const OPERATION_DATA_SCHEMAS: Readonly<
     valid: booleanValue,
     errors: valueArray,
     warnings: valueArray,
-    semanticAdvisor: nullable(recordValue),
-    normalizedPreview: nullable(recordValue),
+    semanticAdvisor: nullableJsonSchema(recordValue),
+    normalizedPreview: nullableJsonSchema(recordValue),
   }),
   kb_upsert: objectData({
     created: integerValue,
@@ -234,18 +260,25 @@ export const OPERATION_DATA_SCHEMAS: Readonly<
     effectFailures: recordArray,
     nextActions: recordArray,
   }),
-  kb_check: objectData({
-    violations: valueArray,
-    count: integerValue,
-    diagnostics: recordArray,
-    qualityDiagnostics: recordArray,
-    impactDiagnostics: recordArray,
-    sourceFiles: stringArray,
-    extractedSymbols: recordArray,
-    linkedEntities: recordArray,
-    nextActions: valueArray,
-    migrationPlan: recordValue,
-  }),
+  kb_check: {
+    description:
+      "Synchronous check payload, or a kibi.job.v1 receipt when async:true detached the check into a background job (poll kb_job_status with the jobId).",
+    anyOf: [
+      objectData({
+        violations: valueArray,
+        count: integerValue,
+        diagnostics: recordArray,
+        qualityDiagnostics: recordArray,
+        impactDiagnostics: recordArray,
+        sourceFiles: stringArray,
+        extractedSymbols: recordArray,
+        linkedEntities: recordArray,
+        nextActions: valueArray,
+        migrationPlan: recordValue,
+      }),
+      jobReceiptData,
+    ],
+  },
   kb_compile_intent: objectData({
     version: stringValue,
     planHash: stringValue,
@@ -259,6 +292,7 @@ export const OPERATION_DATA_SCHEMAS: Readonly<
     steps: valueArray,
     sourceWrites: recordArray,
     diagnostics: stringArray,
+    capabilityPlugins: recordValue,
   }),
   kb_apply_plan: objectData({
     version: stringValue,
@@ -280,12 +314,14 @@ export const OPERATION_DATA_SCHEMAS: Readonly<
     effectFailures: recordArray,
     nextActions: recordArray,
   }),
-  kb_ingest_verification: objectData({
-    receipt: recordValue,
-    testId: stringValue,
-    proofOutcome: stringValue,
-    receiptCount: integerValue,
-    upsert: recordValue,
+  kb_ingest_proof: objectData({
+    artifactDigest: stringValue,
+    environmentHash: stringValue,
+    integration: stringValue,
+    passed: integerValue,
+    failed: integerValue,
+    unchanged: integerValue,
+    results: recordArray,
     status: stringValue,
     effectFailures: recordArray,
     nextActions: recordArray,
@@ -333,11 +369,21 @@ const EFFECT_OVERRIDES: Readonly<
     "kb-write": { destructive: true, retrySafety: "unsafe" },
     "workspace-write": { destructive: true, retrySafety: "unsafe" },
   },
-  kb_ingest_verification: {
+  kb_ingest_proof: {
     "kb-write": { destructive: true, retrySafety: "unsafe" },
   },
 };
 
+export function assertUniqueEffectKinds(
+  operation: string,
+  declarations: readonly { readonly kind: string }[],
+  expectedSize: number,
+): void {
+  if (new Set(declarations.map(({ kind }) => kind)).size !== expectedSize) {
+    throw new Error(`Duplicate effect contract for ${operation}`);
+  }
+}
+
 export function declaredEffects(
   operation: OperationName,
   effects: readonly OperationEffect[],
@@ -359,8 +405,6 @@ export function declaredEffects(
       openWorld: override.openWorld === true,
     };
   });
-  if (new Set(declarations.map(({ kind }) => kind)).size !== expected.size) {
-    throw new Error(`Duplicate effect contract for ${operation}`);
-  }
+  assertUniqueEffectKinds(operation, declarations, expected.size);
   return declarations;
 }

package/src/public/operations/discovery-entities.ts

@@ -11,6 +11,9 @@ export type EntityQueryInput = {
   readonly id?: string;
   readonly tags?: readonly string[];
   readonly sourceFile?: string;
+  /** Page size for index-backed queries; bounds each query's output. */
+  readonly limit?: number;
+  readonly offset?: number;
 };
 
 export const VALID_ENTITY_TYPES = [
@@ -63,6 +66,10 @@ export function buildEntityGoal(input: EntityQueryInput): string {
   }
   if (type) {
     const safeType = escapeAtomContent(type);
+    if (input.limit !== undefined) {
+      const offset = input.offset ?? 0;
+      return `kb_query_entities('${safeType}', none, [], none, ${input.limit}, ${offset}, Results, Count)`;
+    }
     return `findall([Id,'${safeType}',Props], kb_entity(Id, '${safeType}', Props), Results)`;
   }
   return "findall([Id,Type,Props], kb_entity(Id, Type, Props), Results)";
@@ -109,6 +116,52 @@ export function paginateResults<T>(
   return results.slice(offset, offset + limit);
 }
 
+/**
+ * Page size for index-backed search candidate fetches. Each page is one
+ * Prolog query, so a fixed page size substantially bounds each response and
+ * fixes the observed large-KB output overflow; it is a practical bound, not
+ * a byte-size guarantee for arbitrarily large individual entity payloads.
+ */
+// implements REQ-kibi-operation-interface-parity, REQ-mcp-search-discovery
+export const SEARCH_CANDIDATE_PAGE_SIZE = 500;
+
+// implements REQ-kibi-operation-interface-parity, REQ-mcp-search-discovery
+export async function loadSearchCandidates(
+  prolog: Pick<PrologPort, "searchEntities">,
+  input: {
+    readonly query: string;
+    readonly type?: string;
+    readonly maxCandidates?: number;
+  },
+  signal?: AbortSignal,
+): Promise<Record<string, unknown>[]> {
+  const maxCandidates = input.maxCandidates ?? Number.POSITIVE_INFINITY;
+  const candidates: Record<string, unknown>[] = [];
+  let offset = 0;
+  let total = Number.POSITIVE_INFINITY;
+  while (offset < total && candidates.length < maxCandidates) {
+    // Call through the port property, never via a detached local: EngineClient
+    // searchEntities depends on `this` (this.command), and the PrologPort
+    // contract does not promise a pre-bound method.
+    const page = await prolog.searchEntities?.(
+      {
+        query: input.query,
+        ...(input.type !== undefined ? { type: input.type } : {}),
+        limit: SEARCH_CANDIDATE_PAGE_SIZE,
+        offset,
+      },
+      signal,
+    );
+    if (!page || page.entities.length === 0) break;
+    candidates.push(...page.entities);
+    total = page.count;
+    offset += page.entities.length;
+  }
+  return Number.isFinite(maxCandidates)
+    ? candidates.slice(0, maxCandidates)
+    : candidates;
+}
+
 // implements REQ-002
 export function dedupeEntities(
   entities: readonly Record<string, unknown>[],

package/src/public/operations/discovery-executors.ts

@@ -15,9 +15,11 @@ import {
   type BranchStoreInspection,
   branchStoreReason,
   inspectBranchStore,
+  storeLockJournalReason,
 } from "../../utils/branch-store.js";
 import {
   loadEntities,
+  loadSearchCandidates,
   paginateResults,
   validateEntityType,
 } from "./discovery-entities.js";
@@ -76,12 +78,12 @@ export type StatusPayload = {
   readonly syncState: string;
   readonly kbPath?: string;
   readonly lastSyncSource?: string;
-  readonly verificationSnapshot?: string;
-  readonly verificationSnapshotAvailable?: boolean;
-  readonly verificationSnapshotDirty?: boolean;
-  readonly verificationSnapshotFileCount?: number;
-  readonly verificationSnapshotVersion?: string;
-  readonly verificationSnapshotError?: string;
+  readonly proofSnapshot?: string;
+  readonly proofSnapshotAvailable?: boolean;
+  readonly proofSnapshotDirty?: boolean;
+  readonly proofSnapshotFileCount?: number;
+  readonly proofSnapshotVersion?: string;
+  readonly proofSnapshotError?: string;
   readonly staleReasons?: readonly Record<string, unknown>[];
   readonly staleReasonCount?: number;
   readonly staleReasonsTruncated?: boolean;
@@ -91,9 +93,9 @@ export type StatusPayload = {
     readonly kind: "exact" | "explicit_override" | "legacy_compat";
     readonly migrationRequired: boolean;
   };
-  readonly verificationSnapshotChanges?: readonly Record<string, unknown>[];
-  readonly verificationSnapshotChangeCount?: number;
-  readonly verificationSnapshotChangesTruncated?: boolean;
+  readonly proofSnapshotChanges?: readonly Record<string, unknown>[];
+  readonly proofSnapshotChangeCount?: number;
+  readonly proofSnapshotChangesTruncated?: boolean;
   readonly branchStore?: BranchStoreInspection;
   readonly engineStatus?: {
     readonly state: "healthy" | "unavailable";
@@ -139,15 +141,19 @@ export async function executeQuery(
   const { type, id, tags, sourceFile, limit = 100, offset = 0 } = input;
   try {
     const prolog = requireProlog(context);
+    const signal = context.signal;
     const indexedPage = prolog.queryEntities
-      ? await prolog.queryEntities({
-          ...(type !== undefined ? { type } : {}),
-          ...(id !== undefined ? { id } : {}),
-          ...(tags !== undefined ? { tags } : {}),
-          ...(sourceFile !== undefined ? { sourceFile } : {}),
-          limit,
-          offset,
-        })
+      ? await prolog.queryEntities(
+          {
+            ...(type !== undefined ? { type } : {}),
+            ...(id !== undefined ? { id } : {}),
+            ...(tags !== undefined ? { tags } : {}),
+            ...(sourceFile !== undefined ? { sourceFile } : {}),
+            limit,
+            offset,
+          },
+          signal,
+        )
       : null;
     if (indexedPage !== null) {
       const paginated = indexedPage.entities;
@@ -259,15 +265,17 @@ export async function executeSearch(
       };
     }
     const indexedCandidates = prolog.searchEntities
-      ? await prolog.searchEntities({
-          query: trimmedQuery,
-          ...(type !== undefined ? { type } : {}),
-          limit: 100_000,
-          offset: 0,
-        })
+      ? await loadSearchCandidates(
+          prolog,
+          {
+            query: trimmedQuery,
+            ...(type !== undefined ? { type } : {}),
+          },
+          context.signal,
+        )
       : null;
     const entities = indexedCandidates
-      ? [...indexedCandidates.entities]
+      ? [...indexedCandidates]
       : await loadEntities(prolog, {
           ...(type !== undefined ? { type } : {}),
         });
@@ -334,21 +342,27 @@ export async function executeStatus(
       };
     } else
       try {
-        const prolog =
-          context.prolog ??
-          (() => {
-            ownedEngine = new EngineClient({
-              workspaceRoot: context.workspaceRoot,
-              branch: attachment.kbBranch,
-              timeout: 15_000,
-            });
-            return ownedEngine;
-          })();
+        // Prefer an injected or session-backed engine so MCP status shares the
+        // same client as discovery tools. Only spawn an owned fallback when no
+        // host session is available (CLI status without a live runtime port).
+        let prolog = context.prolog;
+        if (!prolog && context.ensureProlog) {
+          prolog = await context.ensureProlog();
+        }
+        if (!prolog) {
+          ownedEngine = new EngineClient({
+            workspaceRoot: context.workspaceRoot,
+            branch: attachment.kbBranch,
+            timeout: 15_000,
+          });
+          prolog = ownedEngine;
+        }
         payload = await runOperationJsonQuery<StatusPayload>(
           prolog,
           "status.pl",
           "status:kb_status_json(JsonString)",
           "Status execution",
+          context.signal,
         );
         if (!isStatusPayload(payload)) {
           throw new Error("Status execution query returned an invalid payload");
@@ -385,6 +399,7 @@ export async function executeStatus(
     const snapshotEvidence = await readWorkspaceSnapshot(context);
     const existingReasons = payload.staleReasons ?? [];
     const storeReason = branchStoreReason(store);
+    const lockReason = storeLockJournalReason(store.path);
     const engineReason = engineStatus
       ? {
           code: engineStatus.errorCode ?? "engine_status_unavailable",
@@ -402,6 +417,7 @@ export async function executeStatus(
     const staleReasons = [
       ...existingReasons,
       ...(storeReason ? [storeReason] : []),
+      ...(lockReason ? [lockReason] : []),
       ...(engineReason ? [engineReason] : []),
     ].sort((left, right) =>
       String(left.path ?? "").localeCompare(String(right.path ?? "")),
@@ -414,23 +430,22 @@ export async function executeStatus(
       staleReasons,
       staleReasonCount: staleReasons.length,
       staleReasonsTruncated: false,
-      verificationSnapshot: snapshotEvidence.available
+      proofSnapshot: snapshotEvidence.available
         ? snapshotEvidence.snapshot.hash
         : "unknown",
-      verificationSnapshotAvailable: snapshotEvidence.available,
+      proofSnapshotAvailable: snapshotEvidence.available,
       ...(snapshotEvidence.available
         ? {
-            verificationSnapshotDirty: snapshotEvidence.snapshot.dirty,
-            verificationSnapshotFileCount: snapshotEvidence.snapshot.fileCount,
-            verificationSnapshotVersion: snapshotEvidence.snapshot.version,
-            verificationSnapshotChanges:
-              snapshotEvidence.snapshot.changes ?? [],
-            verificationSnapshotChangeCount:
+            proofSnapshotDirty: snapshotEvidence.snapshot.dirty,
+            proofSnapshotFileCount: snapshotEvidence.snapshot.fileCount,
+            proofSnapshotVersion: snapshotEvidence.snapshot.version,
+            proofSnapshotChanges: snapshotEvidence.snapshot.changes ?? [],
+            proofSnapshotChangeCount:
               snapshotEvidence.snapshot.changeCount ?? 0,
-            verificationSnapshotChangesTruncated:
+            proofSnapshotChangesTruncated:
               snapshotEvidence.snapshot.changesTruncated ?? false,
           }
-        : { verificationSnapshotError: snapshotEvidence.error }),
+        : { proofSnapshotError: snapshotEvidence.error }),
     };
     const schemaStatus = readMigrationConfigStatus(context.workspaceRoot);
     const migrationPlan = buildActionsFromStatus({
@@ -438,9 +453,9 @@ export async function executeStatus(
       branchAttachment: attachment,
       branchStore: store,
       staleReasons,
-      verificationSnapshotAvailable: snapshotEvidence.available,
+      proofSnapshotAvailable: snapshotEvidence.available,
       ...(snapshotEvidence.available
-        ? { verificationSnapshotDirty: snapshotEvidence.snapshot.dirty }
+        ? { proofSnapshotDirty: snapshotEvidence.snapshot.dirty }
         : {}),
       kbSnapshotId: payload.snapshotId,
       workspaceSnapshot: snapshotEvidence.available
@@ -448,7 +463,7 @@ export async function executeStatus(
         : null,
       configStatus: schemaStatus,
     });
-    const bootstrapSourceFiles = context.fs?.glob
+    const listed = context.fs?.glob
       ? await context.fs.glob(
           [
             ".kb/requirements/**/*.md",
@@ -463,6 +478,7 @@ export async function executeStatus(
           { cwd: context.workspaceRoot },
         )
       : [];
+    const bootstrapSourceFiles = Array.isArray(listed) ? listed : [];
     const bootstrapActivation = await classifyActivation(
       context,
       bootstrapSourceFiles,
@@ -514,7 +530,7 @@ export async function executeStatus(
       content: [
         {
           type: "text",
-          text: `Branch ${payload.branch} is ${payload.syncState} (snapshot ${payload.snapshotId}, dirty=${payload.dirty}, verificationSnapshot=${enrichedPayload.verificationSnapshot})`,
+          text: `Branch ${payload.branch} is ${payload.syncState} (snapshot ${payload.snapshotId}, dirty=${payload.dirty}, proofSnapshot=${enrichedPayload.proofSnapshot})`,
         },
       ],
       structuredContent: statusWithPlan,

package/src/public/operations/index.ts

@@ -13,7 +13,7 @@ export * from "./specs/check.js";
 export * from "./specs/discovery.js";
 export * from "./specs/modeling.js";
 export * from "./specs/planning.js";
-export * from "./specs/verification.js";
+export * from "./specs/proof.js";
 export * from "./specs/mutation.js";
 export * from "./specs/reporting.js";
 export * from "./specs/semantic.js";