kibi-cli 0.19.0 → 1.0.1

package/src/public/operations/node-ports.ts

@@ -1,5 +1,6 @@
-import { execFile } from "node:child_process";
+import { execFile, execFileSync } from "node:child_process";
 import { createHash } from "node:crypto";
+import * as fsSync from "node:fs";
 import * as fs from "node:fs/promises";
 import path from "node:path";
 import { promisify } from "node:util";
@@ -23,10 +24,22 @@ type NodeGitPort = GitPort & {
 };
 
 const execFileAsync = promisify(execFile);
-const SNAPSHOT_EXCLUDED_PREFIXES = [".changeset/", ".kb/", "docs/"] as const;
+const SNAPSHOT_EXCLUDED_PREFIXES = [
+  ".changeset/",
+  ".kb/branches/",
+  ".kb/recovery/",
+  ".kb/verification/",
+  ".kb/briefs/",
+  ".kb/migrations/",
+  "docs/",
+] as const;
 const ALWAYS_IGNORED_GLOBS = [
   "**/.git/**",
-  "**/.kb/**",
+  "**/.kb/branches/**",
+  "**/.kb/recovery/**",
+  "**/.kb/verification/**",
+  "**/.kb/briefs/**",
+  "**/.kb/migrations/**",
   "**/node_modules/**",
   "**/vendor/**",
   "**/vendors/**",
@@ -76,10 +89,7 @@ function withoutVerificationReceiptFrontmatter(content: string): string {
 }
 
 function snapshotFileContent(relativePath: string, content: Buffer): Buffer {
-  if (
-    relativePath.startsWith("documentation/") &&
-    relativePath.endsWith(".md")
-  ) {
+  if (relativePath.endsWith(".md")) {
     return Buffer.from(
       withoutVerificationReceiptFrontmatter(content.toString("utf8")),
     );
@@ -87,6 +97,34 @@ function snapshotFileContent(relativePath: string, content: Buffer): Buffer {
   return content;
 }
 
+/**
+ * A tracked markdown file whose only change is verification-receipt frontmatter
+ * cannot alter the snapshot hash (receipts are stripped before hashing), so it
+ * must not mark the workspace dirty either. CI proof runs append receipts to
+ * tracked proof documents before reporting, and would otherwise always surface
+ * a dirty-workspace warning.
+ */
+function isReceiptOnlyMarkdownChange(
+  workspaceRoot: string,
+  relativePath: string,
+): boolean {
+  if (!relativePath.endsWith(".md")) return false;
+  try {
+    const working = snapshotFileContent(
+      relativePath,
+      fsSync.readFileSync(path.join(workspaceRoot, relativePath)),
+    );
+    const committed = execFileSync(
+      "git",
+      ["-C", workspaceRoot, "show", `HEAD:${relativePath}`],
+      { encoding: "buffer", maxBuffer: 64 * 1024 * 1024 },
+    ) as Buffer;
+    return working.equals(snapshotFileContent(relativePath, committed));
+  } catch {
+    return false;
+  }
+}
+
 async function workspaceSnapshot(workspaceRoot: string) {
   const { stdout: listed } = await execFileAsync(
     "git",
@@ -108,7 +146,7 @@ async function workspaceSnapshot(workspaceRoot: string) {
     .filter(includedSnapshotPath)
     .sort();
   const digest = createHash("sha256");
-  digest.update("kibi.workspace-snapshot.v1\0");
+  digest.update("kibi.workspace-snapshot.v2\0");
   for (const relativePath of paths) {
     digest.update(relativePath);
     digest.update("\0");
@@ -132,14 +170,48 @@ async function workspaceSnapshot(workspaceRoot: string) {
       "status",
       "--porcelain=v1",
       "--untracked-files=normal",
+      "-z",
     ],
     { maxBuffer: 16 * 1024 * 1024 },
   );
+  const rawChanges = status.split("\0").filter(Boolean);
+  const changes: {
+    path: string;
+    status: string;
+    snapshotRelevant: boolean;
+    previousPath?: string;
+  }[] = [];
+  for (let index = 0; index < rawChanges.length; index++) {
+    const entry = rawChanges[index] ?? "";
+    const statusCode = entry.slice(0, 2);
+    const relativePath = entry.slice(3).replaceAll("\\", "/");
+    const previous = rawChanges[index + 1];
+    const isRenameOrCopy = statusCode[0] === "R" || statusCode[0] === "C";
+    const previousPath =
+      isRenameOrCopy && previous ? previous.replaceAll("\\", "/") : undefined;
+    const receiptOnly =
+      statusCode.includes("M") &&
+      includedSnapshotPath(relativePath) &&
+      isReceiptOnlyMarkdownChange(workspaceRoot, relativePath);
+    changes.push({
+      path: relativePath,
+      status: statusCode,
+      snapshotRelevant:
+        (includedSnapshotPath(relativePath) && !receiptOnly) ||
+        (previousPath !== undefined && includedSnapshotPath(previousPath)),
+      ...(previousPath !== undefined ? { previousPath } : {}),
+    });
+    if (previousPath !== undefined) index++;
+  }
+  const maxChanges = 200;
   return {
-    version: "kibi.workspace-snapshot.v1" as const,
+    version: "kibi.workspace-snapshot.v2" as const,
     hash: digest.digest("hex"),
-    dirty: status.trim().length > 0,
+    dirty: changes.some((change) => change.snapshotRelevant),
     fileCount: paths.length,
+    changes: changes.slice(0, maxChanges),
+    changeCount: changes.length,
+    changesTruncated: changes.length > maxChanges,
   };
 }
 
@@ -148,10 +220,12 @@ export const nodeFilesystem: NodeFilesystemPort = {
   writeFile: async (filePath, data) => {
     await fs.writeFile(filePath, data, "utf8");
   },
+  rename: (from, to) => fs.rename(from, to),
   mkdir: async (directoryPath) => {
     await fs.mkdir(directoryPath, { recursive: true });
   },
   stat: (filePath) => fs.stat(filePath),
+  unlink: (filePath) => fs.unlink(filePath),
   glob: (patterns, options) =>
     fg([...patterns], {
       cwd: options.cwd,

package/src/public/operations/prolog-json.ts

@@ -5,6 +5,43 @@ import { resolveKbPlPath } from "../../prolog.js";
 import { escapeAtom } from "../../prolog/codec.js";
 import type { PrologPort } from "./runtime-types.js";
 
+export type JsonBindingDecodeStage = "outer" | "inner";
+
+/**
+ * A JSON operation result is transported through Prolog's answer printer and
+ * then through the engine frame. Keep decode failures typed and bounded: the
+ * raw binding may contain project-authored data and must never be copied into
+ * diagnostics wholesale.
+ */
+export class OperationJsonDecodeError extends Error {
+  readonly code = "engine_result_invalid_json";
+  readonly stage: JsonBindingDecodeStage;
+  readonly rawLength: number;
+  readonly prefixCodePoints: readonly number[];
+
+  constructor(
+    errorLabel: string,
+    stage: JsonBindingDecodeStage,
+    rawJson: unknown,
+    cause: unknown,
+  ) {
+    const rawText = typeof rawJson === "string" ? rawJson : "";
+    const bindingType = typeof rawJson;
+    const message = cause instanceof Error ? cause.message : String(cause);
+    super(
+      `${errorLabel} returned invalid JSON binding (stage=${stage}, bindingType=${bindingType}, length=${rawText.length}, prefixCodePoints=${JSON.stringify([...rawText].slice(0, 8).map((character) => character.codePointAt(0) ?? 0))}): ${message}`,
+    );
+    this.name = "OperationJsonDecodeError";
+    this.stage = stage;
+    this.rawLength = rawText.length;
+    this.prefixCodePoints = Object.freeze(
+      [...rawText]
+        .slice(0, 8)
+        .map((character) => character.codePointAt(0) ?? 0),
+    );
+  }
+}
+
 function resolveCoreModulePath(fileName: string): string {
   const genericOverride = getKbPlPathOverride();
   return path.join(
@@ -29,9 +66,10 @@ export async function runOperationJsonQuery<T>(
   const longLivedEngine =
     typeof (prolog as { storageStatus?: unknown }).storageStatus === "function";
   const oneShotMode =
-    !longLivedEngine &&
-    process.env.NODE_ENV === "test" &&
-    typeof (globalThis as { Bun?: unknown }).Bun !== "undefined";
+    prolog.oneShotMode === true ||
+    (!longLivedEngine &&
+      process.env.NODE_ENV === "test" &&
+      typeof (globalThis as { Bun?: unknown }).Bun !== "undefined");
   const typedStatusQuery = prolog.queryStatusJson;
   const result =
     fileName === "status.pl" && typeof typedStatusQuery === "function"
@@ -48,9 +86,26 @@ export async function runOperationJsonQuery<T>(
   if (rawJson === undefined) {
     throw new Error(`${errorLabel} query returned no JsonString binding`);
   }
-  let parsed: unknown = JSON.parse(rawJson);
+  if (typeof rawJson !== "string") {
+    throw new OperationJsonDecodeError(
+      errorLabel,
+      "outer",
+      rawJson,
+      new TypeError("JsonString binding is not a string"),
+    );
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(rawJson);
+  } catch (error) {
+    throw new OperationJsonDecodeError(errorLabel, "outer", rawJson, error);
+  }
   if (typeof parsed === "string") {
-    parsed = JSON.parse(parsed);
+    try {
+      parsed = JSON.parse(parsed);
+    } catch (error) {
+      throw new OperationJsonDecodeError(errorLabel, "inner", parsed, error);
+    }
   }
   return parsed as T;
 }

package/src/public/operations/repair-plan.ts

@@ -237,6 +237,7 @@ const GAP_STAGE: Readonly<Record<string, string>> = {
   stale_verification_receipt: "passing_e2e",
   failed_verification_receipt: "passing_e2e",
   invalid_verification_receipt: "passing_e2e",
+  verification_contract_mismatch: "passing_e2e",
   verification_snapshot_unavailable: "passing_e2e",
   missing_executable_test_symbol: "executable_symbols",
   missing_production_symbol: "production_symbols",

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

@@ -0,0 +1,136 @@
+import type { KibiResult, OperationEffect, OperationName } from "./types.js";
+
+export const KIBI_PROTOCOL_VERSION = 1 as const;
+
+function record(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function diagnostics(value: unknown): KibiResult["diagnostics"] {
+  if (!Array.isArray(value)) return [];
+  return value.flatMap((entry) => {
+    if (typeof entry === "string")
+      return [{ message: entry, severity: "warning" as const }];
+    if (!record(entry) || typeof entry.message !== "string") return [];
+    return [entry as KibiResult["diagnostics"][number]];
+  });
+}
+
+function nextActions(value: unknown): KibiResult["nextActions"] {
+  if (!Array.isArray(value)) return [];
+  return value.flatMap((entry) => {
+    if (
+      !record(entry) ||
+      typeof entry.operation !== "string" ||
+      typeof entry.reason !== "string"
+    )
+      return [];
+    return [
+      {
+        operation: entry.operation,
+        input: entry.input,
+        reason: entry.reason,
+        required: entry.required === true,
+      },
+    ];
+  });
+}
+
+function effectStatus(
+  effect: OperationEffect,
+  data: Record<string, unknown> | undefined,
+): KibiResult["effects"][number] {
+  const failures = data?.effectFailures;
+  if (Array.isArray(failures)) {
+    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 }
+          : {}),
+      };
+    }
+  }
+  return { kind: effect, status: "completed" };
+}
+
+function extraFailedEffects(
+  declared: readonly OperationEffect[],
+  data: Record<string, unknown> | undefined,
+): KibiResult["effects"] {
+  const failures = data?.effectFailures;
+  if (!Array.isArray(failures)) return [];
+  const seen = new Set(declared);
+  return failures.flatMap((entry) => {
+    if (
+      !record(entry) ||
+      typeof entry.kind !== "string" ||
+      seen.has(entry.kind as OperationEffect)
+    ) {
+      return [];
+    }
+    seen.add(entry.kind as OperationEffect);
+    return [
+      {
+        kind: entry.kind,
+        status: "failed" as const,
+        detail: entry.detail,
+        ...(typeof entry.errorCode === "string"
+          ? { errorCode: entry.errorCode }
+          : {}),
+      },
+    ];
+  });
+}
+
+export function resultVersion(spec: {
+  readonly name: OperationName | string;
+  readonly resultVersion?: string;
+}): string {
+  return spec.resultVersion ?? `kibi.${spec.name}.v1`;
+}
+
+export function toKibiResult<T>(
+  spec: {
+    readonly name: OperationName | string;
+    readonly effects: readonly OperationEffect[];
+    readonly resultVersion?: string;
+  },
+  data: T,
+  options: Partial<
+    Pick<KibiResult<T>, "status" | "diagnostics" | "nextActions" | "error">
+  > = {},
+): KibiResult<T> {
+  const row = record(data) ? data : undefined;
+  const status =
+    options.status ??
+    (row?.status === "committed_with_repairs"
+      ? "committed_with_repairs"
+      : "success");
+  return {
+    kibiProtocol: KIBI_PROTOCOL_VERSION,
+    operation: spec.name as OperationName,
+    resultVersion: resultVersion(spec),
+    status,
+    data,
+    effects: [
+      ...spec.effects.map((effect) => effectStatus(effect, row)),
+      ...extraFailedEffects(spec.effects, row),
+    ],
+    diagnostics: options.diagnostics ?? diagnostics(row?.diagnostics),
+    nextActions: options.nextActions ?? nextActions(row?.nextActions),
+    ...(options.error ? { error: options.error } : {}),
+  };
+}
+
+export function operationData(value: unknown): unknown {
+  if (record(value) && "structuredContent" in value) {
+    return value.structuredContent;
+  }
+  return value;
+}

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

@@ -1,3 +1,4 @@
+import type { BranchAttachment } from "../../utils/branch-resolver.js";
 import type { OperationEffect } from "./types.js";
 
 export type { OperationEffect } from "./types.js";
@@ -35,20 +36,79 @@ export type PrologSearchQueryResult = Readonly<{
   count: number;
 }>;
 
+/** Goal-free, versioned commands accepted by the journaled engine. */
+export type EngineCommandV1 =
+  | Readonly<{ version: 1; kind: "status" }>
+  | Readonly<{
+      version: 1;
+      kind: "entities";
+      type?: string;
+      id?: string;
+      tags?: readonly string[];
+      sourceFile?: string;
+      limit: number;
+      offset: number;
+    }>
+  | Readonly<{
+      version: 1;
+      kind: "search";
+      query: string;
+      type?: string;
+      limit: number;
+      offset: number;
+    }>
+  | Readonly<{ version: 1; kind: "checkpoint" }>
+  | Readonly<{ version: 1; kind: "compact" }>
+  | Readonly<{ version: 1; kind: "save" }>
+  | Readonly<{ version: 1; kind: "check"; rule?: string }>
+  | Readonly<{
+      version: 1;
+      kind: "relationship";
+      action: "assert" | "retract";
+      type: string;
+      from: string;
+      to: string;
+    }>
+  | Readonly<{
+      version: 1;
+      kind: "persistence";
+      action: "checkpoint" | "compact" | "save" | "export";
+      targetDirectory?: string;
+    }>
+  | Readonly<{
+      version: 1;
+      kind: "lifecycle";
+      action: "stop" | "cancel";
+      requestId?: number;
+    }>
+  | Readonly<{ version: 1; kind: "stop" }>
+  | Readonly<{ version: 1; kind: "cancel"; requestId: number }>;
+
+export interface EnginePort {
+  execute<T = PrologQueryResult>(
+    command: EngineCommandV1,
+    signal?: AbortSignal,
+  ): Promise<T>;
+}
+
 // implements REQ-kibi-operation-interface-parity
 export interface PrologPort {
-  query(goal: string): Promise<PrologQueryResult>;
+  query(goal: string, signal?: AbortSignal): Promise<PrologQueryResult>;
+  /** True when each query is isolated and must include its module load. */
+  oneShotMode?: boolean;
   /** Optional index-backed page query supplied by the journaled engine. */
   queryEntities?(
     input: PrologEntityQueryInput,
+    signal?: AbortSignal,
   ): Promise<PrologEntityQueryResult>;
   /** Optional normalized-token candidate lookup supplied by the engine. */
   searchEntities?(
     input: PrologSearchQueryInput,
+    signal?: AbortSignal,
   ): Promise<PrologSearchQueryResult>;
   nextSolution(): Promise<PrologQueryResult | null>;
   invalidateCache?(): void;
-  save(): Promise<PrologQueryResult>;
+  save(signal?: AbortSignal): Promise<PrologQueryResult>;
   /** Present on the journaled engine; used to distinguish a persistent port from one-shot SWI. */
   storageStatus?(): Promise<PrologQueryResult>;
   /** Typed public freshness query; avoids exposing module loading over RPC. */
@@ -63,21 +123,39 @@ export type FilesystemStat = {
 export interface FilesystemPort {
   readFile(path: string): Promise<string>;
   writeFile(path: string, data: string): Promise<void>;
+  /** Optional workspace globbing used by source-posture classifiers. */
+  glob?(
+    patterns: readonly string[],
+    options: { readonly cwd: string; readonly includeIgnored?: boolean },
+  ): Promise<readonly string[]>;
+  /** Replace a file atomically when the host filesystem supports it. */
+  rename?(from: string, to: string): Promise<void>;
   mkdir(path: string): Promise<void>;
   stat(path: string): Promise<FilesystemStat>;
+  /** Optional destructive primitive used only to roll back newly-created files. */
+  unlink?(path: string): Promise<void>;
 }
 
 export interface GitPort {
-  revParse(...args: readonly string[]): Promise<string>;
-  showToplevel(): Promise<string>;
+  /** Optional low-level Git probes; the journaled runtime may provide them. */
+  revParse?(...args: readonly string[]): Promise<string>;
+  showToplevel?(): Promise<string>;
   workspaceSnapshot?(workspaceRoot: string): Promise<WorkspaceSnapshot>;
 }
 
 export type WorkspaceSnapshot = Readonly<{
-  version: "kibi.workspace-snapshot.v1";
+  version: "kibi.workspace-snapshot.v2";
   hash: string;
+  /** True only when at least one change can alter the verification snapshot. */
   dirty: boolean;
   fileCount: number;
+  readonly changes?: readonly {
+    readonly path: string;
+    readonly status: string;
+    readonly snapshotRelevant: boolean;
+  }[];
+  readonly changeCount?: number;
+  readonly changesTruncated?: boolean;
 }>;
 
 export interface NetworkPort {
@@ -101,9 +179,17 @@ export type OperationContext = {
   readonly signal: AbortSignal;
   readonly clock: Clock;
   readonly prolog?: PrologPort;
+  readonly engine?: EnginePort;
+  /** Lazily acquire the branch engine for operations that may start without Prolog. */
+  readonly ensureProlog?: () => Promise<PrologPort>;
   readonly fs?: FilesystemPort;
+  /** Whether filesystem-capable mutations must author tracked source files. */
+  readonly sourceFirst?: boolean;
+  /** Internal apply-plan capability: source bytes were already approved/published. */
+  readonly sourcePlanApplication?: boolean;
   readonly git?: GitPort;
   readonly net?: NetworkPort;
+  readonly branchAttachment?: BranchAttachment;
 };
 
 export interface RuntimeOperationSpec<TInput = unknown, TResult = unknown> {