kibi-cli 2.13.0 → 2.15.0

package/dist/operations/modeling/predicate-catalog-6.js

@@ -0,0 +1,106 @@
+/**
+ * UI design patterns: which visual pattern a concept uses, which variants
+ * must share it, which code markers make it recognisable, and the layout
+ * shell it sits in. `kibi-plugin-ui` enforces these through its check policy;
+ * without that plugin they are ordinary predicates.
+ */
+// implements REQ-mcp-suggest-predicates, REQ-ui-pattern-vocabulary
+export const PREDICATE_CATALOG_6 = [
+    {
+        id: "FACT-SCHEMA-UI-PATTERN",
+        predicate_name: "ui_pattern",
+        title: "UI pattern",
+        description: "A UI concept must be presented with a named visual pattern, such as a line-and-dots timeline or a card list.",
+        argument_names: ["subject", "pattern"],
+        argument_types: ["ui_entity", "ui_pattern"],
+        argument_descriptions: [
+            "The UI concept or region, such as an annotation list.",
+            "The agreed visual pattern for that concept.",
+        ],
+        keywords: [
+            "pattern",
+            "design pattern",
+            "presented as",
+            "rendered as",
+            "displayed as",
+            "timeline",
+            "card list",
+            "layout pattern",
+        ],
+        aliases: ["visual pattern", "design direction"],
+        examples: ["ui_pattern(annotation_list, line_dots_timeline)"],
+        tags: ["ui", "design", "pattern"],
+    },
+    {
+        id: "FACT-SCHEMA-SAME-PATTERN",
+        predicate_name: "same_pattern",
+        title: "Same pattern across variants",
+        description: "Two variants of a UI concept (roles, viewports, presentations) must use the same visual pattern.",
+        argument_names: ["subject", "variant", "other_variant"],
+        argument_types: ["ui_entity", "ui_variant", "ui_variant"],
+        argument_descriptions: [
+            "The UI concept whose variants must not diverge.",
+            "One variant, such as a role or presentation.",
+            "The variant that must match it.",
+        ],
+        keywords: [
+            "same pattern",
+            "same design",
+            "consistent",
+            "for both",
+            "same timeline",
+            "must match",
+        ],
+        aliases: ["consistent across roles", "no divergent variant"],
+        examples: ["same_pattern(annotation_list, editor_view, read_only_view)"],
+        tags: ["ui", "design", "consistency"],
+    },
+    {
+        id: "FACT-SCHEMA-PATTERN-MARKER",
+        predicate_name: "pattern_marker",
+        title: "Pattern marker",
+        description: "A visual pattern is recognisable in code by a stable marker such as a CSS class or test id.",
+        argument_names: ["subject", "marker"],
+        argument_types: ["ui_pattern", "ui_marker"],
+        argument_descriptions: [
+            "The visual pattern the marker belongs to.",
+            "Literal class name or test id that implementations of the pattern contain.",
+        ],
+        keywords: [
+            "marker",
+            "marked by",
+            "class name",
+            "test id",
+            "data-testid",
+            "css class",
+        ],
+        aliases: ["pattern anchor"],
+        examples: ["pattern_marker(line_dots_timeline, timeline_dot)"],
+        tags: ["ui", "design", "pattern"],
+    },
+    {
+        id: "FACT-SCHEMA-UI-CONTAINER",
+        predicate_name: "ui_container",
+        title: "UI container",
+        description: "A UI region must sit in a container of a given size with a given overflow behaviour.",
+        argument_names: ["subject", "size", "overflow"],
+        argument_types: ["ui_entity", "ui_size", "ui_overflow"],
+        argument_descriptions: [
+            "The UI region the container holds.",
+            "Container size, such as half_page or full_height.",
+            "Overflow behaviour, such as scroll or clip.",
+        ],
+        keywords: [
+            "container",
+            "half page",
+            "half-page",
+            "scrollbar",
+            "scrollable",
+            "panel",
+            "overflow",
+        ],
+        aliases: ["layout shell"],
+        examples: ["ui_container(review_panel, half_page, scroll)"],
+        tags: ["ui", "design", "layout"],
+    },
+];

package/dist/operations/modeling/predicate-catalog.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"predicate-catalog.d.ts","sourceRoot":"","sources":["../../../src/operations/modeling/predicate-catalog.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACV,wBAAwB,EACxB,mBAAmB,EACpB,MAAM,sBAAsB,CAAC;AAO9B,eAAO,MAAM,mBAAmB,EAAE,mBAOjC,CAAC;AAGF,eAAO,MAAM,wBAAwB,EAAE,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAKxE,CAAC;AAGF,eAAO,MAAM,0BAA0B,EAAE,wBAAwB,EAMhE,CAAC"}
+{"version":3,"file":"predicate-catalog.d.ts","sourceRoot":"","sources":["../../../src/operations/modeling/predicate-catalog.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EACV,wBAAwB,EACxB,mBAAmB,EACpB,MAAM,sBAAsB,CAAC;AAO9B,eAAO,MAAM,mBAAmB,EAAE,mBAOjC,CAAC;AAGF,eAAO,MAAM,wBAAwB,EAAE,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAKxE,CAAC;AAGF,eAAO,MAAM,0BAA0B,EAAE,wBAAwB,EAOhE,CAAC"}

package/dist/operations/modeling/predicate-catalog.js

@@ -3,6 +3,7 @@ import { PREDICATE_CATALOG_2 } from "./predicate-catalog-2.js";
 import { PREDICATE_CATALOG_3 } from "./predicate-catalog-3.js";
 import { PREDICATE_CATALOG_4 } from "./predicate-catalog-4.js";
 import { PREDICATE_CATALOG_5 } from "./predicate-catalog-5.js";
+import { PREDICATE_CATALOG_6 } from "./predicate-catalog-6.js";
 import { PREDICATE_USAGE_HINTS_1 } from "./predicate-usage-hints-1.js";
 import { PREDICATE_USAGE_HINTS_2 } from "./predicate-usage-hints-2.js";
 import { PREDICATE_USAGE_HINTS_3 } from "./predicate-usage-hints-3.js";
@@ -30,4 +31,5 @@ export const BUILT_IN_PREDICATE_SCHEMAS = [
     ...PREDICATE_CATALOG_3,
     ...PREDICATE_CATALOG_4,
     ...PREDICATE_CATALOG_5,
+    ...PREDICATE_CATALOG_6,
 ];

package/dist/operations/modeling/predicate-usage-hints-4.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"predicate-usage-hints-4.d.ts","sourceRoot":"","sources":["../../../src/operations/modeling/predicate-usage-hints-4.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAGhE,eAAO,MAAM,uBAAuB,EAAE,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAkFvE,CAAC"}
+{"version":3,"file":"predicate-usage-hints-4.d.ts","sourceRoot":"","sources":["../../../src/operations/modeling/predicate-usage-hints-4.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAGhE,eAAO,MAAM,uBAAuB,EAAE,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAkHvE,CAAC"}

package/dist/operations/modeling/predicate-usage-hints-4.js

@@ -81,4 +81,36 @@ export const PREDICATE_USAGE_HINTS_4 = {
         ],
         // implements REQ-mcp-suggest-predicates
     },
+    ui_pattern: {
+        use_when: [
+            "Use when a UI concept must be presented with a named visual pattern that other screens or variants must not replace.",
+        ],
+        do_not_use_when: [
+            "Do not use for alignment between two elements (visual_layout_rule) or for colours and spacing a linter can check.",
+        ],
+    },
+    same_pattern: {
+        use_when: [
+            "Use when two variants of one UI concept, such as roles or presentations, must render the same visual pattern.",
+        ],
+        do_not_use_when: [
+            "Do not use when the variants are intentionally different; record that difference in the requirement instead.",
+        ],
+    },
+    pattern_marker: {
+        use_when: [
+            "Use to name a stable class or test id that every implementation of a visual pattern contains.",
+        ],
+        do_not_use_when: [
+            "Do not use for markers that change with content or styling, such as generated class names.",
+        ],
+    },
+    ui_container: {
+        use_when: [
+            "Use when a UI region must sit in a container of a named size with a named overflow behaviour, such as a half-page scroll panel.",
+        ],
+        do_not_use_when: [
+            "Do not use for exact pixel sizes or brand tokens a linter or stylesheet already enforces.",
+        ],
+    },
 };

package/dist/operations/modeling/suggest-predicates.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"suggest-predicates.d.ts","sourceRoot":"","sources":["../../../src/operations/modeling/suggest-predicates.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,gBAAgB,EAChB,UAAU,EACX,MAAM,0CAA0C,CAAC;AAyBlD,OAAO,KAAK,EAGV,mBAAmB,EACnB,qBAAqB,EACrB,uBAAuB,EACxB,MAAM,sBAAsB,CAAC;AAG9B,YAAY,EACV,iBAAiB,EACjB,wBAAwB,EACxB,mBAAmB,EACnB,0BAA0B,EAC1B,qBAAqB,EACrB,uBAAuB,GACxB,MAAM,sBAAsB,CAAC;AA6H9B,wBAAgB,sCAAsC,CACpD,IAAI,EAAE,IAAI,CAAC,mBAAmB,EAAE,qBAAqB,GAAG,gBAAgB,CAAC,EACzE,KAAK,EAAE,IAAI,CAAC,mBAAmB,EAAE,qBAAqB,GAAG,gBAAgB,CAAC,GACzE,MAAM,CAIR;AAED,wBAAgB,2CAA2C,CACzD,IAAI,EAAE,IAAI,CACR,mBAAmB,EACnB,qBAAqB,GAAG,OAAO,GAAG,gBAAgB,CACnD,EACD,KAAK,EAAE,IAAI,CACT,mBAAmB,EACnB,qBAAqB,GAAG,OAAO,GAAG,gBAAgB,CACnD,GACA,MAAM,CAKR;AA+HD,wBAAsB,yBAAyB,CAC7C,MAAM,EAAE,UAAU,GAAG,IAAI,EACzB,IAAI,EAAE,qBAAqB,EAC3B,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,uBAAuB,CAAC,CAwRlC;AAkID,wBAAsB,wBAAwB,CAC5C,IAAI,EAAE,qBAAqB,EAC3B,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,uBAAuB,CAAC,CAElC"}
+{"version":3,"file":"suggest-predicates.d.ts","sourceRoot":"","sources":["../../../src/operations/modeling/suggest-predicates.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,gBAAgB,EAChB,UAAU,EACX,MAAM,0CAA0C,CAAC;AA0BlD,OAAO,KAAK,EAGV,mBAAmB,EACnB,qBAAqB,EACrB,uBAAuB,EACxB,MAAM,sBAAsB,CAAC;AAG9B,YAAY,EACV,iBAAiB,EACjB,wBAAwB,EACxB,mBAAmB,EACnB,0BAA0B,EAC1B,qBAAqB,EACrB,uBAAuB,GACxB,MAAM,sBAAsB,CAAC;AA6H9B,wBAAgB,sCAAsC,CACpD,IAAI,EAAE,IAAI,CAAC,mBAAmB,EAAE,qBAAqB,GAAG,gBAAgB,CAAC,EACzE,KAAK,EAAE,IAAI,CAAC,mBAAmB,EAAE,qBAAqB,GAAG,gBAAgB,CAAC,GACzE,MAAM,CAIR;AAED,wBAAgB,2CAA2C,CACzD,IAAI,EAAE,IAAI,CACR,mBAAmB,EACnB,qBAAqB,GAAG,OAAO,GAAG,gBAAgB,CACnD,EACD,KAAK,EAAE,IAAI,CACT,mBAAmB,EACnB,qBAAqB,GAAG,OAAO,GAAG,gBAAgB,CACnD,GACA,MAAM,CAKR;AA+HD,wBAAsB,yBAAyB,CAC7C,MAAM,EAAE,UAAU,GAAG,IAAI,EACzB,IAAI,EAAE,qBAAqB,EAC3B,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,uBAAuB,CAAC,CAmTlC;AA2ID,wBAAsB,wBAAwB,CAC5C,IAAI,EAAE,qBAAqB,EAC3B,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,uBAAuB,CAAC,CAElC"}

package/dist/operations/modeling/suggest-predicates.js

@@ -6,7 +6,7 @@ import { semanticClaimKey } from "../semantic-advisor/clauses.js";
 import { composeOntologyCatalogForOperation } from "../semantic-advisor/plugin-orchestration.js";
 import { STRONG_APPLICABILITY_SCORE, WEAK_CANDIDATE_MARGIN, evaluateSemanticApplicability, } from "./predicate-applicability.js";
 import { buildGapApplyPlan, buildPredicateApplyPlan, buildPredicateSchemaDraft, buildRelationshipPlan, buildSuggestion, } from "./predicate-applyplan.js";
-import { buildBindingHints, describeBindingHints, } from "./predicate-binding-hints.js";
+import { buildBindingHints, describeBindingHints, unnamedParticipantArguments, } from "./predicate-binding-hints.js";
 import { BUILT_IN_PREDICATE_SCHEMAS } from "./predicate-catalog.js";
 import { inferSubject } from "./predicate-inference.js";
 import { loadExistingPredicateSchemas } from "./predicate-loader.js";
@@ -326,6 +326,20 @@ export async function handleKbSuggestPredicates(prolog, args, context) {
     const completeCandidate = recommendedCandidate && recommendedCandidate.binding_status === "complete"
         ? recommendedCandidate
         : undefined;
+    // implements REQ-model-predicates-participant-not-subject
+    // A schema whose participant argument (actor, role, owner) the claim never
+    // names does not fit the claim: no binding the agent could supply would be
+    // read from the claim. When every unbound argument of the recommended
+    // candidate is such a participant, the claim is an ontology gap, not a
+    // binding request. An argument unbound for another reason (a value the
+    // claim does name but in other words, a closed vocabulary) still asks for
+    // bindings.
+    const unnamedParticipants = recommendedCandidate && !completeCandidate
+        ? unnamedParticipantArguments(recommendedCandidate, text, requirementSubjects)
+        : [];
+    const schemaDoesNotFit = unnamedParticipants.length > 0 &&
+        unnamedParticipants.length ===
+            (recommendedCandidate?.unbound_arguments.length ?? 0);
     // The action names the predicate state; existingGrounding (non-empty) is
     // the separate "already grounded" signal. A complete candidate for a claim
     // that is already grounded becomes a replacement, never a second link.
@@ -337,7 +351,9 @@ export async function handleKbSuggestPredicates(prolog, args, context) {
             ? alreadyGrounded
                 ? "replace_grounding"
                 : "apply_requires_predicate"
-            : "provide_argument_bindings";
+            : schemaDoesNotFit
+                ? "record_ontology_gap"
+                : "provide_argument_bindings";
     const predicatePlan = completeCandidate
         ? buildPredicateApplyPlan(completeCandidate, args)
         : [];
@@ -349,7 +365,7 @@ export async function handleKbSuggestPredicates(prolog, args, context) {
         ? alreadyGrounded
             ? []
             : predicatePlan
-        : !recommendedCandidate && !unavailableSchema
+        : (!recommendedCandidate && !unavailableSchema) || schemaDoesNotFit
             ? buildGapApplyPlan(text, args)
             : [];
     const plannedFactId = typeof predicatePlan[0]?.id === "string" ? predicatePlan[0].id : null;
@@ -368,7 +384,10 @@ export async function handleKbSuggestPredicates(prolog, args, context) {
     if (alreadyGrounded) {
         warnings.push(`${args.requirementId} already grounds this claim (${claimKey}) through ${groundingSummary}. A modeled claim takes exactly one logical grounding relationship, so adding requires_predicate beside it fails the proposition-complete rule. ${replacementPlan ? "Keep the existing grounding, or follow replacementPlan to swap it for the predicate." : "Keep the existing grounding; no predicate replacement is available yet."}`);
     }
-    const bindingHints = recommendedAction === "provide_argument_bindings" && recommendedCandidate
+    // The hints stay on a schema that does not fit, so the agent can see which
+    // participant the claim would have to name.
+    const bindingHints = (recommendedAction === "provide_argument_bindings" || schemaDoesNotFit) &&
+        recommendedCandidate
         ? buildBindingHints(recommendedCandidate, text, requirementSubjects)
         : [];
     if (recommendedCandidate?.subject_pairing === "unpaired") {
@@ -385,13 +404,15 @@ export async function handleKbSuggestPredicates(prolog, args, context) {
             ? `To use ${completeCandidate?.predicate_name} instead, follow replacementPlan and link requires_predicate to ${plannedFactId}; otherwise keep the existing grounding.`
             : completeCandidate
                 ? `Suggested ${candidates.length} predicate candidate(s). Top applicable match: ${completeCandidate.predicate_name}. Apply the predicate fact ${plannedFactId}, then link requires_predicate to that fact id (not a candidate id).`
-                : recommendedCandidate
-                    ? `Matched ${recommendedCandidate.predicate_name}, but exact reviewed values are still required for: ${recommendedCandidate.unbound_arguments.join(", ")}. Bind them from the claim text: ${describeBindingHints(bindingHints)}. A value that repeats an argument name or a stop word stays unbound. No apply plan was generated.`
-                    : unavailableSchema
-                        ? `Requested predicate schema ${args.schemaId} is unavailable or semantically inapplicable. No apply plan was generated.`
-                        : alreadyGrounded
-                            ? "No predicate candidate passed the semantic applicability gate; keep the existing grounding and record the ontology-gap observation in applyPlan so the missing schema stays visible."
-                            : "No predicate candidate passed the semantic applicability gate; record an ontology gap and review the generated schema draft instead of silently writing prose.");
+                : schemaDoesNotFit && recommendedCandidate
+                    ? `Matched ${recommendedCandidate.predicate_name}, but the claim names no ${unnamedParticipants.join(" or ")} (${describeBindingHints(bindingHints)}), so this schema does not fit the claim. Record the ontology-gap observation in applyPlan instead of inventing a participant; a predicate_schema whose arguments the claim names would fit.`
+                    : recommendedCandidate
+                        ? `Matched ${recommendedCandidate.predicate_name}, but exact reviewed values are still required for: ${recommendedCandidate.unbound_arguments.join(", ")}. Bind them from the claim text: ${describeBindingHints(bindingHints)}. A value that repeats an argument name or a stop word stays unbound. No apply plan was generated.`
+                        : unavailableSchema
+                            ? `Requested predicate schema ${args.schemaId} is unavailable or semantically inapplicable. No apply plan was generated.`
+                            : alreadyGrounded
+                                ? "No predicate candidate passed the semantic applicability gate; keep the existing grounding and record the ontology-gap observation in applyPlan so the missing schema stays visible."
+                                : "No predicate candidate passed the semantic applicability gate; record an ontology gap and review the generated schema draft instead of silently writing prose.");
     const logicClaims = Array.from(new Set([...(args.existingLogicClaims ?? []), claimKey]));
     return {
         content: [{ type: "text", text: textSummary }],
@@ -475,11 +496,13 @@ async function storedRequirementProperties(prolog, requirementId, warnings) {
  * fact, retract the old grounding link, then link requires_predicate. The
  * order is forced: kb_upsert merges a requirement's relationships, so linking
  * first would give the claim two groundings and be rejected. Between the
- * retraction and the link the claim is ungrounded (kb_check reports
- * logic-coverage), so the steps run back to back and `rollback` restores the
- * old link if the last step fails.
+ * retraction and the link the claim is ungrounded and its subject fact is
+ * unpaired (kb_check reports logic-coverage and strict-req-fact-pairing for
+ * the requirement), so the steps run back to back; `expected` states those
+ * transient diagnostics and `rollback` restores the old link when kb_check
+ * after the last step is not clean.
  */
-// implements REQ-model-predicates-grounding-aware-v2, REQ-model-predicates-plan-roundtrip
+// implements REQ-model-predicates-grounding-aware-v2, REQ-model-predicates-plan-roundtrip, REQ-model-predicates-replacement-diagnostics
 function buildGroundingReplacementPlan(requirementId, factId, predicatePlan, existing, stored) {
     const requirementUpsert = (relationships) => ({
         type: "req",
@@ -490,8 +513,16 @@ function buildGroundingReplacementPlan(requirementId, factId, predicatePlan, exi
     const restate = stored === null
         ? `add the requirement's stored title and status as properties (they could not be read), keep this relationship only`
         : "the properties restate the stored title, status and metadata; kb_upsert keeps the stored proposition ledger";
+    const transientRules = ["logic-coverage", "strict-req-fact-pairing"];
     return {
         relationshipTarget: factId,
+        expected: {
+            // kb_check findings for the requirement after each step, by rule name
+            // (violations carry `rule`, quality diagnostics `rule.<name>`).
+            kbCheckAfterStep: [[], transientRules, []],
+            kbCheckAfterLastStep: [],
+            rollbackWhen: "kb_check after the last step is not clean",
+        },
         steps: [
             {
                 operation: "kb_upsert",
@@ -516,9 +547,9 @@ function buildGroundingReplacementPlan(requirementId, factId, predicatePlan, exi
         rollback: {
             operation: "kb_upsert",
             input: requirementUpsert(existing.map((row) => row.relationship)),
-            reason: "Only if the last step fails: restore the retracted grounding link so the claim is grounded again.",
+            reason: `Only if kb_check after the last step is not clean (it still reports ${transientRules.join(" or ")} for ${requirementId}, or the step failed): restore the retracted grounding link so the claim is grounded again.`,
         },
-        instructions: `Only replace the grounding when the predicate states the claim at least as precisely as ${existing.map((row) => row.factId).join(", ")}. Apply the steps unchanged, in order and back to back: linking requires_predicate before the retraction is rejected because the claim would have two groundings, and between the retraction and the link the claim is ungrounded, so kb_check reports logic-coverage for ${requirementId} until the last step lands. If the last step fails, apply rollback. Run kb_check after the last step.`,
+        instructions: `Only replace the grounding when the predicate states the claim at least as precisely as ${existing.map((row) => row.factId).join(", ")}. Apply the steps unchanged, in order and back to back: linking requires_predicate before the retraction is rejected because the claim would have two groundings, and between the retraction and the link the claim is ungrounded and its subject unpaired, so kb_check reports both ${transientRules.join(" and ")} for ${requirementId} until the last step lands (see expected.kbCheckAfterStep). Run kb_check after the last step; if it is not clean, apply rollback.`,
     };
 }
 export async function executeSuggestPredicates(args, context) {

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

@@ -6,6 +6,14 @@ type TransactionInput = {
     readonly skipContradictionCheck: boolean;
 };
 export declare function buildUpsertCommitGoal(input: TransactionInput): string;
+/**
+ * Goal that stages the same entity and relationships the commit goal would
+ * and runs the commit-time contradiction check inside a transaction that is
+ * always rolled back (kb_preview_upsert_contradiction/3). It succeeds when
+ * the commit would pass the check and fails with the commit's error when it
+ * would not; it never writes.
+ */
+export declare function buildUpsertContradictionPreviewGoal(input: TransactionInput): string;
 type WhatIfInput = TransactionInput & {
     readonly relationshipsOnly?: boolean;
 };

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

@@ -1 +1 @@
-{"version":3,"file":"contradictions.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/contradictions.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AASrE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEpD,KAAK,gBAAgB,GAAG;IACtB,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACnD,QAAQ,CAAC,aAAa,EAAE,SAAS,iBAAiB,EAAE,CAAC;IACrD,QAAQ,CAAC,sBAAsB,EAAE,OAAO,CAAC;CAC1C,CAAC;AAGF,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,gBAAgB,GAAG,MAAM,CAOrE;AAiBD,KAAK,WAAW,GAAG,gBAAgB,GAAG;IAAE,QAAQ,CAAC,iBAAiB,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC;AAgB/E;;;;;GAKG;AACH,wBAAgB,4BAA4B,CAC1C,MAAM,EAAE,SAAS,WAAW,EAAE,GAC7B,MAAM,CAER;AAGD;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,SAAS,WAAW,EAAE,GAC7B,MAAM,CAER;AAED,oEAAoE;AAEpE,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,SAAS,gBAAgB,EAAE,GAClC,MAAM,CAKR;AAGD,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,EAC1C,KAAK,EAAE,MAAM,GACZ,KAAK,CAAC,SAAS,GAAG,SAAS,CAAC,CAe9B;AAGD,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,MAAM,EAChB,GAAG,CAAC,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,iBAAiB,GACzB,MAAM,CAOR"}
+{"version":3,"file":"contradictions.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/contradictions.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AASrE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEpD,KAAK,gBAAgB,GAAG;IACtB,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACnD,QAAQ,CAAC,aAAa,EAAE,SAAS,iBAAiB,EAAE,CAAC;IACrD,QAAQ,CAAC,sBAAsB,EAAE,OAAO,CAAC;CAC1C,CAAC;AAGF,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,gBAAgB,GAAG,MAAM,CAOrE;AAGD;;;;;;GAMG;AACH,wBAAgB,mCAAmC,CACjD,KAAK,EAAE,gBAAgB,GACtB,MAAM,CAOR;AAiBD,KAAK,WAAW,GAAG,gBAAgB,GAAG;IAAE,QAAQ,CAAC,iBAAiB,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC;AAgB/E;;;;;GAKG;AACH,wBAAgB,4BAA4B,CAC1C,MAAM,EAAE,SAAS,WAAW,EAAE,GAC7B,MAAM,CAER;AAGD;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,SAAS,WAAW,EAAE,GAC7B,MAAM,CAER;AAED,oEAAoE;AAEpE,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,SAAS,gBAAgB,EAAE,GAClC,MAAM,CAKR;AAGD,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,EAC1C,KAAK,EAAE,MAAM,GACZ,KAAK,CAAC,SAAS,GAAG,SAAS,CAAC,CAe9B;AAGD,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,MAAM,EAChB,GAAG,CAAC,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,iBAAiB,GACzB,MAAM,CAOR"}

package/dist/operations/mutation/contradictions.js

@@ -7,6 +7,19 @@ export function buildUpsertCommitGoal(input) {
     const relationships = input.relationships.map((relationship) => `rel(${String(relationship.type)}, '${escapeAtom(String(relationship.from))}', '${escapeAtom(String(relationship.to))}', ${buildRelationshipMetadata(relationship)})`);
     return `kb_commit_upsert(${type}, ${buildPropertyList(input.entity)}, [${relationships.join(", ")}], ${input.skipContradictionCheck ? "true" : "false"}, ChangeKind)`;
 }
+// implements REQ-kibi-operation-interface-parity
+/**
+ * Goal that stages the same entity and relationships the commit goal would
+ * and runs the commit-time contradiction check inside a transaction that is
+ * always rolled back (kb_preview_upsert_contradiction/3). It succeeds when
+ * the commit would pass the check and fails with the commit's error when it
+ * would not; it never writes.
+ */
+export function buildUpsertContradictionPreviewGoal(input) {
+    const type = String(input.entity.type);
+    const relationships = input.relationships.map((relationship) => `rel(${String(relationship.type)}, '${escapeAtom(String(relationship.from))}', '${escapeAtom(String(relationship.to))}', ${buildRelationshipMetadata(relationship)})`);
+    return `kb_preview_upsert_contradiction(${type}, ${buildPropertyList(input.entity)}, [${relationships.join(", ")}])`;
+}
 function upsertBatchEntry(input) {
     const type = String(input.entity.type);
     const relationships = input.relationships.map((relationship) => `rel(${String(relationship.type)}, '${escapeAtom(String(relationship.from))}', '${escapeAtom(String(relationship.to))}', ${buildRelationshipMetadata(relationship)})`);

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

@@ -8,6 +8,18 @@ export type SourceWriteReceipt = Readonly<{
     created: boolean;
 }>;
 export declare function writePendingSourceReceipt(workspaceRoot: string, relativePath: string, afterHash: string): void;
+type FileTimes = Readonly<{
+    atime: Date;
+    mtime: Date;
+}>;
+/** The access and modification times of a file, or `null` when unreadable. */
+export declare function readFileTimes(absolutePath: string): FileTimes | null;
+/**
+ * Put a restored file's times back so freshness checks, which compare file
+ * times with the compiled snapshot, do not report a rolled-back write as a
+ * newer source. Best effort: a port without a host file is left alone.
+ */
+export declare function restoreFileTimes(absolutePath: string, times: FileTimes | null): void;
 /**
  * Retire the pending receipt of a source that a committed plan deleted. A
  * receipt binds untracked input to exact bytes, so one left behind for a
@@ -74,4 +86,5 @@ export declare function writeSourceForUpsert(input: UpsertInput, entity: Readonl
 } | null>;
 /** Resolve and normalize the canonical authored path for an entity. */
 export declare function canonicalSourcePath(context: OperationContext, input: UpsertInput, entity: Readonly<Record<string, unknown>>, existing?: Readonly<Record<string, unknown>>): string;
+export {};
 //# sourceMappingURL=source-authoring.d.ts.map

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

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

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

@@ -25,6 +25,46 @@ export function writePendingSourceReceipt(workspaceRoot, relativePath, afterHash
         createdAt: new Date().toISOString(),
     }, null, 2)}\n`, { mode: 0o600 });
 }
+/** The access and modification times of a file, or `null` when unreadable. */
+// implements REQ-core-atomic-upsert-persistence
+export function readFileTimes(absolutePath) {
+    try {
+        const stat = fs.statSync(absolutePath);
+        return { atime: stat.atime, mtime: stat.mtime };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Put a restored file's times back so freshness checks, which compare file
+ * times with the compiled snapshot, do not report a rolled-back write as a
+ * newer source. Best effort: a port without a host file is left alone.
+ */
+// implements REQ-core-atomic-upsert-persistence
+export function restoreFileTimes(absolutePath, times) {
+    if (times === null)
+        return;
+    try {
+        fs.utimesSync(absolutePath, times.atime, times.mtime);
+    }
+    catch {
+        // The bytes are restored; a failed time reset only costs a sync.
+    }
+}
+/**
+ * Snapshot a pending-source receipt's bytes, or `null` when none exists, so a
+ * rolled-back write can restore the receipt exactly as it found it.
+ */
+// implements REQ-core-atomic-upsert-persistence
+function readPendingSourceReceiptBytes(receiptPath) {
+    try {
+        return fs.readFileSync(receiptPath, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * Retire the pending receipt of a source that a committed plan deleted. A
  * receipt binds untracked input to exact bytes, so one left behind for a
@@ -644,6 +684,10 @@ export async function writeSourceForUpsert(input, entity, existing, context, sou
     catch {
         before = undefined;
     }
+    // Freshness compares file times with the compiled snapshot, so restoring
+    // the bytes alone would still make an untouched entity read as stale after
+    // a rolled-back write. Snapshot the times before the publication below.
+    const priorTimes = before === undefined ? null : readFileTimes(absolute);
     // 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
@@ -676,6 +720,12 @@ export async function writeSourceForUpsert(input, entity, existing, context, sou
         afterHash: digest(after),
         created: before === undefined,
     };
+    const pendingReceipt = pendingReceiptPath(context.workspaceRoot, relative);
+    // Snapshot the pending-source receipt before this write republishes it. A
+    // commit-time refusal restores the authored bytes, so the receipt must go
+    // back to the hash it bound before the write (or disappear again) or the
+    // next sync reports hash drift against a file that never changed.
+    const priorReceiptBytes = readPendingSourceReceiptBytes(pendingReceipt);
     const rollback = async () => {
         const fsPort = context.fs;
         if (fsPort === undefined)
@@ -700,8 +750,14 @@ export async function writeSourceForUpsert(input, entity, existing, context, sou
                 await fsPort.unlink(absolute);
             else
                 await fsPort.writeFile(absolute, "");
+            // implements REQ-core-atomic-upsert-persistence
+            // A receipt that predates this write (its file was removed outside
+            // Kibi) keeps binding the missing source so sync still reports it.
             try {
-                fs.unlinkSync(pendingReceiptPath(context.workspaceRoot, relative));
+                if (priorReceiptBytes === null)
+                    fs.unlinkSync(pendingReceipt);
+                else
+                    fs.writeFileSync(pendingReceipt, priorReceiptBytes, { mode: 0o600 });
             }
             catch {
                 // The pending receipt is advisory recovery metadata.
@@ -722,9 +778,21 @@ export async function writeSourceForUpsert(input, entity, existing, context, sou
                 await fsPort.unlink?.(rollbackTemp).catch(() => undefined);
                 throw error;
             }
+            // implements REQ-core-atomic-upsert-persistence
+            // The authored bytes are back to `before`; rebind the pending receipt
+            // and the file times to the same state they had before this write.
+            try {
+                if (priorReceiptBytes === null)
+                    fs.unlinkSync(pendingReceipt);
+                else
+                    fs.writeFileSync(pendingReceipt, priorReceiptBytes, { mode: 0o600 });
+            }
+            catch {
+                // The pending receipt is advisory recovery metadata.
+            }
+            restoreFileTimes(absolute, priorTimes);
         }
     };
-    const pendingReceipt = pendingReceiptPath(context.workspaceRoot, relative);
     try {
         if (receipt.afterHash !== null &&
             (before === undefined || fs.existsSync(pendingReceipt))) {

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":"AASA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0CAA0C,CAAC;AACjF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AAUxE,OAAO,EAAE,2BAA2B,EAAE,MAAM,sCAAsC,CAAC;AA4BnF,OAAO,EACL,KAAK,kBAAkB,EAExB,MAAM,oBAAoB,CAAC;AAQ5B,OAAO,KAAK,EACV,iBAAiB,EACjB,iBAAiB,EACjB,WAAW,EACX,aAAa,EACb,eAAe,EAChB,MAAM,YAAY,CAAC;AA6CpB,wBAAgB,gCAAgC,CAC9C,aAAa,EAAE,MAAM,EACrB,SAAS,EAAE,MAAM,GAChB,IAAI,CAkBN;AAmCD,wBAAsB,+BAA+B,CACnD,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACzC,OAAO,EAAE,gBAAgB,EACzB,MAAM,CAAC,EAAE,iBAAiB,GACzB,OAAO,CAAC,IAAI,CAAC,CAqBf;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,EACzB,MAAM,CAAC,EAAE,iBAAiB,EAC1B,MAAM,CAAC,EAAE,kBAAkB,GAC1B,OAAO,CAAC,SAAS,iBAAiB,EAAE,CAAC,CA8BvC;AAmCD,MAAM,MAAM,uBAAuB,GAAG,QAAQ,CAAC;IAC7C,kEAAkE;IAClE,QAAQ,CAAC,kBAAkB,CAAC,EAAE,OAAO,CAAC;IACtC;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,iBAAiB,CAAC;CACrC,CAAC,CAAC;AAGH,MAAM,MAAM,gBAAgB,GAAG,QAAQ,CAAC;IACtC,QAAQ,CAAC,SAAS,EAAE,eAAe,CAAC;IACpC,yEAAyE;IACzE,QAAQ,CAAC,aAAa,EAAE,SAAS,iBAAiB,EAAE,CAAC;IACrD,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC,OAAO,2BAA2B,CAAC,CAAC;CACnE,CAAC,CAAC;AAGH;;;;;;;;GAQG;AACH,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,WAAW,EACpB,OAAO,EAAE,gBAAgB,EACzB,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,gBAAgB,CAAC,CAgF3B;AAGD,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;IACtC;;;;OAIG;IACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,OAAO,CAAC;CACxC,CAAC,CAAC;AAyBH,wBAAsB,aAAa,CACjC,KAAK,EAAE,WAAW,EAClB,OAAO,EAAE,gBAAgB,EACzB,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAAC,eAAe,CAAC,aAAa,CAAC,CAAC,CAsgBzC"}
+{"version":3,"file":"upsert.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/upsert.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0CAA0C,CAAC;AACjF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AAUxE,OAAO,EAAE,2BAA2B,EAAE,MAAM,sCAAsC,CAAC;AA8BnF,OAAO,EACL,KAAK,kBAAkB,EAExB,MAAM,oBAAoB,CAAC;AAQ5B,OAAO,KAAK,EACV,iBAAiB,EACjB,iBAAiB,EACjB,WAAW,EACX,aAAa,EACb,eAAe,EAChB,MAAM,YAAY,CAAC;AA6CpB,wBAAgB,gCAAgC,CAC9C,aAAa,EAAE,MAAM,EACrB,SAAS,EAAE,MAAM,GAChB,IAAI,CAkBN;AAwCD,wBAAsB,+BAA+B,CACnD,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACzC,OAAO,EAAE,gBAAgB,EACzB,MAAM,CAAC,EAAE,iBAAiB,GACzB,OAAO,CAAC,IAAI,CAAC,CAqBf;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,EACzB,MAAM,CAAC,EAAE,iBAAiB,EAC1B,MAAM,CAAC,EAAE,kBAAkB,GAC1B,OAAO,CAAC,SAAS,iBAAiB,EAAE,CAAC,CA8BvC;AAmCD,MAAM,MAAM,uBAAuB,GAAG,QAAQ,CAAC;IAC7C,kEAAkE;IAClE,QAAQ,CAAC,kBAAkB,CAAC,EAAE,OAAO,CAAC;IACtC;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,iBAAiB,CAAC;CACrC,CAAC,CAAC;AAGH,MAAM,MAAM,gBAAgB,GAAG,QAAQ,CAAC;IACtC,QAAQ,CAAC,SAAS,EAAE,eAAe,CAAC;IACpC,yEAAyE;IACzE,QAAQ,CAAC,aAAa,EAAE,SAAS,iBAAiB,EAAE,CAAC;IACrD,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC,OAAO,2BAA2B,CAAC,CAAC;CACnE,CAAC,CAAC;AAGH;;;;;;;;GAQG;AACH,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,WAAW,EACpB,OAAO,EAAE,gBAAgB,EACzB,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,gBAAgB,CAAC,CAgF3B;AAGD,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;IACtC;;;;OAIG;IACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,OAAO,CAAC;CACxC,CAAC,CAAC;AAyBH,wBAAsB,aAAa,CACjC,KAAK,EAAE,WAAW,EAClB,OAAO,EAAE,gBAAgB,EACzB,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAAC,eAAe,CAAC,aAAa,CAAC,CAAC,CA4gBzC"}

package/dist/operations/mutation/upsert.js

@@ -20,7 +20,7 @@ import { assertPredicateArgumentVocabulary } from "./predicate-vocabulary-guard.
 import { existingRelationships, validateLiveRelationshipTargets, validateRelationshipSources, validateStrictLanePairing, validateSupersedesSourceHistory, } from "./relationships.js";
 import { withStoredRequirementSemantics } from "./requirement-semantics.js";
 import { MutationRollbackFailureError, MutationSaga } from "./saga.js";
-import { writePendingSourceReceipt, writeSourceForUpsert, } from "./source-authoring.js";
+import { readFileTimes, restoreFileTimes, writePendingSourceReceipt, writeSourceForUpsert, } from "./source-authoring.js";
 import { storedEntityLookup, } from "./stored-entity.js";
 import { acquireSymbolCompilerLock, releaseSymbolCompilerLock, } from "./symbol-compiler-lock.js";
 import { validateSymbolGranularity } from "./symbol-granularity.js";
@@ -69,7 +69,7 @@ export function assertRelationshipShardContained(workspaceRoot, shardPath) {
         throw new OperationError("SOURCE_PATH_INVALID", `Relationship shard follows a symlink outside the workspace: ${shardPath}`);
     }
 }
-function restoreRelationshipShard(shardPath, before, expectedAfterHash) {
+function restoreRelationshipShard(shardPath, before, expectedAfterHash, beforeTimes = null) {
     // 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.
@@ -96,6 +96,10 @@ function restoreRelationshipShard(shardPath, before, expectedAfterHash) {
         return;
     }
     writeFileSync(shardPath, before, "utf8");
+    // implements REQ-core-atomic-upsert-persistence
+    // Freshness compares file times with the compiled snapshot; a restored
+    // shard with a new time would read as a newer source after a refusal.
+    restoreFileTimes(shardPath, beforeTimes);
 }
 export async function validateAppendOnlyProofReceipts(entity, context, staged) {
     if (entity.type !== "test")
@@ -269,6 +273,7 @@ export async function executeUpsert(input, context, options = {}) {
     let sourceMutationLock;
     let operationFailure;
     const relationshipShardBefore = new Map();
+    const relationshipShardBeforeTimes = new Map();
     const relationshipShardAfterHash = new Map();
     let planRecoveryWarnings = [];
     const holdsSymbolCompilerLock = input.type === "symbol" &&
@@ -346,7 +351,7 @@ export async function executeUpsert(input, context, options = {}) {
                 name: "relationship-shards",
                 rollback: () => {
                     for (const [shardPath, before] of relationshipShardBefore) {
-                        restoreRelationshipShard(shardPath, before, relationshipShardAfterHash.get(shardPath) ?? null);
+                        restoreRelationshipShard(shardPath, before, relationshipShardAfterHash.get(shardPath) ?? null, relationshipShardBeforeTimes.get(shardPath) ?? null);
                     }
                 },
             });
@@ -360,6 +365,7 @@ export async function executeUpsert(input, context, options = {}) {
                 assertRelationshipShardContained(context.workspaceRoot, shardPath);
                 if (!relationshipShardBefore.has(shardPath)) {
                     relationshipShardBefore.set(shardPath, existsSync(shardPath) ? readFileSync(shardPath, "utf8") : null);
+                    relationshipShardBeforeTimes.set(shardPath, readFileTimes(shardPath));
                 }
                 appendRelationship(path.join(context.workspaceRoot, ".kb"), {
                     type,

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

@@ -1 +1 @@
-{"version":3,"file":"validate-upsert.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/validate-upsert.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,gBAAgB,EAEjB,MAAM,0CAA0C,CAAC;AAClD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AAOxE,OAAO,KAAK,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AA+CrE;;;;;GAKG;AACH,wBAAsB,qBAAqB,CACzC,KAAK,EAAE,WAAW,EAClB,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,eAAe,CAAC,qBAAqB,CAAC,CAAC,CA4DjD"}
+{"version":3,"file":"validate-upsert.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/validate-upsert.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,gBAAgB,EAEjB,MAAM,0CAA0C,CAAC;AAClD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AAWxE,OAAO,KAAK,EAEV,WAAW,EACX,qBAAqB,EACtB,MAAM,YAAY,CAAC;AA2EpB;;;;;GAKG;AACH,wBAAsB,qBAAqB,CACzC,KAAK,EAAE,WAAW,EAClB,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,eAAe,CAAC,qBAAqB,CAAC,CAAC,CAuEjD"}

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

@@ -4,6 +4,7 @@ import { entityIdStyleWarnings } from "../../utils/entity-id-style.js";
 import { analyzeSemanticAdvisorInput } from "../semantic-advisor/analyze-prose.js";
 import { assertSemanticInventoryBoundary } from "../semantic-advisor/ingestion-boundary.js";
 import { entityContextWarnings } from "./context-warning.js";
+import { buildUpsertContradictionPreviewGoal, formatUpsertError, } from "./contradictions.js";
 import { validateRelationshipSources } from "./relationships.js";
 import { validateSymbolGranularity } from "./symbol-granularity.js";
 import { validateAppendOnlyProofReceipts, validateUpsertForCommit, } from "./upsert.js";
@@ -13,6 +14,25 @@ async function entityExists(prolog, id) {
     const result = await prolog.query(`once(kb_entity('${escapeAtom(id)}', _Type, _Props))`);
     return result.success;
 }
+// implements REQ-kibi-operation-interface-parity, REQ-kibi-truthful-consistency
+/**
+ * The commit-time contradiction check, run against a staged and rolled-back
+ * copy of the store. Only a `req` commit runs it (facts and scenarios never
+ * do), and `_skipContradictionCheck` skips it at commit, so the preview skips
+ * it too. A refusal carries the same message the commit would raise.
+ */
+async function previewContradictions(prolog, input, entity, relationships) {
+    if (input.type !== "req" || input._skipContradictionCheck === true)
+        return;
+    const preview = await prolog.query(buildUpsertContradictionPreviewGoal({
+        entity,
+        relationships,
+        skipContradictionCheck: false,
+    }));
+    if (!preview.success) {
+        throw new Error(formatUpsertError(input.id, preview.error, preview.errorRecord));
+    }
+}
 /**
  * The validation chain for a runtime without a store: everything that does
  * not need to read the KB.
@@ -39,10 +59,16 @@ async function validateWithoutStore(input, context) {
 export async function executeValidateUpsert(input, context) {
     try {
         const { entity, semantic } = context.prolog !== undefined
-            ? await validateUpsertForCommit(input, context).then((result) => ({
-                entity: result.validated.entity,
-                semantic: result.semantic,
-            }))
+            ? await validateUpsertForCommit(input, context).then(async (result) => {
+                // The commit goal checks requirement contradictions after the
+                // validations above; a dry run previews that stage as well, so
+                // "valid" means the commit would not refuse the write.
+                await previewContradictions(context.prolog, input, result.validated.entity, result.validated.relationships);
+                return {
+                    entity: result.validated.entity,
+                    semantic: result.semantic,
+                };
+            })
             : await validateWithoutStore(input, context);
         // Style warnings apply only to entities this upsert would create, so the
         // existence read happens only when the ID actually has a style issue.