@reventlessdev/reventless-core 3.0.0-alpha.258 → 3.0.0-alpha.260

package/src/plugin/component/Plugin_Structure.res

@@ -21,20 +21,6 @@ let rec isLabelShape = (t: SchemaType.schemaType): bool =>
   | _ => false
   }
 
-// Whether a field can hold a lifecycle: a closed set of values, or an optional
-// one. A free-text `lifecycle: string` is not a lifecycle — filtering a command
-// menu against `allowedStates` needs states to compare with.
-let rec isLifecycleShape = (t: SchemaType.schemaType): bool =>
-  switch t {
-  | Enum(_, _) => true
-  | Nullable(inner) => isLifecycleShape(inner)
-  // A union is a closed set of *shapes*, not of values, and `allowedStates`
-  // compares values. The same answer the ppx gives `@lifecycle` on a union
-  // field, which is a compile error — this is the convention rung agreeing.
-  | TaggedUnion(_, _) => false
-  | _ => false
-  }
-
 // Field names that say "this one is the record's name" in the only way
 // available short of the `@displayName` annotation. Matched case-insensitively
 // and *exactly*: `customerName` holds a customer's name, not this record's.
@@ -43,33 +29,10 @@ let conventionalLabelNames = ["name", "title", "label", "displayname"]
 let shapeOfField = (~entityName: string, ~name: string, schema: S.t<unknown>): SchemaType.schemaType =>
   SchemaType.fromSury(~parentName=entityName, ~fieldName=name, schema)
 
-// The field holding the entity's lifecycle, for filtering a per-row command menu:
-// `@lifecycle`, else an enum field literally named `lifecycle`, else None. Not
-// keyed on `status` — a promiscuous name that would guess, and guess often.
-let lifecycleFieldFromStateSchema = (
-  ~entityName: string,
-  stateSchema: S.t<unknown>,
-): option<string> => {
-  let annotated = switch Reventless.StateAnnotations.getSpec(stateSchema) {
-  | Some(spec) => spec.lifecycle
-  | None => None
-  }
-  switch annotated {
-  | Some(_) as some => some
-  | None =>
-    switch stateSchema {
-    | Object({properties}) =>
-      properties
-      ->Dict.get("lifecycle")
-      ->Option.flatMap(schema =>
-        isLifecycleShape(shapeOfField(~entityName, ~name="lifecycle", schema))
-          ? Some("lifecycle")
-          : None
-      )
-    | _ => None
-    }
-  }
-}
+// The field holding the entity's lifecycle, for filtering a per-row command
+// menu. One rule, stated in `Reventless.Lifecycle` — the projection machinery
+// resolves the field a trail entry records against from the same place.
+let lifecycleFieldFromStateSchema = Reventless.Lifecycle.fieldName
 
 // The field whose truth withdraws a row from ordinary reads. Annotation-only —
 // no convention rung, since guessing wrong here makes rows vanish.
@@ -113,7 +76,7 @@ let checkRetiredValue = (~entityName: string, stateSchema: S.t<unknown>): retire
   | None | Some({values: None}) => NotDeclared
   | Some({field, values: Some(values)}) =>
     let named = values->Array.join(", ")
-    let lifecycle = lifecycleFieldFromStateSchema(~entityName, stateSchema)
+    let lifecycle = lifecycleFieldFromStateSchema(stateSchema)
     if lifecycle != Some(field) {
       log.warn(
         ~comp="Plugin_Structure",
@@ -190,7 +153,7 @@ let lifecycleStatesFromStateSchema = (
   ~entityName: string,
   stateSchema: S.t<unknown>,
 ): option<array<string>> =>
-  lifecycleFieldFromStateSchema(~entityName, stateSchema)->Option.flatMap(field =>
+  lifecycleFieldFromStateSchema(stateSchema)->Option.flatMap(field =>
     switch stateSchema {
     | Object({properties}) =>
       properties
@@ -965,7 +928,7 @@ let queryableDefFromSpec = (
     labelField: label.field,
     searchableFields: label.searchableFields,
     labelFieldSource: Some(labelFieldSourceToString(label.source)),
-    lifecycleField: lifecycleFieldFromStateSchema(~entityName=name, stateSchema),
+    lifecycleField: lifecycleFieldFromStateSchema(stateSchema),
     ownerField: Reventless.Owner.fieldNames(stateSchema)->Array.get(0),
     retiredField: retiredFieldFromStateSchema(stateSchema),
     retiredValues: retiredValuesFromStateSchema(stateSchema),
@@ -1410,7 +1373,7 @@ let make = (
         labelField: label.field,
         searchableFields: label.searchableFields,
         labelFieldSource: Some(labelFieldSourceToString(label.source)),
-        lifecycleField: lifecycleFieldFromStateSchema(~entityName=R.Spec.name, stateSchema),
+        lifecycleField: lifecycleFieldFromStateSchema(stateSchema),
         // Same schema `lifecycleField` reads, so the two cannot disagree about which
         // fields this view has.
         ownerField: Reventless.Owner.fieldNames(stateSchema)->Array.get(0),
@@ -1451,7 +1414,7 @@ let make = (
         labelField: label.field,
         searchableFields: label.searchableFields,
         labelFieldSource: Some(labelFieldSourceToString(label.source)),
-        lifecycleField: lifecycleFieldFromStateSchema(~entityName=SVS.Spec.name, stateSchema),
+        lifecycleField: lifecycleFieldFromStateSchema(stateSchema),
         ownerField: Reventless.Owner.fieldNames(stateSchema)->Array.get(0),
         retiredField: retiredFieldFromStateSchema(stateSchema),
         retiredValues: retiredValuesFromStateSchema(stateSchema),

package/src/plugin/component/Plugin_Structure.res.mjs

@@ -12,6 +12,7 @@ import * as Primitive_string from "@rescript/runtime/lib/es6/Primitive_string.js
 import * as Trait$Reventless from "@reventlessdev/reventless-spec/src/types/Trait.res.mjs";
 import * as DcbTag$Reventless from "@reventlessdev/reventless-spec/src/components/DcbTag.res.mjs";
 import * as Message$Reventless from "@reventlessdev/reventless-spec/src/types/Message.res.mjs";
+import * as Lifecycle$Reventless from "@reventlessdev/reventless-spec/src/types/Lifecycle.res.mjs";
 import * as Reference$Reventless from "@reventlessdev/reventless-spec/src/components/Reference.res.mjs";
 import * as Util_Sury$Reventless from "@reventlessdev/reventless-spec/src/util/Util_Sury.res.mjs";
 import * as Logger$ReventlessCore from "../../util/Logger.res.mjs";
@@ -47,24 +48,6 @@ function isLabelShape(_t) {
   };
 }
 
-function isLifecycleShape(_t) {
-  while (true) {
-    let t = _t;
-    if (typeof t !== "object") {
-      return false;
-    }
-    switch (t.TAG) {
-      case "Nullable" :
-        _t = t._0;
-        continue;
-      case "Enum" :
-        return true;
-      default:
-        return false;
-    }
-  };
-}
-
 let conventionalLabelNames = [
   "name",
   "title",
@@ -74,22 +57,6 @@ let conventionalLabelNames = [
 
 let shapeOfField = SchemaType$ReventlessCore.fromSury;
 
-function lifecycleFieldFromStateSchema(entityName, stateSchema) {
-  let spec = StateAnnotations$Reventless.getSpec(stateSchema);
-  let annotated = spec !== undefined ? spec.lifecycle : undefined;
-  if (annotated !== undefined) {
-    return annotated;
-  } else if (stateSchema.type === "object") {
-    return Stdlib_Option.flatMap(stateSchema.properties["lifecycle"], schema => {
-      if (isLifecycleShape(SchemaType$ReventlessCore.fromSury(entityName, "lifecycle", schema))) {
-        return "lifecycle";
-      }
-    });
-  } else {
-    return;
-  }
-}
-
 function retiredFromStateSchema(stateSchema) {
   let spec = StateAnnotations$Reventless.getSpec(stateSchema);
   if (spec !== undefined) {
@@ -120,7 +87,7 @@ function checkRetiredValue(entityName, stateSchema) {
   }
   let field = match.field;
   let named = values.join(", ");
-  let lifecycle = lifecycleFieldFromStateSchema(entityName, stateSchema);
+  let lifecycle = Lifecycle$Reventless.fieldName(stateSchema);
   if (Primitive_object.notequal(lifecycle, field)) {
     log.warn("Plugin_Structure", undefined, entityName + `: @retired(` + named + `) is on "` + field + `", which is not this record's lifecycle field` + Stdlib_Option.getOr(Stdlib_Option.map(lifecycle, f => ` (that is "` + f + `")`), " (it declares none)") + `. A retirement state no command's declared edge can name loses the command filtering the state form exists for.`);
   }
@@ -169,7 +136,7 @@ function reportRetiredStates(pluginName, failures, unchecked) {
 }
 
 function lifecycleStatesFromStateSchema(entityName, stateSchema) {
-  return Stdlib_Option.flatMap(lifecycleFieldFromStateSchema(entityName, stateSchema), field => {
+  return Stdlib_Option.flatMap(Lifecycle$Reventless.fieldName(stateSchema), field => {
     if (stateSchema.type === "object") {
       return Stdlib_Option.map(stateSchema.properties[field], schema => {
         let match = SchemaType$ReventlessCore.fromSury(entityName, field, schema);
@@ -715,7 +682,7 @@ function queryableDefFromSpec(plugin, name, stateSchema, authorization, visibili
     labelField: label.field,
     searchableFields: label.searchableFields,
     labelFieldSource: labelFieldSourceToString(label.source),
-    lifecycleField: lifecycleFieldFromStateSchema(name, stateSchema),
+    lifecycleField: Lifecycle$Reventless.fieldName(stateSchema),
     ownerField: Owner$Reventless.fieldNames(stateSchema)[0],
     retiredField: retiredFieldFromStateSchema(stateSchema),
     retiredValues: retiredValuesFromStateSchema(stateSchema),
@@ -1024,7 +991,7 @@ function make(name, aggregatesOpt, readModelsOpt, stateViewSlicesOpt, stateChang
       labelField: label.field,
       searchableFields: label.searchableFields,
       labelFieldSource: labelFieldSourceToString(label.source),
-      lifecycleField: lifecycleFieldFromStateSchema(R.Spec.name, stateSchema),
+      lifecycleField: Lifecycle$Reventless.fieldName(stateSchema),
       ownerField: Owner$Reventless.fieldNames(stateSchema)[0],
       retiredField: retiredFieldFromStateSchema(stateSchema),
       retiredValues: retiredValuesFromStateSchema(stateSchema),
@@ -1056,7 +1023,7 @@ function make(name, aggregatesOpt, readModelsOpt, stateViewSlicesOpt, stateChang
       labelField: label.field,
       searchableFields: label.searchableFields,
       labelFieldSource: labelFieldSourceToString(label.source),
-      lifecycleField: lifecycleFieldFromStateSchema(SVS.Spec.name, stateSchema),
+      lifecycleField: Lifecycle$Reventless.fieldName(stateSchema),
       ownerField: Owner$Reventless.fieldNames(stateSchema)[0],
       retiredField: retiredFieldFromStateSchema(stateSchema),
       retiredValues: retiredValuesFromStateSchema(stateSchema),
@@ -1383,11 +1350,12 @@ function make(name, aggregatesOpt, readModelsOpt, stateViewSlicesOpt, stateChang
   };
 }
 
+let lifecycleFieldFromStateSchema = Lifecycle$Reventless.fieldName;
+
 export {
   log,
   declaredTransitionsOnly,
   isLabelShape,
-  isLifecycleShape,
   conventionalLabelNames,
   shapeOfField,
   lifecycleFieldFromStateSchema,

package/src/plugin/connect/PluginExtensionPoint_UiFragment.res.mjs

@@ -2,7 +2,7 @@
 
 import * as Id$Reventless from "@reventlessdev/reventless-spec/src/types/Id.res.mjs";
 import * as Plugin$ReventlessCore from "../component/Plugin.res.mjs";
-import * as UiFragmentRegistry$ReventlessCore from "../../admin/UiFragmentRegistry/StateChangeSlice/UiFragmentRegistry.res.mjs";
+import * as UiFragmentRegistry$ReventlessCore from "../../admin/UiFragmentRegistry/StateChange/UiFragmentRegistry.res.mjs";
 import * as ExtensionPointMapping$ReventlessInfra from "@reventlessdev/reventless-infra/src/types/ExtensionPointMapping.res.mjs";
 import * as PluginExtensionPointSpec$ReventlessInfra from "@reventlessdev/reventless-infra/src/types/PluginExtensionPointSpec.res.mjs";
 

package/tests/admin/AdminApiSchemaDriftTest.res.mjs

@@ -4,7 +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 Plugin$Reventless from "@reventlessdev/reventless-spec/src/components/Plugin.res.mjs";
 import * as SchemaType$ReventlessCore from "../../src/components/Api/SchemaType.res.mjs";
-import * as UiFragments$ReventlessCore from "../../src/admin/UiFragmentRegistry/StateViewSlice/UiFragments.res.mjs";
+import * as UiFragments$ReventlessCore from "../../src/admin/UiFragmentRegistry/StateView/UiFragments.res.mjs";
 import * as Platform_UIFragmentsApi$ReventlessCore from "../../src/admin/Platform_UIFragmentsApi.res.mjs";
 import * as Platform_PluginStructuresApi$ReventlessCore from "../../src/admin/Platform_PluginStructuresApi.res.mjs";
 import * as Platform_ComponentDefinitionsApi$ReventlessCore from "../../src/admin/Platform_ComponentDefinitionsApi.res.mjs";

package/tests/api/BrandedMarkerCompositionTest.res

@@ -0,0 +1,74 @@
+open JestGlobals
+
+// A field marker and a branded semantic type on the same field. Both markers
+// used to test for the literal `string` keyword, so both saw the brand instead
+// of the string and refused a field they should have taken — which would have
+// made declaring what a field *is* cost it whatever the marker gave.
+//
+// The composition assertion is the one that matters. `@owner` cannot see the
+// schema sury-ppx derives from `Email.t`, so the tempting fix is to inject
+// `Owner.string` over it: that type-checks, passes an "is it marked" test, and
+// silently leaves the field a plain string with the address grammar gone.
+// Asserting the marker is there proves nothing on its own — the rejection below
+// is what says the brand survived.
+describe("a field marker on a branded semantic:", () => {
+  let stateSchema = PsBrandedMarkersReadModel.stateSchema->S.castToUnknown
+
+  let fieldOf = name =>
+    switch stateSchema {
+    | Object({properties}) => properties->Dict.get(name)
+    | _ => None
+    }
+
+  describe("@owner on an Email field:", () => {
+    testSync("marks the field as the owner", () =>
+      expect(fieldOf("email")->Option.mapOr(false, Reventless.Owner.isFieldOwner))->toBe(true)
+    )
+
+    testSync("keeps the email semantic", () =>
+      expect(
+        fieldOf("email")
+        ->Option.flatMap(Reventless.Semantic.getFrom)
+        ->Option.map(s => s.id),
+      )->toEqual(Some("email"))
+    )
+
+    // The regression a substituting fix would land, and it lands in silence:
+    // the row still scopes to its owner, and the field accepts anything.
+    testSync("still rejects what is not an address", () => {
+      let parses = raw =>
+        switch fieldOf("email") {
+        | Some(schema) =>
+          switch raw->JSON.Encode.string->S.parseOrThrow(~to=schema) {
+          | _ => true
+          | exception _ => false
+          }
+        | None => false
+        }
+      expect((parses("buyer@example.com"), parses("buyer")))->toEqual((true, false))
+    })
+  })
+
+  describe("@displayName on a DateTime field:", () => {
+    testSync("names the row by it", () =>
+      expect(
+        S.Metadata.get(stateSchema, ~id=Reventless.DisplayName.displayNameId)->Option.map(d =>
+          d.fields
+        ),
+      )->toEqual(Some(["openedAt"]))
+    )
+
+    testSync("and the instant grammar survives", () => {
+      let parses = raw =>
+        switch fieldOf("openedAt") {
+        | Some(schema) =>
+          switch raw->JSON.Encode.string->S.parseOrThrow(~to=schema) {
+          | _ => true
+          | exception _ => false
+          }
+        | None => false
+        }
+      expect((parses("2026-03-02T09:00:00Z"), parses("tomorrow")))->toEqual((true, false))
+    })
+  })
+})

package/tests/api/BrandedMarkerCompositionTest.res.mjs

@@ -0,0 +1,74 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+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 Owner$Reventless from "@reventlessdev/reventless-spec/src/components/Owner.res.mjs";
+import * as Semantic$Reventless from "@reventlessdev/reventless-spec/src/semantic/Semantic.res.mjs";
+import * as DisplayName$Reventless from "@reventlessdev/reventless-spec/src/components/DisplayName.res.mjs";
+import * as PsBrandedMarkersReadModel$ReventlessCore from "./PsBrandedMarkersReadModel.res.mjs";
+
+globalThis.describe("a field marker on a branded semantic:", () => {
+  let fieldOf = name => {
+    if (PsBrandedMarkersReadModel$ReventlessCore.stateSchema.type === "object") {
+      return PsBrandedMarkersReadModel$ReventlessCore.stateSchema.properties[name];
+    }
+  };
+  globalThis.describe("@owner on an Email field:", () => {
+    globalThis.test("marks the field as the owner", () => {
+      globalThis.expect(Stdlib_Option.mapOr(fieldOf("email"), false, Owner$Reventless.isFieldOwner)).toBe(true);
+    });
+    globalThis.test("keeps the email semantic", () => {
+      globalThis.expect(Stdlib_Option.map(Stdlib_Option.flatMap(fieldOf("email"), Semantic$Reventless.getFrom), s => s.id)).toEqual("email");
+    });
+    globalThis.test("still rejects what is not an address", () => {
+      let parses = raw => {
+        let schema = fieldOf("email");
+        if (schema === undefined) {
+          return false;
+        }
+        try {
+          S.parseOrThrow(raw, schema);
+          return true;
+        } catch (exn) {
+          return false;
+        }
+      };
+      globalThis.expect([
+        parses("buyer@example.com"),
+        parses("buyer")
+      ]).toEqual([
+        true,
+        false
+      ]);
+    });
+  });
+  globalThis.describe("@displayName on a DateTime field:", () => {
+    globalThis.test("names the row by it", () => {
+      globalThis.expect(Stdlib_Option.map(Sury.$Metadata_get(PsBrandedMarkersReadModel$ReventlessCore.stateSchema, DisplayName$Reventless.displayNameId), d => d.fields)).toEqual(["openedAt"]);
+    });
+    globalThis.test("and the instant grammar survives", () => {
+      let parses = raw => {
+        let schema = fieldOf("openedAt");
+        if (schema === undefined) {
+          return false;
+        }
+        try {
+          S.parseOrThrow(raw, schema);
+          return true;
+        } catch (exn) {
+          return false;
+        }
+      };
+      globalThis.expect([
+        parses("2026-03-02T09:00:00Z"),
+        parses("tomorrow")
+      ]).toEqual([
+        true,
+        false
+      ]);
+    });
+  });
+});
+
+/*  Not a pure module */

package/tests/api/PsBrandedMarkersReadModel.res

@@ -0,0 +1,24 @@
+// Fixture for the field markers that meet a branded semantic type. A spec file
+// and named `*ReadModel*` deliberately: the annotation machinery runs only under
+// `@@reventless.spec` and only for a file the PPX reads as a read model or state
+// view, so a module inside the test would exercise nothing.
+//
+// The two markers here are the two that used to read the literal `string`
+// keyword and so refuse a field whose type is a string wearing a brand.
+
+@@reventless.spec("BrandedMarkersReadModel")
+
+@schema
+type consumedEvent = SubscriptionOpened({subscriptionId: string, email: string})
+
+@schema
+type state = {
+  @id subscriptionId: string,
+  // The owner named by an address rather than by a bare id. `@owner` has to
+  // compose onto the schema sury-ppx derives from `Email.t` — replacing it would
+  // type-check and leave the field a plain marked string.
+  @owner email: Reventless.Email.t,
+  // `@displayName` never touches the field's schema; it only joins values, so a
+  // branded string is one it can read.
+  @displayName @summary openedAt: Reventless.DateTime.t,
+}

package/tests/api/PsBrandedMarkersReadModel.res.mjs

@@ -0,0 +1,87 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Sury from "sury";
+import * as Email$Reventless from "@reventlessdev/reventless-spec/src/semantic/Email.res.mjs";
+import * as Owner$Reventless from "@reventlessdev/reventless-spec/src/components/Owner.res.mjs";
+import * as DateTime$Reventless from "@reventlessdev/reventless-spec/src/semantic/DateTime.res.mjs";
+import * as ReadModel$Reventless from "@reventlessdev/reventless-spec/src/components/ReadModel.res.mjs";
+import * as DisplayName$Reventless from "@reventlessdev/reventless-spec/src/components/DisplayName.res.mjs";
+import * as StateAnnotations$Reventless from "@reventlessdev/reventless-spec/src/components/StateAnnotations.res.mjs";
+
+let consumedEventSchema = Sury.$schema(s => ({
+  TAG: "SubscriptionOpened",
+  subscriptionId: s.m(Sury.string),
+  email: s.m(Sury.string)
+}));
+
+let stateSchema = Sury.$schema(s => ({
+  subscriptionId: s.m(Sury.string),
+  email: s.m(Owner$Reventless.mark(Email$Reventless.schema)),
+  openedAt: s.m(DateTime$Reventless.schema),
+  displayName: s.m(Sury.$option(Sury.string))
+}));
+
+let stateSchema$1 = Sury.$Metadata_set(stateSchema, DisplayName$Reventless.displayNameId, {
+  fields: ["openedAt"],
+  separator: " "
+});
+
+let config = ReadModel$Reventless.config(undefined, undefined, [{
+    index: "_owner",
+    type_: "S",
+    idField: "email",
+    subIdField: "id",
+    projectionType: "ALL",
+    derived: true
+  }]);
+
+let makeId = (state => state.subscriptionId);
+
+let stateSchema$2 = Sury.$Metadata_set(stateSchema$1, StateAnnotations$Reventless.stateAnnotationsId, {
+  ids: ["subscriptionId"],
+  compositeIds: [],
+  subIds: [],
+  compositeSubIds: [],
+  indexes: [],
+  hidden: [],
+  summary: ["openedAt"],
+  internal: [],
+  drillTargets: [],
+  drillTargetKeys: [],
+  collapsed: [],
+  scan: [],
+  scanSort: [],
+  semantic: [],
+  metric: [],
+  lifecycle: undefined,
+  groupBy: undefined,
+  visibility: undefined,
+  live: undefined,
+  retired: undefined
+});
+
+let name = "BrandedMarkersReadModel";
+
+let Id;
+
+let subIdConfig;
+
+let moduleUrl = "@reventlessdev/reventless-core/tests/api/PsBrandedMarkersReadModel.res.mjs";
+
+let authorization = "AllowAuthenticated";
+
+let visibility = "Public";
+
+export {
+  name,
+  Id,
+  consumedEventSchema,
+  config,
+  subIdConfig,
+  makeId,
+  stateSchema$2 as stateSchema,
+  moduleUrl,
+  authorization,
+  visibility,
+}
+/* consumedEventSchema Not a pure module */

package/tests/api/SuryToJsonSchemaTest.res

@@ -57,7 +57,7 @@ describe("SuryToJsonSchema:", () => {
     testSync("emits format:\"date-time\" for a DateTime-marked string field", () => {
       let schema = S.schema(s =>
         {
-          "placedAt": s.matches(Reventless.DateTime.string),
+          "placedAt": s.matches(Reventless.DateTime.schema),
           "name": s.matches(S.string),
         }
       )->S.castToUnknown
@@ -72,6 +72,38 @@ describe("SuryToJsonSchema:", () => {
         getPropertyOf(json, "name")->Option.flatMap(s => getProperty(s, "format")),
       )->toBe(None)
     })
+
+    // The no-drift claim behind writing `placedAt: Reventless.DateTime.t` in
+    // place of `@s.matches(DateTime.string) string`: the type emits exactly what
+    // the annotation emitted, semantic key still absent. This is the one test
+    // that would catch that output changing by accident.
+    testSync("a DateTime field emits format and no semantic key", () => {
+      let json = SuryToJsonSchema.deriveObjectSchema(
+        S.schema(s => {"placedAt": s.matches(Reventless.DateTime.schema)})->S.castToUnknown,
+      )
+      let keyOf = key => getPropertyOf(json, "placedAt")->Option.flatMap(s => getProperty(s, key))
+      expect((keyOf("type"), keyOf("format"), keyOf("x-reventless-semantic")))->toEqual((
+        Some(JSON.Encode.string("string")),
+        Some(JSON.Encode.string("date-time")),
+        None,
+      ))
+    })
+
+    // A calendar date speaks both vocabularies, and that asymmetry with
+    // `DateTime` is deliberate: `DateTime`'s bare-`format` output predates the
+    // generic marker and is a published contract, so it keeps it; a semantic
+    // arriving now has no such history and should say what it is as well.
+    testSync("a CalendarDate field emits format:\"date\" AND the semantic key", () => {
+      let json = SuryToJsonSchema.deriveObjectSchema(
+        S.schema(s => {"issuedOn": s.matches(Reventless.CalendarDate.schema)})->S.castToUnknown,
+      )
+      let keyOf = key => getPropertyOf(json, "issuedOn")->Option.flatMap(s => getProperty(s, key))
+      expect((keyOf("type"), keyOf("format"), keyOf("x-reventless-semantic")))->toEqual((
+        Some(JSON.Encode.string("string")),
+        Some(JSON.Encode.string("date")),
+        Some(JSON.Encode.string("date")),
+      ))
+    })
   })
 
   describe("deriveObjectSchema with an owner field:", () => {
@@ -898,7 +930,7 @@ describe("SuryToJsonSchema:", () => {
       let schema = S.schema(s =>
         {
           "customerId": s.matches(Reventless.Reference.to_("Customer")),
-          "placedAt": s.matches(Reventless.DateTime.string),
+          "placedAt": s.matches(Reventless.DateTime.schema),
         }
       )->S.castToUnknown
       let json = SuryToJsonSchema.deriveObjectSchema(schema)
@@ -1203,7 +1235,7 @@ describe("SuryToJsonSchema:", () => {
       S.schema(s =>
         {
           "deliveryWindow": s.matches(Reventless.DateRange.schema),
-          "orderedAt": s.matches(Reventless.DateTime.string),
+          "orderedAt": s.matches(Reventless.DateTime.schema),
         }
       )->S.castToUnknown,
     )
@@ -1324,4 +1356,60 @@ describe("SuryToJsonSchema:", () => {
     )
   })
 
+  // The value a field opens with is JSON Schema's own keyword, not an
+  // `x-reventless-` extension — and it rides on the field's schema, so it
+  // survives the one place a name-keyed annotation spec cannot reach: a record
+  // nested inside a command.
+  describe("a field declaring a default:", () => {
+    let defaultOf = (json, ~field) =>
+      getPropertyOf(json, field)->Option.flatMap(s => getProperty(s, "default"))
+
+    let json = SuryToJsonSchema.deriveObjectSchema(
+      S.schema(s =>
+        {
+          "quantity": s.matches(S.int->Reventless.FieldDefault.int(1)),
+          "shippingMethod": s.matches(S.string->Reventless.FieldDefault.string("Standard")),
+          "plain": s.matches(S.int),
+        }
+      )->S.castToUnknown,
+    )
+
+    testSync("carries it as `default`", () =>
+      expect(defaultOf(json, ~field="quantity"))->toEqual(Some(JSON.Encode.int(1)))
+    )
+
+    testSync("keeps the shape the value actually has", () =>
+      expect(
+        getPropertyOf(json, "quantity")->Option.flatMap(s => getProperty(s, "type")),
+      )->toEqual(Some(JSON.Encode.string("integer")))
+    )
+
+    testSync("carries a string default the same way", () =>
+      expect(defaultOf(json, ~field="shippingMethod"))
+      ->toEqual(Some(JSON.Encode.string("Standard")))
+    )
+
+    testSync("while a field declaring none says nothing", () =>
+      expect(defaultOf(json, ~field="plain"))->toBe(None)
+    )
+
+    // The case the whole marker exists for: a name-keyed annotation spec speaks
+    // for a record's own fields, and an order's line items are one level in.
+    testSync("and reaches a field of a nested record", () => {
+      let lineItem = S.schema(s =>
+        {
+          "productId": s.matches(S.string),
+          "quantity": s.matches(S.int->Reventless.FieldDefault.int(1)),
+        }
+      )
+      let nested = SuryToJsonSchema.deriveObjectSchema(
+        S.schema(s => {"lineItems": s.matches(S.array(lineItem))})->S.castToUnknown,
+      )
+      expect(
+        getPropertyOf(nested, "lineItems")
+        ->Option.flatMap(a => getProperty(a, "items"))
+        ->Option.flatMap(i => defaultOf(i, ~field="quantity")),
+      )->toEqual(Some(JSON.Encode.int(1)))
+    })
+  })
 })