@reventlessdev/reventless-spec 3.0.0-alpha.100

package/src/components/AutomationSlice.res

@@ -0,0 +1,279 @@
+/**
+Module types for a DCB automation slice (TODO List Pattern).
+
+An `AutomationSlice` listens to the shared `DcbEventLog` event topic, accumulates
+pending work items (TODO list), and processes them exactly once by issuing commands.
+Completion events mark TODO items as done, closing the automation loop.
+
+```
+Event(s) → TODO List (read model) → Processor → Command → Event(s)
+```
+
+Plan 02 splits the merged spec into two module types:
+
+- `Spec` — types, identity, schemas, configuration constants. Per D2,
+  `todoItem` lives here (the persisted TODO state has a schema queried for
+  sweeping pending items — externally-observable, like ReadModel state).
+- `Automation` — the three pure functions `collect`, `resolve`, `process`.
+
+@example
+```rescript
+// ShipOrder.res
+let name = "ShipOrder"
+
+@schema type todoItem = {orderId: string, shippingAddress: string}
+@schema type command = CreateShipment({orderId: @s.matches(DcbTag.string) string, address: string})
+
+let collect = event => switch event {
+  | OrderPlaced({orderId, shippingAddress}) =>
+    [(orderId, {orderId, shippingAddress})]
+  | _ => []
+}
+
+let resolve = event => switch event {
+  | ShipmentCreated({orderId}) => Some(orderId)
+  | _ => None
+}
+
+let process = (id, item) =>
+  Some((id, CreateShipment({orderId: item.orderId, address: item.shippingAddress})))
+
+let maxRetries = 3
+let heartbeatInterval = 60
+```
+*/
+
+/**
+The lean Spec for an AutomationSlice — types, identity, schemas, sweep config.
+
+Plan 04 dropped `consumedEvent` from the Spec — the framework now derives the
+consumed-event set from each per-source Mapping's `sourceEventSchema`, so a
+manually-declared union is no longer necessary. Single-source slices have one
+`Mapping` whose `sourceEventSchema` IS the consumed-event schema; multi-source
+slices have several Mappings and the framework walks all of them.
+*/
+module type Spec = {
+  /** Logical name of this automation slice (used as a component prefix). */
+  let name: string
+  let moduleUrl: string
+
+  /** The TODO item state — what data is accumulated for each pending work item. Must carry `@schema`. */
+  @schema
+  type todoItem
+
+  /** The command type produced by the processor. Must carry `@schema`. */
+  @schema
+  type command
+
+  /** Maximum number of retries for a failed processing attempt. */
+  let maxRetries: int
+
+  /** Heartbeat interval in seconds for sweeping pending/failed items. */
+  let heartbeatInterval: int
+
+  /** Name of the aggregate or StateChangeSlice that receives the produced command. */
+  let targetName: string
+}
+
+// ── Plan 04: Mixed-source mappings ───────────────────────────────────────────
+//
+// An AutomationSlice can declare per-source mappings that consume Aggregate
+// events alongside the slice's own DcbEventLog events. Each mapping carries its
+// own `collect`/`resolve` (over the source's `event` type) plus a `toTags`
+// validation step run before each command publish. `process` remains shared in
+// the slice's `Automation` module since it operates on `todoItem` regardless of
+// the originating source.
+
+/**
+Ambient deployment context plumbed to every mapping function.
+
+`Plugin_Builder` constructs this from its existing `~environment`, `~name` and
+related parameters. `collect` and `resolve` use it to complete partial event
+payloads (e.g. when a DCB tag field is supplied by deployment metadata rather
+than the source event); `toTags` uses it to validate that all tag fields on the
+target command will be populated.
+
+The record is intentionally narrow — extending it is a deliberate framework
+change, not an open-dict escape hatch. Runtime registry lookups are out of
+scope (see Plan 04 / decision 3).
+*/
+type context = {
+  environment: string,
+  platformName: string,
+  pluginName: string,
+  sliceName: string,
+}
+
+/**
+A compiled per-source-to-AutomationSlice mapping.
+
+Created by `AutomationSlice.Mapping.Make(Source, Target, Impl)`. The mapping
+binds `sourceEvent` (decode target) plus `collect`/`resolve` to the slice's
+`todoItem` type. `process` remains in the slice's `Automation` module — it is
+source-agnostic.
+
+Validation belongs upstream of the mapping: `collect` should return `[]` for
+events that shouldn't enter the TODO list, and the command schema's
+`@compositePartitionTag` / `@s.matches(DcbTag.string)` annotations enforce
+DCB-tag invariants at encode time (failures mark the item Failed → retry).
+*/
+module type Mapping = {
+  module SourceId: Id.T
+  @schema
+  type sourceEvent
+  type todoItem
+  type command
+  let sourceEventSchema: S.t<sourceEvent>
+  let sourceName: string
+  let collect: (sourceEvent, context) => array<(string, todoItem)>
+  let resolve: sourceEvent => option<string>
+}
+
+/**
+The Automation — the source-agnostic processing function.
+
+Plan 04 moved `collect` and `resolve` to per-source `Mapping` modules (where
+they switch over the source's own `event` type). `process` stays here because
+it operates on `todoItem`, which is uniform across sources.
+
+The "close PPX gaps" plan merged the previous `Mappings` shape into this type:
+the same module that exposes `process` also exposes the per-source `mappings`
+array and the inner `module type Mapping`. This collapses the Plan 04 3-arg
+`AutomationSlice.Make(Spec, Automation, Mappings)` into a 2-arg
+`Make(Spec, Automation)` and lets the merged `_Automation.res` file (process +
+per-source `Mapping.Make` + `let mappings`) live as a single source file.
+*/
+module type Automation = {
+  module Spec: Spec
+
+  /**
+  Process: given a pending TODO item, produce a command.
+  The processor calls this for each pending item. Returns the target ID and command.
+  May return `None` to skip processing (e.g., wait for more data).
+  */
+  let process: (string, Spec.todoItem) => option<(string, Spec.command)>
+
+  /** File URL of this Automation module (`import.meta.url`). */
+  let moduleUrl: string
+
+  /**
+  The per-source `Mapping` type — substituted onto the slice's `Spec`. The
+  PPX-injected `module M = Reventless.AutomationSlice.Mappings.Make(Spec)`
+  + `module type Mapping = M.Mapping` produces exactly this shape; legacy
+  3-file files re-export it via `module type Mapping = <Stem>_Mappings.Mapping`.
+  */
+  module type Mapping = Mapping
+    with type todoItem = Spec.todoItem
+    and type command = Spec.command
+
+  /**
+  The per-source mappings registered with this slice. Each entry is a first-class
+  module satisfying `Mapping`. The framework walks these to discover source
+  topics and dispatch decoded events to the matching `collect`/`resolve`.
+  */
+  let mappings: array<module(Mapping)>
+}
+
+/**
+The implementation passed to `AutomationSlice.Mapping.Make`. Caller-supplied
+`collect`/`resolve` are bound to source/target types via destructive
+substitution in the functor.
+*/
+module type MappingImpl = {
+  type sourceEvent
+  type todoItem
+  type command
+  let collect: (sourceEvent, context) => array<(string, todoItem)>
+  let resolve: sourceEvent => option<string>
+}
+
+/**
+A collection of `Mapping` modules for a single AutomationSlice target.
+
+Pass a `Mappings` module to the AutomationSlice plugin builder to register all
+source-to-slice mappings. The shape mirrors `Projection.Mappings` for
+ReadModels.
+
+@example
+```rescript
+// AutoFulfillment_Mappings.res
+module M = Reventless.AutomationSlice.Mappings.Make(AutoFulfillmentSpec)
+module type Mapping = M.Mapping
+
+let mappings: array<module(Mapping)> = [
+  module(FromOrderShipped),
+  module(FromStockReserved),
+]
+```
+*/
+module type Mappings = {
+  module Target: Spec
+  module type Mapping = Mapping
+    with type todoItem = Target.todoItem
+    and type command = Target.command
+  let moduleUrl: string
+  let mappings: array<module(Mapping)>
+}
+
+/**
+Builds an `AutomationSlice.Mapping` from a `Source`, the slice's `Spec`, and a
+`MappingImpl`.
+
+@example
+```rescript
+// AutoFulfillment/FromOrderShipped.res
+module FromOrderShipped = Reventless.AutomationSlice.Mapping.Make(
+  OrderSpec,                    // Source: Aggregate spec module
+  AutoFulfillmentSpec,          // Target: this slice's spec
+  {
+    let collect = (event, _ctx) =>
+      switch event {
+      | OrderSpec.OrderShipped({orderId, productId}) =>
+        [(orderId ++ ":" ++ productId, {AutoFulfillmentSpec.orderId, productId})]
+      | _ => []
+      }
+
+    let resolve = event =>
+      switch event {
+      | OrderSpec.OrderRefunded({orderId, productId}) =>
+        Some(orderId ++ ":" ++ productId)
+      | _ => None
+      }
+  },
+)
+```
+*/
+module Mapping = {
+  module Make = (
+    Source: Projection.Source,
+    Target: Spec,
+    Impl: MappingImpl
+      with type sourceEvent := Source.event
+      and type todoItem := Target.todoItem
+      and type command := Target.command,
+  ): (
+    Mapping
+      with type sourceEvent = Source.event
+      and type todoItem = Target.todoItem
+      and type command = Target.command
+      and module SourceId = Source.Id
+  ) => {
+    module SourceId = Source.Id
+    @schema
+    type sourceEvent = Source.event
+    type todoItem = Target.todoItem
+    type command = Target.command
+    let sourceName = Source.name
+    let collect = Impl.collect
+    let resolve = Impl.resolve
+  }
+}
+
+module Mappings = {
+  module Make = (Target: Spec) => {
+    module type Mapping = Mapping
+      with type todoItem = Target.todoItem
+      and type command = Target.command
+  }
+}
+

package/src/components/AutomationSlice.res.mjs

@@ -0,0 +1,30 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+
+function Make(Source) {
+  return Target => (Impl => ({
+    SourceId: Source.Id,
+    sourceEventSchema: Source.eventSchema,
+    sourceName: Source.name,
+    collect: Impl.collect,
+    resolve: Impl.resolve
+  }));
+}
+
+let Mapping = {
+  Make: Make
+};
+
+function Make$1(Target) {
+  return {};
+}
+
+let Mappings = {
+  Make: Make$1
+};
+
+export {
+  Mapping,
+  Mappings,
+}
+/* No side effect */

package/src/components/CapabilityManifest.res

@@ -0,0 +1,74 @@
+/**
+The per-plugin capability manifest — `capabilities.json`, written beside the
+generated `Plugin.res` by the plugin package's build.
+
+Each entry states one capability the plugin's fields declare they need, keyed
+by the store's qualified `{plugin}.{store}` identity, with the declaring
+`(component, field)` sites as provenance. The keys are taken verbatim from
+`pluginStructure.requiredStores` — the manifest is a rendering of the
+structure, never a second scan of the sources, so the two cannot spell one
+fact differently.
+
+The platform generator unions these files across a deployment's plugins and
+emits the platform's capability list from them.
+*/
+
+@schema
+type kind = ObjectStore
+
+/** The declaration site: the component's spec name and the field carrying the
+    `@storageRef` annotation, plus the store exactly as that field spells it.
+
+    `annotation` is optional only to keep reading a manifest emitted before it
+    existed: a plugin built earlier still parses, and a reader that cannot say
+    what the source says omits the claim rather than inventing one. Every
+    manifest emitted now carries it. */
+@schema
+type provenance = {component: string, field: string, annotation?: string}
+
+@schema
+type entry = {
+  kind: kind,
+  key: string,
+  declaredBy: array<provenance>,
+}
+
+@schema
+type t = {capabilities: array<entry>}
+
+/**
+Build the manifest from a plugin's structure.
+
+Keys iterate `requiredStores` itself, so a manifest's key set is byte-identical
+to what the deployed plugin reports at runtime — the contract the deploy-time
+coverage assertion checks against. A structure with no declarations yields an
+empty `capabilities` list, not an absent file: "declares nothing" is a
+statement, and the generator reading the manifests must be able to tell it
+apart from "was never built".
+*/
+let fromStructure = (structure: Plugin.pluginStructure): t => {
+  let declarations = structure.requiredStoreDeclarations->Option.getOr([])
+  {
+    capabilities: structure.requiredStores
+    ->Option.getOr([])
+    ->Array.map(key => {
+      kind: ObjectStore,
+      key,
+      declaredBy: declarations->Array.filterMap(d =>
+        d.store == key
+          ? Some({component: d.component, field: d.field, annotation: ?d.annotation})
+          : None
+      ),
+    }),
+  }
+}
+
+/** Deterministic rendering: 2-space indent, trailing newline. Rebuilding with
+    no source change must produce a byte-identical file, so the committed
+    manifest never churns. */
+let render = (manifest: t): string =>
+  JSON.stringify(manifest->S.reverseConvertToJsonOrThrow(schema), ~space=2) ++ "\n"
+
+/** One call for the emit CLI: structure in, `capabilities.json` content out. */
+let renderForStructure = (structure: Plugin.pluginStructure): string =>
+  structure->fromStructure->render

package/src/components/CapabilityManifest.res.mjs

@@ -0,0 +1,61 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as S from "sury/src/S.res.mjs";
+import * as Stdlib_Array from "@rescript/runtime/lib/es6/Stdlib_Array.js";
+import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
+
+let kindSchema = S.literal("ObjectStore");
+
+let provenanceSchema = S.schema(s => ({
+  component: s.m(S.string),
+  field: s.m(S.string),
+  annotation: s.m(S.option(S.string))
+}));
+
+let entrySchema = S.schema(s => ({
+  kind: s.m(kindSchema),
+  key: s.m(S.string),
+  declaredBy: s.m(S.array(provenanceSchema))
+}));
+
+let schema = S.schema(s => ({
+  capabilities: s.m(S.array(entrySchema))
+}));
+
+function fromStructure(structure) {
+  let declarations = Stdlib_Option.getOr(structure.requiredStoreDeclarations, []);
+  return {
+    capabilities: Stdlib_Option.getOr(structure.requiredStores, []).map(key => ({
+      kind: "ObjectStore",
+      key: key,
+      declaredBy: Stdlib_Array.filterMap(declarations, d => {
+        if (d.store === key) {
+          return {
+            component: d.component,
+            field: d.field,
+            annotation: d.annotation
+          };
+        }
+      })
+    }))
+  };
+}
+
+function render(manifest) {
+  return JSON.stringify(S.reverseConvertToJsonOrThrow(manifest, schema), undefined, 2) + "\n";
+}
+
+function renderForStructure(structure) {
+  return render(fromStructure(structure));
+}
+
+export {
+  kindSchema,
+  provenanceSchema,
+  entrySchema,
+  schema,
+  fromStructure,
+  render,
+  renderForStructure,
+}
+/* kindSchema Not a pure module */

package/src/components/ComponentKind.res

@@ -0,0 +1,99 @@
+// Single source of truth for the Reventless component-kind vocabulary: the kinds
+// themselves, every accepted folder spelling (singular / plural / short form),
+// the canonical folder name, and the body-file suffixes. The plugin generator
+// (`generator/Discovery`) and the external tooling that classifies files by
+// folder (`reventless-gwt`'s `ComponentMeta`) both derive from this, so the two
+// can't drift — previously the generator accepted plural/short folder names that
+// the gwt discovery silently didn't recognise.
+
+type t =
+  | StateChangeSlice
+  | StateViewSlice
+  | StateViewSliceStream
+  | AutomationSlice
+  | InboundTranslationSlice
+  | OutboundTranslationSlice
+  | Aggregate
+  | ReadModel
+  | ReadModelStream
+  | Task
+  | ExtensionPoint
+  | Extension
+
+let all = [
+  StateChangeSlice,
+  StateViewSlice,
+  StateViewSliceStream,
+  AutomationSlice,
+  InboundTranslationSlice,
+  OutboundTranslationSlice,
+  Aggregate,
+  ReadModel,
+  ReadModelStream,
+  Task,
+  ExtensionPoint,
+  Extension,
+]
+
+// The canonical (singular) folder name for a kind — the spelling the naming
+// conventions and the graph `kind` field use.
+let folderName = (t: t): string =>
+  switch t {
+  | StateChangeSlice => "StateChangeSlice"
+  | StateViewSlice => "StateViewSlice"
+  | StateViewSliceStream => "StateViewSliceStream"
+  | AutomationSlice => "AutomationSlice"
+  | InboundTranslationSlice => "InboundTranslationSlice"
+  | OutboundTranslationSlice => "OutboundTranslationSlice"
+  | Aggregate => "Aggregate"
+  | ReadModel => "ReadModel"
+  | ReadModelStream => "ReadModelStream"
+  | Task => "Task"
+  | ExtensionPoint => "ExtensionPoint"
+  | Extension => "Extension"
+  }
+
+// Every folder spelling that denotes a kind → the kind. Tolerates the singular,
+// plural, and (for slices) short forms the generator has always accepted.
+let folderToKind = (folder: string): option<t> =>
+  switch folder {
+  | "StateChange" | "StateChanges" | "StateChangeSlice" | "StateChangeSlices" =>
+    Some(StateChangeSlice)
+  | "StateView" | "StateViews" | "StateViewSlice" | "StateViewSlices" => Some(StateViewSlice)
+  | "StateViewSliceStream" | "StateViewSliceStreams" => Some(StateViewSliceStream)
+  | "Automation" | "Automations" | "AutomationSlice" | "AutomationSlices" => Some(AutomationSlice)
+  | "InboundTranslation"
+  | "InboundTranslations"
+  | "InboundTranslationSlice"
+  | "InboundTranslationSlices" =>
+    Some(InboundTranslationSlice)
+  | "OutboundTranslation"
+  | "OutboundTranslations"
+  | "OutboundTranslationSlice"
+  | "OutboundTranslationSlices" =>
+    Some(OutboundTranslationSlice)
+  | "Aggregate" | "Aggregates" => Some(Aggregate)
+  | "ReadModel" | "ReadModels" => Some(ReadModel)
+  | "ReadModelStream" | "ReadModelStreams" => Some(ReadModelStream)
+  | "Task" | "Tasks" => Some(Task)
+  | "ExtensionPoint" | "ExtensionPoints" => Some(ExtensionPoint)
+  | "Extension" | "Extensions" => Some(Extension)
+  | _ => None
+  }
+
+let isKindFolder = (folder: string): bool => folderToKind(folder)->Option.isSome
+
+// Body-file suffixes stripped to recover a component's spec stem (longest first,
+// so `_ExtensionPointMapping` is removed before `_ExtensionPoint`). Spec and body
+// files in one folder collapse to the same component name.
+let bodySuffixes = [
+  "_ExtensionPointMapping",
+  "_ExtensionPoint",
+  "_Extension",
+  "_Projections",
+  "_Projection",
+  "_Mappings",
+  "_Behavior",
+  "_Automation",
+  "_Translation",
+]

package/src/components/ComponentKind.res.mjs

@@ -0,0 +1,125 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
+
+let all = [
+  "StateChangeSlice",
+  "StateViewSlice",
+  "StateViewSliceStream",
+  "AutomationSlice",
+  "InboundTranslationSlice",
+  "OutboundTranslationSlice",
+  "Aggregate",
+  "ReadModel",
+  "ReadModelStream",
+  "Task",
+  "ExtensionPoint",
+  "Extension"
+];
+
+function folderName(t) {
+  switch (t) {
+    case "StateChangeSlice" :
+      return "StateChangeSlice";
+    case "StateViewSlice" :
+      return "StateViewSlice";
+    case "StateViewSliceStream" :
+      return "StateViewSliceStream";
+    case "AutomationSlice" :
+      return "AutomationSlice";
+    case "InboundTranslationSlice" :
+      return "InboundTranslationSlice";
+    case "OutboundTranslationSlice" :
+      return "OutboundTranslationSlice";
+    case "Aggregate" :
+      return "Aggregate";
+    case "ReadModel" :
+      return "ReadModel";
+    case "ReadModelStream" :
+      return "ReadModelStream";
+    case "Task" :
+      return "Task";
+    case "ExtensionPoint" :
+      return "ExtensionPoint";
+    case "Extension" :
+      return "Extension";
+  }
+}
+
+function folderToKind(folder) {
+  switch (folder) {
+    case "Aggregate" :
+    case "Aggregates" :
+      return "Aggregate";
+    case "Automation" :
+    case "AutomationSlice" :
+    case "AutomationSlices" :
+    case "Automations" :
+      return "AutomationSlice";
+    case "ExtensionPoint" :
+    case "ExtensionPoints" :
+      return "ExtensionPoint";
+    case "Extension" :
+    case "Extensions" :
+      return "Extension";
+    case "InboundTranslation" :
+    case "InboundTranslationSlice" :
+    case "InboundTranslationSlices" :
+    case "InboundTranslations" :
+      return "InboundTranslationSlice";
+    case "OutboundTranslation" :
+    case "OutboundTranslationSlice" :
+    case "OutboundTranslationSlices" :
+    case "OutboundTranslations" :
+      return "OutboundTranslationSlice";
+    case "ReadModelStream" :
+    case "ReadModelStreams" :
+      return "ReadModelStream";
+    case "ReadModel" :
+    case "ReadModels" :
+      return "ReadModel";
+    case "StateChange" :
+    case "StateChangeSlice" :
+    case "StateChangeSlices" :
+    case "StateChanges" :
+      return "StateChangeSlice";
+    case "StateViewSliceStream" :
+    case "StateViewSliceStreams" :
+      return "StateViewSliceStream";
+    case "StateView" :
+    case "StateViewSlice" :
+    case "StateViewSlices" :
+    case "StateViews" :
+      return "StateViewSlice";
+    case "Task" :
+    case "Tasks" :
+      return "Task";
+    default:
+      return;
+  }
+}
+
+function isKindFolder(folder) {
+  return Stdlib_Option.isSome(folderToKind(folder));
+}
+
+let bodySuffixes = [
+  "_ExtensionPointMapping",
+  "_ExtensionPoint",
+  "_Extension",
+  "_Projections",
+  "_Projection",
+  "_Mappings",
+  "_Behavior",
+  "_Automation",
+  "_Translation"
+];
+
+export {
+  all,
+  folderName,
+  folderToKind,
+  isKindFolder,
+  bodySuffixes,
+}
+/* No side effect */

package/src/components/Counter.res

@@ -0,0 +1,24 @@
+/**
+A named counter (e.g. `"ProductCount"`). Used as a key in the counts database.
+Multiple counters can exist within the same `Counter` component.
+*/
+type counterId = string
+
+/**
+An opaque reference string that de-duplicates counter increments.
+
+Each unique `reference` is counted at most once per `counterId`.
+Typically set to the event's message ID to make increments idempotent.
+*/
+type reference = string
+
+/**
+A counter threshold target.
+
+When the count for `counterId` reaches `target`, the event mapping
+framework fires the associated command.
+*/
+type counterTarget = {
+  counterId: counterId,
+  target: int,
+}

package/src/components/Counter.res.mjs

@@ -0,0 +1,2 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+/* This output is empty. Its source's type definitions, externals and/or unused code got optimized away. */