kibi-cli 2.1.0 → 2.3.0

package/dist/operations/proof/ingest-proof.js

@@ -1,5 +1,6 @@
 import { join } from "node:path";
 import { resolveBoundSymbolScope } from "../../extractors/manifest.js";
+import { loadCoveredBySymbolsByTest, receiptCodeScopeSymbolIds, } from "./code-scope.js";
 import { evaluateContractAgainstRun, } from "../../proof/evaluate.js";
 import { loadProofIntegrations, resolveIntegration, toExecution, } from "../../proof/integrations.js";
 import { loadEntities } from "../../public/operations/discovery-entities.js";
@@ -9,8 +10,32 @@ import { PROOF_CONTRACT_VERSION, PROOF_RECEIPT_VERSION, proofBindingsErrors, pro
 import { MAX_PROOF_RECEIPTS, proofReceiptCurrentBindingErrors, proofReceiptHistoryErrors, } from "../../public/proof-receipt.js";
 import { projectEntityProperties } from "../mutation/entity-projection.js";
 import { resolveContainedSourcePath } from "../mutation/source-authoring.js";
+import { buildUpsertBatchCommitGoal, parseUpsertChangeKinds, } from "../mutation/contradictions.js";
 import { executeUpsert } from "../mutation/upsert.js";
+import { acquireWorkspaceMutationLock, releaseWorkspaceMutationLock, } from "../mutation/workspace-mutation-lock.js";
+import { MutationRollbackFailureError } from "../mutation/saga.js";
 import { patchReceiptsIntoDocument, removeFrontmatterBlock, } from "./receipt-document.js";
+async function rollbackUncommittedReceipts(pending, originalError, lifecycle) {
+    const failures = [];
+    for (const entry of pending) {
+        if (entry.deferred.state === "committed")
+            continue;
+        try {
+            const rollbackFailures = await entry.deferred.rollback();
+            for (const failure of rollbackFailures) {
+                failures.push({ testId: entry.testId, ...failure });
+            }
+        }
+        catch (error) {
+            failures.push({ testId: entry.testId, step: "rollback", error });
+        }
+    }
+    if (failures.length > 0) {
+        lifecycle?.onRollbackFailure?.();
+        throw new AggregateError([originalError, ...failures.map((failure) => failure.error)], `Proof ingest failed and could not restore every uncommitted receipt source; the source mutation lock remains held for recovery (${failures.map(({ testId, step }) => `${testId}:${step}`).join(", ")})`);
+    }
+    throw originalError;
+}
 function text(value) {
     return typeof value === "string" ? value.trim() : "";
 }
@@ -120,7 +145,7 @@ function existingReceipts(test) {
         : [];
 }
 // implements REQ-kibi-verification-evidence-contract
-export async function executeIngestProof(args, context) {
+async function executeIngestProofUnlocked(args, context, lifecycle) {
     if (!context.prolog)
         throw new Error("Proof ingest requires a Prolog runtime");
     const snapshot = requiredString(args.snapshot, "snapshot");
@@ -162,18 +187,37 @@ export async function executeIngestProof(args, context) {
         }
     }
     else {
-        const all = await loadEntities(context.prolog, { type: "test" });
-        for (const test of all) {
-            const contract = record(test.proof_contract);
-            if (contract &&
-                contract.version === PROOF_CONTRACT_VERSION &&
-                text(contract.integration) === integrationId) {
-                tests.push(test);
+        // Select candidates from the paged contract projection (no receipt
+        // histories), then load each matching test in full: the append-only
+        // receipt update needs that test's existing history, but never every
+        // test's history in a single Prolog answer.
+        const candidates = await loadEntities(context.prolog, {
+            type: "test",
+            projection: "proof_contract",
+        });
+        for (const candidate of candidates) {
+            const contract = record(candidate.proof_contract);
+            if (!contract ||
+                contract.version !== PROOF_CONTRACT_VERSION ||
+                text(contract.integration) !== integrationId) {
+                continue;
             }
+            const testId = String(candidate.id);
+            const found = await loadEntities(context.prolog, {
+                id: testId,
+                type: "test",
+            });
+            const test = found[0];
+            if (!test)
+                throw new Error(`Proof ingest failed: test ${testId} was not found`);
+            tests.push(test);
         }
         if (tests.length === 0)
             throw new Error(`Proof ingest failed: no tests declare proof_contract.integration '${integrationId}'`);
     }
+    // Loaded outside the per-test binding try/catch: an engine failure must fail
+    // the ingest, not silently write receipts without a binding hash.
+    const coveredBy = await loadCoveredBySymbolsByTest(context.prolog);
     const prepared = [];
     for (const test of tests) {
         const testId = String(test.id);
@@ -207,7 +251,7 @@ export async function executeIngestProof(args, context) {
                 const absolute = resolveContainedSourcePath(context.workspaceRoot, source);
                 const authored = await context.fs.readFile(absolute);
                 const stripped = removeFrontmatterBlock(authored, "proof_receipts");
-                const codeScope = resolveBoundSymbolScope(join(context.workspaceRoot, ".kb", "symbols.yaml"), bindings.map((binding) => binding.symbol_id));
+                const codeScope = resolveBoundSymbolScope(join(context.workspaceRoot, ".kb", "symbols.yaml"), receiptCodeScopeSymbolIds(contract, bindings, coveredBy.get(testId) ?? []));
                 bindingHash = receiptBindingHash(contract, stripped ?? authored, codeScope);
             }
             catch {
@@ -253,82 +297,138 @@ export async function executeIngestProof(args, context) {
         });
     }
     const results = [];
+    const pendingCommits = [];
     let passed = 0;
     let failed = 0;
     let unchanged = 0;
-    for (const entry of prepared) {
-        const { testId, test, contract, evaluation, receipt, existing } = entry;
-        // Idempotent re-ingestion: the same artifact against the same effective
-        // contract+fingerprint derives the same receipt id and must not re-append.
-        if (existing.some((row) => row.receipt_id === receipt.receipt_id)) {
-            unchanged += 1;
-            if (receipt.outcome === "passed")
-                passed += 1;
-            else
-                failed += 1;
-            results.push({
+    try {
+        for (const entry of prepared) {
+            const { testId, test, contract, evaluation, receipt, existing } = entry;
+            // Idempotent re-ingestion: the same artifact against the same effective
+            // contract+fingerprint derives the same receipt id and must not re-append.
+            if (existing.some((row) => row.receipt_id === receipt.receipt_id)) {
+                unchanged += 1;
+                if (receipt.outcome === "passed")
+                    passed += 1;
+                else
+                    failed += 1;
+                results.push({
+                    testId,
+                    outcome: receipt.outcome,
+                    receiptId: receipt.receipt_id,
+                    applied: false,
+                    duplicate: true,
+                    receiptCount: existing.length,
+                    gaps: evaluation.gaps,
+                });
+                continue;
+            }
+            const nextReceipts = [
+                ...existing,
+                receipt,
+            ].slice(-MAX_PROOF_RECEIPTS);
+            const historyErrors = proofReceiptHistoryErrors(testId, test.verification_scope, nextReceipts);
+            const bindingErrors = proofReceiptCurrentBindingErrors(testId, test.verification_scope, receipt, contract, receipt.fingerprint);
+            const receiptErrors = [...historyErrors, ...bindingErrors];
+            if (receiptErrors.length > 0)
+                throw new Error(`Proof ingest failed for ${testId}: ${receiptErrors.join("; ")}`);
+            const properties = projectEntityProperties(test);
+            properties.proof_receipts = undefined;
+            // Surgical receipt append: splice only the proof_receipts block into the
+            // authored document so unrelated frontmatter keeps its authored form.
+            // Canonical re-rendering here would change non-receipt bytes, shift the
+            // workspace snapshot hash mid-campaign, and make later integrations in
+            // the same `kibi prove --all` refuse with "changed the tracked
+            // workspace". Falls back to the canonical render when the document is
+            // not a patchable markdown file.
+            let sourceDocumentOverride;
+            const source = typeof test.source === "string" ? test.source : "";
+            if (context.fs && source !== "" && /\.(md|mdx)$/i.test(source)) {
+                try {
+                    const absolute = resolveContainedSourcePath(context.workspaceRoot, source);
+                    const before = await context.fs.readFile(absolute);
+                    sourceDocumentOverride =
+                        patchReceiptsIntoDocument(before, nextReceipts) ?? undefined;
+                }
+                catch {
+                    sourceDocumentOverride = undefined;
+                }
+            }
+            // exactOptionalPropertyTypes: only pass the override when one exists.
+            const upsertOptions = {
+                deferCompiledCommit: true,
+                ...(sourceDocumentOverride === undefined
+                    ? {}
+                    : { sourceDocumentOverride }),
+            };
+            const upsert = await executeUpsert({
+                type: "test",
+                id: testId,
+                properties: { ...properties, proof_receipts: nextReceipts },
+            }, context, upsertOptions);
+            const deferred = upsert.structuredContent?.deferredCommit;
+            if (!deferred) {
+                throw new Error(`Proof ingest failed for ${testId}: receipt commit was not prepared`);
+            }
+            pendingCommits.push({
                 testId,
                 outcome: receipt.outcome,
                 receiptId: receipt.receipt_id,
-                applied: false,
-                duplicate: true,
-                receiptCount: existing.length,
+                receiptCount: nextReceipts.length,
                 gaps: evaluation.gaps,
+                deferred,
             });
-            continue;
         }
-        const nextReceipts = [
-            ...existing,
-            receipt,
-        ].slice(-MAX_PROOF_RECEIPTS);
-        const historyErrors = proofReceiptHistoryErrors(testId, test.verification_scope, nextReceipts);
-        const bindingErrors = proofReceiptCurrentBindingErrors(testId, test.verification_scope, receipt, contract, receipt.fingerprint);
-        const receiptErrors = [...historyErrors, ...bindingErrors];
-        if (receiptErrors.length > 0)
-            throw new Error(`Proof ingest failed for ${testId}: ${receiptErrors.join("; ")}`);
-        const properties = projectEntityProperties(test);
-        properties.proof_receipts = undefined;
-        // Surgical receipt append: splice only the proof_receipts block into the
-        // authored document so unrelated frontmatter keeps its authored form.
-        // Canonical re-rendering here would change non-receipt bytes, shift the
-        // workspace snapshot hash mid-campaign, and make later integrations in
-        // the same `kibi prove --all` refuse with "changed the tracked
-        // workspace". Falls back to the canonical render when the document is
-        // not a patchable markdown file.
-        let sourceDocumentOverride;
-        const source = typeof test.source === "string" ? test.source : "";
-        if (context.fs && source !== "" && /\.(md|mdx)$/i.test(source)) {
-            try {
-                const absolute = resolveContainedSourcePath(context.workspaceRoot, source);
-                const before = await context.fs.readFile(absolute);
-                sourceDocumentOverride =
-                    patchReceiptsIntoDocument(before, nextReceipts) ?? undefined;
-            }
-            catch {
-                sourceDocumentOverride = undefined;
+    }
+    catch (error) {
+        if (error instanceof MutationRollbackFailureError) {
+            lifecycle?.onRollbackFailure?.();
+        }
+        await rollbackUncommittedReceipts(pendingCommits, error, lifecycle);
+    }
+    const prolog = context.prolog;
+    if (!prolog)
+        throw new Error("Proof ingest failed: Prolog runtime is unavailable");
+    const batchSize = 25;
+    for (let offset = 0; offset < pendingCommits.length; offset += batchSize) {
+        const batch = pendingCommits.slice(offset, offset + batchSize);
+        let written;
+        try {
+            written = await prolog.query(buildUpsertBatchCommitGoal(batch.map((entry) => ({
+                entity: entry.deferred.entity,
+                relationships: entry.deferred.relationships,
+                skipContradictionCheck: entry.deferred.skipContradictionCheck,
+            }))));
+            if (!written.success) {
+                throw new Error(written.error || "batch commit failed");
             }
+            // Prolog success is the irreversible commit boundary. Finalize this
+            // batch before parsing auxiliary metadata or doing more work, so later
+            // failures can only roll back still-prepared source writes.
+            for (const entry of batch)
+                entry.deferred.finalize();
+            lifecycle?.onBatchCommitted?.();
+            prolog.invalidateCache?.();
+            parseUpsertChangeKinds(written.bindings, batch.length);
+        }
+        catch (error) {
+            await rollbackUncommittedReceipts(pendingCommits, error, lifecycle);
+        }
+        for (const entry of batch) {
+            if (entry.outcome === "passed")
+                passed += 1;
+            else
+                failed += 1;
+            results.push({
+                testId: entry.testId,
+                outcome: entry.outcome,
+                receiptId: entry.receiptId,
+                applied: true,
+                duplicate: false,
+                receiptCount: entry.receiptCount,
+                gaps: entry.gaps,
+            });
         }
-        // exactOptionalPropertyTypes: only pass the override when one exists.
-        const upsertOptions = sourceDocumentOverride === undefined ? {} : { sourceDocumentOverride };
-        const upsert = await executeUpsert({
-            type: "test",
-            id: testId,
-            properties: { ...properties, proof_receipts: nextReceipts },
-        }, context, upsertOptions);
-        void upsert;
-        if (receipt.outcome === "passed")
-            passed += 1;
-        else
-            failed += 1;
-        results.push({
-            testId,
-            outcome: receipt.outcome,
-            receiptId: receipt.receipt_id,
-            applied: true,
-            duplicate: false,
-            receiptCount: nextReceipts.length,
-            gaps: evaluation.gaps,
-        });
     }
     const summary = passed > 0
         ? `Proved ${passed} test(s)${failed > 0 ? `, ${failed} failed` : ""}${unchanged > 0 ? `, ${unchanged} unchanged` : ""}.`
@@ -346,3 +446,37 @@ export async function executeIngestProof(args, context) {
         },
     };
 }
+// implements REQ-kibi-verification-evidence-contract
+export async function executeIngestProof(args, context) {
+    if (!context.fs ||
+        context.sourceFirst === false ||
+        context.sourceMutationLockHeld === true) {
+        return executeIngestProofUnlocked(args, context);
+    }
+    const lock = await acquireWorkspaceMutationLock(context.workspaceRoot);
+    let operationFailure;
+    let committed = false;
+    let releaseSafe = true;
+    try {
+        return await executeIngestProofUnlocked(args, { ...context, sourceMutationLockHeld: true }, {
+            onBatchCommitted: () => {
+                committed = true;
+            },
+            onRollbackFailure: () => {
+                releaseSafe = false;
+            },
+        });
+    }
+    catch (error) {
+        operationFailure = { error };
+        throw error;
+    }
+    finally {
+        // A failed compensation must leave the cooperative lock fail-closed. The
+        // next writer will require verified recovery rather than observing a
+        // partially restored set of receipt documents.
+        if (releaseSafe) {
+            releaseWorkspaceMutationLock(lock, operationFailure, committed);
+        }
+    }
+}

package/dist/operations/proof/migrate-legacy-receipts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"migrate-legacy-receipts.d.ts","sourceRoot":"","sources":["../../../src/operations/proof/migrate-legacy-receipts.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0CAA0C,CAAC;AAOjF,MAAM,MAAM,yBAAyB,GAAG,QAAQ,CAAC;IAC/C,yCAAyC;IAEzC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC,CAAC;AAGH,MAAM,MAAM,2BAA2B,GAAG,QAAQ,CAAC;IAEjD,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,SAAS;QAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAC/C,CAAC,CAAC;AAEH;;;;;;;;;;GAUG;AAEH,wBAAsB,4BAA4B,CAChD,IAAI,EAAE,yBAAyB,EAC/B,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC;IACT,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/C,iBAAiB,EAAE,2BAA2B,CAAC;CAChD,CAAC,CAkFD"}
+{"version":3,"file":"migrate-legacy-receipts.d.ts","sourceRoot":"","sources":["../../../src/operations/proof/migrate-legacy-receipts.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0CAA0C,CAAC;AAOjF,MAAM,MAAM,yBAAyB,GAAG,QAAQ,CAAC;IAC/C,yCAAyC;IAEzC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC,CAAC;AAGH,MAAM,MAAM,2BAA2B,GAAG,QAAQ,CAAC;IAEjD,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,SAAS;QAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAC/C,CAAC,CAAC;AAEH;;;;;;;;;;GAUG;AAEH,wBAAsB,4BAA4B,CAChD,IAAI,EAAE,yBAAyB,EAC/B,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC;IACT,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/C,iBAAiB,EAAE,2BAA2B,CAAC;CAChD,CAAC,CAqFD"}

package/dist/operations/proof/migrate-legacy-receipts.js

@@ -15,7 +15,7 @@
  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 { loadEntities } from "../../public/operations/discovery-entities.js";
+import { loadEntities, loadEntitiesPaged, } from "../../public/operations/discovery-entities.js";
 import { projectEntityProperties } from "../mutation/entity-projection.js";
 import { resolveContainedSourcePath } from "../mutation/source-authoring.js";
 import { executeUpsert } from "../mutation/upsert.js";
@@ -37,10 +37,12 @@ export async function executeMigrateLegacyReceipts(args, context) {
         throw new Error("Legacy receipt migration requires a Prolog runtime");
     if (context.fs === undefined)
         throw new Error("Legacy receipt migration failed: this maintenance action rewrites authored test documents and requires a filesystem-capable runtime");
-    const tests = await loadEntities(context.prolog, {
-        type: "test",
-        ...(args.testId === undefined ? {} : { id: args.testId }),
-    });
+    // A bulk run pages full entities: receipt histories are exactly what this
+    // maintenance action reads, and loading all of them at once can exceed the
+    // bounded Prolog output capacity on long-lived stores.
+    const tests = args.testId === undefined
+        ? await loadEntitiesPaged(context.prolog, "test")
+        : await loadEntities(context.prolog, { type: "test", id: args.testId });
     if (args.testId !== undefined && tests.length === 0) {
         throw new Error(`Legacy receipt migration failed: test ${args.testId} was not found`);
     }

package/dist/operations/proof/prune-receipts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"prune-receipts.d.ts","sourceRoot":"","sources":["../../../src/operations/proof/prune-receipts.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0CAA0C,CAAC;AASjF,MAAM,MAAM,iBAAiB,GAAG,QAAQ,CAAC;IACvC,uDAAuD;IAEvD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,uCAAuC;IACvC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC,CAAC;AAGH,MAAM,MAAM,uBAAuB,GAAG,QAAQ,CAAC;IAE7C,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC,CAAC;AAEH,MAAM,MAAM,mBAAmB,GAAG,QAAQ,CAAC;IAEzC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,SAAS,uBAAuB,EAAE,CAAC;CAC3C,CAAC,CAAC;AAYH;;;;;;;;;GASG;AAEH,wBAAsB,oBAAoB,CACxC,IAAI,EAAE,iBAAiB,EACvB,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC;IACT,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/C,iBAAiB,EAAE,mBAAmB,CAAC;CACxC,CAAC,CAoED"}
+{"version":3,"file":"prune-receipts.d.ts","sourceRoot":"","sources":["../../../src/operations/proof/prune-receipts.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0CAA0C,CAAC;AASjF,MAAM,MAAM,iBAAiB,GAAG,QAAQ,CAAC;IACvC,uDAAuD;IAEvD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,uCAAuC;IACvC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC,CAAC;AAGH,MAAM,MAAM,uBAAuB,GAAG,QAAQ,CAAC;IAE7C,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC,CAAC;AAEH,MAAM,MAAM,mBAAmB,GAAG,QAAQ,CAAC;IAEzC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,SAAS,uBAAuB,EAAE,CAAC;CAC3C,CAAC,CAAC;AAYH;;;;;;;;;GASG;AAEH,wBAAsB,oBAAoB,CACxC,IAAI,EAAE,iBAAiB,EACvB,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC;IACT,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/C,iBAAiB,EAAE,mBAAmB,CAAC;CACxC,CAAC,CAuED"}

package/dist/operations/proof/prune-receipts.js

@@ -15,7 +15,7 @@
  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 { loadEntities } from "../../public/operations/discovery-entities.js";
+import { loadEntities, loadEntitiesPaged, } from "../../public/operations/discovery-entities.js";
 import { proofReceiptHistoryErrors, } from "../../public/proof-receipt.js";
 import { projectEntityProperties } from "../mutation/entity-projection.js";
 import { executeUpsert } from "../mutation/upsert.js";
@@ -44,10 +44,12 @@ export async function executePruneReceipts(args, context) {
     if (context.fs === undefined)
         throw new Error("Proof prune failed: this maintenance action rewrites authored test documents and requires a filesystem-capable runtime");
     const keep = parseKeep(args.keep);
-    const tests = await loadEntities(context.prolog, {
-        type: "test",
-        ...(args.testId === undefined ? {} : { id: args.testId }),
-    });
+    // A bulk run pages full entities: receipt histories are exactly what this
+    // maintenance action reads, and loading all of them at once can exceed the
+    // bounded Prolog output capacity on long-lived stores.
+    const tests = args.testId === undefined
+        ? await loadEntitiesPaged(context.prolog, "test")
+        : await loadEntities(context.prolog, { type: "test", id: args.testId });
     if (args.testId !== undefined && tests.length === 0) {
         throw new Error(`Proof prune failed: test ${args.testId} was not found`);
     }

package/dist/operations/semantic-advisor/analysis-receipt.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"analysis-receipt.d.ts","sourceRoot":"","sources":["../../../src/operations/semantic-advisor/analysis-receipt.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,EACL,KAAK,OAAO,EAMb,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EACV,6BAA6B,EAI7B,4BAA4B,EAC5B,0BAA0B,EAC1B,mBAAmB,EACnB,iBAAiB,EACjB,cAAc,EACf,MAAM,YAAY,CAAC;AAyBpB,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,SAAS,cAAc,EAAE,EAClC,OAAO,EAAE,OAAO,EAChB,WAAW,EAAE,SAAS,0BAA0B,EAAE,EAClD,OAAO,EAAE,SAAS,cAAc,EAAE,EAClC,YAAY,EAAE,SAAS,mBAAmB,EAAE,EAC5C,eAAe,EAAE,SAAS,4BAA4B,EAAE,EACxD,cAAc,EAAE,SAAS,iBAAiB,EAAE,GAC3C,6BAA6B,CAkH/B"}
+{"version":3,"file":"analysis-receipt.d.ts","sourceRoot":"","sources":["../../../src/operations/semantic-advisor/analysis-receipt.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,EACL,KAAK,OAAO,EAMb,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EACV,6BAA6B,EAI7B,4BAA4B,EAC5B,0BAA0B,EAC1B,mBAAmB,EACnB,iBAAiB,EACjB,cAAc,EACf,MAAM,YAAY,CAAC;AAyBpB,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,SAAS,cAAc,EAAE,EAClC,OAAO,EAAE,OAAO,EAChB,WAAW,EAAE,SAAS,0BAA0B,EAAE,EAClD,OAAO,EAAE,SAAS,cAAc,EAAE,EAClC,YAAY,EAAE,SAAS,mBAAmB,EAAE,EAC5C,eAAe,EAAE,SAAS,4BAA4B,EAAE,EACxD,cAAc,EAAE,SAAS,iBAAiB,EAAE,GAC3C,6BAA6B,CA2H/B"}

package/dist/operations/semantic-advisor/analysis-receipt.js

@@ -27,9 +27,15 @@ export function buildAdvisorResult(payload, signals, modeled, suggestions, claus
             : suggestions.some(({ kind }) => kind === "predicate")
                 ? "predicate"
                 : null;
+    const signalLane = chooseLane(signals);
+    const unresolvedNormative = propositions.some(({ role, status }) => role === "normative" &&
+        ["missing", "ambiguous", "ontology_gap"].includes(status));
     const candidateLane = modeled
         ? "none"
-        : (suggestionLane ?? chooseLane(signals));
+        : (suggestionLane ??
+            (signalLane === "none" && unresolvedNormative
+                ? "observation_review"
+                : signalLane));
     const readiness = modeled
         ? "modeled"
         : candidateLane === "none"

package/dist/operations/semantic-advisor/analyze-prose.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"analyze-prose.d.ts","sourceRoot":"","sources":["../../../src/operations/semantic-advisor/analyze-prose.ts"],"names":[],"mappings":"AAkCA,OAAO,KAAK,EACV,6BAA6B,EAC7B,oBAAoB,EAWrB,MAAM,YAAY,CAAC;AAEpB,eAAO,MAAM,wBAAwB,wBAAwB,CAAC;AAC9D,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAEhD,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,EAAE,CAI1D;AAg0BD,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,oBAAoB,GAC1B,6BAA6B,CA+D/B"}
+{"version":3,"file":"analyze-prose.d.ts","sourceRoot":"","sources":["../../../src/operations/semantic-advisor/analyze-prose.ts"],"names":[],"mappings":"AAmCA,OAAO,KAAK,EACV,6BAA6B,EAC7B,oBAAoB,EAWrB,MAAM,YAAY,CAAC;AAEpB,eAAO,MAAM,wBAAwB,wBAAwB,CAAC;AAC9D,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAEhD,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,EAAE,CAI1D;AAk2BD,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,oBAAoB,GAC1B,6BAA6B,CA+D/B"}

package/dist/operations/semantic-advisor/analyze-prose.js

@@ -2,7 +2,7 @@ import { createBuiltinOntologyPack, detectSignals as detectBuiltinSignals, } fro
 import { utf8Span, validateLogicIr, } from "../../logic/ir.js";
 import { logicRuleFactId } from "../modeling/logic-modeling.js";
 import { buildAdvisorResult } from "./analysis-receipt.js";
-import { extractSemanticClauses, semanticClaimKey, } from "./clauses.js";
+import { extractSemanticClauses, hasNormativeAssertion, semanticClaimKey, } from "./clauses.js";
 import { observationPlan } from "./observation-plan.js";
 import { predicateSuggestion as buildPredicateSuggestion, isRecord, payloadHash, propertiesOf, relationship, semanticClausesOf, semanticSourceHash, semanticSourceOf, sourceOf, statementOf, stringValue, } from "./shared.js";
 import { detectStrictSuggestion } from "./strict-rules.js";
@@ -371,11 +371,33 @@ function unmatchedClauseSuggestion(payload, clause, clauses, expectedClaimKeys)
     }, clause, clauses, expectedClaimKeys, statementOf(payload), semanticSourceOf(payload).field);
 }
 function propositionRole(statement, normative) {
-    if (/\b(?:for example|e\.g\.|such as|illustrative)\b/i.test(statement))
+    // Explicit context labels may quote obligations. Incidental explanatory
+    // words within an asserted obligation must not exempt it from grounding.
+    const assertedNormative = normative && hasNormativeAssertion(statement);
+    // A bare desired impression is subjective, even when phrased with should.
+    // Keep concrete actions, quantitative conditions and any independent
+    // obligation assertive instead of exempting them through subjective words.
+    const impression = /\bshould\s+(?:feel\s+(?:welcoming|comfortable|energetic)(?:\s+and\s+(?:welcoming|comfortable|energetic))*|(?:look|seem)\s+complete)\b/i.exec(statement);
+    const impressionTail = impression
+        ? statement.slice(impression.index + impression[0].length).trim()
+        : "";
+    const subjectiveAspiration = impression !== null &&
+        (impressionTail.length === 0 ||
+            /^(?:to|for)\s+[^,;.!?]+$/i.test(impressionTail)) &&
+        !/\b(?:and|or)\b/i.test(impressionTail) &&
+        !/\d|\b(?:at least|at most|exactly|within|no more than)\b/i.test(statement) &&
+        !hasNormativeAssertion(statement.replace(impression[0], ""));
+    if (/^\s*(?:for example\b|e\.g\.|(?:example|illustrative(?: example)?)\s*:)/i.test(statement) ||
+        (!assertedNormative &&
+            /\b(?:for example|e\.g\.|such as|illustrative)\b/i.test(statement)))
         return "example";
-    if (/\b(?:because|so that|in order to| rationale|therefore)\b/i.test(statement))
+    if (/^\s*rationale\s*:/i.test(statement) ||
+        (!assertedNormative &&
+            /\b(?:because|so that|in order to| rationale|therefore)\b/i.test(statement)))
         return "rationale";
-    if (/\b(?:feel|comfortable|looks complete|seems complete|subjective|prefer)\b/i.test(statement))
+    if (subjectiveAspiration ||
+        (!assertedNormative &&
+            /\b(?:feel|comfortable|looks complete|seems complete|subjective|prefer)\b/i.test(statement)))
         return "subjective";
     if (/\b(?:means|defined as|refers to|is called)\b/i.test(statement))
         return "definition";

package/dist/operations/semantic-advisor/clauses.d.ts

@@ -5,6 +5,7 @@ export type SemanticClause = Readonly<{
     normative: boolean;
     source: "detected" | "supplied";
 }>;
+export declare function hasNormativeAssertion(text: string): boolean;
 export declare function normalizeSemanticClause(value: string): string;
 export declare function semanticClaimKey(text: string): string;
 export declare function extractSemanticClauses(text: string, suppliedClauses?: readonly string[]): readonly SemanticClause[];

package/dist/operations/semantic-advisor/clauses.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"clauses.d.ts","sourceRoot":"","sources":["../../../src/operations/semantic-advisor/clauses.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,cAAc,GAAG,QAAQ,CAAC;IACpC,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,OAAO,CAAC;IACnB,MAAM,EAAE,UAAU,GAAG,UAAU,CAAC;CACjC,CAAC,CAAC;AAKH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAW7D;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAIrD;AA4BD,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,MAAM,EACZ,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,GAClC,SAAS,cAAc,EAAE,CA4B3B"}
+{"version":3,"file":"clauses.d.ts","sourceRoot":"","sources":["../../../src/operations/semantic-advisor/clauses.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,cAAc,GAAG,QAAQ,CAAC;IACpC,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,OAAO,CAAC;IACnB,MAAM,EAAE,UAAU,GAAG,UAAU,CAAC;CACjC,CAAC,CAAC;AAYH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE3D;AAED,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAW7D;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAIrD;AA4BD,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,MAAM,EACZ,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,GAClC,SAAS,cAAc,EAAE,CA4B3B"}

package/dist/operations/semantic-advisor/clauses.js

@@ -1,5 +1,11 @@
 import { createHash } from "node:crypto";
-const NORMATIVE_PATTERN = /\b(?:must|shall|should|required|requires?|may\s+only|may\s+(?:have\s+)?(?:at\s+most|at\s+least|exactly|no\s+more\s+than|up\s+to)|only\s+.+?\s+(?:may|can)|must\s+not|shall\s+not|cannot|can't|denied|forbidden|prohibited|(?:is|are|be|become|becomes|remain|remains)\s+(?:invalid|rejected|prohibited|forbidden)|(?:reject|rejects|rejected|rejection)\s+(?:invalid|unresolved|ambiguous)|fail(?:s|ed)?\s+(?:clearly|explicitly|with)|expires?\s+(?:after|within|in)|failure\s+(?:behavior|policy|outcome)|error\s+(?:handling|behavior|policy|outcome)|required\s+outcome|defaults?\s+to|before|unless|when|if)\b/i;
+const NORMATIVE_ASSERTION_PATTERN = /\b(?:must|shall|should|required|requires?|may\s+only|may\s+(?:have\s+)?(?:at\s+most|at\s+least|exactly|no\s+more\s+than|up\s+to)|only\s+.+?\s+(?:may|can)|must\s+not|shall\s+not|cannot|can't|denied|forbidden|prohibited|(?:is|are|be|become|becomes|remain|remains)\s+(?:invalid|rejected|prohibited|forbidden)|(?:reject|rejects|rejected|rejection)\s+(?:invalid|unresolved|ambiguous)|fail(?:s|ed)?\s+(?:clearly|explicitly|with)|expires?\s+(?:after|within|in)|failure\s+(?:behavior|policy|outcome)|error\s+(?:handling|behavior|policy|outcome)|required\s+outcome|defaults?\s+to)\b/i;
+// Conditional/temporal cues help discover clauses but do not by themselves
+// turn explanatory or subjective context into an asserted obligation.
+const NORMATIVE_PATTERN = new RegExp(`${NORMATIVE_ASSERTION_PATTERN.source}|\\b(?:before|unless|when|if)\\b`, "i");
+export function hasNormativeAssertion(text) {
+    return NORMATIVE_ASSERTION_PATTERN.test(text);
+}
 export function normalizeSemanticClause(value) {
     return (value
         .replace(/^\s*(?:[-*+]\s+|\d+[.)]\s+)/, "")

package/dist/performance-trace.d.ts

@@ -0,0 +1,17 @@
+export declare const KIBI_PERF_TRACE_DIR_ENV = "KIBI_PERF_TRACE_DIR";
+export declare const KIBI_PERF_TIMINGS_ENV = "KIBI_PERF_TIMINGS";
+export declare const KIBI_PERF_TRACE_MAX_EVENTS = 5000;
+export declare const KIBI_PERF_TRACE_MAX_BYTES: number;
+export type PerformanceTraceEventKind = "prolog-round-trip" | "prolog-process-cache-hit" | "engine-query-cache-hit" | "engine-freshness-cache-hit";
+interface PerformanceTraceEvent {
+    readonly kind: PerformanceTraceEventKind;
+    readonly durationMs: number;
+}
+/**
+ * Append one bounded, payload-free timing observation to the explicitly
+ * supplied private host trace directory. Trace I/O is best-effort and never
+ * changes the operation result.
+ */
+export declare function writePerformanceTraceEvent(event: PerformanceTraceEvent): void;
+export {};
+//# sourceMappingURL=performance-trace.d.ts.map

package/dist/performance-trace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"performance-trace.d.ts","sourceRoot":"","sources":["../src/performance-trace.ts"],"names":[],"mappings":"AAYA,eAAO,MAAM,uBAAuB,wBAAwB,CAAC;AAC7D,eAAO,MAAM,qBAAqB,sBAAsB,CAAC;AACzD,eAAO,MAAM,0BAA0B,OAAQ,CAAC;AAChD,eAAO,MAAM,yBAAyB,QAAa,CAAC;AAEpD,MAAM,MAAM,yBAAyB,GACjC,mBAAmB,GACnB,0BAA0B,GAC1B,wBAAwB,GACxB,4BAA4B,CAAC;AAEjC,UAAU,qBAAqB;IAC7B,QAAQ,CAAC,IAAI,EAAE,yBAAyB,CAAC;IACzC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAwHD;;;;GAIG;AACH,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,qBAAqB,GAAG,IAAI,CAoC7E"}