kibi-cli 0.18.1 → 1.0.1

package/dist/commands/report.js

@@ -0,0 +1,191 @@
+import { execFileSync, spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { mkdir, rename, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { coverageSpec } from "../public/operations/specs/reporting.js";
+import { KIBI_BRAND, renderKibiBadge } from "../report/brand.js";
+import { renderHtmlReport, } from "../report/html-report.js";
+import { resolveReportRepository, } from "../report/repository.js";
+import { createCliRuntime } from "../runtime/cli-runtime.js";
+import { listGitRemotes } from "./github-init.js";
+function gitCommitSha(cwd) {
+    try {
+        const sha = execFileSync("git", ["-C", cwd, "rev-parse", "HEAD"], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "pipe"],
+        }).trim();
+        return /^[0-9a-f]{7,64}$/i.test(sha) ? sha : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function loadReportRepository(cwd, branch) {
+    const commitSha = gitCommitSha(cwd);
+    return resolveReportRepository({
+        remotes: listGitRemotes(cwd),
+        ...(commitSha ? { commitSha } : {}),
+        branch,
+    });
+}
+function parseTags(value) {
+    return (value ?? "")
+        .split(",")
+        .map((item) => item.trim())
+        .filter(Boolean);
+}
+function parseLimit(value) {
+    const raw = (value ?? "10000").trim();
+    const limit = /^\d+$/.test(raw) ? Number(raw) : Number.NaN;
+    if (!Number.isSafeInteger(limit) || limit < 1 || limit > 100_000) {
+        throw new Error("Report limit must be an integer between 1 and 100000");
+    }
+    return limit;
+}
+function reportTarget(root, output) {
+    const requested = output?.trim() || "kibi-report";
+    const absolute = path.resolve(root, requested);
+    return [".html", ".htm"].includes(path.extname(absolute).toLowerCase())
+        ? absolute
+        : path.join(absolute, "index.html");
+}
+async function executeCoverageInContext(context, tags, limit) {
+    const requirements = await coverageSpec.execute({
+        by: "req",
+        tags,
+        includePassing: true,
+        includeTransitive: true,
+        limit,
+        offset: 0,
+    }, context);
+    const symbols = await coverageSpec.execute({
+        by: "symbol",
+        tags,
+        includePassing: false,
+        includeTransitive: true,
+        // Only the complete summary is needed for the unowned-code metric.
+        limit: 0,
+        offset: 0,
+    }, context);
+    if (!requirements.structuredContent || !symbols.structuredContent) {
+        throw new Error("Coverage did not return structured report data");
+    }
+    return {
+        requirements: requirements.structuredContent,
+        symbols: symbols.structuredContent,
+        branch: context.branchAttachment?.gitBranch ??
+            String(requirements.structuredContent.meta?.branch ?? "unknown"),
+    };
+}
+async function loadCoverage(tags, limit) {
+    const runtime = createCliRuntime();
+    const runtimeSpec = coverageSpec;
+    const context = await runtime.open(runtimeSpec);
+    let result;
+    try {
+        result = await executeCoverageInContext(context, tags, limit);
+    }
+    catch (error) {
+        await runtime.close(context, { status: "error", error });
+        throw error;
+    }
+    await runtime.close(context, { status: "success", result });
+    return result;
+}
+async function writeAtomically(filePath, contents) {
+    const directory = path.dirname(filePath);
+    const temporaryPath = path.join(directory, `.${path.basename(filePath)}.${randomUUID()}.tmp`);
+    await mkdir(directory, { recursive: true });
+    try {
+        await writeFile(temporaryPath, contents, "utf8");
+        await rename(temporaryPath, filePath);
+    }
+    catch (error) {
+        await rm(temporaryPath, { force: true });
+        throw error;
+    }
+}
+export async function openReport(filePath) {
+    const fileUrl = pathToFileURL(filePath).href;
+    const [command, args] = process.platform === "darwin"
+        ? ["open", [fileUrl]]
+        : process.platform === "win32"
+            ? ["rundll32", ["url.dll,FileProtocolHandler", fileUrl]]
+            : ["xdg-open", [fileUrl]];
+    await new Promise((resolve, reject) => {
+        const child = spawn(command, args, {
+            detached: true,
+            stdio: "ignore",
+        });
+        child.once("error", reject);
+        child.once("spawn", () => {
+            child.unref();
+            resolve();
+        });
+    });
+}
+function assertCompleteRequirementRows(coverage, limit) {
+    const total = Number(coverage.summary.total ?? 0);
+    if (Number.isFinite(total) && coverage.rows.length < total) {
+        throw new Error(`Report requires complete requirement rows, but ${coverage.rows.length} of ${total} were returned. Increase --limit above ${limit}.`);
+    }
+}
+// implements REQ-kibi-html-health-report
+export async function reportCommand(options, deps = {}) {
+    const limit = parseLimit(options.limit);
+    const tags = parseTags(options.tag);
+    const coverage = await (deps.loadCoverage ?? loadCoverage)(tags, limit);
+    assertCompleteRequirementRows(coverage.requirements, limit);
+    const now = (deps.now ?? (() => new Date()))();
+    const workspace = (deps.cwd ?? (() => process.cwd()))();
+    const html = renderHtmlReport({
+        requirements: coverage.requirements,
+        symbols: coverage.symbols,
+        branch: coverage.branch,
+        generatedAt: now,
+        repository: deps.repository ?? loadReportRepository(workspace, coverage.branch),
+    });
+    const outputPath = reportTarget(workspace, options.output);
+    const requestedOutput = options.output?.trim() || "kibi-report";
+    const outputIsHtmlFile = [".html", ".htm"].includes(path.extname(requestedOutput).toLowerCase());
+    const badgePath = outputIsHtmlFile
+        ? path.join(path.dirname(outputPath), `${path.basename(outputPath, path.extname(outputPath))}.badge.svg`)
+        : path.join(path.dirname(outputPath), "badge.svg");
+    const summary = coverage.requirements.summary;
+    const total = Number(summary.total ?? 0);
+    const notApplicable = Number(summary.proofNotApplicable ?? 0);
+    const proven = Number(summary.proofProven ?? 0);
+    const currentRequirements = Math.max(0, total - notApplicable);
+    const proofPercent = currentRequirements === 0
+        ? 0
+        : Math.round((proven / currentRequirements) * 100);
+    const hasContradiction = coverage.requirements.rows.some((row) => Array.isArray(row.proofGaps) &&
+        row.proofGaps.includes("blocking_contradiction"));
+    const snapshotStale = coverage.requirements.meta?.dirty === true ||
+        coverage.requirements.meta?.verificationSnapshotDirty === true;
+    const badgeMessage = currentRequirements === 0 ? "no requirements" : `${proofPercent}% proven`;
+    const badgeColor = currentRequirements === 0
+        ? KIBI_BRAND.rail
+        : hasContradiction
+            ? KIBI_BRAND.danger
+            : snapshotStale
+                ? KIBI_BRAND.warning
+                : proofPercent === 100
+                    ? KIBI_BRAND.success
+                    : proofPercent >= 90
+                        ? KIBI_BRAND.signal
+                        : proofPercent >= 70
+                            ? KIBI_BRAND.warning
+                            : KIBI_BRAND.danger;
+    const badge = renderKibiBadge(badgeMessage, badgeColor);
+    await writeAtomically(outputPath, html);
+    await writeAtomically(badgePath, badge);
+    console.log(`Kibi report written to ${outputPath}`);
+    console.log(`Kibi badge written to ${badgePath}`);
+    if (options.open === true) {
+        await (deps.openReport ?? openReport)(outputPath);
+        console.log("Opened Kibi report in the default browser");
+    }
+    return outputPath;
+}

package/dist/commands/search.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../src/commands/search.ts"],"names":[],"mappings":"AAQA,UAAU,aAAa;IACrB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IACnC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,wBAAsB,aAAa,CACjC,KAAK,EAAE,MAAM,GAAG,SAAS,EACzB,OAAO,EAAE,aAAa,GACrB,OAAO,CAAC,IAAI,CAAC,CAmCf"}
+{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../src/commands/search.ts"],"names":[],"mappings":"AAMA,UAAU,aAAa;IACrB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IACnC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,wBAAsB,aAAa,CACjC,KAAK,EAAE,MAAM,GAAG,SAAS,EACzB,OAAO,EAAE,aAAa,GACrB,OAAO,CAAC,IAAI,CAAC,CAmCf"}

package/dist/commands/search.js

@@ -1,4 +1,6 @@
-import { VALID_ENTITY_TYPES, executeOperation, searchSpec, } from "../public/operations/index.js";
+import { VALID_ENTITY_TYPES } from "../public/operations/discovery-entities.js";
+import { executeOperation } from "../public/operations/runtime-types.js";
+import { searchSpec } from "../public/operations/specs/discovery.js";
 import { createCliRuntime } from "../runtime/cli-runtime.js";
 import { printDiscoveryResult } from "./discovery-shared.js";
 export async function searchCommand(query, options) {

package/dist/commands/status.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"status.d.ts","sourceRoot":"","sources":["../../src/commands/status.ts"],"names":[],"mappings":"AAIA,UAAU,aAAa;IACrB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CACpC;AAED,wBAAsB,aAAa,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAazE"}
+{"version":3,"file":"status.d.ts","sourceRoot":"","sources":["../../src/commands/status.ts"],"names":[],"mappings":"AAKA,UAAU,aAAa;IACrB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CACpC;AAED,wBAAsB,aAAa,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAazE"}

package/dist/commands/status.js

@@ -1,4 +1,5 @@
-import { executeOperation, statusSpec } from "../public/operations/index.js";
+import { executeOperation } from "../public/operations/runtime-types.js";
+import { statusSpec } from "../public/operations/specs/discovery.js";
 import { createCliRuntime } from "../runtime/cli-runtime.js";
 import { printDiscoveryResult } from "./discovery-shared.js";
 export async function statusCommand(options) {

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

@@ -10,14 +10,37 @@ interface SyncCacheDeps {
 export type SyncCache = {
     version: number;
     hashes: Record<string, string>;
+    /** Content hashes for relationship shards; optional for v1 caches. */
+    relationshipHashes?: Record<string, string>;
+    /** Normalized entity payload hashes, keyed by canonical entity ID. */
+    entityHashes?: Record<string, string>;
+    /** Entity IDs last compiled from each normalized source path. */
+    sourceEntityIds?: Record<string, string[]>;
+    /** Normalized relationship keys last compiled from each shard. */
+    shardRelationships?: Record<string, string[]>;
     seenAt: Record<string, string>;
     semanticHashes: Record<string, string>;
     semanticContracts: Record<string, boolean>;
 };
-export declare const SYNC_CACHE_VERSION = 1;
+/**
+ * v2: cache identities are workspace-root relative instead of process-cwd
+ * relative, and symbol manifests are fingerprinted together with their
+ * generated coordinate artifact so artifact-only changes are never mistaken
+ * for no-ops.
+ */
+export declare const SYNC_CACHE_VERSION = 2;
 export declare const SYNC_CACHE_TTL_MS: number;
-export declare function toCacheKey(filePath: string): string;
-export declare function hashFile(filePath: string, deps?: Partial<SyncCacheDeps>): string;
+export declare function toCacheKey(workspaceRoot: string, filePath: string): string;
+export declare function hashFile(workspaceRoot: string, filePath: string, deps?: Partial<SyncCacheDeps>): string;
+/** Deterministically hash a JSON-compatible compiler payload. */
+export declare function hashNormalized(value: unknown): string;
+/**
+ * Composite fingerprint for a symbol manifest and its generated coordinate
+ * artifact. The artifact is a compiler dependency of the manifest, so its
+ * existence, emptiness, content, and deletion must all change the effective
+ * source hash even though the authored YAML bytes stay identical.
+ */
+export declare function hashManifestWithCoordinates(workspaceRoot: string, manifestPath: string, coordinatesPath: string | null, deps?: Partial<SyncCacheDeps>): string;
 export declare function readSyncCache(cachePath: string, deps?: Partial<SyncCacheDeps>): SyncCache;
 export declare function writeSyncCache(cachePath: string, cache: SyncCache, deps?: Partial<SyncCacheDeps>): void;
 export declare function copySyncCache(livePath: string, stagingPath: string, deps?: Partial<SyncCacheDeps>): void;

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

@@ -1 +1 @@
-{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../../src/commands/sync/cache.ts"],"names":[],"mappings":"AAkBA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAG7E,UAAU,aAAa;IACrB,UAAU,EAAE,OAAO,UAAU,CAAC;IAC9B,UAAU,EAAE,OAAO,UAAU,CAAC;IAC9B,SAAS,EAAE,OAAO,SAAS,CAAC;IAC5B,YAAY,EAAE,OAAO,YAAY,CAAC;IAClC,aAAa,EAAE,OAAO,aAAa,CAAC;CACrC;AAaD,MAAM,MAAM,SAAS,GAAG;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACvC,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC5C,CAAC;AAEF,eAAO,MAAM,kBAAkB,IAAI,CAAC;AACpC,eAAO,MAAM,iBAAiB,QAA2B,CAAC;AAE1D,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED,wBAAgB,QAAQ,CAEtB,QAAQ,EAAE,MAAM,EAChB,IAAI,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,GAC5B,MAAM,CAIR;AAED,wBAAgB,aAAa,CAE3B,SAAS,EAAE,MAAM,EACjB,IAAI,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,GAC5B,SAAS,CA0CX;AAED,wBAAgB,cAAc,CAE5B,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,SAAS,EAChB,IAAI,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,GAC5B,IAAI,CAaN;AAED,wBAAgB,aAAa,CAE3B,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,EACnB,IAAI,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,GAC5B,IAAI,CASN"}
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../../src/commands/sync/cache.ts"],"names":[],"mappings":"AAkBA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAI7E,UAAU,aAAa;IACrB,UAAU,EAAE,OAAO,UAAU,CAAC;IAC9B,UAAU,EAAE,OAAO,UAAU,CAAC;IAC9B,SAAS,EAAE,OAAO,SAAS,CAAC;IAC5B,YAAY,EAAE,OAAO,YAAY,CAAC;IAClC,aAAa,EAAE,OAAO,aAAa,CAAC;CACrC;AAaD,MAAM,MAAM,SAAS,GAAG;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,sEAAsE;IACtE,kBAAkB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5C,sEAAsE;IACtE,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,iEAAiE;IACjE,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IAC3C,kEAAkE;IAClE,kBAAkB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IAC9C,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACvC,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC5C,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,IAAI,CAAC;AACpC,eAAO,MAAM,iBAAiB,QAA2B,CAAC;AAE1D,wBAAgB,UAAU,CAAC,aAAa,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAM1E;AAED,wBAAgB,QAAQ,CAEtB,aAAa,EAAE,MAAM,EACrB,QAAQ,EAAE,MAAM,EAChB,IAAI,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,GAC5B,MAAM,CAIR;AAED,iEAAiE;AACjE,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAerD;AAED;;;;;GAKG;AAEH,wBAAgB,2BAA2B,CACzC,aAAa,EAAE,MAAM,EACrB,YAAY,EAAE,MAAM,EACpB,eAAe,EAAE,MAAM,GAAG,IAAI,EAC9B,IAAI,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,GAC5B,MAAM,CA4FR;AAED,wBAAgB,aAAa,CAE3B,SAAS,EAAE,MAAM,EACjB,IAAI,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,GAC5B,SAAS,CAuDX;AAED,wBAAgB,cAAc,CAE5B,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,SAAS,EAChB,IAAI,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,GAC5B,IAAI,CAaN;AAED,wBAAgB,aAAa,CAE3B,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,EACnB,IAAI,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,GAC5B,IAAI,CASN"}

package/dist/commands/sync/cache.js

@@ -18,6 +18,7 @@
 import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import * as path from "node:path";
+import { load as parseYAML } from "js-yaml";
 function resolveDeps(overrides) {
     return {
         createHash,
@@ -28,18 +29,140 @@ function resolveDeps(overrides) {
         ...overrides,
     };
 }
-export const SYNC_CACHE_VERSION = 1;
+/**
+ * v2: cache identities are workspace-root relative instead of process-cwd
+ * relative, and symbol manifests are fingerprinted together with their
+ * generated coordinate artifact so artifact-only changes are never mistaken
+ * for no-ops.
+ */
+export const SYNC_CACHE_VERSION = 2;
 export const SYNC_CACHE_TTL_MS = 30 * 24 * 60 * 60 * 1000;
-export function toCacheKey(filePath) {
-    return path.relative(process.cwd(), filePath).split(path.sep).join("/");
+export function toCacheKey(workspaceRoot, filePath) {
+    const root = path.resolve(workspaceRoot);
+    const target = path.isAbsolute(filePath)
+        ? filePath
+        : path.resolve(root, filePath);
+    return path.relative(root, target).split(path.sep).join("/");
 }
 export function hashFile(
 // implements REQ-003
-filePath, deps) {
+workspaceRoot, filePath, deps) {
     const resolved = resolveDeps(deps);
     const content = resolved.readFileSync(filePath);
     return resolved.createHash("sha256").update(content).digest("hex");
 }
+/** Deterministically hash a JSON-compatible compiler payload. */
+export function hashNormalized(value) {
+    const normalize = (input) => {
+        if (Array.isArray(input))
+            return input.map(normalize);
+        if (input !== null && typeof input === "object") {
+            return Object.fromEntries(Object.entries(input)
+                .sort(([left], [right]) => left.localeCompare(right))
+                .map(([key, child]) => [key, normalize(child)]));
+        }
+        return input;
+    };
+    return createHash("sha256")
+        .update(JSON.stringify(normalize(value)))
+        .digest("hex");
+}
+/**
+ * Composite fingerprint for a symbol manifest and its generated coordinate
+ * artifact. The artifact is a compiler dependency of the manifest, so its
+ * existence, emptiness, content, and deletion must all change the effective
+ * source hash even though the authored YAML bytes stay identical.
+ */
+// implements REQ-generated-coordinate-persistence
+export function hashManifestWithCoordinates(workspaceRoot, manifestPath, coordinatesPath, deps) {
+    const resolved = resolveDeps(deps);
+    const manifestContent = resolved.readFileSync(manifestPath);
+    const manifestHash = resolved
+        .createHash("sha256")
+        .update(manifestContent)
+        .digest("hex");
+    let artifactState = "missing";
+    let artifactHash = "";
+    if (coordinatesPath !== null && resolved.existsSync(coordinatesPath)) {
+        const content = resolved.readFileSync(coordinatesPath);
+        artifactState = content.length > 0 ? "present" : "empty";
+        artifactHash = resolved.createHash("sha256").update(content).digest("hex");
+    }
+    const referencedSources = [];
+    let symbols = [];
+    try {
+        const parsed = parseYAML(manifestContent.toString());
+        if (parsed !== null &&
+            typeof parsed === "object" &&
+            !Array.isArray(parsed) &&
+            Array.isArray(parsed.symbols)) {
+            symbols = parsed.symbols;
+        }
+    }
+    catch {
+        // Extraction owns the user-facing YAML diagnostic. Fingerprinting must
+        // still complete so malformed manifests cannot look cache-current.
+    }
+    const sourcePaths = new Set();
+    for (const value of symbols) {
+        if (value === null || typeof value !== "object" || Array.isArray(value)) {
+            continue;
+        }
+        const symbol = value;
+        const sourceFile = typeof symbol.sourceFile === "string"
+            ? symbol.sourceFile
+            : typeof symbol.source === "string"
+                ? symbol.source
+                : undefined;
+        if (sourceFile !== undefined && sourceFile.length > 0) {
+            sourcePaths.add(sourceFile);
+        }
+    }
+    const root = path.resolve(workspaceRoot);
+    for (const sourceFile of [...sourcePaths].sort()) {
+        try {
+            const absolute = path.isAbsolute(sourceFile)
+                ? path.resolve(sourceFile)
+                : path.resolve(root, sourceFile);
+            const relative = path.relative(root, absolute);
+            if (relative === ".." || relative.startsWith(`..${path.sep}`)) {
+                referencedSources.push({
+                    path: sourceFile,
+                    state: "outside-workspace",
+                });
+            }
+            else if (!resolved.existsSync(absolute)) {
+                referencedSources.push({ path: sourceFile, state: "missing" });
+            }
+            else {
+                try {
+                    referencedSources.push({
+                        path: sourceFile,
+                        state: "present",
+                        sha256: resolved
+                            .createHash("sha256")
+                            .update(resolved.readFileSync(absolute))
+                            .digest("hex"),
+                    });
+                }
+                catch {
+                    referencedSources.push({ path: sourceFile, state: "unreadable" });
+                }
+            }
+        }
+        catch {
+            referencedSources.push({ path: sourceFile, state: "unreadable" });
+        }
+    }
+    return resolved
+        .createHash("sha256")
+        .update(JSON.stringify({
+        manifest: manifestHash,
+        coordinates: { state: artifactState, sha256: artifactHash },
+        referencedSources,
+    }))
+        .digest("hex");
+}
 export function readSyncCache(
 // implements REQ-003
 cachePath, deps) {
@@ -64,13 +187,26 @@ cachePath, deps) {
                 semanticContracts: {},
             };
         }
-        return {
+        const cache = {
             version: SYNC_CACHE_VERSION,
             hashes: parsed.hashes ?? {},
             seenAt: parsed.seenAt ?? {},
             semanticHashes: parsed.semanticHashes ?? {},
             semanticContracts: parsed.semanticContracts ?? {},
         };
+        if (parsed.relationshipHashes !== undefined) {
+            cache.relationshipHashes = parsed.relationshipHashes;
+        }
+        if (parsed.entityHashes !== undefined) {
+            cache.entityHashes = parsed.entityHashes;
+        }
+        if (parsed.sourceEntityIds !== undefined) {
+            cache.sourceEntityIds = parsed.sourceEntityIds;
+        }
+        if (parsed.shardRelationships !== undefined) {
+            cache.shardRelationships = parsed.shardRelationships;
+        }
+        return cache;
     }
     catch {
         return {

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

@@ -1,8 +1,29 @@
-import type { KbConfigPaths } from "../../utils/config.js";
+export type DiscoveryOptions = Readonly<{
+    trackedOnly?: boolean;
+    recoverMissingPendingSources?: boolean;
+    /** Read-only callers must not consume receipts merely by discovering files. */
+    consumeTrackedPendingReceipts?: boolean;
+}>;
+/**
+ * A missing-source receipt selected for explicit recovery.
+ *
+ * The receipt path alone is not enough: another Kibi process may publish a
+ * newer receipt between discovery and the derived-store publication.  The
+ * raw digest lets the recovery boundary compare-and-delete the exact receipt
+ * it observed, leaving a newer receipt available for its owner to handle.
+ */
+export type PendingSourceReceiptSnapshot = Readonly<{
+    receiptPath: string;
+    path: string;
+    afterHash: string;
+    rawHash: string;
+}>;
+export declare function clearRecoveredPendingSourceReceipts(cwd: string, receipts: readonly PendingSourceReceiptSnapshot[]): void;
 export declare function normalizeMarkdownPath(pattern: string | undefined): string | null;
-export declare function discoverSourceFiles(cwd: string, paths: KbConfigPaths): Promise<{
+export declare function discoverSourceFiles(cwd: string, options?: DiscoveryOptions): Promise<{
     markdownFiles: string[];
     manifestFiles: string[];
     relationshipsDir: string;
+    recoveredPendingReceiptPaths: PendingSourceReceiptSnapshot[];
 }>;
 //# sourceMappingURL=discovery.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"discovery.d.ts","sourceRoot":"","sources":["../../../src/commands/sync/discovery.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAI3D,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,GAAG,SAAS,GAC1B,MAAM,GAAG,IAAI,CAIf;AAED,wBAAsB,mBAAmB,CACvC,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,aAAa,GACnB,OAAO,CAAC;IACT,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,gBAAgB,EAAE,MAAM,CAAC;CAC1B,CAAC,CAkCD"}
+{"version":3,"file":"discovery.d.ts","sourceRoot":"","sources":["../../../src/commands/sync/discovery.ts"],"names":[],"mappings":"AAiCA,MAAM,MAAM,gBAAgB,GAAG,QAAQ,CAAC;IACtC,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,4BAA4B,CAAC,EAAE,OAAO,CAAC;IACvC,+EAA+E;IAC/E,6BAA6B,CAAC,EAAE,OAAO,CAAC;CACzC,CAAC,CAAC;AAEH;;;;;;;GAOG;AACH,MAAM,MAAM,4BAA4B,GAAG,QAAQ,CAAC;IAClD,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC,CAAC;AAyFH,wBAAgB,mCAAmC,CACjD,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,SAAS,4BAA4B,EAAE,GAChD,IAAI,CA2EN;AAsBD,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,GAAG,SAAS,GAC1B,MAAM,GAAG,IAAI,CAIf;AAED,wBAAsB,mBAAmB,CACvC,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC;IACT,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,gBAAgB,EAAE,MAAM,CAAC;IACzB,4BAA4B,EAAE,4BAA4B,EAAE,CAAC;CAC9D,CAAC,CA4FD"}