kibi-cli 0.19.0 → 1.0.1

package/dist/public/operations/migration-plan.js

@@ -0,0 +1,537 @@
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import * as path from "node:path";
+import { legacyConfigExists } from "../../utils/config.js";
+import { readKbManifestStatus } from "../../utils/kb-manifest.js";
+import { getSchemaVersionStatus, normalizeSchemaVersion, } from "../../utils/schema-version.js";
+export const MIGRATION_PLAN_VERSION = "kibi.migration-plan.v2";
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function stableValue(value, root = true) {
+    if (Array.isArray(value))
+        return value.map((entry) => stableValue(entry, false));
+    if (!isRecord(value))
+        return value;
+    return Object.fromEntries(Object.entries(value)
+        .filter(([key]) => root
+        ? key !== "planHash" && key !== "status" && key !== "summary"
+        : key !== "planHash")
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, item]) => [key, stableValue(item, false)]));
+}
+// implements REQ-agent-guided-migration-orchestration
+export function migrationPlanHash(value) {
+    return createHash("sha256")
+        .update(JSON.stringify(stableValue(value)))
+        .digest("hex");
+}
+function uniqueSorted(values) {
+    return [...new Set(values ?? [])].sort();
+}
+function actionSort(left, right) {
+    return (left.state.localeCompare(right.state) ||
+        left.safety.localeCompare(right.safety) ||
+        left.category.localeCompare(right.category) ||
+        left.id.localeCompare(right.id));
+}
+/** Return actions in a deterministic dependency-first order for agents and the applier. */
+function dependencyOrder(actions) {
+    const byId = new Map(actions.map((action) => [action.id, action]));
+    const remaining = new Map(actions.map((action) => [
+        action.id,
+        new Set(action.dependsOn.filter((dependency) => byId.has(dependency))),
+    ]));
+    const ordered = [];
+    const ready = actions
+        .filter((action) => (remaining.get(action.id)?.size ?? 0) === 0)
+        .sort(actionSort)
+        .map((action) => action.id);
+    const queued = new Set(ready);
+    while (ready.length > 0) {
+        const id = ready.shift();
+        if (id === undefined)
+            break;
+        queued.delete(id);
+        const action = byId.get(id);
+        if (action === undefined)
+            continue;
+        ordered.push(action);
+        for (const [candidateId, dependencies] of remaining) {
+            if (!dependencies.delete(id) ||
+                dependencies.size !== 0 ||
+                queued.has(candidateId)) {
+                continue;
+            }
+            ready.push(candidateId);
+            queued.add(candidateId);
+            ready.sort((left, right) => {
+                const leftAction = byId.get(left);
+                const rightAction = byId.get(right);
+                if (leftAction === undefined || rightAction === undefined) {
+                    return left.localeCompare(right);
+                }
+                return actionSort(leftAction, rightAction);
+            });
+        }
+    }
+    // Preserve cyclic/missing-dependency actions in canonical order; validation will block them.
+    if (ordered.length !== actions.length) {
+        const emitted = new Set(ordered.map((action) => action.id));
+        ordered.push(...actions.filter((action) => !emitted.has(action.id)).sort(actionSort));
+    }
+    return ordered;
+}
+function summarize(actions) {
+    return {
+        actionCount: actions.length,
+        readyActionCount: actions.filter((action) => action.state === "ready")
+            .length,
+        blockedActionCount: actions.filter((action) => action.state === "blocked")
+            .length,
+        automaticActionCount: actions.filter((action) => action.safety === "automatic").length,
+        reviewActionCount: actions.filter((action) => action.safety === "review")
+            .length,
+        operatorActionCount: actions.filter((action) => action.safety === "operator").length,
+        executionActionCount: actions.filter((action) => action.safety === "execution").length,
+    };
+}
+// implements REQ-agent-guided-migration-orchestration
+export function buildMigrationPlan(input = {}) {
+    const actions = dependencyOrder([...(input.actions ?? [])].sort(actionSort));
+    const evaluatedDomains = uniqueSorted(input.evaluatedDomains);
+    const incompleteDomains = uniqueSorted(input.incompleteDomains);
+    const expected = {
+        branch: input.expected?.branch ?? null,
+        kbBranch: input.expected?.kbBranch ?? null,
+        kbSnapshotId: input.expected?.kbSnapshotId ?? null,
+        workspaceSnapshot: input.expected?.workspaceSnapshot ?? null,
+        configHash: input.expected?.configHash ?? null,
+    };
+    const body = {
+        version: MIGRATION_PLAN_VERSION,
+        expected,
+        scope: {
+            evaluatedDomains,
+            incompleteDomains,
+            complete: incompleteDomains.length === 0,
+        },
+        actions,
+        diagnostics: [...(input.diagnostics ?? [])].sort(),
+    };
+    const planHash = migrationPlanHash(body);
+    const summary = summarize(actions);
+    const status = actions.length === 0 && incompleteDomains.length === 0
+        ? "no_actions"
+        : actions.length > 0 && summary.readyActionCount === 0
+            ? "blocked"
+            : incompleteDomains.length > 0 || summary.blockedActionCount > 0
+                ? "partial"
+                : "ready";
+    return {
+        ...body,
+        planHash,
+        status,
+        summary,
+    };
+}
+export function mergeMigrationPlans(plans) {
+    if (plans.length === 0)
+        return buildMigrationPlan();
+    const first = plans[0];
+    if (first === undefined)
+        return buildMigrationPlan();
+    const actions = new Map();
+    const diagnostics = new Set();
+    const evaluated = new Set();
+    const incomplete = new Set();
+    for (const plan of plans) {
+        for (const action of plan.actions) {
+            const existing = actions.get(action.id);
+            if (existing === undefined || action.state === "ready") {
+                actions.set(action.id, action);
+            }
+        }
+        for (const value of plan.diagnostics)
+            diagnostics.add(value);
+        for (const value of plan.scope.evaluatedDomains)
+            evaluated.add(value);
+        for (const value of plan.scope.incompleteDomains)
+            incomplete.add(value);
+    }
+    return buildMigrationPlan({
+        expected: first.expected,
+        evaluatedDomains: [...evaluated],
+        incompleteDomains: [...incomplete],
+        actions: [...actions.values()],
+        diagnostics: [...diagnostics],
+    });
+}
+function actionDefaults(input) {
+    return {
+        id: input.id ?? "migration-action-unknown",
+        code: input.code ?? "migration_action",
+        category: input.category ?? "quality",
+        state: input.state ?? "ready",
+        safety: input.safety ?? "review",
+        invocation: input.invocation ?? {
+            kind: "review",
+            instruction: "Review this migration action and choose a disposition.",
+        },
+        affectedEntityIds: uniqueSorted(input.affectedEntityIds),
+        affectedFiles: uniqueSorted(input.affectedFiles),
+        dependsOn: uniqueSorted(input.dependsOn),
+        preconditions: input.preconditions ?? [],
+        postconditions: input.postconditions ?? [],
+        evidence: input.evidence ?? {},
+        autoApplicable: input.autoApplicable ?? false,
+        dispositionRequired: input.dispositionRequired ?? false,
+        allowedDispositions: input.allowedDispositions ?? [
+            "fixed",
+            "accepted",
+            "deferred",
+        ],
+    };
+}
+export function migrationAction(input) {
+    return actionDefaults(input);
+}
+export function buildActionsFromCheck(input) {
+    const actions = [];
+    for (const [index, violation] of (input.violations ?? []).entries()) {
+        const rule = typeof violation.rule === "string" ? violation.rule : "check";
+        const entityId = typeof violation.entityId === "string" ? violation.entityId : "";
+        const suggestion = typeof violation.suggestion === "string"
+            ? violation.suggestion
+            : typeof violation.description === "string"
+                ? violation.description
+                : "Review the blocking validation violation.";
+        actions.push(migrationAction({
+            id: `check-${rule}-${entityId || "workspace"}-${index + 1}`,
+            code: `check_${rule}`,
+            category: "quality",
+            safety: "review",
+            invocation: { kind: "review", instruction: suggestion },
+            affectedEntityIds: entityId ? [entityId] : [],
+            evidence: { violation },
+            dispositionRequired: false,
+        }));
+    }
+    for (const [index, diagnostic] of (input.qualityDiagnostics ?? []).entries()) {
+        const id = typeof diagnostic.id === "string" ? diagnostic.id : "quality";
+        const entityId = typeof diagnostic.entityId === "string" ? diagnostic.entityId : "";
+        const suggestion = typeof diagnostic.suggestion === "string"
+            ? diagnostic.suggestion
+            : "Review this quality diagnostic.";
+        const blocking = diagnostic.blocking === true;
+        actions.push(migrationAction({
+            id: `diagnostic-${id}-${entityId || "workspace"}-${index + 1}`,
+            code: `quality_${id}`,
+            category: "quality",
+            safety: blocking ? "review" : "review",
+            invocation: { kind: "review", instruction: suggestion },
+            affectedEntityIds: entityId ? [entityId] : [],
+            affectedFiles: Array.isArray(diagnostic.files)
+                ? diagnostic.files.filter((value) => typeof value === "string")
+                : [],
+            evidence: { diagnostic },
+            dispositionRequired: true,
+        }));
+    }
+    return actions;
+}
+export function buildActionsFromCoverage(input) {
+    const actions = [];
+    const batches = Array.isArray(input.repairPlan?.batches)
+        ? input.repairPlan.batches.filter(isRecord)
+        : [];
+    for (const batch of batches) {
+        const id = typeof batch.id === "string" ? batch.id : "repair-batch";
+        const phase = typeof batch.phase === "string" ? batch.phase : "review";
+        const req = typeof batch.requirementId === "string" ? batch.requirementId : "";
+        const ready = batch.state === "ready";
+        const automatic = phase === "source_coordinates";
+        actions.push(migrationAction({
+            id: `coverage-${id}`,
+            code: `coverage_${phase}`,
+            category: phase === "verification_evidence" ? "verification" : "semantic",
+            state: ready ? "ready" : "blocked",
+            safety: automatic
+                ? "automatic"
+                : phase === "verification_evidence"
+                    ? "execution"
+                    : "review",
+            invocation: automatic
+                ? {
+                    kind: "cli",
+                    command_argv: ["kibi", "sync", "--refresh-symbol-coordinates"],
+                }
+                : {
+                    kind: "review",
+                    instruction: typeof batch.objective === "string"
+                        ? batch.objective
+                        : "Apply the dependency-ordered coverage repair batch.",
+                },
+            affectedEntityIds: req ? [req] : [],
+            dependsOn: Array.isArray(batch.dependsOn)
+                ? batch.dependsOn
+                    .filter((value) => typeof value === "string")
+                    .map((value) => `coverage-${value}`)
+                : [],
+            evidence: { batch },
+            autoApplicable: automatic && ready,
+            dispositionRequired: !automatic,
+        }));
+    }
+    const repairs = Array.isArray(input.symbolRepairPlan?.repairs)
+        ? input.symbolRepairPlan.repairs.filter(isRecord)
+        : [];
+    for (const repair of repairs) {
+        const symbolId = typeof repair.symbolId === "string" ? repair.symbolId : "symbol";
+        const action = typeof repair.action === "string" ? repair.action : "review";
+        const automatic = action === "refresh_coordinates";
+        actions.push(migrationAction({
+            id: `symbol-${action}-${symbolId}`,
+            code: `symbol_${action}`,
+            category: "symbol",
+            safety: automatic ? "automatic" : "review",
+            invocation: automatic
+                ? {
+                    kind: "cli",
+                    command_argv: ["kibi", "sync", "--refresh-symbol-coordinates"],
+                }
+                : {
+                    kind: "review",
+                    instruction: `Review ${action} for ${symbolId} using current extraction and Git evidence.`,
+                },
+            affectedEntityIds: [symbolId],
+            evidence: { repair },
+            autoApplicable: automatic,
+            dispositionRequired: !automatic,
+        }));
+    }
+    return actions;
+}
+export function readMigrationConfigStatus(workspaceRoot) {
+    const status = readKbManifestStatus(workspaceRoot);
+    if (status.state === "ok") {
+        return {
+            status: getSchemaVersionStatus({
+                schemaVersion: status.manifest.schemaVersion,
+            }).status,
+            currentVersion: status.manifest.schemaVersion,
+            latestVersion: getSchemaVersionStatus({
+                schemaVersion: status.manifest.schemaVersion,
+            }).latestVersion,
+            needsMigration: getSchemaVersionStatus({
+                schemaVersion: status.manifest.schemaVersion,
+            }).needsMigration,
+            warning: null,
+            configHash: status.manifestHash,
+        };
+    }
+    const legacySchemaVersion = readLegacySchemaVersion(workspaceRoot);
+    const schemaStatus = getSchemaVersionStatus(legacySchemaVersion === null
+        ? undefined
+        : { schemaVersion: legacySchemaVersion });
+    return {
+        ...schemaStatus,
+        currentVersion: normalizeSchemaVersion(legacySchemaVersion),
+        configHash: null,
+        warning: status.warning,
+    };
+}
+/**
+ * Best-effort recognition of a legacy `.kb/config.json` schemaVersion for
+ * repositories that have not yet run the storage migration. Malformed
+ * documents return null so status reports demand repair rather than
+ * silently treating the KB as uninitialized.
+ */
+function readLegacySchemaVersion(workspaceRoot) {
+    const legacyPath = path.join(workspaceRoot, ".kb", "config.json");
+    if (!existsSync(legacyPath))
+        return null;
+    try {
+        const parsed = JSON.parse(readFileSync(legacyPath, "utf8"));
+        return parsed.schemaVersion ?? null;
+    }
+    catch {
+        return "";
+    }
+}
+// implements REQ-agent-guided-migration-orchestration
+export function buildActionsFromStatus(input) {
+    const actions = [];
+    const attachment = input.branchAttachment;
+    const store = input.branchStore;
+    const configStatus = input.configStatus ?? readMigrationConfigStatus(input.workspaceRoot);
+    const branch = typeof attachment?.gitBranch === "string" ? attachment.gitBranch : null;
+    const kbBranch = typeof attachment?.kbBranch === "string" ? attachment.kbBranch : null;
+    if (attachment?.migrationRequired === true) {
+        const legacy = attachment.kind === "legacy_compat" &&
+            typeof branch === "string" &&
+            typeof kbBranch === "string";
+        actions.push(migrationAction({
+            id: "branch-legacy-attachment",
+            code: legacy ? "legacy_branch_storage" : "ambiguous_branch_attachment",
+            category: "branch",
+            state: legacy ? "ready" : "blocked",
+            safety: legacy ? "automatic" : "operator",
+            invocation: legacy
+                ? {
+                    kind: "cli",
+                    command_argv: [
+                        "kibi",
+                        "branch",
+                        "migrate",
+                        "--from",
+                        kbBranch,
+                        "--to",
+                        branch,
+                        "--apply",
+                    ],
+                }
+                : {
+                    kind: "review",
+                    instruction: "Resolve branch and KB provenance explicitly; Kibi will not guess or rename Git branches.",
+                },
+            affectedFiles: [
+                typeof attachment.storePath === "string"
+                    ? attachment.storePath
+                    : ".kb/branches",
+            ],
+            evidence: { attachment },
+            autoApplicable: legacy,
+            dispositionRequired: !legacy,
+        }));
+    }
+    const storeState = typeof store?.state === "string" ? store.state : null;
+    const legacyStorageMigrationRequired = legacyConfigExists(input.workspaceRoot);
+    if (storeState === "missing") {
+        actions.push(migrationAction({
+            id: "branch-store-ensure",
+            code: "missing_exact_branch_store",
+            category: "storage",
+            safety: "automatic",
+            invocation: { kind: "cli", command_argv: ["kibi", "branch", "ensure"] },
+            affectedFiles: [
+                typeof store?.path === "string" ? store.path : ".kb/branches",
+            ],
+            evidence: { store },
+            autoApplicable: true,
+        }));
+    }
+    else if (storeState === "incomplete" || storeState === "unreadable") {
+        actions.push(migrationAction({
+            id: "branch-store-recover",
+            code: "damaged_exact_branch_store",
+            category: "storage",
+            safety: "automatic",
+            invocation: {
+                kind: "cli",
+                command_argv: ["kibi", "branch", "recover", "--apply"],
+            },
+            affectedFiles: [
+                typeof store?.path === "string" ? store.path : ".kb/branches",
+            ],
+            evidence: { store, backupRequired: true },
+            autoApplicable: true,
+        }));
+    }
+    if (configStatus.needsMigration || legacyStorageMigrationRequired) {
+        actions.push(migrationAction({
+            id: "schema-config-upgrade",
+            code: configStatus.status === "invalid"
+                ? "invalid_schema_version"
+                : legacyStorageMigrationRequired
+                    ? "legacy_storage_migration"
+                    : "schema_version_upgrade",
+            category: "schema",
+            state: configStatus.status === "newer" ? "blocked" : "ready",
+            safety: configStatus.status === "newer" ? "operator" : "automatic",
+            invocation: { kind: "cli", command_argv: ["kibi", "migrate", "--yes"] },
+            affectedFiles: [
+                ".kb/manifest.json",
+                ".kb/migrations",
+                ".kb/config.json",
+            ],
+            evidence: { configStatus },
+            dependsOn: storeState === "missing" ? ["branch-store-ensure"] : [],
+            autoApplicable: configStatus.status !== "newer",
+        }));
+    }
+    for (const reason of input.staleReasons ?? []) {
+        const code = typeof reason.code === "string" ? reason.code : "stale_source";
+        const file = typeof reason.path === "string" ? reason.path : "";
+        actions.push(migrationAction({
+            id: `freshness-${code}-${file}`,
+            code,
+            category: "freshness",
+            safety: "review",
+            invocation: {
+                kind: "review",
+                instruction: typeof reason.remediation === "string"
+                    ? reason.remediation
+                    : "Refresh or reconcile the stale source, then run kibi sync and read back status.",
+            },
+            affectedFiles: file ? [file] : [],
+            evidence: { reason },
+            dispositionRequired: true,
+        }));
+    }
+    if (input.verificationSnapshotAvailable === false) {
+        actions.push(migrationAction({
+            id: "verification-snapshot-unavailable",
+            code: "verification_snapshot_unavailable",
+            category: "verification",
+            safety: "operator",
+            invocation: {
+                kind: "review",
+                instruction: "Use a runtime that can compute a workspace verification snapshot before claiming proof.",
+            },
+            evidence: { verificationSnapshotAvailable: false },
+            dispositionRequired: true,
+        }));
+    }
+    else if (input.verificationSnapshotDirty === true) {
+        actions.push(migrationAction({
+            id: "verification-snapshot-dirty",
+            code: "verification_snapshot_dirty",
+            category: "verification",
+            safety: "review",
+            invocation: {
+                kind: "review",
+                instruction: "Resolve or intentionally record the listed dirty workspace paths before reusing or creating proof receipts.",
+            },
+            evidence: { verificationSnapshotDirty: true },
+            dispositionRequired: true,
+        }));
+    }
+    const incompleteDomains = actions.some((action) => action.code === "damaged_exact_branch_store" ||
+        action.code === "ambiguous_branch_attachment" ||
+        action.code === "missing_exact_branch_store" ||
+        action.code === "schema_version_upgrade" ||
+        action.code === "invalid_schema_version" ||
+        action.code === "legacy_storage_migration")
+        ? ["kb"]
+        : [];
+    return buildMigrationPlan({
+        expected: {
+            branch,
+            kbBranch,
+            kbSnapshotId: input.kbSnapshotId ?? null,
+            workspaceSnapshot: input.workspaceSnapshot ?? null,
+            configHash: configStatus.configHash,
+        },
+        evaluatedDomains: [
+            "package",
+            "branch",
+            "storage",
+            "schema",
+            "freshness",
+            "verification",
+        ],
+        incompleteDomains,
+        actions,
+    });
+}

package/dist/public/operations/node-ports.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"node-ports.d.ts","sourceRoot":"","sources":["../../../src/public/operations/node-ports.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,cAAc,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAE/E,KAAK,kBAAkB,GAAG,cAAc,GAAG;IACzC,QAAQ,CAAC,IAAI,EAAE,CACb,QAAQ,EAAE,SAAS,MAAM,EAAE,EAC3B,OAAO,EAAE;QAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,CAAA;KAAE,KACjE,OAAO,CAAC,SAAS,MAAM,EAAE,CAAC,CAAC;CACjC,CAAC;AAEF,KAAK,WAAW,GAAG,OAAO,GAAG;IAC3B,QAAQ,CAAC,YAAY,EAAE,CACrB,aAAa,EAAE,MAAM,EACrB,KAAK,EAAE,SAAS,MAAM,EAAE,KACrB,OAAO,CAAC,SAAS,MAAM,EAAE,CAAC,CAAC;CACjC,CAAC;AA2HF,eAAO,MAAM,cAAc,EAAE,kBAkB5B,CAAC;AAEF,eAAO,MAAM,OAAO,EAAE,WAiBrB,CAAC;AAEF,eAAO,MAAM,WAAW,EAAE,WAEzB,CAAC"}
+{"version":3,"file":"node-ports.d.ts","sourceRoot":"","sources":["../../../src/public/operations/node-ports.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,cAAc,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAE/E,KAAK,kBAAkB,GAAG,cAAc,GAAG;IACzC,QAAQ,CAAC,IAAI,EAAE,CACb,QAAQ,EAAE,SAAS,MAAM,EAAE,EAC3B,OAAO,EAAE;QAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,CAAA;KAAE,KACjE,OAAO,CAAC,SAAS,MAAM,EAAE,CAAC,CAAC;CACjC,CAAC;AAEF,KAAK,WAAW,GAAG,OAAO,GAAG;IAC3B,QAAQ,CAAC,YAAY,EAAE,CACrB,aAAa,EAAE,MAAM,EACrB,KAAK,EAAE,SAAS,MAAM,EAAE,KACrB,OAAO,CAAC,SAAS,MAAM,EAAE,CAAC,CAAC;CACjC,CAAC;AAkMF,eAAO,MAAM,cAAc,EAAE,kBAoB5B,CAAC;AAEF,eAAO,MAAM,OAAO,EAAE,WAiBrB,CAAC;AAEF,eAAO,MAAM,WAAW,EAAE,WAEzB,CAAC"}

package/dist/public/operations/node-ports.js

@@ -1,15 +1,28 @@
-import { execFile } from "node:child_process";
+import { execFile, execFileSync } from "node:child_process";
 import { createHash } from "node:crypto";
+import * as fsSync from "node:fs";
 import * as fs from "node:fs/promises";
 import path from "node:path";
 import { promisify } from "node:util";
 import fg from "fast-glob";
 import { createRepoIgnorePolicy } from "../ignore-policy.js";
 const execFileAsync = promisify(execFile);
-const SNAPSHOT_EXCLUDED_PREFIXES = [".changeset/", ".kb/", "docs/"];
+const SNAPSHOT_EXCLUDED_PREFIXES = [
+    ".changeset/",
+    ".kb/branches/",
+    ".kb/recovery/",
+    ".kb/verification/",
+    ".kb/briefs/",
+    ".kb/migrations/",
+    "docs/",
+];
 const ALWAYS_IGNORED_GLOBS = [
     "**/.git/**",
-    "**/.kb/**",
+    "**/.kb/branches/**",
+    "**/.kb/recovery/**",
+    "**/.kb/verification/**",
+    "**/.kb/briefs/**",
+    "**/.kb/migrations/**",
     "**/node_modules/**",
     "**/vendor/**",
     "**/vendors/**",
@@ -53,12 +66,30 @@ function withoutVerificationReceiptFrontmatter(content) {
     return retained.join("");
 }
 function snapshotFileContent(relativePath, content) {
-    if (relativePath.startsWith("documentation/") &&
-        relativePath.endsWith(".md")) {
+    if (relativePath.endsWith(".md")) {
         return Buffer.from(withoutVerificationReceiptFrontmatter(content.toString("utf8")));
     }
     return content;
 }
+/**
+ * A tracked markdown file whose only change is verification-receipt frontmatter
+ * cannot alter the snapshot hash (receipts are stripped before hashing), so it
+ * must not mark the workspace dirty either. CI proof runs append receipts to
+ * tracked proof documents before reporting, and would otherwise always surface
+ * a dirty-workspace warning.
+ */
+function isReceiptOnlyMarkdownChange(workspaceRoot, relativePath) {
+    if (!relativePath.endsWith(".md"))
+        return false;
+    try {
+        const working = snapshotFileContent(relativePath, fsSync.readFileSync(path.join(workspaceRoot, relativePath)));
+        const committed = execFileSync("git", ["-C", workspaceRoot, "show", `HEAD:${relativePath}`], { encoding: "buffer", maxBuffer: 64 * 1024 * 1024 });
+        return working.equals(snapshotFileContent(relativePath, committed));
+    }
+    catch {
+        return false;
+    }
+}
 async function workspaceSnapshot(workspaceRoot) {
     const { stdout: listed } = await execFileAsync("git", [
         "-C",
@@ -76,7 +107,7 @@ async function workspaceSnapshot(workspaceRoot) {
         .filter(includedSnapshotPath)
         .sort();
     const digest = createHash("sha256");
-    digest.update("kibi.workspace-snapshot.v1\0");
+    digest.update("kibi.workspace-snapshot.v2\0");
     for (const relativePath of paths) {
         digest.update(relativePath);
         digest.update("\0");
@@ -98,12 +129,39 @@ async function workspaceSnapshot(workspaceRoot) {
         "status",
         "--porcelain=v1",
         "--untracked-files=normal",
+        "-z",
     ], { maxBuffer: 16 * 1024 * 1024 });
+    const rawChanges = status.split("\0").filter(Boolean);
+    const changes = [];
+    for (let index = 0; index < rawChanges.length; index++) {
+        const entry = rawChanges[index] ?? "";
+        const statusCode = entry.slice(0, 2);
+        const relativePath = entry.slice(3).replaceAll("\\", "/");
+        const previous = rawChanges[index + 1];
+        const isRenameOrCopy = statusCode[0] === "R" || statusCode[0] === "C";
+        const previousPath = isRenameOrCopy && previous ? previous.replaceAll("\\", "/") : undefined;
+        const receiptOnly = statusCode.includes("M") &&
+            includedSnapshotPath(relativePath) &&
+            isReceiptOnlyMarkdownChange(workspaceRoot, relativePath);
+        changes.push({
+            path: relativePath,
+            status: statusCode,
+            snapshotRelevant: (includedSnapshotPath(relativePath) && !receiptOnly) ||
+                (previousPath !== undefined && includedSnapshotPath(previousPath)),
+            ...(previousPath !== undefined ? { previousPath } : {}),
+        });
+        if (previousPath !== undefined)
+            index++;
+    }
+    const maxChanges = 200;
     return {
-        version: "kibi.workspace-snapshot.v1",
+        version: "kibi.workspace-snapshot.v2",
         hash: digest.digest("hex"),
-        dirty: status.trim().length > 0,
+        dirty: changes.some((change) => change.snapshotRelevant),
         fileCount: paths.length,
+        changes: changes.slice(0, maxChanges),
+        changeCount: changes.length,
+        changesTruncated: changes.length > maxChanges,
     };
 }
 export const nodeFilesystem = {
@@ -111,10 +169,12 @@ export const nodeFilesystem = {
     writeFile: async (filePath, data) => {
         await fs.writeFile(filePath, data, "utf8");
     },
+    rename: (from, to) => fs.rename(from, to),
     mkdir: async (directoryPath) => {
         await fs.mkdir(directoryPath, { recursive: true });
     },
     stat: (filePath) => fs.stat(filePath),
+    unlink: (filePath) => fs.unlink(filePath),
     glob: (patterns, options) => fg([...patterns], {
         cwd: options.cwd,
         onlyFiles: true,

package/dist/public/operations/prolog-json.d.ts

@@ -1,4 +1,18 @@
 import type { PrologPort } from "./runtime-types.js";
+export type JsonBindingDecodeStage = "outer" | "inner";
+/**
+ * A JSON operation result is transported through Prolog's answer printer and
+ * then through the engine frame. Keep decode failures typed and bounded: the
+ * raw binding may contain project-authored data and must never be copied into
+ * diagnostics wholesale.
+ */
+export declare class OperationJsonDecodeError extends Error {
+    readonly code = "engine_result_invalid_json";
+    readonly stage: JsonBindingDecodeStage;
+    readonly rawLength: number;
+    readonly prefixCodePoints: readonly number[];
+    constructor(errorLabel: string, stage: JsonBindingDecodeStage, rawJson: unknown, cause: unknown);
+}
 export declare function runOperationJsonQuery<T>(prolog: PrologPort, fileName: string, goal: string, errorLabel: string): Promise<T>;
 export declare function toPrologAtom(value?: string): string;
 export declare function toPrologList(values?: readonly string[]): string;