kibi-cli 0.19.0 → 2.0.0

package/dist/commands/sync/manifest.js

@@ -15,12 +15,12 @@
  You should have received a copy of the GNU Affero General Public License
  along with this program.  If not, see <https://www.gnu.org/licenses/>.
 */
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, readFileSync, renameSync, unlinkSync, writeFileSync, } from "node:fs";
 import * as path from "node:path";
 import { dump as dumpYAML, load as parseYAML } from "js-yaml";
-import { writeCoordinateArtifact, } from "../../extractors/symbol-coordinates.js";
+import { coarseCoordinateSpan, coordinateIdentityHash, coordinateSourceHash, parseCoordinateArtifact, writeCoordinateArtifact, } from "../../extractors/symbol-coordinates.js";
 import { enrichSymbolCoordinates, } from "../../extractors/symbols-coordinator.js";
-import { COARSE_GRANULARITY_REASONS, isCoarseGranularityReason, } from "../../public/symbol-granularity.js";
+import { COARSE_GRANULARITY_REASONS, COARSE_GRANULARITY_REASONS_PARENTHESIZED, isCoarseGranularityReason, } from "../../public/symbol-granularity.js";
 import { resolveSymbolsManifestPaths } from "../../utils/manifest-paths.js";
 function resolveDeps(overrides) {
     return {
@@ -29,6 +29,8 @@ function resolveDeps(overrides) {
         existsSync,
         parseYAML,
         readFileSync,
+        renameSync,
+        unlinkSync,
         writeFileSync,
         writeCoordinateArtifact,
         resolveSymbolsManifestPaths,
@@ -40,17 +42,16 @@ export const SYMBOLS_MANIFEST_COMMENT_BLOCK = `# symbols.yaml
 #   id, title, sourceFile, links, status, tags, owner, priority
 # Generated coordinates are stored separately in symbol-coordinates.yaml.
 # Run \`kibi sync --refresh-symbol-coordinates\` to refresh them.
+#
+# Coordinate refresh granularity gate:
+#   The AST extractor locates per-declaration spans for code files. When it
+#   cannot find a declaration, a title-match or whole-file coarse span is
+#   published ONLY for symbols that declare a coarse granularity_reason
+#   (${COARSE_GRANULARITY_REASONS.join(", ")}).
+#   A symbol without granularity_reason whose extraction misses gets no
+#   coordinate entry at all and is reported as failed; add symbol_role and
+#   granularity_reason to opt it into the coarse fallback.
 `;
-const SYMBOL_COORD_EXTENSIONS = new Set([
-    ".ts",
-    ".tsx",
-    ".js",
-    ".jsx",
-    ".mts",
-    ".cts",
-    ".mjs",
-    ".cjs",
-]);
 const GENERATED_COORD_FIELDS = [
     "sourceLine",
     "sourceColumn",
@@ -62,19 +63,107 @@ const GENERATED_MANIFEST_FIELDS = new Set([
     "coordinatesGeneratedAt",
 ]);
 /**
- * Coarse symbol anchors for which per-symbol coordinates are not expected.
+ * Coarse symbol anchors for which AST per-declaration coordinates are not
+ * expected.
  *
  * Test-suite, module-level-behavior, and config-artifact symbols represent a
  * whole file or configuration unit, and `extractor-miss` explicitly documents
- * that the extractor cannot locate a declaration. These entries legitimately
- * carry no generated coordinates, so coordinate refresh counts them as
- * unchanged instead of flagging them as failures.
+ * that the extractor cannot locate a declaration. Refresh still counts those
+ * entries as unchanged instead of failures, but it persists title-match or
+ * whole-file coordinates so proof-bearing executable symbols can resolve.
  */
 export { COARSE_GRANULARITY_REASONS };
 export function isCoarseGranularityAnchor(entry) {
     const reason = entry.granularity_reason;
     return isCoarseGranularityReason(reason);
 }
+function extractedCoordinates(entry) {
+    const { sourceFile, sourceLine, sourceColumn, sourceEndLine, sourceEndColumn, } = entry;
+    return typeof sourceFile === "string" &&
+        typeof sourceLine === "number" &&
+        typeof sourceColumn === "number" &&
+        typeof sourceEndLine === "number" &&
+        typeof sourceEndColumn === "number"
+        ? {
+            sourceFile,
+            sourceLine,
+            sourceColumn,
+            sourceEndLine,
+            sourceEndColumn,
+        }
+        : null;
+}
+function readSourceText(sourceFile, workspaceRoot, deps) {
+    const absolute = path.isAbsolute(sourceFile)
+        ? sourceFile
+        : path.resolve(workspaceRoot, sourceFile);
+    if (!deps.existsSync(absolute))
+        return null;
+    try {
+        const content = deps.readFileSync(absolute, "utf8");
+        return typeof content === "string" ? content : null;
+    }
+    catch {
+        return null;
+    }
+}
+function fallbackCoarseCoordinates(entry, workspaceRoot, deps) {
+    if (!isCoarseGranularityAnchor(entry))
+        return null;
+    const sourceFile = typeof entry.sourceFile === "string" ? entry.sourceFile : undefined;
+    const title = typeof entry.title === "string" ? entry.title : "";
+    if (sourceFile === undefined)
+        return null;
+    const content = readSourceText(sourceFile, workspaceRoot, deps);
+    if (content === null)
+        return null;
+    return coarseCoordinateSpan(sourceFile, title, content);
+}
+/** Atomically replace `targetPath` with `content` via temp file + rename. */
+function publishAtomically(targetPath, content, deps) {
+    const temporary = `${targetPath}.kibi-tmp-${process.pid}`;
+    try {
+        deps.writeFileSync(temporary, content, "utf8");
+        deps.renameSync(temporary, targetPath);
+    }
+    catch (error) {
+        try {
+            deps.unlinkSync(temporary);
+        }
+        catch {
+            // Temp cleanup is best effort; the original failure propagates.
+        }
+        throw error;
+    }
+}
+function manifestEntryIdentity(entry) {
+    const title = typeof entry.title === "string" ? entry.title : undefined;
+    const sourceFile = typeof entry.sourceFile === "string" ? entry.sourceFile : undefined;
+    const granularityReason = typeof entry.granularity_reason === "string"
+        ? entry.granularity_reason
+        : undefined;
+    return {
+        id: String(entry.id),
+        ...(title === undefined ? {} : { title }),
+        ...(sourceFile === undefined ? {} : { sourceFile }),
+        ...(granularityReason === undefined
+            ? {}
+            : { granularity_reason: granularityReason }),
+    };
+}
+/**
+ * Typed reason an eligible (code-file) symbol still has no coordinates after
+ * enrichment: the AST extractor missed and the symbol either lacks a coarse
+ * granularity_reason (so the whole-file fallback is gated off) or the
+ * fallback itself produced no span.
+ */
+function coarseAnchorFailureReason(entry) {
+    const reason = entry.granularity_reason;
+    if (!isCoarseGranularityReason(reason)) {
+        return `extractor produced no coordinates; add symbol_role and granularity_reason ${COARSE_GRANULARITY_REASONS_PARENTHESIZED} to enable the whole-file coarse fallback`;
+    }
+    return "extractor produced no coordinates and the whole-file coarse fallback found no span for this symbol";
+}
 export async function refreshManifestCoordinates(
 // implements REQ-003
 manifestPath, workspaceRoot, deps) {
@@ -83,56 +172,60 @@ manifestPath, workspaceRoot, deps) {
     const rawContent = resolved.readFileSync(manifestPath, "utf8");
     const parsed = resolved.parseYAML(rawContent);
     if (!isRecord(parsed)) {
-        console.warn(`Warning: symbols manifest ${manifestPath} is not a YAML object; skipping coordinate refresh`);
-        return;
+        throw new Error(`symbols manifest ${manifestPath} is not a YAML object; refusing coordinate refresh`);
     }
     const rawSymbols = parsed.symbols;
     if (!Array.isArray(rawSymbols)) {
-        console.warn(`Warning: symbols manifest ${manifestPath} has no symbols array; skipping coordinate refresh`);
-        return;
+        throw new Error(`symbols manifest ${manifestPath} has no symbols array; refusing coordinate refresh`);
     }
     const before = rawSymbols.map((entry) => isRecord(entry)
         ? { ...entry }
         : {});
-    const enriched = await resolved.enrichSymbolCoordinates(before, workspaceRoot);
-    // Build coordinates map keyed by symbol id
-    const coordinatesMap = {};
-    for (const entry of enriched) {
-        const id = typeof entry?.id === "string" ? entry.id : undefined;
-        if (!id)
-            continue;
-        if (typeof entry.sourceFile === "string" &&
-            typeof entry.sourceLine === "number" &&
-            typeof entry.sourceColumn === "number" &&
-            typeof entry.sourceEndLine === "number" &&
-            typeof entry.sourceEndColumn === "number") {
-            coordinatesMap[id] = {
-                sourceFile: entry.sourceFile,
-                sourceLine: entry.sourceLine,
-                sourceColumn: entry.sourceColumn,
-                sourceEndLine: entry.sourceEndLine,
-                sourceEndColumn: entry.sourceEndColumn,
-            };
+    let coordinatesPath = null;
+    if (shouldRefreshCoordinates) {
+        coordinatesPath =
+            resolved.resolveSymbolsManifestPaths(workspaceRoot).coordinatesPath;
+        if (resolved.existsSync(coordinatesPath)) {
+            const existing = parseCoordinateArtifact(String(resolved.readFileSync(coordinatesPath, "utf8")));
+            if (existing.status === "invalid") {
+                throw new Error(`Failed to parse coordinate artifact ${coordinatesPath}: ${existing.reason}`);
+            }
         }
     }
-    // Optionally write the coordinate artifact to the coordinates path when explicitly requested
+    const enriched = await resolved.enrichSymbolCoordinates(before, workspaceRoot);
+    // Publish the generated coordinate artifact when explicitly requested.
+    // Parse and I/O failures are fatal so sync never advances cache state on a
+    // partially published compiler dependency. Symbols without extractable
+    // coordinates stay absent from the artifact; coverage keeps their gap visible.
+    let refreshedArtifactBytes = null;
     if (shouldRefreshCoordinates) {
-        try {
-            const coordinatesPath = resolved.resolveSymbolsManifestPaths(workspaceRoot).coordinatesPath;
-            const artifactContent = resolved.writeCoordinateArtifact(coordinatesMap);
-            resolved.writeFileSync(coordinatesPath, artifactContent, "utf8");
-        }
-        catch (err) {
-            console.warn(`Warning: Failed to write symbol-coordinates artifact: ${String(err)}`);
+        const boundEntries = {};
+        for (const entry of enriched) {
+            const id = typeof entry?.id === "string" ? entry.id : undefined;
+            if (!id)
+                continue;
+            const span = extractedCoordinates(entry) ??
+                fallbackCoarseCoordinates(entry, workspaceRoot, resolved);
+            if (span === null)
+                continue;
+            const sourceText = readSourceText(span.sourceFile, workspaceRoot, resolved);
+            if (sourceText === null)
+                continue;
+            boundEntries[id] = {
+                ...span,
+                identityHash: coordinateIdentityHash(manifestEntryIdentity(entry)),
+                sourceHash: coordinateSourceHash(sourceText),
+            };
         }
+        refreshedArtifactBytes = resolved.writeCoordinateArtifact(boundEntries);
     }
     // Coordinates belong exclusively to the generated artifact. Always strip
     // them from the authored manifest so consecutive refreshes are idempotent.
     const strippedEnriched = enriched.map((current) => Object.fromEntries(Object.entries(current).filter(([field]) => !GENERATED_MANIFEST_FIELDS.has(field))));
     parsed.symbols = strippedEnriched;
     let refreshed = 0;
-    let failed = 0;
     let unchanged = 0;
+    const failures = [];
     for (let i = 0; i < before.length; i++) {
         const previous = before[i] ?? {};
         const current = enriched[i] ?? previous;
@@ -150,11 +243,13 @@ manifestPath, workspaceRoot, deps) {
                     ? previous.sourceFile
                     : undefined, workspaceRoot, resolved);
         if (eligible && !hasAllGeneratedCoordinates(current)) {
-            failed++;
-        }
-        else {
-            unchanged++;
+            failures.push({
+                id: typeof current.id === "string" ? current.id : `#${i}`,
+                reason: coarseAnchorFailureReason(current),
+            });
+            continue;
         }
+        unchanged++;
     }
     const dumped = resolved.dumpYAML(parsed, {
         lineWidth: -1,
@@ -162,10 +257,51 @@ manifestPath, workspaceRoot, deps) {
         sortKeys: false,
     });
     const nextContent = `${SYMBOLS_MANIFEST_COMMENT_BLOCK}${dumped}`;
-    if (rawContent !== nextContent) {
-        resolved.writeFileSync(manifestPath, nextContent, "utf8");
+    let manifestPublished = false;
+    try {
+        if (rawContent !== nextContent) {
+            publishAtomically(manifestPath, nextContent, resolved);
+            manifestPublished = true;
+        }
+        if (refreshedArtifactBytes !== null && coordinatesPath !== null) {
+            publishAtomically(coordinatesPath, refreshedArtifactBytes, resolved);
+        }
+    }
+    catch (error) {
+        if (manifestPublished) {
+            try {
+                const current = resolved.readFileSync(manifestPath, "utf8");
+                if (current !== nextContent) {
+                    throw new Error(`symbol manifest changed after publication; refusing rollback: ${manifestPath}`);
+                }
+                publishAtomically(manifestPath, rawContent, resolved);
+            }
+            catch (rollbackError) {
+                throw new AggregateError([error, rollbackError], `Coordinate artifact publication failed and manifest rollback failed: ${manifestPath}`);
+            }
+        }
+        throw error;
+    }
+    // The generated coordinates live in the artifact beside the manifest, not
+    // in the authored symbols.yaml this command also rewrites; naming the
+    // artifact keeps diff audits pointed at the file that actually changed.
+    const counts = `(refreshed=${refreshed}, unchanged=${unchanged}, failed=${failures.length})`;
+    if (coordinatesPath !== null) {
+        console.log(`\u2713 Refreshed symbol coordinates in ${path.relative(workspaceRoot, coordinatesPath)} ${counts}`);
+    }
+    else {
+        console.log(`\u2713 Normalized symbol manifest ${path.relative(workspaceRoot, manifestPath)} ${counts}`);
+    }
+    const maxReportedFailures = 10;
+    for (const failure of failures.slice(0, maxReportedFailures)) {
+        console.log(`  failed ${failure.id}: ${failure.reason}`);
+    }
+    if (failures.length > maxReportedFailures) {
+        console.log(`  ... and ${failures.length - maxReportedFailures} more failed symbol(s)`);
+    }
+    if (failures.length > 0) {
+        console.log("  Symbols without a published coordinate entry are dropped from coverage on the next plain sync until they succeed.");
     }
-    console.log(`\u2713 Refreshed symbol coordinates in ${path.relative(workspaceRoot, manifestPath)} (refreshed=${refreshed}, unchanged=${unchanged}, failed=${failed})`);
 }
 export function hasAllGeneratedCoordinates(
 // implements REQ-003
@@ -184,10 +320,9 @@ sourceFile, workspaceRoot, deps) {
     const absolute = path.isAbsolute(sourceFile)
         ? sourceFile
         : path.resolve(workspaceRoot, sourceFile);
-    if (!resolved.existsSync(absolute))
-        return false;
-    const ext = path.extname(absolute).toLowerCase();
-    return SYMBOL_COORD_EXTENSIONS.has(ext);
+    // Non-JS/TS files also undergo coordinate extraction through the text
+    // heuristic. A miss there must be reported just like an AST extraction miss.
+    return resolved.existsSync(absolute);
 }
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);

package/dist/commands/sync/persistence.d.ts

@@ -18,7 +18,10 @@ export declare function persistEntities(prolog: PrologProcess, results: Extracti
     entityCount: number;
     kbModified: boolean;
 }>;
-export declare function persistRelationships(prolog: PrologProcess, results: ExtractionResult[], shardRelationships: ExtractedRelationship[]): Promise<{
+export declare function relationshipFailureMessage(singleError: string | undefined, batchError: string | undefined): string;
+export declare function persistRelationships(prolog: PrologProcess, results: ExtractionResult[], shardRelationships: ExtractedRelationship[], options?: {
+    workspaceRoot?: string;
+}): Promise<{
     relationshipCount: number;
     kbModified: boolean;
 }>;

package/dist/commands/sync/persistence.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"persistence.d.ts","sourceRoot":"","sources":["../../../src/commands/sync/persistence.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAEV,qBAAqB,EACrB,gBAAgB,EACjB,MAAM,8BAA8B,CAAC;AACtC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAgHrD,MAAM,WAAW,iBAAiB;IAChC,WAAW,EAAE,MAAM,CAAC;IACpB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,UAAU,EAAE,OAAO,CAAC;CACrB;AA8CD,iFAAiF;AACjF,wBAAsB,yBAAyB,CAC7C,MAAM,EAAE,aAAa,EACrB,WAAW,EAAE,SAAS,MAAM,EAAE,GAC7B,OAAO,CAAC,MAAM,CAAC,CAkCjB;AAED,0EAA0E;AAC1E,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,aAAa,EACrB,SAAS,EAAE,SAAS,MAAM,EAAE,GAC3B,OAAO,CAAC,MAAM,CAAC,CAmBjB;AAED,8EAA8E;AAC9E,wBAAsB,8BAA8B,CAClD,MAAM,EAAE,aAAa,EACrB,SAAS,EAAE,SAAS,MAAM,EAAE,GAC3B,OAAO,CAAC,IAAI,CAAC,CAoBf;AAED,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,aAAa,EACrB,aAAa,EAAE,SAAS,qBAAqB,EAAE,GAC9C,OAAO,CAAC,MAAM,CAAC,CAuBjB;AAmCD,wBAAsB,eAAe,CAEnC,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,gBAAgB,EAAE,EAC3B,SAAS,EAAE,GAAG,CAAC,MAAM,CAAC,EACtB,OAAO,GAAE;IAAE,qBAAqB,CAAC,EAAE,OAAO,CAAA;CAAO,GAChD,OAAO,CAAC;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,OAAO,CAAA;CAAE,CAAC,CAuOvD;AA6BD,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,gBAAgB,EAAE,EAC3B,kBAAkB,EAAE,qBAAqB,EAAE,GAC1C,OAAO,CAAC;IAAE,iBAAiB,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,OAAO,CAAA;CAAE,CAAC,CA0N7D"}
+{"version":3,"file":"persistence.d.ts","sourceRoot":"","sources":["../../../src/commands/sync/persistence.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAEV,qBAAqB,EACrB,gBAAgB,EACjB,MAAM,8BAA8B,CAAC;AACtC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAiHrD,MAAM,WAAW,iBAAiB;IAChC,WAAW,EAAE,MAAM,CAAC;IACpB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,UAAU,EAAE,OAAO,CAAC;CACrB;AA8CD,iFAAiF;AACjF,wBAAsB,yBAAyB,CAC7C,MAAM,EAAE,aAAa,EACrB,WAAW,EAAE,SAAS,MAAM,EAAE,GAC7B,OAAO,CAAC,MAAM,CAAC,CAkCjB;AAED,0EAA0E;AAC1E,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,aAAa,EACrB,SAAS,EAAE,SAAS,MAAM,EAAE,GAC3B,OAAO,CAAC,MAAM,CAAC,CAmBjB;AAED,8EAA8E;AAC9E,wBAAsB,8BAA8B,CAClD,MAAM,EAAE,aAAa,EACrB,SAAS,EAAE,SAAS,MAAM,EAAE,GAC3B,OAAO,CAAC,IAAI,CAAC,CAoBf;AAED,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,aAAa,EACrB,aAAa,EAAE,SAAS,qBAAqB,EAAE,GAC9C,OAAO,CAAC,MAAM,CAAC,CAuBjB;AAmCD,wBAAsB,eAAe,CAEnC,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,gBAAgB,EAAE,EAC3B,SAAS,EAAE,GAAG,CAAC,MAAM,CAAC,EACtB,OAAO,GAAE;IAAE,qBAAqB,CAAC,EAAE,OAAO,CAAA;CAAO,GAChD,OAAO,CAAC;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,OAAO,CAAA;CAAE,CAAC,CAiPvD;AA4BD,wBAAgB,0BAA0B,CACxC,WAAW,EAAE,MAAM,GAAG,SAAS,EAC/B,UAAU,EAAE,MAAM,GAAG,SAAS,GAC7B,MAAM,CAER;AAGD,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,gBAAgB,EAAE,EAC3B,kBAAkB,EAAE,qBAAqB,EAAE,EAC3C,OAAO,GAAE;IAAE,aAAa,CAAC,EAAE,MAAM,CAAA;CAAO,GACvC,OAAO,CAAC;IAAE,iBAAiB,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,OAAO,CAAA;CAAE,CAAC,CAmO7D"}

package/dist/commands/sync/persistence.js

@@ -18,7 +18,8 @@
 import * as path from "node:path";
 import { toPrologAtom, toPrologString } from "../../prolog/codec.js";
 import { loadEntities } from "../../public/operations/discovery-entities.js";
-import { appendOnlyVerificationReceiptHistoryErrors } from "../../public/verification-receipt.js";
+import { appendOnlyProofReceiptHistoryErrors } from "../../public/proof-receipt.js";
+import { findUntrackedDocumentMatches } from "./untracked-targets.js";
 // Field categorization for typed fact serialization
 // NOTE: base entity fields (status, owner, priority, severity) are NOT listed here —
 // they are emitted in the base props block above. Only fact-specific atom fields go here.
@@ -285,15 +286,15 @@ prolog, results, entityIds, options = {}) {
                     id: entity.id,
                     type: "test",
                 });
-                const previous = Array.isArray(existing[0]?.verification_receipts)
-                    ? existing[0].verification_receipts.filter((receipt) => receipt !== null &&
+                const previous = Array.isArray(existing[0]?.proof_receipts)
+                    ? existing[0].proof_receipts.filter((receipt) => receipt !== null &&
                         typeof receipt === "object" &&
                         !Array.isArray(receipt))
                     : [];
-                const next = Array.isArray(entity.verification_receipts)
-                    ? entity.verification_receipts
+                const next = Array.isArray(entity.proof_receipts)
+                    ? entity.proof_receipts
                     : undefined;
-                const receiptErrors = appendOnlyVerificationReceiptHistoryErrors(previous, next);
+                const receiptErrors = appendOnlyProofReceiptHistoryErrors(previous, next);
                 if (receiptErrors.length > 0) {
                     throw new Error(receiptErrors.join("; "));
                 }
@@ -369,8 +370,14 @@ prolog, results, entityIds, options = {}) {
                 if (entity.verification_perspective !== undefined) {
                     props.push(`verification_perspective=${toPrologAtom(entity.verification_perspective)}`);
                 }
-                if (entity.verification_receipts !== undefined) {
-                    props.push(`verification_receipts=${toPrologString(JSON.stringify(entity.verification_receipts))}`);
+                if (entity.proof_contract !== undefined) {
+                    props.push(`proof_contract=${toPrologString(JSON.stringify(entity.proof_contract))}`);
+                }
+                if (entity.proof_bindings !== undefined) {
+                    props.push(`proof_bindings=${toPrologString(JSON.stringify(entity.proof_bindings))}`);
+                }
+                if (entity.proof_receipts !== undefined) {
+                    props.push(`proof_receipts=${toPrologString(JSON.stringify(entity.proof_receipts))}`);
                 }
             }
             const propsList = `[${props.join(", ")}]`;
@@ -447,8 +454,11 @@ function semanticEntityContext(entity, sourceFile) {
     }
     return ` (${details.join("; ")})`;
 }
+export function relationshipFailureMessage(singleError, batchError) {
+    return singleError || batchError || "Unknown error";
+}
 // implements REQ-core-persistence
-export async function persistRelationships(prolog, results, shardRelationships) {
+export async function persistRelationships(prolog, results, shardRelationships, options = {}) {
     let relCount = 0;
     let kbModified = false;
     // Build ID lookup for relationship resolution
@@ -522,9 +532,7 @@ export async function persistRelationships(prolog, results, shardRelationships)
                         rel: item.rel,
                         fromId: item.fromId,
                         toId: item.toId,
-                        error: single.error ||
-                            (relationshipBatchRunner ? batch.error : undefined) ||
-                            "Unknown error",
+                        error: relationshipFailureMessage(single.error, relationshipBatchRunner ? batch.error : undefined),
                     });
                 }
             }
@@ -606,6 +614,12 @@ export async function persistRelationships(prolog, results, shardRelationships)
             const idList = [...missingIds].sort().join(", ");
             console.warn(`\nTip: ${missingEntities.length} relationship(s) reference ${missingIds.size} missing entity/ies: ${idList}.`);
             console.warn("  Create the missing docs (e.g., docs/requirements/REQ-*.md) or remove stale relationships.");
+            const untrackedMatches = options.workspaceRoot !== undefined
+                ? findUntrackedDocumentMatches(options.workspaceRoot, [...missingIds])
+                : new Map();
+            for (const [id, docPath] of untrackedMatches) {
+                console.warn(`  Note: document for ${id} exists at ${docPath} but is untracked, so sync ignores it. Stage it with \`git add ${docPath}\` (staging is enough; no commit required) and sync again.`);
+            }
         }
         else if (invalidRels.length > 0) {
             console.warn("\nTip: Check that relationship types and directions match the allowed schema (e.g., implements symbol→req, verified_by req→test).");

package/dist/commands/sync/staging.d.ts

@@ -16,6 +16,7 @@ interface StagingDeps {
     writeFileSync: typeof writeFileSync;
 }
 export declare function createUniqueStagingPath(currentBranch: string, rootDir: string, pid?: number, now?: number): string;
+export declare function abandonedStagingBranch(branch: string | undefined): string | undefined;
 export declare function cleanupAbandonedStagingDirectories(stagingPath: string, deps?: Partial<StagingDeps>): Promise<void>;
 export declare function prepareStagingEnvironment(stagingPath: string, livePath: string, rebuild: boolean, deps?: Partial<StagingDeps>): Promise<void>;
 export declare function atomicPublish(stagingPath: string, livePath: string, deps?: Partial<StagingDeps>): void;

package/dist/commands/sync/staging.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"staging.d.ts","sourceRoot":"","sources":["../../../src/commands/sync/staging.ts"],"names":[],"mappings":"AAkBA,OAAO,EACL,UAAU,EACV,SAAS,EACT,UAAU,EACV,MAAM,EACN,aAAa,EACd,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAEvC,OAAO,EAAE,MAAM,WAAW,CAAC;AAC3B,OAAO,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AAEnE,UAAU,WAAW;IACnB,iBAAiB,EAAE,OAAO,iBAAiB,CAAC;IAC5C,YAAY,EAAE,OAAO,YAAY,CAAC;IAClC,GAAG,EAAE,MAAM,MAAM,CAAC;IAClB,UAAU,EAAE,OAAO,UAAU,CAAC;IAC9B,EAAE,EAAE,OAAO,EAAE,CAAC;IACd,cAAc,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;IACzC,SAAS,EAAE,OAAO,SAAS,CAAC;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,OAAO,UAAU,CAAC;IAC9B,MAAM,EAAE,OAAO,MAAM,CAAC;IACtB,aAAa,EAAE,OAAO,aAAa,CAAC;CACrC;AA+BD,wBAAgB,uBAAuB,CACrC,aAAa,EAAE,MAAM,EACrB,OAAO,EAAE,MAAM,EACf,GAAG,SAAc,EACjB,GAAG,SAAa,GACf,MAAM,CAOR;AAGD,wBAAsB,kCAAkC,CACtD,WAAW,EAAE,MAAM,EACnB,IAAI,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GAC1B,OAAO,CAAC,IAAI,CAAC,CAqDf;AAED,wBAAsB,yBAAyB,CAE7C,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,OAAO,EAChB,IAAI,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GAC1B,OAAO,CAAC,IAAI,CAAC,CA6Cf;AA0CD,wBAAgB,aAAa,CAE3B,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAChB,IAAI,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GAC1B,IAAI,CAeN;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CACrC,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAChB,IAAI,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GAC1B,IAAI,CA6DN;AAED,wBAAgB,cAAc,CAE5B,WAAW,EAAE,MAAM,EACnB,IAAI,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GAC1B,IAAI,CAKN"}
+{"version":3,"file":"staging.d.ts","sourceRoot":"","sources":["../../../src/commands/sync/staging.ts"],"names":[],"mappings":"AAkBA,OAAO,EACL,UAAU,EACV,SAAS,EACT,UAAU,EACV,MAAM,EACN,aAAa,EACd,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAEvC,OAAO,EAAE,MAAM,WAAW,CAAC;AAC3B,OAAO,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AAEnE,UAAU,WAAW;IACnB,iBAAiB,EAAE,OAAO,iBAAiB,CAAC;IAC5C,YAAY,EAAE,OAAO,YAAY,CAAC;IAClC,GAAG,EAAE,MAAM,MAAM,CAAC;IAClB,UAAU,EAAE,OAAO,UAAU,CAAC;IAC9B,EAAE,EAAE,OAAO,EAAE,CAAC;IACd,cAAc,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;IACzC,SAAS,EAAE,OAAO,SAAS,CAAC;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,OAAO,UAAU,CAAC;IAC9B,MAAM,EAAE,OAAO,MAAM,CAAC;IACtB,aAAa,EAAE,OAAO,aAAa,CAAC;CACrC;AA+BD,wBAAgB,uBAAuB,CACrC,aAAa,EAAE,MAAM,EACrB,OAAO,EAAE,MAAM,EACf,GAAG,SAAc,EACjB,GAAG,SAAa,GACf,MAAM,CAOR;AAED,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,MAAM,GAAG,SAAS,GACzB,MAAM,GAAG,SAAS,CAEpB;AAGD,wBAAsB,kCAAkC,CACtD,WAAW,EAAE,MAAM,EACnB,IAAI,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GAC1B,OAAO,CAAC,IAAI,CAAC,CAqDf;AAED,wBAAsB,yBAAyB,CAE7C,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,OAAO,EAChB,IAAI,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GAC1B,OAAO,CAAC,IAAI,CAAC,CA6Cf;AA0CD,wBAAgB,aAAa,CAE3B,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAChB,IAAI,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GAC1B,IAAI,CAeN;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CACrC,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAChB,IAAI,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GAC1B,IAAI,CA6DN;AAED,wBAAgB,cAAc,CAE5B,WAAW,EAAE,MAAM,EACnB,IAAI,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GAC1B,IAAI,CAKN"}

package/dist/commands/sync/staging.js

@@ -50,16 +50,19 @@ function resolveDeps(overrides) {
 export function createUniqueStagingPath(currentBranch, rootDir, pid = process.pid, now = Date.now()) {
     return path.join(rootDir, ".kb", "branches", `${currentBranch}.staging.${pid}.${now}`);
 }
+export function abandonedStagingBranch(branch) {
+    return branch ? branch : undefined;
+}
 // implements REQ-003
 export async function cleanupAbandonedStagingDirectories(stagingPath, deps) {
     const resolved = resolveDeps(deps);
     const stagingDir = path.dirname(stagingPath);
     const stagingBase = path.basename(stagingPath);
-    const match = /^(?<branch>.+)\.staging\.(?<pid>\d+)\.(?<timestamp>\d+)$/.exec(stagingBase);
+    const match = /^(?<branch>.*)\.staging\.(?<pid>\d+)\.(?<timestamp>\d+)$/.exec(stagingBase);
     if (!match?.groups) {
         return;
     }
-    const branch = match.groups.branch;
+    const branch = abandonedStagingBranch(match.groups.branch);
     if (!branch) {
         return;
     }

package/dist/commands/sync/untracked-targets.d.ts

@@ -0,0 +1,24 @@
+interface UntrackedTargetsDeps {
+    execFileSync: (file: string, args: readonly string[], options: {
+        encoding: "utf8";
+        maxBuffer: number;
+        stdio: "pipe";
+    }) => string;
+    existsSync: (path: string) => boolean;
+    readFileSync: (path: string, encoding: "utf8") => string;
+}
+/**
+ * Match missing relationship-target ids against untracked `.kb` documents.
+ *
+ * Sync discovery intentionally enumerates only git-tracked (or
+ * pending-receipt) documents, so a freshly authored but unstaged `.kb` doc is
+ * invisible to sync while relationships that reference it fail with a
+ * misleading "Target entity does not exist". This helper powers the sync
+ * warning that tells the author to stage the document instead.
+ *
+ * Best effort by design: any git or filesystem failure yields no matches so
+ * the diagnostic can never break a sync run.
+ */
+export declare function findUntrackedDocumentMatches(workspaceRoot: string, missingIds: readonly string[], deps?: Partial<UntrackedTargetsDeps>): Map<string, string>;
+export {};
+//# sourceMappingURL=untracked-targets.d.ts.map

package/dist/commands/sync/untracked-targets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"untracked-targets.d.ts","sourceRoot":"","sources":["../../../src/commands/sync/untracked-targets.ts"],"names":[],"mappings":"AAsBA,UAAU,oBAAoB;IAC5B,YAAY,EAAE,CACZ,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,OAAO,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,KAC5D,MAAM,CAAC;IACZ,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;IACtC,YAAY,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,MAAM,CAAC;CAC1D;AAQD;;;;;;;;;;;GAWG;AAEH,wBAAgB,4BAA4B,CAC1C,aAAa,EAAE,MAAM,EACrB,UAAU,EAAE,SAAS,MAAM,EAAE,EAC7B,IAAI,GAAE,OAAO,CAAC,oBAAoB,CAAM,GACvC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAiDrB"}

package/dist/commands/sync/untracked-targets.js

@@ -0,0 +1,108 @@
+/*
+ Kibi — repo-local, per-branch, queryable long-term memory for software projects
+ Copyright (C) 2026 Piotr Franczyk
+
+ This program is free software: you can redistribute it and/or modify
+ it under the terms of the GNU Affero General Public License as published by
+ the Free Software Foundation, either version 3 of the License, or
+ (at your option) any later version.
+
+ This program is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ GNU Affero General Public License for more details.
+
+ You should have received a copy of the GNU Affero General Public License
+ along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import * as path from "node:path";
+const defaultDeps = {
+    execFileSync: (file, args, options) => execFileSync(file, args, options),
+    existsSync,
+    readFileSync,
+};
+/**
+ * Match missing relationship-target ids against untracked `.kb` documents.
+ *
+ * Sync discovery intentionally enumerates only git-tracked (or
+ * pending-receipt) documents, so a freshly authored but unstaged `.kb` doc is
+ * invisible to sync while relationships that reference it fail with a
+ * misleading "Target entity does not exist". This helper powers the sync
+ * warning that tells the author to stage the document instead.
+ *
+ * Best effort by design: any git or filesystem failure yields no matches so
+ * the diagnostic can never break a sync run.
+ */
+// implements REQ-core-persistence
+export function findUntrackedDocumentMatches(workspaceRoot, missingIds, deps = {}) {
+    const resolved = { ...defaultDeps, ...deps };
+    const matches = new Map();
+    if (missingIds.length === 0)
+        return matches;
+    let untracked;
+    try {
+        const output = resolved.execFileSync("git", [
+            "-C",
+            workspaceRoot,
+            "ls-files",
+            "--others",
+            "--exclude-standard",
+            "-z",
+            "--",
+            ".kb",
+        ], { encoding: "utf8", maxBuffer: 16 * 1024 * 1024, stdio: "pipe" });
+        untracked = output.split("\0").filter(Boolean);
+    }
+    catch {
+        return matches;
+    }
+    const remaining = new Set(missingIds);
+    for (const relative of untracked) {
+        if (remaining.size === 0)
+            break;
+        if (!relative.endsWith(".md"))
+            continue;
+        const absolute = path.resolve(workspaceRoot, relative.replaceAll("\\", "/"));
+        if (!resolved.existsSync(absolute))
+            continue;
+        let content;
+        try {
+            content = resolved.readFileSync(absolute, "utf8");
+        }
+        catch {
+            continue;
+        }
+        const id = frontmatterId(content);
+        if (id !== null && remaining.has(id)) {
+            const workspaceRelative = path
+                .relative(workspaceRoot, absolute)
+                .replaceAll("\\", "/");
+            matches.set(id, workspaceRelative);
+            remaining.delete(id);
+        }
+    }
+    return matches;
+}
+/**
+ * Extract `id:` from a markdown document's YAML frontmatter (the first
+ * `---` block). Documents whose id never appears in the frontmatter region
+ * are not entity candidates.
+ */
+function frontmatterId(content) {
+    const lines = content.match(/[^\n]*\n|[^\n]+$/g) ?? [];
+    if (lines[0]?.trim() !== "---")
+        return null;
+    for (let index = 1; index < lines.length && index < 64; index++) {
+        const line = lines[index] ?? "";
+        if (line.trim() === "---")
+            return null;
+        const match = line.match(/^id:\s*(?:"([^"]+)"|'([^']+)'|(\S+))/);
+        if (match) {
+            const id = (match[1] ?? match[2] ?? match[3])?.trim();
+            return id && id.length > 0 ? id : null;
+        }
+    }
+    return null;
+}