@reventlessdev/reventless-infra 3.0.0-alpha.100

package/src/components/DcbEventLog.res

@@ -0,0 +1,130 @@
+/**
+Deploy-time outputs produced when a `DcbEventLog` is provisioned.
+
+- `resources` — the underlying storage infrastructure (e.g. DynamoDB table)
+- `eventTopic` — the SNS topic for downstream subscribers (state view slices)
+*/
+type outputs = {resources: array<Adapter.resource>, eventTopic: EventTopic.outputs}
+
+/**
+A raw event ready to be stored in the DCB log.
+Produced by slice callbacks after encoding with their eventSchema.
+
+`meta` is the envelope metadata for this event (causation, correlation, tracing).
+Slice callbacks derive it from the triggering message's context.
+*/
+type rawEvent = {
+  eventType: string,
+  data: JSON.t,
+  tags: array<Reventless.DcbTag.tag>,
+  meta: Reventless.Message.meta,
+}
+
+/**
+A raw event read from the DCB log at a known position.
+Consumed by slice callbacks for decoding with their consumedEventSchema.
+
+`meta` is the envelope metadata that was written at append time.
+`recordedAt` is the storage timestamp, set by the storage adapter at append.
+*/
+type rawSequencedEvent = {
+  position: Reventless.DcbTag.sequencePosition,
+  eventType: string,
+  data: JSON.t,
+  tags: array<Reventless.DcbTag.tag>,
+  meta: Reventless.Message.meta,
+  recordedAt: string,
+}
+
+/**
+The result of a DCB `read` operation.
+
+- `events` — the matching events in sequence order
+- `headPosition` — the sequence position of the last event read (use as the
+  `after` cursor in a subsequent `appendCondition` to detect conflicts)
+*/
+type readResult = {
+  events: array<rawSequencedEvent>,
+  headPosition?: Reventless.DcbTag.sequencePosition,
+}
+
+/**
+Reads events from the DCB log matching the given query.
+
+- `~query` — content-based filter (event types + tags)
+- `~after` — optional cursor; only events after this position are returned
+*/
+type read = (
+  ~query: Reventless.DcbTag.query,
+  ~after: Reventless.DcbTag.sequencePosition=?,
+) => promise<readResult>
+
+/**
+Typed DCB append outcome — mirrors `EventLog.appendError`. `Conflict` is the
+optimistic-concurrency sentinel (the append-condition failed: a matching event
+was written since `condition.after`), which the slice callback retries by
+re-reading and re-deciding. Every other failure is a `StorageFailure` carrying
+its message. Replaces the former string sentinel that conflated the two — a
+storage error whose text happened to contain "conflict" would have been retried
+forever, and backends disagreed on the sentinel's casing so conflict metrics were
+misclassified across backends.
+*/
+type appendError =
+  | Conflict
+  | StorageFailure(string)
+
+/**
+Appends raw events to the DCB log with optional optimistic-concurrency checking.
+
+Returns `Ok(position)` on success or `Error(Conflict)` if the append condition
+was violated (i.e. the log was modified since `condition.after`), or
+`Error(StorageFailure(_))` on any other failure.
+*/
+type append = (
+  array<rawEvent>,
+  ~condition: Reventless.DcbTag.appendCondition=?,
+) => promise<result<Reventless.DcbTag.sequencePosition, appendError>>
+
+/**
+Streams events from the DCB log matching the given query.
+Use for large result sets that should not be loaded into memory at once.
+*/
+type readStream = (
+  ~query: Reventless.DcbTag.query,
+  ~after: Reventless.DcbTag.sequencePosition=?,
+  /** Opt into strongly-consistent single-tag reads. Defaults to eventually
+      consistent: a stale read can only cause a rejected append (then a retry),
+      never a wrong write, because the append fence is always evaluated strongly.
+      The slice callback sets this on retries (eventual-first, strong-on-retry). */
+  ~strongConsistency: bool=?,
+) => Stream.t<rawSequencedEvent, string, unit>
+
+/**
+Appends a stream of raw events to the DCB log as an `Effect.t`.
+Use for high-throughput batch imports.
+*/
+type appendStream = (
+  Stream.t<rawEvent, string, unit>,
+  ~condition: Reventless.DcbTag.appendCondition=?,
+) => Effect.t<result<Reventless.DcbTag.sequencePosition, appendError>, string, unit>
+
+/**
+Runtime operations exposed by a `DcbEventLog` component.
+Works with raw events — encode/decode is handled by each slice's callback.
+
+Obtained via `Component.operations(dcbEventLog)`. Available inside Lambda handlers.
+*/
+type operations = {
+  read: read,
+  append: append,
+  readStream: readStream,
+  appendStream: appendStream,
+}
+
+type t
+type component = Component.t<t, outputs, operations>
+
+module type T = {
+  type component = component
+  let make: (~name: string, ~indexes: array<string>=?, ~opts: Pulumi.ComponentResource.options=?) => component
+}

package/src/components/DcbEventLog.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/components/DeployBootstrap.res

@@ -0,0 +1,83 @@
+/**
+Deploy-time bootstrap seam: a named choke point through which a deploy program
+runs cross-cutting activations at fixed phases, without hand-editing the
+generated `Main.res`.
+
+No-op by default. Zero registrations ⇒ `run` does nothing ⇒ existing generated
+and hand-written deploy programs are byte-identical and preview with no resource
+diff. An extension (a backend, an operational package) registers a contribution
+via `register` — at module-load time as an import side effect, or explicitly —
+and the generated program's `run(PreDeploy)` / `run(PostDeploy)` calls fire it in
+registration order.
+
+Same shape as `ReventlessCore.Monitoring.use`: a module-level registry consulted
+by an emitted call, so deploy-time extension becomes *registration*, not *file
+editing*. See `docs/plans/deploy-bootstrap-seam.md`.
+*/
+
+/**
+Ordered phases at which bootstrap contributions run during a deploy program.
+*/
+type phase =
+  | /** before `deployPlatform` / `deployPlugin` — seam registration and other
+       ordering-sensitive activations that must precede the platform/plugin
+       graph build */
+  PreDeploy
+  | /** after the platform/plugin graph is registered — exports, cross-stack
+       output emission */
+  PostDeploy
+
+type contribution = unit => unit
+
+let preContributions: ref<array<contribution>> = ref([])
+let postContributions: ref<array<contribution>> = ref([])
+let preRan = ref(false)
+let postRan = ref(false)
+
+let registryFor = phase =>
+  switch phase {
+  | PreDeploy => preContributions
+  | PostDeploy => postContributions
+  }
+
+let ranFor = phase =>
+  switch phase {
+  | PreDeploy => preRan
+  | PostDeploy => postRan
+  }
+
+/**
+Register a contribution. Contributions run in registration order within a phase.
+Safe to call at module-load time (as an import side effect) or explicitly.
+Defaults to `PreDeploy`.
+*/
+let register = (~phase=PreDeploy, contribution: contribution) => {
+  let registry = registryFor(phase)
+  registry := registry.contents->Array.concat([contribution])
+}
+
+/**
+Run all contributions registered for a phase, in registration order. Emitted by
+generated deploy programs around the platform/plugin build. Idempotent per phase:
+running an already-run phase is a no-op, and running a phase with no
+registrations does nothing.
+*/
+let run = (phase: phase) => {
+  let ran = ranFor(phase)
+  if !ran.contents {
+    ran := true
+    registryFor(phase).contents->Array.forEach(contribution => contribution())
+  }
+}
+
+/**
+Reset all registries and run-flags. Test-support only — deploy programs never
+call this. Lets a test exercise registration order, phase isolation, and
+idempotency from a clean slate.
+*/
+let reset = () => {
+  preContributions := []
+  postContributions := []
+  preRan := false
+  postRan := false
+}

package/src/components/DeployBootstrap.res.mjs

@@ -0,0 +1,69 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+
+let preContributions = {
+  contents: []
+};
+
+let postContributions = {
+  contents: []
+};
+
+let preRan = {
+  contents: false
+};
+
+let postRan = {
+  contents: false
+};
+
+function registryFor(phase) {
+  if (phase === "PreDeploy") {
+    return preContributions;
+  } else {
+    return postContributions;
+  }
+}
+
+function ranFor(phase) {
+  if (phase === "PreDeploy") {
+    return preRan;
+  } else {
+    return postRan;
+  }
+}
+
+function register(phaseOpt, contribution) {
+  let phase = phaseOpt !== undefined ? phaseOpt : "PreDeploy";
+  let registry = registryFor(phase);
+  registry.contents = registry.contents.concat([contribution]);
+}
+
+function run(phase) {
+  let ran = ranFor(phase);
+  if (!ran.contents) {
+    ran.contents = true;
+    registryFor(phase).contents.forEach(contribution => contribution());
+    return;
+  }
+}
+
+function reset() {
+  preContributions.contents = [];
+  postContributions.contents = [];
+  preRan.contents = false;
+  postRan.contents = false;
+}
+
+export {
+  preContributions,
+  postContributions,
+  preRan,
+  postRan,
+  registryFor,
+  ranFor,
+  register,
+  run,
+  reset,
+}
+/* No side effect */

package/src/components/EventCollector.res

@@ -0,0 +1,19 @@
+/**
+ * Enqueues an event for processing by a downstream component (e.g. a read model).
+ *
+ * - `delay` — delivery delay in seconds (0 for immediate delivery)
+ * - `id` — the aggregate ID string the event belongs to
+ * - `message` — the serialized event payload (JSON string)
+ *
+ * This function is exposed by read model `operations` so that the aggregate
+ * runtime can push events without knowing the read model's infrastructure details.
+ */
+type enqueueEvent = (/* ~delay: */ int, /* ~id: */ string, /* ~message: */ string) => promise<unit>
+
+/**
+ * Deploy-time outputs produced when an `EventCollector` is provisioned.
+ *
+ * An `EventCollector` is the inbound queue of a read model — events are collected
+ * here and then processed in order by the read model's projection function.
+ */
+type outputs = {name: string, resources: array<Adapter.resource>}

package/src/components/EventCollector.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/components/EventLog.res

@@ -0,0 +1,24 @@
+/**
+Module type for an aggregate's event log specification.
+
+`EventLog.T` is used by the framework to configure the event storage backend
+(e.g. a DynamoDB table) and the associated event topic for downstream subscribers.
+*/
+module type T = {
+  module Id: Reventless.Id.T
+
+  /** Logical name of the aggregate / event stream (used as a table-name prefix). */
+  let name: string
+
+  /** The event type stored in this log. Must carry `@schema` for serialization. */
+  @schema
+  type event
+}
+
+/**
+Deploy-time outputs produced when an `EventLog` is provisioned.
+
+- `resources` — the underlying infrastructure resources (e.g. DynamoDB table)
+- `eventTopic` — the event topic outputs for downstream subscribers
+*/
+type outputs = {resources: array<Adapter.resource>, eventTopic: EventTopic.outputs}

package/src/components/EventLog.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/components/EventMapper.res

@@ -0,0 +1,37 @@
+/**
+Deploy-time outputs produced when an `EventMapper` is provisioned.
+
+An `EventMapper` subscribes to an aggregate's event topic and routes events
+to one or more target aggregate command topics, optionally via a `Counter`.
+*/
+type outputs = {
+  name: string,
+  eventCollector: Pulumi.Output.t<EventCollector.outputs>,
+  counter?: Counter.outputs,
+}
+
+/**
+A collection of `EventMapping.T` modules that route events from one aggregate
+to commands on one or more target aggregates.
+
+Pass a `Mappings` module to `Platform.Aggregate.Make` as the third argument.
+Use `NoEventMappings.Make(TargetSpec)` when no routing is needed.
+
+@example
+```rescript
+// CatalogPlugin.res
+module CategoryMappings: Mappings with module Target := CategoriesReadModel = {
+  module CategoryMappings = Mappings.Make(CategoriesReadModel)
+  module type Mapping = CategoryMappings.Mapping
+  let mappings = CategoriesProjections.mappings
+}
+```
+*/
+module type Mappings = {
+  module Target: Reventless.EventMapping.Target
+  module type Mapping = Reventless.EventMapping.T with module Target := Target
+  let moduleUrl: string
+  let mappings: array<module(Mapping)>
+  /** Optional counter component for threshold-based command triggers. */
+  let counter: option<module(Counter.T)>
+}

package/src/components/EventMapper.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/components/EventTopic.res

@@ -0,0 +1,51 @@
+/**
+Module type for an aggregate's event topic specification.
+
+`EventTopic.T` is used by the framework to identify the event channel
+(e.g. an SNS topic) and validate that published events match the
+aggregate's event schema.
+*/
+module type T = {
+  module Id: Reventless.Id.T
+
+  /** Logical name of the aggregate or component owning this event topic. */
+  let name: string
+
+  /** The event type published to this topic. Must carry `@schema` for serialization. */
+  @schema
+  type event
+}
+
+/**
+Deploy-time outputs produced when an `EventTopic` is provisioned.
+Contains the underlying messaging infrastructure resources.
+*/
+type outputs = {resources: array<Adapter.resource>}
+
+/** A dictionary of event topic outputs keyed by aggregate name. */
+type allOutputs = dict<outputs>
+
+/**
+Publishes a single event as raw JSON to the event topic.
+
+- `string` — the aggregate ID (as a plain string)
+- `Message.meta` — the event envelope metadata
+- `JSON.t` — the serialized event payload
+*/
+type publishJson = (string, Reventless.Message.meta, JSON.t) => promise<unit>
+
+/**
+An item in a streaming event publication batch.
+Passed to `publishJsonStream` for high-throughput event pipelines.
+*/
+type publishJsonStreamItem = {
+  service: string,
+  meta: Reventless.Message.meta,
+  json: JSON.t,
+}
+
+/**
+Publishes a stream of event items as an `Effect.t`.
+Use this for high-throughput or streaming event pipelines.
+*/
+type publishJsonStream = Stream.t<publishJsonStreamItem, string, unit> => Effect.t<unit, string, unit>

package/src/components/EventTopic.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/components/Extension.res

@@ -0,0 +1,64 @@
+/**
+Deploy-time outputs produced when an `Extension` is provisioned.
+
+- `name` — the extension's logical name
+- `extensionPointName` — the extension point this extension connects to
+- `aggregateNames` — names of aggregates wired through this extension
+*/
+type outputs = {
+  name: string,
+  extensionPointName: string,
+  aggregateNames: array<string>,
+}
+
+// eventHandler type is defined in reventless (references Plugin.pluginDefinition which
+// would create a circular dependency: Extension → Plugin → Extension).
+// The spec-level T uses abstract `type operations` to avoid the cycle.
+
+/**
+Module type for a provisioned extension component.
+
+An `Extension` connects a host plugin's extension point to one or more aggregates,
+translating commands and events in both directions via `ExtensionMapping.Mapping`.
+
+`operations` is left abstract at the spec level to avoid a circular dependency.
+The concrete type is defined in the `reventless` package.
+*/
+module type T = {
+  type operations
+  type component
+  let make: (
+    ~publishToPluginExtensionPoint: CommandTopic.publishJsons,
+    ~publishToAggregates: dict<CommandTopic.publishJsons>,
+    ~readModelNamesForSourceName: dict<array<string>>,
+    ~publishToReadModels: dict<EventCollector.enqueueEvent>,
+    ~queryEngine: Reventless.QueryEngine.operations,
+    ~opts: option<Pulumi.ComponentResource.options>,
+  ) => component
+  let outputs: component => outputs
+  let operations: component => Pulumi.Output.t<operations>
+}
+
+/**
+Pre-build blueprint for an extension — compiled mappings that have not yet been
+instantiated as a Pulumi component.
+
+`Plugin.make` receives blueprints, groups them by extension point name,
+auto-merges mappings for the same EP, sets the component name to the plugin
+name, and builds the actual `Extension` component.
+*/
+module type Blueprint = {
+  module Spec: ExtensionMapping.Spec
+  module type Mapping = ExtensionMapping.T with module ExtensionPoint := Spec
+  let name: string
+  // npm-style specifier of the user extension file (the one declaring the
+  // `module Mapping`). Threaded from the user-facing Mapping.moduleUrl by
+  // Platform.Extension.Make so deploy-side helpers can emit HANDLER_CONFIG
+  // entries that let the runtime dynamic-import the user mapping at cold
+  // start.
+  let moduleUrl: string
+  // npm-style specifier of the Delegate (aggregate / slice) the extension
+  // delegates to. Threaded from Mapping.delegateModuleUrl by Platform.Extension.Make.
+  let delegateModuleUrl: string
+  let mappings: array<module(Mapping)>
+}

package/src/components/Extension.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/components/ExtensionPoint.res

@@ -0,0 +1,62 @@
+/**
+Deploy-time outputs produced when an `ExtensionPoint` is provisioned.
+
+- `name` — the extension point's logical name
+- `aggregateNames` — names of aggregates connected via `ExtensionPointMapping`
+- `commandTopic` — the inbound command queue for extensions to publish to
+- `eventTopic` — the outbound event topic extensions subscribe to
+*/
+type outputs = {
+  name: string,
+  aggregateNames: array<string>,
+  commandTopic: Pulumi.Output.t<CommandTopic.outputs>,
+  eventTopic: Pulumi.Output.t<EventTopic.outputs>,
+  // Module URLs preserved from the Spec and Mappings packed into Make. The
+  // EventCollector runtime needs them at HANDLER_CONFIG-build time to wire
+  // outgoing event publication for this extension point — see
+  // `Plugin_Helpers.registerEventCollectorContext` and the `extensionPointEntry`
+  // type that's serialised into the Lambda's HANDLER_CONFIG.
+  specModule: string,
+  mappingsModule: string,
+}
+
+// eventHandler type is defined in reventless (references Plugin.pluginDefinition which
+// would create a circular dependency: ExtensionPoint → Plugin → ExtensionPoint).
+// The infra-level T uses abstract `type operations` to avoid the cycle.
+
+/**
+A collection of `ExtensionPointMapping.T` modules connecting aggregates to
+this extension point.
+
+Pass a `Mappings` module to `Platform.ExtensionPoint.Make` to register all
+aggregate-to-extension-point connections.
+*/
+module type Mappings = {
+  module Spec: ExtensionPointMapping.Spec
+  module type Mapping = ExtensionPointMapping.T with module ExtensionPoint := Spec
+  let name: string
+  let moduleUrl: string
+  let mappings: array<module(Mapping)>
+}
+
+/**
+Module type for a provisioned extension point component.
+
+`operations` is left abstract to avoid a circular dependency between
+`ExtensionPoint`, `Plugin`, and back. The concrete type is defined in
+the `reventless` package.
+*/
+module type T = {
+  type operations
+  type component
+  let make: (
+    ~aggregateResources: dict<array<Adapter.resource>>,
+    ~publishToAggregates: dict<CommandTopic.publishJsons>,
+    ~scheduler: Scheduler.operations,
+    ~queryEngine: Reventless.QueryEngine.operations,
+    ~resourceNaming: ResourceNaming.operations,
+    ~opts: option<Pulumi.ComponentResource.options>,
+  ) => component
+  let outputs: component => outputs
+  let operations: component => Pulumi.Output.t<operations>
+}

package/src/components/ExtensionPoint.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/components/Heartbeat.res

@@ -0,0 +1,7 @@
+/**
+ * Deploy-time outputs produced when a `Heartbeat` component is provisioned.
+ *
+ * The heartbeat is an internal health-check component that periodically fires
+ * to verify that the plugin's Lambda handlers are reachable and warm.
+ */
+type outputs = {name: string, resources: array<Adapter.resource>}

package/src/components/Heartbeat.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/components/InboundTranslationSlice.res

@@ -0,0 +1,41 @@
+/**
+Deploy-time outputs produced when an `InboundTranslationSlice` is provisioned.
+
+- `resources` -- the underlying infrastructure
+- `queryDb` -- the DynamoDB table for the audit log
+*/
+type outputs = {
+  resources: array<Adapter.resource>,
+  queryDb: QueryDb.outputs,
+}
+
+/**
+Runtime operations exposed by an `InboundTranslationSlice` component.
+
+- `receive` -- accept external input, translate it, and publish a command
+*/
+type operations = {
+  receive: JSON.t => promise<result<array<string>, string>>,
+}
+
+/**
+Module type produced by `Platform.InboundTranslationSlice.Make(Spec)`.
+
+@example
+```rescript
+module PaymentWebhookSlice = Platform.InboundTranslationSlice.Make(PaymentWebhook)
+let slice = PaymentWebhookSlice.make(~publishJsons=publishJsonsOutput)
+```
+*/
+type t
+
+module type T = {
+  module Spec: Reventless.InboundTranslationSlice.Spec
+  module Translation: Reventless.InboundTranslationSlice.Translation with module Spec := Spec
+  type component = Component.t<t, outputs, operations>
+  let queryDbName: string
+  let make: (
+    ~publishJsons: Pulumi.Output.t<CommandTopic.publishJsons>,
+    ~opts: Pulumi.ComponentResource.options=?,
+  ) => component
+}

package/src/components/InboundTranslationSlice.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/components/OutboundTranslationSlice.res

@@ -0,0 +1,44 @@
+/**
+Deploy-time outputs produced when an `OutboundTranslationSlice` is provisioned.
+
+- `resources` -- the underlying infrastructure (e.g. SQS subscription)
+- `queryDb` -- the DynamoDB table for the TODO list
+*/
+type outputs = {
+  resources: array<Adapter.resource>,
+  queryDb: QueryDb.outputs,
+}
+
+/**
+Runtime operations exposed by an `OutboundTranslationSlice` component.
+
+- `enqueueEvent` -- push events into the slice's projection queue
+- `translatePending` -- manually trigger Phase 2 (useful in tests and for heartbeat)
+*/
+type operations = {
+  enqueueEvent: EventCollector.enqueueEvent,
+  translatePending: unit => promise<unit>,
+}
+
+/**
+Module type produced by `Platform.OutboundTranslationSlice.Make(Spec)`.
+
+@example
+```rescript
+module SendTrackingEmailSlice = Platform.OutboundTranslationSlice.Make(SendTrackingEmail)
+let slice = SendTrackingEmailSlice.make(~dcbEventLog=log, ~publishJsons=publishJsonsOutput)
+```
+*/
+type t
+
+module type T = {
+  module Spec: Reventless.OutboundTranslationSlice.Spec
+  module Translation: Reventless.OutboundTranslationSlice.Translation with module Spec := Spec
+  type component = Component.t<t, outputs, operations>
+  let queryDbName: string
+  let make: (
+    ~dcbEventLog: DcbEventLog.component,
+    ~publishJsons: Pulumi.Output.t<CommandTopic.publishJsons>,
+    ~opts: Pulumi.ComponentResource.options=?,
+  ) => component
+}

package/src/components/OutboundTranslationSlice.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. */