@reventlessdev/reventless-spec 3.0.0-alpha.100

package/src/components/DcbDecode.res

@@ -0,0 +1,118 @@
+// Decodes raw stored events against a consumed event schema.
+// Supports the full spectrum of consumed events:
+//   - Payload-less variants (match by TAG only, bypass sury)
+//   - Partial projections (sury parse with field subset)
+//   - Full shape (sury parse as-is)
+
+// Build a lookup of TAG name -> variant kind (payloadLess or withFields)
+// from a consumed event schema. Cached per schema for performance.
+
+type variantKind =
+  | PayloadLess
+  | WithFields
+
+let buildVariantLookup = (schema: S.t<unknown>): dict<variantKind> => {
+  let lookup = Dict.make()
+  switch schema {
+  | Union({anyOf}) =>
+    anyOf->Array.forEach(variantSchema =>
+      switch variantSchema {
+      | Object({items, properties}) =>
+        switch DcbTag.variantTagName(items) {
+        | Some(name) =>
+          let kind = if properties->Dict.keysToArray->Array.length == 0 {
+            PayloadLess
+          } else {
+            WithFields
+          }
+          lookup->Dict.set(name, kind)
+        | None => ()
+        }
+      | String({const: ?Some(name)}) =>
+        // sury represents payload-less variants in some cases as bare String({const})
+        lookup->Dict.set(name, PayloadLess)
+      | _ => ()
+      }
+    )
+  | Object({items}) =>
+    // Single-variant schema with fields
+    switch DcbTag.variantTagName(items) {
+    | Some(name) => lookup->Dict.set(name, WithFields)
+    | None => ()
+    }
+  | String({const: ?Some(name)}) =>
+    // Single payload-less variant — sury compiles `type t = Foo` to String({const: "Foo"})
+    lookup->Dict.set(name, PayloadLess)
+  | _ => ()
+  }
+  lookup
+}
+
+type decoder<'event> = {
+  lookup: dict<variantKind>,
+  schema: S.t<'event>,
+  constructors: dict<'event>,
+}
+
+external unsafeCast: 'a => 'b = "%identity"
+
+// Build a map of TAG name -> constructed payload-less variant value
+// by encoding each payload-less variant through sury and storing the result.
+// This is done once per schema, not per event.
+let buildPayloadLessConstructors = (schema: S.t<'event>, lookup: dict<variantKind>): dict<'event> => {
+  let constructors = Dict.make()
+  // For payload-less variants, we need to figure out what ReScript value
+  // corresponds to each TAG name. sury's schema for a union with payload-less
+  // variants encodes them as bare strings. So `| ItemCreated` serializes to
+  // JSON string "ItemCreated". We can use S.parseJsonOrThrow with the string.
+  lookup->Dict.toArray->Array.forEach(((tagName, kind)) =>
+    switch kind {
+    | PayloadLess =>
+      try {
+        let value = JSON.String(tagName)->S.parseJsonOrThrow(schema)
+        constructors->Dict.set(tagName, value)
+      } catch {
+      | _ => ()
+      }
+    | WithFields => ()
+    }
+  )
+  constructors
+}
+
+type makeDecoderResult<'event> = {
+  decode: (~eventType: string, ~data: dict<JSON.t>) => option<'event>,
+  eventTypes: array<string>,
+}
+
+let makeDecoder = (schema: S.t<'event>): makeDecoderResult<'event> => {
+  let unknownSchema: S.t<unknown> = unsafeCast(schema)
+  let lookup = buildVariantLookup(unknownSchema)
+  let constructors = buildPayloadLessConstructors(schema, lookup)
+  let eventTypes = lookup->Dict.keysToArray
+
+  let decode = (~eventType: string, ~data: dict<JSON.t>): option<'event> =>
+    switch lookup->Dict.get(eventType) {
+    | None => None
+    | Some(PayloadLess) => constructors->Dict.get(eventType)
+    | Some(WithFields) =>
+      // Reconstruct the JSON with TAG for sury parsing
+      let jsonDict = data->Dict.copy
+      jsonDict->Dict.set("TAG", JSON.String(eventType))
+      try {
+        Some(JSON.Object(jsonDict)->S.parseJsonOrThrow(schema))
+      } catch {
+      | _ =>
+        // 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
+      }
+    }
+
+  {decode, eventTypes}
+}

package/src/components/DcbDecode.res.mjs

@@ -0,0 +1,100 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as S from "sury/src/S.res.mjs";
+import * as Primitive_option from "@rescript/runtime/lib/es6/Primitive_option.js";
+import * as DcbTag$Reventless from "./DcbTag.res.mjs";
+
+function buildVariantLookup(schema) {
+  let lookup = {};
+  switch (schema.type) {
+    case "string" :
+      let name = schema.const;
+      if (name !== undefined) {
+        lookup[name] = "PayloadLess";
+      }
+      break;
+    case "object" :
+      let name$1 = DcbTag$Reventless.variantTagName(schema.items);
+      if (name$1 !== undefined) {
+        lookup[name$1] = "WithFields";
+      }
+      break;
+    case "union" :
+      schema.anyOf.forEach(variantSchema => {
+        switch (variantSchema.type) {
+          case "string" :
+            let name = variantSchema.const;
+            if (name !== undefined) {
+              lookup[name] = "PayloadLess";
+              return;
+            } else {
+              return;
+            }
+          case "object" :
+            let name$1 = DcbTag$Reventless.variantTagName(variantSchema.items);
+            if (name$1 === undefined) {
+              return;
+            }
+            let kind = Object.keys(variantSchema.properties).length === 0 ? "PayloadLess" : "WithFields";
+            lookup[name$1] = kind;
+            return;
+          default:
+            return;
+        }
+      });
+      break;
+  }
+  return lookup;
+}
+
+function buildPayloadLessConstructors(schema, lookup) {
+  let constructors = {};
+  Object.entries(lookup).forEach(param => {
+    let tagName = param[0];
+    if (param[1] !== "PayloadLess") {
+      return;
+    }
+    try {
+      let value = S.parseJsonOrThrow(tagName, schema);
+      constructors[tagName] = value;
+      return;
+    } catch (exn) {
+      return;
+    }
+  });
+  return constructors;
+}
+
+function makeDecoder(schema) {
+  let lookup = buildVariantLookup(schema);
+  let constructors = buildPayloadLessConstructors(schema, lookup);
+  let eventTypes = Object.keys(lookup);
+  let decode = (eventType, data) => {
+    let match = lookup[eventType];
+    if (match === undefined) {
+      return;
+    }
+    if (match === "PayloadLess") {
+      return constructors[eventType];
+    }
+    let jsonDict = Object.assign({}, data);
+    jsonDict["TAG"] = eventType;
+    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;
+    }
+  };
+  return {
+    decode: decode,
+    eventTypes: eventTypes
+  };
+}
+
+export {
+  buildVariantLookup,
+  buildPayloadLessConstructors,
+  makeDecoder,
+}
+/* S Not a pure module */

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 */