kibi-cli 0.19.0 → 1.0.1

package/dist/commands/branch.d.ts

@@ -1,6 +1,42 @@
 export interface BranchEnsureOptions {
     from?: string;
+    workspaceRoot?: string;
 }
+export interface BranchMigrateOptions {
+    from?: string;
+    to?: string;
+    apply?: boolean;
+    /** Hash-bound preview approval required for every mutating migration. */
+    approvalHash?: string;
+    recoverJournal?: string;
+    workspaceRoot?: string;
+}
+export interface BranchRecoverOptions {
+    apply?: boolean;
+    workspaceRoot?: string;
+}
+export interface BranchRestoreOptions {
+    branch?: string;
+    apply?: boolean;
+    workspaceRoot?: string;
+}
+/** Legacy migration changes storage format for one exact branch identity. */
+export declare function isSupportedLegacyBranchMigration(from: string, to: string): boolean;
+export declare function branchMigrationApprovalHash(from: string, to: string, sourcePath: string, targetPath: string): string;
 export declare function branchEnsureCommand(options?: BranchEnsureOptions): Promise<void>;
+/**
+ * Move a legacy branch-named KB into the exact active Git branch namespace.
+ * Preview is the default; --apply is required because this changes tracked
+ * workspace state.
+ */
+export declare function branchMigrateCommand(options?: BranchMigrateOptions): Promise<void>;
+/**
+ * Rebuild an unreadable exact branch store from the current authored sources.
+ * The existing bytes are moved to a Kibi-owned recovery directory only after a
+ * clean staging store has been created successfully.
+ */
+export declare function branchRecoverCommand(options?: BranchRecoverOptions): Promise<void>;
+/** Restore the newest quarantined store for an exact branch identity. */
+export declare function branchRestoreCommand(options?: BranchRestoreOptions): Promise<void>;
 export default branchEnsureCommand;
 //# sourceMappingURL=branch.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"branch.d.ts","sourceRoot":"","sources":["../../src/commands/branch.ts"],"names":[],"mappings":"AA2BA,MAAM,WAAW,mBAAmB;IAClC,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAmDD,wBAAsB,mBAAmB,CACvC,OAAO,CAAC,EAAE,mBAAmB,GAC5B,OAAO,CAAC,IAAI,CAAC,CAsBf;AAED,eAAe,mBAAmB,CAAC"}
+{"version":3,"file":"branch.d.ts","sourceRoot":"","sources":["../../src/commands/branch.ts"],"names":[],"mappings":"AA4CA,MAAM,WAAW,mBAAmB;IAClC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,oBAAoB;IACnC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,yEAAyE;IACzE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,oBAAoB;IACnC,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,oBAAoB;IACnC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,6EAA6E;AAC7E,wBAAgB,gCAAgC,CAC9C,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,GACT,OAAO,CAET;AAuBD,wBAAgB,2BAA2B,CACzC,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,EACV,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,GACjB,MAAM,CAeR;AAgHD,wBAAsB,mBAAmB,CACvC,OAAO,CAAC,EAAE,mBAAmB,GAC5B,OAAO,CAAC,IAAI,CAAC,CA2Bf;AAED;;;;GAIG;AACH,wBAAsB,oBAAoB,CACxC,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,IAAI,CAAC,CA2Kf;AAED;;;;GAIG;AACH,wBAAsB,oBAAoB,CACxC,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,IAAI,CAAC,CAyFf;AAED,yEAAyE;AACzE,wBAAsB,oBAAoB,CACxC,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,IAAI,CAAC,CAkDf;AAED,eAAe,mBAAmB,CAAC"}

package/dist/commands/branch.js

@@ -15,64 +15,395 @@
  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 { createHash } from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { copyCleanSnapshot, getBranchDiagnostic, isValidBranchName, resolveActiveBranch, } from "../utils/branch-resolver.js";
-function resolveExplicitFromBranch(fromBranch) {
-    if (!isValidBranchName(fromBranch)) {
-        console.warn(`Warning: invalid branch name provided via --from: '${fromBranch}'`);
-        return null;
-    }
-    const fromPath = path.join(process.cwd(), ".kb/branches", fromBranch);
-    if (fs.existsSync(fromPath)) {
-        return fromBranch;
-    }
-    console.warn(`Warning: --from branch '${fromBranch}' KB does not exist`);
-    return null;
+import { EngineClient, acquireEnginePublicationLease, engineSocketPath, } from "../engine.js";
+import { getBranchDiagnostic, isValidBranchName, resolveActiveBranch, resolveBranchAttachment, } from "../utils/branch-resolver.js";
+import { branchStoreManifestMatches, branchStoreManifestPath, branchStorePath, branchStoresRoot, ensureBranchStoreManifest, expectedBranchStoreManifest, legacyBranchStorePath, readBranchStoreManifest, } from "../utils/branch-store-locator.js";
+import { inspectBranchStore } from "../utils/branch-store.js";
+/** Legacy migration changes storage format for one exact branch identity. */
+export function isSupportedLegacyBranchMigration(from, to) {
+    return from === to;
 }
-function resolveDefaultSourceBranch() {
-    // No default branch concept - branches are independent
-    // When --from is not specified, an empty branch KB will be created
-    return null;
-}
-function determineSourceBranch(explicitFromBranch) {
-    if (explicitFromBranch) {
-        const fromResult = resolveExplicitFromBranch(explicitFromBranch);
-        if (fromResult) {
-            return fromResult;
+function hashLegacyStore(sourcePath) {
+    const hash = createHash("sha256");
+    const visit = (directory, relative = "") => {
+        for (const entry of fs
+            .readdirSync(directory, { withFileTypes: true })
+            .sort((left, right) => left.name.localeCompare(right.name))) {
+            const absolute = path.join(directory, entry.name);
+            const child = relative ? path.join(relative, entry.name) : entry.name;
+            if (entry.isDirectory())
+                visit(absolute, child);
+            else if (entry.isFile()) {
+                hash.update(child.replaceAll(path.sep, "/"));
+                hash.update("\0");
+                hash.update(fs.readFileSync(absolute));
+                hash.update("\0");
+            }
         }
+    };
+    visit(sourcePath);
+    return hash.digest("hex");
+}
+export function branchMigrationApprovalHash(from, to, sourcePath, targetPath) {
+    const sourceHash = hashLegacyStore(sourcePath);
+    return createHash("sha256")
+        .update(JSON.stringify({
+        version: 2,
+        from,
+        to,
+        sourcePath,
+        targetPath,
+        sourceHash,
+        manifestVersion: expectedBranchStoreManifest(to).version,
+    }))
+        .digest("hex");
+}
+function migrationJournalPath(workspaceRoot, id) {
+    if (!/^[A-Za-z0-9._-]+$/.test(id)) {
+        throw new Error("branch migration journal ID is invalid");
     }
-    return resolveDefaultSourceBranch();
+    return path.join(workspaceRoot, ".kb", "recovery", "branch-migrations", `${id}.json`);
+}
+function writeMigrationJournal(journalPath, journal) {
+    fs.writeFileSync(journalPath, `${JSON.stringify(journal, null, 2)}\n`, {
+        mode: 0o600,
+    });
 }
-function createBranchKbFromSource(sourceBranch, targetBranch) {
-    const sourcePath = path.join(process.cwd(), ".kb/branches", sourceBranch);
-    const targetPath = path.join(process.cwd(), ".kb/branches", targetBranch);
-    copyCleanSnapshot(sourcePath, targetPath);
-    console.log(`Created branch KB: ${targetBranch} (from ${sourceBranch})`);
+function recoverBranchMigration(workspaceRoot, id, apply) {
+    const journalPath = migrationJournalPath(workspaceRoot, id);
+    const journal = JSON.parse(fs.readFileSync(journalPath, "utf8"));
+    if (journal.version !== 2)
+        throw new Error("Unsupported branch migration journal version");
+    const root = path.resolve(workspaceRoot);
+    const paths = ["sourcePath", "targetPath", "stagingPath", "backupPath"].map((key) => path.resolve(root, String(journal[key])));
+    if (paths.some((candidate) => !candidate.startsWith(`${root}${path.sep}`))) {
+        throw new Error("Branch migration journal path escapes workspace");
+    }
+    const [sourcePath, targetPath, stagingPath, backupPath] = paths;
+    if (!sourcePath || !targetPath || !stagingPath || !backupPath) {
+        throw new Error("Branch migration journal is incomplete");
+    }
+    console.log(`Branch migration recovery preview: ${id}`);
+    console.log(`State: ${String(journal.state)}`);
+    console.log(`Source: ${sourcePath}`);
+    console.log(`Target: ${targetPath}`);
+    console.log(`Backup: ${backupPath}`);
+    if (!apply) {
+        console.log("Preview only. Re-run with --apply to recover this journal.");
+        return;
+    }
+    if (journal.state === "committed")
+        return;
+    if (journal.state === "prepared") {
+        if (fs.existsSync(sourcePath) &&
+            fs.existsSync(stagingPath) &&
+            !fs.existsSync(targetPath)) {
+            fs.renameSync(sourcePath, backupPath);
+            writeMigrationJournal(journalPath, {
+                ...journal,
+                state: "legacy_quarantined",
+            });
+        }
+        else if (fs.existsSync(sourcePath) && fs.existsSync(targetPath)) {
+            throw new Error("Recovery found both legacy source and target; refusing to choose a winner");
+        }
+    }
+    if (fs.existsSync(backupPath) &&
+        fs.existsSync(stagingPath) &&
+        !fs.existsSync(targetPath)) {
+        fs.renameSync(stagingPath, targetPath);
+        if (!branchStoreManifestMatches(targetPath, String(journal.to))) {
+            throw new Error("Recovered target manifest does not match the exact branch identity");
+        }
+        writeMigrationJournal(journalPath, {
+            ...journal,
+            state: "target_published",
+        });
+    }
+    if (fs.existsSync(backupPath) && fs.existsSync(targetPath)) {
+        if (!branchStoreManifestMatches(targetPath, String(journal.to))) {
+            const corrupt = `${targetPath}.corrupt-${Date.now()}`;
+            fs.renameSync(targetPath, corrupt);
+            fs.renameSync(backupPath, targetPath);
+            throw new Error(`Invalid target moved to ${corrupt}; verified legacy backup restored`);
+        }
+        writeMigrationJournal(journalPath, { ...journal, state: "committed" });
+        return;
+    }
+    throw new Error(`Migration journal ${id} remains incomplete; rerun its recovery preview`);
 }
-function createEmptyBranchKb(branch) {
-    const kbPath = path.join(process.cwd(), ".kb/branches", branch);
-    fs.mkdirSync(kbPath, { recursive: true });
-    console.log(`Created branch KB: ${branch} (empty schema)`);
+function createEmptyBranchKb(branch, workspaceRoot) {
+    const kbPath = ensureBranchStoreManifest(workspaceRoot, branch);
+    console.log(`Created branch KB: ${branch} (${kbPath})`);
 }
 export async function branchEnsureCommand(options) {
-    const branchResult = resolveActiveBranch(process.cwd());
+    const workspaceRoot = path.resolve(options?.workspaceRoot ?? process.cwd());
+    const branchResult = resolveBranchAttachment(workspaceRoot);
     if ("error" in branchResult) {
         console.error(getBranchDiagnostic(undefined, branchResult.error));
         throw new Error(`Failed to resolve active branch: ${branchResult.error}`);
     }
-    const currentBranch = branchResult.branch;
-    const kbPath = path.join(process.cwd(), ".kb/branches", currentBranch);
+    if (branchResult.migrationRequired) {
+        throw new Error(`Branch ensure blocked by legacy storage at ${branchResult.storePath}. Run an explicit 'kibi branch migrate --from ${branchResult.kbBranch} --to ${branchResult.gitBranch} --apply' first.`);
+    }
+    const currentBranch = branchResult.kbBranch;
+    const kbPath = branchResult.storePath;
+    if (options?.from !== undefined) {
+        throw new Error("branch ensure --from was removed: new branch stores compile from the current checkout's tracked sources. Use branch migrate for an explicit legacy-store move.");
+    }
     if (fs.existsSync(kbPath)) {
         console.log(`Branch KB already exists: ${currentBranch}`);
         return;
     }
-    const sourceBranch = determineSourceBranch(options?.from);
-    if (sourceBranch) {
-        createBranchKbFromSource(sourceBranch, currentBranch);
+    createEmptyBranchKb(currentBranch, workspaceRoot);
+}
+/**
+ * Move a legacy branch-named KB into the exact active Git branch namespace.
+ * Preview is the default; --apply is required because this changes tracked
+ * workspace state.
+ */
+export async function branchMigrateCommand(options = {}) {
+    const workspaceRoot = path.resolve(options.workspaceRoot ?? process.cwd());
+    if (options.recoverJournal !== undefined) {
+        recoverBranchMigration(workspaceRoot, options.recoverJournal, options.apply === true);
+        return;
+    }
+    const from = options.from;
+    if (!from || !isValidBranchName(from)) {
+        throw new Error("branch migrate requires a valid --from branch name");
+    }
+    const active = resolveActiveBranch(workspaceRoot);
+    if ("error" in active) {
+        throw new Error(`Failed to resolve active branch: ${active.error}`);
+    }
+    const to = options.to;
+    if (!to || !isValidBranchName(to)) {
+        throw new Error("branch migrate requires an explicit valid --to branch name");
+    }
+    if (active.branch !== to) {
+        throw new Error(`branch migrate --to '${to}' does not match the active Git branch '${active.branch}'`);
+    }
+    if (!isSupportedLegacyBranchMigration(from, to)) {
+        throw new Error("branch migrate only supports a same-identity literal-to-hashed migration; every cross-branch move is refused");
+    }
+    // `from === to` is valid for the same-identity storage bridge: it names the
+    // same exact Git identity while moving a legacy literal directory into its
+    // hashed compiled-store path. The explicit pair is still required; no
+    // rename is inferred from commit history.
+    const root = branchStoresRoot(workspaceRoot);
+    const sourcePath = legacyBranchStorePath(workspaceRoot, from);
+    const targetPath = branchStorePath(workspaceRoot, to);
+    if (!fs.existsSync(sourcePath)) {
+        throw new Error(`Legacy source KB does not exist: ${sourcePath}`);
+    }
+    if (fs.existsSync(targetPath)) {
+        throw new Error(`Target branch KB already exists: ${targetPath}`);
+    }
+    const approvalHash = branchMigrationApprovalHash(from, to, sourcePath, targetPath);
+    console.log(`Branch KB migration preview: ${from} -> ${to}`);
+    console.log(`Source: ${sourcePath}`);
+    console.log(`Target: ${targetPath}`);
+    console.log(`Approval hash: ${approvalHash}`);
+    if (!options.apply) {
+        console.log("Preview only. Re-run with --apply to move the branch KB.");
+        return;
+    }
+    if (!options.approvalHash) {
+        throw new Error(`branch migrate requires --approval-hash from the preview (${approvalHash})`);
+    }
+    if (options.approvalHash !== approvalHash) {
+        throw new Error(`branch migrate approval hash mismatch; expected ${approvalHash}`);
+    }
+    const publicationLease = acquireEnginePublicationLease(workspaceRoot, from);
+    try {
+        const engine = new EngineClient({
+            workspaceRoot,
+            branch: from,
+            timeout: 2_000,
+            allowPublicationLock: true,
+        });
+        const engineSocket = engineSocketPath(workspaceRoot, from);
+        try {
+            if (fs.existsSync(engineSocket))
+                await engine.start(false);
+            if (engine.isRunning()) {
+                await engine.stop(false);
+            }
+            else if (fs.existsSync(engineSocket)) {
+                throw new Error(`Kibi engine socket remains present but is not reachable: ${engineSocket}`);
+            }
+        }
+        catch (error) {
+            throw new Error(`Branch migration blocked: engine shutdown failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        finally {
+            await engine.terminate();
+        }
+        if (branchMigrationApprovalHash(from, to, sourcePath, targetPath) !==
+            approvalHash) {
+            throw new Error("Branch migration source changed after engine shutdown; rerun the preview");
+        }
+        fs.mkdirSync(root, { recursive: true });
+        const migrationId = `${Date.now()}-${from.replaceAll("/", "__")}-${to.replaceAll("/", "__")}`;
+        const journalPath = path.join(workspaceRoot, ".kb", "recovery", "branch-migrations", `${migrationId}.json`);
+        const stagingPath = `${targetPath}.staging-${process.pid}-${Date.now()}`;
+        const backupPath = path.join(workspaceRoot, ".kb", "recovery", "branch-migrations", `${migrationId}-legacy`);
+        fs.mkdirSync(path.dirname(backupPath), { recursive: true });
+        const journal = {
+            version: 2,
+            from,
+            to,
+            sourcePath: path.relative(workspaceRoot, sourcePath),
+            targetPath: path.relative(workspaceRoot, targetPath),
+            stagingPath: path.relative(workspaceRoot, stagingPath),
+            backupPath: path.relative(workspaceRoot, backupPath),
+            approvalHash,
+            state: "prepared",
+        };
+        writeMigrationJournal(journalPath, { ...journal });
+        try {
+            fs.cpSync(sourcePath, stagingPath, {
+                recursive: true,
+                errorOnExist: true,
+            });
+            fs.writeFileSync(branchStoreManifestPath(stagingPath), `${JSON.stringify(expectedBranchStoreManifest(to), null, 2)}\n`, { mode: 0o600 });
+            fs.renameSync(sourcePath, backupPath);
+            writeMigrationJournal(journalPath, {
+                ...journal,
+                state: "legacy_quarantined",
+            });
+            fs.renameSync(stagingPath, targetPath);
+            if (!branchStoreManifestMatches(targetPath, to)) {
+                throw new Error("migrated branch store manifest verification failed");
+            }
+            writeMigrationJournal(journalPath, {
+                ...journal,
+                state: "target_published",
+            });
+            writeMigrationJournal(journalPath, { ...journal, state: "committed" });
+        }
+        catch (error) {
+            // Leave the hash-bound journal and any staging bytes for explicit crash
+            // recovery; never silently select a winner between source and target.
+            throw new Error(`Branch migration failed before authoritative completion; recover ${journalPath}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        console.log(`Migrated branch KB to exact Git branch '${to}'.`);
+        console.log(`Legacy store preserved at ${backupPath}.`);
+        console.log(`Migration journal: ${journalPath}.`);
+    }
+    finally {
+        publicationLease.release();
+    }
+}
+/**
+ * Rebuild an unreadable exact branch store from the current authored sources.
+ * The existing bytes are moved to a Kibi-owned recovery directory only after a
+ * clean staging store has been created successfully.
+ */
+export async function branchRecoverCommand(options = {}) {
+    const workspaceRoot = path.resolve(options.workspaceRoot ?? process.cwd());
+    const attachment = resolveBranchAttachment(workspaceRoot);
+    if ("error" in attachment) {
+        throw new Error(`Failed to resolve active branch: ${attachment.error}`);
+    }
+    if (attachment.kind !== "exact") {
+        throw new Error("branch recover requires an exact Git/KB attachment; migrate legacy storage before recovery.");
+    }
+    const inspection = inspectBranchStore(workspaceRoot, attachment.kbBranch);
+    if (inspection.state === "missing") {
+        throw new Error(`Branch KB is missing at ${inspection.path}; run 'kibi branch ensure' instead.`);
+    }
+    const stamp = new Date().toISOString().replaceAll(":", "-");
+    const backupPath = path.join(workspaceRoot, ".kb", "recovery", attachment.kbBranch, stamp);
+    console.log(`Branch KB recovery preview: ${attachment.kbBranch}`);
+    console.log(`Store: ${inspection.path}`);
+    console.log(`State: ${inspection.state}${inspection.errorCode ? ` (${inspection.errorCode})` : ""}`);
+    console.log(`Backup: ${backupPath}`);
+    console.log("Strategy: rebuild a clean journaled store from current authored sources.");
+    console.log("Git branch remains unchanged; no branch rename will be performed.");
+    if (!options.apply) {
+        console.log("Preview only. Re-run with --apply to create the backup and publish the rebuilt store.");
+        return;
+    }
+    const { syncCommand } = await import("./sync.js");
+    const result = await syncCommand({
+        rebuild: true,
+        recoveryBackupPath: backupPath,
+        workspaceRoot,
+    });
+    if (!result.success) {
+        throw new Error("Branch KB recovery did not complete successfully.");
+    }
+    // Reattach through the normal delta path after publishing the isolated
+    // generation. This establishes the current checkpoint/snapshot metadata on
+    // the recovered store, so recovery finishes fresh rather than merely
+    // structurally readable.
+    const checkpoint = await syncCommand({ workspaceRoot });
+    if (!checkpoint.success) {
+        throw new Error("Recovered branch KB could not establish a fresh checkpoint.");
+    }
+    const auditPath = path.join(workspaceRoot, ".kb", "migrations", `${attachment.kbBranch.replaceAll("/", "__")}.recovery.json`);
+    fs.mkdirSync(path.dirname(auditPath), { recursive: true });
+    fs.writeFileSync(auditPath, `${JSON.stringify({
+        version: 1,
+        branch: attachment.kbBranch,
+        recoveredAt: new Date().toISOString(),
+        priorState: inspection.state,
+        priorErrorCode: inspection.errorCode ?? null,
+        backupPath: path.relative(workspaceRoot, backupPath),
+        strategy: "rebuild_from_authored_sources",
+    }, null, 2)}\n`, "utf8");
+    console.log(`Recovered exact branch KB '${attachment.kbBranch}'.`);
+    console.log(`Original bytes preserved at ${backupPath}.`);
+    console.log(`Recovery audit: ${auditPath}`);
+}
+/** Restore the newest quarantined store for an exact branch identity. */
+export async function branchRestoreCommand(options = {}) {
+    const workspaceRoot = path.resolve(options.workspaceRoot ?? process.cwd());
+    const branch = options.branch;
+    if (!branch || !isValidBranchName(branch)) {
+        throw new Error("branch restore requires a valid --branch identity");
+    }
+    const targetPath = branchStorePath(workspaceRoot, branch);
+    if (fs.existsSync(targetPath)) {
+        throw new Error(`Target branch store already exists: ${targetPath}`);
+    }
+    const keyRoot = path.join(workspaceRoot, ".kb", "quarantine", "branches", path.basename(targetPath));
+    const candidates = fs.existsSync(keyRoot)
+        ? fs
+            .readdirSync(keyRoot, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => path.join(keyRoot, entry.name))
+            .sort()
+            .reverse()
+        : [];
+    const source = candidates.find((candidate) => {
+        try {
+            const metadata = JSON.parse(fs.readFileSync(path.join(candidate, "quarantine.json"), "utf8"));
+            return metadata.branch === branch;
+        }
+        catch {
+            return false;
+        }
+    });
+    if (!source)
+        throw new Error(`No quarantined store found for '${branch}'.`);
+    console.log(`Branch restore preview: ${branch}`);
+    console.log(`Source: ${source}`);
+    console.log(`Target: ${targetPath}`);
+    if (!options.apply) {
+        console.log("Preview only. Re-run with --apply to restore the store.");
+        return;
     }
-    else {
-        createEmptyBranchKb(currentBranch);
+    const manifest = readBranchStoreManifest(source);
+    if (manifest === null || !branchStoreManifestMatches(source, branch)) {
+        throw new Error(`Quarantined store identity mismatch for '${branch}'.`);
     }
+    fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+    fs.renameSync(source, targetPath);
+    console.log(`Restored exact branch store for '${branch}'.`);
 }
 export default branchEnsureCommand;

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

@@ -1 +1 @@
-{"version":3,"file":"check.d.ts","sourceRoot":"","sources":["../../src/commands/check.ts"],"names":[],"mappings":"AAmFA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAE3D,YAAY,EAAE,SAAS,EAAE,CAAC;AAG1B,MAAM,WAAW,YAAY;IAC3B,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC3B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CAC1B;AA2bD,wBAAsB,YAAY,CAChC,OAAO,EAAE,YAAY,GACpB,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAqX/B"}
+{"version":3,"file":"check.d.ts","sourceRoot":"","sources":["../../src/commands/check.ts"],"names":[],"mappings":"AAqFA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAE3D,YAAY,EAAE,SAAS,EAAE,CAAC;AAE1B,MAAM,WAAW,YAAY;IAC3B,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC3B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CAC1B;AAmaD,wBAAsB,YAAY,CAChC,OAAO,EAAE,YAAY,GACpB,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CA4W/B"}

package/dist/commands/check.js

@@ -18,14 +18,14 @@
 import { existsSync } from "node:fs";
 import * as path from "node:path";
 import { EngineClient } from "../engine.js";
-import { getBranchOverride, isCliTraceOrDebugEnabled } from "../env.js";
+import { isCliTraceOrDebugEnabled } from "../env.js";
 import { extractFromManifest, extractFromManifestString, } from "../extractors/manifest.js";
 import { extractFromMarkdownString, } from "../extractors/markdown.js";
 import { PrologProcess } from "../prolog.js";
 import { escapeAtom, parseTriples, parseViolationRows, } from "../prolog/codec.js";
 import { createSemanticReviewDiagnostics, createSymbolGranularityDiagnostics, createSymbolQualityDiagnostics, hasBlockingImpactDiagnostics, } from "../public/impact-diagnostics.js";
 import { executeCheck } from "../public/operations/check-executor.js";
-import { KIBI_NO_IMPACT_DECLARATION, KIBI_SYMBOLS_MANIFEST_PATH, } from "../traceability/evidence-model.js";
+import { KIBI_NO_IMPACT_DECLARATION, KIBI_SYMBOLS_MANIFEST_PATH, KIBI_SYMBOL_COORDINATES_PATH, } from "../traceability/evidence-model.js";
 import { getStagedFiles } from "../traceability/git-staged.js";
 import { validateStagedMarkdown } from "../traceability/markdown-validate.js";
 import { collectStagedKibiDiagnostics, } from "../traceability/staged-diagnostics.js";
@@ -34,9 +34,9 @@ import { assessStagedSymbolsManifest, collectStagedAuthoredSymbolsManifestEviden
 import { createManifestLookupSentinelKey, extractSymbolsFromStagedFile, } from "../traceability/symbol-extract.js";
 import { cleanupTempKb, consultOverlay, createOverlayFacts, createTempKb, projectStagedEntities, } from "../traceability/temp-kb.js";
 import { formatViolations as formatStagedViolations, validateStagedSymbols, } from "../traceability/validate.js";
-import { loadConfig } from "../utils/config.js";
+import { resolveBranchAttachment } from "../utils/branch-resolver.js";
+import { CANONICAL_ENTITY_PATHS } from "../utils/kb-paths.js";
 import { safeCleanupProlog } from "../utils/prolog-cleanup.js";
-import { getCurrentBranch } from "./init-helpers.js";
 function getMatchGroup(match, index = 1) {
     const value = match?.[index];
     return typeof value === "string" ? value : null;
@@ -70,9 +70,8 @@ function buildManifestLookup(stagedFiles) {
     // Pre-populate lookup from working-tree manifests so that code-only changes
     // (where symbols.yaml is not staged) still resolve to the correct symbol IDs
     // and relationships already defined on disk.
-    const config = loadConfig(process.cwd());
-    const symbolsRelPath = config.paths.symbols;
-    if (symbolsRelPath) {
+    const symbolsRelPath = CANONICAL_ENTITY_PATHS.symbols;
+    {
         const absSymbolsPath = path.resolve(process.cwd(), symbolsRelPath);
         if (existsSync(absSymbolsPath)) {
             try {
@@ -104,10 +103,8 @@ function buildManifestLookup(stagedFiles) {
         }
     }
     const stagedManifestFiles = stagedFiles.filter((file) => file.content !== undefined &&
-        (file.path.endsWith("/symbols.yaml") ||
-            file.path.endsWith("/symbols.yml") ||
-            file.path === "symbols.yaml" ||
-            file.path === "symbols.yml"));
+        (file.path === CANONICAL_ENTITY_PATHS.symbols ||
+            file.path === ".kb/symbols.yml"));
     for (const manifestFile of stagedManifestFiles) {
         manifestLookup.set(createManifestLookupSentinelKey(manifestFile.path), {
             id: manifestFile.path,
@@ -173,29 +170,9 @@ function isKibiEntityType(value) {
     return KIBI_ENTITY_TYPES.has(value);
 }
 function isStagedManifestPath(filePath) {
-    if (filePath.endsWith("/symbols.yaml") ||
-        filePath.endsWith("/symbols.yml") ||
-        filePath.endsWith("/symbol-coordinates.yaml") ||
-        filePath === "symbols.yaml" ||
-        filePath === "symbols.yml" ||
-        filePath === "symbol-coordinates.yaml") {
-        return true;
-    }
-    try {
-        const config = loadConfig(process.cwd());
-        if (config.paths.symbols) {
-            const relSymbols = config.paths.symbols;
-            const configuredBase = relSymbols.split(/[\\/]/).pop();
-            if (filePath === relSymbols ||
-                (configuredBase && filePath.endsWith(`/${configuredBase}`))) {
-                return true;
-            }
-        }
-    }
-    catch {
-        // ignore config read errors
-    }
-    return false;
+    return (filePath === CANONICAL_ENTITY_PATHS.symbols ||
+        filePath === ".kb/symbols.yml" ||
+        filePath === KIBI_SYMBOL_COORDINATES_PATH);
 }
 function isTestOnlySourcePath(filePath) {
     return (filePath.startsWith("tests/") ||
@@ -363,28 +340,21 @@ export async function checkCommand(options) {
     let prolog = null;
     let engine = null;
     let attached = false;
-    let resolvedBranch = "develop";
+    let resolvedBranch = "";
     try {
         let resolvedKbPath = "";
         if (options.kbPath) {
             resolvedKbPath = options.kbPath;
         }
         else {
-            const envBranch = getBranchOverride();
-            let branch = envBranch || undefined;
-            if (!branch) {
-                try {
-                    branch = await getCurrentBranch(process.cwd());
-                }
-                catch {
-                    branch = undefined;
-                }
+            const attachment = resolveBranchAttachment(process.cwd());
+            if ("error" in attachment)
+                throw new Error(attachment.error);
+            resolvedBranch = attachment.kbBranch;
+            if (attachment.migrationRequired) {
+                console.warn(`Warning: reading legacy KB attachment ${attachment.gitBranch} -> ${attachment.kbBranch}; migrate before writes or sync.`);
             }
-            if (!branch)
-                branch = envBranch || "develop";
-            resolvedBranch = branch;
-            // fallback to main if develop isn't present? keep path consistent
-            resolvedKbPath = path.join(process.cwd(), ".kb/branches", branch || "main");
+            resolvedKbPath = attachment.storePath;
         }
         if (options.staged) {
             const minLinks = options.minLinks ? Number(options.minLinks) : 1;
@@ -396,7 +366,7 @@ export async function checkCommand(options) {
                     return { exitCode: 0 };
                 }
                 const { manifestLookup, manifestResults, authoredSymbolResults, stagedAuthoredSymbolResults, } = buildManifestLookup(stagedFiles);
-                const symbolsManifestPath = loadConfig(process.cwd()).paths.symbols ?? KIBI_SYMBOLS_MANIFEST_PATH;
+                const symbolsManifestPath = KIBI_SYMBOLS_MANIFEST_PATH;
                 const sourceFiles = stagedFiles.filter((file) => !file.path.endsWith(".md") && !isStagedManifestPath(file.path));
                 const markdownFiles = stagedFiles.filter((f) => f.path.endsWith(".md"));
                 const markdownErrors = [];
@@ -1027,20 +997,3 @@ async function checkSymbolCoverage(prolog) {
     }
     return violations;
 }
-async function checkSymbolTraceability(prolog, requireAdr) {
-    const violations = [];
-    const requireAdrStr = requireAdr ? "true" : "false";
-    const result = await prolog.query(`findall(violation(Rule, EntityId, Desc, Sugg, Src), 
-      checks:symbol_traceability_violation(${requireAdrStr}, violation(Rule, EntityId, Desc, Sugg, Src)), 
-      Violations)`);
-    if (!result.success || !result.bindings.Violations) {
-        return violations;
-    }
-    const violationsStr = result.bindings.Violations;
-    if (violationsStr && violationsStr !== "[]") {
-        for (const v of parseViolationRows(violationsStr)) {
-            violations.push(v);
-        }
-    }
-    return violations;
-}

package/dist/commands/discovery-shared.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"discovery-shared.d.ts","sourceRoot":"","sources":["../../src/commands/discovery-shared.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAE9D,OAAO,EACL,KAAK,cAAc,EAEpB,MAAM,uCAAuC,CAAC;AAC/C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAMnE,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAE3D,MAAM,WAAW,uBAAuB;IACtC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CAC3B;AAED,qDAAqD;AACrD,MAAM,WAAW,aAAa;IAC5B,YAAY,EAAE,CAAC,IAAI,EAAE;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,KAAK,aAAa,CAAC;IAC3D,WAAW,EAAE,OAAO,eAAe,CAAC;CACrC;AAGD,wBAAsB,oBAAoB,CAAC,MAAM,EAAE,OAAO,EACxD,IAAI,EAAE,aAAa,CAAC,MAAM,EAAE,OAAO,CAAC,EACpC,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,cAAmB,6EAG7B;AAGD,wBAAsB,wBAAwB,CAAC,CAAC,EAC9C,QAAQ,EAAE,CAAC,MAAM,EAAE,aAAa,KAAK,OAAO,CAAC,CAAC,CAAC,EAC/C,IAAI,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,GAC5B,OAAO,CAAC,CAAC,CAAC,CAsDZ;AAID,wBAAsB,oBAAoB,IAAI,OAAO,CAAC,MAAM,CAAC,CAS5D;AAGD,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,MAAM,EAChB,IAAI,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,GAC5B,MAAM,CAGR;AAGD,wBAAsB,kBAAkB,CAAC,CAAC,EACxC,MAAM,EAAE,aAAa,EACrB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,EAClB,MAAM,CAAC,EAAE,MAAM,EACf,IAAI,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,GAC5B,OAAO,CAAC,CAAC,CAAC,CAwBZ;AAGD,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,EACpC,UAAU,EAAE,OAAO,EACnB,YAAY,EAAE,MAAM,GACnB,IAAI,CAQN"}
+{"version":3,"file":"discovery-shared.d.ts","sourceRoot":"","sources":["../../src/commands/discovery-shared.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAE9D,OAAO,EACL,KAAK,cAAc,EAEpB,MAAM,uCAAuC,CAAC;AAC/C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAMnE,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAE3D,MAAM,WAAW,uBAAuB;IACtC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CAC3B;AAED,qDAAqD;AACrD,MAAM,WAAW,aAAa;IAC5B,YAAY,EAAE,CAAC,IAAI,EAAE;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,KAAK,aAAa,CAAC;IAC3D,WAAW,EAAE,OAAO,eAAe,CAAC;CACrC;AAGD,wBAAsB,oBAAoB,CAAC,MAAM,EAAE,OAAO,EACxD,IAAI,EAAE,aAAa,CAAC,MAAM,EAAE,OAAO,CAAC,EACpC,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,cAAmB,6EAG7B;AAGD,wBAAsB,wBAAwB,CAAC,CAAC,EAC9C,QAAQ,EAAE,CAAC,MAAM,EAAE,aAAa,KAAK,OAAO,CAAC,CAAC,CAAC,EAC/C,IAAI,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,GAC5B,OAAO,CAAC,CAAC,CAAC,CA+CZ;AAID,wBAAsB,oBAAoB,IAAI,OAAO,CAAC,MAAM,CAAC,CAI5D;AAGD,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,MAAM,EAChB,IAAI,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,GAC5B,MAAM,CAGR;AAGD,wBAAsB,kBAAkB,CAAC,CAAC,EACxC,MAAM,EAAE,aAAa,EACrB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,EAClB,MAAM,CAAC,EAAE,MAAM,EACf,IAAI,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,GAC5B,OAAO,CAAC,CAAC,CAAC,CAwBZ;AAGD,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,EACpC,UAAU,EAAE,OAAO,EACnB,YAAY,EAAE,MAAM,GACnB,IAAI,CAQN"}