kibi-cli 0.19.0 → 2.0.0

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

@@ -0,0 +1,324 @@
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { coarseCoordinateSpan } from "../../extractors/symbol-coordinates.js";
+import {
+  type ManifestSymbolEntry,
+  analyzeSourceText,
+  enrichSymbolCoordinates,
+} from "../../extractors/symbols-coordinator.js";
+import { isCoarseGranularityReason } from "../symbol-granularity.js";
+import { loadEntities } from "./discovery-entities.js";
+import type { OperationContext } from "./runtime-types.js";
+
+export const SYMBOL_REPAIR_PLAN_VERSION = "kibi.symbol-repair-plan.v1" as const;
+
+export type SymbolRepairPlan = Readonly<{
+  version: typeof SYMBOL_REPAIR_PLAN_VERSION;
+  readOnly: true;
+  autoApplicable: false;
+  repairs: readonly Readonly<Record<string, unknown>>[];
+}>;
+
+function sourceFileOf(
+  entity: Readonly<Record<string, unknown>>,
+): string | null {
+  const value = entity.sourceFile ?? entity.source;
+  return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+
+function coordinatesPresent(
+  entity: Readonly<Record<string, unknown>>,
+): boolean {
+  return [
+    entity.sourceLine,
+    entity.sourceColumn,
+    entity.sourceEndLine,
+    entity.sourceEndColumn,
+  ].every((value) => Number.isInteger(value) && Number(value) >= 0);
+}
+
+export type CoordinateRepairEvidence = Readonly<{
+  symbolId: string;
+  sourceFile: string | null;
+  refreshable: boolean;
+  reason:
+    | "extractable"
+    | "coarse_anchor"
+    | "extractor_miss"
+    | "source_unavailable";
+  suggestion: string;
+}>;
+
+/** Preview the same extraction and explicit coarse fallback used by refresh. */
+export async function inspectCoordinateRepairs(
+  symbols: readonly Readonly<Record<string, unknown>>[],
+  workspaceRoot: string,
+): Promise<Map<string, CoordinateRepairEvidence>> {
+  const entries: ManifestSymbolEntry[] = symbols.map((symbol) => {
+    const sourceFile = sourceFileOf(symbol);
+    return {
+      id: String(symbol.id),
+      title: typeof symbol.title === "string" ? symbol.title : "",
+      ...(sourceFile === null ? {} : { sourceFile }),
+      ...(typeof symbol.granularity_reason === "string"
+        ? { granularity_reason: symbol.granularity_reason }
+        : {}),
+    };
+  });
+  const enriched = await enrichSymbolCoordinates(entries, workspaceRoot);
+  return new Map(
+    entries.map((entry, index) => {
+      const sourceFile = entry.sourceFile ?? null;
+      let source: string | null = null;
+      if (sourceFile) {
+        try {
+          source = readFileSync(
+            path.resolve(workspaceRoot, sourceFile),
+            "utf8",
+          );
+        } catch {
+          /* A missing or unreadable source requires authored repair. */
+        }
+      }
+      const extracted =
+        entry.title.length > 0 && coordinatesPresent(enriched[index] ?? {});
+      const coarse =
+        source !== null &&
+        sourceFile !== null &&
+        isCoarseGranularityReason(entry.granularity_reason) &&
+        coarseCoordinateSpan(sourceFile, entry.title, source) !== null;
+      const reason =
+        source === null
+          ? "source_unavailable"
+          : extracted
+            ? "extractable"
+            : coarse
+              ? "coarse_anchor"
+              : "extractor_miss";
+      const refreshable = source !== null && (extracted || coarse);
+      return [
+        entry.id,
+        {
+          symbolId: entry.id,
+          sourceFile,
+          refreshable,
+          reason,
+          suggestion: refreshable
+            ? "Refresh and persist current symbol coordinates."
+            : source === null
+              ? "Repair sourceFile to point to readable implementation code before refreshing."
+              : "Query and validate the symbol, then author a resolvable title/sourceFile or an explicit granularity_reason: extractor-miss (or another intentional coarse anchor) through kb_upsert before refreshing.",
+        },
+      ];
+    }),
+  );
+}
+
+/** Attach current extraction evidence before constructing requirement repairs. */
+export async function addCoordinateRepairEvidence(
+  rows: readonly Readonly<Record<string, unknown>>[],
+  context: OperationContext,
+): Promise<readonly Readonly<Record<string, unknown>>[]> {
+  const missingByRow = rows.map((row) => {
+    const stages = row.proofStages as
+      | { sourceCoordinates?: { missingSymbols?: unknown } }
+      | undefined;
+    const missing = stages?.sourceCoordinates?.missingSymbols;
+    return Array.isArray(missing)
+      ? missing.filter((id): id is string => typeof id === "string")
+      : [];
+  });
+  const ids = new Set(missingByRow.flat());
+  if (ids.size === 0 || !context.prolog) return rows;
+  const symbols = (
+    await loadEntities(context.prolog, { type: "symbol" })
+  ).filter((symbol) => ids.has(String(symbol.id)));
+  const evidence = await inspectCoordinateRepairs(
+    symbols,
+    context.workspaceRoot,
+  );
+  return rows.map((row, index) => {
+    const missing = missingByRow[index] ?? [];
+    if (missing.length === 0) return row;
+    const coordinateRepairs = missing.map(
+      (id) =>
+        evidence.get(id) ?? {
+          symbolId: id,
+          sourceFile: null,
+          refreshable: false,
+          reason: "source_unavailable",
+          suggestion: "Query and repair the missing symbol before refreshing.",
+        },
+    );
+    const stages = row.proofStages as Record<string, Record<string, unknown>>;
+    return {
+      ...row,
+      ...(Array.isArray(row.proofRepairs)
+        ? {
+            proofRepairs: row.proofRepairs.map((repair) =>
+              repair?.gap === "missing_symbol_coordinates" &&
+              coordinateRepairs.some((item) => !item.refreshable)
+                ? {
+                    ...repair,
+                    action: [
+                      ...new Set(
+                        coordinateRepairs
+                          .filter((item) => !item.refreshable)
+                          .map((item) => item.suggestion),
+                      ),
+                    ].join(" "),
+                  }
+                : repair,
+            ),
+          }
+        : {}),
+      proofStages: {
+        ...stages,
+        sourceCoordinates: {
+          ...stages.sourceCoordinates,
+          coordinateRepairs,
+        },
+      },
+    };
+  });
+}
+
+function currentCandidates(
+  entity: Readonly<Record<string, unknown>>,
+  symbols: readonly Readonly<Record<string, unknown>>[],
+  extractedByPath: ReadonlyMap<
+    string,
+    readonly { name: string; kind: string }[]
+  >,
+): Readonly<Record<string, unknown>>[] {
+  const title = typeof entity.title === "string" ? entity.title : "";
+  const kind = typeof entity.symbol_kind === "string" ? entity.symbol_kind : "";
+  const source = sourceFileOf(entity);
+  const extracted = source ? (extractedByPath.get(source) ?? []) : [];
+  const names = new Set(
+    extracted
+      .filter((candidate) => !kind || candidate.kind === kind)
+      .map((candidate) => candidate.name),
+  );
+  return symbols
+    .filter((candidate) => candidate.id !== entity.id)
+    .filter((candidate) => {
+      const candidateTitle =
+        typeof candidate.title === "string" ? candidate.title : "";
+      const candidateKind =
+        typeof candidate.symbol_kind === "string" ? candidate.symbol_kind : "";
+      return (
+        (title !== "" && candidateTitle === title) ||
+        (kind !== "" && candidateKind === kind && names.has(candidateTitle))
+      );
+    })
+    .map((candidate) => ({
+      symbolId: String(candidate.id),
+      title: candidate.title,
+      symbolKind: candidate.symbol_kind,
+      sourceFile: sourceFileOf(candidate),
+      evidence: "current extraction/title/kind match",
+    }));
+}
+
+/** Build review-only, evidence-backed symbol recovery suggestions. */
+export async function buildSymbolRepairPlan(
+  rows: readonly Readonly<Record<string, unknown>>[],
+  context: OperationContext,
+): Promise<SymbolRepairPlan | undefined> {
+  if (!context.prolog || rows.length === 0) return undefined;
+  const symbols = await loadEntities(context.prolog, { type: "symbol" });
+  const extractedByPath = new Map<
+    string,
+    readonly { name: string; kind: string }[]
+  >();
+  for (const symbol of symbols) {
+    const source = sourceFileOf(symbol);
+    if (!source || extractedByPath.has(source)) continue;
+    const absolute = path.isAbsolute(source)
+      ? source
+      : path.resolve(context.workspaceRoot, source);
+    if (!existsSync(absolute)) continue;
+    try {
+      const analysis = analyzeSourceText(
+        absolute,
+        readFileSync(absolute, "utf8"),
+      );
+      if (analysis.providerId === null) continue;
+      extractedByPath.set(
+        source,
+        analysis.symbols.map((candidate) => ({
+          name: candidate.name,
+          kind: candidate.kind,
+        })),
+      );
+    } catch {
+      // An unavailable extractor cannot establish that a declaration is absent.
+    }
+  }
+
+  const coordinateEvidence = await inspectCoordinateRepairs(
+    symbols.filter((symbol) => !coordinatesPresent(symbol)),
+    context.workspaceRoot,
+  );
+  const repairs = rows.flatMap((row) => {
+    if (row.type !== "symbol") return [];
+    const entity = symbols.find((candidate) => candidate.id === row.id);
+    if (!entity) return [];
+    const source = sourceFileOf(entity);
+    const absolute = source
+      ? path.isAbsolute(source)
+        ? source
+        : path.resolve(context.workspaceRoot, source)
+      : null;
+    const exists = absolute !== null && existsSync(absolute);
+    const candidates = currentCandidates(entity, symbols, extractedByPath);
+    const extraction = source ? extractedByPath.get(source) : undefined;
+    const extractionProvesAbsent =
+      exists &&
+      extraction !== undefined &&
+      !extraction.some(
+        (candidate) =>
+          candidate.name === entity.title &&
+          (!entity.symbol_kind || candidate.kind === entity.symbol_kind),
+      );
+    const gaps = Array.isArray(row.gaps) ? row.gaps.map(String) : [];
+    const action = !exists
+      ? entity.symbol_origin === "extracted"
+        ? "delete_obsolete_symbol"
+        : "review"
+      : extractionProvesAbsent && entity.symbol_origin === "extracted"
+        ? "delete_obsolete_symbol"
+        : !coordinatesPresent(entity)
+          ? coordinateEvidence.get(String(entity.id))?.refreshable === true
+            ? "refresh_coordinates"
+            : "review"
+          : candidates.length > 0
+            ? "remap"
+            : "review";
+    return [
+      {
+        symbolId: String(entity.id),
+        action,
+        candidates,
+        evidence: {
+          sourceFile: source,
+          sourceExists: exists,
+          extractionProvesAbsent,
+          gaps,
+          currentExtractionAvailable: source
+            ? extractedByPath.has(source)
+            : false,
+          autoApply: false,
+          coordinateRepair: coordinateEvidence.get(String(entity.id)),
+        },
+      },
+    ];
+  });
+  return {
+    version: SYMBOL_REPAIR_PLAN_VERSION,
+    readOnly: true,
+    autoApplicable: false,
+    repairs,
+  };
+}

package/src/public/operations/types.ts

@@ -18,7 +18,10 @@ export type OperationName =
   | "kb_check"
   | "kb_model_requirement"
   | "kb_suggest_predicates"
-  | "kb_autopilot_generate";
+  | "kb_plan_bootstrap"
+  | "kb_compile_intent"
+  | "kb_apply_plan"
+  | "kb_ingest_proof";
 
 export type OperationEffect =
   | "local-read"
@@ -28,6 +31,14 @@ export type OperationEffect =
   | "kb-write"
   | "workspace-write";
 
+export type OperationEffectDeclaration = Readonly<{
+  kind: OperationEffect;
+  mutability: "read" | "write";
+  destructive: boolean;
+  retrySafety: "safe" | "unsafe";
+  openWorld: boolean;
+}>;
+
 export interface OperationContent {
   readonly type: string;
   readonly text?: string;
@@ -38,6 +49,40 @@ export interface OperationResult<O = unknown> {
   readonly structuredContent?: O;
 }
 
+export type KibiResultStatus = "success" | "committed_with_repairs" | "error";
+
+export type KibiResult<T = unknown> = {
+  readonly kibiProtocol: 1;
+  readonly operation: OperationName | string;
+  readonly resultVersion: string;
+  readonly status: KibiResultStatus;
+  readonly data: T;
+  readonly effects: readonly {
+    readonly kind: string;
+    readonly status: "completed" | "failed" | "not_applicable";
+    readonly detail?: unknown;
+    readonly errorCode?: string;
+  }[];
+  readonly diagnostics: readonly {
+    readonly code?: string;
+    readonly severity?: "info" | "warning" | "error";
+    readonly message: string;
+    readonly detail?: unknown;
+  }[];
+  readonly nextActions: readonly {
+    readonly operation: OperationName | string;
+    readonly input?: unknown;
+    readonly reason: string;
+    readonly required: boolean;
+  }[];
+  readonly error?: {
+    readonly code: string;
+    readonly message: string;
+    readonly retryable: boolean;
+    readonly details?: unknown;
+  };
+};
+
 export interface OperationSpec<
   I = Readonly<Record<string, unknown>>,
   O = unknown,
@@ -48,6 +93,12 @@ export interface OperationSpec<
   readonly businessInputSchema: Readonly<Record<string, unknown>>;
   readonly requiresProlog: boolean;
   readonly effects: readonly OperationEffect[];
+  /** Generated effect metadata used by MCP annotations and telemetry. */
+  readonly declaredEffects?: readonly OperationEffectDeclaration[];
+  /** Version of the machine-readable result data for this operation. */
+  readonly resultVersion?: string;
+  /** JSON Schema for the machine-readable result data. */
+  readonly outputSchema?: Readonly<Record<string, unknown>>;
   readonly execute: {
     bivarianceHack(
       input: I,
@@ -55,3 +106,13 @@ export interface OperationSpec<
     ): Promise<OperationResult<O>>;
   }["bivarianceHack"];
 }
+
+/** A catalog spec after its generated machine contract has been attached. */
+export type ResolvedOperationSpec<
+  I = Readonly<Record<string, unknown>>,
+  O = unknown,
+> = OperationSpec<I, O> & {
+  readonly declaredEffects: readonly OperationEffectDeclaration[];
+  readonly resultVersion: string;
+  readonly outputSchema: Readonly<Record<string, unknown>>;
+};

package/src/public/proof-fingerprint.ts

@@ -0,0 +1,216 @@
+import { createHash } from "node:crypto";
+
+import type {
+  ProofBinding,
+  ProofContract,
+  ProofEnvironment,
+} from "./proof-protocol.js";
+
+/** Cosmetic integration-config keys that never participate in proof identity. */
+const COSMETIC_KEYS = new Set([
+  "description",
+  "label",
+  "labels",
+  "comment",
+  "comments",
+  "displayName",
+  "display_name",
+  "docs",
+  "notes",
+]);
+
+export function stripCosmetic(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(stripCosmetic);
+  if (value !== null && typeof value === "object") {
+    const source = value as Record<string, unknown>;
+    const result: Record<string, unknown> = {};
+    for (const key of Object.keys(source).sort()) {
+      if (COSMETIC_KEYS.has(key)) continue;
+      result[key] = stripCosmetic(source[key]);
+    }
+    return result;
+  }
+  return value;
+}
+
+export function canonicalJson(value: unknown): string {
+  if (value === undefined) return "null";
+  if (Array.isArray(value)) {
+    return `[${value.map(canonicalJson).join(",")}]`;
+  }
+  if (value !== null && typeof value === "object") {
+    return `{${Object.entries(value)
+      .sort(([left], [right]) => left.localeCompare(right))
+      .map(([key, child]) => `${JSON.stringify(key)}:${canonicalJson(child)}`)
+      .join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+
+function sha256(value: string): string {
+  return createHash("sha256").update(value).digest("hex");
+}
+
+export function jsonDigest(value: unknown): string {
+  return sha256(canonicalJson(value));
+}
+
+/** Kibi canonicalizes the typed environment and derives the environment hash itself. */
+export function environmentHash(environment: ProofEnvironment): string {
+  return jsonDigest(stripCosmetic(environment));
+}
+
+export function proofContractHash(contract: ProofContract): string {
+  return jsonDigest(contract);
+}
+
+/**
+ * Per-contract receipt binding: hashes what the receipt's validity actually
+ * depends on — the test's proof contract and the test's authored document
+ * with any receipt block removed — so a receipt stays valid while unrelated
+ * workspace state changes, and goes stale the moment the test's own contract
+ * or document does. Callers pass the receipt-stripped document content.
+ */
+// implements REQ-kibi-proof-evidence-protocol
+export interface ReceiptCodeScopeEntry {
+  readonly symbolId: string;
+  readonly sourceHash: string;
+}
+
+export function receiptBindingHash(
+  contract: ProofContract,
+  receiptStrippedTestDocument: string,
+  codeScope: readonly ReceiptCodeScopeEntry[] = [],
+): string {
+  const scope = codeScope
+    .map((entry) => ({
+      symbolId: entry.symbolId,
+      sourceHash: entry.sourceHash,
+    }))
+    .sort((left, right) => left.symbolId.localeCompare(right.symbolId));
+  return jsonDigest({
+    binding: "kibi.receipt-binding.v1",
+    contract: proofContractHash(contract),
+    testDoc: createHash("sha256")
+      .update(receiptStrippedTestDocument)
+      .digest("hex"),
+    codeScope: scope,
+  });
+}
+
+export type ProofIntegrationExecution = Readonly<{
+  id: string;
+  producer: string;
+  producer_version?: string;
+  command: readonly string[];
+  artifact?: string;
+  targets?: readonly string[];
+  options?: Record<string, unknown>;
+}>;
+
+export type ProofFingerprintComponents = Readonly<{
+  contract: string;
+  integration: string;
+  command: string;
+  bindings: string;
+  producer: string;
+}>;
+
+export type ProofFingerprint = Readonly<{
+  fingerprint: string;
+  components: ProofFingerprintComponents;
+}>;
+
+function integrationExecutionProjection(
+  integration: ProofIntegrationExecution,
+): Record<string, unknown> {
+  return {
+    id: integration.id,
+    producer: integration.producer,
+    ...(integration.producer_version !== undefined
+      ? { producer_version: integration.producer_version }
+      : {}),
+    command: [...integration.command],
+    ...(integration.artifact !== undefined
+      ? { artifact: integration.artifact }
+      : {}),
+    ...(integration.targets !== undefined
+      ? { targets: [...integration.targets] }
+      : {}),
+    ...(integration.options !== undefined
+      ? { options: stripCosmetic(integration.options) }
+      : {}),
+  };
+}
+
+function normalizedBindings(
+  bindings: readonly ProofBinding[],
+): readonly ProofBinding[] {
+  return [...bindings]
+    .map((binding) => ({
+      symbol_id: binding.symbol_id,
+      target: binding.target,
+      ...(binding.native_id !== undefined
+        ? { native_id: binding.native_id }
+        : {}),
+      ...(binding.aliases !== undefined
+        ? { aliases: [...binding.aliases] }
+        : {}),
+      ...(binding.source_file !== undefined
+        ? { source_file: binding.source_file }
+        : {}),
+      ...(binding.line !== undefined ? { line: binding.line } : {}),
+    }))
+    .sort((left, right) =>
+      `${left.target}\0${left.symbol_id}`.localeCompare(
+        `${right.target}\0${right.symbol_id}`,
+      ),
+    );
+}
+
+/**
+ * The effective proof fingerprint binds a receipt to everything that changes
+ * what executes or how evidence maps to obligations: the semantic contract,
+ * the integration's execution semantics, the exact command, and the bindings.
+ * Cosmetic metadata is excluded, so editing a description never stales proof.
+ */
+export function effectiveProofFingerprint(input: {
+  contract: ProofContract;
+  integration: ProofIntegrationExecution;
+  bindings: readonly ProofBinding[];
+}): ProofFingerprint {
+  const integrationProjection = integrationExecutionProjection(
+    input.integration,
+  );
+  const components: ProofFingerprintComponents = {
+    contract: proofContractHash(input.contract),
+    integration: jsonDigest(integrationProjection),
+    command: jsonDigest([...input.integration.command]),
+    bindings: jsonDigest(normalizedBindings(input.bindings)),
+    producer: jsonDigest({
+      producer: input.integration.producer,
+      ...(input.integration.producer_version !== undefined
+        ? { version: input.integration.producer_version }
+        : {}),
+    }),
+  };
+  return { fingerprint: jsonDigest(components), components };
+}
+
+export const FINGERPRINT_COMPONENT_NAMES = [
+  "contract",
+  "integration",
+  "command",
+  "bindings",
+  "producer",
+] as const;
+
+/** Names the fingerprint components that drifted between two executions. */
+export function fingerprintDrift(
+  previous: ProofFingerprintComponents,
+  current: ProofFingerprintComponents,
+): string[] {
+  return FINGERPRINT_COMPONENT_NAMES.filter(
+    (name) => previous[name] !== current[name],
+  );
+}