@reventlessdev/reventless-spec 3.0.0-alpha.80 → 3.0.0-alpha.81

package/CHANGELOG.md

@@ -3,6 +3,14 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# 3.0.0-alpha.81 (2026-07-26)
+
+### Features
+
+* **auto-ui:** declare command target state via [@target](https://github.com/target)State ([5fc0374](https://github.com/ReventlessDev/reventless-core/commit/5fc03741a8816c57085b86a4ad7d595e3b690193)), closes [#5](https://github.com/ReventlessDev/reventless-core/issues/5)
+* **auto-ui:** declare field semantics + dashboard metrics ([@semantic](https://github.com/semantic), [@metric](https://github.com/metric)) ([d74ff77](https://github.com/ReventlessDev/reventless-core/commit/d74ff7721e18e8638a82931a370a549b304dac94)), closes [#4](https://github.com/ReventlessDev/reventless-core/issues/4)
+
+
 # 3.0.0-alpha.80 (2026-07-22)
 
 ### Features

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reventlessdev/reventless-spec",
-  "version": "3.0.0-alpha.80",
+  "version": "3.0.0-alpha.81",
   "description": "Specifications for Reventless",
   "license": "Apache-2.0",
   "bin": {

package/src/components/Plugin.res

@@ -177,6 +177,16 @@ type commandDef = {
   */
   allowedStates: @s.matches(stringArrayOptionSchema) option<array<string>>,
   /**
+  The single status value this command's handler writes — the command's *to*
+  state, sibling of `allowedStates`' *from* set. Source: the
+  `@targetState("Shipped")` command-variant annotation. `None` (absent
+  annotation) is the back-compat default: AutoUI's board resolver then falls
+  back to its name-stem heuristic. `Some("Shipped")` lets the resolver move a
+  row by a declared transition instead of a guess. js_nullable for JSON safety,
+  same as `allowedStates`.
+  */
+  targetState: @s.matches(stringOptionSchema) option<string>,
+  /**
   Whether this command variant is exposed in the generated API (a non-`@noApi`
   variant of a non-`@noApi` command). Dev tooling badges API-exposed commands in
   the event graph. js_nullable (T | null) so it stays JSON-safe inside the

package/src/components/Plugin.res.mjs

@@ -102,6 +102,7 @@ let commandDefSchema = S.schema(s => ({
   mutationField: s.m(S.string),
   references: s.m(S.array(fieldReferenceSchema)),
   allowedStates: s.m(stringArrayOptionSchema),
+  targetState: s.m(stringOptionSchema),
   apiExposed: s.m(boolOptionSchema)
 }));
 

package/src/components/StateAnnotations.res

@@ -26,6 +26,13 @@ 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>,
@@ -40,6 +47,22 @@ type stateAnnotationSpec = {
   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

package/src/components/StateViewSlice.res

@@ -24,7 +24,7 @@ let name = "CategoriesView"
   | CategoryRenamed({categoryId: string, name: string})
   | CategoryArchived({categoryId: string})
 
-let project = event => switch event {
+let project = ({event}) => switch event {
   | CategoryAdded({categoryId, name}) =>
     [Set(categoryId, {categoryId, name, archived: false})]
   | CategoryRenamed({categoryId, name}) =>
@@ -81,6 +81,29 @@ module type Spec = {
   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.
 */
@@ -89,9 +112,10 @@ module type Projection = {
 
   /**
   Projects one consumed event into read model actions.
-  Receives only events declared in `Spec.consumedEvent` — no wildcard needed.
+  Receives the event wrapped in a `consumed` envelope (event + `meta` +
+  `recordedAt`); only events declared in `Spec.consumedEvent` — no wildcard needed.
   */
-  let project: Spec.consumedEvent => array<Projection.action<string, Spec.state>>
+  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/types/DateTime.res

@@ -0,0 +1,33 @@
+/**
+Marks a `string` state field as an ISO-8601 date-time.
+
+Sury has no string-typed datetime format (`S.datetime` transforms to `Js.Date.t`,
+changing the field's runtime type), so this mirrors the `DcbTag.string`
+precedent: a `S.t<string>` carrying sury metadata that downstream schema walkers
+detect. `SchemaType`/`SuryToJsonSchema` surface it as `format: "date-time"` on
+the field's JSON Schema, which the AutoUI date heuristics key off (CalendarView,
+TimelineView, date-axis charts).
+
+Use on a producer/storage timestamp a projection writes into its state — most
+commonly a `meta.time`-derived field such as `placedAt` / `shippedAt`:
+
+@example
+```rescript
+@schema
+type state = {
+  orderId: string,
+  placedAt: @s.matches(Reventless.DateTime.string) string,
+}
+```
+*/
+
+/** Internal sury metadata ID used to mark a date-time string field. */
+let dateTimeId: S.Metadata.Id.t<bool> = S.Metadata.Id.make(~namespace="reventless", ~name="dateTime")
+
+/** A sury string schema annotated as an ISO-8601 date-time field.
+    Use with `@s.matches(Reventless.DateTime.string)`. */
+let string: S.t<string> = S.string->S.Metadata.set(~id=dateTimeId, true)
+
+/** Whether a field schema carries the date-time marker. */
+let isDateTime = (fieldSchema: S.t<unknown>) =>
+  S.Metadata.get(fieldSchema, ~id=dateTimeId)->Option.isSome

package/src/types/DateTime.res.mjs

@@ -0,0 +1,19 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as S from "sury/src/S.res.mjs";
+import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
+
+let dateTimeId = S.Metadata.Id.make("reventless", "dateTime");
+
+let string = S.Metadata.set(S.string, dateTimeId, true);
+
+function isDateTime(fieldSchema) {
+  return Stdlib_Option.isSome(S.Metadata.get(fieldSchema, dateTimeId));
+}
+
+export {
+  dateTimeId,
+  string,
+  isDateTime,
+}
+/* dateTimeId Not a pure module */