kibi-cli 1.0.1 → 2.0.0

package/dist/operations/mutation/source-authoring.js

@@ -1,4 +1,5 @@
 import { createHash } from "node:crypto";
+import { randomUUID } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import { dump as dumpYaml, load as loadYaml } from "js-yaml";
@@ -196,7 +197,7 @@ function symbolManifestRecord(entity, relationships = []) {
     }
     return record;
 }
-function manifestRelationships(item) {
+export function manifestRelationships(item) {
     if (item === null ||
         typeof item !== "object" ||
         !("get" in item) ||
@@ -452,7 +453,7 @@ function renderSourceDocument(input, entity, existingContent, relativePath) {
     }
     return renderEntityDocument(input, entity, existingContent);
 }
-export async function writeSourceForUpsert(input, entity, existing, context) {
+export async function writeSourceForUpsert(input, entity, existing, context, sourceDocumentOverride) {
     if (!context?.fs)
         return null;
     const absolute = sourcePath(context, input, entity, existing);
@@ -466,16 +467,30 @@ export async function writeSourceForUpsert(input, entity, existing, context) {
     catch {
         before = undefined;
     }
-    const after = renderSourceDocument(input, entity, before, relative);
+    // Proof-receipt ingest supplies pre-patched bytes so unrelated frontmatter
+    // keeps its authored formatting (and the workspace snapshot stays stable).
+    // Only valid when the document already exists; a new document still needs
+    // the canonical render.
+    const after = before !== undefined && sourceDocumentOverride !== undefined
+        ? sourceDocumentOverride
+        : renderSourceDocument(input, entity, before, relative);
     await context.fs.mkdir(path.dirname(absolute));
-    const temporary = `${absolute}.kibi-source-${digest(relative).slice(0, 12)}`;
-    await context.fs.writeFile(temporary, after);
-    if (context.fs.rename) {
-        await context.fs.rename(temporary, absolute);
+    const temporary = `${absolute}.kibi-source-${process.pid}-${randomUUID()}`;
+    try {
+        await context.fs.writeFile(temporary, after);
+        if (context.fs.rename) {
+            await context.fs.rename(temporary, absolute);
+        }
+        else {
+            await context.fs.writeFile(absolute, after);
+            await context.fs.unlink?.(temporary).catch(() => undefined);
+        }
     }
-    else {
-        await context.fs.writeFile(absolute, after);
+    catch (error) {
+        // A failed rename must not leak the unique temp file into the authored
+        // tree; the published target (if any) is untouched at this point.
         await context.fs.unlink?.(temporary).catch(() => undefined);
+        throw error;
     }
     const receipt = {
         path: relative,
@@ -484,46 +499,40 @@ export async function writeSourceForUpsert(input, entity, existing, context) {
         afterHash: digest(after),
         created: before === undefined,
     };
-    const pendingReceipt = pendingReceiptPath(context.workspaceRoot, relative);
-    if (receipt.afterHash !== null &&
-        (before === undefined || fs.existsSync(pendingReceipt))) {
-        writePendingSourceReceipt(context.workspaceRoot, relative, receipt.afterHash);
-    }
-    return {
-        receipt,
-        rollback: async () => {
-            const fsPort = context.fs;
-            if (fsPort === undefined)
-                return;
-            // Compare before restore: a concurrent writer may have replaced the file
-            // after our publication. Never clobber newer bytes; keep the recovery
-            // receipt so the next sync reconciles deterministically instead.
-            let current;
+    const rollback = async () => {
+        const fsPort = context.fs;
+        if (fsPort === undefined)
+            return;
+        // Compare before restore: a concurrent writer may have replaced the file
+        // after our publication. Never clobber newer bytes; keep the recovery
+        // receipt so the next sync reconciles deterministically instead.
+        let current;
+        try {
+            current = await fsPort.readFile(absolute);
+        }
+        catch {
+            current = undefined;
+        }
+        if (current !== undefined && digest(current) !== digest(after)) {
+            writePendingSourceReceipt(context.workspaceRoot, relative, receipt.afterHash);
+            console.warn(`Skipped source rollback for ${relative}: file changed after the Kibi write; kept concurrent content and recorded recovery metadata.`);
+            return;
+        }
+        if (before === undefined) {
+            if (fsPort.unlink)
+                await fsPort.unlink(absolute);
+            else
+                await fsPort.writeFile(absolute, "");
             try {
-                current = await fsPort.readFile(absolute);
+                fs.unlinkSync(pendingReceiptPath(context.workspaceRoot, relative));
             }
             catch {
-                current = undefined;
+                // The pending receipt is advisory recovery metadata.
             }
-            if (current !== undefined && digest(current) !== digest(after)) {
-                writePendingSourceReceipt(context.workspaceRoot, relative, receipt.afterHash);
-                console.warn(`Skipped source rollback for ${relative}: file changed after the Kibi write; kept concurrent content and recorded recovery metadata.`);
-                return;
-            }
-            if (before === undefined) {
-                if (fsPort.unlink)
-                    await fsPort.unlink(absolute);
-                else
-                    await fsPort.writeFile(absolute, "");
-                try {
-                    fs.unlinkSync(pendingReceiptPath(context.workspaceRoot, relative));
-                }
-                catch {
-                    // The pending receipt is advisory recovery metadata.
-                }
-            }
-            else {
-                const rollbackTemp = `${absolute}.kibi-rollback-${digest(relative).slice(0, 12)}`;
+        }
+        else {
+            const rollbackTemp = `${absolute}.kibi-rollback-${process.pid}-${randomUUID()}`;
+            try {
                 await fsPort.writeFile(rollbackTemp, before);
                 if (fsPort.rename)
                     await fsPort.rename(rollbackTemp, absolute);
@@ -532,8 +541,32 @@ export async function writeSourceForUpsert(input, entity, existing, context) {
                     await fsPort.unlink?.(rollbackTemp).catch(() => undefined);
                 }
             }
-        },
+            catch (error) {
+                await fsPort.unlink?.(rollbackTemp).catch(() => undefined);
+                throw error;
+            }
+        }
     };
+    const pendingReceipt = pendingReceiptPath(context.workspaceRoot, relative);
+    try {
+        if (receipt.afterHash !== null &&
+            (before === undefined || fs.existsSync(pendingReceipt))) {
+            writePendingSourceReceipt(context.workspaceRoot, relative, receipt.afterHash);
+        }
+    }
+    catch (receiptError) {
+        // The source bytes are already published but the caller has not received
+        // the rollback handle yet. Unwind the publication here so no failed call
+        // ever leaves a half-registered source write behind.
+        try {
+            await rollback();
+        }
+        catch (rollbackError) {
+            throw new AggregateError([receiptError, rollbackError], `Source published for ${relative}, but pending receipt publication and rollback both failed; recover from the pending-source receipt or restore the authored file manually`);
+        }
+        throw receiptError;
+    }
+    return { receipt, rollback };
 }
 /** Resolve and normalize the canonical authored path for an entity. */
 export function canonicalSourcePath(context, input, entity, existing) {

package/dist/operations/mutation/strict-fact.d.ts

@@ -1,4 +1,5 @@
 export declare function valueFieldHint(value: unknown): string;
 export declare function factKindShapeHints(entity: Readonly<Record<string, unknown>>): string[];
+export declare function assertRuleSchemaArity(argumentNames: unknown, argumentTypes: unknown): void;
 export declare function validateFactModelingShape(entity: Readonly<Record<string, unknown>>): void;
 //# sourceMappingURL=strict-fact.d.ts.map

package/dist/operations/mutation/strict-fact.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"strict-fact.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/strict-fact.ts"],"names":[],"mappings":"AAUA,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAarD;AAGD,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GACxC,MAAM,EAAE,CA+EV;AAGD,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GACxC,IAAI,CAuDN"}
+{"version":3,"file":"strict-fact.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/strict-fact.ts"],"names":[],"mappings":"AAUA,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAarD;AAGD,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GACxC,MAAM,EAAE,CA+EV;AAED,wBAAgB,qBAAqB,CACnC,aAAa,EAAE,OAAO,EACtB,aAAa,EAAE,OAAO,GACrB,IAAI,CAUN;AAGD,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GACxC,IAAI,CA+CN"}

package/dist/operations/mutation/strict-fact.js

@@ -93,6 +93,13 @@ export function factKindShapeHints(entity) {
         ];
     return [];
 }
+export function assertRuleSchemaArity(argumentNames, argumentTypes) {
+    if (!Array.isArray(argumentNames) ||
+        !Array.isArray(argumentTypes) ||
+        argumentNames.length !== argumentTypes.length) {
+        throw new Error("Entity validation failed: rule_schema argument_names and argument_types must have equal lengths");
+    }
+}
 // implements REQ-kibi-operation-interface-parity
 export function validateFactModelingShape(entity) {
     const hints = factKindShapeHints(entity);
@@ -123,10 +130,6 @@ export function validateFactModelingShape(entity) {
             entity.rule_name.trim() === "") {
             throw new Error("Entity validation failed: fact_kind 'rule_schema' requires rule_name");
         }
-        if (!Array.isArray(entity.argument_names) ||
-            !Array.isArray(entity.argument_types) ||
-            entity.argument_names.length !== entity.argument_types.length) {
-            throw new Error("Entity validation failed: rule_schema argument_names and argument_types must have equal lengths");
-        }
+        assertRuleSchemaArity(entity.argument_names, entity.argument_types);
     }
 }

package/dist/operations/mutation/symbol-compiler-lock.d.ts

@@ -15,6 +15,7 @@ export interface SymbolCompilerLockOptions {
     readonly now?: () => number;
     readonly sleep?: (ms: number) => Promise<void>;
     readonly fileSystem?: SymbolCompilerLockFileSystem;
+    readonly isProcessAlive?: (pid: number) => boolean;
 }
 export declare class SymbolCompilerLockError extends Error {
     readonly name = "SymbolCompilerLockError";
@@ -31,7 +32,7 @@ export interface SymbolCompilerLockHandle {
 }
 export declare function releaseSymbolCompilerLock(handle: SymbolCompilerLockHandle | undefined, operationFailure?: {
     readonly error: unknown;
-}): void;
+}, committed?: boolean): void;
 /**
  * Acquire the workspace symbol compiler lock without a callback shape, for
  * operations whose lock must span several awaits (source publication,
@@ -44,7 +45,9 @@ export declare function acquireSymbolCompilerLock(workspaceRoot: string, options
  * Atomic directory creation is the lock authority. Owner metadata is
  * release authorization and diagnostics: every existing target, including a
  * legacy file or a directory with missing/corrupt metadata, blocks contenders
- * until timeout.
+ * until timeout. A well-formed owner record whose holder pid is provably
+ * dead is stolen immediately instead of blocking for the full timeout;
+ * corrupt metadata and live holders stay fail-closed.
  * Release failures propagate so successful work is never reported unlocked.
  */
 export declare function withSymbolCompilerLock<T>(workspaceRoot: string, operation: () => Promise<T>, options?: SymbolCompilerLockOptions): Promise<T>;

package/dist/operations/mutation/symbol-compiler-lock.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"symbol-compiler-lock.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/symbol-compiler-lock.ts"],"names":[],"mappings":"AAyBA,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,SAAS,EAAE,CAClB,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAA;KAAE,KACvC,IAAI,CAAC;IACV,QAAQ,CAAC,YAAY,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,MAAM,CAAC;IAClD,QAAQ,CAAC,aAAa,EAAE,CACtB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE;QAAE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAA;KAAE,KACxD,IAAI,CAAC;IACV,QAAQ,CAAC,UAAU,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IAC9C,QAAQ,CAAC,SAAS,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;CAC9C;AAeD,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C,QAAQ,CAAC,UAAU,CAAC,EAAE,4BAA4B,CAAC;CACpD;AAGD,qBAAa,uBAAwB,SAAQ,KAAK;IAChD,SAAkB,IAAI,6BAA6B;CACpD;AAmJD,MAAM,WAAW,wBAAwB;IACvC;;;;;;OAMG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,IAAI,CAAC;CAC9B;AAGD,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,wBAAwB,GAAG,SAAS,EAC5C,gBAAgB,CAAC,EAAE;IAAE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GAC7C,IAAI,CAaN;AAED;;;;GAIG;AAEH,wBAAsB,yBAAyB,CAC7C,aAAa,EAAE,MAAM,EACrB,OAAO,GAAE,yBAA8B,GACtC,OAAO,CAAC,wBAAwB,CAAC,CA+HnC;AAED;;;;;;;;GAQG;AAEH,wBAAsB,sBAAsB,CAAC,CAAC,EAC5C,aAAa,EAAE,MAAM,EACrB,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAC3B,OAAO,GAAE,yBAA8B,GACtC,OAAO,CAAC,CAAC,CAAC,CAWZ"}
+{"version":3,"file":"symbol-compiler-lock.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/symbol-compiler-lock.ts"],"names":[],"mappings":"AA0BA,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,SAAS,EAAE,CAClB,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAA;KAAE,KACvC,IAAI,CAAC;IACV,QAAQ,CAAC,YAAY,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,MAAM,CAAC;IAClD,QAAQ,CAAC,aAAa,EAAE,CACtB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE;QAAE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAA;KAAE,KACxD,IAAI,CAAC;IACV,QAAQ,CAAC,UAAU,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IAC9C,QAAQ,CAAC,SAAS,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;CAC9C;AAeD,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C,QAAQ,CAAC,UAAU,CAAC,EAAE,4BAA4B,CAAC;IACnD,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;CACpD;AAGD,qBAAa,uBAAwB,SAAQ,KAAK;IAChD,SAAkB,IAAI,6BAA6B;CACpD;AA8MD,MAAM,WAAW,wBAAwB;IACvC;;;;;;OAMG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,IAAI,CAAC;CAC9B;AAGD,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,wBAAwB,GAAG,SAAS,EAC5C,gBAAgB,CAAC,EAAE;IAAE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;CAAE,EAC9C,SAAS,UAAQ,GAChB,IAAI,CAoBN;AAED;;;;GAIG;AAEH,wBAAsB,yBAAyB,CAC7C,aAAa,EAAE,MAAM,EACrB,OAAO,GAAE,yBAA8B,GACtC,OAAO,CAAC,wBAAwB,CAAC,CA2InC;AAED;;;;;;;;;;GAUG;AAEH,wBAAsB,sBAAsB,CAAC,CAAC,EAC5C,aAAa,EAAE,MAAM,EACrB,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAC3B,OAAO,GAAE,yBAA8B,GACtC,OAAO,CAAC,CAAC,CAAC,CAWZ"}

package/dist/operations/mutation/symbol-compiler-lock.js

@@ -1,5 +1,6 @@
 import { mkdirSync, readFileSync, rmdirSync, unlinkSync, writeFileSync, } from "node:fs";
 import * as path from "node:path";
+import { OperationError } from "../../cli-errors.js";
 /**
  * Workspace-scoped mutex serializing every writer of the symbol compiler
  * surface: authored manifest edits, targeted coordinate refresh, full
@@ -125,17 +126,73 @@ function existingLockDescription(fileSystem, target, ownerPath) {
         }
     }
 }
+function defaultIsProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return !(error instanceof Error &&
+            "code" in error &&
+            error.code === "ESRCH");
+    }
+}
+/**
+ * Read the current lock owner record and steal the lock only when the
+ * recorded holder pid is provably dead. A readable owner.json identifies a
+ * directory lock; a readable lock path itself identifies a legacy file lock.
+ * Corrupt, missing, or unreadable metadata stays fail-closed: an
+ * initializing writer must never be stolen from, and a live holder (or an
+ * unverifiable pid) keeps the mutex.
+ */
+function stealStaleLockIfHolderIsDead(fileSystem, target, ownerPath, isProcessAlive) {
+    let record = null;
+    let legacyFileLock = false;
+    try {
+        record = readLockRecord(fileSystem.readFileSync(ownerPath));
+    }
+    catch {
+        try {
+            record = readLockRecord(fileSystem.readFileSync(target));
+            legacyFileLock = true;
+        }
+        catch {
+            return "unknown";
+        }
+    }
+    if (record === null)
+        return "unknown";
+    if (isProcessAlive(record.pid))
+        return "live";
+    try {
+        if (legacyFileLock) {
+            const removal = retryTransientFilesystemOperation(() => fileSystem.unlinkSync(target));
+            if (!removal.ok)
+                return "unknown";
+            return "stolen";
+        }
+        removeLockOwner(fileSystem, target, ownerPath, true);
+        removeLockDirectory(fileSystem, target);
+    }
+    catch {
+        return "unknown";
+    }
+    return "stolen";
+}
 async function defaultSleep(ms) {
     await new Promise((resolvePromise) => setTimeout(resolvePromise, ms));
 }
 // implements REQ-generated-coordinate-persistence
-export function releaseSymbolCompilerLock(handle, operationFailure) {
+export function releaseSymbolCompilerLock(handle, operationFailure, committed = false) {
     if (handle === undefined)
         return;
     try {
         handle.release();
     }
     catch (releaseError) {
+        if (committed) {
+            throw new OperationError("SYMBOL_COMPILER_LOCK_RELEASE_FAILED", `Mutation committed, but symbol compiler lock release failed: ${errorDetail(releaseError)}; do not retry the mutation until the lock is manually verified and released`, false);
+        }
         if (operationFailure !== undefined) {
             throw new AggregateError([operationFailure.error, releaseError], "Operation failed and symbol compiler lock release failed");
         }
@@ -153,6 +210,7 @@ export async function acquireSymbolCompilerLock(workspaceRoot, options = {}) {
     const now = options.now ?? Date.now;
     const sleep = options.sleep ?? defaultSleep;
     const fileSystem = options.fileSystem ?? NODE_FILE_SYSTEM;
+    const isProcessAlive = options.isProcessAlive ?? defaultIsProcessAlive;
     const target = lockPath(workspaceRoot);
     const ownerPath = path.join(target, OWNER_FILE);
     const token = randomToken();
@@ -177,6 +235,9 @@ export async function acquireSymbolCompilerLock(workspaceRoot, options = {}) {
             throw new SymbolCompilerLockError(`failed to acquire symbol compiler lock directory at ${target} after ${targetResult.attempts} attempt(s): ${errorDetail(targetResult.error)}`);
         }
         lastBlocker = existingLockDescription(fileSystem, target, ownerPath);
+        if (stealStaleLockIfHolderIsDead(fileSystem, target, ownerPath, isProcessAlive) === "stolen") {
+            continue;
+        }
         await sleep(RETRY_INTERVAL_MS);
     }
     if (!acquired) {
@@ -254,7 +315,9 @@ export async function acquireSymbolCompilerLock(workspaceRoot, options = {}) {
  * Atomic directory creation is the lock authority. Owner metadata is
  * release authorization and diagnostics: every existing target, including a
  * legacy file or a directory with missing/corrupt metadata, blocks contenders
- * until timeout.
+ * until timeout. A well-formed owner record whose holder pid is provably
+ * dead is stolen immediately instead of blocking for the full timeout;
+ * corrupt metadata and live holders stay fail-closed.
  * Release failures propagate so successful work is never reported unlocked.
  */
 // implements REQ-generated-coordinate-persistence

package/dist/operations/mutation/symbol-granularity.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"symbol-granularity.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/symbol-granularity.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0CAA0C,CAAC;AAUjF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AA+FpD,wBAAsB,yBAAyB,CAC7C,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACzC,aAAa,EAAE,SAAS,iBAAiB,EAAE,EAC3C,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,IAAI,CAAC,CAuCf"}
+{"version":3,"file":"symbol-granularity.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/symbol-granularity.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0CAA0C,CAAC;AAWjF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AA+FpD,wBAAsB,yBAAyB,CAC7C,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACzC,aAAa,EAAE,SAAS,iBAAiB,EAAE,EAC3C,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,IAAI,CAAC,CAuCf"}

package/dist/operations/mutation/symbol-granularity.js

@@ -1,6 +1,6 @@
 import path from "node:path";
 import { Project, ScriptKind, SyntaxKind } from "ts-morph";
-import { getBehavioralSymbolNames, getNonBehavioralSymbolNames, inferSymbolRole, isAllowedGranularityReason, isTraceabilityRelationshipType, } from "../../public/symbol-granularity.js";
+import { ALLOWED_GRANULARITY_REASONS_PROSE, getBehavioralSymbolNames, getNonBehavioralSymbolNames, inferSymbolRole, isAllowedGranularityReason, isTraceabilityRelationshipType, } from "../../public/symbol-granularity.js";
 function scriptKind(filePath) {
     const extension = path.extname(filePath).toLowerCase();
     if (extension === ".tsx")
@@ -136,5 +136,5 @@ export async function validateSymbolGranularity(entity, relationships, context)
     const ignored = nonBehavioral.length > 0
         ? ` Non-behavioral symbols in the file were ignored for this decision: ${summarized(nonBehavioral)}.`
         : "";
-    throw new Error(`Symbol ${String(entity.id)} links ${entity.sourceFile} coarsely while granular symbols are available (behavioral only): ${summarized(behavioral)}. Move relationships to a behavioral symbol, add a manifest behavioral anchor, or set granularity_reason to config-artifact, module-level-behavior, extractor-miss, legacy-link, or test-suite.${ignored}`);
+    throw new Error(`Symbol ${String(entity.id)} links ${entity.sourceFile} coarsely while granular symbols are available (behavioral only): ${summarized(behavioral)}. Move relationships to a behavioral symbol, add a manifest behavioral anchor, or set granularity_reason to ${ALLOWED_GRANULARITY_REASONS_PROSE}.${ignored}`);
 }

package/dist/operations/mutation/symbol-refresh.d.ts

@@ -13,6 +13,7 @@ export type ArtifactPublicationReceipt = {
     rollback(): void;
 };
 type RefreshImplementation = (symbolId: string, context: OperationContext) => Promise<RefreshResult>;
+export declare function restoreOrUnlinkCoordinateArtifact(targetPath: string, before: string | null): void;
 /** Targeted coordinate refresh under the workspace symbol compiler lock. */
 export declare function refreshSymbolCoordinates(symbolId: string, context: OperationContext): Promise<RefreshResult>;
 /** Run one refresh step without acquiring the lock (caller holds it). */

package/dist/operations/mutation/symbol-refresh.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"symbol-refresh.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/symbol-refresh.ts"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0CAA0C,CAAC;AAgBjF,MAAM,MAAM,sBAAsB,GAC9B,SAAS,GACT,WAAW,GACX,SAAS,GACT,WAAW,CAAC;AAGhB,MAAM,MAAM,aAAa,GAAG;IAC1B,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,OAAO,CAAC,EAAE,sBAAsB,CAAC;IAC1C,QAAQ,CAAC,WAAW,CAAC,EAAE,0BAA0B,CAAC;CACnD,CAAC;AAGF,MAAM,MAAM,0BAA0B,GAAG;IACvC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,IAAI,IAAI,CAAC;CAClB,CAAC;AAEF,KAAK,qBAAqB,GAAG,CAC3B,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,gBAAgB,KACtB,OAAO,CAAC,aAAa,CAAC,CAAC;AAqS5B,4EAA4E;AAC5E,wBAAsB,wBAAwB,CAC5C,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,aAAa,CAAC,CASxB;AAED,yEAAyE;AAEzE,wBAAsB,gCAAgC,CACpD,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,aAAa,CAAC,CAGxB;AAED;;;GAGG;AAEH,wBAAsB,mCAAmC,CACvD,QAAQ,EAAE,MAAM,EAChB,oBAAoB,EAAE,MAAM,EAC5B,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,aAAa,CAAC,CAOxB;AAGD,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,qBAAqB,GAAG,SAAS,GACzC,IAAI,CAEN"}
+{"version":3,"file":"symbol-refresh.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/symbol-refresh.ts"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0CAA0C,CAAC;AAgBjF,MAAM,MAAM,sBAAsB,GAC9B,SAAS,GACT,WAAW,GACX,SAAS,GACT,WAAW,CAAC;AAGhB,MAAM,MAAM,aAAa,GAAG;IAC1B,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,OAAO,CAAC,EAAE,sBAAsB,CAAC;IAC1C,QAAQ,CAAC,WAAW,CAAC,EAAE,0BAA0B,CAAC;CACnD,CAAC;AAGF,MAAM,MAAM,0BAA0B,GAAG;IACvC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,IAAI,IAAI,CAAC;CAClB,CAAC;AAEF,KAAK,qBAAqB,GAAG,CAC3B,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,gBAAgB,KACtB,OAAO,CAAC,aAAa,CAAC,CAAC;AAsD5B,wBAAgB,iCAAiC,CAC/C,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,GAAG,IAAI,GACpB,IAAI,CAMN;AA6OD,4EAA4E;AAC5E,wBAAsB,wBAAwB,CAC5C,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,aAAa,CAAC,CASxB;AAED,yEAAyE;AAEzE,wBAAsB,gCAAgC,CACpD,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,aAAa,CAAC,CAGxB;AAED;;;GAGG;AAEH,wBAAsB,mCAAmC,CACvD,QAAQ,EAAE,MAAM,EAChB,oBAAoB,EAAE,MAAM,EAC5B,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,aAAa,CAAC,CAOxB;AAGD,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,qBAAqB,GAAG,SAAS,GACzC,IAAI,CAEN"}

package/dist/operations/mutation/symbol-refresh.js

@@ -1,4 +1,4 @@
-import { createHash } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { existsSync, readFileSync, renameSync, unlinkSync, writeFileSync, } from "node:fs";
 import * as path from "node:path";
 import { load as parseYaml } from "js-yaml";
@@ -46,8 +46,15 @@ function sourceTextFor(sourceFile, workspaceRoot) {
 function contentHash(content) {
     return createHash("sha256").update(content).digest("hex");
 }
+export function restoreOrUnlinkCoordinateArtifact(targetPath, before) {
+    if (before === null) {
+        unlinkSync(targetPath);
+        return;
+    }
+    replaceArtifactAtomically(targetPath, before);
+}
 function replaceArtifactAtomically(targetPath, content) {
-    const temporary = `${targetPath}.kibi-tmp-${process.pid}`;
+    const temporary = `${targetPath}.kibi-tmp-${process.pid}-${randomUUID()}`;
     try {
         writeFileSync(temporary, content, "utf8");
         renameSync(temporary, targetPath);
@@ -81,12 +88,7 @@ function publishArtifact(targetPath, content) {
             if (contentHash(current) !== afterHash) {
                 throw new CoordinateArtifactError(`coordinate artifact changed after publication; refusing rollback: ${targetPath}`);
             }
-            if (before === null) {
-                unlinkSync(targetPath);
-            }
-            else {
-                replaceArtifactAtomically(targetPath, before);
-            }
+            restoreOrUnlinkCoordinateArtifact(targetPath, before);
         },
     };
 }

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

@@ -1,7 +1,23 @@
 import type { OperationContext } from "../../public/operations/runtime-types.js";
 import type { OperationResult } from "../../public/operations/types.js";
 import type { RelationshipInput, UpsertInput, UpsertPayload } from "./types.js";
-export declare function validateAppendOnlyVerificationReceipts(entity: Readonly<Record<string, unknown>>, context: OperationContext): Promise<void>;
+export declare function validateAppendOnlyProofReceipts(entity: Readonly<Record<string, unknown>>, context: OperationContext): Promise<void>;
 export declare function effectiveRelationships(input: UpsertInput, entity: Readonly<Record<string, unknown>>, relationships: readonly RelationshipInput[], context: OperationContext): Promise<readonly RelationshipInput[]>;
-export declare function executeUpsert(input: UpsertInput, context: OperationContext): Promise<OperationResult<UpsertPayload>>;
+export type UpsertExecutionOptions = Readonly<{
+    /**
+     * Internal escape hatch for proof-receipt ingest: when provided, the
+     * authored document is written with exactly these bytes instead of the
+     * canonical re-render. Receipt appends must not canonicalize unrelated
+     * frontmatter — a mid-campaign reformat would change the workspace
+     * snapshot hash and make every later `kibi prove` integration refuse.
+     */
+    readonly sourceDocumentOverride?: string;
+    /**
+     * Internal escape hatch for `kibi proof prune`: the prune maintenance
+     * command deliberately shrinks a test's receipt history to its newest
+     * entries. Everything else keeps the append-only invariant fail-closed.
+     */
+    readonly allowReceiptsPrune?: boolean;
+}>;
+export declare function executeUpsert(input: UpsertInput, context: OperationContext, options?: UpsertExecutionOptions): Promise<OperationResult<UpsertPayload>>;
 //# sourceMappingURL=upsert.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"upsert.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/upsert.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0CAA0C,CAAC;AACjF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AAkCxE,OAAO,KAAK,EAAE,iBAAiB,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAkGhF,wBAAsB,sCAAsC,CAC1D,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACzC,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,IAAI,CAAC,CAaf;AAED,wBAAsB,sBAAsB,CAC1C,KAAK,EAAE,WAAW,EAClB,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACzC,aAAa,EAAE,SAAS,iBAAiB,EAAE,EAC3C,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,SAAS,iBAAiB,EAAE,CAAC,CAuBvC;AAkCD,wBAAsB,aAAa,CACjC,KAAK,EAAE,WAAW,EAClB,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,eAAe,CAAC,aAAa,CAAC,CAAC,CAqZzC"}
+{"version":3,"file":"upsert.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/upsert.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0CAA0C,CAAC;AACjF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AAkCxE,OAAO,KAAK,EAAE,iBAAiB,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAuGhF,wBAAsB,+BAA+B,CACnD,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACzC,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,IAAI,CAAC,CAaf;AAED,wBAAsB,sBAAsB,CAC1C,KAAK,EAAE,WAAW,EAClB,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACzC,aAAa,EAAE,SAAS,iBAAiB,EAAE,EAC3C,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,SAAS,iBAAiB,EAAE,CAAC,CAuBvC;AAmCD,MAAM,MAAM,sBAAsB,GAAG,QAAQ,CAAC;IAC5C;;;;;;OAMG;IAEH,QAAQ,CAAC,sBAAsB,CAAC,EAAE,MAAM,CAAC;IACzC;;;;OAIG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,OAAO,CAAC;CACvC,CAAC,CAAC;AAEH,wBAAsB,aAAa,CACjC,KAAK,EAAE,WAAW,EAClB,OAAO,EAAE,gBAAgB,EACzB,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAAC,eAAe,CAAC,aAAa,CAAC,CAAC,CAsczC"}