@reventlessdev/reventless-spec 3.0.0-alpha.146 → 3.0.0-alpha.148

package/CHANGELOG.md

@@ -3,6 +3,20 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# 3.0.0-alpha.148 (2026-09-25)
+
+### Bug Fixes
+
+* **spec:** a chapter that carries both keys backs neither ([cbd823e](https://github.com/ReventlessDev/reventless-core/commit/cbd823e4f87ddd5810debd929bb536b2003d0e4c))
+
+
+# 3.0.0-alpha.147 (2026-09-25)
+
+### Bug Fixes
+
+* **spec,core:** a partition tag its chapter backs overrides inference ([4244a4a](https://github.com/ReventlessDev/reventless-core/commit/4244a4af9e7aad4378d9b6276ddeb44878e125b2))
+
+
 # 3.0.0-alpha.146 (2026-09-24)
 
 ### Features

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reventlessdev/reventless-spec",
-  "version": "3.0.0-alpha.146",
+  "version": "3.0.0-alpha.148",
   "description": "Specifications for Reventless",
   "license": "Apache-2.0",
   "bin": {

package/src/components/DcbScopeInference.res

@@ -211,33 +211,43 @@ Applying the give-back everywhere would be wrong: `AddProduct` reads
 `CategoryAdded({categoryId})` from a slice partitioned by `categoryId`, which
 would hand `categoryId` back and leave it two candidates.
 */
-let resolvePartitions = (slices: array<sliceShape>): partitionResolution => {
-  let producersByEventType: dict<array<sliceShape>> = Dict.make()
-  slices->Array.forEach(s =>
-    s.produced->Array.forEach(e => {
-      let prev = producersByEventType->Dict.get(e.eventType)->Option.getOr([])
-      if !(prev->Array.some(p => p.sliceName == s.sliceName)) {
-        producersByEventType->Dict.set(e.eventType, prev->Array.concat([s]))
-      }
-    })
-  )
-  // chapter -> the keys every id-carrying event written in that chapter carries.
-  let chapterKeys = Dict.make()
+/**
+Chapter -> the keys every id-carrying event written in that chapter carries: what the
+chapter says its slices are about. Rule 1's tie-break reads it, and so does the check
+that decides whether a `@partitionTag` inference disagrees with is the author's
+mistake or inference's (`DcbValidation.validatePartitionHintsVsInference`).
+*/
+let chapterKeys = (slices: array<sliceShape>): dict<array<string>> => {
+  let byChapter = Dict.make()
   slices->Array.forEach(s =>
     s.chapter->Option.forEach(chapter => {
       let events = s.produced->Array.filter(e => e.idFields->Array.length > 0)
       events->Array.forEach(
         e => {
           let keys = e->keysOfEvent
-          let shared = switch chapterKeys->Dict.get(chapter) {
+          let shared = switch byChapter->Dict.get(chapter) {
           | Some(prev) => prev->Array.filter(k => keys->Array.includes(k))
           | None => dedupSorted(keys)
           }
-          chapterKeys->Dict.set(chapter, shared)
+          byChapter->Dict.set(chapter, shared)
         },
       )
     })
   )
+  byChapter
+}
+
+let resolvePartitions = (slices: array<sliceShape>): partitionResolution => {
+  let producersByEventType: dict<array<sliceShape>> = Dict.make()
+  slices->Array.forEach(s =>
+    s.produced->Array.forEach(e => {
+      let prev = producersByEventType->Dict.get(e.eventType)->Option.getOr([])
+      if !(prev->Array.some(p => p.sliceName == s.sliceName)) {
+        producersByEventType->Dict.set(e.eventType, prev->Array.concat([s]))
+      }
+    })
+  )
+  let chapterKeys = chapterKeys(slices)
   let chapterKeysOf = (s: sliceShape) => s.chapter->Option.flatMap(c => chapterKeys->Dict.get(c))
   let byChapter = (s: sliceShape, candidates) =>
     switch s->chapterKeysOf {

package/src/components/DcbScopeInference.res.mjs

@@ -58,6 +58,20 @@ function sameAssignment(a, b) {
   return Primitive_object.equal(entries(a), entries(b));
 }
 
+function chapterKeys(slices) {
+  let byChapter = {};
+  slices.forEach(s => Stdlib_Option.forEach(s.chapter, chapter => {
+    let events = s.produced.filter(e => e.idFields.length !== 0);
+    events.forEach(e => {
+      let keys = e.idFields.map(tagKeyOf);
+      let prev = byChapter[chapter];
+      let shared = prev !== undefined ? prev.filter(k => keys.includes(k)) : dedupSorted(keys);
+      byChapter[chapter] = shared;
+    });
+  }));
+  return byChapter;
+}
+
 function resolvePartitions(slices) {
   let producersByEventType = {};
   slices.forEach(s => {
@@ -69,17 +83,8 @@ function resolvePartitions(slices) {
       }
     });
   });
-  let chapterKeys = {};
-  slices.forEach(s => Stdlib_Option.forEach(s.chapter, chapter => {
-    let events = s.produced.filter(e => e.idFields.length !== 0);
-    events.forEach(e => {
-      let keys = e.idFields.map(tagKeyOf);
-      let prev = chapterKeys[chapter];
-      let shared = prev !== undefined ? prev.filter(k => keys.includes(k)) : dedupSorted(keys);
-      chapterKeys[chapter] = shared;
-    });
-  }));
-  let chapterKeysOf = s => Stdlib_Option.flatMap(s.chapter, c => chapterKeys[c]);
+  let chapterKeys$1 = chapterKeys(slices);
+  let chapterKeysOf = s => Stdlib_Option.flatMap(s.chapter, c => chapterKeys$1[c]);
   let byChapter = (s, candidates) => {
     let keys = chapterKeysOf(s);
     if (keys === undefined) {
@@ -348,6 +353,7 @@ export {
   commandScalarKeys,
   foreignConsumedKeys,
   sameAssignment,
+  chapterKeys,
   resolvePartitions,
   partitionBlockers,
   crossPartitionForSlice,

package/src/components/DcbValidation.res

@@ -440,12 +440,15 @@ let validateCrossPartitionScope = (~producers: array<(string, S.t<unknown>)>): a
   warnings
 }
 
-/** Two-bucket result of validating annotations against the inferred scope. */
+/** Result of validating annotations against the inferred scope. */
 type scopeInferenceIssues = {
   /** Annotations that conflict with inference — likely bugs (warn/error). */
   contradictions: array<validationError>,
   /** Annotations inference already derives — safe to delete (info). */
   redundancies: array<validationError>,
+  /** Annotations that decide against inference where the slice's chapter backs them —
+      kept, and reported so the decision stays visible (info). */
+  overrides: array<validationError>,
 }
 
 /**
@@ -483,7 +486,7 @@ let validateScopeVsInference = (
       }
     )
   )
-  {contradictions, redundancies}
+  {contradictions, redundancies, overrides: []}
 }
 
 /**
@@ -493,6 +496,15 @@ Checks each `@partitionTag` against what inference derives with that hint remove
   hint names a key the slice only reads as a reference to another entity. Storage,
   fence and read scope would all follow the wrong key.
 - **Redundant** — inference reaches the same key unaided; the annotation can go.
+- **Override** — inference disagrees, but the slice's chapter backs the hint: every
+  id-carrying event written in the chapter carries the hinted key and not every one
+  carries the key inference chose, and every foreign
+  event the slice reads by that key is written by a slice partitioned by it. Rule 1
+  cannot tell an own key read back off a sibling's events from a reference
+  (`ShipOrder` writing `{orderId, carrierBookingId}` and reading `OrderPlaced` has
+  `AddProduct`'s shape exactly), and the hint is how the author says which. The
+  chapter is what separates the two: every event under `Order/` carries `orderId`,
+  while a `@partitionTag categoryId` on `AddProduct` disagrees with `Product/`.
 
 A hint that names a key the slice's events do not carry is not checked here:
 inference ignores it, and the boundary derivation reports the slice instead.
@@ -502,6 +514,45 @@ let validatePartitionHintsVsInference = (
 ): scopeInferenceIssues => {
   let contradictions: array<validationError> = []
   let redundancies: array<validationError> = []
+  let overrides: array<validationError> = []
+  let chapterKeys = DcbScopeInference.chapterKeys(shapes)
+  let producersOf = eventType =>
+    shapes->Array.filter(p => p.produced->Array.some(e => e.eventType == eventType))
+  // The chapter backs the hint, and what the slice reads by that key is its own
+  // entity: each foreign arm carrying it comes from a slice partitioned by it.
+  // Backing means telling the keys apart: a chapter whose events all carry both the
+  // hinted key and inference's (one slice, one event with both ids) says nothing
+  // about which one the slice is about, so it backs neither.
+  let backedByChapter = (s: DcbScopeInference.sliceShape, hint, inferred, partitionBySlice) => {
+    let chapterAgrees =
+      s.chapter
+      ->Option.flatMap(c => chapterKeys->Dict.get(c))
+      ->Option.mapOr(false, keys =>
+        keys->Array.includes(hint) && !(inferred->Array.some(k => keys->Array.includes(k)))
+      )
+    let own = s.produced->Array.map(e => e.eventType)
+    let readsOwnEntity =
+      s.consumed
+      ->Array.filter(e =>
+        !(own->Array.includes(e.eventType)) &&
+        e->DcbScopeInference.keysOfEvent->Array.includes(hint)
+      )
+      ->Array.every(e =>
+        switch producersOf(e.eventType) {
+        | [] => false
+        | producers =>
+          producers->Array.every(p => partitionBySlice->Dict.get(p.sliceName) == Some(hint))
+        }
+      )
+    chapterAgrees && readsOwnEntity
+  }
+  let overridden = (s: DcbScopeInference.sliceShape, hint, inference) =>
+    overrides->Array.push({
+      sliceName: s.sliceName,
+      message: `@partitionTag ${hint} decides the partition against inference (${inference}): every event in chapter ${s.chapter->Option.getOr(
+          "",
+        )} carries ${hint}, and what the slice reads by it is written by slices partitioned by ${hint}.`,
+    })
   shapes->Array.forEach(s =>
     switch s.partitionHint {
     | Some(hint) if DcbScopeInference.producedKeys(s)->Array.includes(hint) =>
@@ -546,6 +597,8 @@ let validatePartitionHintsVsInference = (
             sliceName: s.sliceName,
             message: `@partitionTag ${hint} is what inference derives without it — the annotation is redundant and can be removed.`,
           })
+        | Some(inferred) if backedByChapter(s, hint, [inferred], unaided.partitionBySlice) =>
+          overridden(s, hint, `it derives ${inferred}`)
         | Some(inferred) =>
           contradictions->Array.push({
             sliceName: s.sliceName,
@@ -553,7 +606,11 @@ let validatePartitionHintsVsInference = (
           })
         | None =>
           let candidates = unaided.candidatesBySlice->Dict.get(s.sliceName)->Option.getOr([])
-          if !(candidates->Array.includes(hint)) {
+          if candidates->Array.includes(hint) {
+            ()
+          } else if backedByChapter(s, hint, candidates, unaided.partitionBySlice) {
+            overridden(s, hint, `candidates: ${candidates->Array.join(", ")}`)
+          } else {
             contradictions->Array.push({
               sliceName: s.sliceName,
               message: `@partitionTag names ${hint}, which this slice only reads as a reference to another entity (candidates: ${candidates->Array.join(
@@ -566,7 +623,7 @@ let validatePartitionHintsVsInference = (
     | _ => ()
     }
   )
-  {contradictions, redundancies}
+  {contradictions, redundancies, overrides}
 }
 
 /**

package/src/components/DcbValidation.res.mjs

@@ -424,13 +424,52 @@ function validateScopeVsInference(annotations, inferred) {
   });
   return {
     contradictions: contradictions,
-    redundancies: redundancies
+    redundancies: redundancies,
+    overrides: []
   };
 }
 
 function validatePartitionHintsVsInference(shapes) {
   let contradictions = [];
   let redundancies = [];
+  let overrides = [];
+  let chapterKeys = DcbScopeInference$Reventless.chapterKeys(shapes);
+  let producersOf = eventType => shapes.filter(p => p.produced.some(e => e.eventType === eventType));
+  let backedByChapter = (s, hint, inferred, partitionBySlice) => {
+    let chapterAgrees = Stdlib_Option.mapOr(Stdlib_Option.flatMap(s.chapter, c => chapterKeys[c]), false, keys => {
+      if (keys.includes(hint)) {
+        return !inferred.some(k => keys.includes(k));
+      } else {
+        return false;
+      }
+    });
+    let own = s.produced.map(e => e.eventType);
+    let readsOwnEntity = s.consumed.filter(e => {
+      if (own.includes(e.eventType)) {
+        return false;
+      } else {
+        return DcbScopeInference$Reventless.keysOfEvent(e).includes(hint);
+      }
+    }).every(e => {
+      let producers = producersOf(e.eventType);
+      if (producers.length !== 0) {
+        return producers.every(p => Primitive_object.equal(partitionBySlice[p.sliceName], hint));
+      } else {
+        return false;
+      }
+    });
+    if (chapterAgrees) {
+      return readsOwnEntity;
+    } else {
+      return false;
+    }
+  };
+  let overridden = (s, hint, inference) => {
+    overrides.push({
+      sliceName: s.sliceName,
+      message: `@partitionTag ` + hint + ` decides the partition against inference (` + inference + `): every event in chapter ` + Stdlib_Option.getOr(s.chapter, "") + ` carries ` + hint + `, and what the slice reads by it is written by slices partitioned by ` + hint + `.`
+    });
+  };
   shapes.forEach(s => {
     let hint = s.partitionHint;
     if (hint === undefined) {
@@ -470,16 +509,23 @@ function validatePartitionHintsVsInference(shapes) {
           sliceName: s.sliceName,
           message: `@partitionTag ` + hint + ` is what inference derives without it — the annotation is redundant and can be removed.`
         });
+        return;
+      } else if (backedByChapter(s, hint, [inferred], unaided.partitionBySlice)) {
+        return overridden(s, hint, `it derives ` + inferred);
       } else {
         contradictions.push({
           sliceName: s.sliceName,
           message: `@partitionTag names ` + hint + `, but inference derives ` + inferred + ` from the slice graph — ` + hint + ` is read from another entity. Remove the annotation, or move it to ` + inferred + `.`
         });
+        return;
       }
-      return;
     }
     let candidates = Stdlib_Option.getOr(unaided.candidatesBySlice[s.sliceName], []);
-    if (!candidates.includes(hint)) {
+    if (candidates.includes(hint)) {
+      return;
+    } else if (backedByChapter(s, hint, candidates, unaided.partitionBySlice)) {
+      return overridden(s, hint, `candidates: ` + candidates.join(", "));
+    } else {
       contradictions.push({
         sliceName: s.sliceName,
         message: `@partitionTag names ` + hint + `, which this slice only reads as a reference to another entity (candidates: ` + candidates.join(", ") + `). Move the annotation to the slice's own key.`
@@ -489,7 +535,8 @@ function validatePartitionHintsVsInference(shapes) {
   });
   return {
     contradictions: contradictions,
-    redundancies: redundancies
+    redundancies: redundancies,
+    overrides: overrides
   };
 }