@reventlessdev/reventless-spec 3.0.0-alpha.100

package/src/components/StateAnnotations.res

@@ -0,0 +1,97 @@
+/**
+Spec describing the structural annotations declared on the fields of an
+`@schema type state` record. The ppx attaches one of these to the generated
+`stateSchema` whenever a field carries a structural annotation (`@id`,
+`@compositeId`, `@subId`, `@compositeSubId`, `@index`), a visibility
+annotation (`@hidden`, `@summary`), a hierarchical-rendering annotation
+(`@drillTarget`, `@collapsed`), a server-query opt-in annotation
+(`@scan`, `@scanSort`), or a UI-list annotation (`@status`, `@groupBy`).
+Downstream consumers (UI, MCP, codegen) read the
+spec to surface field roles in JSON Schema as `x-reventless-*` extension
+properties.
+
+Each list contains the source field names; `indexes` carries `(fieldName,
+indexName)` pairs where `indexName` is `""` for unnamed `@index` annotations.
+`hidden` lists fields the UI should suppress from summary/list views;
+`summary` lists fields the UI should always include in summary/list views.
+`drillTargets` carries `(fieldName, sliceName)` pairs naming the slice/view
+the UI should navigate to instead of expanding the field inline;
+`drillTargetKeys` carries `(fieldName, keyPath)` pairs for fields whose
+drill-down target is keyed by a sub-path within the array element;
+`collapsed` lists object-typed fields the UI should render as an inline
+summary rather than expanding. `scan` lists fields the type author opted
+into server-side equality filtering on (without a backing index); `scanSort`
+lists fields the type author opted into server-side sorting on. The cost is
+free on the in-memory adapter but is `O(n)` Scan + FilterExpression on
+DynamoDB-backed adapters — the annotation is the explicit signal that the
+read model is small enough or the cost is acceptable.
+*/
+/**
+Declared aggregation for a `@metric`-annotated numeric field. `aggregate` is one
+of `"count"`, `"sum"`, `"avg"` (the UI's dashboard vocabulary); `label` is the
+KPI label, or `""` to let the UI derive one from the field name.
+*/
+type metricSpec = {aggregate: string, label: string}
+
+type stateAnnotationSpec = {
+  ids: array<string>,
+  compositeIds: array<string>,
+  subIds: array<string>,
+  compositeSubIds: array<string>,
+  indexes: array<(string, string)>,
+  hidden: array<string>,
+  summary: array<string>,
+  drillTargets: array<(string, string)>,
+  drillTargetKeys: array<(string, string)>,
+  collapsed: array<string>,
+  scan: array<string>,
+  scanSort: array<string>,
+  /**
+  Fields annotated `@semantic("<id>")` — `(fieldName, semanticId)` pairs. The
+  semantic id is the UI's `AutoSemantics` vocabulary (e.g. `"currency"`,
+  `"geo-lat"`); the PPX can't validate it (the UI owns that vocabulary).
+  `SuryToJsonSchema` emits `x-reventless-semantic` on the named field, which
+  AutoUI reads at `#Annotation` provenance — above its heuristic, below a
+  `ui-hints.json` `fields:` override.
+  */
+  semantic: array<(string, string)>,
+  /**
+  Fields annotated `@metric(...)` — `(fieldName, metricSpec)` pairs.
+  `SuryToJsonSchema` emits `x-reventless-metric: {aggregate, label}` on the named
+  field, which AutoUI folds into the dashboard metric list it already builds from
+  hints — so a plugin gets a Dashboard page from its schema alone.
+  */
+  metric: array<(string, metricSpec)>,
+  /**
+  Field annotated `@status` on the state record (PPX-emitted). `Some(name)`
+  when one such annotation exists; the PPX errors on duplicate `@status`
+  annotations within the same record. Codegen consumes this to populate
+  `queryableDef.statusField` (with a fallback to a field literally named
+  `"status"` when this annotation is absent).
+  */
+  status: option<string>,
+  /**
+  Field annotated `@groupBy` on the state record (PPX-emitted). `Some(name)`
+  when one such annotation exists; the PPX errors on duplicate `@groupBy`
+  annotations within the same record. `SuryToJsonSchema.deriveObjectSchema`
+  emits `x-reventless-group-by: true` on the named field, which the UI's
+  list view reads to render rows in sections keyed on that field.
+  */
+  groupBy: option<string>,
+  /**
+  Component-level visibility hint from `@@reventless.visibility(...)`.
+  `Some("Internal")` when the file-level attribute is `Internal`; `None`
+  (omitted) for the default `Public`. `SuryToJsonSchema.deriveObjectSchema`
+  emits `x-reventless-visibility: "Internal"` on the schema when present —
+  the default case is omitted to keep schemas compact.
+  */
+  visibility: option<string>,
+}
+
+/** Sury metadata ID used to attach a `stateAnnotationSpec` to a state schema. */
+let stateAnnotationsId: S.Metadata.Id.t<stateAnnotationSpec> =
+  S.Metadata.Id.make(~namespace="reventless", ~name="stateAnnotations")
+
+/** Returns the spec attached to a state schema, if any. */
+let getSpec = (schema: S.t<unknown>): option<stateAnnotationSpec> =>
+  S.Metadata.get(schema, ~id=stateAnnotationsId)

package/src/components/StateAnnotations.res.mjs

@@ -0,0 +1,15 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as S from "sury/src/S.res.mjs";
+
+let stateAnnotationsId = S.Metadata.Id.make("reventless", "stateAnnotations");
+
+function getSpec(schema) {
+  return S.Metadata.get(schema, stateAnnotationsId);
+}
+
+export {
+  stateAnnotationsId,
+  getSpec,
+}
+/* stateAnnotationsId Not a pure module */

package/src/components/StateChangeSlice.res

@@ -0,0 +1,131 @@
+/**
+Module types for a DCB write-side state change slice.
+
+A `StateChangeSlice` is the DCB equivalent of an aggregate: it processes
+commands by reading the relevant events from a shared `DcbEventLog`, building
+a `state` (ephemeral read model), and appending new events conditioned
+on no concurrent changes to the same entities.
+
+Plan 02 splits the merged spec into two module types:
+
+- `Spec` — types, identity, schemas. The structural contract.
+- `Behavior` — `state`, `initialState`, `evolve`, `decide`. The state machine.
+
+@example
+```rescript
+// AddCategory.res
+let name = "AddCategory"
+
+type state = {exists: bool, archived: bool}
+let initialState = {exists: false, archived: false}
+
+@schema type consumedEvent =
+  | CategoryAdded
+  | CategoryArchived
+
+let evolve = (state, event) => switch event {
+  | CategoryAdded => {exists: true, archived: false}
+  | CategoryArchived => {...state, archived: true}
+}
+
+@schema type command = AddCategory({categoryId: @s.matches(DcbTag.string) string, name: string})
+@schema type error = CategoryAlreadyExists
+
+@schema type event =
+  | CategoryAdded({categoryId: @s.matches(DcbTag.string) string, name: string})
+
+let decide = (state, command) => switch command {
+  | AddCategory({categoryId, name}) =>
+    if state.exists { Error(CategoryAlreadyExists) }
+    else { Ok([CategoryAdded({categoryId, name})]) }
+}
+```
+*/
+
+/**
+The lean Spec for a StateChangeSlice — types, identity, schemas. State and
+state-evolution functions live in the sibling `Behavior` module type.
+*/
+module type Spec = {
+  /** Logical name of this slice (used as a command topic prefix). */
+  let name: string
+  let moduleUrl: string
+
+  /** Identity type — always `Id.String` for DCB slices. */
+  module Id: Id.T
+
+  /**
+  Events this slice reads to build its decision model (in `evolve`).
+  Only needs the fields required for the decision — no tag annotations needed.
+  May be payload-less for events where only existence matters.
+  Must carry `@schema`.
+  */
+  @schema
+  type consumedEvent
+
+  /** Commands this slice handles. Must carry `@schema`. */
+  @schema
+  type command
+
+  /** Business rule violation errors. Must carry `@schema`. */
+  @schema
+  type error
+
+  /** Events this slice emits (from `decide`). Must carry `@schema` and include tag annotations. */
+  @schema
+  type event
+
+  /** Schema for the command type — used to extract DCB tags for the conditional read. */
+  let commandSchema: S.t<command>
+
+  /** Authorization rule evaluated at the GraphQL resolver entry before any
+      command is dispatched. Auto-injected by `@@reventless.spec` and on
+      structurally-detected inline spec modules — defaults to
+      `AllowAuthenticated`; override at the file/module level with
+      `@@reventless.authorize(<rule>)`. */
+  let commandAuthorization: command => Authorization.permission
+
+  /** Decision-read consistency mode for this slice's optimistic-concurrency
+      retry loop. Auto-injected by `@@reventless.spec` and on
+      structurally-detected inline spec modules — defaults to
+      `EscalateOnRetry` (eventual first, strong on retry); override at the
+      file/module level with `@@reventless.consistency(AlwaysStrong)` (or
+      `AlwaysEventual`). Affects RCU/latency only, never correctness — the
+      conditional append's fence is always evaluated strongly. */
+  let readConsistency: ReadConsistency.t
+}
+
+/**
+The Behavior — pure state machine that decides commands and folds events.
+
+`module Spec: Spec` shares the lean Spec's types so `evolve` references
+`Spec.consumedEvent`, `decide` references `Spec.command`/`Spec.event`/`Spec.error`.
+*/
+module type Behavior = {
+  module Spec: Spec
+
+  /**
+  The ephemeral state built by replaying relevant events.
+  Not persisted — reconstructed for each command by reading from the DCB log.
+  */
+  type state
+
+  /** The initial (empty) state before any events have been applied. */
+  let initialState: state
+
+  /**
+  Folds one consumed event into the state during the read phase.
+  Must be a pure function — no side effects.
+  */
+  let evolve: (state, Spec.consumedEvent) => state
+
+  /**
+  Decides what events to append given the current state and the command.
+  Return `Ok(events)` to append, or `Error(error)` to reject the command.
+  */
+  let decide: (state, Spec.command) => result<array<Spec.event>, Spec.error>
+
+  /** File URL of this Behavior module (`import.meta.url`). */
+  let moduleUrl: string
+}
+

package/src/components/StateChangeSlice.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/StateViewSlice.res

@@ -0,0 +1,123 @@
+/**
+Module types for a DCB read-side state view slice.
+
+A `StateViewSlice` is the DCB equivalent of a `ReadModel`: it listens to the
+shared `DcbEventLog` event topic and projects events into a queryable state table
+using the `Projection.action` algebra.
+
+Plan 02 splits the merged spec into two module types:
+
+- `Spec` — types, identity, schemas, infrastructure config. The persisted
+  state contract (matches the ReadModel convention where `state` is in Spec).
+- `Projection` — the single `project` function (and any future projection
+  helpers).
+
+@example
+```rescript
+// CategoriesView.res
+let name = "CategoriesView"
+
+@schema type state = {categoryId: string, name: string, archived: bool}
+
+@schema type consumedEvent =
+  | CategoryAdded({categoryId: string, name: string})
+  | CategoryRenamed({categoryId: string, name: string})
+  | CategoryArchived({categoryId: string})
+
+let project = ({event}) => switch event {
+  | CategoryAdded({categoryId, name}) =>
+    [Set(categoryId, {categoryId, name, archived: false})]
+  | CategoryRenamed({categoryId, name}) =>
+    [Update(categoryId, state => {...state, name})]
+  | CategoryArchived({categoryId}) =>
+    [Update(categoryId, state => {...state, archived: true})]
+}
+```
+*/
+
+/**
+The lean Spec for a StateViewSlice — types, identity, schemas, infra config.
+Per D2, `state` lives here (not in `Projection`) because the projected state
+is the externally-observable contract — schema queried by GraphQL resolvers.
+*/
+module type Spec = {
+  /** Logical name of this view slice (used as a DynamoDB table prefix). */
+  let name: string
+  let moduleUrl: string
+
+  /** The projected state type stored in the view table. Must carry `@schema`. */
+  @schema
+  type state
+
+  /** Sury schema for the state type — generated automatically by `@schema`. */
+  let stateSchema: S.t<state>
+
+  /**
+  Events this view slice projects. Only needs the fields required for the projection —
+  no tag annotations needed. May be payload-less where only existence matters.
+  Must carry `@schema`.
+  */
+  @schema
+  type consumedEvent
+
+  /** Infrastructure configuration (indexes, resolvers). */
+  let config: ReadModel.config
+
+  /** Optional composite-key configuration. `None` for single-key tables. */
+  let subIdConfig: option<ReadModel.subIdConfig<state>>
+
+  /** Authorization rule evaluated at the GraphQL resolver entry before any
+      query is resolved. Auto-injected by `@@reventless.spec` and on
+      structurally-detected inline spec modules — defaults to
+      `AllowAuthenticated`. */
+  let authorization: Authorization.permission
+
+  /** AutoUI visibility hint. Auto-injected by `@@reventless.spec` and on
+      structurally-detected inline spec modules — defaults to
+      `Visibility.Public`; override at the file/module level with
+      `@@reventless.visibility(Internal)` to hide from the AutoUI manifest.
+      Does not affect GraphQL exposure, authorization, or resolver
+      provisioning. */
+  let visibility: Visibility.t
+}
+
+/**
+The envelope a projection receives for each consumed event.
+
+Carries the decoded event alongside the metadata the storage layer already
+holds, so a projection can persist producer time or the acting user without the
+command author having to duplicate that framework state into the event payload.
+
+`meta.time` and `recordedAt` are **different clocks** — pick deliberately:
+
+- `meta.time` — *producer* time, stamped when the command handler created the
+  event. This is the domain-meaningful timestamp (when the order was placed,
+  when it shipped); it is identical across every path.
+- `recordedAt` — *storage* time, when the event was appended to the DCB log. On
+  the AWS (DynamoDB-stream) path this is the authoritative stored column; on the
+  local (topic) path it is stamped at publish, so it may sit a few milliseconds
+  after the stored value. Use it for storage-lag diagnostics, not domain dates.
+*/
+type consumed<'e> = {
+  event: 'e,
+  meta: Message.meta,
+  recordedAt: string,
+}
+
+/**
+The Projection — the pure projection function from consumed events to actions.
+*/
+module type Projection = {
+  module Spec: Spec
+
+  /**
+  Projects one consumed event into read model actions.
+  Receives the event wrapped in a `consumed` envelope (event + `meta` +
+  `recordedAt`); only events declared in `Spec.consumedEvent` — no wildcard needed.
+  */
+  let project: consumed<Spec.consumedEvent> => array<Projection.action<string, Spec.state>>
+
+  /** File URL of this Projection module (`import.meta.url`). */
+  let moduleUrl: string
+}
+

package/src/components/StateViewSlice.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/Task.res

@@ -0,0 +1,62 @@
+/**
+Derives the name used to query a task's S3 bucket.
+
+- `~taskName` — the task's logical name
+- `~bucketName` — optional override; defaults to the task's configured bucket name
+*/
+type queryBucketName = (~taskName: string, ~bucketName: string=?) => string
+
+/**
+An action that a task handler can return after processing a trigger.
+
+- `PublishCommands(aggregateName, commands)` — publish commands to an aggregate
+- `CreateSchedule(schedule)` — create a new recurring or one-time schedule
+- `DeleteSchedule(name)` — delete a schedule by name
+*/
+type taskAction =
+  | PublishCommands(string, array<Message.commandJson>)
+  | CreateSchedule(Schedule.schedule)
+  | DeleteSchedule(string)
+
+/**
+A callback invoked when an S3 object event occurs on a task bucket.
+
+- `~eventName` — the S3 event type (e.g. `"ObjectCreated:Put"`)
+- `~key` — the S3 object key that triggered the event
+
+Returns an array of `taskAction` values to execute after the callback completes.
+*/
+type bucketCallback = (~eventName: string, ~key: string) => promise<array<taskAction>>
+
+/**
+The access mode a task needs for one of its S3 buckets.
+
+- `Read` — task reads from the bucket (e.g. to import catalog data)
+- `Write` — task writes to the bucket (e.g. to export a report)
+- `ReadWrite` — task reads and writes
+*/
+type bucketMode = Read | Write | ReadWrite
+
+/**
+Configuration for one S3 bucket used by a task.
+
+- `bucketName` — optional override; if absent, the framework derives a name
+- `bucketMode` — the required access level
+- `callback` — optional handler triggered by S3 object events
+*/
+type bucketSpec = {bucketName?: string, bucketMode: bucketMode, callback?: bucketCallback}
+
+/** An array of `SideEffect.T` modules executed when this task fires. */
+type sideEffects = array<module(SideEffect.T)>
+
+/**
+The runtime configuration returned by a task's `setup` function.
+
+- `buckets` — optional list of S3 bucket specifications
+- `sideEffects` — optional list of side effect modules to execute
+*/
+type config = {
+  buckets?: array<bucketSpec>,
+  sideEffects?: sideEffects,
+}
+

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