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

package/CHANGELOG.md

@@ -3,12 +3,24 @@
 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.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.62",
   "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/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

@@ -360,3 +360,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";
 
@@ -346,6 +347,35 @@ 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,
@@ -356,5 +386,6 @@ export {
   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 => ({