@reventlessdev/reventless-spec 3.0.0-alpha.136 → 3.0.0-alpha.138

package/CHANGELOG.md

@@ -3,6 +3,30 @@
 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.138 (2026-09-20)
+
+* fix(spec)!: let an explicit partition tag declare an identity the name cannot ([01d82c0](https://github.com/ReventlessDev/reventless-core/commit/01d82c0714a31f31d55c466eae9100cf4dcc85f0))
+
+### BREAKING CHANGES
+
+* a @partitionTag on a field whose name is not *Id / *Ids was
+inert and now takes effect, so such a slice's partition key — and with it its
+storage key, fence and read scope — changes to the annotated field. Nothing else
+moves: the annotation was doing nothing before, so no slice that resolved a key
+resolves a different one.
+
+
+
+# 3.0.0-alpha.137 (2026-09-20)
+
+### Bug Fixes
+
+* **spec:** resolve the drift guard's paths from the module, not the cwd ([7f4d8de](https://github.com/ReventlessDev/reventless-core/commit/7f4d8de896f37ce4a855ecc6a980788f01d0e1c7))
+### Features
+
+* **spec:** enumerate the transparent-string semantics, and check the list against the sources ([995c31c](https://github.com/ReventlessDev/reventless-core/commit/995c31c5eb1a9bdb2ad88d39b2b9a8a5348be0da))
+
+
 # 3.0.0-alpha.136 (2026-09-16)
 
 ### Bug Fixes

package/package.json

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

package/src/components/DcbScopeInference.res

@@ -34,8 +34,22 @@ The three rules (over the representation):
    on `ProductAdded`) are payload ⇒ not indexed ⇒ the sibling-leak GSI write never
    happens.
 */
-/** A `*Id` / `*Ids`-shaped field, identified by name only (no schema, no tag flag). */
-type idField = {name: string, isList: bool}
+/** A field the slice graph treats as an entity identity.
+
+    Normally that is a `*Id` / `*Ids`-shaped name — the convention is the signal,
+    and this module stays schema-agnostic by taking the name alone.
+
+    `byTag` marks the exception: an identity the *name* does not declare, which an
+    adapter recognised from an explicit `@partitionTag`. A domain's own identifier
+    is often not suffixed — `sku`, `isbn`, `vin` — and without this the annotation
+    naming one would be extracted as a hint and then dropped, because `seedOf`
+    only honours a hint already among the produced keys. So the escape hatch would
+    have worked for every field except the ones that need it.
+
+    It is carried rather than folded in because removing the annotation removes
+    the identity, which is exactly what the redundancy check has to know: a hint
+    inference cannot reach without it is never redundant. */
+type idField = {name: string, isList: bool, byTag?: bool}
 
 /** One variant arm: its constructor name and the `*Id` fields it carries. */
 type eventShape = {eventType: string, idFields: array<idField>}

package/src/components/DcbTag.res

@@ -1084,29 +1084,42 @@ which is this module's half of the split.
 */
 let idFieldsOfProperties = (properties: dict<S.t<unknown>>): array<DcbScopeInference.idField> => {
   let isIdName = (name: string) => name->String.endsWith("Ids") || name->String.endsWith("Id")
-  properties
-  ->Dict.toArray
-  ->Array.flatMap(((name, fieldSchema)) =>
+  // An explicit `@partitionTag` declares an identity the naming convention cannot
+  // express — a domain's own identifier is often unsuffixed (`sku`, `isbn`).
+  // Without this the hint is extracted and then ignored, since `seedOf` honours
+  // only a hint already among the produced keys, so the escape hatch would work
+  // for every field except the ones that need it. Flagged, not folded in: taking
+  // the annotation away takes the identity with it, which is what the redundancy
+  // check has to be able to tell.
+  let identity = (name, fieldSchema, isList) =>
     if isIdName(name) {
-      let isList = switch fieldSchema {
-      | Array(_) => true
-      | _ => false
-      }
-      [{DcbScopeInference.name, isList}]
+      Some({DcbScopeInference.name, isList})
+    } else if isPartitionTag(fieldSchema) {
+      Some({DcbScopeInference.name, isList, byTag: true})
     } else {
+      None
+    }
+  properties
+  ->Dict.toArray
+  ->Array.flatMap(((name, fieldSchema)) => {
+    let isList = switch fieldSchema {
+    | Array(_) => true
+    | _ => false
+    }
+    switch identity(name, fieldSchema, isList) {
+    | Some(f) => [f]
+    | None =>
       switch nestedRecordProperties(fieldSchema) {
       | Some((nested, nestedIsList)) =>
         nested
         ->Dict.toArray
-        ->Array.filterMap(((nestedName, _)) =>
-          isIdName(nestedName)
-            ? Some({DcbScopeInference.name: nestedName, isList: nestedIsList})
-            : None
+        ->Array.filterMap(((nestedName, nestedSchema)) =>
+          identity(nestedName, nestedSchema, nestedIsList)
         )
       | None => []
       }
     }
-  )
+  })
 }
 
 /**

package/src/components/DcbTag.res.mjs

@@ -703,31 +703,36 @@ function idFieldsOfProperties(properties) {
       return name.endsWith("Id");
     }
   };
+  let identity = (name, fieldSchema, isList) => {
+    if (isIdName(name)) {
+      return {
+        name: name,
+        isList: isList
+      };
+    } else if (Stdlib_Option.isSome(Sury.$Metadata_get(fieldSchema, dcbPartitionTagId))) {
+      return {
+        name: name,
+        isList: isList,
+        byTag: true
+      };
+    } else {
+      return;
+    }
+  };
   return Object.entries(properties).flatMap(param => {
     let fieldSchema = param[1];
-    let name = param[0];
-    if (isIdName(name)) {
-      let isList;
-      isList = fieldSchema.type === "array";
-      return [{
-          name: name,
-          isList: isList
-        }];
+    let isList;
+    isList = fieldSchema.type === "array";
+    let f = identity(param[0], fieldSchema, isList);
+    if (f !== undefined) {
+      return [f];
     }
     let match = nestedRecordProperties(fieldSchema);
     if (match === undefined) {
       return [];
     }
     let nestedIsList = match[1];
-    return Stdlib_Array.filterMap(Object.entries(match[0]), param => {
-      let nestedName = param[0];
-      if (isIdName(nestedName)) {
-        return {
-          name: nestedName,
-          isList: nestedIsList
-        };
-      }
-    });
+    return Stdlib_Array.filterMap(Object.entries(match[0]), param => identity(param[0], param[1], nestedIsList));
   });
 }
 

package/src/components/DcbValidation.res

@@ -501,29 +501,62 @@ let validatePartitionHintsVsInference = (
   shapes->Array.forEach(s =>
     switch s.partitionHint {
     | Some(hint) if DcbScopeInference.producedKeys(s)->Array.includes(hint) =>
+      // "Without the annotation" has to mean without everything the annotation
+      // brought. A field that is an identity only because it carries the tag
+      // (`byTag`) stops being one when the tag goes, so dropping only the hint
+      // would ask whether inference reaches a key it can no longer see — and
+      // answer yes, reporting a load-bearing annotation as removable.
+      let withoutTag = (e: DcbScopeInference.eventShape) => {
+        ...e,
+        idFields: e.idFields->Array.filter(f => f.byTag != Some(true)),
+      }
+      // A hint naming an identity that exists only because of the annotation is
+      // **necessary**, and fits neither verdict this check was built to give.
+      // Called redundant it would be removed and the key would vanish; called
+      // contradictory it would be "corrected" to whatever name-shaped field
+      // happens to sit beside it — which is the author's choice overruled, not a
+      // mistake found. Both readings come from assuming the field is an identity
+      // either way, which is true only when the name says so.
+      let declaredByTag =
+        s.produced->Array.some(e =>
+          e.idFields->Array.some(f => f.name == hint && f.byTag == Some(true))
+        )
       let unaided = DcbScopeInference.resolvePartitions(
-        shapes->Array.map(o => o.sliceName == s.sliceName ? {...o, partitionHint: None} : o),
+        shapes->Array.map(o =>
+          o.sliceName == s.sliceName
+            ? {
+                ...o,
+                partitionHint: None,
+                produced: o.produced->Array.map(withoutTag),
+                consumed: o.consumed->Array.map(withoutTag),
+              }
+            : o
+        ),
       )
-      switch unaided.partitionBySlice->Dict.get(s.sliceName) {
-      | Some(inferred) if inferred == hint =>
-        redundancies->Array.push({
-          sliceName: s.sliceName,
-          message: `@partitionTag ${hint} is what inference derives without it — the annotation is redundant and can be removed.`,
-        })
-      | Some(inferred) =>
-        contradictions->Array.push({
-          sliceName: s.sliceName,
-          message: `@partitionTag names ${hint}, but inference derives ${inferred} from the slice graph — ${hint} is read from another entity. Remove the annotation, or move it to ${inferred}.`,
-        })
-      | None =>
-        let candidates = unaided.candidatesBySlice->Dict.get(s.sliceName)->Option.getOr([])
-        if !(candidates->Array.includes(hint)) {
+      if declaredByTag {
+        ()
+      } else {
+        switch unaided.partitionBySlice->Dict.get(s.sliceName) {
+        | Some(inferred) if inferred == hint =>
+          redundancies->Array.push({
+            sliceName: s.sliceName,
+            message: `@partitionTag ${hint} is what inference derives without it — the annotation is redundant and can be removed.`,
+          })
+        | Some(inferred) =>
           contradictions->Array.push({
             sliceName: s.sliceName,
-            message: `@partitionTag names ${hint}, which this slice only reads as a reference to another entity (candidates: ${candidates->Array.join(
-                ", ",
-              )}). Move the annotation to the slice's own key.`,
+            message: `@partitionTag names ${hint}, but inference derives ${inferred} from the slice graph — ${hint} is read from another entity. Remove the annotation, or move it to ${inferred}.`,
           })
+        | None =>
+          let candidates = unaided.candidatesBySlice->Dict.get(s.sliceName)->Option.getOr([])
+          if !(candidates->Array.includes(hint)) {
+            contradictions->Array.push({
+              sliceName: s.sliceName,
+              message: `@partitionTag names ${hint}, which this slice only reads as a reference to another entity (candidates: ${candidates->Array.join(
+                  ", ",
+                )}). Move the annotation to the slice's own key.`,
+            })
+          }
         }
       }
     | _ => ()

package/src/components/DcbValidation.res.mjs

@@ -437,14 +437,30 @@ function validatePartitionHintsVsInference(shapes) {
     if (!DcbScopeInference$Reventless.producedKeys(s).includes(hint)) {
       return;
     }
+    let withoutTag = e => ({
+      eventType: e.eventType,
+      idFields: e.idFields.filter(f => Primitive_object.notequal(f.byTag, true))
+    });
+    let declaredByTag = s.produced.some(e => e.idFields.some(f => {
+      if (f.name === hint) {
+        return Primitive_object.equal(f.byTag, true);
+      } else {
+        return false;
+      }
+    }));
     let unaided = DcbScopeInference$Reventless.resolvePartitions(shapes.map(o => {
       if (o.sliceName !== s.sliceName) {
         return o;
       }
       let newrecord = {...o};
       newrecord.partitionHint = undefined;
+      newrecord.produced = o.produced.map(withoutTag);
+      newrecord.consumed = o.consumed.map(withoutTag);
       return newrecord;
     }));
+    if (declaredByTag) {
+      return;
+    }
     let inferred = unaided.partitionBySlice[s.sliceName];
     if (inferred !== undefined) {
       if (inferred === hint) {

package/src/semantic/Semantic.res

@@ -113,6 +113,50 @@ module Id = {
   let geolocation = "geolocation"
 }
 
+/** One transparent-string semantic: a `semantic/` module whose `type t` is a
+    bare `string`. */
+type brandedString = {
+  moduleName: string,
+  /** The `Id` values of this module carry. Not derivable from the module name —
+      `CalendarDate` carries `date`. */
+  id: string,
+  /** Whether the module exposes the `let schema` that sury-ppx resolves `X.t`
+      to by convention. The `false`s build theirs from a function taking
+      arguments (`forStore` / `forField` / `forCollection`), so such a field
+      always carries an explicit `@s.matches` and there is no name a pass could
+      derive. Offering one as a plain type pick emits code that does not
+      compile. */
+  hasDerivableSchema: bool,
+}
+
+/** Every transparent-string semantic, so a consumer can ask what they are
+    instead of transcribing the set.
+
+    A check written against the literal `string` keyword sees only the brand and
+    refuses the field, which would make declaring a semantic cost the field
+    whatever that check gates — so a pass that must leave these alone needs the
+    set, not a guess. It cannot be guessed from the names: `Money.t` is a record,
+    `Duration.t` an int, `Percent.t` and `Bytes.t` floats, and all four are
+    deliberately absent.
+
+    Both facts here are computable from the sources, and `SemanticBrandedStringsTest`
+    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},
+]
+
 let semanticId: S.Metadata.Id.t<t> = S.Metadata.Id.make(~namespace="reventless", ~name="semantic")
 
 /** Mark a schema as carrying a semantic. */

package/src/semantic/Semantic.res.mjs

@@ -4,25 +4,49 @@ 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";
 
+let dateTime = "dateTime";
+
+let date = "date";
+
+let storageRef = "storageRef";
+
+let uploadableImage = "uploadableImage";
+
+let uploadableFile = "uploadableFile";
+
+let imageRef = "imageRef";
+
+let fileRef = "fileRef";
+
+let memberRef = "memberRef";
+
+let email = "email";
+
+let phone = "phone";
+
+let url = "url";
+
+let color = "color";
+
 let Id = {
-  dateTime: "dateTime",
-  date: "date",
+  dateTime: dateTime,
+  date: date,
   reference: "reference",
-  storageRef: "storageRef",
+  storageRef: storageRef,
   offload: "offload",
-  uploadableImage: "uploadableImage",
-  uploadableFile: "uploadableFile",
-  imageRef: "imageRef",
-  fileRef: "fileRef",
+  uploadableImage: uploadableImage,
+  uploadableFile: uploadableFile,
+  imageRef: imageRef,
+  fileRef: fileRef,
   captionedImage: "captionedImage",
-  memberRef: "memberRef",
-  email: "email",
-  phone: "phone",
-  url: "url",
+  memberRef: memberRef,
+  email: email,
+  phone: phone,
+  url: url,
   percent: "percent",
   bytes: "bytes",
   duration: "duration",
-  color: "color",
+  color: color,
   money: "money",
   dateRange: "dateRange",
   geoPoint: "geoPoint",
@@ -30,6 +54,69 @@ let Id = {
   geolocation: "geolocation"
 };
 
+let brandedStrings = [
+  {
+    moduleName: "DateTime",
+    id: dateTime,
+    hasDerivableSchema: true
+  },
+  {
+    moduleName: "CalendarDate",
+    id: date,
+    hasDerivableSchema: true
+  },
+  {
+    moduleName: "Email",
+    id: email,
+    hasDerivableSchema: true
+  },
+  {
+    moduleName: "Phone",
+    id: phone,
+    hasDerivableSchema: true
+  },
+  {
+    moduleName: "Url",
+    id: url,
+    hasDerivableSchema: true
+  },
+  {
+    moduleName: "Color",
+    id: color,
+    hasDerivableSchema: true
+  },
+  {
+    moduleName: "FileRef",
+    id: fileRef,
+    hasDerivableSchema: true
+  },
+  {
+    moduleName: "ImageRef",
+    id: imageRef,
+    hasDerivableSchema: true
+  },
+  {
+    moduleName: "MemberRef",
+    id: memberRef,
+    hasDerivableSchema: false
+  },
+  {
+    moduleName: "StorageRef",
+    id: storageRef,
+    hasDerivableSchema: false
+  },
+  {
+    moduleName: "UploadableFile",
+    id: uploadableFile,
+    hasDerivableSchema: false
+  },
+  {
+    moduleName: "UploadableImage",
+    id: uploadableImage,
+    hasDerivableSchema: false
+  }
+];
+
 let semanticId = Sury.$Metadata_Id_make("reventless", "semantic");
 
 function mark(schema, id, payloadOpt) {
@@ -129,6 +216,7 @@ function has(fieldSchema, id) {
 
 export {
   Id,
+  brandedStrings,
   semanticId,
   mark,
   refined,