@reventlessdev/reventless-spec 3.0.0-alpha.127 → 3.0.0-alpha.128

package/CHANGELOG.md

@@ -3,6 +3,18 @@
 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.128 (2026-09-04)
+
+### Features
+
+* **notifications:** the wording is a table of values, not a switch ([bfcc939](https://github.com/ReventlessDev/reventless-core/commit/bfcc93940b81060d201fd231447fb14dcf48d80e))
+* **plugin:** a slice publishes which topics it subscribes to ([c689695](https://github.com/ReventlessDev/reventless-core/commit/c6896957ecb636204678222ac5a26b30870439cb))
+* **spec,traits:** an image carries the text that goes with it, and a set's first member is its primary ([e4e5845](https://github.com/ReventlessDev/reventless-core/commit/e4e58458aee7b3db5564727d358a3a9767362ca4))
+* **spec:** a field can say it selects one of the values its row already holds ([2ae50c3](https://github.com/ReventlessDev/reventless-core/commit/2ae50c34deee48508a9f1f39e3eef6a5d2f5df00))
+* **spec:** a field can say its value must not be rendered into a message ([3183f53](https://github.com/ReventlessDev/reventless-core/commit/3183f53a0ae667f794bbd1a3d77acf362dfa8e57))
+* **spec:** a message template renders a payload through its own schema ([39e3f61](https://github.com/ReventlessDev/reventless-core/commit/39e3f6126bd831a316323b4663bc37c50cdfc704))
+
+
 # 3.0.0-alpha.127 (2026-09-02)
 
 * feat(aws)!: the messaging sender is configuration, and a stack can choose to only log ([23b8b4b](https://github.com/ReventlessDev/reventless-core/commit/23b8b4bfe9c70555de4d74266ca686cb427485ca))

package/package.json

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

package/schema/platform-api.graphql

@@ -134,6 +134,7 @@ type Platform_IssuedCommandDef {
 type Platform_OutboundTranslationSliceDef {
   chapter: String
   consumedEventTypes: [String!]!
+  consumedSources: [String!]
   externalSystem: String
   inboundCommandTypes: [String!]!
   name: String!

package/src/components/Plugin.res

@@ -261,6 +261,14 @@ type outboundTranslationSliceDef = {
   externalSystem: @s.matches(stringOptionSchema) option<string>,
   /** Chapter grouping band — see `queryableDef.chapter`. */
   chapter: @s.matches(stringOptionSchema) option<string>,
+  /** The topics this slice subscribes to, as `Spec.sourceNames` declares them —
+      an Aggregate's `Spec.name` or a DCB source name. `Some([])` is the declared
+      default and means this plugin's own DCB log; `None` is an older structure
+      that did not publish the field. A different fact from `consumedEventTypes`,
+      which names event types and not where they came from — two topics carrying
+      an event of the same name are indistinguishable there. Optional so an older
+      reader ignores it. */
+  consumedSources: @s.matches(stringArrayOptionSchema) option<array<string>>,
 }
 
 @schema

package/src/components/Plugin.res.mjs

@@ -172,7 +172,8 @@ let outboundTranslationSliceDefSchema = Sury.$schema(s => ({
   inboundCommandTypes: s.m(Sury.array(Sury.string)),
   targetName: s.m(stringOptionSchema),
   externalSystem: s.m(stringOptionSchema),
-  chapter: s.m(stringOptionSchema)
+  chapter: s.m(stringOptionSchema),
+  consumedSources: s.m(stringArrayOptionSchema)
 }));
 
 let inboundTranslationSliceDefSchema = Sury.$schema(s => ({

package/src/components/Sensitive.res

@@ -0,0 +1,137 @@
+/**
+Marks a field whose value must not be rendered into content a person receives.
+
+`@sensitive` is a *position*, not a type: it says "whatever this field holds, do
+not put it in an outbound message". What the field **is** — an email, a token, a
+reference — is declared separately, exactly as owning and tagging are separate
+facts about one field.
+
+It is declared where the field is declared, and read by anything that composes
+text somebody will read. That is the whole reason it lives here rather than
+beside whichever consumer happens to need it first: a marking that exists in one
+consumer is a marking the rest of the system cannot honour, and the domain model
+is the only place that knows which values are sensitive.
+
+## Absent means "not stated", not "safe"
+
+A reader that misses the marker leaks the value, so the failure is *open* — the
+same shape as `Owner`, and the reason `isFieldSensitive` follows the wrappers
+rather than leaving each consumer to unwrap for itself.
+
+## Some fields need no annotation
+
+A field whose semantic already says it is a contact detail is sensitive without
+anybody writing it down — see `impliedBySemantic`. The annotation is for the
+values a type cannot betray: a token, a note, a reference somebody chose.
+
+`@sensitive` is the authoring form and is sugar over the constructors below, the
+way `@owner` is sugar over `Owner`'s. Write `@s.matches(Sensitive.mark(…))` by
+hand where the ppx shorthand cannot reach — a file with no `@@reventless.spec`
+annotation, or a field whose type is neither `string` nor `option<string>`.
+
+@example
+```rescript
+@schema type event =
+  PasswordReset({
+    @owner customerId: string,
+    @sensitive resetToken: string,
+  })
+```
+*/
+let sensitiveId: S.Metadata.Id.t<bool> = S.Metadata.Id.make(
+  ~namespace="reventless",
+  ~name="sensitive",
+)
+
+/**
+Layers the marker onto a schema that already says something else.
+
+Sensitivity is independent of everything else a field declares — it may equally
+be a DCB tag, an owner, or a reference — but a field carries at most one
+`@s.matches`, so this composes by *wrapping* what the field already resolved to
+rather than replacing it. Replacing would silently drop the field's tag, and a
+dropped tag is a decision read that quietly misses events.
+*/
+let mark = (schema: S.t<'a>): S.t<'a> => schema->S.Metadata.set(~id=sensitiveId, true)
+
+/** A string field that must not be rendered outbound. */
+let string: S.t<string> = S.string->mark
+
+/**
+An `option<string>` field that must not be rendered outbound.
+
+Needed because `@s.matches` on an explicitly-`option`-typed field must supply the
+whole field schema, wrapper included. The `f?: string` form needs nothing extra:
+sury wraps the annotated inner schema itself, and `isFieldSensitive` looks
+through that wrapper either way.
+*/
+let optionString: S.t<option<string>> = S.option(string)
+
+/** Whether this exact schema carries the marker. Does not look through wrappers. */
+let isSensitive = (schema: S.t<unknown>): bool =>
+  S.Metadata.get(schema, ~id=sensitiveId)->Option.getOr(false)
+
+/**
+Whether a *field* is sensitive, wherever inside the field's type the marker sits.
+
+An optional field keeps its marker inside the union wrapper, so a walk reading
+only the outer schema answers `false` for `token?: string` — and here that means
+the value is rendered into a message rather than withheld. Object properties are
+deliberately not followed, for the same reason `Owner` does not follow them: a
+marker on a nested record's field belongs to that field, and attributing it to
+the enclosing one would withhold a whole record because one leaf is private.
+*/
+let isFieldSensitive = (schema: S.t<unknown>): bool =>
+  isSensitive(schema) ||
+    switch schema->Semantic.unwrapOptional {
+    | Some(inner) => isSensitive(inner)
+    | None => false
+    }
+
+/**
+The sensitive fields declared on an object schema, in declaration order.
+
+Threaded to the JSON-Schema walk the way `Owner.fieldNames` is, and for the same
+reason: the IR is shape-driven and sensitivity is not a shape — the field stays a
+plain string either way. Reading it off the sury schema here also keeps it
+available on command and event variants, which carry no annotation spec.
+*/
+let fieldNamesOfProperties = (properties: dict<S.t<unknown>>): array<string> =>
+  properties
+  ->Dict.toArray
+  ->Array.filterMap(((propName, propSchema)) =>
+    isFieldSensitive(propSchema) ? Some(propName) : None
+  )
+
+let fieldNames = (schema: S.t<unknown>): array<string> =>
+  switch schema {
+  | Object({properties}) => fieldNamesOfProperties(properties)
+  | _ => []
+  }
+
+/**
+The sensitive fields of one constructor of a command or event union.
+
+The form a renderer actually needs: it composes text about **one** occurrence, so
+only that variant's fields have anything to say. `OrderPlaced` and
+`PasswordReset` live in the same union and know nothing about each other's
+fields — resolving by TAG here rather than at the call site is what stops a
+template from consulting the wrong arm.
+
+Answers `[]` for an unknown tag and for a payload-less variant, both of which
+mean the same thing to a caller: nothing on this event is withheld.
+*/
+let variantFieldNames = (schema: S.t<unknown>, ~variant: string): array<string> =>
+  schema->Semantic.unionVariant(~variant)->Option.mapOr([], fieldNames)
+
+/**
+The semantics that are sensitive without an annotation.
+
+A contact detail is one whether or not anybody remembered to mark it, so the
+rule is stated once here rather than left to each consumer to remember. Kept
+deliberately short: it holds only the semantics whose *whole meaning* is "how to
+reach a particular person". A postal address or a display name can be sensitive
+in context, and context is exactly what an annotation is for.
+*/
+let impliedBySemantic = (semanticId: string): bool =>
+  semanticId === Semantic.Id.email || semanticId === Semantic.Id.phone

package/src/components/Sensitive.res.mjs

@@ -0,0 +1,74 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Sury from "sury";
+import * as Stdlib_Array from "@rescript/runtime/lib/es6/Stdlib_Array.js";
+import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
+import * as Semantic$Reventless from "../semantic/Semantic.res.mjs";
+
+let sensitiveId = Sury.$Metadata_Id_make("reventless", "sensitive");
+
+function mark(schema) {
+  return Sury.$Metadata_set(schema, sensitiveId, true);
+}
+
+let string = Sury.$Metadata_set(Sury.string, sensitiveId, true);
+
+let optionString = Sury.$option(string);
+
+function isSensitive(schema) {
+  return Stdlib_Option.getOr(Sury.$Metadata_get(schema, sensitiveId), false);
+}
+
+function isFieldSensitive(schema) {
+  if (isSensitive(schema)) {
+    return true;
+  }
+  let inner = Semantic$Reventless.unwrapOptional(schema);
+  if (inner !== undefined) {
+    return isSensitive(inner);
+  } else {
+    return false;
+  }
+}
+
+function fieldNamesOfProperties(properties) {
+  return Stdlib_Array.filterMap(Object.entries(properties), param => {
+    if (isFieldSensitive(param[1])) {
+      return param[0];
+    }
+  });
+}
+
+function fieldNames(schema) {
+  if (schema.type === "object") {
+    return fieldNamesOfProperties(schema.properties);
+  } else {
+    return [];
+  }
+}
+
+function variantFieldNames(schema, variant) {
+  return Stdlib_Option.mapOr(Semantic$Reventless.unionVariant(schema, variant), [], fieldNames);
+}
+
+function impliedBySemantic(semanticId) {
+  if (semanticId === Semantic$Reventless.Id.email) {
+    return true;
+  } else {
+    return semanticId === Semantic$Reventless.Id.phone;
+  }
+}
+
+export {
+  sensitiveId,
+  mark,
+  string,
+  optionString,
+  isSensitive,
+  isFieldSensitive,
+  fieldNamesOfProperties,
+  fieldNames,
+  variantFieldNames,
+  impliedBySemantic,
+}
+/* sensitiveId Not a pure module */

package/src/semantic/Bytes.res

@@ -1,26 +1,9 @@
 /**
-Marks a numeric field as a count of bytes.
+Marks a numeric field as a count of bytes: finite, whole, zero or greater.
 
-## Why `float` and not `int`
-
-A byte count is a whole number and cannot be negative, so `int` is the type it
-wants to be. It is the wrong one here anyway: ReScript's `int` is int32, and
-sury enforces that, so an `int` byte count silently caps at 2,147,483,647 — just
-under 2 GiB. A type whose stated job is file sizes cannot stop at 2 GB.
-
-`float` is a JS number, exact for every integer up to 2^53 — nine petabytes,
-which is enough. The discreteness `int` would have given for free is recovered
-by checking it: the grammar below rejects a fractional byte count, so the type
-still means what `int` meant, minus the ceiling.
-
-The wire is unaffected either way — both are JSON numbers — so this is a source
-choice, not a format one. A field genuinely bounded below 2 GiB can still be
-declared `int` and left unmarked; this type is for the ones that are not.
-
-## The grammar
-
-A finite, whole number, zero or greater. Zero is a real byte count — an empty
-object — so it is accepted.
+`float` rather than `int` because ReScript's `int` is int32, which caps a byte
+count just under 2 GiB; wholeness is recovered by the grammar below. The wire is
+a JSON number either way.
 
 @example
 ```rescript
@@ -52,3 +35,20 @@ let fromFloat = (raw: float): result<t, string> =>
 
 /** The sury schema for a byte-count field. Use with `@s.matches(Reventless.Bytes.schema)`. */
 let schema: S.t<t> = S.float->Semantic.refined(~id=Semantic.Id.bytes, ~check=fromFloat)
+
+/** Binary, because a byte count is what a filesystem reports. */
+let step = 1024.0
+let units = ["B", "KB", "MB", "GB", "TB", "PB"]
+
+/** The count as text — `"512 B"`, `"1.5 KB"`, `"2 MB"`. Locale-independent, the
+    way `Money.format` is, so one value reads the same everywhere. */
+let format = (b: t): string => {
+  let last = Array.length(units) - 1
+  let rec reduce = (value: float, index: int): (float, string) =>
+    value < step || index >= last
+      ? (value, units->Array.getUnsafe(index))
+      : reduce(value /. step, index + 1)
+  let (value, unit) = reduce(b, 0)
+  // One decimal, and only when it says something: 2097152 is "2 MB", not "2.0 MB".
+  Float.toString(Math.round(value *. 10.0) /. 10.0) ++ " " ++ unit
+}

package/src/semantic/Bytes.res.mjs

@@ -31,8 +31,43 @@ function fromFloat(raw) {
 
 let schema = Semantic$Reventless.refined(Sury.float, Semantic$Reventless.Id.bytes, fromFloat);
 
+let units = [
+  "B",
+  "KB",
+  "MB",
+  "GB",
+  "TB",
+  "PB"
+];
+
+function format(b) {
+  let last = units.length - 1 | 0;
+  let reduce = (_value, _index) => {
+    while (true) {
+      let index = _index;
+      let value = _value;
+      if (value < 1024.0 || index >= last) {
+        return [
+          value,
+          units[index]
+        ];
+      }
+      _index = index + 1 | 0;
+      _value = value / 1024.0;
+      continue;
+    };
+  };
+  let match = reduce(b, 0);
+  return (Math.round(match[0] * 10.0) / 10.0).toString() + " " + match[1];
+}
+
+let step = 1024.0;
+
 export {
   fromFloat,
   schema,
+  step,
+  units,
+  format,
 }
 /* schema Not a pure module */

package/src/semantic/CaptionedImage.res

@@ -0,0 +1,100 @@
+/**
+An image the platform stores, together with the text that goes with it.
+
+## Why the text travels with the reference
+
+A picture and the words that describe it are one thing, and holding them apart is
+what let them drift. A view that carried an image field and a caption field
+beside it had to keep the pair in step on every arm of its projection, and the
+one arm that forgot produced a hero image with no alternative text — an
+accessibility hole opened by a projection, not by a missing command.
+
+Inside one value there is no pair to keep in step. It also puts the text where a
+renderer can reach it: a cell renderer is handed a field's key, its schema and
+its value, and never the row — so a caption in a *sibling field* is a caption no
+cell can draw.
+
+## Two texts, not one
+
+They are different things and one does not substitute for the other.
+**`altText` replaces** the image: what a screen reader announces instead of it,
+what shows when it fails to load. **`caption` sits beside** it, visible to
+everyone. `altText: "Blue running shoe, side profile"` and
+`caption: "Front view"` are both correct and neither does the other's job.
+
+A consumer resolves them like this, and the rules are written down because a
+wrong one is silent:
+
+- **the visible caption** is `caption` only. Absent means no visible text.
+- **`alt`** is `altText`, else `caption`, else `""`.
+
+The fallback through `caption` is deliberate and slightly impure. The pure rule —
+`altText` else `""` — makes a host that filled only `caption` emit `alt=""` on
+every photo, which declares them decorative. An imperfect accessible name is
+better than a wrong one.
+
+## No store argument on the field
+
+The store is the host field's name, pluralised, derived by the ppx exactly as it
+is for {!UploadableImage} — and the rule is idempotent, so `productImages:
+array<CaptionedImage.t>` and `categoryImage?: CaptionedImage.t` both derive the
+store their host means. The marker lands on this record rather than on the `ref`
+inside it, which is what lets `StorageRef.getFieldStore` find the store through
+an array wrapper without looking a level deeper.
+
+## A pair, not a general type
+
+Monomorphic on purpose: the ppx matches the *spelling* of a field's type under an
+empty type-argument list, so an `Attachment.t<'ref>` would not match and no store
+would be derived — silently. A document counterpart is a second type for the
+reason {!UploadableImage} and {!UploadableFile} are two: they differ in what the
+value depicts, not in how a reference to it is written. It would carry no
+`altText`, because a document has no visual to replace.
+
+@example
+```rescript
+@schema type state = {
+  productId: string,
+  productImages: array<Reventless.CaptionedImage.t>,
+}
+```
+*/
+
+/** The record itself. No `@schema`: the derived schema would have to name a
+    store, and the store is the host field's — so `forField` is the only way to
+    a schema, and a field the ppx did not reach fails to compile rather than
+    provisioning a store nobody meant. */
+type t = {
+  ref: UploadableImage.t,
+  altText?: string,
+  caption?: string,
+}
+
+/**
+The sury schema for a field holding captioned images out of a named store.
+
+Prefer typing the field `CaptionedImage.t` (or `array<CaptionedImage.t>`) and
+letting the ppx call this. Written by hand it needs the derived store name, which
+defeats the point of the type.
+*/
+let forField = (~plugin: option<string>=?, ~store: string): S.t<t> =>
+  S.schema(s => {
+    ref: s.matches(UploadableImage.forField(~plugin?, ~store)),
+    altText: ?s.matches(S.option(S.string)),
+    caption: ?s.matches(S.option(S.string)),
+  })->Semantic.mark(
+    ~id=Semantic.Id.captionedImage,
+    // The store rides on the record, not on `ref`: a field reader looks through
+    // an optional wrapper and an array element and no further, so a marker one
+    // record deeper would be a store declaration nothing provisions.
+    ~payload=StoredIn({plugin, store, threshold: None}),
+  )
+
+/** The text that replaces the image, by the rule above — `altText`, else the
+    caption, else nothing. One definition, because a second one would be the
+    drift this type exists to remove. */
+let altTextOf = (c: t): option<string> =>
+  switch c.altText {
+  | Some(_) as text => text
+  | None => c.caption
+  }

package/src/semantic/CaptionedImage.res.mjs

@@ -0,0 +1,35 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Sury from "sury";
+import * as Semantic$Reventless from "./Semantic.res.mjs";
+import * as UploadableImage$Reventless from "./UploadableImage.res.mjs";
+
+function forField(plugin, store) {
+  return Semantic$Reventless.mark(Sury.$schema(s => ({
+    ref: s.m(UploadableImage$Reventless.forField(plugin, store)),
+    altText: s.m(Sury.$option(Sury.string)),
+    caption: s.m(Sury.$option(Sury.string))
+  })), Semantic$Reventless.Id.captionedImage, {
+    TAG: "StoredIn",
+    _0: {
+      plugin: plugin,
+      store: store,
+      threshold: undefined
+    }
+  });
+}
+
+function altTextOf(c) {
+  let text = c.altText;
+  if (text !== undefined) {
+    return text;
+  } else {
+    return c.caption;
+  }
+}
+
+export {
+  forField,
+  altTextOf,
+}
+/* sury Not a pure module */

package/src/semantic/Duration.res

@@ -1,29 +1,10 @@
 /**
-Marks an `int` field as a length of time, in **seconds**.
+Marks an `int` field as a length of time, in **seconds** — whole, zero or
+greater. Zero is a real duration.
 
-## Why a scalar, and why seconds are part of the type
-
-The obvious richer design is `{value, unit}`. It is not available here, and the
-reason is the reason this whole set of types is safe to add: a record is an
-*object* on the wire, so adopting it would turn every field that used it into a
-decode failure against events already written. These types are additive
-precisely because they stay scalars. A duration that carries its unit is a
-different type for a different plan, not a later version of this one — widening
-this one would retroactively hand an upcaster obligation to every field that had
-already adopted it.
-
-Seconds, because that is what the renderer reads: it formats `3660` as
-`"1h 1m"`. Milliseconds would be off by a factor of a thousand and would
-render as weeks, which is the same class of silent wrongness `Percent` avoids by
-matching its gauge.
-
-`int` is right here where it was wrong for `Bytes`: int32 seconds is 68 years,
-which no duration field needs to exceed.
-
-## The grammar
-
-A whole number of seconds, zero or greater. Zero is a real duration — an instant
-timeout, a zero-length window.
+Seconds because that is the unit `format` reads; milliseconds would render as
+weeks. A scalar rather than `{value, unit}` so the type stays additive on the
+wire. `int` is safe here — int32 seconds is 68 years.
 
 @example
 ```rescript
@@ -51,3 +32,20 @@ let fromInt = (raw: int): result<t, string> =>
 /** The sury schema for a duration field, in seconds.
     Use with `@s.matches(Reventless.Duration.schema)`. */
 let schema: S.t<t> = S.int->Semantic.refined(~id=Semantic.Id.duration, ~check=fromInt)
+
+let scales = [(86400, "d"), (3600, "h"), (60, "m"), (1, "s")]
+
+/** The duration as text, largest unit first and zero units dropped — `3660` is
+    `"1h 1m"`, `0` is `"0s"`. Locale-independent, the way `Money.format` is. */
+let format = (d: t): string => {
+  let remaining = ref(d < 0 ? 0 : d)
+  let parts = []
+  scales->Array.forEach(((size, suffix)) => {
+    let count = remaining.contents / size
+    if count > 0 {
+      parts->Array.push(Int.toString(count) ++ suffix)
+      remaining := remaining.contents - count * size
+    }
+  })
+  Array.length(parts) == 0 ? "0s" : parts->Array.join(" ")
+}

package/src/semantic/Duration.res.mjs

@@ -1,6 +1,7 @@
 // Generated by ReScript, PLEASE EDIT WITH CARE
 
 import * as Sury from "sury";
+import * as Primitive_int from "@rescript/runtime/lib/es6/Primitive_int.js";
 import * as Semantic$Reventless from "./Semantic.res.mjs";
 
 function fromInt(raw) {
@@ -19,8 +20,50 @@ function fromInt(raw) {
 
 let schema = Semantic$Reventless.refined(Sury.int, Semantic$Reventless.Id.duration, fromInt);
 
+let scales = [
+  [
+    86400,
+    "d"
+  ],
+  [
+    3600,
+    "h"
+  ],
+  [
+    60,
+    "m"
+  ],
+  [
+    1,
+    "s"
+  ]
+];
+
+function format(d) {
+  let remaining = {
+    contents: d < 0 ? 0 : d
+  };
+  let parts = [];
+  scales.forEach(param => {
+    let size = param[0];
+    let count = Primitive_int.div(remaining.contents, size);
+    if (count > 0) {
+      parts.push(count.toString() + param[1]);
+      remaining.contents = remaining.contents - (count * size | 0) | 0;
+      return;
+    }
+  });
+  if (parts.length === 0) {
+    return "0s";
+  } else {
+    return parts.join(" ");
+  }
+}
+
 export {
   fromInt,
   schema,
+  scales,
+  format,
 }
 /* schema Not a pure module */