@reventlessdev/reventless-core 3.0.0-alpha.244 → 3.0.0-alpha.246

package/CHANGELOG.md

@@ -3,6 +3,21 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# 3.0.0-alpha.246 (2026-08-21)
+
+### Bug Fixes
+
+* **core:** make @resolves/[@resolves](https://github.com/resolves)Many work end to end ([4c52957](https://github.com/ReventlessDev/reventless-core/commit/4c5295759dcb4b3eda4f0f4f2c1bc387fed88fcb))
+* **deps:** update sury to 11.0.0-rc.2 to fix unreachable union constructors ([fa5744f](https://github.com/ReventlessDev/reventless-core/commit/fa5744fed8de975e2f14725c856c6e5ce7d04a74))
+
+
+# 3.0.0-alpha.245 (2026-08-20)
+
+### Features
+
+* **core:** report a union value stored without its member type ([3a834b5](https://github.com/ReventlessDev/reventless-core/commit/3a834b51d1d9441f5dfcaebec5fac365063c905e))
+
+
 # 3.0.0-alpha.244 (2026-08-20)
 
 ### Bug Fixes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reventlessdev/reventless-core",
-  "version": "3.0.0-alpha.244",
+  "version": "3.0.0-alpha.246",
   "description": "Core package for Reventless framework",
   "license": "Apache-2.0",
   "jest": {
@@ -26,7 +26,7 @@
     }
   },
   "dependencies": {
-    "sury": "11.0.0-rc.1",
+    "sury": "11.0.0-rc.2",
     "uuid": "^13.0.0",
     "@reventlessdev/rescript-effect": "0.1.0-alpha.32",
     "@reventlessdev/rescript-fast-csv": "2.0.0-alpha.8",
@@ -36,13 +36,13 @@
     "@reventlessdev/rescript-pulumi-pulumi": "2.3.0-alpha.19",
     "@reventlessdev/rescript-ssh2": "2.0.0-alpha.8",
     "@reventlessdev/rescript-uuid": "2.0.0-alpha.0",
-    "@reventlessdev/reventless-infra": "3.0.0-alpha.148",
-    "@reventlessdev/reventless-spec": "3.0.0-alpha.120",
-    "@reventlessdev/reventless-interop": "3.0.0-alpha.32"
+    "@reventlessdev/reventless-infra": "3.0.0-alpha.149",
+    "@reventlessdev/reventless-interop": "3.0.0-alpha.33",
+    "@reventlessdev/reventless-spec": "3.0.0-alpha.121"
   },
   "devDependencies": {
     "rescript": "12.3.0",
-    "sury-ppx": "11.0.0-rc.1",
+    "sury-ppx": "11.0.0-rc.2",
     "@reventlessdev/reventless-ppx": "1.0.0-alpha.72"
   },
   "peerDependencies": {

package/src/components/Api/Api_Naming.res

@@ -128,6 +128,64 @@ let queryFieldNamesForReadModel = (~plugin: string, ~name: string, ~connectionSp
   }
 }
 
+// The GraphQL type a queryable is exposed as, from its spec name alone. Both
+// `queryFieldNamesFor*` above name it this way, so a `@resolves` target reached
+// by spec name lands on the same type whichever kind declares it.
+let returnTypeNameFor = (~plugin: string, ~name: string) =>
+  `${plugin}_${singularize(stripViewSuffix(name))}`
+
+/**
+The cross-table fields `@resolves` / `@resolvesMany` add to a queryable's object
+type, named for the SDL. `plugin` owns the declaring view.
+
+A target in another plugin is refused rather than emitted: under merged-API
+composition each plugin's document must be valid standalone, so a field
+returning a type the plugin does not define fails the merge — and on AWS the
+target table's `dynamodb:*` grant is attached to the *declaring* plugin's API
+role, so even a schema that merged would be refused at read time.
+*/
+let resolvedFieldsOfConfig = (
+  ~plugin: string,
+  config: Reventless.ReadModel.config,
+): array<ReventlessInfra.Api.resolvedFieldEntry> => {
+  let assertSamePlugin = (~pluginName: option<string>, ~tableName: string, ~fieldName: string) =>
+    switch pluginName {
+    | Some(p) if p != plugin =>
+      JsError.throwWithMessage(
+        `Field \`${fieldName}\` resolves to "${tableName}" in plugin "${p}", but cross-plugin ` ++
+        `resolvers are not supported: a plugin's GraphQL document must be valid standalone, and ` ++
+        `"${p}"'s table is not readable by "${plugin}"'s API role. Query the other view directly, ` ++
+        `or project the fields you need into this one.`,
+      )
+    | _ => ()
+    }
+  let single = config.idResolvers->Array.map(({source, target}) => {
+    let (fieldName, multi) = switch source.resolvedField {
+    | Single(f) => (f, false)
+    | Multi(f) => (f, true)
+    }
+    assertSamePlugin(~pluginName=target.pluginName, ~tableName=target.tableName, ~fieldName)
+    {
+      ReventlessInfra.Api.fieldName,
+      typeName: returnTypeNameFor(~plugin, ~name=target.tableName),
+      multi,
+    }
+  })
+  let many = config.idsResolvers->Array.map(({source, target}) => {
+    assertSamePlugin(
+      ~pluginName=target.pluginName,
+      ~tableName=target.tableName,
+      ~fieldName=source.resolvedField,
+    )
+    {
+      ReventlessInfra.Api.fieldName: source.resolvedField,
+      typeName: returnTypeNameFor(~plugin, ~name=target.tableName),
+      multi: true,
+    }
+  })
+  Array.concat(single, many)
+}
+
 let queryFieldNamesForStateView = (~plugin: string, ~viewName: string, ~connectionSpec: bool=true): queryNames => {
   let entity = stripViewSuffix(viewName)
   let singular = singularize(entity)

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

@@ -101,6 +101,48 @@ function queryFieldNamesForReadModel(plugin, name, connectionSpecOpt) {
   };
 }
 
+function returnTypeNameFor(plugin, name) {
+  return plugin + `_` + singularize(stripViewSuffix(name));
+}
+
+function resolvedFieldsOfConfig(plugin, config) {
+  let assertSamePlugin = (pluginName, tableName, fieldName) => {
+    if (pluginName !== undefined && pluginName !== plugin) {
+      return Stdlib_JsError.throwWithMessage(`Field \`` + fieldName + `\` resolves to "` + tableName + `" in plugin "` + pluginName + `", but cross-plugin resolvers are not supported: a plugin's GraphQL document must be valid standalone, and ` + (`"` + pluginName + `"'s table is not readable by "` + plugin + `"'s API role. Query the other view directly, `) + `or project the fields you need into this one.`);
+    }
+  };
+  let single = config.idResolvers.map(param => {
+    let target = param.target;
+    let f = param.source.resolvedField;
+    let match;
+    match = f.TAG === "Single" ? [
+        f._0,
+        false
+      ] : [
+        f._0,
+        true
+      ];
+    let fieldName = match[0];
+    assertSamePlugin(target.pluginName, target.tableName, fieldName);
+    return {
+      fieldName: fieldName,
+      typeName: returnTypeNameFor(plugin, target.tableName),
+      multi: match[1]
+    };
+  });
+  let many = config.idsResolvers.map(param => {
+    let target = param.target;
+    let source = param.source;
+    assertSamePlugin(target.pluginName, target.tableName, source.resolvedField);
+    return {
+      fieldName: source.resolvedField,
+      typeName: returnTypeNameFor(plugin, target.tableName),
+      multi: true
+    };
+  });
+  return single.concat(many);
+}
+
 function queryFieldNamesForStateView(plugin, viewName, connectionSpecOpt) {
   let connectionSpec = connectionSpecOpt !== undefined ? connectionSpecOpt : true;
   let entity = stripViewSuffix(viewName);
@@ -147,6 +189,8 @@ export {
   sliceMutationFieldFor,
   canonicalPlural,
   queryFieldNamesForReadModel,
+  returnTypeNameFor,
+  resolvedFieldsOfConfig,
   queryFieldNamesForStateView,
   queryFieldNamesForSliceQueryDb,
   adminField,

package/src/components/Api/GraphQL_FragmentGenerator.res

@@ -170,10 +170,18 @@ let reportUnclassifiedUnions = (~typeName: string, schema: S.t<unknown>): unit =
     )
   )
 
+// The SDL line for one `@resolves` / `@resolvesMany` field. Both forms are
+// nullable: the single form has no row when the foreign key names one that was
+// never written, and the batch form drops missing ids rather than padding with
+// nulls, so the list is shorter — never null inside.
+let resolvedFieldSdl = ({fieldName, typeName, multi}: resolvedFieldEntry): string =>
+  multi ? `  ${fieldName}: [${typeName}!]` : `  ${fieldName}: ${typeName}`
+
 let deriveObjectTypeWithNested = (
   ~typeName: string,
   ~excludeFields: array<string>=[],
   ~includeIdParam: bool=true,
+  ~resolvedFields: array<resolvedFieldEntry>=[],
   schema: S.t<unknown>,
 ): array<string> => {
   reportUnclassifiedUnions(~typeName, schema)
@@ -219,7 +227,24 @@ let deriveObjectTypeWithNested = (
     } else {
       mainType
     }
-    Array.concat(collectedTypes, [mainTypeWithId])
+    // A cross-table field shares the type with the state record's own fields, so
+    // a name already taken would emit the field twice and fail the whole document
+    // — for every plugin in the merge, not just this one. Refuse at build time,
+    // naming both halves.
+    resolvedFields->Array.forEach(({fieldName}) =>
+      if filteredFields->Dict.get(fieldName)->Option.isSome || (includeIdParam && fieldName == "id") {
+        JsError.throwWithMessage(
+          `${typeName}.${fieldName} is declared by @resolves/@resolvesMany and is already a field of the state record. Name the resolved field something the state does not use.`,
+        )
+      }
+    )
+    let mainTypeComplete = if resolvedFields->Array.length == 0 {
+      mainTypeWithId
+    } else {
+      let body = mainTypeWithId->String.slice(~start=0, ~end=mainTypeWithId->String.length - 1)
+      body ++ resolvedFields->Array.map(resolvedFieldSdl)->Array.join("\n") ++ "\n}"
+    }
+    Array.concat(collectedTypes, [mainTypeComplete])
   | None => []
   }
 }
@@ -763,6 +788,40 @@ let generate = (
     }
   })
 
+  // Two things a cross-table field has to satisfy, both checked before anything
+  // is emitted so the report names the declaration rather than the merge:
+  //
+  // The type it returns has to be one this fragment defines. A plugin's document
+  // is validated standalone before it is merged, and a field returning a name
+  // nothing declares fails the whole document rather than just the field.
+  //
+  // And the target has to be guarded the way the parent is. A nested field is
+  // reached through its parent, so it answers under the parent's authorization —
+  // a target that guards itself differently would be handed over by the wider
+  // door, which is the kind of hole nothing downstream can see. Equal rules pass,
+  // and so does a target open to everyone, which can only narrow.
+  let permissionOf = (entry: querySchemaEntry) =>
+    entry.permission->Option.getOr(Reventless.Authorization.AllowAuthenticated)
+  queryEntries->Array.forEach(entry =>
+    entry.resolvedFields
+    ->Option.getOr([])
+    ->Array.forEach(({fieldName, typeName}) =>
+      switch queryEntries->Array.find(e => e.returnTypeName == typeName) {
+      | None =>
+        JsError.throwWithMessage(
+          `${entry.returnTypeName}.${fieldName} is declared by @resolves/@resolvesMany and resolves to "${typeName}", which this plugin does not expose as a queryable. The target must be a ReadModel or StateViewSlice of the same plugin, named by its spec name.`,
+        )
+      | Some(target) =>
+        let targetPermission = permissionOf(target)
+        if targetPermission != permissionOf(entry) && targetPermission != AllowAnonymous {
+          JsError.throwWithMessage(
+            `${entry.returnTypeName}.${fieldName} resolves to "${typeName}", which declares a different authorization. A cross-table field is read through its parent and would answer under ${entry.returnTypeName}'s rule, handing over rows ${typeName}'s own door withholds. Give the two views the same authorization, or query ${typeName} directly.`,
+          )
+        }
+      }
+    )
+  )
+
   queryEntries->Array.forEach(entry => {
     let includeIdParam = entry.includeIdParam->Option.getOr(true)
     let connectionSpec = entry.connectionSpec->Option.getOr(true)
@@ -776,6 +835,7 @@ let generate = (
         ~typeName=entry.returnTypeName,
         ~excludeFields,
         ~includeIdParam,
+        ~resolvedFields=entry.resolvedFields->Option.getOr([]),
         entry.stateSchema,
       )
       nestedTypes->Array.forEach(t => {

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

@@ -3,6 +3,8 @@
 import * as Stdlib_Array from "@rescript/runtime/lib/es6/Stdlib_Array.js";
 import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
 import * as Stdlib_String from "@rescript/runtime/lib/es6/Stdlib_String.js";
+import * as Stdlib_JsError from "@rescript/runtime/lib/es6/Stdlib_JsError.js";
+import * as Primitive_object from "@rescript/runtime/lib/es6/Primitive_object.js";
 import * as Logger$ReventlessCore from "../../util/Logger.res.mjs";
 import * as Api_Naming$ReventlessCore from "./Api_Naming.res.mjs";
 import * as SchemaType$ReventlessCore from "./SchemaType.res.mjs";
@@ -129,9 +131,20 @@ function reportUnclassifiedUnions(typeName, schema) {
   SchemaType$ReventlessCore.unclassifiedUnions(schema).forEach(param => log.warn("GraphQL_FragmentGenerator", undefined, typeName + `.` + param.path + ` is emitted as String: ` + param.reason));
 }
 
-function deriveObjectTypeWithNested(typeName, excludeFieldsOpt, includeIdParamOpt, schema) {
+function resolvedFieldSdl(param) {
+  let typeName = param.typeName;
+  let fieldName = param.fieldName;
+  if (param.multi) {
+    return `  ` + fieldName + `: [` + typeName + `!]`;
+  } else {
+    return `  ` + fieldName + `: ` + typeName;
+  }
+}
+
+function deriveObjectTypeWithNested(typeName, excludeFieldsOpt, includeIdParamOpt, resolvedFieldsOpt, schema) {
   let excludeFields = excludeFieldsOpt !== undefined ? excludeFieldsOpt : [];
   let includeIdParam = includeIdParamOpt !== undefined ? includeIdParamOpt : true;
+  let resolvedFields = resolvedFieldsOpt !== undefined ? resolvedFieldsOpt : [];
   reportUnclassifiedUnions(typeName, schema);
   let fields = SchemaType$ReventlessCore.fromSuryObject(typeName, schema);
   if (fields === undefined) {
@@ -158,7 +171,20 @@ function deriveObjectTypeWithNested(typeName, excludeFieldsOpt, includeIdParamOp
   seenTypes.add(typeName);
   let mainType = objectRefToGraphQL(undefined, typeName, filteredFields, collectedTypes, seenTypes);
   let mainTypeWithId = includeIdParam ? mainType.replace(`type ` + typeName + ` {\n`, `type ` + typeName + ` implements Node {\n  id: ID!\n`) : mainType;
-  return collectedTypes.concat([mainTypeWithId]);
+  resolvedFields.forEach(param => {
+    let fieldName = param.fieldName;
+    if (Stdlib_Option.isSome(filteredFields[fieldName]) || includeIdParam && fieldName === "id") {
+      return Stdlib_JsError.throwWithMessage(typeName + `.` + fieldName + ` is declared by @resolves/@resolvesMany and is already a field of the state record. Name the resolved field something the state does not use.`);
+    }
+  });
+  let mainTypeComplete;
+  if (resolvedFields.length === 0) {
+    mainTypeComplete = mainTypeWithId;
+  } else {
+    let body = mainTypeWithId.slice(0, mainTypeWithId.length - 1 | 0);
+    mainTypeComplete = body + resolvedFields.map(resolvedFieldSdl).join("\n") + "\n}";
+  }
+  return collectedTypes.concat([mainTypeComplete]);
 }
 
 function derivePluralWrapperType(pluralTypeName, singularTypeName) {
@@ -504,6 +530,20 @@ function generate(mutationEntries, queryEntries) {
         return;
     }
   });
+  queryEntries.forEach(entry => {
+    Stdlib_Option.getOr(entry.resolvedFields, []).forEach(param => {
+      let typeName = param.typeName;
+      let fieldName = param.fieldName;
+      let target = queryEntries.find(e => e.returnTypeName === typeName);
+      if (target === undefined) {
+        return Stdlib_JsError.throwWithMessage(entry.returnTypeName + `.` + fieldName + ` is declared by @resolves/@resolvesMany and resolves to "` + typeName + `", which this plugin does not expose as a queryable. The target must be a ReadModel or StateViewSlice of the same plugin, named by its spec name.`);
+      }
+      let targetPermission = Stdlib_Option.getOr(target.permission, "AllowAuthenticated");
+      if (Primitive_object.notequal(targetPermission, Stdlib_Option.getOr(entry.permission, "AllowAuthenticated")) && targetPermission !== "AllowAnonymous") {
+        return Stdlib_JsError.throwWithMessage(entry.returnTypeName + `.` + fieldName + ` resolves to "` + typeName + `", which declares a different authorization. A cross-table field is read through its parent and would answer under ` + entry.returnTypeName + `'s rule, handing over rows ` + typeName + `'s own door withholds. Give the two views the same authorization, or query ` + typeName + ` directly.`);
+      }
+    });
+  });
   queryEntries.forEach(entry => {
     let includeIdParam = Stdlib_Option.getOr(entry.includeIdParam, true);
     let connectionSpec = Stdlib_Option.getOr(entry.connectionSpec, true);
@@ -511,7 +551,7 @@ function generate(mutationEntries, queryEntries) {
       seenTypes.add(entry.returnTypeName);
       let fields = entry.excludeFields;
       let excludeFields = fields !== undefined ? fields : [];
-      let nestedTypes = deriveObjectTypeWithNested(entry.returnTypeName, excludeFields, includeIdParam, entry.stateSchema);
+      let nestedTypes = deriveObjectTypeWithNested(entry.returnTypeName, excludeFields, includeIdParam, Stdlib_Option.getOr(entry.resolvedFields, []), entry.stateSchema);
       nestedTypes.forEach(t => {
         types.push(t);
       });
@@ -606,6 +646,7 @@ export {
   objectRefToGraphQL,
   deriveFieldType,
   reportUnclassifiedUnions,
+  resolvedFieldSdl,
   deriveObjectTypeWithNested,
   derivePluralWrapperType,
   deriveConnectionTypes,

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

@@ -13,7 +13,7 @@ function inspectScalar(schema) {
 }
 
 function inspectObjectType(typeName, schema) {
-  let types = GraphQL_FragmentGenerator$ReventlessCore.deriveObjectTypeWithNested(typeName, undefined, undefined, schema);
+  let types = GraphQL_FragmentGenerator$ReventlessCore.deriveObjectTypeWithNested(typeName, undefined, undefined, undefined, schema);
   return types[types.length - 1 | 0];
 }
 
@@ -42,7 +42,7 @@ function inspectMutationFields(fieldPrefix, commandSchema) {
 }
 
 function inspectQueryFields(name, typeName, stateSchema) {
-  let types = GraphQL_FragmentGenerator$ReventlessCore.deriveObjectTypeWithNested(typeName, undefined, undefined, stateSchema);
+  let types = GraphQL_FragmentGenerator$ReventlessCore.deriveObjectTypeWithNested(typeName, undefined, undefined, undefined, stateSchema);
   let typeDef = types[types.length - 1 | 0];
   let singleQuery = GraphQL_FragmentGenerator$ReventlessCore.deriveObjectQueryField(name, typeName, undefined, undefined);
   let pluralName = name + "s";

package/src/components/Dcb/Dcb_Builder.res

@@ -1095,6 +1095,8 @@ module Make = (
           let subIdField = V.Spec.subIdConfig->Option.map(c => c.subIdField)
           let indexes = V.Spec.config.indexes
           let indexQueries = if indexes->Array.length > 0 {Some(indexes)} else {None}
+          let resolved = Api_Naming.resolvedFieldsOfConfig(~plugin=name, V.Spec.config)
+          let resolvedFields = if resolved->Array.length > 0 {Some(resolved)} else {None}
           {
             ReventlessInfra.Api.singleFieldName: qn.singleFieldName,
             listFieldName: qn.listFieldName,
@@ -1107,6 +1109,7 @@ module Make = (
             connectionSpec: true,
             subIdField: ?subIdField,
             indexQueries: ?indexQueries,
+            resolvedFields: ?resolvedFields,
           }
         })
 

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

@@ -603,6 +603,8 @@ function Make(DcbEventLogStorage) {
         let subIdField = Stdlib_Option.map(V.Spec.subIdConfig, c => c.subIdField);
         let indexes = V.Spec.config.indexes;
         let indexQueries = indexes.length !== 0 ? indexes : undefined;
+        let resolved = Api_Naming$ReventlessCore.resolvedFieldsOfConfig(name, V.Spec.config);
+        let resolvedFields = resolved.length !== 0 ? resolved : undefined;
         return {
           singleFieldName: qn.singleFieldName,
           listFieldName: qn.listFieldName,
@@ -614,7 +616,8 @@ function Make(DcbEventLogStorage) {
           includeIdParam: qn.includeIdParam,
           connectionSpec: true,
           subIdField: subIdField,
-          indexQueries: indexQueries
+          indexQueries: indexQueries,
+          resolvedFields: resolvedFields
         };
       });
       let automationEntries = automationSlices.map(A => {

package/src/components/QueryDb/QueryDb_Operations.res

@@ -1,3 +1,5 @@
+let log = Logger.fromEnv()
+
 module type Ops = {
   let jsonOps: QueryDb.operations<string, JSON.t>
 }
@@ -72,11 +74,53 @@ module Make = (ReadModelSpec: Reventless.ReadModel.Spec, Ops: Ops) => {
   // backends — and, unlike a read-time stamp, it is also on the row the live
   // change channel hands over as raw JSON. A view with no union field is walked
   // and left exactly as it was.
-  let stampUnionMembers = dict =>
+  // The union fields this view declares, read once. Empty for most views, and
+  // the whole diagnostic below costs nothing when it is.
+  let declaredUnionFields =
+    Reventless.TaggedUnion.fieldsOf(ReadModelSpec.stateSchema->S.castToUnknown)
+
+  // Logged once per instantiation, and unconditionally: "none" has to be
+  // distinguishable from "never instantiated", because a schema that resolves no
+  // union fields and a stamp that failed to run leave the same stored row.
+  log.debug(
+    ~comp="QueryDb",
+    `${ReadModelSpec.name}: union fields ${switch declaredUnionFields {
+      | [] => "none"
+      | fields =>
+        fields->Array.map(((f, n)) => `${f}:${n->Option.getOr("<unnamed>")}`)->Array.join(", ")
+      }}`,
+  )
+
+  // A union value stored without `__typename` is the failure D1 exists to
+  // prevent, and it is silent: the member resolves to null, the null takes its
+  // non-nullable parent, and a list loses the row rather than erroring. Nothing
+  // downstream can tell that from "no such row", so it is reported here — the
+  // one place that knows both the schema and the row.
+  let reportUnstamped = dict =>
+    declaredUnionFields->Array.forEach(((field, unionName)) =>
+      switch dict->Dict.get(field)->Option.flatMap(JSON.Decode.object) {
+      | Some(value) if value->Dict.get("TAG")->Option.isSome =>
+        if value->Dict.get(Reventless.TaggedUnion.typenameKey)->Option.isNone {
+          log.warn(
+            ~comp="QueryDb",
+            `${ReadModelSpec.name}.${field}: stored a union value with no ${Reventless.TaggedUnion.typenameKey} ` ++
+            `(union ${unionName->Option.getOr("<unnamed>")}). The field will resolve to null and take its ` ++
+            `parent with it. Union fields seen on this spec: ${declaredUnionFields
+              ->Array.map(((f, _)) => f)
+              ->Array.join(", ")}`,
+          )
+        }
+      | _ => ()
+      }
+    )
+
+  let stampUnionMembers = dict => {
     Reventless.TaggedUnion.stampInto(
       ~schema=ReadModelSpec.stateSchema->S.castToUnknown,
       JSON.Encode.object(dict),
     )
+    reportUnstamped(dict)
+  }
 
   let save = async (id, state, saveMode, ttl) =>
     switch state->Message.encode(ReadModelSpec.stateSchema)->JSON.Decode.object {

package/src/components/QueryDb/QueryDb_Operations.res.mjs

@@ -7,9 +7,12 @@ import * as Stdlib_Result from "@rescript/runtime/lib/es6/Stdlib_Result.js";
 import * as Effect from "effect/Effect";
 import * as Stream from "effect/Stream";
 import * as Primitive_exceptions from "@rescript/runtime/lib/es6/Primitive_exceptions.js";
+import * as Logger$ReventlessCore from "../../util/Logger.res.mjs";
 import * as Message$ReventlessCore from "../../Message.res.mjs";
 import * as TaggedUnion$Reventless from "@reventlessdev/reventless-spec/src/components/TaggedUnion.res.mjs";
 
+let log = Logger$ReventlessCore.fromEnv();
+
 function Make(ReadModelSpec) {
   return Ops => {
     let decode = (id, stateJson) => {
@@ -77,14 +80,30 @@ function Make(ReadModelSpec) {
         dict[attrName$1] = value$1;
       });
     };
-    let stampUnionMembers = dict => TaggedUnion$Reventless.stampInto(ReadModelSpec.stateSchema, dict);
+    let declaredUnionFields = TaggedUnion$Reventless.fieldsOf(ReadModelSpec.stateSchema);
+    log.debug("QueryDb", undefined, ReadModelSpec.name + `: union fields ` + (
+      declaredUnionFields.length !== 0 ? declaredUnionFields.map(param => param[0] + `:` + Stdlib_Option.getOr(param[1], "<unnamed>")).join(", ") : "none"
+    ));
+    let reportUnstamped = dict => {
+      declaredUnionFields.forEach(param => {
+        let field = param[0];
+        let value = Stdlib_Option.flatMap(dict[field], Stdlib_JSON.Decode.object);
+        if (value !== undefined && Stdlib_Option.isSome(value["TAG"]) && Stdlib_Option.isNone(value[TaggedUnion$Reventless.typenameKey])) {
+          return log.warn("QueryDb", undefined, ReadModelSpec.name + `.` + field + `: stored a union value with no ` + TaggedUnion$Reventless.typenameKey + ` ` + (`(union ` + Stdlib_Option.getOr(param[1], "<unnamed>") + `). The field will resolve to null and take its `) + (`parent with it. Union fields seen on this spec: ` + declaredUnionFields.map(param => param[0]).join(", ")));
+        }
+      });
+    };
+    let stampUnionMembers = dict => {
+      TaggedUnion$Reventless.stampInto(ReadModelSpec.stateSchema, dict);
+      reportUnstamped(dict);
+    };
     let save = async (id, state, saveMode, ttl) => {
       let dict = Stdlib_JSON.Decode.object(Message$ReventlessCore.encode(state, ReadModelSpec.stateSchema));
       if (dict !== undefined) {
         dict["id"] = Message$ReventlessCore.encode(id, ReadModelSpec.Id.schema);
         injectSubId(dict, state);
         injectCompositeIndexAttrs(dict);
-        TaggedUnion$Reventless.stampInto(ReadModelSpec.stateSchema, dict);
+        stampUnionMembers(dict);
         return await Ops.jsonOps.save(ReadModelSpec.Id.toString(id), dict, saveMode, ttl);
       } else {
         return {
@@ -110,7 +129,7 @@ function Make(ReadModelSpec) {
             dict["id"] = Message$ReventlessCore.encode(id, ReadModelSpec.Id.schema);
             injectSubId(dict, state);
             injectCompositeIndexAttrs(dict);
-            TaggedUnion$Reventless.stampInto(ReadModelSpec.stateSchema, dict);
+            stampUnionMembers(dict);
             return {
               TAG: "Ok",
               _0: batch.concat([[
@@ -154,6 +173,8 @@ function Make(ReadModelSpec) {
       load: load,
       injectSubId: injectSubId,
       injectCompositeIndexAttrs: injectCompositeIndexAttrs,
+      declaredUnionFields: declaredUnionFields,
+      reportUnstamped: reportUnstamped,
       stampUnionMembers: stampUnionMembers,
       save: save,
       saveBatch: saveBatch,
@@ -165,6 +186,7 @@ function Make(ReadModelSpec) {
 }
 
 export {
+  log,
   Make,
 }
-/* effect/Effect Not a pure module */
+/* log Not a pure module */

package/src/plugin/component/Plugin_Builder.res

@@ -255,6 +255,7 @@ module Make = (
         // its SDL did not declare. The DCB and admin entries have populated this
         // all along; the omission here was the asymmetry, not the rule.
         let indexes = R.Spec.config.indexes
+        let resolvedFields = Api_Naming.resolvedFieldsOfConfig(~plugin=name, R.Spec.config)
         {
           ReventlessInfra.Api.singleFieldName: qn.singleFieldName,
           listFieldName: qn.listFieldName,
@@ -265,6 +266,7 @@ module Make = (
           connectionSpec: true,
           subIdField: ?subIdField,
           indexQueries: ?(indexes->Array.length > 0 ? Some(indexes) : None),
+          resolvedFields: ?(resolvedFields->Array.length > 0 ? Some(resolvedFields) : None),
         }
       })
 

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

@@ -196,6 +196,7 @@ function Make(Spec) {
           let qn = Api_Naming$ReventlessCore.queryFieldNamesForReadModel(extra$1, R.Spec.name, undefined);
           let subIdField = Stdlib_Option.map(R.Spec.subIdConfig, c => c.subIdField);
           let indexes = R.Spec.config.indexes;
+          let resolvedFields = Api_Naming$ReventlessCore.resolvedFieldsOfConfig(extra$1, R.Spec.config);
           return {
             singleFieldName: qn.singleFieldName,
             listFieldName: qn.listFieldName,
@@ -205,7 +206,8 @@ function Make(Spec) {
             permission: R.Spec.authorization,
             connectionSpec: true,
             subIdField: subIdField,
-            indexQueries: indexes.length !== 0 ? indexes : undefined
+            indexQueries: indexes.length !== 0 ? indexes : undefined,
+            resolvedFields: resolvedFields.length !== 0 ? resolvedFields : undefined
           };
         });
         let queryEntries = queryEntriesFromReadModels.concat(dcbResult.queryEntries);

package/tests/api/GraphQL_FragmentGeneratorTest.res

@@ -572,3 +572,144 @@ describe("@internal keeps a field off the generated type", () => {
     ))
   })
 })
+
+// `@resolves` / `@resolvesMany` add a field to a queryable's object type that the
+// state record does not carry — the row on the other side of a foreign key. The
+// PPX has written those configs into `config.idResolvers` / `config.idsResolvers`
+// all along and nothing emitted the field, so every backend provisioned a
+// resolver for a field its own schema never declared.
+
+module ResolvedFields = {
+  @schema
+  type product = {productId: string, name: string}
+
+  @schema
+  type order = {orderId: string, productId: string, productIds: array<string>}
+
+  let entries = (
+    ~resolvedFields,
+    ~targetPermission: option<Reventless.Authorization.permission>=?,
+  ): array<ReventlessInfra.Api.querySchemaEntry> => [
+    {
+      singleFieldName: "Catalog_Order",
+      listFieldName: "Catalog_Orders",
+      returnTypeName: "Catalog_Order",
+      stateSchema: orderSchema->S.castToUnknown,
+      authorization: None,
+      resolvedFields: ?resolvedFields,
+    },
+    {
+      singleFieldName: "Catalog_Product",
+      listFieldName: "Catalog_Products",
+      returnTypeName: "Catalog_Product",
+      stateSchema: productSchema->S.castToUnknown,
+      authorization: None,
+      permission: ?targetPermission,
+    },
+  ]
+
+  let bothFields: array<ReventlessInfra.Api.resolvedFieldEntry> = [
+    {fieldName: "product", typeName: "Catalog_Product", multi: false},
+    {fieldName: "products", typeName: "Catalog_Product", multi: true},
+  ]
+}
+
+describe("@resolves / @resolvesMany reach the SDL", () => {
+  let refused = f =>
+    try {
+      let _ = f()
+      false
+    } catch {
+    | _ => true
+    }
+
+  let orderType = (~resolvedFields, ~targetPermission=?) =>
+    GraphQL_Stitcher.decode(
+      GraphQL_FragmentGenerator.generate(
+        ~mutationEntries=[],
+        ~queryEntries=ResolvedFields.entries(~resolvedFields, ~targetPermission?),
+      ),
+    ).types
+    ->Array.find(t => t->String.startsWith("type Catalog_Order "))
+    ->Option.getOr("")
+
+  testSync("the single form returns the target's type", () =>
+    expect(
+      orderType(~resolvedFields=Some(ResolvedFields.bothFields))->String.includes(
+        "product: Catalog_Product",
+      ),
+    )->toBe(true)
+  )
+
+  // A list of non-null items rather than `[T]`: the batch read drops ids it did
+  // not find instead of padding the gap with nulls, so the field is shorter.
+  testSync("the batch form returns a list of the target's type", () =>
+    expect(
+      orderType(~resolvedFields=Some(ResolvedFields.bothFields))->String.includes(
+        "products: [Catalog_Product!]",
+      ),
+    )->toBe(true)
+  )
+
+  testSync("the state's own fields are untouched", () => {
+    let sdl = orderType(~resolvedFields=Some(ResolvedFields.bothFields))
+    expect((sdl->String.includes("orderId:"), sdl->String.includes("id: ID!")))->toEqual((
+      true,
+      true,
+    ))
+  })
+
+  // The control: without the entry the type is exactly what it was, which is what
+  // made the annotation inert rather than wrong.
+  testSync("a view that declares none gets no extra field", () =>
+    expect(orderType(~resolvedFields=None)->String.includes("Catalog_Product"))->toBe(false)
+  )
+
+  // A plugin's document is validated standalone before the merge, so a field
+  // returning a name nothing declares fails the whole document — every type in
+  // it, not just this field. Refused where the declaration is, naming it.
+  testSync("a target this plugin does not expose is refused", () =>
+    expect(
+      refused(() =>
+        orderType(
+          ~resolvedFields=Some([{fieldName: "supplier", typeName: "Supply_Supplier", multi: false}]),
+        )
+      ),
+    )->toBe(true)
+  )
+
+  // A nested field is read through its parent, so it answers under the parent's
+  // rule. A target guarded more narrowly than the view that embeds it would be
+  // handed over by the wider door.
+  testSync("a target guarded differently from the parent is refused", () =>
+    expect(
+      refused(() =>
+        orderType(
+          ~resolvedFields=Some(ResolvedFields.bothFields),
+          ~targetPermission=AllowGroups(["Admin"]),
+        )
+      ),
+    )->toBe(true)
+  )
+
+  // A target open to everyone can only narrow, so it needs no refusal.
+  testSync("a target open to everyone is allowed under an authenticated parent", () =>
+    expect(
+      refused(() =>
+        orderType(~resolvedFields=Some(ResolvedFields.bothFields), ~targetPermission=AllowAnonymous)
+      ),
+    )->toBe(false)
+  )
+
+  testSync("a resolved field colliding with a state field is refused", () =>
+    expect(
+      refused(() =>
+        orderType(
+          ~resolvedFields=Some([
+            {fieldName: "productId", typeName: "Catalog_Product", multi: false},
+          ]),
+        )
+      ),
+    )->toBe(true)
+  )
+})

package/tests/api/GraphQL_FragmentGeneratorTest.res.mjs

@@ -246,7 +246,7 @@ globalThis.describe("semantic composites are named once, not once per field", ()
     globalThis.expect(fragmentTypes.some(t => t.includes("AddProductPrice"))).toBe(false);
   });
   globalThis.test("the output position keeps the bare name", () => {
-    let types = GraphQL_FragmentGenerator$ReventlessCore.deriveObjectTypeWithNested("Catalog_Product", undefined, false, Sury.$schema(s => ({
+    let types = GraphQL_FragmentGenerator$ReventlessCore.deriveObjectTypeWithNested("Catalog_Product", undefined, false, undefined, Sury.$schema(s => ({
       productId: s.m(Sury.string),
       price: s.m(Money$Reventless.schema)
     })));
@@ -430,7 +430,7 @@ globalThis.describe("the by-index door", () => {
 });
 
 globalThis.describe("@internal keeps a field off the generated type", () => {
-  let types = excludeFields => GraphQL_FragmentGenerator$ReventlessCore.deriveObjectTypeWithNested("Platform_Widget", excludeFields, undefined, PsInternalFieldsReadModel$ReventlessCore.stateSchema).join("\n");
+  let types = excludeFields => GraphQL_FragmentGenerator$ReventlessCore.deriveObjectTypeWithNested("Platform_Widget", excludeFields, undefined, undefined, PsInternalFieldsReadModel$ReventlessCore.stateSchema).join("\n");
   globalThis.test("the declared fields are absent", () => {
     globalThis.expect([
       types(undefined).includes("eventCollector"),
@@ -471,6 +471,112 @@ globalThis.describe("@internal keeps a field off the generated type", () => {
   });
 });
 
+let productSchema = Sury.$schema(s => ({
+  productId: s.m(Sury.string),
+  name: s.m(Sury.string)
+}));
+
+let orderSchema = Sury.$schema(s => ({
+  orderId: s.m(Sury.string),
+  productId: s.m(Sury.string),
+  productIds: s.m(Sury.array(Sury.string))
+}));
+
+function entries(resolvedFields, targetPermission) {
+  return [
+    {
+      singleFieldName: "Catalog_Order",
+      listFieldName: "Catalog_Orders",
+      returnTypeName: "Catalog_Order",
+      stateSchema: orderSchema,
+      authorization: undefined,
+      resolvedFields: resolvedFields
+    },
+    {
+      singleFieldName: "Catalog_Product",
+      listFieldName: "Catalog_Products",
+      returnTypeName: "Catalog_Product",
+      stateSchema: productSchema,
+      authorization: undefined,
+      permission: targetPermission
+    }
+  ];
+}
+
+let bothFields = [
+  {
+    fieldName: "product",
+    typeName: "Catalog_Product",
+    multi: false
+  },
+  {
+    fieldName: "products",
+    typeName: "Catalog_Product",
+    multi: true
+  }
+];
+
+let ResolvedFields = {
+  productSchema: productSchema,
+  orderSchema: orderSchema,
+  entries: entries,
+  bothFields: bothFields
+};
+
+globalThis.describe("@resolves / @resolvesMany reach the SDL", () => {
+  let refused = f => {
+    try {
+      f();
+      return false;
+    } catch (exn) {
+      return true;
+    }
+  };
+  let orderType = (resolvedFields, targetPermission) => Stdlib_Option.getOr(GraphQL_Stitcher$ReventlessCore.decode(GraphQL_FragmentGenerator$ReventlessCore.generate([], entries(resolvedFields, targetPermission))).types.find(t => t.startsWith("type Catalog_Order ")), "");
+  globalThis.test("the single form returns the target's type", () => {
+    globalThis.expect(orderType(bothFields, undefined).includes("product: Catalog_Product")).toBe(true);
+  });
+  globalThis.test("the batch form returns a list of the target's type", () => {
+    globalThis.expect(orderType(bothFields, undefined).includes("products: [Catalog_Product!]")).toBe(true);
+  });
+  globalThis.test("the state's own fields are untouched", () => {
+    let sdl = orderType(bothFields, undefined);
+    globalThis.expect([
+      sdl.includes("orderId:"),
+      sdl.includes("id: ID!")
+    ]).toEqual([
+      true,
+      true
+    ]);
+  });
+  globalThis.test("a view that declares none gets no extra field", () => {
+    globalThis.expect(orderType(undefined, undefined).includes("Catalog_Product")).toBe(false);
+  });
+  globalThis.test("a target this plugin does not expose is refused", () => {
+    globalThis.expect(refused(() => orderType([{
+        fieldName: "supplier",
+        typeName: "Supply_Supplier",
+        multi: false
+      }], undefined))).toBe(true);
+  });
+  globalThis.test("a target guarded differently from the parent is refused", () => {
+    globalThis.expect(refused(() => orderType(bothFields, {
+      TAG: "AllowGroups",
+      _0: ["Admin"]
+    }))).toBe(true);
+  });
+  globalThis.test("a target open to everyone is allowed under an authenticated parent", () => {
+    globalThis.expect(refused(() => orderType(bothFields, "AllowAnonymous"))).toBe(false);
+  });
+  globalThis.test("a resolved field colliding with a state field is refused", () => {
+    globalThis.expect(refused(() => orderType([{
+        fieldName: "productId",
+        typeName: "Catalog_Product",
+        multi: false
+      }], undefined))).toBe(true);
+  });
+});
+
 export {
   OrderSliceCmd,
   mutationFor,
@@ -482,5 +588,6 @@ export {
   RefDoorRow,
   queryFor,
   refDoorFragment,
+  ResolvedFields,
 }
 /* commandSchema Not a pure module */