@reventlessdev/reventless-core 3.0.0-alpha.222 → 3.0.0-alpha.223

package/CHANGELOG.md

@@ -3,6 +3,16 @@
 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.223 (2026-08-10)
+
+### Bug Fixes
+
+* **core:** collect [@ref](https://github.com/ref) declared on an array field ([6f9e2fe](https://github.com/ReventlessDev/reventless-core/commit/6f9e2fef2568ad57a8bf2efbaa9cd4830a947f26))
+### Features
+
+* **admin:** carry Internal queryables on their own manifest field ([f5aa03d](https://github.com/ReventlessDev/reventless-core/commit/f5aa03d60b0b2554d116fe9b3784d30f2c4ef356))
+
+
 # 3.0.0-alpha.222 (2026-08-10)
 
 **Note:** Version bump only for package @reventlessdev/reventless-core

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reventlessdev/reventless-core",
-  "version": "3.0.0-alpha.222",
+  "version": "3.0.0-alpha.223",
   "description": "Core package for Reventless framework",
   "license": "Apache-2.0",
   "jest": {
@@ -33,12 +33,12 @@
     "@reventlessdev/rescript-hash-object": "1.2.0-alpha.14",
     "@reventlessdev/rescript-jest": "1.0.0-alpha.10",
     "@reventlessdev/rescript-node": "2.0.0-alpha.3",
+    "@reventlessdev/rescript-ssh2": "2.0.0-alpha.3",
     "@reventlessdev/rescript-pulumi-pulumi": "2.3.0-alpha.18",
     "@reventlessdev/rescript-uuid": "2.0.0-alpha.0",
-    "@reventlessdev/reventless-infra": "3.0.0-alpha.132",
-    "@reventlessdev/rescript-ssh2": "2.0.0-alpha.3",
     "@reventlessdev/reventless-interop": "3.0.0-alpha.30",
-    "@reventlessdev/reventless-spec": "3.0.0-alpha.106"
+    "@reventlessdev/reventless-infra": "3.0.0-alpha.133",
+    "@reventlessdev/reventless-spec": "3.0.0-alpha.107"
   },
   "devDependencies": {
     "rescript": "12.3.0",

package/src/admin/Platform_ComponentDefinitionsApi.res

@@ -30,7 +30,14 @@ let sdlTypes: array<string> = [
   `type Platform_OutboundTranslationSliceDef {\n  name: String!\n  consumedEventTypes: [String!]!\n  inboundCommandTypes: [String!]!\n  targetName: String\n  externalSystem: String\n  chapter: String\n}`,
   `type Platform_InboundTranslationSliceDef {\n  name: String!\n  commandTypes: [String!]!\n  targetName: String\n  externalSystem: String\n  chapter: String\n}`,
   `type Platform_ExtensionDef {\n  name: String!\n  delegateNames: [String!]!\n  eventTypes: [String!]!\n  commandTypes: [String!]!\n}`,
-  `type Platform_ComponentDefinitionEntry {\n  pluginId: String!\n  readModels: [Platform_ReadSideDef!]!\n  stateViewSlices: [Platform_ReadSideDef!]!\n  stateChangeSlices: [Platform_WriteSideDef!]!\n  aggregates: [Platform_WriteSideDef!]!\n  automationSlices: [Platform_AutomationSliceDef!]!\n  outboundTranslationSlices: [Platform_OutboundTranslationSliceDef!]!\n  inboundTranslationSlices: [Platform_InboundTranslationSliceDef!]!\n  extensions: [Platform_ExtensionDef!]!\n}`,
+  // `internalQueryables` is the complement of the `readModels` / `stateViewSlices`
+  // filter, not an addition to either: it carries exactly the components the
+  // filter removed. A consumer enumerating surfaces reads the two filtered lists
+  // and is structurally unable to turn an Internal view into a page; a consumer
+  // resolving a reference target reads all three. Keeping it a separate field is
+  // what makes that separation structural rather than a filter every enumeration
+  // site has to remember.
+  `type Platform_ComponentDefinitionEntry {\n  pluginId: String!\n  readModels: [Platform_ReadSideDef!]!\n  stateViewSlices: [Platform_ReadSideDef!]!\n  internalQueryables: [Platform_ReadSideDef!]!\n  stateChangeSlices: [Platform_WriteSideDef!]!\n  aggregates: [Platform_WriteSideDef!]!\n  automationSlices: [Platform_AutomationSliceDef!]!\n  outboundTranslationSlices: [Platform_OutboundTranslationSliceDef!]!\n  inboundTranslationSlices: [Platform_InboundTranslationSliceDef!]!\n  extensions: [Platform_ExtensionDef!]!\n}`,
 ]
 
 let sdlQueryField: string = `  Platform_ComponentDefinitions: [Platform_ComponentDefinitionEntry!]!`
@@ -75,6 +82,13 @@ let encodeCommandDef = (c: commandDef): JSON.t =>
 // Internal ReadModels / StateViewSlices are carried in pluginStructure for developer
 // tooling but must stay out of the deployed AutoUI — the menu, drill-down pages and
 // queryable defs are all derived from this response, so filter them here.
+//
+// Hidden from the menu is not the same question as denied as a reference target: a
+// denormalised lookup view is precisely the thing an author wants referenceable but
+// not navigable. The filtered lists answer the first question, `internalQueryables`
+// (below) answers the second. Neither is a security boundary — an Internal view
+// keeps its resolver and stays queryable, so naming it here publishes a fact the
+// caller is already entitled to.
 let isPublicQueryable = (q: queryableDef): bool => q.visibility != Some("Internal")
 
 let encodeQueryableDef = (r: queryableDef): JSON.t =>
@@ -190,6 +204,13 @@ let encodePluginStructureEntry = (~pluginId: string, def: pluginStructure): JSON
       ->Array.map(encodeQueryableDef)
       ->JSON.Encode.array,
     ),
+    (
+      "internalQueryables",
+      Array.concat(def.readModels, def.stateViewSlices)
+      ->Array.filter(q => !isPublicQueryable(q))
+      ->Array.map(encodeQueryableDef)
+      ->JSON.Encode.array,
+    ),
     ("stateChangeSlices", def.stateChangeSlices->Array.map(encodeWritableDef)->JSON.Encode.array),
     ("aggregates", def.aggregates->Array.map(encodeWritableDef)->JSON.Encode.array),
     (

package/src/admin/Platform_ComponentDefinitionsApi.res.mjs

@@ -15,7 +15,7 @@ let sdlTypes = [
   `type Platform_OutboundTranslationSliceDef {\n  name: String!\n  consumedEventTypes: [String!]!\n  inboundCommandTypes: [String!]!\n  targetName: String\n  externalSystem: String\n  chapter: String\n}`,
   `type Platform_InboundTranslationSliceDef {\n  name: String!\n  commandTypes: [String!]!\n  targetName: String\n  externalSystem: String\n  chapter: String\n}`,
   `type Platform_ExtensionDef {\n  name: String!\n  delegateNames: [String!]!\n  eventTypes: [String!]!\n  commandTypes: [String!]!\n}`,
-  `type Platform_ComponentDefinitionEntry {\n  pluginId: String!\n  readModels: [Platform_ReadSideDef!]!\n  stateViewSlices: [Platform_ReadSideDef!]!\n  stateChangeSlices: [Platform_WriteSideDef!]!\n  aggregates: [Platform_WriteSideDef!]!\n  automationSlices: [Platform_AutomationSliceDef!]!\n  outboundTranslationSlices: [Platform_OutboundTranslationSliceDef!]!\n  inboundTranslationSlices: [Platform_InboundTranslationSliceDef!]!\n  extensions: [Platform_ExtensionDef!]!\n}`
+  `type Platform_ComponentDefinitionEntry {\n  pluginId: String!\n  readModels: [Platform_ReadSideDef!]!\n  stateViewSlices: [Platform_ReadSideDef!]!\n  internalQueryables: [Platform_ReadSideDef!]!\n  stateChangeSlices: [Platform_WriteSideDef!]!\n  aggregates: [Platform_WriteSideDef!]!\n  automationSlices: [Platform_AutomationSliceDef!]!\n  outboundTranslationSlices: [Platform_OutboundTranslationSliceDef!]!\n  inboundTranslationSlices: [Platform_InboundTranslationSliceDef!]!\n  extensions: [Platform_ExtensionDef!]!\n}`
 ];
 
 function encodeStrings(ss) {
@@ -325,6 +325,10 @@ function encodePluginStructureEntry(pluginId, def) {
       "stateViewSlices",
       def.stateViewSlices.filter(isPublicQueryable).map(encodeQueryableDef)
     ],
+    [
+      "internalQueryables",
+      def.readModels.concat(def.stateViewSlices).filter(q => !Primitive_object.notequal(q.visibility, "Internal")).map(encodeQueryableDef)
+    ],
     [
       "stateChangeSlices",
       def.stateChangeSlices.map(encodeWritableDef)

package/src/plugin/component/Plugin_Structure.res

@@ -164,20 +164,29 @@ let labelFieldsFromStateSchema = (
 // because its components never pass through `make` — has to derive its defs the
 // same way, and a second copy of this walk would be free to drift from this one.
 
+// A variant's declared cross-entity references. Shared by the command and event
+// walks because the two ask the identical question of identical field dicts, and
+// the question is `getFieldTarget` rather than `getTarget`: a reference declared
+// on an `array<string>` field sits on the element schema. Collecting it in one
+// place is what stops one walk from being taught that and the other not.
+let extractReferences = (properties: dict<S.t<unknown>>): array<
+  Reventless.Plugin.fieldReference,
+> =>
+  properties
+  ->Dict.toArray
+  ->Array.filterMap(((fieldName, fieldSchema)) =>
+    Reventless.Reference.getFieldTarget(fieldSchema)->Option.map(target => (
+      {
+        Reventless.Plugin.fieldName,
+        entity: target.entity,
+        plugin: target.plugin,
+      }: Reventless.Plugin.fieldReference
+    ))
+  )
+
 let toEventDef = (v: S.t<unknown>): option<Reventless.Plugin.eventDef> => {
   let mkDef = (~variantName, ~properties) => {
-    let references =
-      properties
-      ->Dict.toArray
-      ->Array.filterMap(((fieldName, fieldSchema)) =>
-        Reventless.Reference.getTarget(fieldSchema)->Option.map(target => (
-          {
-            Reventless.Plugin.fieldName,
-            entity: target.entity,
-            plugin: target.plugin,
-          }: Reventless.Plugin.fieldReference
-        ))
-      )
+    let references = extractReferences(properties)
     ({
       Reventless.Plugin.name: variantName,
       // Derived for the same reason as `commandDef.schema`: an event's field
@@ -301,18 +310,7 @@ let make = (
     // `S.literal("Archive")` string rather than an `{TAG, ...}` object.
     let mkDef = (~variantName, ~properties) => {
       let (level, aggregateIdField) = commandLevelAndId(~isAggregate, ~variantName, properties)
-      let references =
-        properties
-        ->Dict.toArray
-        ->Array.filterMap(((fieldName, fieldSchema)) =>
-          Reventless.Reference.getTarget(fieldSchema)->Option.map(target => (
-            {
-              Reventless.Plugin.fieldName,
-              entity: target.entity,
-              plugin: target.plugin,
-            }: Reventless.Plugin.fieldReference
-          ))
-        )
+      let references = extractReferences(properties)
       // Per-variant `allowedStates` lives on the *parent* command schema
       // (the PPX attaches a single dict<variantName, [|states|]> via
       // markAllowedStates). Look it up by variant name; back-compat

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

@@ -140,16 +140,20 @@ function labelFieldsFromStateSchema(entityName, stateSchema) {
   };
 }
 
+function extractReferences(properties) {
+  return Stdlib_Array.filterMap(Object.entries(properties), param => {
+    let fieldName = param[0];
+    return Stdlib_Option.map(Reference$Reventless.getFieldTarget(param[1]), target => ({
+      fieldName: fieldName,
+      entity: target.entity,
+      plugin: target.plugin
+    }));
+  });
+}
+
 function toEventDef(v) {
   let mkDef = (variantName, properties) => {
-    let references = Stdlib_Array.filterMap(Object.entries(properties), param => {
-      let fieldName = param[0];
-      return Stdlib_Option.map(Reference$Reventless.getTarget(param[1]), target => ({
-        fieldName: fieldName,
-        entity: target.entity,
-        plugin: target.plugin
-      }));
-    });
+    let references = extractReferences(properties);
     return {
       name: variantName,
       schema: JSON.stringify(SuryToJsonSchema$ReventlessCore.deriveObjectSchema(v)),
@@ -267,14 +271,7 @@ function make(name, aggregatesOpt, readModelsOpt, stateViewSlicesOpt, stateChang
   let toCommandDef = (isAggregate, mutationFieldFor, parentSchema, v) => {
     let mkDef = (variantName, properties) => {
       let match = commandLevelAndId(isAggregate, variantName, properties);
-      let references = Stdlib_Array.filterMap(Object.entries(properties), param => {
-        let fieldName = param[0];
-        return Stdlib_Option.map(Reference$Reventless.getTarget(param[1]), target => ({
-          fieldName: fieldName,
-          entity: target.entity,
-          plugin: target.plugin
-        }));
-      });
+      let references = extractReferences(properties);
       let allowedStates = ApiAllowedStatesHelpers$ReventlessCore.getAllowedStates(parentSchema, variantName);
       let targetState = ApiTargetStateHelpers$ReventlessCore.getTargetState(parentSchema, variantName);
       let apiExposed = false;
@@ -653,6 +650,7 @@ export {
   statusFieldFromStateSchema,
   labelFieldSourceToString,
   labelFieldsFromStateSchema,
+  extractReferences,
   toEventDef,
   extractEventDefs,
   extractErrorDefs,

package/tests/admin/Platform_ComponentDefinitionsApiTest.res

@@ -106,6 +106,7 @@ describe("encodePluginStructureEntry", () => {
       "automationSlices",
       "extensions",
       "inboundTranslationSlices",
+      "internalQueryables",
       "outboundTranslationSlices",
       "pluginId",
       "readModels",
@@ -252,21 +253,68 @@ describe("visibility filtering (deployed AutoUI hides Internal)", () => {
     visibility: Some("Internal"),
     chapter: None,
   }
+  // A distinct name per source array: the complement has to be fed by both, and
+  // reusing one def would hide a version that only walks `readModels`.
+  let internalSlice: queryableDef = {
+    ...internalQbl,
+    name: "PendingShipments",
+    queryField: "Ordering_PendingShipments",
+  }
   let mixed: pluginStructure = {
     ...structure,
     readModels: [qbl, internalQbl],
-    stateViewSlices: [internalQbl],
+    stateViewSlices: [internalSlice],
   }
-  let mixedJson =
-    Platform_ComponentDefinitionsApi.encodePluginStructureEntry(~pluginId="Ordering", mixed)->JSON.stringify
+  let mixedEntry =
+    Platform_ComponentDefinitionsApi.encodePluginStructureEntry(~pluginId="Ordering", mixed)
+
+  // Names under one key of the encoded entry. `String.includes` over the whole
+  // JSON can no longer answer this: an Internal view is legitimately present
+  // under `internalQueryables`, so a whole-document search cannot tell "kept out
+  // of the surfaces" from "dropped entirely" — which is the distinction the
+  // feature is.
+  let namesAt = (entry: JSON.t, key: string): array<string> =>
+    entry
+    ->JSON.Decode.object
+    ->Option.flatMap(o => o->Dict.get(key))
+    ->Option.flatMap(JSON.Decode.array)
+    ->Option.getOr([])
+    ->Array.filterMap(c =>
+      c->JSON.Decode.object->Option.flatMap(o => o->Dict.get("name"))->Option.flatMap(JSON.Decode.string)
+    )
+
+  testSync("excludes an Internal queryableDef from the encoded read-side", () => {
+    expect(mixedEntry->namesAt("readModels"))->toEqual(["Products"])
+    expect(mixedEntry->namesAt("stateViewSlices"))->toEqual([])
+  })
 
-  testSync("excludes an Internal queryableDef from the encoded read-side", () =>
-    expect(mixedJson->String.includes("AvailableProducts"))->toEqual(false)
+  testSync("keeps a Public queryableDef", () =>
+    expect(mixedEntry->namesAt("readModels")->Array.includes("Products"))->toEqual(true)
   )
 
-  testSync("keeps a Public queryableDef", () =>
-    expect(mixedJson->String.includes("\"name\":\"Products\""))->toEqual(true)
+  // Both directions, deliberately: a change that also leaked Internal views back
+  // into the surface lists would pass a presence-only assertion.
+  testSync("carries what the filter removed on internalQueryables", () =>
+    expect(mixedEntry->namesAt("internalQueryables"))->toEqual([
+      "AvailableProducts",
+      "PendingShipments",
+    ])
   )
+
+  testSync("encodes internalQueryables as [] for an all-Public entry, not a missing key", () => {
+    let entry = Platform_ComponentDefinitionsApi.encodePluginStructureEntry(
+      ~pluginId="Ordering",
+      {...structure, readModels: [qbl], stateViewSlices: []},
+    )
+    expect(
+      entry->JSON.Decode.object->Option.flatMap(o => o->Dict.get("internalQueryables")),
+    )->toEqual(Some(JSON.Encode.array([])))
+  })
+
+  testSync("declares internalQueryables on the entry type in the SDL", () => {
+    let sdl = Platform_ComponentDefinitionsApi.sdlTypes->Array.join("\n")
+    expect(sdl->String.includes("internalQueryables: [Platform_ReadSideDef!]!"))->toEqual(true)
+  })
 })
 
 describe("allowedStates + statusField populated", () => {

package/tests/admin/Platform_ComponentDefinitionsApiTest.res.mjs

@@ -1,6 +1,7 @@
 // Generated by ReScript, PLEASE EDIT WITH CARE
 
 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 Platform_ComponentDefinitionsApi$ReventlessCore from "../../src/admin/Platform_ComponentDefinitionsApi.res.mjs";
@@ -146,6 +147,7 @@ globalThis.describe("encodePluginStructureEntry", () => {
       "automationSlices",
       "extensions",
       "inboundTranslationSlices",
+      "internalQueryables",
       "outboundTranslationSlices",
       "pluginId",
       "readModels",
@@ -268,11 +270,29 @@ globalThis.describe("visibility filtering (deployed AutoUI hides Internal)", ()
     visibility: internalQbl_visibility,
     chapter: undefined
   };
+  let internalSlice_consumedEventTypes = internalQbl_consumedEventTypes;
+  let internalSlice_linkedWriteSide = internalQbl_linkedWriteSide;
+  let internalSlice_searchableFields = internalQbl_searchableFields;
+  let internalSlice_labelFieldSource = "convention";
+  let internalSlice_visibility = "Internal";
+  let internalSlice = {
+    name: "PendingShipments",
+    queryField: "Ordering_PendingShipments",
+    schema: "{}",
+    consumedEventTypes: internalSlice_consumedEventTypes,
+    linkedWriteSide: internalSlice_linkedWriteSide,
+    labelField: "name",
+    searchableFields: internalSlice_searchableFields,
+    labelFieldSource: internalSlice_labelFieldSource,
+    statusField: undefined,
+    visibility: internalSlice_visibility,
+    chapter: undefined
+  };
   let mixed_readModels = [
     qbl,
     internalQbl
   ];
-  let mixed_stateViewSlices = [internalQbl];
+  let mixed_stateViewSlices = [internalSlice];
   let mixed_stateChangeSlices = structure_stateChangeSlices;
   let mixed_aggregates = structure_aggregates;
   let mixed_automationSlices = structure_automationSlices;
@@ -292,12 +312,40 @@ globalThis.describe("visibility filtering (deployed AutoUI hides Internal)", ()
     requiredStores: undefined,
     requiredStoreDeclarations: undefined
   };
-  let mixedJson = JSON.stringify(Platform_ComponentDefinitionsApi$ReventlessCore.encodePluginStructureEntry("Ordering", mixed));
+  let mixedEntry = Platform_ComponentDefinitionsApi$ReventlessCore.encodePluginStructureEntry("Ordering", mixed);
+  let namesAt = (entry, key) => Stdlib_Array.filterMap(Stdlib_Option.getOr(Stdlib_Option.flatMap(Stdlib_Option.flatMap(Stdlib_JSON.Decode.object(entry), o => o[key]), Stdlib_JSON.Decode.array), []), c => Stdlib_Option.flatMap(Stdlib_Option.flatMap(Stdlib_JSON.Decode.object(c), o => o["name"]), Stdlib_JSON.Decode.string));
   globalThis.test("excludes an Internal queryableDef from the encoded read-side", () => {
-    globalThis.expect(mixedJson.includes("AvailableProducts")).toEqual(false);
+    globalThis.expect(namesAt(mixedEntry, "readModels")).toEqual(["Products"]);
+    globalThis.expect(namesAt(mixedEntry, "stateViewSlices")).toEqual([]);
   });
   globalThis.test("keeps a Public queryableDef", () => {
-    globalThis.expect(mixedJson.includes("\"name\":\"Products\"")).toEqual(true);
+    globalThis.expect(namesAt(mixedEntry, "readModels").includes("Products")).toEqual(true);
+  });
+  globalThis.test("carries what the filter removed on internalQueryables", () => {
+    globalThis.expect(namesAt(mixedEntry, "internalQueryables")).toEqual([
+      "AvailableProducts",
+      "PendingShipments"
+    ]);
+  });
+  globalThis.test("encodes internalQueryables as [] for an all-Public entry, not a missing key", () => {
+    let entry = Platform_ComponentDefinitionsApi$ReventlessCore.encodePluginStructureEntry("Ordering", {
+      readModels: [qbl],
+      stateViewSlices: [],
+      stateChangeSlices: structure_stateChangeSlices,
+      aggregates: structure_aggregates,
+      automationSlices: structure_automationSlices,
+      outboundTranslationSlices: structure_outboundTranslationSlices,
+      inboundTranslationSlices: structure_inboundTranslationSlices,
+      extensions: structure_extensions,
+      extensionPoints: undefined,
+      requiredStores: undefined,
+      requiredStoreDeclarations: undefined
+    });
+    globalThis.expect(Stdlib_Option.flatMap(Stdlib_JSON.Decode.object(entry), o => o["internalQueryables"])).toEqual([]);
+  });
+  globalThis.test("declares internalQueryables on the entry type in the SDL", () => {
+    let sdl = Platform_ComponentDefinitionsApi$ReventlessCore.sdlTypes.join("\n");
+    globalThis.expect(sdl.includes("internalQueryables: [Platform_ReadSideDef!]!")).toEqual(true);
   });
 });
 

package/tests/plugin/PluginStructureTest.res

@@ -121,6 +121,20 @@ module PsChangePhotoSlice: ReventlessInfra.StateChangeSlice.T = {
   let make = (~dcbEventLog as _, ~publishJsons as _, ~tagKeysByEventType as _=?, ~crossPartitionTagKeys as _=?, ~runtime as _=?, ~opts as _=?): component => Obj.magic(0)
 }
 
+module PsReserveStockSlice: ReventlessInfra.StateChangeSlice.T = {
+  module Spec = PsReserveStock
+  module Behavior = {
+    type state = PsReserveStock.state
+    let initialState = PsReserveStock.initialState
+    let evolve = PsReserveStock.evolve
+    let decide = PsReserveStock.decide
+    let moduleUrl = PsReserveStock.moduleUrl
+  }
+  let isAsync = false
+  type component = scsComponent
+  let make = (~dcbEventLog as _, ~publishJsons as _, ~tagKeysByEventType as _=?, ~crossPartitionTagKeys as _=?, ~runtime as _=?, ~opts as _=?): component => Obj.magic(0)
+}
+
 let structure = Plugin_Structure.make(
   ~name="TestPlugin",
   ~stateChangeSlices=[module(PsPlaceOrderSlice), module(PsShipOrderSlice)],
@@ -960,4 +974,59 @@ describe("Plugin_Structure.make — Phase 2 graph fields", () => {
       )->toEqual([true, true, true, false, false])
     })
   })
+
+  // A plural reference is declared exactly like a singular one, and the ppx puts
+  // the marker where `Reference.to_` returns it: on the element schema, one level
+  // inside the array. Reading the field's own schema therefore answers "no
+  // reference" for every `@ref` array — and the consuming side treats a missing
+  // declaration as licence to guess, so the field resolves to whatever its name
+  // suggests instead of what the author wrote.
+  describe("plural references reach the manifest", () => {
+    let withPluralRefs = Plugin_Structure.make(
+      ~name="TestPlugin",
+      ~stateChangeSlices=[module(PsReserveStockSlice)],
+    )
+    let slice = withPluralRefs.stateChangeSlices->Array.getUnsafe(0)
+    let referencesOf = refs =>
+      refs->Array.map(({Reventless.Plugin.fieldName: f, entity}) => (f, entity))
+
+    // Scalar and plural in one command: the plural forms are the regression, the
+    // scalar one is here so a fix that reaches them by breaking it cannot pass.
+    testSync("a command collects its array refs alongside its scalar one", () => {
+      let cmd = slice.commands->Array.getUnsafe(0)
+      expect(cmd.references->referencesOf)->toEqual([
+        ("customerId", "Customers"),
+        ("productIds", "AvailableProducts"),
+        ("warehouseIds", "Warehouses"),
+      ])
+    })
+
+    // Optionality is a statement about presence. An optional array puts the
+    // element two wrappers down, which is the shape most likely to be missed by
+    // an unwrap that only handles one.
+    testSync("an optional array ref is collected under the field's own name", () => {
+      let cmd = slice.commands->Array.getUnsafe(0)
+      expect(
+        cmd.references->Array.find(({fieldName}) => fieldName == "warehouseIds"),
+      )->toEqual(Some({Reventless.Plugin.fieldName: "warehouseIds", entity: "Warehouses", plugin: None}))
+    })
+
+    // The event walk is a separate function over the same field dicts. Left to
+    // itself it would be fixed by accident or not at all.
+    testSync("an event collects its array ref too", () => {
+      let evt = slice.events->Array.getUnsafe(0)
+      expect(evt.references->referencesOf)->toEqual([("productIds", "AvailableProducts")])
+    })
+
+    // The declared entity, not the one `productIds` reads like. Before the
+    // element unwrap this field resolved by heuristic to `Products`.
+    testSync("the declared entity wins over the one the field name suggests", () => {
+      let cmd = slice.commands->Array.getUnsafe(0)
+      expect(
+        cmd.references
+        ->Array.find(({fieldName}) => fieldName == "productIds")
+        ->Option.map(({entity}) => entity),
+      )->toEqual(Some("AvailableProducts"))
+    })
+  })
 })

package/tests/plugin/PluginStructureTest.res.mjs

@@ -14,6 +14,7 @@ import * as PsOrdersView$ReventlessCore from "./StateViewSlice/PsOrdersView.res.
 import * as PsPlaceOrder$ReventlessCore from "./StateChangeSlice/PsPlaceOrder.res.mjs";
 import * as PsChangePhoto$ReventlessCore from "./StateChangeSlice/PsChangePhoto.res.mjs";
 import * as CapabilityManifest$Reventless from "@reventlessdev/reventless-spec/src/components/CapabilityManifest.res.mjs";
+import * as PsReserveStock$ReventlessCore from "./StateChangeSlice/PsReserveStock.res.mjs";
 import * as PsUploadAvatar$ReventlessCore from "./StateChangeSlice/PsUploadAvatar.res.mjs";
 import * as PsAnnotatedView$ReventlessCore from "./StateViewSlice/PsAnnotatedView.res.mjs";
 import * as PsAttachInvoice$ReventlessCore from "./StateChangeSlice/PsAttachInvoice.res.mjs";
@@ -276,6 +277,36 @@ let PsChangePhotoSlice = {
   make: make$8
 };
 
+let Behavior$5 = {
+  initialState: false,
+  evolve: PsReserveStock$ReventlessCore.evolve,
+  decide: PsReserveStock$ReventlessCore.decide,
+  moduleUrl: PsReserveStock$ReventlessCore.moduleUrl
+};
+
+function make$9(param, param$1, param$2, param$3, param$4, param$5) {
+  return 0;
+}
+
+let PsReserveStockSlice_Spec = {
+  name: PsReserveStock$ReventlessCore.name,
+  moduleUrl: PsReserveStock$ReventlessCore.moduleUrl,
+  Id: Id$Reventless.$$String,
+  consumedEventSchema: PsReserveStock$ReventlessCore.consumedEventSchema,
+  errorSchema: PsReserveStock$ReventlessCore.errorSchema,
+  eventSchema: PsReserveStock$ReventlessCore.eventSchema,
+  commandSchema: PsReserveStock$ReventlessCore.commandSchema,
+  commandAuthorization: PsReserveStock$ReventlessCore.commandAuthorization,
+  readConsistency: PsReserveStock$ReventlessCore.readConsistency
+};
+
+let PsReserveStockSlice = {
+  Spec: PsReserveStockSlice_Spec,
+  Behavior: Behavior$5,
+  isAsync: false,
+  make: make$9
+};
+
 let structure = Plugin_Structure$ReventlessCore.make("TestPlugin", undefined, undefined, [
   PsOrdersViewSlice,
   PsAvailableProductsViewSlice,
@@ -962,6 +993,50 @@ globalThis.describe("Plugin_Structure.make — Phase 2 graph fields", () => {
       ]);
     });
   });
+  globalThis.describe("plural references reach the manifest", () => {
+    let withPluralRefs = Plugin_Structure$ReventlessCore.make("TestPlugin", undefined, undefined, undefined, [PsReserveStockSlice], undefined, undefined, undefined, undefined, undefined, undefined);
+    let slice = withPluralRefs.stateChangeSlices[0];
+    let referencesOf = refs => refs.map(param => [
+      param.fieldName,
+      param.entity
+    ]);
+    globalThis.test("a command collects its array refs alongside its scalar one", () => {
+      let cmd = slice.commands[0];
+      globalThis.expect(referencesOf(cmd.references)).toEqual([
+        [
+          "customerId",
+          "Customers"
+        ],
+        [
+          "productIds",
+          "AvailableProducts"
+        ],
+        [
+          "warehouseIds",
+          "Warehouses"
+        ]
+      ]);
+    });
+    globalThis.test("an optional array ref is collected under the field's own name", () => {
+      let cmd = slice.commands[0];
+      globalThis.expect(cmd.references.find(param => param.fieldName === "warehouseIds")).toEqual({
+        fieldName: "warehouseIds",
+        entity: "Warehouses",
+        plugin: undefined
+      });
+    });
+    globalThis.test("an event collects its array ref too", () => {
+      let evt = slice.events[0];
+      globalThis.expect(referencesOf(evt.references)).toEqual([[
+          "productIds",
+          "AvailableProducts"
+        ]]);
+    });
+    globalThis.test("the declared entity wins over the one the field name suggests", () => {
+      let cmd = slice.commands[0];
+      globalThis.expect(Stdlib_Option.map(cmd.references.find(param => param.fieldName === "productIds"), param => param.entity)).toEqual("AvailableProducts");
+    });
+  });
 });
 
 export {
@@ -974,6 +1049,7 @@ export {
   PsAttachInvoiceSlice,
   PsUploadAvatarSlice,
   PsChangePhotoSlice,
+  PsReserveStockSlice,
   structure,
 }
 /* structure Not a pure module */

package/tests/plugin/StateChangeSlice/PsReserveStock.res

@@ -0,0 +1,44 @@
+// Test fixture spec where every reference carrier is PLURAL.
+//
+// `Reference.to_` returns an *element* schema, so the ppx annotates the `string`
+// inside `array<string>` and the field's own schema carries no marker. A walk
+// that asks the field directly finds nothing and drops the declaration — and a
+// dropped `@ref` is not the same as an absent one: the consuming side falls back
+// to a naming heuristic and resolves the field to whatever entity the name
+// suggests, so the author's declaration is both ignored and reported as missing.
+//
+// The command declares the scalar and plural forms side by side so a regression
+// shows up as one of the two disappearing rather than as an empty list, and
+// `warehouseIds?` covers the plural-inside-optional shape, where the array sits
+// one wrapper further down still.
+
+@@reventless.spec("ReserveStock")
+
+type state = bool
+let initialState = false
+
+@schema
+type consumedEvent = StockReserved({reservationId: string})
+
+let evolve = (_state, _event) => true
+
+@schema
+type command =
+  | ReserveStock({
+      @partitionTag reservationId: string,
+      @ref("Customers") customerId: string,
+      @ref("AvailableProducts") productIds: array<string>,
+      @ref("Warehouses") warehouseIds?: array<string>,
+    })
+
+@schema
+type error = OutOfStock
+
+@schema
+type event =
+  StockReserved({
+    @partitionTag reservationId: string,
+    @ref("AvailableProducts") productIds: array<string>,
+  })
+
+let decide = (_state, _command): result<array<event>, error> => Ok([])

package/tests/plugin/StateChangeSlice/PsReserveStock.res.mjs

@@ -0,0 +1,67 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as S from "sury/src/S.res.mjs";
+import * as DcbTag$Reventless from "@reventlessdev/reventless-spec/src/components/DcbTag.res.mjs";
+import * as Reference$Reventless from "@reventlessdev/reventless-spec/src/components/Reference.res.mjs";
+
+let consumedEventSchema = S.schema(s => ({
+  TAG: "StockReserved",
+  reservationId: s.m(DcbTag$Reventless.string)
+}));
+
+function evolve(_state, _event) {
+  return true;
+}
+
+let commandSchema = S.schema(s => ({
+  TAG: "ReserveStock",
+  reservationId: s.m(DcbTag$Reventless.partition),
+  customerId: s.m(Reference$Reventless.to_(undefined, undefined, "Customers")),
+  productIds: s.m(S.array(Reference$Reventless.to_(undefined, "productId", "AvailableProducts"))),
+  warehouseIds: s.m(S.option(S.array(Reference$Reventless.to_(undefined, "warehouseId", "Warehouses"))))
+}));
+
+let errorSchema = S.literal("OutOfStock");
+
+let eventSchema = S.schema(s => ({
+  TAG: "StockReserved",
+  reservationId: s.m(DcbTag$Reventless.partition),
+  productIds: s.m(S.array(Reference$Reventless.to_(undefined, "productId", "AvailableProducts")))
+}));
+
+function decide(_state, _command) {
+  return {
+    TAG: "Ok",
+    _0: []
+  };
+}
+
+function commandAuthorization(param) {
+  return "AllowAuthenticated";
+}
+
+let name = "ReserveStock";
+
+let Id;
+
+let initialState = false;
+
+let moduleUrl = "@reventlessdev/reventless-core/tests/plugin/StateChangeSlice/PsReserveStock.res.mjs";
+
+let readConsistency = "EscalateOnRetry";
+
+export {
+  name,
+  Id,
+  initialState,
+  consumedEventSchema,
+  evolve,
+  commandSchema,
+  errorSchema,
+  eventSchema,
+  decide,
+  moduleUrl,
+  commandAuthorization,
+  readConsistency,
+}
+/* consumedEventSchema Not a pure module */