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

package/CHANGELOG.md

@@ -3,6 +3,35 @@
 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))
+### Features
+
+* **dcb:** a boundary that cannot derive its scope says so ([db79969](https://github.com/ReventlessDev/reventless-core/commit/db79969df36bd90607425f6a22b4624227cfc4a0))
+
+### BREAKING CHANGES
+
+* `Capability_Messaging_Ses.make` is replaced by
+`Capability_Messaging.make(~name)`, which reads the transport and the address
+from config; the SES module keeps only `emailSender`. A deployment that named its
+sender in code must move it to `platform:messagingEmailSender` or the deploy is
+refused.
+
+
+
 # 3.0.0-alpha.126 (2026-09-01)
 
 **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.126",
+  "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/DcbScopeInference.res

@@ -130,6 +130,40 @@ let foreignConsumedKeys = (s: sliceShape): array<string> => {
   )
 }
 
+/**
+Which consumed arms cost a slice its partition — the actionable half of the
+"no own partition key" ambiguity.
+
+Rule 1 subtracts `foreignConsumedKeys` from `producedKeys`, so a slice whose only
+produced key is also declared on a consumed arm it does not itself produce is left
+with nothing. In practice that is almost always one mistake: a *lifecycle* arm
+naming the id it is already partitioned by (`ProductAdded({productId})` on a slice
+whose every event carries `productId`), which reads as "this id comes from a
+foreign producer" when it is in fact this slice's own partition.
+
+The ambiguity message can only say a partition was not found. This says which arm
+to delete, which is the whole difference between a diagnostic and a puzzle — so it
+is here, beside the rule that produces the ambiguity, rather than duplicated by
+each surface that reports one.
+
+Returns one entry per produced key that a foreign arm claims, naming those arms.
+Empty when the slice has a partition (nothing to explain) or when the produced
+keys are simply too many (a different ambiguity, answered by `@partitionTag`).
+*/
+let partitionBlockers = (s: sliceShape): array<(string, array<string>)> => {
+  let foreign = foreignConsumedKeys(s)
+  let ownProduced = Set.make()
+  s.produced->Array.forEach(e => ownProduced->Set.add(e.eventType))
+  producedKeys(s)
+  ->Array.filter(k => foreign->Array.includes(k))
+  ->Array.map(k => (
+    k,
+    s.consumed
+    ->Array.filter(e => !(ownProduced->Set.has(e.eventType)) && e->keysOfEvent->Array.includes(k))
+    ->Array.map(e => e.eventType),
+  ))
+}
+
 /**
 Per-slice cross-partition keys for the test harness, which has no global owner
 map: a foreign-read key that is not the slice's own partition is read across
@@ -169,9 +203,16 @@ let infer = (slices: array<sliceShape>): derived => {
       switch produced->Array.filter(k => !(foreign->Array.includes(k))) {
       | [single] => partitionBySlice->Dict.set(s.sliceName, single)
       | [] =>
+        // Name the arms that took the key. Almost always a lifecycle arm
+        // declaring the id the slice is already partitioned by, where the fix is
+        // to drop the field rather than to annotate around it.
+        let blame =
+          partitionBlockers(s)
+          ->Array.map(((key, arms)) => `${arms->Array.join("/")} declares ${key}`)
+          ->Array.join("; ")
         let _ = ambiguities->Array.push((
           s.sliceName,
-          "no own partition key — every produced *Id is read from a foreign producer (pure join?); add an explicit @partitionTag",
+          `no own partition key — every produced *Id is read from a foreign producer (${blame}). If that field is this slice's own partition, remove it from the consumed arm; if the slice really is a pure join, add an explicit @partitionTag`,
         ))
       | many =>
         let _ = ambiguities->Array.push((

package/src/components/DcbScopeInference.res.mjs

@@ -50,6 +50,24 @@ function foreignConsumedKeys(s) {
   }));
 }
 
+function partitionBlockers(s) {
+  let foreign = foreignConsumedKeys(s);
+  let ownProduced = new Set();
+  s.produced.forEach(e => {
+    ownProduced.add(e.eventType);
+  });
+  return producedKeys(s).filter(k => foreign.includes(k)).map(k => [
+    k,
+    s.consumed.filter(e => {
+      if (ownProduced.has(e.eventType)) {
+        return false;
+      } else {
+        return e.idFields.map(tagKeyOf).includes(k);
+      }
+    }).map(e => e.eventType)
+  ]);
+}
+
 function crossPartitionForSlice(s) {
   let foreign = foreignConsumedKeys(s);
   let scalar = commandScalarKeys(s);
@@ -93,12 +111,13 @@ function infer(slices) {
           s.sliceName,
           `multiple candidate partition keys (` + many.join(", ") + `) — add an explicit @partitionTag`
         ]);
-      } else {
-        ambiguities.push([
-          s.sliceName,
-          "no own partition key — every produced *Id is read from a foreign producer (pure join?); add an explicit @partitionTag"
-        ]);
+        return;
       }
+      let blame = partitionBlockers(s).map(param => param[1].join("/") + ` declares ` + param[0]).join("; ");
+      ambiguities.push([
+        s.sliceName,
+        `no own partition key — every produced *Id is read from a foreign producer (` + blame + `). If that field is this slice's own partition, remove it from the consumed arm; if the slice really is a pure join, add an explicit @partitionTag`
+      ]);
       return;
     }
     let single = many[0];
@@ -171,6 +190,7 @@ export {
   consumedKeys,
   commandScalarKeys,
   foreignConsumedKeys,
+  partitionBlockers,
   crossPartitionForSlice,
   infer,
 }

package/src/components/DcbTag.res

@@ -1008,6 +1008,15 @@ The DCB decision-read scope threaded into every StateChangeSlice callback:
 type effectiveScope = {
   crossPartitionTagKeys: array<string>,
   tagKeysByEventType: dict<array<string>>,
+  /** Slices whose partition did not resolve, as `(slice, reason)` — non-empty
+      means the two fields above are the *annotated* fallback, not the derivation. */
+  ambiguities: array<(string, string)>,
+  /** Cross-partition keys the inference found that the fallback does not carry.
+      Non-empty is the harmful case and only that: a reference read silently
+      narrows to its own partition, so a slice decides against events it cannot
+      see and rejects a command whose facts are in the log. Empty (even with
+      ambiguities) means the fallback happens to agree and nothing is lost. */
+  droppedCrossPartitionTagKeys: array<string>,
 }
 
 /**
@@ -1023,6 +1032,12 @@ the runtime decision query cannot diverge from the storage/GSI scope. Before thi
 existed the entry point re-derived scope from annotations alone, silently dropping
 inferred cross-partition reference reads — see
 `docs/analysis/dcb-runtime-scope-annotation-drift.md`.
+
+The fallback reports itself. `ambiguities` says it happened and
+`droppedCrossPartitionTagKeys` says whether it cost anything, so a caller can
+distinguish a fallback that agrees with the derivation from one that quietly
+narrows a reference read — the second is a wrong answer waiting for the first
+command that needs the key, and callers are expected to raise it.
 */
 let deriveEffectiveScope = (slices: array<sliceSchemas>): effectiveScope => {
   let producedSchemas = slices->Array.map(s => s.eventSchema)
@@ -1055,6 +1070,10 @@ let deriveEffectiveScope = (slices: array<sliceSchemas>): effectiveScope => {
   {
     crossPartitionTagKeys: useInferred ? inferred.crossPartitionTagKeys : annotatedCross,
     tagKeysByEventType: useInferred ? inferred.tagKeysByEventType : annotatedTagKeys,
+    ambiguities: inferred.ambiguities,
+    droppedCrossPartitionTagKeys: useInferred
+      ? []
+      : inferred.crossPartitionTagKeys->Array.filter(k => !(annotatedCross->Array.includes(k))),
   }
 }
 

package/src/components/DcbTag.res.mjs

@@ -636,7 +636,9 @@ function deriveEffectiveScope(slices) {
   let useInferred = inferred.ambiguities.length === 0;
   return {
     crossPartitionTagKeys: useInferred ? inferred.crossPartitionTagKeys : annotatedCross,
-    tagKeysByEventType: useInferred ? inferred.tagKeysByEventType : annotatedTagKeys
+    tagKeysByEventType: useInferred ? inferred.tagKeysByEventType : annotatedTagKeys,
+    ambiguities: inferred.ambiguities,
+    droppedCrossPartitionTagKeys: useInferred ? [] : inferred.crossPartitionTagKeys.filter(k => !annotatedCross.includes(k))
   };
 }
 

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/generator/Codegen.res

@@ -608,6 +608,27 @@ let renderComposition = (
     pluginNameToEnvBase(config.name) ++
     "_UI_BUNDLE_URL\"",
   )
+  // The DCB boundary's slices as schemas, outside `Make` because the scope they
+  // determine is a property of the specs and not of any platform. Emitted rather
+  // than hand-listed so a slice added tomorrow is in it: this is the only value
+  // from which the whole boundary's scope can be derived without applying the
+  // functor, which is what lets a test — and the repo's scope check — assert that
+  // it resolves. A per-slice test cannot: one slice never has a boundary.
+  if resolved.stateChangeSlices->Array.length > 0 {
+    lines->Array.push("")
+    lines->Array.push("let dcbSliceSchemas: array<Reventless.DcbTag.sliceSchemas> = [")
+    resolved.stateChangeSlices->Array.forEach(stem =>
+      lines->Array.push(
+        "  {" ++
+        `name: ${stem}.name, ` ++
+        `commandSchema: ${stem}.commandSchema->S.castToUnknown, ` ++
+        `consumedEventSchema: ${stem}.consumedEventSchema->S.castToUnknown, ` ++
+        `eventSchema: ${stem}.eventSchema->S.castToUnknown` ++ "},",
+      )
+    )
+    lines->Array.push("]")
+  }
+
   lines->Array.push("")
   lines->Array.push("module Make = (Platform: ReventlessInfra.Platform.T) => {")
 

package/src/generator/Codegen.res.mjs

@@ -399,6 +399,14 @@ function renderComposition(config, resolved, componentChapters) {
   lines.push("// AUTO-GENERATED — do not edit. Run `npm run generate` to update.");
   lines.push("");
   lines.push("@val external uiBundleUrl: option<string> = \"process.env." + pluginNameToEnvBase(config.name) + "_UI_BUNDLE_URL\"");
+  if (resolved.stateChangeSlices.length !== 0) {
+    lines.push("");
+    lines.push("let dcbSliceSchemas: array<Reventless.DcbTag.sliceSchemas> = [");
+    resolved.stateChangeSlices.forEach(stem => {
+      lines.push("  {" + (`name: ` + stem + `.name, `) + (`commandSchema: ` + stem + `.commandSchema->S.castToUnknown, `) + (`consumedEventSchema: ` + stem + `.consumedEventSchema->S.castToUnknown, `) + (`eventSchema: ` + stem + `.eventSchema->S.castToUnknown`) + "},");
+    });
+    lines.push("]");
+  }
   lines.push("");
   lines.push("module Make = (Platform: ReventlessInfra.Platform.T) => {");
   let push = sectionLines => {

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