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

package/CHANGELOG.md

@@ -3,6 +3,21 @@
 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
+
+* **core:** annotate event-collector logs with the element's comp ([eda413a](https://github.com/ReventlessDev/reventless-core/commit/eda413ab00eb8bb02b30e029af2d6221e3e9ba75)), closes [#1](https://github.com/ReventlessDev/reventless-core/issues/1)
+
+
 # 3.0.0-alpha.79 (2026-07-17)
 
 **Note:** Version bump only for package @reventlessdev/reventless-spec

package/package.json

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

package/src/LogPrefix.res

@@ -12,6 +12,8 @@ Resolution priority for a comp string like `"Kind(Name)"`:
    - strip trailing `Plugin` (handles `CommandTopic(FooPlugin)`)
    - last dot segment (handles `Extension(Catalog.Products.Ordering)`)
    - first dot segment (handles `ExtensionPoint(Catalog.Products)`)
+4. Longest registered component name that prefixes the inner name (handles
+   kind-suffixed resource names like `EventCollector(CustomersReadModel)`).
 
 `Plugin_Builder` registers every component (and the plugin's self-name) when
 constructing a plugin, so all transformation candidates resolve to a
@@ -100,6 +102,26 @@ let lastDotSegment = (s: string): option<string> => {
 let lookup = (name: string): option<string> =>
   componentPluginRegistry.contents->Dict.get(name)
 
+// Last-resort candidate: the inner name is a registered component name carrying a
+// component-kind suffix (`Customers` + `ReadModel` → `CustomersReadModel`), which is
+// how event-collector resources are named. Longest prefix wins so `OrdersReadModel`
+// resolves via `Orders` rather than a shorter `Order` registered by another plugin.
+// LogPrefix sits below `ComponentType`, so this stays suffix-table-free.
+let longestRegisteredPrefix = (name: string): option<string> =>
+  componentPluginRegistry.contents
+  ->Dict.keysToArray
+  ->Array.reduce(None, (acc, key) =>
+    if key->String.length < name->String.length && name->String.startsWith(key) {
+      switch acc {
+      | Some(best) if best->String.length >= key->String.length => acc
+      | _ => Some(key)
+      }
+    } else {
+      acc
+    }
+  )
+  ->Option.flatMap(lookup)
+
 let resolvePlugin = (~comp=?, ()) =>
   switch comp {
   | Some(c) =>
@@ -118,12 +140,14 @@ let resolvePlugin = (~comp=?, ()) =>
             lastDotSegment(inner),
             firstDotSegment(inner),
           ]
-          candidates->Array.reduce(None, (acc, candidate) =>
+          candidates
+          ->Array.reduce(None, (acc, candidate) =>
             switch acc {
             | Some(_) => acc
             | None => candidate->Option.flatMap(lookup)
             }
           )
+          ->Option.orElse(longestRegisteredPrefix(inner))
         }
       }
     | None => currentPluginName.contents

package/src/LogPrefix.res.mjs

@@ -80,6 +80,16 @@ function lookup(name) {
   return componentPluginRegistry.contents[name];
 }
 
+function longestRegisteredPrefix(name) {
+  return Stdlib_Option.flatMap(Stdlib_Array.reduce(Object.keys(componentPluginRegistry.contents), undefined, (acc, key) => {
+    if (key.length < name.length && name.startsWith(key) && !(acc !== undefined && acc.length >= key.length)) {
+      return key;
+    } else {
+      return acc;
+    }
+  }), lookup);
+}
+
 function resolvePlugin(comp, param) {
   if (comp === undefined) {
     return currentPluginName.contents;
@@ -102,13 +112,13 @@ function resolvePlugin(comp, param) {
     lastDotSegment(inner),
     firstDotSegment(inner)
   ];
-  return Stdlib_Array.reduce(candidates, undefined, (acc, candidate) => {
+  return Stdlib_Option.orElse(Stdlib_Array.reduce(candidates, undefined, (acc, candidate) => {
     if (acc !== undefined) {
       return acc;
     } else {
       return Stdlib_Option.flatMap(candidate, lookup);
     }
-  });
+  }), longestRegisteredPrefix(inner));
 }
 
 function fmtPlainPrefix(comp, param) {
@@ -141,6 +151,7 @@ export {
   firstDotSegment,
   lastDotSegment,
   lookup,
+  longestRegisteredPrefix,
   resolvePlugin,
   fmtPlainPrefix,
   fmtComp,

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 */