@reventlessdev/reventless-core 3.0.0-alpha.186 → 3.0.0-alpha.188

package/CHANGELOG.md

@@ -3,6 +3,22 @@
 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.188 (2026-07-28)
+
+**Note:** Version bump only for package @reventlessdev/reventless-core
+
+
+
+
+
+# 3.0.0-alpha.187 (2026-07-28)
+
+### Features
+
+* **spec:** one semantic marker every typed semantic marks itself with ([aa18afc](https://github.com/ReventlessDev/reventless-core/commit/aa18afcf04c8edad9afe27e6fa4261d01e184da7))
+* **spec:** StorageRef — the first semantic type, declared on the field's type ([44f15c3](https://github.com/ReventlessDev/reventless-core/commit/44f15c37de71261d701d18a9f1ada6f481c4a8dc))
+
+
 # 3.0.0-alpha.186 (2026-07-27)
 
 ### Features

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reventlessdev/reventless-core",
-  "version": "3.0.0-alpha.186",
+  "version": "3.0.0-alpha.188",
   "description": "Core package for Reventless framework",
   "license": "Apache-2.0",
   "jest": {
@@ -28,22 +28,22 @@
   "dependencies": {
     "sury": "11.0.0-alpha.4",
     "uuid": "^13.0.0",
-    "@reventlessdev/rescript-effect": "0.1.0-alpha.31",
     "@reventlessdev/rescript-fast-csv": "1.2.0-alpha.14",
-    "@reventlessdev/rescript-jest": "1.0.0-alpha.9",
     "@reventlessdev/rescript-hash-object": "1.2.0-alpha.13",
+    "@reventlessdev/rescript-jest": "1.0.0-alpha.9",
     "@reventlessdev/rescript-node-streams": "1.1.0-alpha.13",
+    "@reventlessdev/rescript-effect": "0.1.0-alpha.31",
     "@reventlessdev/rescript-pulumi-pulumi": "2.3.0-alpha.17",
     "@reventlessdev/rescript-ssh2": "1.1.0-alpha.14",
     "@reventlessdev/rescript-uuid": "1.1.0-alpha.17",
-    "@reventlessdev/reventless-interop": "3.0.0-alpha.29",
-    "@reventlessdev/reventless-spec": "3.0.0-alpha.81",
-    "@reventlessdev/reventless-infra": "3.0.0-alpha.106"
+    "@reventlessdev/reventless-infra": "3.0.0-alpha.107",
+    "@reventlessdev/reventless-spec": "3.0.0-alpha.82",
+    "@reventlessdev/reventless-interop": "3.0.0-alpha.29"
   },
   "devDependencies": {
     "rescript": "12.3.0",
     "sury-ppx": "11.0.0-alpha.2",
-    "@reventlessdev/reventless-ppx": "1.0.0-alpha.56"
+    "@reventlessdev/reventless-ppx": "1.0.0-alpha.58"
   },
   "peerDependencies": {
     "rescript": "12.3.0"

package/src/components/Api/GraphQL_FragmentGenerator.res

@@ -62,6 +62,11 @@ let rec fromSchemaType = (
       collectedTypes->Array.push(`enum ${name} {\n  ${valuesStr}\n}`)
     }
     `${name}${bang}`
+  // GraphQL carries the value's shape, not its meaning: a storage ref is a
+  // String on the wire exactly as it is in the event log. The semantic reaches
+  // the UI through the field's JSON Schema, which is the channel that can
+  // express it.
+  | Semantic(_, inner) => fromSchemaType(~required, ~asInput, inner, collectedTypes, seenTypes)
   | Unknown => `String${bang}`
   }
 }
@@ -171,13 +176,14 @@ let emptyCapability: serverCapability = {filterFields: [], sortFields: []}
 // Convert a SchemaType.schemaType to its GraphQL scalar name (input position).
 // Mirrors the scalar branches of fromSchemaType — kept inline because we don't
 // emit `!`/list wrappers for filter inputs.
-let scalarOfSchemaType = (st: SchemaType.schemaType): string =>
+let rec scalarOfSchemaType = (st: SchemaType.schemaType): string =>
   switch st {
   | ScalarString => "String"
   | ScalarNumber => "Float"
   | ScalarBoolean => "Boolean"
   | ScalarBigInt => "String"
   | EntityId => "ID"
+  | Semantic(_, inner) => scalarOfSchemaType(inner)
   | _ => "String"
   }
 

package/src/components/Api/GraphQL_FragmentGenerator.res.mjs

@@ -71,6 +71,10 @@ function fromSchemaType(_required, _asInputOpt, _st, collectedTypes, seenTypes)
             collectedTypes.push(`enum ` + name$1 + ` {\n  ` + valuesStr + `\n}`);
           }
           return name$1 + bang;
+        case "Semantic" :
+          _st = st._1;
+          _asInputOpt = asInput;
+          continue;
       }
     }
   };
@@ -144,20 +148,28 @@ let emptyCapability = {
   sortFields: emptyCapability_sortFields
 };
 
-function scalarOfSchemaType(st) {
-  if (typeof st === "object") {
-    return "String";
-  }
-  switch (st) {
-    case "ScalarNumber" :
-      return "Float";
-    case "ScalarBoolean" :
-      return "Boolean";
-    case "EntityId" :
-      return "ID";
-    default:
-      return "String";
-  }
+function scalarOfSchemaType(_st) {
+  while (true) {
+    let st = _st;
+    if (typeof st !== "object") {
+      switch (st) {
+        case "ScalarNumber" :
+          return "Float";
+        case "ScalarBoolean" :
+          return "Boolean";
+        case "EntityId" :
+          return "ID";
+        default:
+          return "String";
+      }
+    } else {
+      if (st.TAG !== "Semantic") {
+        return "String";
+      }
+      _st = st._1;
+      continue;
+    }
+  };
 }
 
 function deriveServerCapability(schema) {

package/src/components/Api/SchemaType.res

@@ -9,6 +9,12 @@ type rec schemaType =
   | ArrayOf(schemaType)
   | ObjectRef(string, dict<schemaType>)
   | Enum(string, array<string>)
+  | /** A field whose type carries a semantic the IR has no dedicated shape for.
+        Wraps the shape the value actually has, so every consumer that only cares
+        about shape unwraps and is otherwise unaffected. `DateTime` and `EntityId`
+        are *not* expressed this way: they long predate the generic marker and
+        their JSON Schema `format` output is a published contract. */
+  Semantic(Reventless.Semantic.t, schemaType)
   | Unknown
 
 let isTagged = Reventless.DcbTag.isTagged
@@ -27,6 +33,26 @@ let isIdsFieldName = (name: string): bool => {
 }
 
 let rec fromSury = (~parentName: string, ~fieldName: string, schema: S.t<unknown>): schemaType => {
+  let shape = shapeOf(~parentName, ~fieldName, schema)
+  // Semantics the IR already has a dedicated shape for keep it: `dateTime` and
+  // `reference` are read below via `isDateTime` / `getTarget`, both of which now
+  // consult the generic marker, and their `format` output is a published
+  // contract. Every other semantic rides along as a wrapper, so surfacing a new
+  // one costs a value rather than a branch.
+  switch Reventless.Semantic.get(schema) {
+  | Some({id} as sem)
+    if id !== Reventless.Semantic.Id.dateTime && id !== Reventless.Semantic.Id.reference =>
+    Semantic(sem, shape)
+  | _ => shape
+  }
+}
+
+and shapeOf = (~parentName: string, ~fieldName: string, schema: S.t<unknown>): schemaType => {
+  // Two independent facts, checked independently. A DCB-tagged field is an
+  // entity id because it routes; a reference field is one because it points at
+  // an entity. Neither implies the other — a `@partitionTag` field carries no
+  // reference, and `Reference.toWithoutDcbTag` carries no tag — so collapsing
+  // these into one test would silently reclassify whichever case it dropped.
   if isTagged(schema) || Reventless.Reference.getTarget(schema)->Option.isSome {
     EntityId
   } else {

package/src/components/Api/SchemaType.res.mjs

@@ -4,6 +4,7 @@ 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 DcbTag$Reventless from "@reventlessdev/reventless-spec/src/components/DcbTag.res.mjs";
 import * as DateTime$Reventless from "@reventlessdev/reventless-spec/src/types/DateTime.res.mjs";
+import * as Semantic$Reventless from "@reventlessdev/reventless-spec/src/semantic/Semantic.res.mjs";
 import * as Reference$Reventless from "@reventlessdev/reventless-spec/src/components/Reference.res.mjs";
 
 function isIdFieldName(name) {
@@ -27,6 +28,24 @@ function isIdsFieldName(name) {
 }
 
 function fromSury(parentName, fieldName, schema) {
+  let shape = shapeOf(parentName, fieldName, schema);
+  let sem = Semantic$Reventless.get(schema);
+  if (sem === undefined) {
+    return shape;
+  }
+  let id = sem.id;
+  if (id !== Semantic$Reventless.Id.dateTime && id !== Semantic$Reventless.Id.reference) {
+    return {
+      TAG: "Semantic",
+      _0: sem,
+      _1: shape
+    };
+  } else {
+    return shape;
+  }
+}
+
+function shapeOf(parentName, fieldName, schema) {
   if (DcbTag$Reventless.isTagged(schema) || Stdlib_Option.isSome(Reference$Reventless.getTarget(schema))) {
     return "EntityId";
   }
@@ -156,6 +175,7 @@ export {
   isIdFieldName,
   isIdsFieldName,
   fromSury,
+  shapeOf,
   fromSuryObject,
 }
 /* DcbTag-Reventless Not a pure module */

package/src/components/Api/SuryToJsonSchema.res

@@ -1,6 +1,8 @@
 // Shared utility: convert sury S.t<'a> schemas to JSON Schema objects.
 // Uses SchemaType as the shared intermediate representation.
 
+let log = Logger.fromEnv()
+
 // ── Helpers ──────────────────────────────────────────────────────────────
 
 let str = JSON.Encode.string
@@ -8,6 +10,18 @@ let str = JSON.Encode.string
 let jsonObject = (entries: array<(string, JSON.t)>): JSON.t =>
   JSON.Encode.object(Dict.fromArray(entries))
 
+// An absent plugin means "the declaring plugin's own", which the key's absence
+// says exactly. Writing an empty string instead would make "mine" and "unnamed"
+// indistinguishable to every reader.
+let withOptionalPlugin = (
+  entries: array<(string, JSON.t)>,
+  plugin: option<string>,
+): array<(string, JSON.t)> =>
+  switch plugin {
+  | Some(p) => entries->Array.concat([("plugin", JSON.Encode.string(p))])
+  | None => entries
+  }
+
 // Merge x-reventless-* extension properties from a Reventless.StateAnnotations.stateAnnotationSpec
 // into a property schema (a JSON Schema object). Returns the schema unchanged when the field
 // has no annotations or when the schema is not a JSON object.
@@ -70,7 +84,21 @@ let mergeAnnotations = (
     }
     switch spec.semantic->Array.find(((field, _)) => field === fieldName) {
     | Some((_, semanticId)) =>
-      obj->Dict.set("x-reventless-semantic", JSON.Encode.string(semanticId))
+      // The type wins. A typed declaration is better-sourced than an annotation
+      // — the compiler checked it and it cannot drift from the field's shape —
+      // so an annotation never overwrites one. A field carrying both is the
+      // domain saying two things about one value, which is worth hearing about
+      // rather than resolving in silence.
+      switch obj->Dict.get("x-reventless-semantic") {
+      | Some(fromType) =>
+        if fromType !== JSON.Encode.string(semanticId) {
+          log.warn(
+            ~comp="SuryToJsonSchema",
+            `field "${fieldName}" declares semantic "${semanticId}" by annotation but its type already carries ${fromType->JSON.stringify}; the type wins`,
+          )
+        }
+      | None => obj->Dict.set("x-reventless-semantic", JSON.Encode.string(semanticId))
+      }
     | None => ()
     }
     switch spec.metric->Array.find(((field, _)) => field === fieldName) {
@@ -107,9 +135,50 @@ let rec fromSchemaType = (st: SchemaType.schemaType): JSON.t =>
       ("type", str("string")),
       ("enum", JSON.Encode.array(values->Array.map(JSON.Encode.string))),
     ])
+  | Semantic(sem, inner) => fromSchemaType(inner)->withSemantic(sem)
   | Unknown => jsonObject([("type", str("string"))])
   }
 
+// Attach a type-carried semantic to a field's JSON Schema.
+//
+// This is the type path's emission point, and it is deliberately *not*
+// `mergeAnnotations`: that one is fed by the PPX-collected annotation spec,
+// which the PPX only ever collects on read-model `state` records. This walk is
+// schema-shape-driven and runs over every schema, commands and events included —
+// which is where a declaration like a storage ref has to live, since that is
+// where the value is first accepted.
+//
+// Both paths write the same `x-reventless-semantic` key, on purpose: one wire
+// format, whatever the source. The payload rides in sibling keys so a reader
+// that knows only the bare string still reads it correctly.
+and withSemantic = (fieldSchema: JSON.t, sem: Reventless.Semantic.t): JSON.t =>
+  switch fieldSchema->JSON.Decode.object {
+  | None => fieldSchema
+  | Some(obj) =>
+    obj->Dict.set("x-reventless-semantic", str(sem.id))
+    // The `type` discriminator is what lets a reader tell a type-carried
+    // semantic from an annotated one, and rank it above the annotation
+    // accordingly: the compiler checked this one, and it cannot drift from the
+    // field's shape.
+    obj->Dict.set("x-reventless-semantic-source", str("type"))
+    switch sem.payload {
+    | Plain => ()
+    | ReferenceTo({entity, plugin}) =>
+      obj->Dict.set(
+        "x-reventless-semantic-target",
+        jsonObject(withOptionalPlugin([("entity", str(entity))], plugin)),
+      )
+    | StoredIn({plugin, store}) =>
+      // An absent plugin means "this plugin's own store" — omit the key rather
+      // than writing an empty string, so a reader never has to tell those apart.
+      obj->Dict.set(
+        "x-reventless-semantic-target",
+        jsonObject(withOptionalPlugin([("store", str(store))], plugin)),
+      )
+    }
+    JSON.Encode.object(obj)
+  }
+
 and objectRefToJsonSchema = (
   ~annotations: option<Reventless.StateAnnotations.stateAnnotationSpec>=?,
   fields: dict<SchemaType.schemaType>,

package/src/components/Api/SuryToJsonSchema.res.mjs

@@ -1,9 +1,12 @@
 // Generated by ReScript, PLEASE EDIT WITH CARE
 
 import * as Stdlib_JSON from "@rescript/runtime/lib/es6/Stdlib_JSON.js";
+import * as Logger$ReventlessCore from "../../util/Logger.res.mjs";
 import * as SchemaType$ReventlessCore from "./SchemaType.res.mjs";
 import * as StateAnnotations$Reventless from "@reventlessdev/reventless-spec/src/components/StateAnnotations.res.mjs";
 
+let log = Logger$ReventlessCore.fromEnv();
+
 function str(prim) {
   return prim;
 }
@@ -12,6 +15,17 @@ function jsonObject(entries) {
   return Object.fromEntries(entries);
 }
 
+function withOptionalPlugin(entries, plugin) {
+  if (plugin !== undefined) {
+    return entries.concat([[
+        "plugin",
+        plugin
+      ]]);
+  } else {
+    return entries;
+  }
+}
+
 function mergeAnnotations(fieldSchema, fieldName, spec) {
   let obj = Stdlib_JSON.Decode.object(fieldSchema);
   if (obj === undefined) {
@@ -64,7 +78,15 @@ function mergeAnnotations(fieldSchema, fieldName, spec) {
   }
   let match$3 = spec.semantic.find(param => param[0] === fieldName);
   if (match$3 !== undefined) {
-    obj["x-reventless-semantic"] = match$3[1];
+    let semanticId = match$3[1];
+    let fromType = obj["x-reventless-semantic"];
+    if (fromType !== undefined) {
+      if (fromType !== semanticId) {
+        log.warn("SuryToJsonSchema", undefined, `field "` + fieldName + `" declares semantic "` + semanticId + `" by annotation but its type already carries ` + JSON.stringify(fromType) + `; the type wins`);
+      }
+    } else {
+      obj["x-reventless-semantic"] = semanticId;
+    }
   }
   let match$4 = spec.metric.find(param => param[0] === fieldName);
   if (match$4 !== undefined) {
@@ -167,8 +189,36 @@ function fromSchemaType(st) {
             st._1.map(prim => prim)
           ]
         ]);
+      case "Semantic" :
+        return withSemantic(fromSchemaType(st._1), st._0);
+    }
+  }
+}
+
+function withSemantic(fieldSchema, sem) {
+  let obj = Stdlib_JSON.Decode.object(fieldSchema);
+  if (obj === undefined) {
+    return fieldSchema;
+  }
+  obj["x-reventless-semantic"] = sem.id;
+  obj["x-reventless-semantic-source"] = "type";
+  let match = sem.payload;
+  if (typeof match === "object") {
+    if (match.TAG === "ReferenceTo") {
+      let match$1 = match._0;
+      obj["x-reventless-semantic-target"] = Object.fromEntries(withOptionalPlugin([[
+          "entity",
+          match$1.entity
+        ]], match$1.plugin));
+    } else {
+      let match$2 = match._0;
+      obj["x-reventless-semantic-target"] = Object.fromEntries(withOptionalPlugin([[
+          "store",
+          match$2.store
+        ]], match$2.plugin));
     }
   }
+  return obj;
 }
 
 function objectRefToJsonSchema(annotations, fields) {
@@ -231,12 +281,15 @@ function toJsonSchema(schema) {
 }
 
 export {
+  log,
   str,
   jsonObject,
+  withOptionalPlugin,
   mergeAnnotations,
   fromSchemaType,
+  withSemantic,
   objectRefToJsonSchema,
   deriveObjectSchema,
   toJsonSchema,
 }
-/* SchemaType-ReventlessCore Not a pure module */
+/* log Not a pure module */

package/tests/api/SuryToJsonSchemaTest.res

@@ -490,4 +490,133 @@ describe("SuryToJsonSchema:", () => {
       )->toBe(None)
     })
   })
+
+  // Reference-ness and DCB-tagged-ness are separate facts that happen to
+  // co-occur on `Reference.to_`. The schema walk tests them independently, and
+  // must keep doing so: a field can carry either alone, and a semantic type that
+  // is marked but deliberately *not* DCB-tagged (a storage ref, say) must not be
+  // dragged into entity-id classification by the other fact. Routing failures do
+  // not show up in a schema diff, so the distinction is pinned here executably.
+  describe("reference / DCB-tag decoupling:", () => {
+    let formatOf = (schema: JSON.t, fieldName: string): option<JSON.t> =>
+      getPropertyOf(schema, fieldName)->Option.flatMap(s => getProperty(s, "format"))
+
+    testSync("a DCB-tagged field with no reference is still an entity id", () => {
+      let schema = S.schema(s =>
+        {
+          "orderId": s.matches(Reventless.DcbTag.string),
+        }
+      )->S.castToUnknown
+      let json = SuryToJsonSchema.deriveObjectSchema(schema)
+      expect(formatOf(json, "orderId"))->toEqual(Some(JSON.Encode.string("uuid")))
+      expect(Reventless.Reference.getTarget(schema))->toBe(None)
+    })
+
+    testSync("a reference without a DCB tag is still an entity id", () => {
+      let field = Reventless.Reference.toWithoutDcbTag("Customer")
+      let schema = S.schema(s => {"customerId": s.matches(field)})->S.castToUnknown
+      let json = SuryToJsonSchema.deriveObjectSchema(schema)
+      expect(formatOf(json, "customerId"))->toEqual(Some(JSON.Encode.string("uuid")))
+      expect(Reventless.DcbTag.isTagged(field->S.castToUnknown))->toBe(false)
+    })
+
+    testSync("Reference.to_ carries both facts", () => {
+      let field = Reventless.Reference.to_("Customer")
+      expect(Reventless.DcbTag.isTagged(field->S.castToUnknown))->toBe(true)
+      expect(
+        Reventless.Reference.getTarget(field->S.castToUnknown)->Option.map(t => t.entity),
+      )->toEqual(Some("Customer"))
+    })
+
+    testSync("neither reference nor tag emits x-reventless-semantic on the wire", () => {
+      // `dateTime` and `reference` predate the generic marker and keep emitting
+      // `format`; adding the semantic key for them would change a published
+      // contract. Only semantics without a dedicated shape surface as the key.
+      let schema = S.schema(s =>
+        {
+          "customerId": s.matches(Reventless.Reference.to_("Customer")),
+          "placedAt": s.matches(Reventless.DateTime.string),
+        }
+      )->S.castToUnknown
+      let json = SuryToJsonSchema.deriveObjectSchema(schema)
+      let semanticOf = fieldName =>
+        getPropertyOf(json, fieldName)->Option.flatMap(s =>
+          getProperty(s, "x-reventless-semantic")
+        )
+      expect(semanticOf("customerId"))->toBe(None)
+      expect(semanticOf("placedAt"))->toBe(None)
+    })
+  })
+
+  // The reason the generic marker exists. `x-reventless-semantic` used to be
+  // emitted only by the annotation merge, which is fed by a PPX pass that only
+  // ever runs on read-model `state` records — so a command field could not carry
+  // a semantic at all. This walk is shape-driven and runs over every schema, so
+  // the declaration reaches the place the value is first accepted.
+  describe("type-carried semantics on a command field:", () => {
+    let semanticOf = (json, fieldName) =>
+      getPropertyOf(json, fieldName)->Option.flatMap(s => getProperty(s, "x-reventless-semantic"))
+
+    testSync("a storage-ref command field emits the semantic id", () => {
+      let schema = S.schema(s =>
+        {
+          "productId": s.matches(S.string),
+          "imageUrl": s.matches(Reventless.StorageRef.forStore(~store="productImages")),
+        }
+      )->S.castToUnknown
+      let json = SuryToJsonSchema.deriveObjectSchema(schema)
+      expect(semanticOf(json, "imageUrl"))->toEqual(Some(JSON.Encode.string("storageRef")))
+      expect(semanticOf(json, "productId"))->toBe(None)
+    })
+
+    testSync("it carries the store identity and marks the type as its source", () => {
+      let schema = S.schema(s =>
+        {
+          "imageUrl": s.matches(
+            Reventless.StorageRef.forStore(~plugin="catalog", ~store="productImages"),
+          ),
+        }
+      )->S.castToUnknown
+      let json = SuryToJsonSchema.deriveObjectSchema(schema)
+      let field = getPropertyOf(json, "imageUrl")
+      expect(field->Option.flatMap(s => getProperty(s, "x-reventless-semantic-source")))->toEqual(
+        Some(JSON.Encode.string("type")),
+      )
+      expect(field->Option.flatMap(s => getProperty(s, "x-reventless-semantic-target")))->toEqual(
+        Some(
+          JSON.Encode.object(
+            Dict.fromArray([
+              ("store", JSON.Encode.string("productImages")),
+              ("plugin", JSON.Encode.string("catalog")),
+            ]),
+          ),
+        ),
+      )
+    })
+
+    testSync("the underlying string shape is unchanged", () => {
+      // The marker refines an existing `string` field; nothing about what is
+      // stored changes, which is why it can be retrofitted onto a live schema.
+      let schema = S.schema(s =>
+        {"imageUrl": s.matches(Reventless.StorageRef.forStore(~store="productImages"))}
+      )->S.castToUnknown
+      let json = SuryToJsonSchema.deriveObjectSchema(schema)
+      expect(
+        getPropertyOf(json, "imageUrl")->Option.flatMap(s => getProperty(s, "type")),
+      )->toEqual(Some(JSON.Encode.string("string")))
+    })
+
+    testSync("a type-carried semantic beats an annotation naming the same field", () => {
+      let withSpec = (schema, spec) =>
+        schema->S.Metadata.set(~id=Reventless.StateAnnotations.stateAnnotationsId, spec)
+      let schema =
+        S.schema(s =>
+          {"imageUrl": s.matches(Reventless.StorageRef.forStore(~store="productImages"))}
+        )
+        ->S.castToUnknown
+        ->withSpec({...emptySpec, semantic: [("imageUrl", "image")]})
+      let json = SuryToJsonSchema.deriveObjectSchema(schema)
+      expect(semanticOf(json, "imageUrl"))->toEqual(Some(JSON.Encode.string("storageRef")))
+    })
+  })
 })

package/tests/api/SuryToJsonSchemaTest.res.mjs

@@ -5,7 +5,10 @@ import * as Stdlib_JSON from "@rescript/runtime/lib/es6/Stdlib_JSON.js";
 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 Primitive_string from "@rescript/runtime/lib/es6/Primitive_string.js";
+import * as DcbTag$Reventless from "@reventlessdev/reventless-spec/src/components/DcbTag.res.mjs";
 import * as DateTime$Reventless from "@reventlessdev/reventless-spec/src/types/DateTime.res.mjs";
+import * as Reference$Reventless from "@reventlessdev/reventless-spec/src/components/Reference.res.mjs";
+import * as StorageRef$Reventless from "@reventlessdev/reventless-spec/src/semantic/StorageRef.res.mjs";
 import * as StateAnnotations$Reventless from "@reventlessdev/reventless-spec/src/components/StateAnnotations.res.mjs";
 import * as SuryToJsonSchema$ReventlessCore from "../../src/components/Api/SuryToJsonSchema.res.mjs";
 
@@ -833,6 +836,107 @@ globalThis.describe("SuryToJsonSchema:", () => {
       globalThis.expect(Stdlib_Option.flatMap(entityIdSchema, s => getProperty(s, "x-reventless-id"))).toBe(undefined);
     });
   });
+  globalThis.describe("reference / DCB-tag decoupling:", () => {
+    let formatOf = (schema, fieldName) => Stdlib_Option.flatMap(getPropertyOf(schema, fieldName), s => getProperty(s, "format"));
+    globalThis.test("a DCB-tagged field with no reference is still an entity id", () => {
+      let schema = S.schema(s => ({
+        orderId: s.m(DcbTag$Reventless.string)
+      }));
+      let json = SuryToJsonSchema$ReventlessCore.deriveObjectSchema(schema);
+      globalThis.expect(formatOf(json, "orderId")).toEqual("uuid");
+      globalThis.expect(Reference$Reventless.getTarget(schema)).toBe(undefined);
+    });
+    globalThis.test("a reference without a DCB tag is still an entity id", () => {
+      let field = Reference$Reventless.toWithoutDcbTag(undefined, "Customer");
+      let schema = S.schema(s => ({
+        customerId: s.m(field)
+      }));
+      let json = SuryToJsonSchema$ReventlessCore.deriveObjectSchema(schema);
+      globalThis.expect(formatOf(json, "customerId")).toEqual("uuid");
+      globalThis.expect(DcbTag$Reventless.isTagged(field)).toBe(false);
+    });
+    globalThis.test("Reference.to_ carries both facts", () => {
+      let field = Reference$Reventless.to_(undefined, undefined, "Customer");
+      globalThis.expect(DcbTag$Reventless.isTagged(field)).toBe(true);
+      globalThis.expect(Stdlib_Option.map(Reference$Reventless.getTarget(field), t => t.entity)).toEqual("Customer");
+    });
+    globalThis.test("neither reference nor tag emits x-reventless-semantic on the wire", () => {
+      let schema = S.schema(s => ({
+        customerId: s.m(Reference$Reventless.to_(undefined, undefined, "Customer")),
+        placedAt: s.m(DateTime$Reventless.string)
+      }));
+      let json = SuryToJsonSchema$ReventlessCore.deriveObjectSchema(schema);
+      let semanticOf = fieldName => Stdlib_Option.flatMap(getPropertyOf(json, fieldName), s => getProperty(s, "x-reventless-semantic"));
+      globalThis.expect(semanticOf("customerId")).toBe(undefined);
+      globalThis.expect(semanticOf("placedAt")).toBe(undefined);
+    });
+  });
+  globalThis.describe("type-carried semantics on a command field:", () => {
+    let semanticOf = (json, fieldName) => Stdlib_Option.flatMap(getPropertyOf(json, fieldName), s => getProperty(s, "x-reventless-semantic"));
+    globalThis.test("a storage-ref command field emits the semantic id", () => {
+      let schema = S.schema(s => ({
+        productId: s.m(S.string),
+        imageUrl: s.m(StorageRef$Reventless.forStore(undefined, "productImages"))
+      }));
+      let json = SuryToJsonSchema$ReventlessCore.deriveObjectSchema(schema);
+      globalThis.expect(semanticOf(json, "imageUrl")).toEqual("storageRef");
+      globalThis.expect(semanticOf(json, "productId")).toBe(undefined);
+    });
+    globalThis.test("it carries the store identity and marks the type as its source", () => {
+      let schema = S.schema(s => ({
+        imageUrl: s.m(StorageRef$Reventless.forStore("catalog", "productImages"))
+      }));
+      let json = SuryToJsonSchema$ReventlessCore.deriveObjectSchema(schema);
+      let field = getPropertyOf(json, "imageUrl");
+      globalThis.expect(Stdlib_Option.flatMap(field, s => getProperty(s, "x-reventless-semantic-source"))).toEqual("type");
+      globalThis.expect(Stdlib_Option.flatMap(field, s => getProperty(s, "x-reventless-semantic-target"))).toEqual(Object.fromEntries([
+        [
+          "store",
+          "productImages"
+        ],
+        [
+          "plugin",
+          "catalog"
+        ]
+      ]));
+    });
+    globalThis.test("the underlying string shape is unchanged", () => {
+      let schema = S.schema(s => ({
+        imageUrl: s.m(StorageRef$Reventless.forStore(undefined, "productImages"))
+      }));
+      let json = SuryToJsonSchema$ReventlessCore.deriveObjectSchema(schema);
+      globalThis.expect(Stdlib_Option.flatMap(getPropertyOf(json, "imageUrl"), s => getProperty(s, "type"))).toEqual("string");
+    });
+    globalThis.test("a type-carried semantic beats an annotation naming the same field", () => {
+      let withSpec = (schema, spec) => S.Metadata.set(schema, StateAnnotations$Reventless.stateAnnotationsId, spec);
+      let schema = withSpec(S.schema(s => ({
+        imageUrl: s.m(StorageRef$Reventless.forStore(undefined, "productImages"))
+      })), {
+        ids: emptySpec_ids,
+        compositeIds: emptySpec_compositeIds,
+        subIds: emptySpec_subIds,
+        compositeSubIds: emptySpec_compositeSubIds,
+        indexes: emptySpec_indexes,
+        hidden: emptySpec_hidden,
+        summary: emptySpec_summary,
+        drillTargets: emptySpec_drillTargets,
+        drillTargetKeys: emptySpec_drillTargetKeys,
+        collapsed: emptySpec_collapsed,
+        scan: emptySpec_scan,
+        scanSort: emptySpec_scanSort,
+        semantic: [[
+            "imageUrl",
+            "image"
+          ]],
+        metric: emptySpec_metric,
+        status: undefined,
+        groupBy: undefined,
+        visibility: undefined
+      });
+      let json = SuryToJsonSchema$ReventlessCore.deriveObjectSchema(schema);
+      globalThis.expect(semanticOf(json, "imageUrl")).toEqual("storageRef");
+    });
+  });
 });
 
 export {