@reventlessdev/reventless-spec 3.0.0-alpha.61

package/src/types/Projection.res

@@ -0,0 +1,220 @@
+/**
+The aggregate whose events drive this projection.
+Used to subscribe to the correct event topic.
+*/
+module type Source = {
+  module Id: Id.T
+  let name: string
+  @schema
+  type event
+}
+
+/**
+The read model table that stores the projected state.
+`subIdConfig` enables composite-key tables (id + sub-id).
+*/
+module type Target = {
+  module Id: Id.T
+  let name: string
+  @schema
+  type state
+  let subIdConfig: option<ReadModel.subIdConfig<state>>
+}
+
+/**
+The outcome of a projection mapping — what to do with the read model state
+after processing a source event.
+
+Returned from a `Projection.Mapping` `project` function.
+Return `Ignore` (or `[]`) when an event should not affect the read model.
+
+@example
+```rescript
+// CategoriesProjections.res
+let project = ({event, id, _}) => switch event {
+  | CategoryAdded({categoryId, name}) =>
+    Set(id, {CategoriesReadModel.categoryId, name, archived: false})
+  | CategoryRenamed({name}) => Update(id, state => {...state, name})
+  | CategoryArchived(_) => Update(id, state => {...state, archived: true})
+}
+```
+*/
+type action<'id, 'state> =
+  /** Create a new state entry. The entry must not already exist. */
+  | Create('id, 'state)
+  /** Create many new state entries. Entries must not already exist. */
+  | CreateMany(array<('id, 'state)>)
+  /** Update an existing entry by applying a transform function. */
+  | Update('id, 'state => 'state)
+  /** Update many existing entries. */
+  | UpdateMany(array<'id>, ('id, 'state) => 'state)
+  /** Update an existing entry, or create it with `'state` if it does not exist. */
+  | UpdateWithDefault('id, 'state, 'state => 'state)
+  /** Update many entries or create them with a default derived from their ID. */
+  | UpdateManyWithDefault(array<'id>, 'id => 'state, ('id, 'state) => 'state)
+  /** Overwrite the state for an entry, creating it if it does not exist. */
+  | Set('id, 'state)
+  /** Overwrite the state for many entries. */
+  | SetMany(array<'id>, 'id => 'state)
+  /** Delete an existing entry. */
+  | Delete('id)
+  /** Delete many entries. */
+  | DeleteMany(array<'id>)
+  /** Delete an entry only if the predicate returns true. */
+  | DeleteIf('id, 'state => bool)
+  /** Delete many entries conditionally. */
+  | DeleteManyIf(array<'id>, ('id, 'state) => bool)
+  /**
+  Create multiple sub-state rows under the same primary ID.
+  Used when one event produces several independent sub-entries.
+  */
+  | CreateMultiState('id, array<'state>)
+  /**
+  Replace the entire set of sub-state rows for a primary ID.
+  The transform receives the current rows and returns the new rows.
+  */
+  | UpdateMultiState('id, array<'state> => array<'state>)
+  /** Update sub-state rows for multiple primary IDs. */
+  | UpdateManyMultiStates(array<'id>, ('id, array<'state>) => array<'state>)
+  /** No-op. Return this when an event should not affect the read model. */
+  | Ignore
+
+/**
+A compiled single-source-to-single-target mapping.
+
+Created by `Projection.Mapping.Make(Source, Target, MappingImpl)`.
+The `project` function receives a full `Message.event'` envelope and returns
+one `action` value.
+*/
+module type Mapping = {
+  //module Source: Source
+  //module Target: Target // NOTE: to be destructive substituted
+  module SourceId: Id.T
+  @schema
+  type sourceEvent
+  @schema
+  type targetState
+
+  let project: Message.event'<string, sourceEvent> => action<string, targetState>
+  let sourceEventSchema: S.t<sourceEvent>
+  let sourceName: string
+  let subIdConfig: option<ReadModel.subIdConfig<targetState>>
+  let targetStateSchema: S.t<targetState>
+}
+
+/**
+A collection of `Mapping` modules for a single read model target.
+
+Pass a `Mappings` module to `Platform.ReadModel.Make` to register all
+source-to-target projections for a read model.
+*/
+module type Mappings = {
+  module Target: Target // to be removed via destructive replace in functor call
+  module type Mapping = Mapping with type targetState = Target.state
+  let moduleUrl: string
+  let mappings: array<module(Mapping)>
+}
+
+module type MappingImpl = {
+  type sourceEvent
+  type targetState
+  let project: Message.event'<string, sourceEvent> => action<string, targetState>
+}
+
+/**
+Builds a `Projection.Mapping` from a `Source`, `Target`, and `MappingImpl`.
+
+@example
+```rescript
+// CategoriesProjections.res
+module CategoryMapping = Projection.Mapping.Make(
+  Category,
+  CategoriesReadModel,
+  {
+    let project = ({event, id, _}) => switch event {
+      | CategoryAdded({categoryId, name}) =>
+        Set(id, {CategoriesReadModel.categoryId, name, archived: false})
+      | CategoryRenamed({name}) => Update(id, state => {...state, name})
+      | CategoryArchived(_) => Update(id, state => {...state, archived: true})
+    }
+  },
+)
+```
+*/
+module Mapping = {
+  module Make = (
+    Source: Source,
+    Target: Target,
+    MappingImpl: MappingImpl with type sourceEvent := Source.event and type targetState := Target.state,
+  ): (Mapping with type targetState = Target.state and type sourceEvent = Source.event and module SourceId = Source.Id) => {
+    module SourceId = Source.Id
+    @schema
+    type sourceEvent = Source.event
+    @schema
+    type targetState = Target.state
+    let project = MappingImpl.project
+    let sourceName = Source.name
+    let subIdConfig = Target.subIdConfig
+  }
+}
+
+module Mappings = {
+  module Make = (Target: Target) => {
+    module type Mapping = Mapping with type targetState = Target.state
+  }
+}
+
+/**
+Builds a `Projection.Source` module for a DCB EventLog.
+
+A DCB-source `Mapping.Make` takes a `Source` whose `name` matches the key under
+which `Plugin_Builder` registers the DCB topic in `allEventTopics`
+(`<pluginName>DcbEventLog`). This helper is a thin convenience that asserts the
+`Source` shape over an inline DCB event subset — the `event` type only needs to
+enumerate the variants this consumer projects (others fall through as decode
+errors and the runtime treats them as `Ignore`).
+
+@example
+```rescript
+// catalog/src/Product/ReadModel/CatalogDcbSource.res
+module CatalogDcbSource = Reventless.Projection.DcbSource.Make({
+  let name = "CatalogDcbEventLog"
+  @schema
+  type event =
+    | ProductAdded({productId: string, name: string, price: float})
+    | ProductRenamed({productId: string, name: string})
+})
+```
+
+Then in your projections file:
+```rescript
+module ProductsFromDcb = Reventless.Projection.Mapping.Make(
+  CatalogDcbSource,
+  ProductsReadModel,
+  { let project = ({event, id, _}) => switch event {
+      | ProductAdded({name}) => Set(id, {ProductsReadModel.name})
+      | ProductRenamed({name}) => Update(id, s => {...s, name})
+    } },
+)
+```
+
+`module Id` is `Reventless.Id.String` for DCB sources — DCB events are
+content-addressed and have no aggregate-style stream ID.
+*/
+module DcbSource = {
+  module type Definition = {
+    let name: string
+    @schema
+    type event
+  }
+  // Returned signature is left structurally inferred (NOT sealed under `Source`)
+  // so that variant constructors of `D.event` remain accessible to callers
+  // writing `switch msg.event { | ProductAdded(_) => ... }`. The result still
+  // satisfies `Source` structurally and is accepted by `Mapping.Make` as such.
+  module Make = (D: Definition) => {
+    module Id = Id.String
+    let name = D.name
+    type event = D.event
+    let eventSchema = D.eventSchema
+  }
+}

package/src/types/Projection.res.mjs

@@ -0,0 +1,44 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+
+function Make(Source) {
+  return Target => (MappingImpl => ({
+    SourceId: Source.Id,
+    project: MappingImpl.project,
+    sourceEventSchema: Source.eventSchema,
+    sourceName: Source.name,
+    subIdConfig: Target.subIdConfig,
+    targetStateSchema: Target.stateSchema
+  }));
+}
+
+let Mapping = {
+  Make: Make
+};
+
+function Make$1(Target) {
+  return {};
+}
+
+let Mappings = {
+  Make: Make$1
+};
+
+function Make$2(D) {
+  return {
+    Id: undefined,
+    name: D.name,
+    eventSchema: D.eventSchema
+  };
+}
+
+let DcbSource = {
+  Make: Make$2
+};
+
+export {
+  Mapping,
+  Mappings,
+  DcbSource,
+}
+/* No side effect */

package/src/types/QueryEngine.res

@@ -0,0 +1,123 @@
+/**
+A typed query value used as a filter operand.
+
+Wraps the three primitive types supported by the query engine so that
+filter comparisons are type-safe without requiring a raw JSON representation.
+*/
+type value =
+  | String(string)
+  | Int(int)
+  | Bool(bool)
+
+/**
+Filter operations for read model queries.
+
+`Filter.config` is a triple `(fieldName, comparator, value)` applied on top of
+the primary key lookup to narrow the result set.
+
+@example
+```rescript
+// Only return categories where archived = false
+let activeFilter: QueryEngine.Filter.config = ("archived", Equal, Bool(false))
+```
+*/
+module Filter = {
+  /** Comparison operators available for field-level filters. */
+  type comparator =
+    | Equal
+    | Unequal
+    | LessOrEqual
+    | Less
+    | GreaterOrEqual
+    | Greater
+    /** Field must exist (have a value). */
+    | Exists
+    /** Field must not exist. */
+    | NotExists
+    /** String / set membership: field contains the given substring or element. */
+    | Contains
+    | NotContains
+    | BeginsWith
+
+  /** A filter specification: `(fieldName, comparator, value)`. */
+  type config = (string, comparator, value)
+}
+
+/**
+Sub-ID filter operations for composite-key read model queries.
+
+`SubId.config` narrows results within a partition already selected by the primary ID.
+
+@example
+```rescript
+// Only return rows where subId begins with "cat-"
+let categoryFilter: QueryEngine.SubId.config = ("categoryId", BeginsWith, String("cat-"))
+```
+*/
+module SubId = {
+  /** Comparison operators available for sub-ID range conditions. */
+  type comparator =
+    | Equal
+    | Unequal
+    | LessOrEqual
+    | Less
+    | GreaterOrEqual
+    | Greater
+    | BeginsWith
+
+  /** A sub-ID filter specification: `(subIdField, comparator, value)`. */
+  type config = (string, comparator, value)
+}
+
+/**
+Fetches rows from a read model by primary key, with optional sub-ID range and
+additional attribute filters.
+
+@example
+```rescript
+let rows = await queryEngine.query(
+  ~readModelName="Categories",
+  ~id=String("cat-1"),
+  ~filterConfigs=[("archived", Filter.Equal, Bool(false))],
+)
+```
+*/
+type query = (
+  ~readModelName: string,
+  ~key: string=?,
+  ~id: value,
+  ~subIdConfig: SubId.config=?,
+  ~filterConfigs: array<Filter.config>=?,
+  ~ascending: bool=?,
+  ~limit: int=?,
+) => promise<array<JSON.t>>
+
+/**
+Scans an entire read model table with attribute filters (no primary key).
+
+Use only when no primary key is available; scans are more expensive than queries.
+
+@example
+```rescript
+let allActive = await queryEngine.scan(
+  ~readModelName="Categories",
+  ~filterConfigs=[("archived", Filter.Equal, Bool(false))],
+  ~limit=100,
+)
+```
+*/
+type scan = (
+  ~readModelName: string,
+  ~filterConfigs: array<Filter.config>,
+  ~limit: int,
+) => promise<array<JSON.t>>
+
+/**
+Runtime query engine injected into task handlers, side effects, and extension point mappings.
+
+Provides provider-agnostic read access to all read models in the plugin.
+*/
+type operations = {
+  scan: scan,
+  query: query,
+}

package/src/types/QueryEngine.res.mjs

@@ -0,0 +1,12 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+
+let Filter = {};
+
+let SubId = {};
+
+export {
+  Filter,
+  SubId,
+}
+/* No side effect */

package/src/types/ReadConsistency.res

@@ -0,0 +1,38 @@
+// Per-slice decision-read consistency mode for DCB StateChangeSlices.
+//
+// Controls how a slice's decision-model read (the conditional read that
+// rebuilds `state` before `decide`) chooses DynamoDB read consistency across
+// the optimistic-concurrency retry loop in `StateChangeSlice_Callback`.
+//
+// Correctness is identical in every mode. A DynamoDB conditional write is
+// always evaluated against the latest committed data, so a stale (eventually
+// consistent) read can only ever cause a *rejected* append — which the retry
+// loop re-reads and resolves — never a wrong write. Strong reads are therefore
+// purely a cost/latency lever against the *replica-lag* class of conflicts;
+// they do nothing for genuine concurrent-writer conflicts (those serialize at
+// the fence regardless). See `docs/analysis/dcb-high-contention-handling.md`.
+//
+// The variant ships with three cases; further cases can be added without
+// breaking existing `@@reventless.consistency(...)` declarations.
+
+@schema
+type t =
+  | // Default: eventual read on the first attempt (cheaper RCU), then strong on
+  // every retry so a replica-lag conflict self-heals deterministically instead
+  // of burning further retries.
+  EscalateOnRetry
+  | // Always strong. For known-hot slices where replica-lag conflicts dominate
+  // and the first eventual read is not worth the wasted attempt.
+  AlwaysStrong
+  | // Always eventual, even on retry. For very cost-sensitive, low-contention
+  // slices that never want to pay strong-read RCU.
+  AlwaysEventual
+
+let default = EscalateOnRetry
+
+let toString = (v: t) =>
+  switch v {
+  | EscalateOnRetry => "EscalateOnRetry"
+  | AlwaysStrong => "AlwaysStrong"
+  | AlwaysEventual => "AlwaysEventual"
+  }

package/src/types/ReadConsistency.res.mjs

@@ -0,0 +1,29 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as S from "sury/src/S.res.mjs";
+
+let schema = S.union([
+  S.literal("EscalateOnRetry"),
+  S.literal("AlwaysStrong"),
+  S.literal("AlwaysEventual")
+]);
+
+function toString(v) {
+  switch (v) {
+    case "EscalateOnRetry" :
+      return "EscalateOnRetry";
+    case "AlwaysStrong" :
+      return "AlwaysStrong";
+    case "AlwaysEventual" :
+      return "AlwaysEventual";
+  }
+}
+
+let $$default = "EscalateOnRetry";
+
+export {
+  schema,
+  $$default as default,
+  toString,
+}
+/* schema Not a pure module */

package/src/types/Schedule.res

@@ -0,0 +1,65 @@
+@schema
+type year = int
+@schema
+type month = int
+@schema
+type day = int
+@schema
+type hour = int
+@schema
+type minute = int
+
+/**
+The repetition rule for a scheduled event.
+
+- `Single(year, month, day, hour, minute)` — fires once at an absolute UTC time
+- `Minutes(n)` / `Hours(n)` / `Days(n)` — fires every n minutes / hours / days
+- `Daily(hour, minute)` — fires every day at the given UTC time
+- `Weekdays(hour, minute)` — fires Monday–Friday at the given UTC time
+- `WeekdaysAndSaturday(hour, minute)` — fires Monday–Saturday at the given UTC time
+
+@example
+```rescript
+// Fire every 15 minutes
+let rate = Schedule.Minutes(15)
+
+// Fire once on 2024-12-31 at 23:59 UTC
+let oneTime = Schedule.Single(2024, 12, 31, 23, 59)
+```
+*/
+@schema
+type rate =
+  | Single(year, month, day, hour, minute)
+  | Minutes(int)
+  | Hours(int)
+  | Days(int)
+  | Daily(hour, minute)
+  | Weekdays(hour, minute)
+  | WeekdaysAndSaturday(hour, minute)
+
+/**
+A named recurring or one-time schedule.
+
+`payload` is an opaque string forwarded to the task handler when the schedule fires.
+
+@example
+```rescript
+let dailySync: Schedule.schedule = {
+  name: "DailyCatalogSync",
+  rate: Daily(2, 0),  // 02:00 UTC every day
+  payload: `{"action": "sync"}`,
+}
+```
+*/
+@schema
+type schedule = {
+  name: string,
+  rate: rate,
+  payload: string,
+}
+
+/** Creates a schedule in the underlying infrastructure (e.g. EventBridge Scheduler). */
+type create = schedule => promise<unit>
+
+/** Deletes a schedule by name from the underlying infrastructure. */
+type delete = /* ~name: */ string => promise<unit>

package/src/types/Schedule.res.mjs

@@ -0,0 +1,68 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as S from "sury/src/S.res.mjs";
+
+let rateSchema = S.union([
+  S.schema(s => ({
+    TAG: "Single",
+    _0: s.m(S.int),
+    _1: s.m(S.int),
+    _2: s.m(S.int),
+    _3: s.m(S.int),
+    _4: s.m(S.int)
+  })),
+  S.schema(s => ({
+    TAG: "Minutes",
+    _0: s.m(S.int)
+  })),
+  S.schema(s => ({
+    TAG: "Hours",
+    _0: s.m(S.int)
+  })),
+  S.schema(s => ({
+    TAG: "Days",
+    _0: s.m(S.int)
+  })),
+  S.schema(s => ({
+    TAG: "Daily",
+    _0: s.m(S.int),
+    _1: s.m(S.int)
+  })),
+  S.schema(s => ({
+    TAG: "Weekdays",
+    _0: s.m(S.int),
+    _1: s.m(S.int)
+  })),
+  S.schema(s => ({
+    TAG: "WeekdaysAndSaturday",
+    _0: s.m(S.int),
+    _1: s.m(S.int)
+  }))
+]);
+
+let scheduleSchema = S.schema(s => ({
+  name: s.m(S.string),
+  rate: s.m(rateSchema),
+  payload: s.m(S.string)
+}));
+
+let yearSchema = S.int;
+
+let monthSchema = S.int;
+
+let daySchema = S.int;
+
+let hourSchema = S.int;
+
+let minuteSchema = S.int;
+
+export {
+  yearSchema,
+  monthSchema,
+  daySchema,
+  hourSchema,
+  minuteSchema,
+  rateSchema,
+  scheduleSchema,
+}
+/* rateSchema Not a pure module */

package/src/types/SideEffect.res

@@ -0,0 +1,45 @@
+/**
+The event source that a `SideEffect.T` module listens to.
+
+Mirrors the aggregate `EventLog.T` shape — the adapter uses `name` and `Id`
+to subscribe to the correct event topic.
+*/
+module type Source = {
+  let name: string
+  module Id: Id.T
+  /** The event type whose emissions trigger this side effect. */
+  @schema
+  type event
+}
+
+/**
+Module type for an imperative side effect triggered by aggregate events.
+
+Side effects are registered on a `Task` and executed after the event is stored.
+They have read access to the query engine but do NOT emit new events or commands.
+
+@example
+```rescript
+module NotifyOnCategoryAdded: SideEffect.T = {
+  module Source = Category
+  let execute = async (id, _meta, event, _queryEngine) => switch event {
+    | CategoryAdded({name}) =>
+      Console.log2("Category added:", name)
+    | _ => ()
+  }
+}
+```
+*/
+module type T = {
+  module Source: Source
+  let moduleUrl: string
+  /**
+  Called once for each event emitted by `Source`.
+
+  - `id` — the aggregate ID that emitted the event
+  - `meta` — the message envelope metadata
+  - `event` — the domain event payload
+  - `queryEngine` — read-only access to all plugin read models
+  */
+  let execute: (Source.Id.t, Message.meta, Source.event, QueryEngine.operations) => promise<unit>
+}

package/src/types/SideEffect.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. */

package/src/types/StoredEvent.res

@@ -0,0 +1,46 @@
+// Logical envelope for an event as it lives in storage (EventLog or DcbEventLog).
+// The DynamoDB adapters flatten `meta` to top-level item attributes so meta keys
+// stay GSI-projectable; the in-memory adapter stores the nested record as-is.
+//
+// This is the single source of truth for the on-disk shape — both
+// EventLog_Operations and DcbEventLogStorage_DynamoDb_Runtime go through it
+// rather than building Dict items by hand.
+
+/**
+A stored event record. Used by both backends:
+- Aggregate EventLog: `id` is the aggregate id, `position` is the zero-padded sequence string, `tags` is absent.
+- DcbEventLog: `id` is the synthesised partition key (derived from tags), `position` is "<unixMs>-<uuid>", `tags` is present.
+
+`event` is the variant constructor name (the on-disk "event" column).
+`data` is the sury-encoded variant payload with the TAG discriminator stripped.
+`recordedAt` is the storage timestamp, set by the storage adapter at append.
+*/
+type storedEvent<'id> = {
+  id: 'id,
+  position: string,
+  event: string,
+  data: JSON.t,
+  meta: Message.meta,
+  recordedAt: string,
+  tags?: array<DcbTag.tag>,
+}
+
+/** Build a sury schema for `storedEvent<'id>` given the `'id` schema. */
+let toStoredEventSchema = (idSchema: S.t<'id>): S.t<storedEvent<'id>> =>
+  S.object(s => {
+    id: s.field("id", idSchema),
+    position: s.field("position", S.string),
+    event: s.field("event", S.string),
+    data: s.field("data", S.json),
+    meta: s.field("meta", Message.metaSchema),
+    recordedAt: s.field("recordedAt", S.string),
+    tags: ?s.field("tags", S.option(S.array(DcbTag.tagSchema))),
+  })
+
+/** Decode a `storedEvent<'id>` from JSON. */
+let decode = (json, idSchema) =>
+  json->S.parseJsonOrThrow(toStoredEventSchema(idSchema))
+
+/** Encode a `storedEvent<'id>` to JSON. */
+let encode = (stored, idSchema) =>
+  stored->S.reverseConvertToJsonOrThrow(toStoredEventSchema(idSchema))