kibi-cli 0.19.0 → 2.0.0

package/dist/public/operations/specs/upsert.d.ts

@@ -106,7 +106,7 @@ export declare const upsertSpec: {
                     };
                     readonly granularity_reason: {
                         readonly type: "string";
-                        readonly enum: readonly ["config-artifact", "module-level-behavior", "extractor-miss", "legacy-link"];
+                        readonly enum: readonly ["config-artifact", "module-level-behavior", "extractor-miss", "legacy-link", "test-suite"];
                         readonly description: "Optional justification for a coarse file/module-level symbol traceability relationship when narrower function/class/type symbols exist.";
                     };
                     readonly symbol_role: {
@@ -124,30 +124,101 @@ export declare const upsertSpec: {
                         readonly enum: readonly ["internal", "consumer"];
                         readonly description: "Optional typed verification perspective for test entities. Example: 'consumer'.";
                     };
-                    readonly verification_receipts: {
+                    readonly proof_contract: {
+                        readonly description: "Semantic proof contract binding this test to explicit proof obligations executed by one configured integration.";
+                        readonly type: "object";
+                        readonly required: readonly ["version", "integration", "required_proofs", "success_policy"];
+                        readonly properties: {
+                            readonly version: {
+                                readonly type: "string";
+                                readonly const: "kibi.proof-contract.v1";
+                            };
+                            readonly integration: {
+                                readonly type: "string";
+                                readonly minLength: 1;
+                            };
+                            readonly required_proofs: {
+                                readonly type: "array";
+                                readonly minItems: 1;
+                                readonly maxItems: 1000;
+                                readonly items: {
+                                    readonly type: "object";
+                                    readonly required: readonly ["symbol_id", "target"];
+                                    readonly properties: {
+                                        readonly symbol_id: {
+                                            readonly type: "string";
+                                            readonly minLength: 1;
+                                        };
+                                        readonly target: {
+                                            readonly type: "string";
+                                            readonly minLength: 1;
+                                        };
+                                    };
+                                    readonly additionalProperties: false;
+                                };
+                            };
+                            readonly success_policy: {
+                                readonly type: "string";
+                                readonly enum: readonly ["all_required_first_attempt"];
+                            };
+                        };
+                        readonly additionalProperties: false;
+                    };
+                    readonly proof_bindings: {
+                        readonly description: "Optional native-runner bindings (native ids, aliases, source coordinates) for proof obligations. Bindings are provenance metadata and never replace the semantic contract.";
                         readonly type: "array";
-                        readonly maxItems: 50;
                         readonly items: {
                             readonly type: "object";
-                            readonly required: readonly ["version", "receipt_id", "test_id", "runner", "command", "scope", "outcome", "code_snapshot", "environment_hash", "started_at", "finished_at", "artifact_digest"];
+                            readonly required: readonly ["symbol_id", "target"];
                             readonly properties: {
-                                readonly version: {
+                                readonly symbol_id: {
                                     readonly type: "string";
-                                    readonly const: "kibi.verification-receipt.v1";
+                                    readonly minLength: 1;
                                 };
-                                readonly receipt_id: {
+                                readonly target: {
                                     readonly type: "string";
-                                    readonly pattern: "^VR-[A-Za-z0-9][A-Za-z0-9._:-]{7,127}$";
+                                    readonly minLength: 1;
                                 };
-                                readonly test_id: {
+                                readonly native_id: {
                                     readonly type: "string";
                                     readonly minLength: 1;
                                 };
-                                readonly runner: {
+                                readonly aliases: {
+                                    readonly type: "array";
+                                    readonly items: {
+                                        readonly type: "string";
+                                        readonly minLength: 1;
+                                    };
+                                };
+                                readonly source_file: {
                                     readonly type: "string";
                                     readonly minLength: 1;
                                 };
-                                readonly command: {
+                                readonly line: {
+                                    readonly type: "integer";
+                                    readonly minimum: 1;
+                                };
+                            };
+                            readonly additionalProperties: false;
+                        };
+                    };
+                    readonly proof_receipts: {
+                        readonly type: "array";
+                        readonly maxItems: 50;
+                        readonly items: {
+                            readonly type: "object";
+                            readonly description: "Kibi-derived kibi.proof-receipt.v1. Receipts are never caller-authored; kb_ingest_proof derives them from kibi.proof-run.v1 artifacts.";
+                            readonly required: readonly ["version", "receipt_id", "test_id", "scope", "outcome", "code_snapshot", "environment_hash", "started_at", "finished_at", "artifact_digest", "contract_hash", "fingerprint", "fingerprint_components", "integration_id", "producer", "command_argv", "run_outcome", "proof_results"];
+                            readonly properties: {
+                                readonly version: {
+                                    readonly type: "string";
+                                    readonly const: "kibi.proof-receipt.v1";
+                                };
+                                readonly receipt_id: {
+                                    readonly type: "string";
+                                    readonly pattern: "^PR-[A-Za-z0-9][A-Za-z0-9._:-]{7,127}$";
+                                };
+                                readonly test_id: {
                                     readonly type: "string";
                                     readonly minLength: 1;
                                 };
@@ -157,7 +228,7 @@ export declare const upsertSpec: {
                                 };
                                 readonly outcome: {
                                     readonly type: "string";
-                                    readonly enum: readonly ["passed", "failed", "errored", "cancelled", "skipped"];
+                                    readonly enum: readonly ["passed", "failed", "errored", "cancelled", "skipped", "timed_out", "interrupted"];
                                 };
                                 readonly code_snapshot: {
                                     readonly type: "string";
@@ -179,10 +250,176 @@ export declare const upsertSpec: {
                                     readonly type: "string";
                                     readonly pattern: "^[a-f0-9]{64}$";
                                 };
+                                readonly contract_hash: {
+                                    readonly type: "string";
+                                    readonly pattern: "^[a-f0-9]{64}$";
+                                };
+                                readonly binding_hash: {
+                                    readonly type: "string";
+                                    readonly pattern: "^[a-f0-9]{64}$";
+                                };
+                                readonly fingerprint: {
+                                    readonly type: "string";
+                                    readonly pattern: "^[a-f0-9]{64}$";
+                                };
+                                readonly fingerprint_components: {
+                                    readonly type: "object";
+                                    readonly required: readonly ["contract", "integration", "command", "bindings", "producer"];
+                                    readonly additionalProperties: false;
+                                    readonly properties: {
+                                        readonly contract: {
+                                            readonly type: "string";
+                                            readonly pattern: "^[a-f0-9]{64}$";
+                                        };
+                                        readonly integration: {
+                                            readonly type: "string";
+                                            readonly pattern: "^[a-f0-9]{64}$";
+                                        };
+                                        readonly command: {
+                                            readonly type: "string";
+                                            readonly pattern: "^[a-f0-9]{64}$";
+                                        };
+                                        readonly bindings: {
+                                            readonly type: "string";
+                                            readonly pattern: "^[a-f0-9]{64}$";
+                                        };
+                                        readonly producer: {
+                                            readonly type: "string";
+                                            readonly pattern: "^[a-f0-9]{64}$";
+                                        };
+                                    };
+                                };
+                                readonly integration_id: {
+                                    readonly type: "string";
+                                    readonly minLength: 1;
+                                };
+                                readonly producer: {
+                                    readonly type: "object";
+                                    readonly required: readonly ["name"];
+                                    readonly properties: {
+                                        readonly name: {
+                                            readonly type: "string";
+                                            readonly minLength: 1;
+                                        };
+                                        readonly version: {
+                                            readonly type: "string";
+                                            readonly minLength: 1;
+                                        };
+                                    };
+                                    readonly additionalProperties: false;
+                                };
+                                readonly command_argv: {
+                                    readonly type: "array";
+                                    readonly minItems: 1;
+                                    readonly items: {
+                                        readonly type: "string";
+                                        readonly minLength: 1;
+                                    };
+                                };
+                                readonly run_outcome: {
+                                    readonly type: "string";
+                                    readonly enum: readonly ["passed", "failed", "errored", "cancelled", "timed_out", "interrupted", "no_results"];
+                                };
+                                readonly proof_results: {
+                                    readonly type: "array";
+                                    readonly minItems: 0;
+                                    readonly maxItems: 1000;
+                                    readonly items: {
+                                        readonly type: "object";
+                                        readonly required: readonly ["symbol_id", "target", "outcome", "binding", "attempts"];
+                                        readonly properties: {
+                                            readonly symbol_id: {
+                                                readonly type: "string";
+                                                readonly minLength: 1;
+                                            };
+                                            readonly target: {
+                                                readonly type: "string";
+                                                readonly minLength: 1;
+                                            };
+                                            readonly outcome: {
+                                                readonly type: "string";
+                                                readonly enum: readonly ["passed", "failed", "timed_out", "skipped", "interrupted", "errored"];
+                                            };
+                                            readonly binding: {
+                                                readonly type: "string";
+                                                readonly enum: readonly ["native_case", "aggregate_run"];
+                                            };
+                                            readonly native_id: {
+                                                readonly type: "string";
+                                                readonly minLength: 1;
+                                            };
+                                            readonly attempts: {
+                                                readonly oneOf: readonly [{
+                                                    readonly type: "object";
+                                                    readonly required: readonly ["status", "entries"];
+                                                    readonly properties: {
+                                                        readonly status: {
+                                                            readonly type: "string";
+                                                            readonly const: "complete";
+                                                        };
+                                                        readonly entries: {
+                                                            readonly type: "array";
+                                                            readonly minItems: 1;
+                                                            readonly items: {
+                                                                readonly type: "object";
+                                                                readonly required: readonly ["outcome"];
+                                                                readonly properties: {
+                                                                    readonly outcome: {
+                                                                        readonly type: "string";
+                                                                        readonly enum: readonly ["passed", "failed", "timed_out", "skipped", "interrupted", "errored"];
+                                                                    };
+                                                                    readonly duration_ms: {
+                                                                        readonly type: "number";
+                                                                        readonly minimum: 0;
+                                                                    };
+                                                                };
+                                                                readonly additionalProperties: false;
+                                                            };
+                                                        };
+                                                    };
+                                                    readonly additionalProperties: false;
+                                                }, {
+                                                    readonly type: "object";
+                                                    readonly required: readonly ["status"];
+                                                    readonly properties: {
+                                                        readonly status: {
+                                                            readonly type: "string";
+                                                            readonly const: "unavailable";
+                                                        };
+                                                    };
+                                                    readonly additionalProperties: false;
+                                                }];
+                                            };
+                                        };
+                                        readonly additionalProperties: false;
+                                    };
+                                };
+                                readonly gaps: {
+                                    readonly type: "array";
+                                    readonly items: {
+                                        readonly type: "object";
+                                        readonly required: readonly ["symbol_id", "target", "reason"];
+                                        readonly properties: {
+                                            readonly symbol_id: {
+                                                readonly type: "string";
+                                                readonly minLength: 1;
+                                            };
+                                            readonly target: {
+                                                readonly type: "string";
+                                                readonly minLength: 1;
+                                            };
+                                            readonly reason: {
+                                                readonly type: "string";
+                                                readonly minLength: 1;
+                                            };
+                                        };
+                                        readonly additionalProperties: false;
+                                    };
+                                };
                             };
                             readonly additionalProperties: false;
                         };
-                        readonly description: "Append-only test execution evidence. Proof accepts only the newest valid passed receipt bound to the current code snapshot and within the seven-day freshness window.";
+                        readonly description: "Append-only proof evidence. Proof accepts only the newest valid passed receipt bound to the current code snapshot, current contract hash, and effective execution fingerprint within the seven-day freshness window. Ingest rotates the oldest entries at the cap.";
                     };
                     readonly fact_kind: {
                         readonly type: "string";
@@ -346,7 +583,7 @@ export declare const upsertSpec: {
                 };
                 readonly allOf: readonly [Record<string, unknown>, {
                     readonly if: {
-                        readonly required: readonly ["verification_receipts"];
+                        readonly required: readonly ["proof_receipts"];
                     };
                     readonly then: {
                         readonly required: readonly ["verification_scope"];
@@ -377,6 +614,20 @@ export declare const upsertSpec: {
                     };
                 };
             };
+            readonly document: {
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly description: "Optional source-first document write. Paths are workspace-relative; omit body when updating to preserve the existing body bytes.";
+                readonly properties: {
+                    readonly path: {
+                        readonly type: "string";
+                        readonly minLength: 1;
+                    };
+                    readonly body: {
+                        readonly type: "string";
+                    };
+                };
+            };
         };
     };
     readonly requiresProlog: true;

package/dist/public/operations/specs/upsert.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"upsert.d.ts","sourceRoot":"","sources":["../../../../src/public/operations/specs/upsert.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,aAAa,EAAE,MAAM,wCAAwC,CAAC;AAQvE,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2BuC,CAAC"}
+{"version":3,"file":"upsert.d.ts","sourceRoot":"","sources":["../../../../src/public/operations/specs/upsert.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,aAAa,EAAE,MAAM,wCAAwC,CAAC;AAQvE,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAqCuC,CAAC"}

package/dist/public/operations/specs/upsert.js

@@ -19,6 +19,15 @@ export const upsertSpec = {
             },
             properties: ENTITY_PROPERTIES_SCHEMA,
             relationships: RELATIONSHIPS_SCHEMA,
+            document: {
+                type: "object",
+                additionalProperties: false,
+                description: "Optional source-first document write. Paths are workspace-relative; omit body when updating to preserve the existing body bytes.",
+                properties: {
+                    path: { type: "string", minLength: 1 },
+                    body: { type: "string" },
+                },
+            },
         },
     },
     requiresProlog: true,

package/dist/public/operations/symbol-repair-plan.d.ts

@@ -0,0 +1,22 @@
+import type { OperationContext } from "./runtime-types.js";
+export declare const SYMBOL_REPAIR_PLAN_VERSION: "kibi.symbol-repair-plan.v1";
+export type SymbolRepairPlan = Readonly<{
+    version: typeof SYMBOL_REPAIR_PLAN_VERSION;
+    readOnly: true;
+    autoApplicable: false;
+    repairs: readonly Readonly<Record<string, unknown>>[];
+}>;
+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 declare function inspectCoordinateRepairs(symbols: readonly Readonly<Record<string, unknown>>[], workspaceRoot: string): Promise<Map<string, CoordinateRepairEvidence>>;
+/** Attach current extraction evidence before constructing requirement repairs. */
+export declare function addCoordinateRepairEvidence(rows: readonly Readonly<Record<string, unknown>>[], context: OperationContext): Promise<readonly Readonly<Record<string, unknown>>[]>;
+/** Build review-only, evidence-backed symbol recovery suggestions. */
+export declare function buildSymbolRepairPlan(rows: readonly Readonly<Record<string, unknown>>[], context: OperationContext): Promise<SymbolRepairPlan | undefined>;
+//# sourceMappingURL=symbol-repair-plan.d.ts.map

package/dist/public/operations/symbol-repair-plan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"symbol-repair-plan.d.ts","sourceRoot":"","sources":["../../../src/public/operations/symbol-repair-plan.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAE3D,eAAO,MAAM,0BAA0B,EAAG,4BAAqC,CAAC;AAEhF,MAAM,MAAM,gBAAgB,GAAG,QAAQ,CAAC;IACtC,OAAO,EAAE,OAAO,0BAA0B,CAAC;IAC3C,QAAQ,EAAE,IAAI,CAAC;IACf,cAAc,EAAE,KAAK,CAAC;IACtB,OAAO,EAAE,SAAS,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EAAE,CAAC;CACvD,CAAC,CAAC;AAoBH,MAAM,MAAM,wBAAwB,GAAG,QAAQ,CAAC;IAC9C,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,WAAW,EAAE,OAAO,CAAC;IACrB,MAAM,EACF,aAAa,GACb,eAAe,GACf,gBAAgB,GAChB,oBAAoB,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC,CAAC;AAEH,gFAAgF;AAChF,wBAAsB,wBAAwB,CAC5C,OAAO,EAAE,SAAS,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EAAE,EACrD,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,wBAAwB,CAAC,CAAC,CA2DhD;AAED,kFAAkF;AAClF,wBAAsB,2BAA2B,CAC/C,IAAI,EAAE,SAAS,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EAAE,EAClD,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,SAAS,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EAAE,CAAC,CA+DvD;AAwCD,sEAAsE;AACtE,wBAAsB,qBAAqB,CACzC,IAAI,EAAE,SAAS,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EAAE,EAClD,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,gBAAgB,GAAG,SAAS,CAAC,CAgGvC"}

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

@@ -0,0 +1,238 @@
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+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) {
+    const value = entity.sourceFile ?? entity.source;
+    return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+function coordinatesPresent(entity) {
+    return [
+        entity.sourceLine,
+        entity.sourceColumn,
+        entity.sourceEndLine,
+        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 : "";
+    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, context) {
+    if (!context.prolog || rows.length === 0)
+        return undefined;
+    const symbols = await loadEntities(context.prolog, { type: "symbol" });
+    const extractedByPath = new Map();
+    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,
+    };
+}