kibi-cli 1.0.1 → 2.0.0

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

@@ -1,6 +1,12 @@
 import { existsSync, readFileSync } from "node:fs";
 import path from "node:path";
-import { analyzeSourceText } from "../../extractors/symbols-coordinator.js";
+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";
 
@@ -31,6 +37,152 @@ function coordinatesPresent(
   ].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>>[],
@@ -92,6 +244,7 @@ export async function buildSymbolRepairPlan(
         absolute,
         readFileSync(absolute, "utf8"),
       );
+      if (analysis.providerId === null) continue;
       extractedByPath.set(
         source,
         analysis.symbols.map((candidate) => ({
@@ -100,10 +253,14 @@ export async function buildSymbolRepairPlan(
         })),
       );
     } catch {
-      extractedByPath.set(source, []);
+      // 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);
@@ -133,7 +290,9 @@ export async function buildSymbolRepairPlan(
       : extractionProvesAbsent && entity.symbol_origin === "extracted"
         ? "delete_obsolete_symbol"
         : !coordinatesPresent(entity)
-          ? "refresh_coordinates"
+          ? coordinateEvidence.get(String(entity.id))?.refreshable === true
+            ? "refresh_coordinates"
+            : "review"
           : candidates.length > 0
             ? "remap"
             : "review";
@@ -151,6 +310,7 @@ export async function buildSymbolRepairPlan(
             ? extractedByPath.has(source)
             : false,
           autoApply: false,
+          coordinateRepair: coordinateEvidence.get(String(entity.id)),
         },
       },
     ];

package/src/public/operations/types.ts

@@ -21,7 +21,7 @@ export type OperationName =
   | "kb_plan_bootstrap"
   | "kb_compile_intent"
   | "kb_apply_plan"
-  | "kb_ingest_verification";
+  | "kb_ingest_proof";
 
 export type OperationEffect =
   | "local-read"

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],
+  );
+}

package/src/public/proof-protocol-types.d.ts

@@ -0,0 +1,96 @@
+// implements REQ-kibi-proof-evidence-protocol
+export type ProofRunOutcome =
+  | "passed"
+  | "failed"
+  | "errored"
+  | "cancelled"
+  | "timed_out"
+  | "interrupted"
+  | "no_results";
+
+export type ProofResultOutcome =
+  | "passed"
+  | "failed"
+  | "timed_out"
+  | "skipped"
+  | "interrupted"
+  | "errored";
+
+export type ProofBindingKind = "native_case" | "aggregate_run";
+export type AttemptsStatus = "complete" | "unavailable";
+export type RunFailurePhase =
+  | "setup"
+  | "collection"
+  | "execution"
+  | "teardown"
+  | "infrastructure";
+export type SuccessPolicy = "all_required_first_attempt";
+
+export type ProofAttempt = Readonly<{
+  outcome: ProofResultOutcome;
+  duration_ms?: number;
+}>;
+
+export type ProofAttempts = Readonly<
+  | { status: "complete"; entries: readonly ProofAttempt[] }
+  | { status: "unavailable" }
+>;
+
+export type ProofResult = Readonly<{
+  symbol_id: string;
+  target: string;
+  outcome: ProofResultOutcome;
+  binding: ProofBindingKind;
+  native_id?: string;
+  attempts: ProofAttempts;
+  diagnostics?: readonly string[];
+}>;
+
+export type ProducerProvenance = Readonly<{
+  name: string;
+  version?: string;
+}>;
+
+export type ProofEnvironment = Readonly<Record<string, unknown>>;
+
+export type ProofRun = Readonly<{
+  outcome: ProofRunOutcome;
+  exit_code: number;
+  started_at: string;
+  finished_at: string;
+  failure_phase?: RunFailurePhase;
+}>;
+
+export type ProofRunArtifact = Readonly<{
+  version: "kibi.proof-run.v1";
+  producer: ProducerProvenance;
+  executor?: ProducerProvenance;
+  command_argv: readonly string[];
+  code_snapshot: string;
+  environment: ProofEnvironment;
+  run: ProofRun;
+  proof_results: readonly ProofResult[];
+  integration?: string;
+  diagnostics?: readonly string[];
+}>;
+
+export type ProofObligation = Readonly<{
+  symbol_id: string;
+  target: string;
+}>;
+
+export type ProofContract = Readonly<{
+  version: "kibi.proof-contract.v1";
+  integration: string;
+  required_proofs: readonly ProofObligation[];
+  success_policy: SuccessPolicy;
+}>;
+
+export type ProofBinding = Readonly<{
+  symbol_id: string;
+  target: string;
+  native_id?: string;
+  aliases?: readonly string[];
+  source_file?: string;
+  line?: number;
+}>;