@reventlessdev/reventless-spec 3.0.0-alpha.61 → 3.0.0-alpha.63

package/CHANGELOG.md

@@ -3,12 +3,31 @@
 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.61 (2026-06-23)
+# 3.0.0-alpha.63 (2026-07-02)
+
+### Bug Fixes
+
+* **spec,interop,layer-builder:** generator/protocol/build failure modes (plan A8,A9) ([66d7a54](https://github.com/ReventlessDev/reventless-core/commit/66d7a54e3a0afdbfe3ea2975f517d1d64d52c180))
+
+
+# 3.0.0-alpha.62 (2026-06-29)
+
+### Features
+
+* external-system boxes for translation slices (Event Graph data) ([3f8ad39](https://github.com/ReventlessDev/reventless-core/commit/3f8ad39b78a3cb1182d59a0e1fb203b7dcb7379b))
 
-**Note:** Version bump only for package @reventlessdev/reventless-spec
 
+# 3.0.0-alpha.61 (2026-06-27)
 
+### Bug Fixes
+
+* **dcb:** harden scope inference against real catalog (partitionHint + rule 3) ([acea3f8](https://github.com/ReventlessDev/reventless-core/commit/acea3f8bb0e96a0993d81fd1aa521e9456982a13))
+* **dcb:** only infer cross-partition for SCALAR foreign references ([57416bf](https://github.com/ReventlessDev/reventless-core/commit/57416bf150df4c801577a60bf72f69abe9c701a8))
+### Features
 
+* **dcb:** add tag-scope inference core + runtime diff logging (Phase 1) ([5e17560](https://github.com/ReventlessDev/reventless-core/commit/5e17560fefc4272deb8b501dcb8ecef11c3a7c23))
+* **dcb:** thread inferred tag scope into the decision-query wiring (Phase 2) ([63445b2](https://github.com/ReventlessDev/reventless-core/commit/63445b239bc368932b043872ca16b6c35f723566))
+* **dcb:** validate [@cross](https://github.com/cross)Partition annotations against inferred scope ([acbb387](https://github.com/ReventlessDev/reventless-core/commit/acbb3870d32bbd4ef7e61ed52795800b87660e93))
 
 
 # 3.0.0-alpha.60 (2026-06-22)

package/package.json

@@ -1,16 +1,11 @@
 {
   "name": "@reventlessdev/reventless-spec",
-  "version": "3.0.0-alpha.61",
+  "version": "3.0.0-alpha.63",
   "description": "Specifications for Reventless",
   "license": "Apache-2.0",
   "bin": {
     "generate-plugin": "./run-generator.mjs"
   },
-  "scripts": {
-    "build": "rescript build",
-    "start": "rescript start",
-    "clean": "rescript clean"
-  },
   "dependencies": {
     "jsonschema2graphql": "1.1.1",
     "sury": "11.0.0-alpha.4",
@@ -30,5 +25,9 @@
     "url": "git+https://github.com/ReventlessDev/reventless-core.git",
     "directory": "reventless/reventless-spec"
   },
-  "gitHead": "c85024f7b9724d4215d34ecc712a14b43eac289d"
-}
+  "scripts": {
+    "build": "rescript build",
+    "start": "rescript start",
+    "clean": "rescript clean"
+  }
+}

package/src/components/DcbDecode.res

@@ -120,7 +120,15 @@ let makeDecoder = (schema: S.t<'event>): makeDecoderResult<'event> => {
       try {
         Some(JSON.Object(jsonDict)->S.parseJsonOrThrow(schema))
       } catch {
-      | _ => None
+      | _ =>
+        // A parse failure here means a stored event no longer matches the
+        // current schema (drift). Dropping it silently hid real data loss;
+        // surface it as a warning so it's diagnosable.
+        Console.warn(
+          "DcbDecode: dropped event `" ++
+          eventType ++ "` — payload does not match the current schema (drift?)",
+        )
+        None
       }
     }
 

package/src/components/DcbDecode.res.mjs

@@ -100,6 +100,7 @@ function makeDecoder(schema) {
     try {
       return Primitive_option.some(S.parseJsonOrThrow(jsonDict, schema));
     } catch (exn) {
+      console.warn("DcbDecode: dropped event `" + eventType + "` — payload does not match the current schema (drift?)");
       return;
     }
   };

package/src/components/DcbScopeInference.res

@@ -0,0 +1,244 @@
+/**
+DCB tag-scope inference (Phase 1 — pure core).
+
+Derives DCB tag scope from the *global* slice graph instead of hand-placed
+`@partitionTag` / `@crossPartition` / `@noTag` annotations. This module is
+deliberately **schema-agnostic**: its input carries only the structural shape of
+each slice (variant names + `*Id`-shaped fields), never an `S.t` schema and never
+a tag-metadata flag. That is precisely what we are replacing — so both the runtime
+(building shapes from `S.t` schemas, via `DcbTag.sliceShapeFromSchemas`) and the
+VS Code tooling (building shapes from parsed `.res` source) can feed the same
+`infer`. See `docs/plans/dcb-tag-scope-inference.md` § "Phase 1 design".
+
+The three rules (over the representation):
+
+1. **Owner / partition.** A slice's partition key is the key its *own* emitted
+   events are identified by — computed as `producedKeys(S)` minus the keys `S`
+   reads from a *foreign* producer (a consumed arm whose event type is produced by
+   a different slice). For `AddProduct` (`ProductAdded({productId, categoryId})`,
+   consuming `CategoryAdded({categoryId})`) the foreign-read `categoryId` is
+   removed, leaving `productId`. No fixpoint needed.
+
+2. **Cross-partition.** A key is cross-partition iff some slice reads it on a
+   *foreign* consumed event while partitioned by something else *and* the key is
+   another entity's partition. `AddProduct` reads `categoryId` (Category's
+   partition) while partitioned by `productId` ⇒ `categoryId` is cross-partition.
+
+3. **Index vs payload.** A `*Id` on an *emitted* event is indexed iff it is the
+   producing slice's own partition key. Foreign reference keys (e.g. `categoryId`
+   on `ProductAdded`) are payload ⇒ not indexed ⇒ the sibling-leak GSI write never
+   happens.
+*/
+
+/** A `*Id` / `*Ids`-shaped field, identified by name only (no schema, no tag flag). */
+type idField = {name: string, isList: bool}
+
+/** One variant arm: its constructor name and the `*Id` fields it carries. */
+type eventShape = {eventType: string, idFields: array<idField>}
+
+/**
+The structural shape of one slice, the boundary type both adapters produce:
+- `command` — the `*Id` fields on the slice's command,
+- `consumed` — the arms (and their `*Id` fields) the slice reads,
+- `produced` — the arms (and their `*Id` fields) the slice writes,
+- `partitionHint` — an explicit `@partitionTag` escape hatch (when the dev marked
+  the partition because the slice's own events legitimately carry two owned keys,
+  e.g. `RecordProductDemand`). Overrides the inferred partition.
+*/
+type sliceShape = {
+  sliceName: string,
+  command: array<idField>,
+  consumed: array<eventShape>,
+  produced: array<eventShape>,
+  partitionHint: option<string>,
+}
+
+/** Derived scope for one tag key. */
+type scope = Partition | CrossPartition | Payload
+
+/**
+The full derivation. `crossPartitionTagKeys` and `tagKeysByEventType` are the two
+values the runtime threads today (via `DcbTag.extractCrossPartitionTagKeys` /
+`mergeTagKeysByEventType`); under inference they are produced here.
+*/
+type derived = {
+  /** sliceName -> its inferred partition key (absent when ambiguous). */
+  partitionBySlice: dict<string>,
+  /** tag key -> the name of a slice that owns it as its partition. */
+  ownerByKey: dict<string>,
+  /** keys read cross-partition by some slice (sorted, deduped). */
+  crossPartitionTagKeys: array<string>,
+  /** produced eventType -> its indexed (non-payload) tag keys (sorted). */
+  tagKeysByEventType: dict<array<string>>,
+  /** (sliceName, reason) for slices whose partition couldn't be inferred. */
+  ambiguities: array<(string, string)>,
+}
+
+/**
+The tag key for a `*Id`-shaped field. A plural `*Ids: array<string>` shares the
+singular producer's key (trailing `s` stripped — `productIds` -> `productId`);
+a scalar `*Id` uses the field name verbatim. Mirrors the PPX's `*Ids` rule.
+*/
+let tagKeyOf = (f: idField): string =>
+  if f.isList && f.name->String.endsWith("s") {
+    f.name->String.slice(~start=0, ~end=f.name->String.length - 1)
+  } else {
+    f.name
+  }
+
+let dedupSorted = (keys: array<string>): array<string> => {
+  let seen = Set.make()
+  keys->Array.forEach(k => seen->Set.add(k))
+  Array.fromIterator(seen->Set.values)->Array.toSorted((a, b) => String.compare(a, b))
+}
+
+let keysOfEvent = (e: eventShape): array<string> => e.idFields->Array.map(tagKeyOf)
+
+let producedKeys = (s: sliceShape): array<string> =>
+  dedupSorted(s.produced->Array.flatMap(keysOfEvent))
+
+let consumedKeys = (s: sliceShape): array<string> =>
+  dedupSorted(s.consumed->Array.flatMap(keysOfEvent))
+
+/**
+Keys the command carries as a **scalar** (`*Id: string`, not `*Ids: array<string>`).
+A scalar tag is AND-ed with the partition into one composite clause unless it is
+read cross-partition, so only a scalar foreign reference needs the cross-partition
+fan. A foreign key the command carries *only* as an array already fans per element
+and stays partition-scoped (it reads the foreign entity's own partition) — the
+`PlaceOrder`/`productIds` shape — so it is **not** cross-partition.
+*/
+let commandScalarKeys = (s: sliceShape): array<string> =>
+  dedupSorted(s.command->Array.filter(f => !f.isList)->Array.map(tagKeyOf))
+
+/**
+Infers DCB tag scope for a set of slices (one DCB consistency boundary / plugin).
+Pure and total — never throws; unresolvable partitions land in `ambiguities`.
+*/
+/**
+The keys a slice reads from a *foreign* event — a consumed arm whose event type
+the slice does **not** itself produce. These are the candidate cross-entity
+references; they cannot be the slice's own partition. Defined on a single shape
+so it works both globally (in `infer`) and per-slice (in the GWT harness, which
+sees only one slice).
+*/
+let foreignConsumedKeys = (s: sliceShape): array<string> => {
+  let ownProduced = Set.make()
+  s.produced->Array.forEach(e => ownProduced->Set.add(e.eventType))
+  dedupSorted(
+    s.consumed->Array.flatMap(e => ownProduced->Set.has(e.eventType) ? [] : e->keysOfEvent),
+  )
+}
+
+/**
+Per-slice cross-partition keys for the test harness, which has no global owner
+map: a foreign-read key that is not the slice's own partition is read across
+partitions. Matches `infer`'s global rule 2 for the common "reference another
+entity" case; the harness unions this with any explicit `@crossPartition`
+annotation so capacity/escape-hatch reads remain covered.
+*/
+let crossPartitionForSlice = (s: sliceShape): array<string> => {
+  let foreign = foreignConsumedKeys(s)
+  let scalar = commandScalarKeys(s)
+  let partition = switch s.partitionHint {
+  | Some(h) if producedKeys(s)->Array.includes(h) => Some(h)
+  | _ =>
+    switch producedKeys(s)->Array.filter(k => !(foreign->Array.includes(k))) {
+    | [single] => Some(single)
+    | _ => None
+    }
+  }
+  // A foreign read is cross-partition only when the command carries the key as a
+  // scalar (must be fanned); an array-only foreign key auto-fans partition-scoped.
+  foreign->Array.filter(k => Some(k) != partition && scalar->Array.includes(k))
+}
+
+let infer = (slices: array<sliceShape>): derived => {
+  // Rule 1 — partition(S) = producedKeys(S) \ foreignConsumedKeys(S), where a
+  // foreign-consumed key rides a consumed arm the slice does not itself produce.
+  // An explicit @partitionTag hint overrides the derivation (escape hatch for
+  // slices whose own events legitimately carry two owned keys).
+  let partitionBySlice = Dict.make()
+  let ambiguities = []
+  slices->Array.forEach(s => {
+    let produced = producedKeys(s)
+    switch s.partitionHint {
+    | Some(h) if produced->Array.includes(h) => partitionBySlice->Dict.set(s.sliceName, h)
+    | _ =>
+      let foreign = foreignConsumedKeys(s)
+      switch produced->Array.filter(k => !(foreign->Array.includes(k))) {
+      | [single] => partitionBySlice->Dict.set(s.sliceName, single)
+      | [] =>
+        let _ = ambiguities->Array.push((
+          s.sliceName,
+          "no own partition key — every produced *Id is read from a foreign producer (pure join?); add an explicit @partitionTag",
+        ))
+      | many =>
+        let _ = ambiguities->Array.push((
+          s.sliceName,
+          `multiple candidate partition keys (${many->Array.join(", ")}) — add an explicit @partitionTag`,
+        ))
+      }
+    }
+  })
+
+  // owner map + the set of keys that are *some* entity's partition.
+  let ownerByKey = Dict.make()
+  let ownedPartitionKeys = Set.make()
+  slices->Array.forEach(s =>
+    switch partitionBySlice->Dict.get(s.sliceName) {
+    | Some(k) =>
+      ownedPartitionKeys->Set.add(k)
+      switch ownerByKey->Dict.get(k) {
+      | Some(_) => ()
+      | None => ownerByKey->Dict.set(k, s.sliceName)
+      }
+    | None => ()
+    }
+  )
+
+  // Rule 2 — a key read on a foreign consumed event that is another entity's
+  // partition (and not this slice's own partition) is cross-partition — but only
+  // when the command carries it as a SCALAR. A foreign key the command carries
+  // only as an array auto-fans per element and stays partition-scoped (it reads
+  // the foreign entity's own partition), so it is not cross-partition.
+  let crossKeys = Set.make()
+  slices->Array.forEach(s => {
+    let own = partitionBySlice->Dict.get(s.sliceName)
+    let scalar = commandScalarKeys(s)
+    s->consumedKeys->Array.forEach(k =>
+      if ownedPartitionKeys->Set.has(k) && Some(k) != own && scalar->Array.includes(k) {
+        crossKeys->Set.add(k)
+      }
+    )
+  })
+  let crossPartitionTagKeys =
+    Array.fromIterator(crossKeys->Set.values)->Array.toSorted((a, b) => String.compare(a, b))
+
+  // Rule 3 — a produced key is indexed iff it is the producing slice's own
+  // partition OR some slice issues a decision read of *that event type* by it
+  // (the key appears on a consumed arm naming the event type). Foreign reference
+  // keys that nobody reads this event type by are payload ⇒ no GSI write ⇒ the
+  // sibling leak is impossible. The read-by-anybody arm is what keeps a composite
+  // own-stream read (e.g. ProductDemandRecorded read by orderId) — and an M:N
+  // capacity read — correctly indexed without a hand annotation.
+  let readKeysByEventType = Dict.make()
+  slices->Array.forEach(s =>
+    s.consumed->Array.forEach(e => {
+      let prev = readKeysByEventType->Dict.get(e.eventType)->Option.getOr([])
+      readKeysByEventType->Dict.set(e.eventType, prev->Array.concat(e->keysOfEvent))
+    })
+  )
+  let tagKeysByEventType = Dict.make()
+  slices->Array.forEach(s => {
+    let own = partitionBySlice->Dict.get(s.sliceName)
+    s.produced->Array.forEach(e => {
+      let readKeys = readKeysByEventType->Dict.get(e.eventType)->Option.getOr([])
+      let indexed =
+        e->keysOfEvent->Array.filter(k => Some(k) == own || readKeys->Array.includes(k))
+      tagKeysByEventType->Dict.set(e.eventType, dedupSorted(indexed))
+    })
+  })
+
+  {partitionBySlice, ownerByKey, crossPartitionTagKeys, tagKeysByEventType, ambiguities}
+}

package/src/components/DcbScopeInference.res.mjs

@@ -0,0 +1,177 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
+import * as Primitive_object from "@rescript/runtime/lib/es6/Primitive_object.js";
+import * as Primitive_string from "@rescript/runtime/lib/es6/Primitive_string.js";
+
+function tagKeyOf(f) {
+  if (f.isList && f.name.endsWith("s")) {
+    return f.name.slice(0, f.name.length - 1 | 0);
+  } else {
+    return f.name;
+  }
+}
+
+function dedupSorted(keys) {
+  let seen = new Set();
+  keys.forEach(k => {
+    seen.add(k);
+  });
+  return Array.from(seen.values()).toSorted(Primitive_string.compare);
+}
+
+function keysOfEvent(e) {
+  return e.idFields.map(tagKeyOf);
+}
+
+function producedKeys(s) {
+  return dedupSorted(s.produced.flatMap(keysOfEvent));
+}
+
+function consumedKeys(s) {
+  return dedupSorted(s.consumed.flatMap(keysOfEvent));
+}
+
+function commandScalarKeys(s) {
+  return dedupSorted(s.command.filter(f => !f.isList).map(tagKeyOf));
+}
+
+function foreignConsumedKeys(s) {
+  let ownProduced = new Set();
+  s.produced.forEach(e => {
+    ownProduced.add(e.eventType);
+  });
+  return dedupSorted(s.consumed.flatMap(e => {
+    if (ownProduced.has(e.eventType)) {
+      return [];
+    } else {
+      return e.idFields.map(tagKeyOf);
+    }
+  }));
+}
+
+function crossPartitionForSlice(s) {
+  let foreign = foreignConsumedKeys(s);
+  let scalar = commandScalarKeys(s);
+  let h = s.partitionHint;
+  let partition;
+  let exit = 0;
+  if (h !== undefined && producedKeys(s).includes(h)) {
+    partition = h;
+  } else {
+    exit = 1;
+  }
+  if (exit === 1) {
+    let match = producedKeys(s).filter(k => !foreign.includes(k));
+    partition = match.length !== 1 ? undefined : match[0];
+  }
+  return foreign.filter(k => {
+    if (Primitive_object.notequal(k, partition)) {
+      return scalar.includes(k);
+    } else {
+      return false;
+    }
+  });
+}
+
+function infer(slices) {
+  let partitionBySlice = {};
+  let ambiguities = [];
+  slices.forEach(s => {
+    let produced = producedKeys(s);
+    let h = s.partitionHint;
+    if (h !== undefined && produced.includes(h)) {
+      partitionBySlice[s.sliceName] = h;
+      return;
+    }
+    let foreign = foreignConsumedKeys(s);
+    let many = produced.filter(k => !foreign.includes(k));
+    let len = many.length;
+    if (len !== 1) {
+      if (len !== 0) {
+        ambiguities.push([
+          s.sliceName,
+          `multiple candidate partition keys (` + many.join(", ") + `) — add an explicit @partitionTag`
+        ]);
+      } else {
+        ambiguities.push([
+          s.sliceName,
+          "no own partition key — every produced *Id is read from a foreign producer (pure join?); add an explicit @partitionTag"
+        ]);
+      }
+      return;
+    }
+    let single = many[0];
+    partitionBySlice[s.sliceName] = single;
+  });
+  let ownerByKey = {};
+  let ownedPartitionKeys = new Set();
+  slices.forEach(s => {
+    let k = partitionBySlice[s.sliceName];
+    if (k === undefined) {
+      return;
+    }
+    ownedPartitionKeys.add(k);
+    let match = ownerByKey[k];
+    if (match !== undefined) {
+      return;
+    } else {
+      ownerByKey[k] = s.sliceName;
+      return;
+    }
+  });
+  let crossKeys = new Set();
+  slices.forEach(s => {
+    let own = partitionBySlice[s.sliceName];
+    let scalar = commandScalarKeys(s);
+    consumedKeys(s).forEach(k => {
+      if (ownedPartitionKeys.has(k) && Primitive_object.notequal(k, own) && scalar.includes(k)) {
+        crossKeys.add(k);
+        return;
+      }
+    });
+  });
+  let crossPartitionTagKeys = Array.from(crossKeys.values()).toSorted(Primitive_string.compare);
+  let readKeysByEventType = {};
+  slices.forEach(s => {
+    s.consumed.forEach(e => {
+      let prev = Stdlib_Option.getOr(readKeysByEventType[e.eventType], []);
+      readKeysByEventType[e.eventType] = prev.concat(e.idFields.map(tagKeyOf));
+    });
+  });
+  let tagKeysByEventType = {};
+  slices.forEach(s => {
+    let own = partitionBySlice[s.sliceName];
+    s.produced.forEach(e => {
+      let readKeys = Stdlib_Option.getOr(readKeysByEventType[e.eventType], []);
+      let indexed = e.idFields.map(tagKeyOf).filter(k => {
+        if (Primitive_object.equal(k, own)) {
+          return true;
+        } else {
+          return readKeys.includes(k);
+        }
+      });
+      tagKeysByEventType[e.eventType] = dedupSorted(indexed);
+    });
+  });
+  return {
+    partitionBySlice: partitionBySlice,
+    ownerByKey: ownerByKey,
+    crossPartitionTagKeys: crossPartitionTagKeys,
+    tagKeysByEventType: tagKeysByEventType,
+    ambiguities: ambiguities
+  };
+}
+
+export {
+  tagKeyOf,
+  dedupSorted,
+  keysOfEvent,
+  producedKeys,
+  consumedKeys,
+  commandScalarKeys,
+  foreignConsumedKeys,
+  crossPartitionForSlice,
+  infer,
+}
+/* No side effect */

package/src/components/DcbTag.res

@@ -926,6 +926,56 @@ let extractCrossPartitionTagKeys = (schema: S.t<'event>): array<string> => {
   Array.fromIterator(seen->Set.values)->Array.toSorted((a, b) => String.compare(a, b))
 }
 
+// --- Schema -> DcbScopeInference shapes (the runtime adapter) ---
+
+/**
+Collects the `*Id` / `*Ids`-shaped fields of one object-variant's properties as
+`DcbScopeInference.idField`s — by **name**, independent of any DCB tag flag. This
+is the un-annotated structural view the scope inference consumes.
+*/
+let idFieldsOfProperties = (properties: dict<S.t<unknown>>): array<DcbScopeInference.idField> =>
+  properties
+  ->Dict.toArray
+  ->Array.filterMap(((name, fieldSchema)) =>
+    if name->String.endsWith("Ids") || name->String.endsWith("Id") {
+      let isList = switch fieldSchema {
+      | Array(_) => true
+      | _ => false
+      }
+      Some({DcbScopeInference.name, isList})
+    } else {
+      None
+    }
+  )
+
+/**
+Extracts the `DcbScopeInference.eventShape`s (variant name + `*Id` fields) from a
+variant schema. Payload-less arms are kept (no id fields); non-variant schemas
+return a single shape.
+*/
+let eventShapesOfSchema = (schema: S.t<'a>): array<DcbScopeInference.eventShape> => {
+  let ofVariant = (variantSchema: S.t<unknown>): option<DcbScopeInference.eventShape> =>
+    switch variantSchema {
+    | Object({items, properties}) =>
+      items
+      ->Array.find(item => item.location == "TAG")
+      ->Option.flatMap(item =>
+        switch item.schema {
+        | String({const}) => Some(const)
+        | _ => None
+        }
+      )
+      ->Option.map(eventType => {DcbScopeInference.eventType, idFields: idFieldsOfProperties(properties)})
+    | String({const}) => Some({DcbScopeInference.eventType: const, idFields: []})
+    | _ => None
+    }
+  switch schema->toUnknownSchema {
+  | Union({anyOf}) => anyOf->Array.filterMap(ofVariant)
+  | Object(_) as obj => ofVariant(obj)->Option.mapOr([], s => [s])
+  | _ => []
+  }
+}
+
 // --- Partition tag derivation ---
 
 /**
@@ -968,6 +1018,33 @@ let extractPartitionTagFields = (schema: S.t<'event>): array<string> => {
   }
 }
 
+/**
+Builds the `DcbScopeInference.sliceShape` for one slice from its sury schemas.
+The `command` fields are flattened across command variants; `consumed` / `produced`
+keep their per-arm structure. Schema-coupling lives here so the inference core
+stays schema-agnostic.
+*/
+let sliceShapeFromSchemas = (
+  ~name: string,
+  ~commandSchema: S.t<'c>,
+  ~consumedEventSchema: S.t<'ce>,
+  ~eventSchema: S.t<'e>,
+): DcbScopeInference.sliceShape => {
+  // An explicit @partitionTag on the produced event is the escape hatch for
+  // slices whose own events carry two owned keys (e.g. RecordProductDemand).
+  let partitionHint = switch extractPartitionTagFields(eventSchema) {
+  | [single] => Some(single)
+  | _ => None
+  }
+  {
+    sliceName: name,
+    command: eventShapesOfSchema(commandSchema)->Array.flatMap(e => e.idFields),
+    consumed: eventShapesOfSchema(consumedEventSchema),
+    produced: eventShapesOfSchema(eventSchema),
+    partitionHint,
+  }
+}
+
 /**
 Checks whether any single variant in a schema has multiple tagged fields.
 If so, a partition tag annotation is needed to disambiguate.

package/src/components/DcbTag.res.mjs

@@ -578,6 +578,63 @@ function extractCrossPartitionTagKeys(schema) {
   return Array.from(seen.values()).toSorted(Primitive_string.compare);
 }
 
+function idFieldsOfProperties(properties) {
+  return Stdlib_Array.filterMap(Object.entries(properties), param => {
+    let name = param[0];
+    if (!(name.endsWith("Ids") || name.endsWith("Id"))) {
+      return;
+    }
+    let isList;
+    isList = param[1].type === "array";
+    return {
+      name: name,
+      isList: isList
+    };
+  });
+}
+
+function eventShapesOfSchema(schema) {
+  let ofVariant = variantSchema => {
+    switch (variantSchema.type) {
+      case "string" :
+        let $$const = variantSchema.const;
+        if ($$const !== undefined) {
+          return {
+            eventType: $$const,
+            idFields: []
+          };
+        } else {
+          return;
+        }
+      case "object" :
+        let properties = variantSchema.properties;
+        return Stdlib_Option.map(Stdlib_Option.flatMap(variantSchema.items.find(item => item.location === "TAG"), item => {
+          let match = item.schema;
+          if (match.type !== "string") {
+            return;
+          }
+          let $$const = match.const;
+          if ($$const !== undefined) {
+            return $$const;
+          }
+        }), eventType => ({
+          eventType: eventType,
+          idFields: idFieldsOfProperties(properties)
+        }));
+      default:
+        return;
+    }
+  };
+  switch (schema.type) {
+    case "object" :
+      return Stdlib_Option.mapOr(ofVariant(schema), [], s => [s]);
+    case "union" :
+      return Stdlib_Array.filterMap(schema.anyOf, ofVariant);
+    default:
+      return [];
+  }
+}
+
 function extractPartitionTagFields(schema) {
   switch (schema.type) {
     case "object" :
@@ -608,6 +665,18 @@ function extractPartitionTagFields(schema) {
   }
 }
 
+function sliceShapeFromSchemas(name, commandSchema, consumedEventSchema, eventSchema) {
+  let match = extractPartitionTagFields(eventSchema);
+  let partitionHint = match.length !== 1 ? undefined : match[0];
+  return {
+    sliceName: name,
+    command: eventShapesOfSchema(commandSchema).flatMap(e => e.idFields),
+    consumed: eventShapesOfSchema(consumedEventSchema),
+    produced: eventShapesOfSchema(eventSchema),
+    partitionHint: partitionHint
+  };
+}
+
 function hasMultiTagVariant(schema) {
   switch (schema.type) {
     case "object" :
@@ -857,7 +926,10 @@ export {
   extractTaggedFields,
   crossPartitionKeysOfProperties,
   extractCrossPartitionTagKeys,
+  idFieldsOfProperties,
+  eventShapesOfSchema,
   extractPartitionTagFields,
+  sliceShapeFromSchemas,
   hasMultiTagVariant,
   findMultiTagVariantNames,
   extractCompositePartitionFieldsFromProperties,

package/src/components/DcbValidation.res

@@ -56,7 +56,10 @@ let extractAllVariants = (schema: S.t<unknown>): array<variantInfo> =>
 // Check if a variant has no payload fields (only TAG)
 let isPayloadLess = (info: variantInfo): bool => info.fields->Dict.toArray->Array.length == 0
 
-// Compare two sury schema types for structural compatibility
+// Compare two sury schema types for structural compatibility. Objects and
+// unions recurse: previously any (Object, Object) / (Union, Union) pair was
+// declared compatible, so nested payload drift (a renamed/retyped nested field,
+// a changed variant) passed validation undetected.
 let rec schemasAreCompatible = (a: S.t<unknown>, b: S.t<unknown>): bool =>
   switch (a, b) {
   | (String(_), String(_)) => true
@@ -65,10 +68,35 @@ let rec schemasAreCompatible = (a: S.t<unknown>, b: S.t<unknown>): bool =>
   | (BigInt(_), BigInt(_)) => true
   | (Array({additionalItems: Schema(aItem)}), Array({additionalItems: Schema(bItem)})) =>
     schemasAreCompatible(aItem, bItem)
-  | (Union(_), Union(_)) => true
-  | (Object(_), Object(_)) => true
+  | (Object({properties: aProps}), Object({properties: bProps})) => propsCompatible(aProps, bProps)
+  | (Union(_), Union(_)) =>
+    // Same set of variant tags, and each shared variant's payload compatible.
+    let av = extractAllVariants(a)
+    let bv = extractAllVariants(b)
+    let at = av->Array.map(v => v.tagName)->Array.toSorted(String.compare)
+    let bt = bv->Array.map(v => v.tagName)->Array.toSorted(String.compare)
+    at == bt &&
+    at->Array.every(tag =>
+      switch (av->Array.find(v => v.tagName == tag), bv->Array.find(v => v.tagName == tag)) {
+      | (Some(x), Some(y)) => propsCompatible(x.fields, y.fields)
+      | _ => false
+      }
+    )
   | _ => false
   }
+// Two property maps are compatible when they carry the same field names and each
+// field's schema is compatible.
+and propsCompatible = (aProps: dict<S.t<unknown>>, bProps: dict<S.t<unknown>>): bool => {
+  let aKeys = aProps->Dict.keysToArray->Array.toSorted(String.compare)
+  let bKeys = bProps->Dict.keysToArray->Array.toSorted(String.compare)
+  aKeys == bKeys &&
+  aKeys->Array.every(k =>
+    switch (aProps->Dict.get(k), bProps->Dict.get(k)) {
+    | (Some(av), Some(bv)) => schemasAreCompatible(av, bv)
+    | _ => false
+    }
+  )
+}
 
 // Get a human-readable type name for a schema
 let schemaTypeName = (schema: S.t<unknown>): string =>
@@ -360,3 +388,49 @@ let validateCrossPartitionScope = (
   )
   warnings
 }
+
+/** Two-bucket 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>,
+}
+
+/**
+Validates explicit `@crossPartition` annotations against the *inferred* scope,
+now that inference drives the decision-query wiring. Two cases per annotated key:
+
+- **Contradiction** — the key is marked `@crossPartition` on a slice that inference
+  resolves as that slice's *own partition*. A slice's own identity is never a
+  cross-partition read; the annotation is wrong and (were it to drive the wiring)
+  would fan the partition into a spurious secondary read. Surface loudly.
+- **Redundant** — the key is marked `@crossPartition` and inference *also* derives
+  it as cross-partition from the slice graph. Harmless, but the annotation can be
+  dropped — that is the whole point of inference.
+
+@param annotations `(sliceName, @crossPartition keys on the slice's produced event)`.
+*/
+let validateScopeVsInference = (
+  ~annotations: array<(string, array<string>)>,
+  ~inferred: DcbScopeInference.derived,
+): scopeInferenceIssues => {
+  let contradictions: array<validationError> = []
+  let redundancies: array<validationError> = []
+  annotations->Array.forEach(((name, cpKeys)) =>
+    cpKeys->Array.forEach(k =>
+      if inferred.partitionBySlice->Dict.get(name) == Some(k) {
+        let _ = contradictions->Array.push({
+          sliceName: name,
+          message: `tag '${k}' is marked @crossPartition but inference resolves it as this slice's own partition key — a slice's own identity is never a cross-partition read. Remove the annotation.`,
+        })
+      } else if inferred.crossPartitionTagKeys->Array.includes(k) {
+        let _ = redundancies->Array.push({
+          sliceName: name,
+          message: `tag '${k}' is marked @crossPartition but the framework already infers it as a cross-partition read from the slice graph — the annotation is redundant and can be removed.`,
+        })
+      }
+    )
+  )
+  {contradictions, redundancies}
+}

package/src/components/DcbValidation.res.mjs

@@ -2,6 +2,7 @@
 
 import * as Stdlib_Array from "@rescript/runtime/lib/es6/Stdlib_Array.js";
 import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
+import * as Primitive_object from "@rescript/runtime/lib/es6/Primitive_object.js";
 import * as Primitive_string from "@rescript/runtime/lib/es6/Primitive_string.js";
 import * as DcbTag$Reventless from "./DcbTag.res.mjs";
 
@@ -94,15 +95,56 @@ function schemasAreCompatible(_a, _b) {
         _a = aItem;
         continue;
       case "object" :
-        return b.type === "object";
+        if (b.type === "object") {
+          return propsCompatible(a.properties, b.properties);
+        } else {
+          return false;
+        }
       case "union" :
-        return b.type === "union";
+        if (b.type !== "union") {
+          return false;
+        }
+        let av = extractAllVariants(a);
+        let bv = extractAllVariants(b);
+        let at = av.map(v => v.tagName).toSorted(Primitive_string.compare);
+        let bt = bv.map(v => v.tagName).toSorted(Primitive_string.compare);
+        if (Primitive_object.equal(at, bt)) {
+          return at.every(tag => {
+            let match = av.find(v => v.tagName === tag);
+            let match$1 = bv.find(v => v.tagName === tag);
+            if (match !== undefined && match$1 !== undefined) {
+              return propsCompatible(match.fields, match$1.fields);
+            } else {
+              return false;
+            }
+          });
+        } else {
+          return false;
+        }
       default:
         return false;
     }
   };
 }
 
+function propsCompatible(aProps, bProps) {
+  let aKeys = Object.keys(aProps).toSorted(Primitive_string.compare);
+  let bKeys = Object.keys(bProps).toSorted(Primitive_string.compare);
+  if (Primitive_object.equal(aKeys, bKeys)) {
+    return aKeys.every(k => {
+      let match = aProps[k];
+      let match$1 = bProps[k];
+      if (match !== undefined && match$1 !== undefined) {
+        return schemasAreCompatible(match, match$1);
+      } else {
+        return false;
+      }
+    });
+  } else {
+    return false;
+  }
+}
+
 function schemaTypeName(schema) {
   switch (schema.type) {
     case "never" :
@@ -346,15 +388,46 @@ function validateCrossPartitionScope(producers) {
   return warnings;
 }
 
+function validateScopeVsInference(annotations, inferred) {
+  let contradictions = [];
+  let redundancies = [];
+  annotations.forEach(param => {
+    let name = param[0];
+    param[1].forEach(k => {
+      if (Primitive_object.equal(inferred.partitionBySlice[name], k)) {
+        contradictions.push({
+          sliceName: name,
+          message: `tag '` + k + `' is marked @crossPartition but inference resolves it as this slice's own partition key — a slice's own identity is never a cross-partition read. Remove the annotation.`
+        });
+        return;
+      } else if (inferred.crossPartitionTagKeys.includes(k)) {
+        redundancies.push({
+          sliceName: name,
+          message: `tag '` + k + `' is marked @crossPartition but the framework already infers it as a cross-partition read from the slice graph — the annotation is redundant and can be removed.`
+        });
+        return;
+      } else {
+        return;
+      }
+    });
+  });
+  return {
+    contradictions: contradictions,
+    redundancies: redundancies
+  };
+}
+
 export {
   extractVariantInfo,
   extractAllVariants,
   isPayloadLess,
   schemasAreCompatible,
+  propsCompatible,
   schemaTypeName,
   dedupeKeys,
   validateCompositeReads,
   validateProducedAndConsumed,
   validateCrossPartitionScope,
+  validateScopeVsInference,
 }
 /* DcbTag-Reventless Not a pure module */

package/src/components/InboundTranslationSlice.res

@@ -51,6 +51,12 @@ module type Spec = {
   /** Name of the aggregate or StateChangeSlice that receives the produced command. */
   let targetName: string
 
+  /** Optional display name of the foreign system this anti-corruption slice receives
+      from (e.g. `"SupplierFeed"`). Drives the **external box** drawn outside the plugin
+      in the Event Graph / Context Map (see docs/plans/translation-external-boxes.md).
+      Auto-injected by `@@reventless.spec` defaulting to `None` — set it to name the box. */
+  let externalSystem: option<string>
+
   /** Authorization rule evaluated at the GraphQL resolver entry before any
       external input is translated. Auto-injected by `@@reventless.spec` and
       on structurally-detected inline spec modules — defaults to

package/src/components/OutboundTranslationSlice.res

@@ -75,6 +75,12 @@ module type Spec = {
 
   /** Name of the aggregate or StateChangeSlice that receives the inbound command, or None for fire-and-forget. */
   let targetName: option<string>
+
+  /** Optional display name of the foreign system this anti-corruption slice publishes
+      to (e.g. `"EmailService"`). Drives the **external box** drawn outside the plugin
+      in the Event Graph / Context Map (see docs/plans/translation-external-boxes.md).
+      Auto-injected by `@@reventless.spec` defaulting to `None` — set it to name the box. */
+  let externalSystem: option<string>
 }
 
 /**

package/src/components/Plugin.res

@@ -243,6 +243,8 @@ type outboundTranslationSliceDef = {
   consumedEventTypes: array<string>,
   inboundCommandTypes: array<string>,
   targetName: @s.matches(stringOptionSchema) option<string>,
+  // Foreign system this slice publishes to — drives the external box (Event Graph).
+  externalSystem: @s.matches(stringOptionSchema) option<string>,
 }
 
 @schema
@@ -250,6 +252,8 @@ type inboundTranslationSliceDef = {
   name: string,
   commandTypes: array<string>,
   targetName: string,
+  // Foreign system this slice receives from — drives the external box (Event Graph).
+  externalSystem: @s.matches(stringOptionSchema) option<string>,
 }
 
 @schema

package/src/components/Plugin.res.mjs

@@ -132,13 +132,15 @@ let outboundTranslationSliceDefSchema = S.schema(s => ({
   name: s.m(S.string),
   consumedEventTypes: s.m(S.array(S.string)),
   inboundCommandTypes: s.m(S.array(S.string)),
-  targetName: s.m(stringOptionSchema)
+  targetName: s.m(stringOptionSchema),
+  externalSystem: s.m(stringOptionSchema)
 }));
 
 let inboundTranslationSliceDefSchema = S.schema(s => ({
   name: s.m(S.string),
   commandTypes: s.m(S.array(S.string)),
-  targetName: s.m(S.string)
+  targetName: s.m(S.string),
+  externalSystem: s.m(stringOptionSchema)
 }));
 
 let extensionDefSchema = S.schema(s => ({

package/src/generator/Pairing.res

@@ -316,12 +316,16 @@ let resolve = (discovered: array<Discovery.discoveredFile>, ~srcDir: string): re
     switch epGroup {
     | None => flatEpMappings->Array.push(stem)
     | Some(g) =>
-      let arr = Dict.get(epByGroup, g)->Option.getOr({
-        let a: array<string> = []
-        Dict.set(epByGroup, g, a)
-        a
-      })
-      arr->Array.push(stem)
+      // `Option.getOr`'s default is evaluated eagerly, so the previous shape
+      // re-created and re-set a fresh empty array every iteration — overwriting
+      // the group's real entry and pushing onto a now-detached array. A group
+      // with ≥2 mappings ended up empty, emitting a Plugin.res that referenced a
+      // never-generated module (`Array.getUnsafe(0)` on `[]`). Use a switch so
+      // the create branch runs only when the group is genuinely absent.
+      switch Dict.get(epByGroup, g) {
+      | Some(arr) => arr->Array.push(stem)
+      | None => Dict.set(epByGroup, g, [stem])
+      }
     }
   })
 

package/src/generator/Pairing.res.mjs

@@ -3,7 +3,6 @@
 import * as Nodefs from "node:fs";
 import * as Nodepath from "node:path";
 import * as Stdlib_Array from "@rescript/runtime/lib/es6/Stdlib_Array.js";
-import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
 import * as Generator_Node$Reventless from "./Generator_Node.res.mjs";
 
 let implSuffixForStateChange = "_Behavior";
@@ -282,9 +281,12 @@ function resolve(discovered, srcDir) {
     let epGroup = param.epGroup;
     let stem = param.stem;
     if (epGroup !== undefined) {
-      let a = [];
-      let arr = Stdlib_Option.getOr(epByGroup[epGroup], (epByGroup[epGroup] = a, a));
-      arr.push(stem);
+      let arr = epByGroup[epGroup];
+      if (arr !== undefined) {
+        arr.push(stem);
+      } else {
+        epByGroup[epGroup] = [stem];
+      }
       return;
     }
     flatEpMappings.push(stem);

package/src/generator/PluginGenerator.res

@@ -2,6 +2,8 @@
 // Usage: generate-plugin <srcDir>
 //        generate-plugin --aws <Namespace> <srcDir>
 
+@val external processExit: int => unit = "process.exit"
+
 let () = {
   let argv2 = Generator_Node.argv->Array.get(2)->Option.getOr("")
   let argv3 = Generator_Node.argv->Array.get(3)->Option.getOr("")
@@ -23,6 +25,9 @@ let () = {
       Console.error("Usage: generate-plugin <srcDir>")
       Console.error("       generate-plugin --aws <Namespace> <srcDir>")
     }
+    // Exit non-zero on a usage error so `prebuild` (and CI) actually fail
+    // instead of continuing green with no Plugin.res generated.
+    processExit(1)
   } else {
     // Resolve to absolute path (handles relative paths and trailing slashes)
     let srcDir = Generator_Node.resolve([srcDirArg])

package/src/generator/PluginGenerator.res.mjs

@@ -39,6 +39,7 @@ if (srcDirArg === "") {
     console.error("Usage: generate-plugin <srcDir>");
     console.error("       generate-plugin --aws <Namespace> <srcDir>");
   }
+  process.exit(1);
 } else {
   let srcDir = Nodepath.resolve(srcDirArg);
   let init = Config$Reventless.read(srcDir);