@reventlessdev/reventless-core 3.0.0-alpha.253 → 3.0.0-alpha.255

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

@@ -3,6 +3,7 @@
 import * as Stdlib_JSON from "@rescript/runtime/lib/es6/Stdlib_JSON.js";
 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 Sensitive$Reventless from "@reventlessdev/reventless-spec/src/components/Sensitive.res.mjs";
 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";
@@ -232,7 +233,7 @@ function fromSchemaType(st) {
           ]
         ]);
       case "ObjectRef" :
-        return objectRefToJsonSchema(undefined, undefined, undefined, st._1);
+        return objectRefToJsonSchema(undefined, undefined, undefined, undefined, st._1);
       case "Enum" :
         return Object.fromEntries([
           [
@@ -269,7 +270,7 @@ function armToJsonSchema(tag, armType) {
   if (armType.TAG !== "ObjectRef") {
     return fromSchemaType(armType);
   }
-  let base = objectRefToJsonSchema(undefined, undefined, undefined, armType._1);
+  let base = objectRefToJsonSchema(undefined, undefined, undefined, undefined, armType._1);
   let obj = Stdlib_JSON.Decode.object(base);
   if (obj === undefined) {
     return base;
@@ -303,26 +304,47 @@ function withSemantic(fieldSchema, sem) {
   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));
+    switch (match.TAG) {
+      case "ReferenceTo" :
+        let match$1 = match._0;
+        obj["x-reventless-semantic-target"] = Object.fromEntries(withOptionalPlugin([[
+            "entity",
+            match$1.entity
+          ]], match$1.plugin));
+        break;
+      case "StoredIn" :
+        let match$2 = match._0;
+        obj["x-reventless-semantic-target"] = Object.fromEntries(withOptionalPlugin([[
+            "store",
+            match$2.store
+          ]], match$2.plugin));
+        break;
+      case "MemberOf" :
+        let match$3 = match._0;
+        let optional = (pairs, key, value) => {
+          if (value !== undefined) {
+            return pairs.concat([[
+                key,
+                value
+              ]]);
+          } else {
+            return pairs;
+          }
+        };
+        obj["x-reventless-semantic-target"] = Object.fromEntries(optional(optional(withOptionalPlugin([[
+            "field",
+            match$3.field
+          ]], match$3.plugin), "view", match$3.view), "content", match$3.content));
+        break;
     }
   }
   return obj;
 }
 
-function objectRefToJsonSchema(annotations, optionalOpt, ownersOpt, fields) {
+function objectRefToJsonSchema(annotations, optionalOpt, ownersOpt, sensitiveOpt, fields) {
   let optional = optionalOpt !== undefined ? optionalOpt : [];
   let owners = ownersOpt !== undefined ? ownersOpt : [];
+  let sensitive = sensitiveOpt !== undefined ? sensitiveOpt : [];
   let props = {};
   let required = [];
   let internal = Stdlib_Option.getOr(Stdlib_Option.flatMap(annotations, spec => spec.internal), []);
@@ -343,7 +365,18 @@ function objectRefToJsonSchema(annotations, optionalOpt, ownersOpt, fields) {
     } else {
       withAnnotations$1 = withAnnotations;
     }
-    props[fieldName] = withAnnotations$1;
+    let obj$1 = Stdlib_JSON.Decode.object(withAnnotations$1);
+    let withAnnotations$2;
+    if (obj$1 !== undefined) {
+      let bySemantic = Stdlib_Option.mapOr(Stdlib_Option.flatMap(obj$1["x-reventless-semantic"], Stdlib_JSON.Decode.string), false, Sensitive$Reventless.impliedBySemantic);
+      if (sensitive.includes(fieldName) || bySemantic) {
+        obj$1["x-reventless-sensitive"] = true;
+      }
+      withAnnotations$2 = obj$1;
+    } else {
+      withAnnotations$2 = withAnnotations$1;
+    }
+    props[fieldName] = withAnnotations$2;
     if (!optional.includes(fieldName) && !isNullableType(fieldType)) {
       required.push(fieldName);
       return;
@@ -377,7 +410,7 @@ function deriveObjectSchema(schema) {
       ]]);
   }
   let annotations = StateAnnotations$Reventless.getSpec(schema);
-  let objSchema = objectRefToJsonSchema(annotations, SchemaType$ReventlessCore.optionalFieldNames(schema), Owner$Reventless.fieldNames(schema), fields);
+  let objSchema = objectRefToJsonSchema(annotations, SchemaType$ReventlessCore.optionalFieldNames(schema), Owner$Reventless.fieldNames(schema), Sensitive$Reventless.fieldNames(schema), fields);
   if (annotations === undefined) {
     return objSchema;
   }

package/src/components/Dcb/Dcb_Builder.res

@@ -379,10 +379,7 @@ module Make = (
         // (DcbCommandTopicEntryPoint.mjs) route through `DcbTag.deriveEffectiveScope`
         // so the runtime decision query cannot drift from this scope — see
         // docs/analysis/dcb-runtime-scope-annotation-drift.md.
-        let {
-          crossPartitionTagKeys: effectiveCrossPartitionTagKeys,
-          tagKeysByEventType: effectiveTagKeysByEventType,
-        } = Reventless.DcbTag.deriveEffectiveScope(
+        let effective = Reventless.DcbTag.deriveEffectiveScope(
           stateChangeSlices->Array.map((module(Sc: StateChangeSlice.T)) => {
             Reventless.DcbTag.name: Sc.Spec.name,
             commandSchema: Sc.Spec.commandSchema->S.castToUnknown,
@@ -390,6 +387,26 @@ module Make = (
             eventSchema: Sc.Spec.eventSchema->S.castToUnknown,
           }),
         )
+        let effectiveCrossPartitionTagKeys = effective.crossPartitionTagKeys
+        let effectiveTagKeysByEventType = effective.tagKeysByEventType
+
+        // An ambiguity is a warning above because a boundary can fall back and
+        // lose nothing. Losing a cross-partition key is not that: the decision
+        // read for every slice that references another entity silently narrows to
+        // its own partition, so it decides against an empty history and rejects a
+        // command whose facts are sitting in the log. Nothing downstream fails —
+        // the wrong answer *is* the failure — so this is the only place it can be
+        // said, and it is said at error level naming the slice to fix.
+        if effective.droppedCrossPartitionTagKeys->Array.length > 0 {
+          log.error(
+            ~comp="Dcb_Builder",
+            `DCB scope degraded (${name}): cross-partition reads of [${effective.droppedCrossPartitionTagKeys->Array.join(
+                ", ",
+              )}] were derived but dropped — an ambiguous slice forced the boundary onto @crossPartition annotations that do not carry them. Slices referencing another entity by these keys will decide against an empty history and reject valid commands. Resolve: ${effective.ambiguities
+              ->Array.map(((slice, reason)) => `${slice} (${reason})`)
+              ->Array.join(" | ")}`,
+          )
+        }
 
         module DcbEventLog = DcbEventLog_Builder.Make(
           DcbEventLogStorage,

package/src/components/Dcb/Dcb_Builder.res.mjs

@@ -231,14 +231,17 @@ function Make(DcbEventLogStorage) {
       let scopeIssues = DcbValidation$Reventless.validateScopeVsInference(scopeAnnotations, inferred);
       scopeIssues.contradictions.forEach(e => log.warn("Dcb_Builder", undefined, `DCB scope contradiction (` + e.sliceName + `): ` + e.message));
       scopeIssues.redundancies.forEach(e => log.info("Dcb_Builder", undefined, `DCB scope (` + e.sliceName + `): ` + e.message));
-      let match = DcbTag$Reventless.deriveEffectiveScope(stateChangeSlices.map(Sc => ({
+      let effective = DcbTag$Reventless.deriveEffectiveScope(stateChangeSlices.map(Sc => ({
         name: Sc.Spec.name,
         commandSchema: Sc.Spec.commandSchema,
         consumedEventSchema: Sc.Spec.consumedEventSchema,
         eventSchema: Sc.Spec.eventSchema
       })));
-      let effectiveTagKeysByEventType = match.tagKeysByEventType;
-      let effectiveCrossPartitionTagKeys = match.crossPartitionTagKeys;
+      let effectiveCrossPartitionTagKeys = effective.crossPartitionTagKeys;
+      let effectiveTagKeysByEventType = effective.tagKeysByEventType;
+      if (effective.droppedCrossPartitionTagKeys.length !== 0) {
+        log.error("Dcb_Builder", undefined, `DCB scope degraded (` + name + `): cross-partition reads of [` + effective.droppedCrossPartitionTagKeys.join(", ") + `] were derived but dropped — an ambiguous slice forced the boundary onto @crossPartition annotations that do not carry them. Slices referencing another entity by these keys will decide against an empty history and reject valid commands. Resolve: ` + effective.ambiguities.map(param => param[0] + ` (` + param[1] + `)`).join(" | "));
+      }
       let DcbEventLog = DcbEventLog_Builder$ReventlessCore.Make(DcbEventLogStorage)(DcbEventTopicPublisher);
       let dcbEventLog = DcbEventLog.make(name, indexes$1, partitionTag, effectiveCrossPartitionTagKeys, opts);
       Stdlib_Option.forEach(HooksConfig.hooks.onDcbEventLogCreated, hook => hook(dcbEventLog));

package/src/plugin/component/Plugin_Structure.res

@@ -1282,6 +1282,13 @@ let make = (
     | Checked(failures) => failures->Array.forEach(f => retiredFailures->Array.push(f)->ignore)
     }
 
+  // Warned rather than refused: an unkeyed view still answers, just without a
+  // filter or an ordering, and a lint that stops a deploy gets silenced.
+  let recordKeyField = (~entityName, stateSchema) =>
+    GraphQL_FragmentGenerator.classifyKeyField(~entityName, stateSchema)
+    ->GraphQL_FragmentGenerator.keyFieldGapMessage
+    ->Option.forEach(why => log.warn(~comp="Plugin_Structure", `${name}/${entityName} ${why}`))
+
   let readModelDefs =
     readModels
     ->Array.map((
@@ -1300,6 +1307,7 @@ let make = (
       let consumed = qualify(~prefix=name, R.consumedEventNames)
       recordRetired(~entityName=R.Spec.name, stateSchema)
       recordLifecycle(~entityName=R.Spec.name, stateSchema)
+      recordKeyField(~entityName=R.Spec.name, stateSchema)
       ({
         Reventless.Plugin.name: R.Spec.name,
         queryField: qf.listFieldName,
@@ -1340,6 +1348,7 @@ let make = (
       )
       recordRetired(~entityName=SVS.Spec.name, stateSchema)
       recordLifecycle(~entityName=SVS.Spec.name, stateSchema)
+      recordKeyField(~entityName=SVS.Spec.name, stateSchema)
       ({
         Reventless.Plugin.name: SVS.Spec.name,
         queryField: qf.listFieldName,
@@ -1452,6 +1461,10 @@ let make = (
       targetName: OTS.Spec.targetName,
       externalSystem: OTS.Spec.externalSystem,
       chapter: chapterOf(OTS.Spec.name),
+      // Published verbatim, `[]` included: `[]` is the declared default meaning
+      // this plugin's own DCB log, and resolving it here to a derived name would
+      // be a second place that name is spelled.
+      consumedSources: Some(OTS.Spec.sourceNames),
     }: Reventless.Plugin.outboundTranslationSliceDef))
 
   // ── Inbound translation slices ────────────────────────────────────────────

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

@@ -962,6 +962,7 @@ function make(name, aggregatesOpt, readModelsOpt, stateViewSlicesOpt, stateChang
       retiredFailures.push(f);
     });
   };
+  let recordKeyField = (entityName, stateSchema) => Stdlib_Option.forEach(GraphQL_FragmentGenerator$ReventlessCore.keyFieldGapMessage(GraphQL_FragmentGenerator$ReventlessCore.classifyKeyField(entityName, stateSchema)), why => log.warn("Plugin_Structure", undefined, name + `/` + entityName + ` ` + why));
   let readModelDefs = readModels.map(R => {
     let qf = Api_Naming$ReventlessCore.queryFieldNamesForReadModel(name, R.Spec.name, undefined);
     let stateSchema = R.Spec.stateSchema;
@@ -970,6 +971,7 @@ function make(name, aggregatesOpt, readModelsOpt, stateViewSlicesOpt, stateChang
     let consumed = qualify(name, R.consumedEventNames);
     recordRetired(R.Spec.name, stateSchema);
     recordLifecycle(R.Spec.name, stateSchema);
+    recordKeyField(R.Spec.name, stateSchema);
     return {
       name: R.Spec.name,
       queryField: qf.listFieldName,
@@ -1001,6 +1003,7 @@ function make(name, aggregatesOpt, readModelsOpt, stateViewSlicesOpt, stateChang
     let keyField = GraphQL_FragmentGenerator$ReventlessCore.resolveKeyField(SVS.Spec.name, stateSchema);
     recordRetired(SVS.Spec.name, stateSchema);
     recordLifecycle(SVS.Spec.name, stateSchema);
+    recordKeyField(SVS.Spec.name, stateSchema);
     return {
       name: SVS.Spec.name,
       queryField: qf.listFieldName,
@@ -1071,7 +1074,8 @@ function make(name, aggregatesOpt, readModelsOpt, stateViewSlicesOpt, stateChang
     inboundCommandTypes: qualify(name, DcbTag$Reventless.extractAllVariantNames(OTS.Spec.inboundCommandSchema)),
     targetName: OTS.Spec.targetName,
     externalSystem: OTS.Spec.externalSystem,
-    chapter: componentChapters[OTS.Spec.name]
+    chapter: componentChapters[OTS.Spec.name],
+    consumedSources: OTS.Spec.sourceNames
   }));
   let inboundTranslationSliceDefs = inboundTranslationSlices.map(ITS => ({
     name: ITS.Spec.name,

package/tests/admin/AdminApiSchemaDriftTest.res

@@ -128,6 +128,7 @@ let outbound: outboundTranslationSliceDef = {
   targetName: Some("Shipment"),
   externalSystem: Some("Shipper"),
   chapter: Some("Fulfilment"),
+  consumedSources: Some(["OrderingDcbEventLog"]),
 }
 
 let inbound: inboundTranslationSliceDef = {

package/tests/admin/AdminApiSchemaDriftTest.res.mjs

@@ -199,13 +199,16 @@ let outbound_externalSystem = "Shipper";
 
 let outbound_chapter = "Fulfilment";
 
+let outbound_consumedSources = ["OrderingDcbEventLog"];
+
 let outbound = {
   name: "ToShipper",
   consumedEventTypes: outbound_consumedEventTypes,
   inboundCommandTypes: outbound_inboundCommandTypes,
   targetName: outbound_targetName,
   externalSystem: outbound_externalSystem,
-  chapter: outbound_chapter
+  chapter: outbound_chapter,
+  consumedSources: outbound_consumedSources
 };
 
 let inbound_commandTypes = ["RecordPayment"];

package/tests/admin/Platform_ComponentDefinitionsApiTest.res

@@ -77,6 +77,7 @@ let structure: pluginStructure = {
       targetName: None,
       externalSystem: None,
       chapter: None,
+      consumedSources: None,
     },
   ],
   inboundTranslationSlices: [
@@ -227,6 +228,7 @@ describe("translation-slice externalSystem round-trip", () => {
         targetName: None,
         externalSystem: Some("ShipperGateway"),
         chapter: None,
+        consumedSources: None,
       },
     ],
     inboundTranslationSlices: [

package/tests/admin/Platform_ComponentDefinitionsApiTest.res.mjs

@@ -118,7 +118,8 @@ let structure_outboundTranslationSlices = [{
     inboundCommandTypes: ["Ship"],
     targetName: undefined,
     externalSystem: undefined,
-    chapter: undefined
+    chapter: undefined,
+    consumedSources: undefined
   }];
 
 let structure_inboundTranslationSlices = [{
@@ -245,7 +246,8 @@ globalThis.describe("translation-slice externalSystem round-trip", () => {
       inboundCommandTypes: ["Ship"],
       targetName: undefined,
       externalSystem: "ShipperGateway",
-      chapter: undefined
+      chapter: undefined,
+      consumedSources: undefined
     }];
   let externalStructure_inboundTranslationSlices = [{
       name: "FromBilling",

package/tests/admin/Platform_PluginStructuresApiTest.res

@@ -183,4 +183,36 @@ describe("absent optional collections", () => {
   testSync("encodes absent requiredStores as null", () =>
     expect(bareJson->String.includes("\"requiredStores\":null"))->toEqual(true)
   )
+
+  // The case the frozen corpus cannot reach: every fixture in it carries
+  // `"outboundTranslationSlices":[]`, so no stored payload has an outbound slice
+  // to be missing a field. A structure written before `consumedSources` existed
+  // has no such key, and the schema alone refuses it — `S.nullAsOption` is
+  // `T | null`, and the variant that also accepts `undefined` fails sury's
+  // jsonable validation inside a union payload, which is where a structure
+  // travels. `parseJsonTolerant` is what makes the absence survivable, and it is
+  // the path the Plugin aggregate replays through.
+  testSync("an outbound slice stored before consumedSources existed still replays", () =>
+    expect(
+      (
+        `{"name":"ToShipper","consumedEventTypes":[],"inboundCommandTypes":[],` ++
+        `"targetName":null,"externalSystem":null,"chapter":null}`
+      )
+      ->JSON.parseOrThrow
+      ->Reventless.Message.parseJsonTolerant(outboundTranslationSliceDefSchema)
+      ->(slice => slice.consumedSources),
+    )->toEqual(None)
+  )
+
+  testSync("an explicit null decodes as None", () =>
+    expect(
+      (
+        `{"name":"ToShipper","consumedEventTypes":[],"inboundCommandTypes":[],` ++
+        `"targetName":null,"externalSystem":null,"chapter":null,"consumedSources":null}`
+      )
+      ->JSON.parseOrThrow
+      ->Reventless.Util_Sury.fromJson(outboundTranslationSliceDefSchema)
+      ->(slice => slice.consumedSources),
+    )->toEqual(None)
+  )
 })

package/tests/admin/Platform_PluginStructuresApiTest.res.mjs

@@ -4,6 +4,9 @@ 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 Plugin$Reventless from "@reventlessdev/reventless-spec/src/components/Plugin.res.mjs";
+import * as Message$Reventless from "@reventlessdev/reventless-spec/src/types/Message.res.mjs";
+import * as Util_Sury$Reventless from "@reventlessdev/reventless-spec/src/util/Util_Sury.res.mjs";
 import * as Platform_PluginStructuresApi$ReventlessCore from "../../src/admin/Platform_PluginStructuresApi.res.mjs";
 
 let publicRm_consumedEventTypes = ["ProductAdded"];
@@ -237,6 +240,12 @@ globalThis.describe("absent optional collections", () => {
   globalThis.test("encodes absent requiredStores as null", () => {
     globalThis.expect(bareJson.includes("\"requiredStores\":null")).toEqual(true);
   });
+  globalThis.test("an outbound slice stored before consumedSources existed still replays", () => {
+    globalThis.expect(Message$Reventless.parseJsonTolerant(JSON.parse(`{"name":"ToShipper","consumedEventTypes":[],"inboundCommandTypes":[],"targetName":null,"externalSystem":null,"chapter":null}`), Plugin$Reventless.outboundTranslationSliceDefSchema).consumedSources).toEqual(undefined);
+  });
+  globalThis.test("an explicit null decodes as None", () => {
+    globalThis.expect(Util_Sury$Reventless.fromJson(JSON.parse(`{"name":"ToShipper","consumedEventTypes":[],"inboundCommandTypes":[],"targetName":null,"externalSystem":null,"chapter":null,"consumedSources":null}`), Plugin$Reventless.outboundTranslationSliceDefSchema).consumedSources).toEqual(undefined);
+  });
 });
 
 export {

package/tests/api/GraphQL_FragmentGeneratorTest.res

@@ -139,6 +139,53 @@ describe("resolveKeyField — the ladder", () => {
   })
 })
 
+// Losing the key is invisible — the view keeps every field and every row, and
+// drops its `<field>Eq` filter and its whole `orderBy` from the SDL. These pin
+// which of the two ways to lose it is worth saying out loud.
+describe("keyFieldGapMessage — which gap is worth a warning", () => {
+  let gapFor = (~entityName, schema) =>
+    GraphQL_FragmentGenerator.classifyKeyField(~entityName, schema->S.castToUnknown)
+    ->GraphQL_FragmentGenerator.keyFieldGapMessage
+
+  // The accident §14b.2 named: the view had `productId` alone and somebody added
+  // `categoryId`, so `sole` stopped firing and the name matches neither.
+  testSync("a second `*Id` field taking the key away is named, with both fields", () => {
+    let schema = S.schema(s =>
+      {"productId": s.matches(S.string), "categoryId": s.matches(S.string)}
+    )
+    let message = gapFor(~entityName="ProductDemand", schema)->Option.getOr("")
+    expect(message->String.includes("productId, categoryId"))->toBe(true)
+    expect(message->String.includes("productDemandId"))->toBe(true)
+  })
+
+  // A read model over an aggregate keeps the row's id on the row key, not in its
+  // state. Warning here would fire on most of them and get the rule silenced —
+  // six views across the example plugins are exactly this shape.
+  testSync("a state with no `*Id` field at all is silent, not warned about", () =>
+    expect(
+      gapFor(
+        ~entityName="Customers",
+        S.schema(s => {"email": s.matches(S.string), "address": s.matches(S.string)}),
+      ),
+    )->toEqual(None)
+  )
+
+  testSync("a resolved key says nothing", () =>
+    expect(
+      gapFor(~entityName="Orders", S.schema(s => {"orderId": s.matches(S.string)})),
+    )->toEqual(None)
+  )
+
+  testSync("an @id-less view whose name picks one of its `*Id` fields is fine", () =>
+    expect(
+      gapFor(
+        ~entityName="Products",
+        S.schema(s => {"productId": s.matches(S.string), "categoryId": s.matches(S.string)}),
+      ),
+    )->toEqual(None)
+  )
+})
+
 describe("deriveServerCapability — inferred keys reach the SDL surface", () => {
   let capabilityFor = (~entityName, schema) =>
     GraphQL_FragmentGenerator.deriveServerCapability(~entityName, schema->S.castToUnknown)

package/tests/api/GraphQL_FragmentGeneratorTest.res.mjs

@@ -148,6 +148,38 @@ globalThis.describe("resolveKeyField — the ladder", () => {
   });
 });
 
+globalThis.describe("keyFieldGapMessage — which gap is worth a warning", () => {
+  globalThis.test("a second `*Id` field taking the key away is named, with both fields", () => {
+    let schema = Sury.$schema(s => ({
+      productId: s.m(Sury.string),
+      categoryId: s.m(Sury.string)
+    }));
+    let message = Stdlib_Option.getOr(GraphQL_FragmentGenerator$ReventlessCore.keyFieldGapMessage(GraphQL_FragmentGenerator$ReventlessCore.classifyKeyField("ProductDemand", schema)), "");
+    globalThis.expect(message.includes("productId, categoryId")).toBe(true);
+    globalThis.expect(message.includes("productDemandId")).toBe(true);
+  });
+  globalThis.test("a state with no `*Id` field at all is silent, not warned about", () => {
+    let schema = Sury.$schema(s => ({
+      email: s.m(Sury.string),
+      address: s.m(Sury.string)
+    }));
+    globalThis.expect(GraphQL_FragmentGenerator$ReventlessCore.keyFieldGapMessage(GraphQL_FragmentGenerator$ReventlessCore.classifyKeyField("Customers", schema))).toEqual(undefined);
+  });
+  globalThis.test("a resolved key says nothing", () => {
+    let schema = Sury.$schema(s => ({
+      orderId: s.m(Sury.string)
+    }));
+    globalThis.expect(GraphQL_FragmentGenerator$ReventlessCore.keyFieldGapMessage(GraphQL_FragmentGenerator$ReventlessCore.classifyKeyField("Orders", schema))).toEqual(undefined);
+  });
+  globalThis.test("an @id-less view whose name picks one of its `*Id` fields is fine", () => {
+    let schema = Sury.$schema(s => ({
+      productId: s.m(Sury.string),
+      categoryId: s.m(Sury.string)
+    }));
+    globalThis.expect(GraphQL_FragmentGenerator$ReventlessCore.keyFieldGapMessage(GraphQL_FragmentGenerator$ReventlessCore.classifyKeyField("Products", schema))).toEqual(undefined);
+  });
+});
+
 globalThis.describe("deriveServerCapability — inferred keys reach the SDL surface", () => {
   globalThis.test("an inferred key yields an eq filter and a sort field", () => {
     let schema = Sury.$schema(s => ({

package/tests/api/SuryToJsonSchemaTest.res

@@ -119,6 +119,78 @@ describe("SuryToJsonSchema:", () => {
     })
   })
 
+  describe("deriveObjectSchema with a sensitive field:", () => {
+    let sensitiveOf = (json, name) =>
+      getPropertyOf(json, name)->Option.flatMap(s => getProperty(s, "x-reventless-sensitive"))
+    let ownerOf = (json, name) =>
+      getPropertyOf(json, name)->Option.flatMap(s => getProperty(s, "x-reventless-owner"))
+
+    let json = SuryToJsonSchema.deriveObjectSchema(
+      S.schema(s =>
+        {
+          "resetToken": s.matches(Reventless.Sensitive.string),
+          "note": s.matches(S.string),
+          "contact": s.matches(Reventless.Email.schema),
+        }
+      )->S.castToUnknown,
+    )
+
+    testSync("the marked field carries x-reventless-sensitive", () =>
+      expect(sensitiveOf(json, "resetToken"))->toEqual(Some(JSON.Encode.bool(true)))
+    )
+
+    // The control. Absent means "not stated", and a reader that misses the
+    // marker renders the value — so a bug that marked everything would look like
+    // caution while a bug that marked nothing leaks. Both need catching, and
+    // only this assertion catches the first.
+    testSync("an unmarked string field carries nothing", () =>
+      expect(sensitiveOf(json, "note"))->toBe(None)
+    )
+
+    // A contact detail is sensitive whether or not anybody wrote it down: the
+    // whole meaning of the semantic is "how to reach a particular person".
+    testSync("an email field is sensitive with no annotation", () =>
+      expect(sensitiveOf(json, "contact"))->toEqual(Some(JSON.Encode.bool(true)))
+    )
+
+    testSync("the field is still a plain string on the wire", () =>
+      expect(
+        getPropertyOf(json, "resetToken")->Option.flatMap(s => getProperty(s, "type")),
+      )->toEqual(Some(JSON.Encode.string("string")))
+    )
+
+    // Same trap as the owner case, and worse in consequence: a reader that only
+    // inspects the outer schema answers "not sensitive" for an optional field,
+    // and the value goes into a message.
+    testSync("an optional sensitive field is still recognised", () => {
+      let optJson = SuryToJsonSchema.deriveObjectSchema(
+        S.schema(s =>
+          {
+            "resetToken": s.matches(S.option(Reventless.Sensitive.string)),
+          }
+        )->S.castToUnknown,
+      )
+      expect(sensitiveOf(optJson, "resetToken"))->toEqual(Some(JSON.Encode.bool(true)))
+    })
+
+    // The composition rule. `mark` wraps rather than replaces, so a field that
+    // is both an owner and sensitive keeps both — a marker that silently
+    // replaced the other would unscope a view or unmask a value.
+    testSync("sensitivity composes with ownership on one field", () => {
+      let bothJson = SuryToJsonSchema.deriveObjectSchema(
+        S.schema(s =>
+          {
+            "customerId": s.matches(Reventless.Sensitive.mark(Reventless.Owner.string)),
+          }
+        )->S.castToUnknown,
+      )
+      expect((sensitiveOf(bothJson, "customerId"), ownerOf(bothJson, "customerId")))->toEqual((
+        Some(JSON.Encode.bool(true)),
+        Some(JSON.Encode.bool(true)),
+      ))
+    })
+  })
+
   describe("deriveObjectSchema with stateAnnotations metadata:", () => {
     let withSpec = (schema, spec) =>
       schema->S.Metadata.set(~id=Reventless.StateAnnotations.stateAnnotationsId, spec)
@@ -927,6 +999,91 @@ describe("SuryToJsonSchema:", () => {
     })
   })
 
+  // A selection, not an input. The whole point of the id is that it travels the
+  // same channel as a store declaration and says something a store declaration
+  // cannot: the candidates are on the row, so nothing is provisioned for it.
+  describe("a member-reference field:", () => {
+    let targetOf = (json, name) =>
+      getPropertyOf(json, name)->Option.flatMap(s =>
+        getProperty(s, "x-reventless-semantic-target")
+      )
+
+    testSync("carries the collection, the view holding it, and what a member is", () => {
+      let json = SuryToJsonSchema.deriveObjectSchema(
+        S.schema(s =>
+          {
+            "productImage": s.matches(
+              Reventless.MemberRef.of_(
+                ~view="Products",
+                ~content=Reventless.Semantic.Id.imageRef,
+                ~field="productImages",
+              ),
+            ),
+          }
+        )->S.castToUnknown,
+      )
+      expect(
+        getPropertyOf(json, "productImage")->Option.flatMap(s =>
+          getProperty(s, "x-reventless-semantic")
+        ),
+      )->toEqual(Some(JSON.Encode.string("memberRef")))
+      expect(targetOf(json, "productImage"))->toEqual(
+        Some(
+          JSON.Encode.object(
+            Dict.fromArray([
+              ("field", JSON.Encode.string("productImages")),
+              ("view", JSON.Encode.string("Products")),
+              ("content", JSON.Encode.string("imageRef")),
+            ]),
+          ),
+        ),
+      )
+    })
+
+    // The second position: a declaration on a view's own state, where the
+    // collection is on the same record and naming a view would invite the reader
+    // to think another one could be meant.
+    testSync("omits the view where the collection is on this very record", () =>
+      expect(
+        targetOf(
+          SuryToJsonSchema.deriveObjectSchema(
+            S.schema(s =>
+              {"productImage": s.matches(Reventless.MemberRef.of_(~field="productImages"))}
+            )->S.castToUnknown,
+          ),
+          "productImage",
+        ),
+      )->toEqual(
+        Some(JSON.Encode.object(Dict.fromArray([("field", JSON.Encode.string("productImages"))]))),
+      )
+    )
+
+    // The assertion the whole design rests on, and the one a reader will want to
+    // see rather than infer: a `memberRef` field declares NO store, so the
+    // provisioning walk passes it by and no upload endpoint is bound. This is
+    // exactly what `imageRef` gets today, reached through a different payload.
+    testSync("declares no store, so nothing is provisioned for it", () =>
+      expect(
+        Reventless.StorageRef.getFieldStore(
+          Reventless.MemberRef.of_(~view="Products", ~field="productImages"),
+        ),
+      )->toBe(None)
+    )
+
+    testSync("stays a plain string on the wire", () =>
+      expect(
+        getPropertyOf(
+          SuryToJsonSchema.deriveObjectSchema(
+            S.schema(s =>
+              {"productImage": s.matches(Reventless.MemberRef.of_(~field="productImages"))}
+            )->S.castToUnknown,
+          ),
+          "productImage",
+        )->Option.flatMap(s => getProperty(s, "type")),
+      )->toEqual(Some(JSON.Encode.string("string")))
+    )
+  })
+
   // The claim the branded scalars rest on: marking a field adds an annotation,
   // not a shape. A string stays a string and a number stays a number on the
   // wire, which is what makes them retrofittable onto a log that already has