@reventlessdev/reventless-spec 3.0.0-alpha.140 → 3.0.0-alpha.142

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.142 (2026-09-22)
+
+### Features
+
+* **spec:** every semantic type says how to write a value ([b661296](https://github.com/ReventlessDev/reventless-core/commit/b661296c1b7c94109e2187efdf48f5643c507f28))
+
+
+# 3.0.0-alpha.141 (2026-09-21)
+
+### Bug Fixes
+
+* **deps:** update rescript to 12.3.1 ([ea1ce37](https://github.com/ReventlessDev/reventless-core/commit/ea1ce377297640f6d0d360e6c84c778d59ecbcc5))
+* **deps:** update sury to 11.0.0 ([8715b22](https://github.com/ReventlessDev/reventless-core/commit/8715b22b33856c46ba57518aad151065c123a995))
+
+
 # 3.0.0-alpha.140 (2026-09-21)
 
 * feat(spec)!: typed projection keys ([fc6a018](https://github.com/ReventlessDev/reventless-core/commit/fc6a01811ba788f3289e84a435a09f77fa627e1a))

package/README.md

@@ -96,7 +96,7 @@ Then register it as a ReScript dependency in `rescript.json`:
 }
 ```
 
-Requires ReScript `^12.3.0` (peer dependency).
+Requires ReScript `^12.3.1` (peer dependency).
 
 ## Links
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reventlessdev/reventless-spec",
-  "version": "3.0.0-alpha.140",
+  "version": "3.0.0-alpha.142",
   "description": "Specifications for Reventless",
   "license": "Apache-2.0",
   "bin": {
@@ -23,17 +23,17 @@
   },
   "dependencies": {
     "jsonschema2graphql": "1.1.1",
-    "sury": "11.0.0-rc.2",
-    "sury-ppx": "11.0.0-rc.2",
+    "sury": "11.0.0",
+    "sury-ppx": "11.0.0",
     "yaml": "^2.8.3",
-    "@reventlessdev/rescript-node": "2.0.0-alpha.12"
+    "@reventlessdev/rescript-node": "2.0.0-alpha.13"
   },
   "devDependencies": {
-    "rescript": "12.3.0",
-    "@reventlessdev/rescript-jest": "1.0.0-alpha.10"
+    "rescript": "12.3.1",
+    "@reventlessdev/rescript-jest": "1.0.0-alpha.11"
   },
   "peerDependencies": {
-    "rescript": "12.3.0"
+    "rescript": "^12.3.1"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org"

package/src/components/DcbTag.res.mjs

@@ -54,7 +54,7 @@ function stringForKey(key) {
   return markForKey(Sury.string, key);
 }
 
-let int = Sury.$Metadata_set(Sury.int, dcbTagId, true);
+let int = Sury.$Metadata_set(Sury.int32, dcbTagId, true);
 
 let partition = markPartition(Sury.string);
 
@@ -88,7 +88,7 @@ let derivedPartitionTagSchema = Sury.union([
   })),
   Sury.$schema(s => ({
     TAG: "ByEventType",
-    _0: s.m(Sury.dict(Sury.string))
+    _0: s.m(Sury.record(Sury.string))
   }))
 ]);
 

package/src/components/Plugin.res.mjs

@@ -61,7 +61,7 @@ let menuEntrySchema = Sury.$schema(s => ({
   label: s.m(Sury.string),
   icon: s.m(Sury.$option(Sury.string)),
   group: s.m(Sury.$option(Sury.string)),
-  sortOrder: s.m(Sury.int)
+  sortOrder: s.m(Sury.int32)
 }));
 
 let pageManifestEntrySchema = Sury.$schema(s => ({
@@ -100,7 +100,7 @@ let commandDefSchema = Sury.$schema(s => ({
   allowedStates: s.m(Sury.$option(Sury.array(Sury.string))),
   targetState: s.m(Sury.$option(Sury.string)),
   allowedStatesSource: s.m(Sury.$option(Sury.string)),
-  apiExposed: s.m(Sury.$option(Sury.bool)),
+  apiExposed: s.m(Sury.$option(Sury.boolean)),
   requiredAccess: s.m(Sury.$option(Sury.array(Sury.string))),
   ownerField: s.m(Sury.$option(Sury.string))
 }));
@@ -118,7 +118,7 @@ let queryableDefSchema = Sury.$schema(s => ({
   ownerField: s.m(Sury.$option(Sury.string)),
   retiredField: s.m(Sury.$option(Sury.string)),
   retiredValues: s.m(Sury.$option(Sury.array(Sury.string))),
-  namedWhenRetired: s.m(Sury.$option(Sury.bool)),
+  namedWhenRetired: s.m(Sury.$option(Sury.boolean)),
   visibility: s.m(Sury.$option(Sury.string)),
   chapter: s.m(Sury.$option(Sury.string)),
   singleQueryField: s.m(Sury.$option(Sury.string)),

package/src/components/TraitCertificate.res.mjs

@@ -5,7 +5,7 @@ import * as Util_Sury$Reventless from "../util/Util_Sury.res.mjs";
 
 let assertionSchema = Sury.$schema(s => ({
   name: s.m(Sury.string),
-  passed: s.m(Sury.bool)
+  passed: s.m(Sury.boolean)
 }));
 
 let schema = Sury.$schema(s => ({
@@ -15,8 +15,8 @@ let schema = Sury.$schema(s => ({
   host: s.m(Sury.string),
   suite: s.m(Sury.string),
   assertions: s.m(Sury.array(assertionSchema)),
-  passed: s.m(Sury.int),
-  failed: s.m(Sury.int)
+  passed: s.m(Sury.int32),
+  failed: s.m(Sury.int32)
 }));
 
 function verified(certificate) {

package/src/components/TraitManifest.res.mjs

@@ -6,7 +6,7 @@ import * as Util_Sury$Reventless from "../util/Util_Sury.res.mjs";
 
 let configFieldSchema = Sury.$schema(s => ({
   name: s.m(Sury.string),
-  required: s.m(Sury.bool)
+  required: s.m(Sury.boolean)
 }));
 
 let schema = Sury.$schema(s => ({
@@ -16,7 +16,7 @@ let schema = Sury.$schema(s => ({
   license: s.m(Sury.string),
   capabilities: s.m(Sury.array(Sury.string)),
   config: s.m(Sury.array(configFieldSchema)),
-  scaffolded: s.m(Sury.bool)
+  scaffolded: s.m(Sury.boolean)
 }));
 
 function render(manifest) {

package/src/generator/PlatformGenerator.res.mjs

@@ -1,6 +1,6 @@
 // Generated by ReScript, PLEASE EDIT WITH CARE
 
-import * as S from "sury/src/S.res.mjs";
+import * as Sury from "sury";
 import * as Yaml from "yaml";
 import * as Nodefs from "node:fs";
 import * as Nodepath from "node:path";
@@ -73,7 +73,7 @@ if (manifestArg === "") {
             console.log(`Read: ` + pluginName + ` — ` + path + ` (via ` + PlatformManifests$Reventless.describeVia(param.via) + `)`);
             let manifest;
             try {
-              manifest = S.parseOrThrow(JSON.parse(Nodefs.readFileSync(path, "utf8")), CapabilityManifest$Reventless.schema);
+              manifest = Sury.parseOrThrow(JSON.parse(Nodefs.readFileSync(path, "utf8")), CapabilityManifest$Reventless.schema);
             } catch (exn) {
               fail(`could not parse ` + path + ` as a capability manifest`);
               manifest = {

package/src/semantic/Bytes.res.mjs

@@ -29,7 +29,7 @@ function fromFloat(raw) {
   }
 }
 
-let schema = Semantic$Reventless.refined(Sury.float, Semantic$Reventless.Id.bytes, fromFloat);
+let schema = Semantic$Reventless.refined(Sury.number, Semantic$Reventless.Id.bytes, fromFloat);
 
 let units = [
   "B",

package/src/semantic/CalendarDate.res

@@ -40,7 +40,7 @@ external toString: t => string = "%identity"
 
 // Sury's rule, held once. `fromString` runs it rather than restating it, and
 // `schema` is built from `fromString`, so there is exactly one grammar here.
-let grammar: S.t<string> = S.isoDate
+let grammar: S.t<string> = (S.isoDate :> S.t<string>)
 
 /** Validate a raw string as an ISO-8601 calendar day, saying why when it is not one. */
 let fromString = (raw: string): result<t, string> =>

package/src/semantic/CalendarDate.res.mjs

@@ -1,6 +1,5 @@
 // Generated by ReScript, PLEASE EDIT WITH CARE
 
-import * as S from "sury/src/S.res.mjs";
 import * as Sury from "sury";
 import * as Semantic$Reventless from "./Semantic.res.mjs";
 
@@ -9,7 +8,7 @@ let grammar = Sury.isoDate;
 function fromString(raw) {
   let value;
   try {
-    value = S.parseOrThrow(raw, grammar);
+    value = Sury.parseOrThrow(raw, grammar);
   } catch (exn) {
     return {
       TAG: "Error",

package/src/semantic/DateTime.res

@@ -3,14 +3,14 @@ Marks a `string` field as an ISO-8601 instant.
 
 ## The grammar
 
-Sury's `S.isoDateTime`, and nothing added — the same rule the branded scalars
+Sury's `S.utcDateTime`, and nothing added — the same rule the branded scalars
 follow. `S.datetime` is the other binding and is not this one: it *transforms* to
 `Js.Date.t`, changing the field's runtime type, where this keeps the string the
 projection wrote.
 
 ## UTC only
 
-`S.isoDateTime` accepts a `Z` instant and rejects an offset — `2026-03-02T09:00:00+01:00`
+`S.utcDateTime` accepts a `Z` instant and rejects an offset — `2026-03-02T09:00:00+01:00`
 and a bare `2026-03-02T09:00:00` both fail. That is stricter than RFC 3339 and it
 is the strictness worth adopting: every instant the framework produces comes from
 `Message.nowAsISOString`, which is always `Z`. "Instants are stored in UTC" is a
@@ -48,7 +48,7 @@ external toString: t => string = "%identity"
 
 // Sury's rule, held once. `fromString` runs it rather than restating it, and
 // `schema` is built from `fromString`, so there is exactly one grammar here.
-let grammar: S.t<string> = S.isoDateTime
+let grammar: S.t<string> = (S.utcDateTime :> S.t<string>)
 
 /** Validate a raw string as a UTC ISO-8601 instant, saying why when it is not one. */
 let fromString = (raw: string): result<t, string> =>

package/src/semantic/DateTime.res.mjs

@@ -1,16 +1,15 @@
 // Generated by ReScript, PLEASE EDIT WITH CARE
 
-import * as S from "sury/src/S.res.mjs";
 import * as Sury from "sury";
 import * as Primitive_float from "@rescript/runtime/lib/es6/Primitive_float.js";
 import * as Semantic$Reventless from "./Semantic.res.mjs";
 
-let grammar = Sury.isoDateTime;
+let grammar = Sury.utcDateTime;
 
 function fromString(raw) {
   let value;
   try {
-    value = S.parseOrThrow(raw, grammar);
+    value = Sury.parseOrThrow(raw, grammar);
   } catch (exn) {
     return {
       TAG: "Error",

package/src/semantic/Duration.res.mjs

@@ -18,7 +18,7 @@ function fromInt(raw) {
   }
 }
 
-let schema = Semantic$Reventless.refined(Sury.int, Semantic$Reventless.Id.duration, fromInt);
+let schema = Semantic$Reventless.refined(Sury.int32, Semantic$Reventless.Id.duration, fromInt);
 
 let scales = [
   [

package/src/semantic/Email.res

@@ -37,7 +37,7 @@ external toString: t => string = "%identity"
 
 // Sury's check, held once. `fromString` runs it rather than restating it, and
 // `schema` is built from `fromString`, so there is exactly one grammar here.
-let grammar: S.t<string> = S.email
+let grammar: S.t<string> = (S.email :> S.t<string>)
 
 /** Validate a raw string as an email address, saying why when it is not one. */
 let fromString = (raw: string): result<t, string> =>

package/src/semantic/Email.res.mjs

@@ -1,6 +1,5 @@
 // Generated by ReScript, PLEASE EDIT WITH CARE
 
-import * as S from "sury/src/S.res.mjs";
 import * as Sury from "sury";
 import * as Semantic$Reventless from "./Semantic.res.mjs";
 
@@ -9,7 +8,7 @@ let grammar = Sury.email;
 function fromString(raw) {
   let value;
   try {
-    value = S.parseOrThrow(raw, grammar);
+    value = Sury.parseOrThrow(raw, grammar);
   } catch (exn) {
     return {
       TAG: "Error",

package/src/semantic/GeoPoint.res.mjs

@@ -48,12 +48,12 @@ function validateLng(raw) {
   }
 }
 
-let latSchema = S.refine(Sury.float, raw => {
+let latSchema = S.refine(Sury.number, raw => {
   let match = validateLat(raw);
   return match.TAG === "Ok";
 }, "expected a latitude in -90…90", undefined);
 
-let lngSchema = S.refine(Sury.float, raw => {
+let lngSchema = S.refine(Sury.number, raw => {
   let match = validateLng(raw);
   return match.TAG === "Ok";
 }, "expected a longitude in -180…180", undefined);

package/src/semantic/Money.res

@@ -91,7 +91,7 @@ let validateAmount = (amount: float): result<float, string> =>
     The check sits on the field rather than on the pair because wholeness is a
     property of the amount: it does not need the currency, and a rule placed
     where it needs nothing else is a rule that cannot be read wrong. (A
-    record-level refinement is available — sury 11.0.0-rc.2 compiles one
+    record-level refinement is available — sury 11 compiles one
     correctly, where 11-alpha hoisted the result object above the field reads and
     threw `Cannot access 'v0' before initialization` — it is simply not what this
     check wants.) */

package/src/semantic/Money.res.mjs

@@ -28,7 +28,7 @@ function validateAmount(amount) {
   }
 }
 
-let amountSchema = S.refine(Sury.float, amount => {
+let amountSchema = S.refine(Sury.number, amount => {
   let match = validateAmount(amount);
   return match.TAG === "Ok";
 }, "expected a monetary amount", undefined);

package/src/semantic/Offload.res.mjs

@@ -10,7 +10,7 @@ let offloadedRefSchema = Sury.$schema(s => ({
   store: s.m(Sury.string),
   key: s.m(Sury.string),
   hash: s.m(Sury.string),
-  bytes: s.m(Sury.int)
+  bytes: s.m(Sury.int32)
 }));
 
 let sentinelKey = "$offload";

package/src/semantic/Percent.res.mjs

@@ -24,7 +24,7 @@ function fromFloat(raw) {
   }
 }
 
-let schema = Semantic$Reventless.refined(Sury.float, Semantic$Reventless.Id.percent, fromFloat);
+let schema = Semantic$Reventless.refined(Sury.number, Semantic$Reventless.Id.percent, fromFloat);
 
 function format(p) {
   return p.toString() + "%";

package/src/semantic/Semantic.res

@@ -133,6 +133,11 @@ type brandedString = {
       derive. Offering one as a plain type pick emits code that does not
       compile. */
   hasDerivableSchema: bool,
+  /** A value the module accepts, as the string itself (not as source): a tool
+      writes it as a string literal. An obvious example, never plausible data,
+      because a new scenario starts from it. For the modules without a derivable
+      schema it is a value their schema accepts for any store or collection. */
+  sample: string,
 }
 
 /** Every transparent-string semantic, so a consumer can ask what they are
@@ -149,18 +154,156 @@ type brandedString = {
     recomputes them rather than trusting this list — so adding a module without
     adding it here fails, and so does the ppx's copy drifting from either. */
 let brandedStrings: array<brandedString> = [
-  {moduleName: "DateTime", id: Id.dateTime, hasDerivableSchema: true},
-  {moduleName: "CalendarDate", id: Id.date, hasDerivableSchema: true},
-  {moduleName: "Email", id: Id.email, hasDerivableSchema: true},
-  {moduleName: "Phone", id: Id.phone, hasDerivableSchema: true},
-  {moduleName: "Url", id: Id.url, hasDerivableSchema: true},
-  {moduleName: "Color", id: Id.color, hasDerivableSchema: true},
-  {moduleName: "FileRef", id: Id.fileRef, hasDerivableSchema: true},
-  {moduleName: "ImageRef", id: Id.imageRef, hasDerivableSchema: true},
-  {moduleName: "MemberRef", id: Id.memberRef, hasDerivableSchema: false},
-  {moduleName: "StorageRef", id: Id.storageRef, hasDerivableSchema: false},
-  {moduleName: "UploadableFile", id: Id.uploadableFile, hasDerivableSchema: false},
-  {moduleName: "UploadableImage", id: Id.uploadableImage, hasDerivableSchema: false},
+  {
+    moduleName: "DateTime",
+    id: Id.dateTime,
+    hasDerivableSchema: true,
+    sample: "2024-01-01T00:00:00Z",
+  },
+  {moduleName: "CalendarDate", id: Id.date, hasDerivableSchema: true, sample: "2024-01-01"},
+  {moduleName: "Email", id: Id.email, hasDerivableSchema: true, sample: "ada@example.com"},
+  // 555-0100…0199 is the North American range reserved for fiction.
+  {moduleName: "Phone", id: Id.phone, hasDerivableSchema: true, sample: "+15555550100"},
+  {moduleName: "Url", id: Id.url, hasDerivableSchema: true, sample: "https://example.com"},
+  {moduleName: "Color", id: Id.color, hasDerivableSchema: true, sample: "#1e90ff"},
+  {
+    moduleName: "FileRef",
+    id: Id.fileRef,
+    hasDerivableSchema: true,
+    sample: "https://example.com/example.pdf",
+  },
+  {
+    moduleName: "ImageRef",
+    id: Id.imageRef,
+    hasDerivableSchema: true,
+    sample: "https://example.com/example.png",
+  },
+  {
+    moduleName: "MemberRef",
+    id: Id.memberRef,
+    hasDerivableSchema: false,
+    sample: "/example/example.png",
+  },
+  {
+    moduleName: "StorageRef",
+    id: Id.storageRef,
+    hasDerivableSchema: false,
+    sample: "/example/example.txt",
+  },
+  {
+    moduleName: "UploadableFile",
+    id: Id.uploadableFile,
+    hasDerivableSchema: false,
+    sample: "/example/example.pdf",
+  },
+  {
+    moduleName: "UploadableImage",
+    id: Id.uploadableImage,
+    hasDerivableSchema: false,
+    sample: "/example/example.png",
+  },
+]
+
+/** How a value of a `valueType` is put together, so a tool can offer an input
+    that fits it. */
+type valueShape =
+  /** A number literal. `integer` says whether it is written `3600` or `50.0` —
+      a float field does not accept an int literal. */
+  | Number({integer: bool})
+  /** One of a closed set of codes, each written as the module's constructor. */
+  | Codes({codes: array<string>})
+  /** A value built from named parts: `(part, module or primitive)`. A module
+      names another `semantic/` module (its `sample` fills the part); a primitive
+      is `float`, `int` or `string`. */
+  | Parts({parts: array<(string, string)>})
+
+/** A semantic whose value is not a bare string: how to write one. */
+type valueType = {
+  moduleName: string,
+  shape: valueShape,
+  /** A value, written as ReScript source, fully qualified: what a tool emits.
+      An obvious example, never plausible data. */
+  sample: string,
+  /** How to write one. `$part` is replaced by that part's source: the module's
+      constructor where it returns `t` (`Money.make`), a record literal where the
+      constructor returns `result`, since a test value should not need
+      unwrapping. A `Number` has the one part `$value`, a `Codes` the one part
+      `$code`. */
+  writer: string,
+}
+
+/** Every semantic whose `type t` is not a bare string and which types a field a
+    scenario fills. The type names cannot say how to write one — `Money.t` is a
+    record, `Duration.t` an int — so a tool reads it here instead of guessing.
+
+    `SemanticValueTypesTest` compiles every sample, runs it through its module's
+    schema, and checks `Currency`'s codes against `Currency.all`. */
+let valueTypes: array<valueType> = [
+  {
+    moduleName: "Money",
+    shape: Parts({parts: [("amount", "float"), ("currency", "Currency")]}),
+    // Whole minor units: 1000 is 10.00 EUR.
+    sample: "Reventless.Money.make(~amount=1000.0, ~currency=Reventless.Currency.EUR)",
+    writer: "Reventless.Money.make(~amount=$amount, ~currency=$currency)",
+  },
+  {
+    moduleName: "Currency",
+    shape: Codes({codes: Currency.all->Array.map(Currency.toString)}),
+    sample: "Reventless.Currency.EUR",
+    writer: "Reventless.Currency.$code",
+  },
+  {
+    moduleName: "DateRange",
+    shape: Parts({parts: [("start", "DateTime"), ("end_", "DateTime")]}),
+    sample: `{Reventless.DateRange.start: "2024-01-01T00:00:00Z", end_: "2024-01-02T00:00:00Z"}`,
+    writer: "{Reventless.DateRange.start: $start, end_: $end_}",
+  },
+  {
+    moduleName: "GeoPoint",
+    shape: Parts({parts: [("lat", "float"), ("lng", "float")]}),
+    sample: "{Reventless.GeoPoint.lat: 0.0, lng: 0.0}",
+    writer: "{Reventless.GeoPoint.lat: $lat, lng: $lng}",
+  },
+  {
+    moduleName: "CaptionedImage",
+    // `altText` and `caption` are optional fields; the writer gives both.
+    shape: Parts({
+      parts: [("ref", "UploadableImage"), ("altText", "string"), ("caption", "string")],
+    }),
+    sample: `{Reventless.CaptionedImage.ref: "/example/example.png", altText: "An example image", caption: "An example caption"}`,
+    writer: "{Reventless.CaptionedImage.ref: $ref, altText: $altText, caption: $caption}",
+  },
+  {
+    moduleName: "Duration",
+    shape: Number({integer: true}),
+    // Seconds: one hour.
+    sample: "3600",
+    writer: "$value",
+  },
+  {moduleName: "Percent", shape: Number({integer: false}), sample: "50.0", writer: "$value"},
+  {moduleName: "Bytes", shape: Number({integer: false}), sample: "1024.0", writer: "$value"},
+]
+
+/** `semantic/` modules whose `type t` types a field, but whose shape
+    `valueShape` cannot express yet. `Geolocation.t` is a union of cases with
+    payloads. A tool asks for its value as ReScript source. */
+let valueTypesWithoutWriter: array<string> = ["Geolocation"]
+
+/** `semantic/` modules that are not a field's value: capabilities, helpers and
+    wrappers the ppx applies. Listed so the coverage test can tell a forgotten
+    module from a deliberate omission. */
+let nonValueModules: array<string> = [
+  "Capabilities",
+  "CapabilityNeed",
+  "Geocoding",
+  "IdentityProvider",
+  "Media_Ref",
+  "Messaging",
+  "Offload",
+  "RowImage",
+  "Secrets",
+  "Semantic",
+  "Template",
 ]
 
 let semanticId: S.Metadata.Id.t<t> = S.Metadata.Id.make(~namespace="reventless", ~name="semantic")

package/src/semantic/Semantic.res.mjs

@@ -3,6 +3,7 @@
 import * as S from "sury/src/S.res.mjs";
 import * as Sury from "sury";
 import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
+import * as Currency$Reventless from "./Currency.res.mjs";
 
 let dateTime = "dateTime";
 
@@ -59,65 +60,208 @@ let brandedStrings = [
   {
     moduleName: "DateTime",
     id: dateTime,
-    hasDerivableSchema: true
+    hasDerivableSchema: true,
+    sample: "2024-01-01T00:00:00Z"
   },
   {
     moduleName: "CalendarDate",
     id: date,
-    hasDerivableSchema: true
+    hasDerivableSchema: true,
+    sample: "2024-01-01"
   },
   {
     moduleName: "Email",
     id: email,
-    hasDerivableSchema: true
+    hasDerivableSchema: true,
+    sample: "ada@example.com"
   },
   {
     moduleName: "Phone",
     id: phone,
-    hasDerivableSchema: true
+    hasDerivableSchema: true,
+    sample: "+15555550100"
   },
   {
     moduleName: "Url",
     id: url,
-    hasDerivableSchema: true
+    hasDerivableSchema: true,
+    sample: "https://example.com"
   },
   {
     moduleName: "Color",
     id: color,
-    hasDerivableSchema: true
+    hasDerivableSchema: true,
+    sample: "#1e90ff"
   },
   {
     moduleName: "FileRef",
     id: fileRef,
-    hasDerivableSchema: true
+    hasDerivableSchema: true,
+    sample: "https://example.com/example.pdf"
   },
   {
     moduleName: "ImageRef",
     id: imageRef,
-    hasDerivableSchema: true
+    hasDerivableSchema: true,
+    sample: "https://example.com/example.png"
   },
   {
     moduleName: "MemberRef",
     id: memberRef,
-    hasDerivableSchema: false
+    hasDerivableSchema: false,
+    sample: "/example/example.png"
   },
   {
     moduleName: "StorageRef",
     id: storageRef,
-    hasDerivableSchema: false
+    hasDerivableSchema: false,
+    sample: "/example/example.txt"
   },
   {
     moduleName: "UploadableFile",
     id: uploadableFile,
-    hasDerivableSchema: false
+    hasDerivableSchema: false,
+    sample: "/example/example.pdf"
   },
   {
     moduleName: "UploadableImage",
     id: uploadableImage,
-    hasDerivableSchema: false
+    hasDerivableSchema: false,
+    sample: "/example/example.png"
   }
 ];
 
+let valueTypes = [
+  {
+    moduleName: "Money",
+    shape: {
+      TAG: "Parts",
+      parts: [
+        [
+          "amount",
+          "float"
+        ],
+        [
+          "currency",
+          "Currency"
+        ]
+      ]
+    },
+    sample: "Reventless.Money.make(~amount=1000.0, ~currency=Reventless.Currency.EUR)",
+    writer: "Reventless.Money.make(~amount=$amount, ~currency=$currency)"
+  },
+  {
+    moduleName: "Currency",
+    shape: {
+      TAG: "Codes",
+      codes: Currency$Reventless.all.map(Currency$Reventless.toString)
+    },
+    sample: "Reventless.Currency.EUR",
+    writer: "Reventless.Currency.$code"
+  },
+  {
+    moduleName: "DateRange",
+    shape: {
+      TAG: "Parts",
+      parts: [
+        [
+          "start",
+          "DateTime"
+        ],
+        [
+          "end_",
+          "DateTime"
+        ]
+      ]
+    },
+    sample: `{Reventless.DateRange.start: "2024-01-01T00:00:00Z", end_: "2024-01-02T00:00:00Z"}`,
+    writer: "{Reventless.DateRange.start: $start, end_: $end_}"
+  },
+  {
+    moduleName: "GeoPoint",
+    shape: {
+      TAG: "Parts",
+      parts: [
+        [
+          "lat",
+          "float"
+        ],
+        [
+          "lng",
+          "float"
+        ]
+      ]
+    },
+    sample: "{Reventless.GeoPoint.lat: 0.0, lng: 0.0}",
+    writer: "{Reventless.GeoPoint.lat: $lat, lng: $lng}"
+  },
+  {
+    moduleName: "CaptionedImage",
+    shape: {
+      TAG: "Parts",
+      parts: [
+        [
+          "ref",
+          "UploadableImage"
+        ],
+        [
+          "altText",
+          "string"
+        ],
+        [
+          "caption",
+          "string"
+        ]
+      ]
+    },
+    sample: `{Reventless.CaptionedImage.ref: "/example/example.png", altText: "An example image", caption: "An example caption"}`,
+    writer: "{Reventless.CaptionedImage.ref: $ref, altText: $altText, caption: $caption}"
+  },
+  {
+    moduleName: "Duration",
+    shape: {
+      TAG: "Number",
+      integer: true
+    },
+    sample: "3600",
+    writer: "$value"
+  },
+  {
+    moduleName: "Percent",
+    shape: {
+      TAG: "Number",
+      integer: false
+    },
+    sample: "50.0",
+    writer: "$value"
+  },
+  {
+    moduleName: "Bytes",
+    shape: {
+      TAG: "Number",
+      integer: false
+    },
+    sample: "1024.0",
+    writer: "$value"
+  }
+];
+
+let valueTypesWithoutWriter = ["Geolocation"];
+
+let nonValueModules = [
+  "Capabilities",
+  "CapabilityNeed",
+  "Geocoding",
+  "IdentityProvider",
+  "Media_Ref",
+  "Messaging",
+  "Offload",
+  "RowImage",
+  "Secrets",
+  "Semantic",
+  "Template"
+];
+
 let semanticId = Sury.$Metadata_Id_make("reventless", "semantic");
 
 function mark(schema, id, payloadOpt) {
@@ -257,6 +401,9 @@ function has(fieldSchema, id) {
 export {
   Id,
   brandedStrings,
+  valueTypes,
+  valueTypesWithoutWriter,
+  nonValueModules,
   semanticId,
   mark,
   refined,
@@ -269,4 +416,4 @@ export {
   fieldIdentityKey,
   has,
 }
-/* semanticId Not a pure module */
+/* valueTypes Not a pure module */

package/src/semantic/Template.res.mjs

@@ -1,6 +1,6 @@
 // Generated by ReScript, PLEASE EDIT WITH CARE
 
-import * as S from "sury/src/S.res.mjs";
+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 Stdlib_Result from "@rescript/runtime/lib/es6/Stdlib_Result.js";
@@ -347,7 +347,7 @@ function isWithheld(schema) {
 
 function parseSafely(json, schema) {
   try {
-    return Primitive_option.some(S.parseOrThrow(json, schema));
+    return Primitive_option.some(Sury.parseOrThrow(json, schema));
   } catch (exn) {
     return;
   }
@@ -542,4 +542,4 @@ export {
   renderSource,
   variantSchema,
 }
-/* S Not a pure module */
+/* sury Not a pure module */

package/src/semantic/Url.res

@@ -38,7 +38,7 @@ external toString: t => string = "%identity"
 // to an append-only log, so the address has to survive the round trip as the
 // caller wrote it. `S.uri` is the string-preserving arm — it still rejects what
 // does not parse, and returns exactly what it was given.
-let grammar: S.t<string> = S.uri
+let grammar: S.t<string> = (S.uri :> S.t<string>)
 
 // Schemes are case-insensitive per RFC 3986, and `HTTPS://x` parses fine, so the
 // allowlist has to fold case or it rejects a valid address on a technicality.

package/src/semantic/Url.res.mjs

@@ -1,6 +1,5 @@
 // Generated by ReScript, PLEASE EDIT WITH CARE
 
-import * as S from "sury/src/S.res.mjs";
 import * as Sury from "sury";
 import * as Semantic$Reventless from "./Semantic.res.mjs";
 
@@ -18,7 +17,7 @@ function hasWebScheme(raw) {
 function fromString(raw) {
   let value;
   try {
-    value = S.parseOrThrow(raw, grammar);
+    value = Sury.parseOrThrow(raw, grammar);
   } catch (exn) {
     return {
       TAG: "Error",

package/src/types/AccountsManifest.res.mjs

@@ -1,6 +1,5 @@
 // Generated by ReScript, PLEASE EDIT WITH CARE
 
-import * as S from "sury/src/S.res.mjs";
 import * as Sury from "sury";
 import * as Yaml from "yaml";
 import * as Nodefs from "node:fs";
@@ -25,7 +24,7 @@ function parseString(yamlText) {
   try {
     return {
       TAG: "Ok",
-      _0: S.parseOrThrow(Yaml.parse(yamlText), entriesSchema)
+      _0: Sury.parseOrThrow(Yaml.parse(yamlText), entriesSchema)
     };
   } catch (raw_err) {
     let err = Primitive_exceptions.internalToException(raw_err);

package/src/types/Identity.res.mjs

@@ -15,7 +15,7 @@ let schema = Sury.$schema(s => ({
   userId: s.m(Sury.string),
   username: s.m(Sury.string),
   groups: s.m(Sury.array(Sury.string)),
-  claims: s.m(Sury.$option(Sury.dict(Sury.string))),
+  claims: s.m(Sury.$option(Sury.record(Sury.string))),
   provider: s.m(providerSchema)
 }));
 

package/src/types/Lifecycle.res.mjs

@@ -62,7 +62,7 @@ function entrySchema(_stateSchema) {
   return Sury.$schema(s => ({
     state: s.m(_stateSchema),
     at: s.m(DateTime$Reventless.schema),
-    afterGap: s.m(Sury.$option(Sury.bool))
+    afterGap: s.m(Sury.$option(Sury.boolean))
   }));
 }
 

package/src/types/Message.res.mjs

@@ -16,7 +16,7 @@ let metaSchema = Sury.$schema(s => ({
   causationId: s.m(Sury.$option(Sury.string)),
   traceparent: s.m(Sury.$option(Sury.string)),
   schemaVersion: s.m(Sury.$option(Sury.string)),
-  headers: s.m(Sury.$option(Sury.dict(Sury.string)))
+  headers: s.m(Sury.$option(Sury.record(Sury.string)))
 }));
 
 let contextSchema = Sury.$schema(s => ({
@@ -33,7 +33,7 @@ let commandJsonSchema = Sury.$schema(s => ({
   id: s.m(Sury.string),
   meta: s.m(metaSchema),
   commandJson: s.m(Sury.json),
-  delay: s.m(Sury.$option(Sury.int))
+  delay: s.m(Sury.$option(Sury.int32))
 }));
 
 let fillMissingDefaults = (function(schema, json, scalarFills){

package/src/types/Schedule.res.mjs

@@ -2,15 +2,15 @@
 
 import * as Sury from "sury";
 
-let yearSchema = Sury.int;
+let yearSchema = Sury.int32;
 
-let monthSchema = Sury.int;
+let monthSchema = Sury.int32;
 
-let daySchema = Sury.int;
+let daySchema = Sury.int32;
 
-let hourSchema = Sury.int;
+let hourSchema = Sury.int32;
 
-let minuteSchema = Sury.int;
+let minuteSchema = Sury.int32;
 
 let rateSchema = Sury.union([
   Sury.$schema(s => ({
@@ -23,15 +23,15 @@ let rateSchema = Sury.union([
   })),
   Sury.$schema(s => ({
     TAG: "Minutes",
-    _0: s.m(Sury.int)
+    _0: s.m(Sury.int32)
   })),
   Sury.$schema(s => ({
     TAG: "Hours",
-    _0: s.m(Sury.int)
+    _0: s.m(Sury.int32)
   })),
   Sury.$schema(s => ({
     TAG: "Days",
-    _0: s.m(Sury.int)
+    _0: s.m(Sury.int32)
   })),
   Sury.$schema(s => ({
     TAG: "Daily",

package/src/util/Util_Sury.res

@@ -7,16 +7,19 @@
 // See docs/plans/sury-11-migration.md.
 
 let toJson: ('a, S.t<'a>) => JSON.t = (value, schema) =>
-  value->S.decodeOrThrow(~from=schema, ~to=S.json)
+  value->S.convertOrThrow(~from=schema, ~to=S.json)
 
 // `~space` defaults to compact, matching the removed `reverseConvertToJsonStringOrThrow`.
 let toJsonString = (value: 'a, schema: S.t<'a>, ~space: int=0): string =>
-  value->S.decodeOrThrow(~from=schema, ~to=space == 0 ? S.jsonString : S.jsonStringWithSpace(space))
+  (value->S.convertOrThrow(
+    ~from=schema,
+    ~to=space == 0 ? S.jsonString : S.jsonStringWithSpace(space),
+  ) :> string)
 
 let fromJson: (JSON.t, S.t<'a>) => 'a = (json, schema) => json->S.parseOrThrow(~to=schema)
 
 let fromJsonString: (string, S.t<'a>) => 'a = (str, schema) =>
-  str->S.decodeOrThrow(~from=S.jsonString, ~to=schema)
+  S.JsonString(str)->S.convertOrThrow(~from=S.jsonString, ~to=schema)
 
 // Sury raises `S.Exn`, which carries `RE_EXN_ID: "S.Exn"` and so is not a `JsExn`
 // even though it is a JS Error at runtime — the usual

package/src/util/Util_Sury.res.mjs

@@ -6,18 +6,20 @@ import * as Stdlib_JsExn from "@rescript/runtime/lib/es6/Stdlib_JsExn.js";
 import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
 
 function toJson(value, schema) {
-  return S.decodeOrThrow(value, schema, Sury.json);
+  return S.convertOrThrow(value, schema, undefined, Sury.json);
 }
 
 function toJsonString(value, schema, spaceOpt) {
   let space = spaceOpt !== undefined ? spaceOpt : 0;
-  return S.decodeOrThrow(value, schema, space === 0 ? Sury.jsonString : Sury.jsonStringWithSpace(space));
+  return S.convertOrThrow(value, schema, undefined, space === 0 ? Sury.jsonString : Sury.jsonStringWithSpace(space));
 }
 
-let fromJson = S.parseOrThrow;
+function fromJson(json, schema) {
+  return Sury.parseOrThrow(json, schema);
+}
 
 function fromJsonString(str, schema) {
-  return S.decodeOrThrow(str, Sury.jsonString, schema);
+  return S.convertOrThrow(str, Sury.jsonString, undefined, schema);
 }
 
 function exnMessage(exn, fallbackOpt) {