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

package/CHANGELOG.md

@@ -3,6 +3,42 @@
 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.225 (2026-08-12)
+
+### Features
+
+* **commands:** stamp owner-marked fields from the authenticated caller ([5266655](https://github.com/ReventlessDev/reventless-core/commit/5266655b34de4d90c8148dec686cb0f336ac223d))
+* **core:** warn when an owner-scoped view exempts nobody ([cafa7a8](https://github.com/ReventlessDev/reventless-core/commit/cafa7a8b2082aeb00e53a9ed9da5bb978158db2d))
+* **platform:** bake a curated component manifest as a static asset ([4f30265](https://github.com/ReventlessDev/reventless-core/commit/4f30265a51fc2c59e69afd8074cf1b2534c06378))
+* **plugin:** publish the access a component's authorization rule implies ([e0d0f09](https://github.com/ReventlessDev/reventless-core/commit/e0d0f096b72fe44b185ed28dc1c133364fa841b8))
+* **plugin:** publish which field ties a component to its owner ([ca71289](https://github.com/ReventlessDev/reventless-core/commit/ca7128931ce525af0d7d3a4487b2b5c54b19bec0))
+* **queries:** narrow owner-bearing reads to the caller ([ba9cc3d](https://github.com/ReventlessDev/reventless-core/commit/ba9cc3d58d7914a9e4827bda90a704a74b1b82dd))
+* **spec:** let a record name the field that identifies its owner ([b69ee91](https://github.com/ReventlessDev/reventless-core/commit/b69ee9123e6beb38fcdd716519103ab9328213c6))
+* **spec:** let the environment name the groups exempt from owner scoping ([2de5c51](https://github.com/ReventlessDev/reventless-core/commit/2de5c5118347a46998f9ab603308fca09addf00b))
+
+
+# 3.0.0-alpha.224 (2026-08-11)
+
+### Bug Fixes
+
+* **api:** one id contract across the read-side query doors ([c52fac2](https://github.com/ReventlessDev/reventless-core/commit/c52fac2bee87b3dd1fa33b4970a74f3cd3866280))
+* feat(core)!: name semantic composites once instead of once per field ([09536ba](https://github.com/ReventlessDev/reventless-core/commit/09536badf338f898b24d749270acd5c7df851ddb))
+### Features
+
+* **api:** infer a queryable's key field and publish its provenance ([c835a42](https://github.com/ReventlessDev/reventless-core/commit/c835a42a0da07cdc4a3f010212e1f340a4a0ca27))
+* **plugin:** publish singleQueryField on queryableDef ([a724ab5](https://github.com/ReventlessDev/reventless-core/commit/a724ab573614792c0615d68b6486b94da14f9f82))
+
+### BREAKING CHANGES
+
+* generated GraphQL type names change. A price field is now
+`MoneyInput!` in a command and `Money!` in a read model, where it was named
+after the field that carried it (`Catalog_AddProductPriceCurrency`,
+`Ordering_SyncNewProductPriceCurrency`, …). AutoUI builds its queries at
+runtime from the component-definitions manifest and adapts on its own; a client
+naming the old types in a hand-written query does not.
+
+
+
 # 3.0.0-alpha.223 (2026-08-10)
 
 ### Bug Fixes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reventlessdev/reventless-core",
-  "version": "3.0.0-alpha.223",
+  "version": "3.0.0-alpha.225",
   "description": "Core package for Reventless framework",
   "license": "Apache-2.0",
   "jest": {
@@ -29,16 +29,16 @@
     "sury": "11.0.0-alpha.4",
     "uuid": "^13.0.0",
     "@reventlessdev/rescript-effect": "0.1.0-alpha.32",
-    "@reventlessdev/rescript-fast-csv": "2.0.0-alpha.3",
     "@reventlessdev/rescript-hash-object": "1.2.0-alpha.14",
+    "@reventlessdev/rescript-node": "2.0.0-alpha.4",
+    "@reventlessdev/rescript-fast-csv": "2.0.0-alpha.4",
     "@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/rescript-ssh2": "2.0.0-alpha.4",
     "@reventlessdev/reventless-interop": "3.0.0-alpha.30",
-    "@reventlessdev/reventless-infra": "3.0.0-alpha.133",
-    "@reventlessdev/reventless-spec": "3.0.0-alpha.107"
+    "@reventlessdev/reventless-infra": "3.0.0-alpha.135",
+    "@reventlessdev/reventless-spec": "3.0.0-alpha.109"
   },
   "devDependencies": {
     "rescript": "12.3.0",

package/src/admin/Platform_Admin_Structure.res

@@ -76,6 +76,8 @@ let activateCommand: commandDef = {
   allowedStates: Some(["Inactive"]),
   targetState: None,
   apiExposed: Some(true),
+  requiredAccess: None,
+  ownerField: None,
 }
 
 let deactivateCommand: commandDef = {
@@ -88,6 +90,8 @@ let deactivateCommand: commandDef = {
   allowedStates: Some(["Connected", "Disconnected"]),
   targetState: None,
   apiExposed: Some(true),
+  requiredAccess: None,
+  ownerField: None,
 }
 
 let pluginAggregate: writableDef = {
@@ -121,6 +125,18 @@ let pluginReadModel: queryableDef = {
   statusField: Some("status"),
   visibility: None,
   chapter: None,
+  // The admin fragment hand-declares its query names rather than deriving them from
+  // the read-model name, so the singular is taken from the same call
+  // `PluginBaseFragment.queryNames.singleFieldName` makes — not singularised here.
+  singleQueryField: Some(Api_Naming.adminField(~name="Plugin")),
+  // No key field to name: the row id is `name@version` (`Plugin.makeId`), and the
+  // state carries the two halves separately rather than the composed key. `None`
+  // is the honest answer — the same one the resolver ladder reaches for a state
+  // with no `*Id` field.
+  idField: None,
+  idFieldSource: None,
+  requiredAccess: None,
+  ownerField: None,
 }
 
 let structure: pluginStructure = {

package/src/admin/Platform_Admin_Structure.res.mjs

@@ -64,7 +64,9 @@ let activateCommand = {
   references: activateCommand_references,
   allowedStates: activateCommand_allowedStates,
   targetState: undefined,
-  apiExposed: activateCommand_apiExposed
+  apiExposed: activateCommand_apiExposed,
+  requiredAccess: undefined,
+  ownerField: undefined
 };
 
 let deactivateCommand_schema = encodeSchema(idArgsSchema);
@@ -91,7 +93,9 @@ let deactivateCommand = {
   references: deactivateCommand_references,
   allowedStates: deactivateCommand_allowedStates,
   targetState: undefined,
-  apiExposed: deactivateCommand_apiExposed
+  apiExposed: deactivateCommand_apiExposed,
+  requiredAccess: undefined,
+  ownerField: undefined
 };
 
 let pluginAggregate_commands = [
@@ -135,6 +139,8 @@ let pluginReadModel_labelFieldSource = "convention";
 
 let pluginReadModel_statusField = "status";
 
+let pluginReadModel_singleQueryField = Api_Naming$ReventlessCore.adminField("Plugin");
+
 let pluginReadModel = {
   name: "Plugins",
   queryField: pluginReadModel_queryField,
@@ -145,8 +151,13 @@ let pluginReadModel = {
   searchableFields: pluginReadModel_searchableFields,
   labelFieldSource: pluginReadModel_labelFieldSource,
   statusField: pluginReadModel_statusField,
+  ownerField: undefined,
   visibility: undefined,
-  chapter: undefined
+  chapter: undefined,
+  singleQueryField: pluginReadModel_singleQueryField,
+  idField: undefined,
+  idFieldSource: undefined,
+  requiredAccess: undefined
 };
 
 let structure_readModels = [pluginReadModel];

package/src/admin/Platform_BakedManifest.res

@@ -0,0 +1,154 @@
+// Curation for the baked component manifest: a deployment's include-list applied
+// to the registered plugin structures, encoded through the very same encoder
+// `Platform_ComponentDefinitions` uses.
+//
+// Curation is not authorization. This module decides WHAT EXISTS for a
+// deployment's audience — deployment data, settled before anyone logs in. What a
+// caller may do stays a server-side decision, enforced per query and per
+// mutation, and nothing here relaxes it. That split is the reason a curated file
+// can be static at all.
+//
+// The filtering happens on the `pluginStructure` record, never on the encoded
+// JSON: whatever survives is then handed to
+// `Platform_ComponentDefinitionsApi.encodePluginStructureEntry`, so a baked entry
+// and a served entry cannot drift in shape, and an include-list that names
+// everything produces byte-identical output.
+
+open Reventless.Plugin
+
+type error =
+  | UnknownPlugin(string)
+  | UnknownView({plugin: string, view: string})
+  | UnknownCommand({plugin: string, command: string})
+
+let describe = (e: error): string =>
+  switch e {
+  | UnknownPlugin(plugin) => `baked manifest: no registered plugin named "${plugin}"`
+  | UnknownView({plugin, view}) =>
+    `baked manifest: plugin "${plugin}" has no view named "${view}"`
+  | UnknownCommand({plugin, command}) =>
+    `baked manifest: plugin "${plugin}" has no command named "${command}"`
+  }
+
+// Views are named by component name — a view IS the surface. Commands are named
+// by command name, not by the write-side component that carries them: the
+// command is what a user invokes, and which slice or aggregate it lives on is an
+// implementation detail the author should not have to know to curate a shop.
+type selection = {
+  plugin: string,
+  views: option<array<string>>,
+  commands: option<array<string>>,
+}
+
+let publicViews = (def: pluginStructure): array<queryableDef> =>
+  Array.concat(def.readModels, def.stateViewSlices)->Array.filter(
+    Platform_ComponentDefinitionsApi.isPublicQueryable,
+  )
+
+let writeSides = (def: pluginStructure): array<writableDef> =>
+  Array.concat(def.stateChangeSlices, def.aggregates)
+
+let commandNames = (def: pluginStructure): array<string> =>
+  def->writeSides->Array.flatMap(w => w.commands->Array.map(c => c.name))
+
+// Every name in the selection has to resolve. A silent no-op here ships a shell
+// with a page missing for a reason no log explains — the same class of failure as
+// a malformed hints file, and it gets the same treatment: fail the deploy.
+let validate = (~def: pluginStructure, sel: selection): result<unit, error> => {
+  let known = (names, candidates) =>
+    names
+    ->Option.getOr([])
+    ->Array.find(name => !(candidates->Array.includes(name)))
+
+  switch sel.views->known(def->publicViews->Array.map(q => q.name)) {
+  | Some(view) => Error(UnknownView({plugin: sel.plugin, view}))
+  | None =>
+    switch sel.commands->known(def->commandNames) {
+    | Some(command) => Error(UnknownCommand({plugin: sel.plugin, command}))
+    | None => Ok()
+    }
+  }
+}
+
+let isSelected = (selected: option<array<string>>, name: string): bool =>
+  switch selected {
+  | None => true
+  | Some(names) => names->Array.includes(name)
+  }
+
+// An Internal view survives the bake only when an included command references it.
+// It is carried for one reason — to be a reference target — and a shell reading a
+// baked manifest has no admin API to recover a missing one from, so leaving it out
+// breaks the picker permanently in the one deployment shape with no fallback.
+// Naming it discloses nothing: the domain API already serves that view to the same
+// caller (Internal is a menu hint, not a boundary).
+let referencedEntities = (~pluginName: string, kept: array<writableDef>): array<string> =>
+  kept
+  ->Array.flatMap(w => w.commands)
+  ->Array.flatMap(c => c.references)
+  ->Array.filterMap(r =>
+    switch r.plugin {
+    | Some(p) if Plugin.name(p) !== pluginName => None
+    | _ => Some(r.entity)
+    }
+  )
+
+let curateStructure = (
+  ~pluginId: string,
+  ~def: pluginStructure,
+  sel: selection,
+): result<pluginStructure, error> =>
+  validate(~def, sel)->Result.map(() => {
+    let pluginName = Plugin.name(pluginId)
+    let keepCommands = (ws: array<writableDef>) =>
+      ws
+      ->Array.map(w => {...w, commands: w.commands->Array.filter(c => sel.commands->isSelected(c.name))})
+      // A write side left with no command contributes no surface. Dropping it
+      // keeps the curated entry a description of what the app offers rather than
+      // a list of components whose commands were all removed.
+      ->Array.filter(w => w.commands->Array.length > 0)
+
+    let stateChangeSlices = def.stateChangeSlices->keepCommands
+    let aggregates = def.aggregates->keepCommands
+    let referenced = referencedEntities(
+      ~pluginName,
+      Array.concat(stateChangeSlices, aggregates),
+    )
+    let keepViews = (qs: array<queryableDef>) =>
+      qs->Array.filter(q =>
+        if Platform_ComponentDefinitionsApi.isPublicQueryable(q) {
+          sel.views->isSelected(q.name)
+        } else {
+          referenced->Array.includes(q.name)
+        }
+      )
+
+    {
+      ...def,
+      readModels: def.readModels->keepViews,
+      stateViewSlices: def.stateViewSlices->keepViews,
+      stateChangeSlices,
+      aggregates,
+    }
+  })
+
+// The whole file: one entry per selection, in the order the deployment declared
+// them, so the include-list also states the order a consumer reads plugins in.
+let curate = (
+  ~structures: array<(string, pluginStructure)>,
+  ~selections: array<selection>,
+): result<JSON.t, error> =>
+  selections->Array.reduce(Ok([]), (acc, sel) =>
+    acc->Result.flatMap(entries =>
+      switch structures->Array.find(((pluginId, _)) => Plugin.name(pluginId) === sel.plugin) {
+      | None => Error(UnknownPlugin(sel.plugin))
+      | Some((pluginId, def)) =>
+        curateStructure(~pluginId, ~def, sel)->Result.map(curated => {
+          entries->Array.push(
+            Platform_ComponentDefinitionsApi.encodePluginStructureEntry(~pluginId, curated),
+          )
+          entries
+        })
+      }
+    )
+  )->Result.map(JSON.Encode.array)

package/src/admin/Platform_BakedManifest.res.mjs

@@ -0,0 +1,156 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+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_Result from "@rescript/runtime/lib/es6/Stdlib_Result.js";
+import * as Plugin$ReventlessCore from "../plugin/component/Plugin.res.mjs";
+import * as Platform_ComponentDefinitionsApi$ReventlessCore from "./Platform_ComponentDefinitionsApi.res.mjs";
+
+function describe(e) {
+  switch (e.TAG) {
+    case "UnknownPlugin" :
+      return `baked manifest: no registered plugin named "` + e._0 + `"`;
+    case "UnknownView" :
+      return `baked manifest: plugin "` + e.plugin + `" has no view named "` + e.view + `"`;
+    case "UnknownCommand" :
+      return `baked manifest: plugin "` + e.plugin + `" has no command named "` + e.command + `"`;
+  }
+}
+
+function publicViews(def) {
+  return def.readModels.concat(def.stateViewSlices).filter(Platform_ComponentDefinitionsApi$ReventlessCore.isPublicQueryable);
+}
+
+function writeSides(def) {
+  return def.stateChangeSlices.concat(def.aggregates);
+}
+
+function commandNames(def) {
+  return writeSides(def).flatMap(w => w.commands.map(c => c.name));
+}
+
+function validate(def, sel) {
+  let known = (names, candidates) => Stdlib_Option.getOr(names, []).find(name => !candidates.includes(name));
+  let view = known(sel.views, publicViews(def).map(q => q.name));
+  if (view !== undefined) {
+    return {
+      TAG: "Error",
+      _0: {
+        TAG: "UnknownView",
+        plugin: sel.plugin,
+        view: view
+      }
+    };
+  }
+  let command = known(sel.commands, commandNames(def));
+  if (command !== undefined) {
+    return {
+      TAG: "Error",
+      _0: {
+        TAG: "UnknownCommand",
+        plugin: sel.plugin,
+        command: command
+      }
+    };
+  } else {
+    return {
+      TAG: "Ok",
+      _0: undefined
+    };
+  }
+}
+
+function isSelected(selected, name) {
+  if (selected !== undefined) {
+    return selected.includes(name);
+  } else {
+    return true;
+  }
+}
+
+function referencedEntities(pluginName, kept) {
+  return Stdlib_Array.filterMap(kept.flatMap(w => w.commands).flatMap(c => c.references), r => {
+    let p = r.plugin;
+    if (p !== undefined && Plugin$ReventlessCore.name(p) !== pluginName) {
+      return;
+    } else {
+      return r.entity;
+    }
+  });
+}
+
+function curateStructure(pluginId, def, sel) {
+  return Stdlib_Result.map(validate(def, sel), () => {
+    let pluginName = Plugin$ReventlessCore.name(pluginId);
+    let keepCommands = ws => ws.map(w => ({
+      name: w.name,
+      commands: w.commands.filter(c => isSelected(sel.commands, c.name)),
+      producedEventTypes: w.producedEventTypes,
+      consumedEventTypes: w.consumedEventTypes,
+      linkedViews: w.linkedViews,
+      consistencyRead: w.consistencyRead,
+      events: w.events,
+      errors: w.errors,
+      chapter: w.chapter
+    })).filter(w => w.commands.length !== 0);
+    let stateChangeSlices = keepCommands(def.stateChangeSlices);
+    let aggregates = keepCommands(def.aggregates);
+    let referenced = referencedEntities(pluginName, stateChangeSlices.concat(aggregates));
+    let keepViews = qs => qs.filter(q => {
+      if (Platform_ComponentDefinitionsApi$ReventlessCore.isPublicQueryable(q)) {
+        return isSelected(sel.views, q.name);
+      } else {
+        return referenced.includes(q.name);
+      }
+    });
+    return {
+      readModels: keepViews(def.readModels),
+      stateViewSlices: keepViews(def.stateViewSlices),
+      stateChangeSlices: stateChangeSlices,
+      aggregates: aggregates,
+      automationSlices: def.automationSlices,
+      outboundTranslationSlices: def.outboundTranslationSlices,
+      inboundTranslationSlices: def.inboundTranslationSlices,
+      extensions: def.extensions,
+      extensionPoints: def.extensionPoints,
+      requiredStores: def.requiredStores,
+      requiredStoreDeclarations: def.requiredStoreDeclarations
+    };
+  });
+}
+
+function curate(structures, selections) {
+  return Stdlib_Result.map(Stdlib_Array.reduce(selections, {
+    TAG: "Ok",
+    _0: []
+  }, (acc, sel) => Stdlib_Result.flatMap(acc, entries => {
+    let match = structures.find(param => Plugin$ReventlessCore.name(param[0]) === sel.plugin);
+    if (match === undefined) {
+      return {
+        TAG: "Error",
+        _0: {
+          TAG: "UnknownPlugin",
+          _0: sel.plugin
+        }
+      };
+    }
+    let pluginId = match[0];
+    return Stdlib_Result.map(curateStructure(pluginId, match[1], sel), curated => {
+      entries.push(Platform_ComponentDefinitionsApi$ReventlessCore.encodePluginStructureEntry(pluginId, curated));
+      return entries;
+    });
+  })), prim => prim);
+}
+
+export {
+  describe,
+  publicViews,
+  writeSides,
+  commandNames,
+  validate,
+  isSelected,
+  referencedEntities,
+  curateStructure,
+  curate,
+}
+/* No side effect */

package/src/admin/Platform_ComponentDefinitionsApi.res

@@ -18,14 +18,18 @@ open Reventless.Plugin
 // consumers long after they were being encoded.
 let sdlTypes: array<string> = [
   `type Platform_FieldReference {\n  fieldName: String!\n  entity: String!\n  plugin: String\n}`,
-  `type Platform_CommandDef {\n  name: String!\n  schema: String!\n  level: String!\n  aggregateIdField: String\n  mutationField: String!\n  references: [Platform_FieldReference!]!\n  allowedStates: [String!]\n  targetState: String\n  apiExposed: Boolean\n}`,
+  `type Platform_CommandDef {\n  name: String!\n  schema: String!\n  level: String!\n  aggregateIdField: String\n  mutationField: String!\n  references: [Platform_FieldReference!]!\n  allowedStates: [String!]\n  targetState: String\n  apiExposed: Boolean\n  requiredAccess: [String!]\n  ownerField: String\n}`,
   `type Platform_EventDef {\n  name: String!\n  schema: String!\n  references: [Platform_FieldReference!]!\n}`,
   // Same fields as Platform_EventDef, kept a distinct type because a refusal is not
   // a fact: a caller selecting `errors` is asking what a command can be rejected
   // with, and the two lists must stay independently evolvable.
   `type Platform_ErrorDef {\n  name: String!\n  schema: String!\n  references: [Platform_FieldReference!]!\n}`,
   `type Platform_WriteSideDef {\n  name: String!\n  commands: [Platform_CommandDef!]!\n  linkedViews: [String!]!\n  consistencyRead: String\n  producedEventTypes: [String!]!\n  consumedEventTypes: [String!]!\n  events: [Platform_EventDef!]!\n  errors: [Platform_ErrorDef!]!\n  chapter: String\n}`,
-  `type Platform_ReadSideDef {\n  name: String!\n  queryField: String!\n  schema: String!\n  consumedEventTypes: [String!]!\n  linkedWriteSide: [String!]!\n  labelField: String!\n  searchableFields: [String!]!\n  labelFieldSource: String\n  statusField: String\n  visibility: String\n  chapter: String\n}`,
+  // `singleQueryField` / `idField` / `idFieldSource` are nullable, not `String!`:
+  // structures persisted before the fields existed decode as `None`, a hand-rolled
+  // def may decline to state them, and a state whose key cannot be resolved has no
+  // `idField` to report.
+  `type Platform_ReadSideDef {\n  name: String!\n  queryField: String!\n  schema: String!\n  consumedEventTypes: [String!]!\n  linkedWriteSide: [String!]!\n  labelField: String!\n  searchableFields: [String!]!\n  labelFieldSource: String\n  statusField: String\n  visibility: String\n  chapter: String\n  singleQueryField: String\n  idField: String\n  idFieldSource: String\n  requiredAccess: [String!]\n  ownerField: String\n}`,
   `type Platform_AutomationSliceDef {\n  name: String!\n  consumedEventTypes: [String!]!\n  producedCommandTypes: [String!]!\n  targetName: String\n  chapter: String\n}`,
   `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}`,
@@ -77,6 +81,11 @@ let encodeCommandDef = (c: commandDef): JSON.t =>
     ),
     ("targetState", c.targetState->Option.mapOr(JSON.Encode.null, JSON.Encode.string)),
     ("apiExposed", c.apiExposed->Option.mapOr(JSON.Encode.null, JSON.Encode.bool)),
+    // Null, not `[]`: a rule asking for nothing checkable and a def written
+    // before the field existed are the same answer to a client — "no key gates
+    // this" — and neither should read as "gated by an empty set".
+    ("requiredAccess", c.requiredAccess->Option.mapOr(JSON.Encode.null, encodeStrings)),
+    ("ownerField", c.ownerField->Option.mapOr(JSON.Encode.null, JSON.Encode.string)),
   ])->JSON.Encode.object
 
 // Internal ReadModels / StateViewSlices are carried in pluginStructure for developer
@@ -111,6 +120,14 @@ let encodeQueryableDef = (r: queryableDef): JSON.t =>
     // survives the filter anyway.
     ("visibility", r.visibility->Option.mapOr(JSON.Encode.null, JSON.Encode.string)),
     ("chapter", r.chapter->Option.mapOr(JSON.Encode.null, JSON.Encode.string)),
+    (
+      "singleQueryField",
+      r.singleQueryField->Option.mapOr(JSON.Encode.null, JSON.Encode.string),
+    ),
+    ("idField", r.idField->Option.mapOr(JSON.Encode.null, JSON.Encode.string)),
+    ("idFieldSource", r.idFieldSource->Option.mapOr(JSON.Encode.null, JSON.Encode.string)),
+    ("requiredAccess", r.requiredAccess->Option.mapOr(JSON.Encode.null, encodeStrings)),
+    ("ownerField", r.ownerField->Option.mapOr(JSON.Encode.null, JSON.Encode.string)),
   ])->JSON.Encode.object
 
 let encodeEventDef = (e: eventDef): JSON.t =>

package/src/admin/Platform_ComponentDefinitionsApi.res.mjs

@@ -6,11 +6,11 @@ import * as Plugin$ReventlessCore from "../plugin/component/Plugin.res.mjs";
 
 let sdlTypes = [
   `type Platform_FieldReference {\n  fieldName: String!\n  entity: String!\n  plugin: String\n}`,
-  `type Platform_CommandDef {\n  name: String!\n  schema: String!\n  level: String!\n  aggregateIdField: String\n  mutationField: String!\n  references: [Platform_FieldReference!]!\n  allowedStates: [String!]\n  targetState: String\n  apiExposed: Boolean\n}`,
+  `type Platform_CommandDef {\n  name: String!\n  schema: String!\n  level: String!\n  aggregateIdField: String\n  mutationField: String!\n  references: [Platform_FieldReference!]!\n  allowedStates: [String!]\n  targetState: String\n  apiExposed: Boolean\n  requiredAccess: [String!]\n  ownerField: String\n}`,
   `type Platform_EventDef {\n  name: String!\n  schema: String!\n  references: [Platform_FieldReference!]!\n}`,
   `type Platform_ErrorDef {\n  name: String!\n  schema: String!\n  references: [Platform_FieldReference!]!\n}`,
   `type Platform_WriteSideDef {\n  name: String!\n  commands: [Platform_CommandDef!]!\n  linkedViews: [String!]!\n  consistencyRead: String\n  producedEventTypes: [String!]!\n  consumedEventTypes: [String!]!\n  events: [Platform_EventDef!]!\n  errors: [Platform_ErrorDef!]!\n  chapter: String\n}`,
-  `type Platform_ReadSideDef {\n  name: String!\n  queryField: String!\n  schema: String!\n  consumedEventTypes: [String!]!\n  linkedWriteSide: [String!]!\n  labelField: String!\n  searchableFields: [String!]!\n  labelFieldSource: String\n  statusField: String\n  visibility: String\n  chapter: String\n}`,
+  `type Platform_ReadSideDef {\n  name: String!\n  queryField: String!\n  schema: String!\n  consumedEventTypes: [String!]!\n  linkedWriteSide: [String!]!\n  labelField: String!\n  searchableFields: [String!]!\n  labelFieldSource: String\n  statusField: String\n  visibility: String\n  chapter: String\n  singleQueryField: String\n  idField: String\n  idFieldSource: String\n  requiredAccess: [String!]\n  ownerField: String\n}`,
   `type Platform_AutomationSliceDef {\n  name: String!\n  consumedEventTypes: [String!]!\n  producedCommandTypes: [String!]!\n  targetName: String\n  chapter: String\n}`,
   `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}`,
@@ -79,6 +79,14 @@ function encodeCommandDef(c) {
     [
       "apiExposed",
       Stdlib_Option.mapOr(c.apiExposed, null, prim => prim)
+    ],
+    [
+      "requiredAccess",
+      Stdlib_Option.mapOr(c.requiredAccess, null, encodeStrings)
+    ],
+    [
+      "ownerField",
+      Stdlib_Option.mapOr(c.ownerField, null, prim => prim)
     ]
   ]);
 }
@@ -132,6 +140,26 @@ function encodeQueryableDef(r) {
     [
       "chapter",
       Stdlib_Option.mapOr(r.chapter, null, prim => prim)
+    ],
+    [
+      "singleQueryField",
+      Stdlib_Option.mapOr(r.singleQueryField, null, prim => prim)
+    ],
+    [
+      "idField",
+      Stdlib_Option.mapOr(r.idField, null, prim => prim)
+    ],
+    [
+      "idFieldSource",
+      Stdlib_Option.mapOr(r.idFieldSource, null, prim => prim)
+    ],
+    [
+      "requiredAccess",
+      Stdlib_Option.mapOr(r.requiredAccess, null, encodeStrings)
+    ],
+    [
+      "ownerField",
+      Stdlib_Option.mapOr(r.ownerField, null, prim => prim)
     ]
   ]);
 }

package/src/components/Api/Api_Ids.res

@@ -0,0 +1,63 @@
+/**
+The one place that knows how a row's GraphQL `id` relates to its storage key.
+
+A read-side row is reachable through several id-accepting doors — the typed
+`X(id: ID!)` query, `XsByIds(ids:)`, the list `filter.ids`, and Relay's
+`node(id:)`. They used to disagree about which form they took, so the obvious
+client call `X(id: row.id)` silently returned `null`: the door took the storage
+key while the row advertised the Relay global id. The rule below is what
+`QueryDbListQuery.passIds` already applied to `filter.ids` — lifted out so every
+door applies it, and so provider adapters share one definition rather than three.
+
+Provider-neutral on purpose: the contract belongs to neither the local platform
+nor AWS.
+*/
+
+@val external btoa: string => string = "btoa"
+@val external atob: string => string = "atob"
+
+/** `btoa("<TypeName>:<localId>")` — the Relay global id for a row. */
+let encode = (~typeName: string, ~localId: string): string => btoa(`${typeName}:${localId}`)
+
+/**
+The `(typeName, localId)` pair inside a global id, or `None` when the string is
+not one. `atob` throws on non-base64 input; a decoded value with no `:` (or a
+leading one, which would mean an empty type name) is not a global id either.
+*/
+let decode = (globalId: string): option<(string, string)> =>
+  try {
+    let decoded = atob(globalId)
+    let idx = decoded->String.indexOf(":")
+    if idx > 0 {
+      Some((
+        decoded->String.slice(~start=0, ~end=idx),
+        decoded->String.slice(~start=idx + 1, ~end=decoded->String.length),
+      ))
+    } else {
+      None
+    }
+  } catch {
+  | _ => None
+  }
+
+/**
+The storage key a global id wraps, or `None` if the string is not one.
+
+Deliberately NOT a `string => string` that "normalises" an id: a raw key that
+happens to be valid base64 would be silently rewritten into something that
+matches nothing. Callers look the raw id up first and fall back to this — see
+`alternateKey`.
+*/
+let toLocalId = (id: string): option<string> => decode(id)->Option.map(((_, localId)) => localId)
+
+/**
+The other key worth trying when a lookup by `id` found nothing: the storage key
+inside it, if it was a global id. Ordering matters — the raw id is always tried
+first, so a key that merely looks like base64 keeps resolving to its own row and
+this only ever runs on a miss.
+*/
+let alternateKey = (id: string): option<string> =>
+  switch toLocalId(id) {
+  | Some(localId) if localId != id => Some(localId)
+  | _ => None
+  }