kibi-cli 0.19.0 → 2.0.0

package/dist/operations/mutation/upsert.js

@@ -1,14 +1,26 @@
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, realpathSync, unlinkSync, writeFileSync, } from "node:fs";
+import path from "node:path";
+import { OperationError } from "../../cli-errors.js";
+import { readManifestWithCoordinateOverlay } from "../../extractors/manifest.js";
+import { extractManifestSymbolRecords } from "../../extractors/manifest.js";
 import { escapeAtom } from "../../prolog/codec.js";
 import { loadEntities } from "../../public/operations/discovery-entities.js";
-import { appendOnlyVerificationReceiptHistoryErrors } from "../../public/verification-receipt.js";
+import { appendOnlyProofReceiptHistoryErrors } from "../../public/proof-receipt.js";
+import { appendRelationship, computeShardPath, } from "../../relationships/shards.js";
+import { resolveBranchAttachment } from "../../utils/branch-resolver.js";
 import { analyzeSemanticAdvisorInput } from "../semantic-advisor/analyze-prose.js";
 import { assertLogicalGroundingClaimKeys, assertSemanticInventoryBoundary, } from "../semantic-advisor/ingestion-boundary.js";
 import { buildUpsertCommitGoal, formatUpsertError } from "./contradictions.js";
-import { existingRelationships, validateLiveRelationshipTargets, validateRelationshipSources, validateStrictLanePairing, } from "./relationships.js";
+import { existingRelationships, validateLiveRelationshipTargets, validateRelationshipSources, validateStrictLanePairing, validateSupersedesSourceHistory, } from "./relationships.js";
+import { MutationSaga } from "./saga.js";
+import { writePendingSourceReceipt, writeSourceForUpsert, } from "./source-authoring.js";
+import { acquireSymbolCompilerLock, releaseSymbolCompilerLock, } from "./symbol-compiler-lock.js";
 import { validateSymbolGranularity } from "./symbol-granularity.js";
-import { refreshSymbolCoordinates } from "./symbol-refresh.js";
+import { refreshSymbolCoordinatesForManifest } from "./symbol-refresh.js";
 import { validateUpsertInput } from "./validation.js";
 import { scenarioCoverageWarnings } from "./warnings.js";
+import { acquireWorkspaceMutationLock, releaseWorkspaceMutationLock, } from "./workspace-mutation-lock.js";
 function requireProlog(context) {
     if (context.prolog === undefined) {
         throw new Error("Upsert operation requires a Prolog runtime");
@@ -28,33 +40,92 @@ function parseChangeKind(value) {
         ? normalized
         : null;
 }
-export async function validateAppendOnlyVerificationReceipts(entity, context) {
+function fileHash(pathname) {
+    if (!existsSync(pathname))
+        return null;
+    return createHash("sha256").update(readFileSync(pathname)).digest("hex");
+}
+function textHash(value) {
+    return createHash("sha256").update(value).digest("hex");
+}
+function assertRelationshipShardContained(workspaceRoot, shardPath) {
+    const root = path.resolve(workspaceRoot);
+    const relationshipRoot = path.resolve(root, ".kb", "relationships");
+    const absolute = path.resolve(shardPath);
+    if (!absolute.startsWith(`${relationshipRoot}${path.sep}`)) {
+        throw new OperationError("SOURCE_PATH_INVALID", `Relationship shard escapes the canonical workspace lane: ${shardPath}`);
+    }
+    let existing = absolute;
+    while (!existsSync(existing) && path.dirname(existing) !== existing) {
+        existing = path.dirname(existing);
+    }
+    const real = realpathSync.native(existing);
+    if (real !== root && !real.startsWith(`${root}${path.sep}`)) {
+        throw new OperationError("SOURCE_PATH_INVALID", `Relationship shard follows a symlink outside the workspace: ${shardPath}`);
+    }
+}
+function restoreRelationshipShard(shardPath, before, expectedAfterHash) {
+    // Compare before restore: a concurrent writer may have replaced the shard
+    // after our append. Never clobber newer bytes; the next check/sync reports
+    // any canonical source path that needs reconciliation.
+    if (expectedAfterHash !== null) {
+        let currentHash = null;
+        try {
+            currentHash = fileHash(shardPath);
+        }
+        catch {
+            currentHash = null;
+        }
+        if (currentHash !== expectedAfterHash) {
+            console.warn(`Skipped relationship shard rollback for ${path.relative(process.cwd(), shardPath)}: shard changed after the Kibi write.`);
+            return;
+        }
+    }
+    if (before === null) {
+        try {
+            unlinkSync(shardPath);
+        }
+        catch {
+            // The file may already be absent after an interrupted atomic replace.
+        }
+        return;
+    }
+    writeFileSync(shardPath, before, "utf8");
+}
+export async function validateAppendOnlyProofReceipts(entity, context) {
     if (entity.type !== "test")
         return;
     const existing = await loadEntities(requireProlog(context), {
         id: String(entity.id),
         type: "test",
     });
-    const previous = receiptRecords(existing[0]?.verification_receipts);
+    const previous = receiptRecords(existing[0]?.proof_receipts);
     if (!previous || previous.length === 0)
         return;
-    const next = receiptRecords(entity.verification_receipts);
-    const errors = appendOnlyVerificationReceiptHistoryErrors(previous, next);
+    const next = receiptRecords(entity.proof_receipts);
+    const errors = appendOnlyProofReceiptHistoryErrors(previous, next);
     if (errors.length > 0) {
         throw new Error(`Entity validation failed: ${errors.join("; ")}`);
     }
 }
 export async function effectiveRelationships(input, entity, relationships, context) {
-    if (input.relationships !== undefined && input.relationships.length > 0) {
-        return relationships;
-    }
     const prolog = requireProlog(context);
     const exists = await prolog.query(`once(kb_entity('${escapeAtom(input.id)}', _, _))`);
     if (!exists.success)
         return relationships;
     try {
-        const current = await existingRelationships(prolog, String(entity.id));
-        return current.length > 0 ? current : relationships;
+        const current = (await existingRelationships(prolog, String(entity.id)))
+            // An upsert owns only relationships whose source is the upserted entity.
+            // Incoming relationships must not be copied into its validation or
+            // canonical source projection.
+            .filter((relationship) => relationship.from === input.id);
+        const merged = new Map();
+        for (const relationship of [...current, ...relationships]) {
+            const key = `${String(relationship.type)}\u0000${String(relationship.from)}\u0000${String(relationship.to)}`;
+            // The explicit input wins so any supplied metadata is retained.
+            merged.set(key, relationship);
+        }
+        return [...merged.values()];
     }
     catch (error) {
         if (error instanceof Error)
@@ -62,55 +133,283 @@ export async function effectiveRelationships(input, entity, relationships, conte
         throw error;
     }
 }
-export async function executeUpsert(input, context) {
+/**
+ * Re-extract one complete canonical symbol entity from the authored manifest
+ * plus the freshly published generated coordinate artifact. Source-first
+ * commits must match exactly what the next sync would compile, instead of
+ * hand-merging generated fields into the caller's partial payload.
+ */
+function reextractCanonicalSymbolEntity(symbolId, authoredRelativePath, workspaceRoot) {
+    const absoluteManifest = path.resolve(workspaceRoot, authoredRelativePath);
+    let records;
+    try {
+        records = readManifestWithCoordinateOverlay(absoluteManifest);
+    }
+    catch (error) {
+        throw new Error(`Canonical symbol manifest ${authoredRelativePath} could not be compiled after coordinate refresh: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const mine = records.find((candidate) => candidate.id === symbolId);
+    if (mine === undefined)
+        return null;
+    const [result] = extractManifestSymbolRecords([mine], absoluteManifest);
+    if (result === undefined)
+        return null;
+    return {
+        ...result.entity,
+        ...(result.sourceFile === undefined
+            ? {}
+            : { sourceFile: result.sourceFile }),
+    };
+}
+export async function executeUpsert(input, context, options = {}) {
+    const branchAttachment = context.branchAttachment ?? resolveBranchAttachment(context.workspaceRoot);
+    if ("error" in branchAttachment) {
+        throw new Error(`Unable to resolve KB branch: ${branchAttachment.error}`);
+    }
+    if (branchAttachment.migrationRequired &&
+        (context.branchAttachment !== undefined || context.fs !== undefined)) {
+        throw new Error(`Upsert blocked: KB is attached through legacy branch storage (${branchAttachment.gitBranch} -> ${branchAttachment.kbBranch}). Run 'kibi branch migrate --from ${branchAttachment.kbBranch} --to ${branchAttachment.gitBranch} --apply' first.`);
+    }
     const prolog = requireProlog(context);
+    // Declared compensation list for the multi-surface mutation. Steps register
+    // as they succeed (authored source -> relationship shards -> coordinates);
+    // a failure rolls them back in reverse under the symbol compiler lock, and
+    // the compiled commit marks the point of no return.
+    const saga = new MutationSaga();
+    let sourceWrite = null;
+    let commitEntity;
+    let relationshipCount = 0;
+    let changeKind = null;
+    let semanticAdvisor;
+    let compilerLock;
+    let sourceMutationLock;
+    let operationFailure;
+    const relationshipShardBefore = new Map();
+    const relationshipShardAfterHash = new Map();
+    const holdsSymbolCompilerLock = input.type === "symbol" &&
+        context.fs !== undefined &&
+        context.sourceFirst !== false;
+    const holdsSourceMutationLock = context.fs !== undefined &&
+        context.sourceFirst !== false &&
+        context.sourceMutationLockHeld !== true;
     try {
+        if (holdsSourceMutationLock) {
+            sourceMutationLock = await acquireWorkspaceMutationLock(context.workspaceRoot);
+        }
+        if (holdsSymbolCompilerLock) {
+            // Symbol source publication, coordinate refresh, canonical
+            // re-extraction, and the RDF commit form one read-modify-write cycle.
+            // Serialize the whole cycle so concurrent full refreshes or sibling
+            // upserts cannot lose updates.
+            compilerLock = await acquireSymbolCompilerLock(context.workspaceRoot);
+        }
         const validated = validateUpsertInput(input, context.clock());
-        await validateAppendOnlyVerificationReceipts(validated.entity, context);
+        if (options.allowReceiptsPrune !== true) {
+            await validateAppendOnlyProofReceipts(validated.entity, context);
+        }
         validateRelationshipSources(input.id, validated.relationships);
         await validateSymbolGranularity(validated.entity, validated.relationships, context);
         const relationships = await effectiveRelationships(input, validated.entity, validated.relationships, context);
-        await validateStrictLanePairing(prolog, relationships);
-        await validateLiveRelationshipTargets(prolog, validated.entity, relationships);
+        relationshipCount = validated.relationships.length;
+        await validateStrictLanePairing(prolog, validated.relationships);
+        await validateLiveRelationshipTargets(prolog, validated.entity, validated.relationships);
+        await validateSupersedesSourceHistory(prolog, validated.entity, validated.relationships, context.workspaceRoot);
         const semantic = analyzeSemanticAdvisorInput({
             payload: { ...input, relationships },
         });
+        semanticAdvisor = semantic.receipt;
         assertSemanticInventoryBoundary({ ...input, relationships }, relationships, semantic.receipt);
         await assertLogicalGroundingClaimKeys(prolog, { ...input, relationships }, relationships);
+        if (context.fs !== undefined && context.sourceFirst !== false) {
+            const existingRows = await loadEntities(prolog, {
+                id: input.id,
+                type: input.type,
+            });
+            const existing = existingRows[0];
+            const existingSource = existing !== undefined && typeof existing.source === "string"
+                ? existing.source
+                : undefined;
+            // Existing non-authored runtime sources (mcp://, test://, etc.) have no
+            // tracked document to update unless the caller explicitly supplies one;
+            // new entities are required to choose a source target in this
+            // filesystem-capable context.
+            if (input.document !== undefined ||
+                existingSource?.match(/\.(?:md|mdx|ya?ml|json)$/i) ||
+                // A filesystem-capable runtime is source-first for every new entity.
+                // writeSourceForUpsert emits the typed DOCUMENT_PATH_REQUIRED request
+                // when configuration has zero or multiple writable targets, rather
+                // than silently creating compiled-only state.
+                existing === undefined) {
+                sourceWrite = await writeSourceForUpsert(input, validated.entity, existing, context, options.sourceDocumentOverride);
+                if (sourceWrite !== null) {
+                    const sourceStep = sourceWrite;
+                    saga.add({
+                        name: "authored-source",
+                        rollback: () => sourceStep.rollback(),
+                        onError: "capture",
+                    });
+                    // The authored path is the entity's canonical identity. Runtime
+                    // transport provenance (mcp://...) must never survive a source-first
+                    // write or a later delete/sync cycle.
+                    commitEntity = {
+                        ...validated.entity,
+                        source: sourceWrite.receipt.path,
+                    };
+                }
+            }
+        }
+        // Relationship shards are canonical source artifacts. Patch them before
+        // the compiled transaction so a failed commit can restore exact bytes and
+        // a successful commit never leaves a compiled-only relationship behind.
+        if (context.fs !== undefined && validated.relationships.length > 0) {
+            // Register the rollback before appending so a failure on any shard (for
+            // example the second write of a multi-shard batch) unwinds the shards
+            // that were already appended.
+            saga.add({
+                name: "relationship-shards",
+                rollback: () => {
+                    for (const [shardPath, before] of relationshipShardBefore) {
+                        restoreRelationshipShard(shardPath, before, relationshipShardAfterHash.get(shardPath) ?? null);
+                    }
+                },
+            });
+            for (const relationship of validated.relationships) {
+                const type = typeof relationship.type === "string" ? relationship.type : "";
+                const from = typeof relationship.from === "string" ? relationship.from : input.id;
+                const to = typeof relationship.to === "string" ? relationship.to : "";
+                if (!type || !from || !to)
+                    continue;
+                const shardPath = computeShardPath(path.join(context.workspaceRoot, ".kb"), from);
+                assertRelationshipShardContained(context.workspaceRoot, shardPath);
+                if (!relationshipShardBefore.has(shardPath)) {
+                    relationshipShardBefore.set(shardPath, existsSync(shardPath) ? readFileSync(shardPath, "utf8") : null);
+                }
+                appendRelationship(path.join(context.workspaceRoot, ".kb"), {
+                    type,
+                    from,
+                    to,
+                    created_at: context.clock().toISOString(),
+                    created_by: "kibi/upsert",
+                    source: "mcp://kibi/upsert",
+                });
+                relationshipShardAfterHash.set(shardPath, fileHash(shardPath));
+            }
+        }
+        // Coordinates are generated compiler state owned by
+        // `.kb/symbol-coordinates.yaml`. Refresh the target's generated record
+        // from current extraction (we hold the symbol compiler lock), then commit
+        // the complete canonical entity the next sync would compile. Failures
+        // abort before the RDF transaction so source and shard rollbacks keep all
+        // surfaces consistent; stale coordinates are never reused as a fallback.
+        if (input.type === "symbol" &&
+            context.fs !== undefined &&
+            context.sourceFirst !== false &&
+            sourceWrite !== null) {
+            const refresh = await refreshSymbolCoordinatesForManifest(input.id, path.resolve(context.workspaceRoot, sourceWrite.receipt.path), context);
+            const coordinatePublication = refresh.publication;
+            if (coordinatePublication !== undefined) {
+                saga.add({
+                    name: "symbol-coordinates",
+                    rollback: () => coordinatePublication.rollback(),
+                    onError: "capture",
+                });
+            }
+            if (!refresh.found || refresh.outcome === "removed") {
+                throw new Error(`Coordinate refresh could not find ${input.id} in the authored symbol manifest`);
+            }
+            const canonical = reextractCanonicalSymbolEntity(input.id, sourceWrite.receipt.path, context.workspaceRoot);
+            if (canonical === null) {
+                throw new Error(`Canonical symbol manifest ${sourceWrite.receipt.path} no longer contains ${input.id} after coordinate refresh`);
+            }
+            // The authored path is the entity's canonical identity. Runtime
+            // transport provenance (mcp://...) must never survive a source-first
+            // write or a later delete/sync cycle.
+            commitEntity = {
+                ...canonical,
+                source: sourceWrite.receipt.path,
+            };
+        }
         const transaction = buildUpsertCommitGoal({
-            entity: validated.entity,
-            relationships,
+            entity: commitEntity ?? validated.entity,
+            relationships: validated.relationships,
             skipContradictionCheck: input._skipContradictionCheck === true,
         });
         const written = await prolog.query(transaction);
         if (!written.success) {
-            throw new Error(formatUpsertError(input.id, written.error));
+            throw new Error(formatUpsertError(input.id, written.error, written.errorRecord));
         }
+        saga.markCommitted();
         // The combined commit is the sole mutation boundary. Invalidate reads only
         // after Prolog reports success so a failed/rolled-back commit does not
         // disturb callers' view of the current snapshot.
         prolog.invalidateCache?.();
-        const changeKind = parseChangeKind(written.bindings.ChangeKind);
+        changeKind = parseChangeKind(written.bindings.ChangeKind);
         if (changeKind === null) {
             throw new Error(`Upsert commit completed without a created/updated result for ${input.id}`);
         }
-        if (input.type === "symbol") {
-            try {
-                await refreshSymbolCoordinates(input.id, context);
-            }
-            catch (error) {
-                if (!(error instanceof Error))
-                    throw error;
-            }
-        }
         const coverage = await scenarioCoverageWarnings(prolog, validated.relationships, input.type, input.id);
         const created = changeKind === "created" ? 1 : 0;
+        const shardWarnings = [];
+        const relationshipSourceWrites = [];
+        for (const [shardPath, before] of relationshipShardBefore) {
+            const afterHash = fileHash(shardPath);
+            const beforeHash = before === null ? null : textHash(before);
+            const expectedAfterHash = relationshipShardAfterHash.get(shardPath) ?? null;
+            if (afterHash === null) {
+                if (expectedAfterHash !== null) {
+                    const relative = path
+                        .relative(context.workspaceRoot, shardPath)
+                        .replaceAll("\\", "/");
+                    shardWarnings.push(`Relationship shard vanished after write: ${relative}`);
+                }
+                continue;
+            }
+            if (afterHash === beforeHash)
+                continue;
+            const relative = path
+                .relative(context.workspaceRoot, shardPath)
+                .replaceAll("\\", "/");
+            writePendingSourceReceipt(context.workspaceRoot, relative, afterHash);
+            relationshipSourceWrites.push({
+                path: relative,
+                mode: "write",
+                beforeHash,
+                afterHash,
+                created: before === null,
+            });
+        }
         const payload = {
             created,
             updated: changeKind === "updated" ? 1 : 0,
-            relationships_created: relationships.length,
-            warnings: [...semantic.warnings, ...coverage],
+            relationships_created: validated.relationships.length,
+            warnings: [...semantic.warnings, ...coverage, ...shardWarnings],
             semanticAdvisor: semantic.receipt,
+            ...(shardWarnings.length > 0
+                ? {
+                    status: "committed_with_repairs",
+                    effectFailures: shardWarnings.map((detail) => ({
+                        kind: "workspace-write",
+                        errorCode: "RELATIONSHIP_SHARD_WRITE_FAILED",
+                        detail,
+                    })),
+                    nextActions: [
+                        {
+                            operation: "kb_check",
+                            reason: "Relationship shard publication failed after the KB commit; inspect the shard diagnostics and repair the canonical YAML before syncing.",
+                            required: true,
+                        },
+                    ],
+                }
+                : {}),
+            ...(sourceWrite ? { sourceWrites: [sourceWrite.receipt] } : {}),
+            ...(relationshipSourceWrites.length > 0
+                ? {
+                    sourceWrites: [
+                        ...(sourceWrite ? [sourceWrite.receipt] : []),
+                        ...relationshipSourceWrites,
+                    ],
+                }
+                : {}),
             ...(input.type === "req"
                 ? {
                     contradictionCheck: {
@@ -136,7 +435,79 @@ export async function executeUpsert(input, context) {
         };
     }
     catch (error) {
+        // Roll back every completed pre-commit surface in reverse order, exactly
+        // once. After the compiled commit this is a no-op: post-commit failures
+        // return committed-with-repairs results instead of undoing committed
+        // state.
+        const rollbackFailures = await saga.rollback();
+        if (saga.committed) {
+            const detail = error instanceof Error ? error.message : String(error);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Upserted ${input.id}, but a derived effect requires repair.`,
+                    },
+                ],
+                structuredContent: {
+                    created: changeKind === "created" ? 1 : 0,
+                    updated: changeKind === "updated" ? 1 : 0,
+                    relationships_created: relationshipCount,
+                    warnings: [detail],
+                    semanticAdvisor: semanticAdvisor,
+                    status: "committed_with_repairs",
+                    effectFailures: [
+                        {
+                            kind: "derived-effect",
+                            errorCode: "POST_COMMIT_EFFECT_FAILED",
+                            detail,
+                        },
+                    ],
+                    nextActions: [
+                        {
+                            operation: "kb_status",
+                            reason: "The compiled mutation committed; inspect the authoritative source and derived status before repairing.",
+                            required: true,
+                        },
+                        {
+                            operation: "kb_sync",
+                            reason: "Recompile canonical source files after the committed derived effect failure; do not retry the original upsert.",
+                            required: true,
+                        },
+                    ],
+                },
+            };
+        }
+        const coordinateFailure = rollbackFailures.find((failure) => failure.step === "symbol-coordinates");
+        if (coordinateFailure !== undefined) {
+            const failure = new AggregateError([error, coordinateFailure.error], `Upsert failed and coordinate artifact rollback failed for ${input.id}`);
+            operationFailure = { error: failure };
+            throw failure;
+        }
+        const sourceFailure = rollbackFailures.find((failure) => failure.step === "authored-source");
+        if (sourceFailure !== undefined) {
+            const rollbackMessage = sourceFailure.error instanceof Error
+                ? sourceFailure.error.message
+                : String(sourceFailure.error);
+            const failure = new AggregateError([error, sourceFailure.error], `Upsert failed and authored source rollback failed for ${input.id}: ${rollbackMessage}`);
+            operationFailure = { error: failure };
+            throw failure;
+        }
+        if (error instanceof OperationError) {
+            operationFailure = { error };
+            throw error;
+        }
         const message = error instanceof Error ? error.message : String(error);
-        throw new Error(`Upsert execution failed: ${message}`);
+        const failure = new Error(`Upsert execution failed: ${message}`);
+        operationFailure = { error: failure };
+        throw failure;
+    }
+    finally {
+        try {
+            releaseSymbolCompilerLock(compilerLock, operationFailure, saga.committed);
+        }
+        finally {
+            releaseWorkspaceMutationLock(sourceMutationLock, operationFailure, saga.committed);
+        }
     }
 }

package/dist/operations/mutation/validate-upsert.js

@@ -2,12 +2,12 @@ import { analyzeSemanticAdvisorInput } from "../semantic-advisor/analyze-prose.j
 import { assertLogicalGroundingClaimKeys, assertSemanticInventoryBoundary, validateSemanticInventoryBoundary, } from "../semantic-advisor/ingestion-boundary.js";
 import { validateLiveRelationshipTargets, validateRelationshipSources, } from "./relationships.js";
 import { validateSymbolGranularity } from "./symbol-granularity.js";
-import { effectiveRelationships, validateAppendOnlyVerificationReceipts, } from "./upsert.js";
+import { effectiveRelationships, validateAppendOnlyProofReceipts, } from "./upsert.js";
 import { validateUpsertInput } from "./validation.js";
 export async function executeValidateUpsert(input, context) {
     try {
         const validated = validateUpsertInput(input, context.clock());
-        await validateAppendOnlyVerificationReceipts(validated.entity, context);
+        await validateAppendOnlyProofReceipts(validated.entity, context);
         validateRelationshipSources(input.id, validated.relationships);
         await validateSymbolGranularity(validated.entity, validated.relationships, context);
         const previewSemantic = analyzeSemanticAdvisorInput({

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

@@ -1 +1 @@
-{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/validation.ts"],"names":[],"mappings":"AAIA,OAAO,EAEL,0BAA0B,EAC3B,MAAM,oCAAoC,CAAC;AAQ5C,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAiF/D,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,WAAW,EAClB,GAAG,EAAE,IAAI,GACR,eAAe,CAwDjB;AAED,OAAO,EAAE,0BAA0B,EAAE,CAAC"}
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/validation.ts"],"names":[],"mappings":"AAKA,OAAO,EAEL,0BAA0B,EAC3B,MAAM,oCAAoC,CAAC;AAO5C,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAkF/D,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,WAAW,EAClB,GAAG,EAAE,IAAI,GACR,eAAe,CA0DjB;AAED,OAAO,EAAE,0BAA0B,EAAE,CAAC"}

package/dist/operations/mutation/validation.js

@@ -1,9 +1,9 @@
 import Ajv from "ajv";
+import { proofReceiptHistoryErrors } from "../../public/proof-receipt.js";
 import entitySchema from "../../public/schemas/entity.js";
 import relationshipSchema from "../../public/schemas/relationship.js";
 // implements REQ-kibi-operation-interface-parity
 import { SYMBOL_ROLES, isAllowedGranularityReason, } from "../../public/symbol-granularity.js";
-import { verificationReceiptHistoryErrors } from "../../public/verification-receipt.js";
 import { semanticClaimKey } from "../semantic-advisor/clauses.js";
 import { factKindShapeHints, validateFactModelingShape, valueFieldHint, } from "./strict-fact.js";
 const ajv = new Ajv({ strict: false });
@@ -22,6 +22,7 @@ const validateEntity = ajv.compile({
                 "module-level-behavior",
                 "extractor-miss",
                 "legacy-link",
+                "test-suite",
             ],
         },
         symbol_role: { type: "string", enum: [...SYMBOL_ROLES] },
@@ -85,9 +86,11 @@ export function validateUpsertInput(input, now) {
     if (!validateEntity(entity)) {
         throw new Error(`Entity validation failed: ${formatEntityErrors(entity, validateEntity.errors ?? [])}`);
     }
-    if (entity.type === "test" && Array.isArray(entity.verification_receipts)) {
-        const receipts = entity.verification_receipts.filter((value) => typeof value === "object" && value !== null && !Array.isArray(value));
-        const receiptErrors = verificationReceiptHistoryErrors(input.id, entity.verification_scope, receipts);
+    validateSymbolSourceFile(entity);
+    validateProofExemptionPairing(entity);
+    if (entity.type === "test" && Array.isArray(entity.proof_receipts)) {
+        const receipts = entity.proof_receipts.filter((value) => typeof value === "object" && value !== null && !Array.isArray(value));
+        const receiptErrors = proofReceiptHistoryErrors(input.id, entity.verification_scope, receipts);
         if (receiptErrors.length > 0) {
             throw new Error(`Entity validation failed: ${receiptErrors.join("; ")}`);
         }
@@ -113,3 +116,43 @@ export function validateUpsertInput(input, now) {
     return { entity, relationships };
 }
 export { isAllowedGranularityReason };
+/**
+ * A symbol whose sourceFile points into .kb/ can publish coordinates to the
+ * artifact, but the engine never merges coordinates for KB-internal paths —
+ * coverage then reports missing_symbol_coordinates forever with no signal.
+ * Reject the configuration at upsert time instead.
+ */
+function validateSymbolSourceFile(entity) {
+    if (entity.type !== "symbol")
+        return;
+    const sourceFile = entity.sourceFile;
+    if (typeof sourceFile !== "string" || sourceFile.trim() === "")
+        return;
+    const normalized = sourceFile.replaceAll("\\", "/").trim();
+    if (normalized === ".kb" || normalized.startsWith(".kb/")) {
+        throw new Error(`Entity validation failed: symbol sourceFile must point at a real code file in the workspace, not into the knowledge base ('${sourceFile}'). Coordinates for .kb/ paths are never merged into the engine, so coverage would report missing_symbol_coordinates permanently. Point the symbol at the implementing or verifying code file instead.`);
+    }
+}
+/**
+ * proof_exempt parks a current requirement outside E2E-proof scope. Without a
+ * reason the requirement would disappear from the proof ladder silently, so
+ * the exemption only exists with its justification attached (mirrored in
+ * requirement_proof.pl, which ignores an exemption without a reason).
+ */
+function validateProofExemptionPairing(entity) {
+    if (entity.type !== "req")
+        return;
+    const flag = entity.proof_exempt;
+    const isExempt = flag === true ||
+        flag === "true" ||
+        flag === "yes" ||
+        flag === "on" ||
+        flag === 1 ||
+        flag === "1";
+    if (!isExempt)
+        return;
+    const reason = entity.proof_exempt_reason;
+    if (typeof reason !== "string" || reason.trim() === "") {
+        throw new Error("Entity validation failed: proof_exempt requires a non-empty proof_exempt_reason explaining why the requirement is outside E2E-proof scope");
+    }
+}

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

@@ -1,4 +1,5 @@
 import type { PrologPort } from "../../public/operations/runtime-types.js";
 import type { RelationshipInput } from "./types.js";
+export declare function scenarioCoverageWarning(entityId: string): readonly string[];
 export declare function scenarioCoverageWarnings(prolog: PrologPort, relationships: readonly RelationshipInput[], entityType: string, entityId: string): Promise<readonly string[]>;
 //# sourceMappingURL=warnings.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"warnings.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/warnings.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0CAA0C,CAAC;AAC3E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAGpD,wBAAsB,wBAAwB,CAC5C,MAAM,EAAE,UAAU,EAClB,aAAa,EAAE,SAAS,iBAAiB,EAAE,EAC3C,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,SAAS,MAAM,EAAE,CAAC,CAc5B"}
+{"version":3,"file":"warnings.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/warnings.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0CAA0C,CAAC;AAC3E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEpD,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAI3E;AAGD,wBAAsB,wBAAwB,CAC5C,MAAM,EAAE,UAAU,EAClB,aAAa,EAAE,SAAS,iBAAiB,EAAE,EAC3C,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,SAAS,MAAM,EAAE,CAAC,CAU5B"}

package/dist/operations/mutation/warnings.js

@@ -1,4 +1,9 @@
 import { escapeAtom } from "../../prolog/codec.js";
+export function scenarioCoverageWarning(entityId) {
+    return [
+        `Scenario-backed coverage: verified_by(${entityId},test) is valid but will not satisfy symbol-coverage because ${entityId} has specified_by a scenario. Use verified_by(scenario,test) or validates(test,scenario) instead.`,
+    ];
+}
 // implements REQ-kibi-operation-interface-parity
 export async function scenarioCoverageWarnings(prolog, relationships, entityType, entityId) {
     if (entityType !== "req")
@@ -7,11 +12,8 @@ export async function scenarioCoverageWarnings(prolog, relationships, entityType
         if (relationship.type !== "verified_by")
             continue;
         const result = await prolog.query(`once(kb_relationship(specified_by, '${escapeAtom(entityId)}', ScenarioId))`);
-        if (result.success) {
-            return [
-                `Scenario-backed coverage: verified_by(${entityId},test) is valid but will not satisfy symbol-coverage because ${entityId} has specified_by a scenario. Use verified_by(scenario,test) or validates(test,scenario) instead.`,
-            ];
-        }
+        if (result.success)
+            return scenarioCoverageWarning(entityId);
     }
     return [];
 }