kibi-cli 1.0.1 → 2.1.0

package/dist/public/operations/symbol-repair-plan.js

@@ -1,6 +1,8 @@
 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 { analyzeSourceText, enrichSymbolCoordinates, } from "../../extractors/symbols-coordinator.js";
+import { isCoarseGranularityReason } from "../symbol-granularity.js";
 import { loadEntities } from "./discovery-entities.js";
 export const SYMBOL_REPAIR_PLAN_VERSION = "kibi.symbol-repair-plan.v1";
 function sourceFileOf(entity) {
@@ -15,6 +17,113 @@ function coordinatesPresent(entity) {
         entity.sourceEndColumn,
     ].every((value) => Number.isInteger(value) && Number(value) >= 0);
 }
+/** Preview the same extraction and explicit coarse fallback used by refresh. */
+export async function inspectCoordinateRepairs(symbols, workspaceRoot) {
+    const entries = 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 = 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, context) {
+    const missingByRow = rows.map((row) => {
+        const stages = row.proofStages;
+        const missing = stages?.sourceCoordinates?.missingSymbols;
+        return Array.isArray(missing)
+            ? missing.filter((id) => 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;
+        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, symbols, extractedByPath) {
     const title = typeof entity.title === "string" ? entity.title : "";
     const kind = typeof entity.symbol_kind === "string" ? entity.symbol_kind : "";
@@ -55,16 +164,21 @@ export async function buildSymbolRepairPlan(rows, context) {
         if (!existsSync(absolute))
             continue;
         try {
-            const analysis = analyzeSourceText(absolute, readFileSync(absolute, "utf8"));
+            const content = readFileSync(absolute, "utf8");
+            // Coverage/impact is a maintenance path: never import project plugins.
+            const analysis = analyzeSourceText(absolute, content);
+            if (analysis.providerId === null)
+                continue;
             extractedByPath.set(source, analysis.symbols.map((candidate) => ({
                 name: candidate.name,
                 kind: candidate.kind,
             })));
         }
         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 [];
@@ -92,7 +206,9 @@ export async function buildSymbolRepairPlan(rows, context) {
             : 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";
@@ -110,6 +226,7 @@ export async function buildSymbolRepairPlan(rows, context) {
                         ? extractedByPath.has(source)
                         : false,
                     autoApply: false,
+                    coordinateRepair: coordinateEvidence.get(String(entity.id)),
                 },
             },
         ];

package/dist/public/operations/types.d.ts

@@ -1,6 +1,6 @@
 import type { OperationContext } from "./runtime-types.js";
 export type { OperationContext };
-export type OperationName = "kb_query" | "kb_search" | "kb_status" | "kb_skills_list" | "kb_skills_load" | "kb_skills_read" | "kb_find_gaps" | "kb_coverage" | "kb_graph" | "kb_sparql_remote" | "kb_semantic_advisor" | "kb_upsert" | "kb_validate_upsert" | "kb_delete" | "kb_check" | "kb_model_requirement" | "kb_suggest_predicates" | "kb_plan_bootstrap" | "kb_compile_intent" | "kb_apply_plan" | "kb_ingest_verification";
+export type OperationName = "kb_query" | "kb_search" | "kb_status" | "kb_skills_list" | "kb_skills_load" | "kb_skills_read" | "kb_find_gaps" | "kb_coverage" | "kb_graph" | "kb_sparql_remote" | "kb_semantic_advisor" | "kb_upsert" | "kb_validate_upsert" | "kb_delete" | "kb_check" | "kb_model_requirement" | "kb_suggest_predicates" | "kb_plan_bootstrap" | "kb_compile_intent" | "kb_apply_plan" | "kb_ingest_proof";
 export type OperationEffect = "local-read" | "kb-read" | "workspace-read" | "network-read" | "kb-write" | "workspace-write";
 export type OperationEffectDeclaration = Readonly<{
     kind: OperationEffect;
@@ -56,6 +56,11 @@ export interface OperationSpec<I = Readonly<Record<string, unknown>>, O = unknow
     readonly businessInputSchema: Readonly<Record<string, unknown>>;
     readonly requiresProlog: boolean;
     readonly effects: readonly OperationEffect[];
+    /**
+     * When true, MCP duplicates envelope `data` into tool `content` text so hosts
+     * that hide `structuredContent` still expose discovery/proof payloads.
+     */
+    readonly agentVisibleStructuredData?: boolean;
     /** Generated effect metadata used by MCP annotations and telemetry. */
     readonly declaredEffects?: readonly OperationEffectDeclaration[];
     /** Version of the machine-readable result data for this operation. */

package/dist/public/operations/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/public/operations/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/public/operations/types.ts"],"names":[],"mappings":"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"}

package/dist/public/proof-fingerprint.d.ts

@@ -0,0 +1,54 @@
+import type { ProofBinding, ProofContract, ProofEnvironment } from "./proof-protocol.js";
+export declare function stripCosmetic(value: unknown): unknown;
+export declare function canonicalJson(value: unknown): string;
+export declare function jsonDigest(value: unknown): string;
+/** Kibi canonicalizes the typed environment and derives the environment hash itself. */
+export declare function environmentHash(environment: ProofEnvironment): string;
+export declare function proofContractHash(contract: ProofContract): string;
+/**
+ * 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.
+ */
+export interface ReceiptCodeScopeEntry {
+    readonly symbolId: string;
+    readonly sourceHash: string;
+}
+export declare function receiptBindingHash(contract: ProofContract, receiptStrippedTestDocument: string, codeScope?: readonly ReceiptCodeScopeEntry[]): string;
+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;
+}>;
+/**
+ * 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 declare function effectiveProofFingerprint(input: {
+    contract: ProofContract;
+    integration: ProofIntegrationExecution;
+    bindings: readonly ProofBinding[];
+}): ProofFingerprint;
+export declare const FINGERPRINT_COMPONENT_NAMES: readonly ["contract", "integration", "command", "bindings", "producer"];
+/** Names the fingerprint components that drifted between two executions. */
+export declare function fingerprintDrift(previous: ProofFingerprintComponents, current: ProofFingerprintComponents): string[];
+//# sourceMappingURL=proof-fingerprint.d.ts.map

package/dist/public/proof-fingerprint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"proof-fingerprint.d.ts","sourceRoot":"","sources":["../../src/public/proof-fingerprint.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,YAAY,EACZ,aAAa,EACb,gBAAgB,EACjB,MAAM,qBAAqB,CAAC;AAe7B,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAYrD;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAYpD;AAMD,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAEjD;AAED,wFAAwF;AACxF,wBAAgB,eAAe,CAAC,WAAW,EAAE,gBAAgB,GAAG,MAAM,CAErE;AAED,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,aAAa,GAAG,MAAM,CAEjE;AAED;;;;;;GAMG;AAEH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,aAAa,EACvB,2BAA2B,EAAE,MAAM,EACnC,SAAS,GAAE,SAAS,qBAAqB,EAAO,GAC/C,MAAM,CAeR;AAED,MAAM,MAAM,yBAAyB,GAAG,QAAQ,CAAC;IAC/C,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC,CAAC,CAAC;AAEH,MAAM,MAAM,0BAA0B,GAAG,QAAQ,CAAC;IAChD,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC,CAAC;AAEH,MAAM,MAAM,gBAAgB,GAAG,QAAQ,CAAC;IACtC,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,0BAA0B,CAAC;CACxC,CAAC,CAAC;AAiDH;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE;IAC/C,QAAQ,EAAE,aAAa,CAAC;IACxB,WAAW,EAAE,yBAAyB,CAAC;IACvC,QAAQ,EAAE,SAAS,YAAY,EAAE,CAAC;CACnC,GAAG,gBAAgB,CAiBnB;AAED,eAAO,MAAM,2BAA2B,yEAM9B,CAAC;AAEX,4EAA4E;AAC5E,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,0BAA0B,EACpC,OAAO,EAAE,0BAA0B,GAClC,MAAM,EAAE,CAIV"}

package/dist/public/proof-fingerprint.js

@@ -0,0 +1,141 @@
+import { createHash } from "node:crypto";
+/** 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) {
+    if (Array.isArray(value))
+        return value.map(stripCosmetic);
+    if (value !== null && typeof value === "object") {
+        const source = value;
+        const result = {};
+        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) {
+    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) {
+    return createHash("sha256").update(value).digest("hex");
+}
+export function jsonDigest(value) {
+    return sha256(canonicalJson(value));
+}
+/** Kibi canonicalizes the typed environment and derives the environment hash itself. */
+export function environmentHash(environment) {
+    return jsonDigest(stripCosmetic(environment));
+}
+export function proofContractHash(contract) {
+    return jsonDigest(contract);
+}
+export function receiptBindingHash(contract, receiptStrippedTestDocument, codeScope = []) {
+    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,
+    });
+}
+function integrationExecutionProjection(integration) {
+    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) {
+    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) {
+    const integrationProjection = integrationExecutionProjection(input.integration);
+    const components = {
+        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",
+];
+/** Names the fingerprint components that drifted between two executions. */
+export function fingerprintDrift(previous, current) {
+    return FINGERPRINT_COMPONENT_NAMES.filter((name) => previous[name] !== current[name]);
+}