@reventlessdev/reventless-core 3.0.0-alpha.148 → 3.0.0-alpha.150

package/CHANGELOG.md

@@ -3,6 +3,20 @@
 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.150 (2026-07-10)
+
+### Features
+
+* **reventless-ppx:** add [@group](https://github.com/group)By state-field annotation → x-reventless-group-by ([9e7a7b2](https://github.com/ReventlessDev/reventless-core/commit/9e7a7b29e54fb4eda1c6a145c0e7b6dcf26940ee))
+
+
+# 3.0.0-alpha.149 (2026-07-09)
+
+### Bug Fixes
+
+* **reventless-core:** DCB StateChangeSlice mutations use ${plugin}_${command}, not ${plugin}_${slice}_${command} ([c5874d2](https://github.com/ReventlessDev/reventless-core/commit/c5874d27ad63e6af5c639c8b6c6f8596fd7f682b))
+
+
 # 3.0.0-alpha.148 (2026-07-09)
 
 ### Bug Fixes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reventlessdev/reventless-core",
-  "version": "3.0.0-alpha.148",
+  "version": "3.0.0-alpha.150",
   "description": "Core package for Reventless framework",
   "license": "Apache-2.0",
   "jest": {
@@ -29,21 +29,21 @@
     "sury": "11.0.0-alpha.4",
     "uuid": "^13.0.0",
     "@reventlessdev/rescript-effect": "0.1.0-alpha.25",
-    "@reventlessdev/rescript-hash-object": "1.2.0-alpha.10",
     "@reventlessdev/rescript-fast-csv": "1.2.0-alpha.11",
+    "@reventlessdev/rescript-hash-object": "1.2.0-alpha.10",
     "@reventlessdev/rescript-jest": "1.0.0-alpha.6",
     "@reventlessdev/rescript-node-streams": "1.1.0-alpha.10",
     "@reventlessdev/rescript-pulumi-pulumi": "2.3.0-alpha.14",
+    "@reventlessdev/rescript-ssh2": "1.1.0-alpha.11",
     "@reventlessdev/rescript-uuid": "1.1.0-alpha.14",
-    "@reventlessdev/reventless-infra": "3.0.0-alpha.91",
+    "@reventlessdev/reventless-infra": "3.0.0-alpha.92",
     "@reventlessdev/reventless-interop": "3.0.0-alpha.24",
-    "@reventlessdev/rescript-ssh2": "1.1.0-alpha.11",
-    "@reventlessdev/reventless-spec": "3.0.0-alpha.69"
+    "@reventlessdev/reventless-spec": "3.0.0-alpha.70"
   },
   "devDependencies": {
     "rescript": "^12.3.0",
     "sury-ppx": "11.0.0-alpha.2",
-    "@reventlessdev/reventless-ppx": "1.0.0-alpha.51"
+    "@reventlessdev/reventless-ppx": "1.0.0-alpha.52"
   },
   "peerDependencies": {
     "rescript": "^12.3.0"

package/src/components/Api/Api_Naming.res

@@ -1,5 +1,3 @@
-open ReventlessInfra.Api
-
 type queryNames = {
   singleFieldName: string,
   listFieldName: string,
@@ -41,13 +39,43 @@ let aggregateMutationField = (~plugin: string, ~aggregate: string, ~command: str
 
 let sliceMutationField = (~plugin: string, ~slice: string) => `${plugin}_${slice}`
 
+// DCB StateChangeSlice per-command mutation field. Unlike aggregates — where multiple
+// aggregates coexist under a plugin so the aggregate name must namespace the command —
+// a DCB slice's command constructor already names the operation, and callers/plans
+// treat the mutation as `${plugin}_${command}`. Doubling in the slice name
+// (`${plugin}_${slice}_${command}`) both renames the primary command out from under
+// existing callers and overflows AppSync's 50-char subscription-field cap once the
+// `on` prefix is added.
+let dcbCommandMutationField = (~plugin: string, ~command: string) => `${plugin}_${command}`
+
+// AppSync hard limit: subscription field names may be at most 50 chars. Each mutation
+// field `f` produces a `@aws_subscribe` subscription `on${f}` (see
+// Plugin_SubscriptionSchema.sourceCFields), so the real cap on a mutation field is 48.
+// Fail at build with an actionable message rather than letting AppSync reject the
+// schema push at deploy time with an opaque 500.
+let appSyncSubscriptionMaxLen = 50
+
+let assertSubscriptionNameFits = (~fieldName: string) => {
+  let subscriptionName = `on${fieldName}`
+  if subscriptionName->String.length > appSyncSubscriptionMaxLen {
+    JsError.throwWithMessage(
+      `Generated subscription field \`${subscriptionName}\` is ${subscriptionName
+        ->String.length
+        ->Int.toString} chars, over AppSync's ${appSyncSubscriptionMaxLen->Int.toString}-char limit. ` ++
+      `Shorten the plugin, slice, or command name behind mutation field \`${fieldName}\`.`,
+    )
+  }
+  fieldName
+}
+
 // DCB StateChangeSlice mutation fields — one per API-exposed command constructor,
 // mirroring the aggregate path (which emits one field per constructor). A slice whose
 // command union has a single API-exposed constructor keeps the byte-identical
-// `Plugin_Slice` name (no schema churn); a multi-command slice uses aggregate-style
-// `Plugin_Slice_Ctor` per constructor so the SDL generator and command resolvers
-// derive the constructor from the trailing `_` segment. @noApi variants are filtered
-// out. Returns [(fieldName, constructorName)] in declaration order.
+// `Plugin_Slice` name (no schema churn); a multi-command slice names each mutation
+// `${plugin}_${command}` — the constructor already names the operation, and callers/plans
+// expect that shape (not aggregate-style `${plugin}_${slice}_${command}`). @noApi
+// variants are filtered out. Every emitted name is guarded against the 50-char AppSync
+// subscription cap at build time. Returns [(fieldName, constructorName)] in declaration order.
 let sliceMutationFields = (
   ~plugin: string,
   ~slice: string,
@@ -57,10 +85,10 @@ let sliceMutationFields = (
   let filtered = ApiNoApiHelpers.filterNoApiVariants(allNames, commandSchema)
   switch filtered {
   | [] => []
-  | [single] => [(sliceMutationField(~plugin, ~slice), single)]
+  | [single] => [(assertSubscriptionNameFits(~fieldName=sliceMutationField(~plugin, ~slice)), single)]
   | _ =>
     filtered->Array.map(ctor => (
-      aggregateMutationField(~plugin, ~aggregate=slice, ~command=ctor),
+      assertSubscriptionNameFits(~fieldName=dcbCommandMutationField(~plugin, ~command=ctor)),
       ctor,
     ))
   }
@@ -68,7 +96,7 @@ let sliceMutationFields = (
 
 // The mutation field name for a single command constructor of a DCB StateChangeSlice,
 // consistent with `sliceMutationFields`: single-command slices resolve every variant
-// to the slice name, multi-command slices to the aggregate-style per-constructor name.
+// to the slice name, multi-command slices to the per-constructor `${plugin}_${command}`.
 let sliceMutationFieldFor = (
   ~plugin: string,
   ~slice: string,
@@ -78,7 +106,7 @@ let sliceMutationFieldFor = (
   if sliceMutationFields(~plugin, ~slice, ~commandSchema)->Array.length <= 1 {
     sliceMutationField(~plugin, ~slice)
   } else {
-    aggregateMutationField(~plugin, ~aggregate=slice, ~command=variant)
+    dcbCommandMutationField(~plugin, ~command=variant)
   }
 
 // Pluralize via the singular stem so already-plural names normalise correctly:

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

@@ -1,5 +1,6 @@
 // Generated by ReScript, PLEASE EDIT WITH CARE
 
+import * as Stdlib_JsError from "@rescript/runtime/lib/es6/Stdlib_JsError.js";
 import * as DcbTag$Reventless from "@reventlessdev/reventless-spec/src/components/DcbTag.res.mjs";
 import * as ApiNoApiHelpers$ReventlessCore from "./ApiNoApiHelpers.res.mjs";
 
@@ -41,6 +42,18 @@ function sliceMutationField(plugin, slice) {
   return plugin + `_` + slice;
 }
 
+function dcbCommandMutationField(plugin, command) {
+  return plugin + `_` + command;
+}
+
+function assertSubscriptionNameFits(fieldName) {
+  let subscriptionName = `on` + fieldName;
+  if (subscriptionName.length > 50) {
+    Stdlib_JsError.throwWithMessage(`Generated subscription field \`` + subscriptionName + `\` is ` + subscriptionName.length.toString() + ` chars, over AppSync's ` + (50).toString() + `-char limit. ` + (`Shorten the plugin, slice, or command name behind mutation field \`` + fieldName + `\`.`));
+  }
+  return fieldName;
+}
+
 function sliceMutationFields(plugin, slice, commandSchema) {
   let allNames = DcbTag$Reventless.extractAllVariantNames(commandSchema);
   let filtered = ApiNoApiHelpers$ReventlessCore.filterNoApiVariants(allNames, commandSchema);
@@ -48,7 +61,7 @@ function sliceMutationFields(plugin, slice, commandSchema) {
   if (len !== 1) {
     if (len !== 0) {
       return filtered.map(ctor => [
-        aggregateMutationField(plugin, slice, ctor),
+        assertSubscriptionNameFits(dcbCommandMutationField(plugin, ctor)),
         ctor
       ]);
     } else {
@@ -57,7 +70,7 @@ function sliceMutationFields(plugin, slice, commandSchema) {
   }
   let single = filtered[0];
   return [[
-      sliceMutationField(plugin, slice),
+      assertSubscriptionNameFits(sliceMutationField(plugin, slice)),
       single
     ]];
 }
@@ -66,7 +79,7 @@ function sliceMutationFieldFor(plugin, slice, commandSchema, variant) {
   if (sliceMutationFields(plugin, slice, commandSchema).length <= 1) {
     return sliceMutationField(plugin, slice);
   } else {
-    return aggregateMutationField(plugin, slice, variant);
+    return dcbCommandMutationField(plugin, variant);
   }
 }
 
@@ -119,12 +132,17 @@ function adminField(name) {
   return `Platform_` + name;
 }
 
+let appSyncSubscriptionMaxLen = 50;
+
 export {
   pluralize,
   singularize,
   stripViewSuffix,
   aggregateMutationField,
   sliceMutationField,
+  dcbCommandMutationField,
+  appSyncSubscriptionMaxLen,
+  assertSubscriptionNameFits,
   sliceMutationFields,
   sliceMutationFieldFor,
   canonicalPlural,

package/src/components/Api/SuryToJsonSchema.res

@@ -44,6 +44,11 @@ let mergeAnnotations = (
     if spec.summary->Array.includes(fieldName) {
       obj->Dict.set("x-reventless-summary", JSON.Encode.bool(true))
     }
+    switch spec.groupBy {
+    | Some(name) if name === fieldName =>
+      obj->Dict.set("x-reventless-group-by", JSON.Encode.bool(true))
+    | _ => ()
+    }
     switch spec.drillTargets->Array.find(((field, _)) => field === fieldName) {
     | Some((_, sliceName)) =>
       obj->Dict.set("x-reventless-drillTarget", JSON.Encode.string(sliceName))

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

@@ -41,6 +41,10 @@ function mergeAnnotations(fieldSchema, fieldName, spec) {
   if (spec.summary.includes(fieldName)) {
     obj["x-reventless-summary"] = true;
   }
+  let name = spec.groupBy;
+  if (name !== undefined && name === fieldName) {
+    obj["x-reventless-group-by"] = true;
+  }
   let match$1 = spec.drillTargets.find(param => param[0] === fieldName);
   if (match$1 !== undefined) {
     obj["x-reventless-drillTarget"] = match$1[1];

package/src/plugin/lifecycle/PluginsReadModelSpec.res

@@ -42,7 +42,9 @@ type state = {
   // @scan opts the field into server-side equality filtering so the connection gains
   // a `kindEq` filter — the panel split (main list vs System/Infrastructure) pages
   // correctly server-side rather than filtering a page client-side.
-  @scan kind: Reventless.Plugin.pluginKind,
+  // @groupBy tags this field as the list view's section key (emitted as
+  // `x-reventless-group-by`); AutoUI sections the admin Plugins view by kind.
+  @scan @groupBy kind: Reventless.Plugin.pluginKind,
   // Other versions of this name that are currently **Connected** — excludes this
   // row's own `version` (whose status is the `status` field above). Lets the
   // projection recompute which version is current (highest Connected) during a

package/src/plugin/lifecycle/PluginsReadModelSpec.res.mjs

@@ -48,6 +48,7 @@ let stateSchema$1 = S.Metadata.set(stateSchema, StateAnnotations$Reventless.stat
   scan: ["kind"],
   scanSort: [],
   status: undefined,
+  groupBy: "kind",
   visibility: undefined
 });
 

package/tests/api/SuryToJsonSchemaTest.res

@@ -30,6 +30,7 @@ let emptySpec: Reventless.StateAnnotations.stateAnnotationSpec = {
   scan: [],
   scanSort: [],
   status: None,
+  groupBy: None,
   visibility: None,
 }
 
@@ -305,6 +306,25 @@ describe("SuryToJsonSchema:", () => {
       ))->toEqual((Some(true), None))
     })
 
+    testSync("emits x-reventless-group-by on the field named by groupBy", () => {
+      let schema = S.schema(s =>
+        {
+          "id": s.matches(S.string),
+          "kind": s.matches(S.string),
+        }
+      )->S.castToUnknown
+      let schema' = schema->withSpec({...emptySpec, groupBy: Some("kind")})
+      let json = SuryToJsonSchema.deriveObjectSchema(schema')
+      let kindSchema = getPropertyOf(json, "kind")
+      let idSchema = getPropertyOf(json, "id")
+      expect((
+        kindSchema
+        ->Option.flatMap(s => getProperty(s, "x-reventless-group-by"))
+        ->Option.flatMap(JSON.Decode.bool),
+        idSchema->Option.flatMap(s => getProperty(s, "x-reventless-group-by")),
+      ))->toEqual((Some(true), None))
+    })
+
     testSync("emits x-reventless-collapsed on field listed in collapsed", () => {
       let schema = S.schema(s =>
         {

package/tests/api/SuryToJsonSchemaTest.res.mjs

@@ -64,6 +64,7 @@ let emptySpec = {
   scan: emptySpec_scan,
   scanSort: emptySpec_scanSort,
   status: undefined,
+  groupBy: undefined,
   visibility: undefined
 };
 
@@ -100,6 +101,7 @@ globalThis.describe("SuryToJsonSchema:", () => {
         scan: emptySpec_scan,
         scanSort: emptySpec_scanSort,
         status: undefined,
+        groupBy: undefined,
         visibility: undefined
       });
       let json = SuryToJsonSchema$ReventlessCore.deriveObjectSchema(schema$p);
@@ -129,6 +131,7 @@ globalThis.describe("SuryToJsonSchema:", () => {
         scan: emptySpec_scan,
         scanSort: emptySpec_scanSort,
         status: undefined,
+        groupBy: undefined,
         visibility: undefined
       });
       let json = SuryToJsonSchema$ReventlessCore.deriveObjectSchema(schema$p);
@@ -161,6 +164,7 @@ globalThis.describe("SuryToJsonSchema:", () => {
         scan: emptySpec_scan,
         scanSort: emptySpec_scanSort,
         status: undefined,
+        groupBy: undefined,
         visibility: undefined
       });
       let json = SuryToJsonSchema$ReventlessCore.deriveObjectSchema(schema$p);
@@ -189,6 +193,7 @@ globalThis.describe("SuryToJsonSchema:", () => {
         scan: emptySpec_scan,
         scanSort: emptySpec_scanSort,
         status: undefined,
+        groupBy: undefined,
         visibility: undefined
       });
       let json = SuryToJsonSchema$ReventlessCore.deriveObjectSchema(schema$p);
@@ -217,6 +222,7 @@ globalThis.describe("SuryToJsonSchema:", () => {
         scan: emptySpec_scan,
         scanSort: emptySpec_scanSort,
         status: undefined,
+        groupBy: undefined,
         visibility: undefined
       });
       let json = SuryToJsonSchema$ReventlessCore.deriveObjectSchema(schema$p);
@@ -242,6 +248,7 @@ globalThis.describe("SuryToJsonSchema:", () => {
         scan: emptySpec_scan,
         scanSort: emptySpec_scanSort,
         status: undefined,
+        groupBy: undefined,
         visibility: undefined
       });
       let json = SuryToJsonSchema$ReventlessCore.deriveObjectSchema(schema$p);
@@ -267,6 +274,7 @@ globalThis.describe("SuryToJsonSchema:", () => {
         scan: emptySpec_scan,
         scanSort: emptySpec_scanSort,
         status: undefined,
+        groupBy: undefined,
         visibility: undefined
       });
       let json = SuryToJsonSchema$ReventlessCore.deriveObjectSchema(schema$p);
@@ -299,6 +307,7 @@ globalThis.describe("SuryToJsonSchema:", () => {
         scan: emptySpec_scan,
         scanSort: emptySpec_scanSort,
         status: undefined,
+        groupBy: undefined,
         visibility: undefined
       });
       let json = SuryToJsonSchema$ReventlessCore.deriveObjectSchema(schema$p);
@@ -334,6 +343,7 @@ globalThis.describe("SuryToJsonSchema:", () => {
         scan: emptySpec_scan,
         scanSort: emptySpec_scanSort,
         status: undefined,
+        groupBy: undefined,
         visibility: undefined
       });
       let json = SuryToJsonSchema$ReventlessCore.deriveObjectSchema(schema$p);
@@ -372,6 +382,7 @@ globalThis.describe("SuryToJsonSchema:", () => {
         scan: emptySpec_scan,
         scanSort: emptySpec_scanSort,
         status: undefined,
+        groupBy: undefined,
         visibility: undefined
       });
       let json = SuryToJsonSchema$ReventlessCore.deriveObjectSchema(schema$p);
@@ -400,6 +411,7 @@ globalThis.describe("SuryToJsonSchema:", () => {
         scan: emptySpec_scan,
         scanSort: emptySpec_scanSort,
         status: undefined,
+        groupBy: undefined,
         visibility: undefined
       });
       let json = SuryToJsonSchema$ReventlessCore.deriveObjectSchema(schema$p);
@@ -425,6 +437,7 @@ globalThis.describe("SuryToJsonSchema:", () => {
         scan: ["status"],
         scanSort: emptySpec_scanSort,
         status: undefined,
+        groupBy: undefined,
         visibility: undefined
       });
       let json = SuryToJsonSchema$ReventlessCore.deriveObjectSchema(schema$p);
@@ -457,6 +470,7 @@ globalThis.describe("SuryToJsonSchema:", () => {
         scan: emptySpec_scan,
         scanSort: ["name"],
         status: undefined,
+        groupBy: undefined,
         visibility: undefined
       });
       let json = SuryToJsonSchema$ReventlessCore.deriveObjectSchema(schema$p);
@@ -470,6 +484,39 @@ globalThis.describe("SuryToJsonSchema:", () => {
         undefined
       ]);
     });
+    globalThis.test("emits x-reventless-group-by on the field named by groupBy", () => {
+      let schema = S.schema(s => ({
+        id: s.m(S.string),
+        kind: s.m(S.string)
+      }));
+      let schema$p = withSpec(schema, {
+        ids: emptySpec_ids,
+        compositeIds: emptySpec_compositeIds,
+        subIds: emptySpec_subIds,
+        compositeSubIds: emptySpec_compositeSubIds,
+        indexes: emptySpec_indexes,
+        hidden: emptySpec_hidden,
+        summary: emptySpec_summary,
+        drillTargets: emptySpec_drillTargets,
+        drillTargetKeys: emptySpec_drillTargetKeys,
+        collapsed: emptySpec_collapsed,
+        scan: emptySpec_scan,
+        scanSort: emptySpec_scanSort,
+        status: undefined,
+        groupBy: "kind",
+        visibility: undefined
+      });
+      let json = SuryToJsonSchema$ReventlessCore.deriveObjectSchema(schema$p);
+      let kindSchema = getPropertyOf(json, "kind");
+      let idSchema = getPropertyOf(json, "id");
+      globalThis.expect([
+        Stdlib_Option.flatMap(Stdlib_Option.flatMap(kindSchema, s => getProperty(s, "x-reventless-group-by")), Stdlib_JSON.Decode.bool),
+        Stdlib_Option.flatMap(idSchema, s => getProperty(s, "x-reventless-group-by"))
+      ]).toEqual([
+        true,
+        undefined
+      ]);
+    });
     globalThis.test("emits x-reventless-collapsed on field listed in collapsed", () => {
       let schema = S.schema(s => ({
         id: s.m(S.string),
@@ -489,6 +536,7 @@ globalThis.describe("SuryToJsonSchema:", () => {
         scan: emptySpec_scan,
         scanSort: emptySpec_scanSort,
         status: undefined,
+        groupBy: undefined,
         visibility: undefined
       });
       let json = SuryToJsonSchema$ReventlessCore.deriveObjectSchema(schema$p);
@@ -520,6 +568,7 @@ globalThis.describe("SuryToJsonSchema:", () => {
         scan: emptySpec_scan,
         scanSort: emptySpec_scanSort,
         status: undefined,
+        groupBy: undefined,
         visibility: "Internal"
       });
       let json = SuryToJsonSchema$ReventlessCore.deriveObjectSchema(schema$p);
@@ -543,6 +592,7 @@ globalThis.describe("SuryToJsonSchema:", () => {
         scan: emptySpec_scan,
         scanSort: emptySpec_scanSort,
         status: undefined,
+        groupBy: undefined,
         visibility: undefined
       });
       let json = SuryToJsonSchema$ReventlessCore.deriveObjectSchema(schema$p);
@@ -606,6 +656,7 @@ globalThis.describe("SuryToJsonSchema:", () => {
         scan: emptySpec_scan,
         scanSort: emptySpec_scanSort,
         status: undefined,
+        groupBy: undefined,
         visibility: undefined
       });
       let native = S.toJSONSchema(schema$p);

package/tests/plugin/StateViewSlice/PsAnnotatedView.res.mjs

@@ -65,6 +65,7 @@ let stateSchema$1 = S.Metadata.set(stateSchema, StateAnnotations$Reventless.stat
   scan: [],
   scanSort: [],
   status: undefined,
+  groupBy: undefined,
   visibility: undefined
 });