kibi-cli 0.19.0 → 2.0.0

package/dist/operations/mutation/relationships.js

@@ -1,6 +1,7 @@
+import { spawnSync } from "node:child_process";
 import { escapeAtom, toPrologAtom } from "../../prolog/codec.js";
 import { parsePrologList } from "./serialization.js";
-const RELATIONSHIP_TYPES = [
+export const RELATIONSHIP_TYPES = [
     "depends_on",
     "specified_by",
     "verified_by",
@@ -19,6 +20,10 @@ const RELATIONSHIP_TYPES = [
     "supersedes",
     "relates_to",
 ];
+export function wrongKindRelationshipError(type, target, wrongKind) {
+    const expected = type === "constrains" ? "subject" : "property_value";
+    return new Error(`Relationship '${type}' requires target '${target}' to be a ${expected}, observation, or meta fact. ${wrongKind[0]?.toUpperCase()}${wrongKind.slice(1)} facts cannot be direct targets of ${type} relationships.`);
+}
 export function dependentRelationshipsGoal(entityId) {
     return `findall([RelType,From], (member(RelType, [${RELATIONSHIP_TYPES.join(", ")}]), kb_relationship(RelType, From, '${escapeAtom(entityId)}')), Dependents)`;
 }
@@ -66,6 +71,75 @@ export function validateRelationshipSources(entityId, relationships) {
         }
     }
 }
+function trackedSource(source) {
+    return source.length > 0 && !source.includes("://");
+}
+export function firstGitAdditionCommit(workspaceRoot, source) {
+    if (!trackedSource(source))
+        return null;
+    const result = spawnSync("git", ["log", "--follow", "--diff-filter=A", "--format=%H", "--", source], { cwd: workspaceRoot, encoding: "utf8" });
+    if (result.status !== 0)
+        return null;
+    return (result.stdout
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter(Boolean)
+        .at(-1) ?? null);
+}
+function gitIsAncestor(workspaceRoot, ancestor, descendant) {
+    const result = spawnSync("git", ["merge-base", "--is-ancestor", ancestor, descendant], { cwd: workspaceRoot, encoding: "utf8" });
+    if (result.status === 0)
+        return true;
+    if (result.status === 1)
+        return false;
+    return null;
+}
+const DEFAULT_SUPERSEDES_HISTORY_DEPS = {
+    firstAdditionCommit: firstGitAdditionCommit,
+    isAncestor: gitIsAncestor,
+};
+export function classifySupersedesHistory(workspaceRoot, sourceCommit, targetCommit, deps = DEFAULT_SUPERSEDES_HISTORY_DEPS) {
+    if (sourceCommit === null || targetCommit === null)
+        return "unknown";
+    if (sourceCommit === targetCommit)
+        return "valid";
+    const targetBeforeSource = deps.isAncestor(workspaceRoot, targetCommit, sourceCommit);
+    if (targetBeforeSource === true)
+        return "valid";
+    const sourceBeforeTarget = deps.isAncestor(workspaceRoot, sourceCommit, targetCommit);
+    return sourceBeforeTarget === true ? "reversed" : "unknown";
+}
+// implements REQ-011
+export async function validateSupersedesSourceHistory(prolog, entity, relationships, workspaceRoot, deps = DEFAULT_SUPERSEDES_HISTORY_DEPS) {
+    const sourceId = typeof entity.id === "string" ? entity.id : "";
+    const source = typeof entity.source === "string" ? entity.source : "";
+    const sourceCommit = deps.firstAdditionCommit(workspaceRoot, source);
+    for (const relationship of relationships) {
+        if (relationship.type !== "supersedes")
+            continue;
+        const targetId = stringField(relationship, "to");
+        let targetSource = "";
+        if (prolog.queryEntities) {
+            const targetPage = await prolog.queryEntities({
+                id: targetId,
+                limit: 1,
+                offset: 0,
+            });
+            const indexedSource = targetPage.entities[0]?.source;
+            targetSource = typeof indexedSource === "string" ? indexedSource : "";
+        }
+        else {
+            const targetResult = await prolog.query(`once((kb_entity('${escapeAtom(targetId)}', _, _SupTargetProps), memberchk(source=_SupTargetRaw, _SupTargetProps), normalize_term_atom(_SupTargetRaw, TargetSource)))`);
+            targetSource = targetResult.success
+                ? String(targetResult.bindings.TargetSource ?? "").replace(/^['"]|['"]$/g, "")
+                : "";
+        }
+        const targetCommit = deps.firstAdditionCommit(workspaceRoot, targetSource);
+        if (classifySupersedesHistory(workspaceRoot, sourceCommit, targetCommit, deps) === "reversed") {
+            throw new Error(`Invalid supersedes direction: tracked source history proves ${sourceId} predates ${targetId}. The replacement must point to the older requirement (new -> old).`);
+        }
+    }
+}
 export function formatRelationshipSourceMismatch(entityId, relationship) {
     const from = stringField(relationship, "from");
     const to = stringField(relationship, "to");
@@ -122,10 +196,8 @@ export async function validateStrictLanePairing(prolog, relationships) {
         if (wrongKind === null)
             continue;
         const result = await prolog.query(`once((kb_entity('${escapeAtom(target)}', fact, _SlpProps), memberchk(fact_kind=_SlpFK, _SlpProps), normalize_term_atom(_SlpFK, ${wrongKind})))`);
-        if (result.success) {
-            const expected = relationship.type === "constrains" ? "subject" : "property_value";
-            throw new Error(`Relationship '${String(relationship.type)}' requires target '${target}' to be a ${expected}, observation, or meta fact. ${wrongKind[0]?.toUpperCase()}${wrongKind.slice(1)} facts cannot be direct targets of ${String(relationship.type)} relationships.`);
-        }
+        if (result.success)
+            throw wrongKindRelationshipError(String(relationship.type), target, wrongKind);
     }
 }
 export async function existingRelationships(prolog, entityId) {

package/dist/operations/mutation/saga.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Declared compensation list for multi-surface mutations.
+ *
+ * An upsert touches authored sources, relationship shards, generated
+ * coordinate artifacts, and the compiled KB — in that order — and a failed
+ * attempt must undo them in reverse order without masking the original
+ * failure. Instead of tracking rollback state in scattered locals, steps
+ * register a named rollback as they succeed; one rollback() call walks the
+ * list backwards exactly once.
+ */
+export type SagaStep = Readonly<{
+    /** Stable identifier used in rollback diagnostics. */
+    name: string;
+    /**
+     * Undo the step. Implementations should target idempotence (guards against
+     * concurrent writers, tolerating an already-restored surface); rollback()
+     * never re-throws a rollback error.
+     */
+    rollback: () => void | Promise<void>;
+    /**
+     * `swallow` (default): preserve the original mutation failure; the recovery
+     * journal / next check reconciles. `capture`: report the rollback failure
+     * alongside the original error (e.g. as an AggregateError).
+     */
+    onError?: "swallow" | "capture";
+}>;
+export type SagaRollbackFailure = Readonly<{
+    step: string;
+    error: unknown;
+}>;
+export declare class MutationSaga {
+    private readonly steps;
+    private rollbackCompleted;
+    private committedAt;
+    /** Register a completed step. Call only after the step fully succeeded. */
+    add(step: SagaStep): void;
+    /**
+     * The durable commit point: once marked, rollback() is a no-op — the
+     * compiled KB holds the change and post-commit failures surface as
+     * committed-with-repairs results instead of undoing committed state.
+     */
+    markCommitted(): void;
+    get committed(): boolean;
+    /**
+     * Roll back every registered step in reverse order, exactly once. Rollback
+     * errors never throw; capture-policy failures are returned so the caller
+     * can decide whether to aggregate them into the propagated error.
+     */
+    rollback(): Promise<readonly SagaRollbackFailure[]>;
+}
+//# sourceMappingURL=saga.d.ts.map

package/dist/operations/mutation/saga.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"saga.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/saga.ts"],"names":[],"mappings":"AAkBA;;;;;;;;;GASG;AAGH,MAAM,MAAM,QAAQ,GAAG,QAAQ,CAAC;IAC9B,sDAAsD;IACtD,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,QAAQ,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrC;;;;OAIG;IACH,OAAO,CAAC,EAAE,SAAS,GAAG,SAAS,CAAC;CACjC,CAAC,CAAC;AAGH,MAAM,MAAM,mBAAmB,GAAG,QAAQ,CAAC;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,OAAO,CAAC;CAChB,CAAC,CAAC;AAGH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAkB;IACxC,OAAO,CAAC,iBAAiB,CAAS;IAClC,OAAO,CAAC,WAAW,CAAuB;IAE1C,2EAA2E;IAE3E,GAAG,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI;IAIzB;;;;OAIG;IAEH,aAAa,IAAI,IAAI;IAKrB,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED;;;;OAIG;IAEG,QAAQ,IAAI,OAAO,CAAC,SAAS,mBAAmB,EAAE,CAAC;CAkB1D"}

package/dist/operations/mutation/saga.js

@@ -0,0 +1,67 @@
+/*
+ Kibi — repo-local, per-branch, queryable long-term memory for software projects
+ Copyright (C) 2026 Piotr Franczyk
+
+ This program is free software: you can redistribute it and/or modify
+ it under the terms of the GNU Affero General Public License as published by
+ the Free Software Foundation, either version 3 of the License, or
+ (at your option) any later version.
+
+ This program is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ GNU Affero General Public License for more details.
+
+ You should have received a copy of the GNU Affero General Public License
+ along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+// implements REQ-014
+export class MutationSaga {
+    steps = [];
+    rollbackCompleted = false;
+    committedAt = null;
+    /** Register a completed step. Call only after the step fully succeeded. */
+    // implements REQ-014
+    add(step) {
+        this.steps.push(step);
+    }
+    /**
+     * The durable commit point: once marked, rollback() is a no-op — the
+     * compiled KB holds the change and post-commit failures surface as
+     * committed-with-repairs results instead of undoing committed state.
+     */
+    // implements REQ-014
+    markCommitted() {
+        this.committedAt = this.steps.length;
+    }
+    // implements REQ-014
+    get committed() {
+        return this.committedAt !== null;
+    }
+    /**
+     * Roll back every registered step in reverse order, exactly once. Rollback
+     * errors never throw; capture-policy failures are returned so the caller
+     * can decide whether to aggregate them into the propagated error.
+     */
+    // implements REQ-014
+    async rollback() {
+        if (this.rollbackCompleted || this.committedAt !== null)
+            return [];
+        this.rollbackCompleted = true;
+        const captured = [];
+        for (const step of [...this.steps].reverse()) {
+            try {
+                await step.rollback();
+            }
+            catch (error) {
+                if (step.onError === "capture") {
+                    captured.push({ step: step.name, error });
+                }
+                // Swallow-policy failures keep the original mutation error intact;
+                // the recovery journal and the next check/sync report what could not
+                // be restored.
+            }
+        }
+        return captured;
+    }
+}

package/dist/operations/mutation/serialization.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"serialization.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/serialization.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAkDpD,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GACxC,MAAM,CAMR;AAGD,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,iBAAiB,GAAG,MAAM,CAOxE;AAGD,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAkBtD"}
+{"version":3,"file":"serialization.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/serialization.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAoDpD,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GACxC,MAAM,CAMR;AAGD,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,iBAAiB,GAAG,MAAM,CAOxE;AAGD,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAkBtD"}

package/dist/operations/mutation/serialization.js

@@ -28,7 +28,9 @@ function serializeValue(key, value) {
     }
     if (key === "rule_ir" ||
         key === "semantic_inventory" ||
-        key === "verification_receipts") {
+        key === "proof_contract" ||
+        key === "proof_bindings" ||
+        key === "proof_receipts") {
         return toPrologString(JSON.stringify(value));
     }
     if (Array.isArray(value))

package/dist/operations/mutation/source-authoring.d.ts

@@ -0,0 +1,65 @@
+import type { OperationContext } from "../../public/operations/runtime-types.js";
+import type { UpsertInput } from "./types.js";
+export type SourceWriteReceipt = Readonly<{
+    path: string;
+    mode: "write" | "delete";
+    beforeHash: string | null;
+    afterHash: string | null;
+    created: boolean;
+}>;
+export declare function writePendingSourceReceipt(workspaceRoot: string, relativePath: string, afterHash: string): void;
+export declare function resolveContainedSourcePath(workspaceRoot: string, relative: string): string;
+export declare function normalizeAuthoredSourcePath(workspaceRoot: string, source: string): string;
+/**
+ * Canonical authored target for an entity type: `.kb/<lane>/<ID>.md` for
+ * markdown entities and `.kb/symbols.yaml` for symbols. Kibi owns these
+ * locations; repositories cannot relocate them.
+ */
+export declare function configuredSourceTarget(workspaceRoot: string, type: string): string | undefined;
+export declare function hasConfiguredSourceTarget(workspaceRoot: string, type: string): boolean;
+/** Generated coordinate fields belong exclusively to `.kb/symbol-coordinates.yaml`. */
+export declare const GENERATED_SYMBOL_FIELDS: readonly ["sourceLine", "sourceColumn", "sourceEndLine", "sourceEndColumn", "coordinatesGeneratedAt"];
+export declare function manifestRelationships(item: unknown): Array<{
+    type: string;
+    target: string;
+}>;
+export declare function renderSourceDeletion(sourcePathValue: string, entityId: string, entityType: string, existingContent: string): {
+    mode: "write" | "delete";
+    body?: string;
+};
+/**
+ * Remove one legacy relationship declaration from an authored Markdown
+ * document.  Relationship shards are the canonical relationship lane, but
+ * older entity documents may still carry `links` or typed `relationships`
+ * frontmatter.  When such a declaration is explicitly deleted, patch only
+ * that record through the YAML CST so comments, ordering, and the Markdown
+ * body remain byte-stable.
+ */
+export declare function renderMarkdownRelationshipDeletion(sourcePathValue: string, existingContent: string, selector: Readonly<{
+    type: string;
+    from: string;
+    to: string;
+}>): {
+    body: string;
+    removed: boolean;
+};
+/**
+ * Remove one exact typed relationship from an authored symbol manifest. The
+ * YAML CST is edited in place so comments, ordering, and unrelated symbols or
+ * relationships remain authored content rather than being re-serialized.
+ */
+export declare function renderYamlRelationshipDeletion(sourcePathValue: string, existingContent: string, selector: Readonly<{
+    type: string;
+    from: string;
+    to: string;
+}>): {
+    body: string;
+    removed: boolean;
+};
+export declare function writeSourceForUpsert(input: UpsertInput, entity: Readonly<Record<string, unknown>>, existing?: Readonly<Record<string, unknown>>, context?: OperationContext, sourceDocumentOverride?: string): Promise<{
+    receipt: SourceWriteReceipt;
+    rollback: () => Promise<void>;
+} | null>;
+/** Resolve and normalize the canonical authored path for an entity. */
+export declare function canonicalSourcePath(context: OperationContext, input: UpsertInput, entity: Readonly<Record<string, unknown>>, existing?: Readonly<Record<string, unknown>>): string;
+//# sourceMappingURL=source-authoring.d.ts.map

package/dist/operations/mutation/source-authoring.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"source-authoring.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/source-authoring.ts"],"names":[],"mappings":"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"}