@reventlessdev/reventless-core 3.0.0-alpha.152 → 3.0.0-alpha.153

package/CHANGELOG.md

@@ -3,6 +3,14 @@
 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.153 (2026-07-10)
+
+### Features
+
+* **plugin-structure:** capture per-component chapter grouping for the deployed graph ([f9c88a9](https://github.com/ReventlessDev/reventless-core/commit/f9c88a9a48d8c032ffe23f9e5277caf12c29e85c))
+* **plugin-structure:** carry translation-slice externalSystem into the deployed structure ([80c0cda](https://github.com/ReventlessDev/reventless-core/commit/80c0cda3b6d5fc6625d4b285f41505028f1dd06f))
+
+
 # 3.0.0-alpha.152 (2026-07-10)
 
 ### Features

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reventlessdev/reventless-core",
-  "version": "3.0.0-alpha.152",
+  "version": "3.0.0-alpha.153",
   "description": "Core package for Reventless framework",
   "license": "Apache-2.0",
   "jest": {
@@ -31,14 +31,14 @@
     "@reventlessdev/rescript-effect": "0.1.0-alpha.25",
     "@reventlessdev/rescript-fast-csv": "1.2.0-alpha.11",
     "@reventlessdev/rescript-hash-object": "1.2.0-alpha.10",
+    "@reventlessdev/rescript-node-streams": "1.1.0-alpha.10",
     "@reventlessdev/rescript-jest": "1.0.0-alpha.6",
     "@reventlessdev/rescript-pulumi-pulumi": "2.3.0-alpha.14",
-    "@reventlessdev/rescript-node-streams": "1.1.0-alpha.10",
     "@reventlessdev/rescript-ssh2": "1.1.0-alpha.11",
     "@reventlessdev/rescript-uuid": "1.1.0-alpha.14",
-    "@reventlessdev/reventless-infra": "3.0.0-alpha.93",
-    "@reventlessdev/reventless-spec": "3.0.0-alpha.71",
-    "@reventlessdev/reventless-interop": "3.0.0-alpha.24"
+    "@reventlessdev/reventless-infra": "3.0.0-alpha.94",
+    "@reventlessdev/reventless-interop": "3.0.0-alpha.24",
+    "@reventlessdev/reventless-spec": "3.0.0-alpha.72"
   },
   "devDependencies": {
     "rescript": "^12.3.0",

package/src/admin/Platform_Admin_Structure.res

@@ -96,6 +96,7 @@ let pluginAggregate: writableDef = {
   linkedViews: ["Plugins"],
   consistencyRead: None,
   events: [],
+  chapter: None,
 }
 
 let pluginReadModel: queryableDef = {
@@ -110,6 +111,7 @@ let pluginReadModel: queryableDef = {
   searchableFields: ["name"],
   statusField: Some("status"),
   visibility: None,
+  chapter: None,
 }
 
 let structure: pluginStructure = {

package/src/admin/Platform_Admin_Structure.res.mjs

@@ -110,7 +110,8 @@ let pluginAggregate = {
   consumedEventTypes: pluginAggregate_consumedEventTypes,
   linkedViews: pluginAggregate_linkedViews,
   consistencyRead: undefined,
-  events: pluginAggregate_events
+  events: pluginAggregate_events,
+  chapter: undefined
 };
 
 let pluginReadModel_queryField = Api_Naming$ReventlessCore.adminField("Plugins");
@@ -134,7 +135,8 @@ let pluginReadModel = {
   labelField: "name",
   searchableFields: pluginReadModel_searchableFields,
   statusField: pluginReadModel_statusField,
-  visibility: undefined
+  visibility: undefined,
+  chapter: undefined
 };
 
 let structure_readModels = [pluginReadModel];

package/src/admin/Platform_ComponentDefinitionsApi.res

@@ -72,6 +72,7 @@ let encodeQueryableDef = (r: queryableDef): JSON.t =>
     ("labelField", JSON.Encode.string(r.labelField)),
     ("searchableFields", encodeStrings(r.searchableFields)),
     ("statusField", r.statusField->Option.mapOr(JSON.Encode.null, JSON.Encode.string)),
+    ("chapter", r.chapter->Option.mapOr(JSON.Encode.null, JSON.Encode.string)),
   ])->JSON.Encode.object
 
 let encodeEventDef = (e: eventDef): JSON.t =>
@@ -94,6 +95,7 @@ let encodeWritableDef = (w: writableDef): JSON.t =>
     ("consumedEventTypes", encodeStrings(w.consumedEventTypes)),
     // Phase 6.3: emitted-event field schemas (None → [] on the wire).
     ("events", w.events->Array.map(encodeEventDef)->JSON.Encode.array),
+    ("chapter", w.chapter->Option.mapOr(JSON.Encode.null, JSON.Encode.string)),
   ])->JSON.Encode.object
 
 let encodeAutomationSliceDef = (a: automationSliceDef): JSON.t =>
@@ -101,6 +103,7 @@ let encodeAutomationSliceDef = (a: automationSliceDef): JSON.t =>
     ("name", JSON.Encode.string(a.name)),
     ("consumedEventTypes", encodeStrings(a.consumedEventTypes)),
     ("producedCommandTypes", encodeStrings(a.producedCommandTypes)),
+    ("chapter", a.chapter->Option.mapOr(JSON.Encode.null, JSON.Encode.string)),
   ])->JSON.Encode.object
 
 let encodeOutboundTranslationSliceDef = (o: outboundTranslationSliceDef): JSON.t =>
@@ -108,12 +111,20 @@ let encodeOutboundTranslationSliceDef = (o: outboundTranslationSliceDef): JSON.t
     ("name", JSON.Encode.string(o.name)),
     ("consumedEventTypes", encodeStrings(o.consumedEventTypes)),
     ("inboundCommandTypes", encodeStrings(o.inboundCommandTypes)),
+    // Foreign system this slice publishes to — lets a deployed-graph consumer draw
+    // the external-system boundary box without workspace access. None → null.
+    ("externalSystem", o.externalSystem->Option.mapOr(JSON.Encode.null, JSON.Encode.string)),
+    ("chapter", o.chapter->Option.mapOr(JSON.Encode.null, JSON.Encode.string)),
   ])->JSON.Encode.object
 
 let encodeInboundTranslationSliceDef = (i: inboundTranslationSliceDef): JSON.t =>
   Dict.fromArray([
     ("name", JSON.Encode.string(i.name)),
     ("commandTypes", encodeStrings(i.commandTypes)),
+    // Foreign system this slice receives from — lets a deployed-graph consumer draw
+    // the external-system boundary box without workspace access. None → null.
+    ("externalSystem", i.externalSystem->Option.mapOr(JSON.Encode.null, JSON.Encode.string)),
+    ("chapter", i.chapter->Option.mapOr(JSON.Encode.null, JSON.Encode.string)),
   ])->JSON.Encode.object
 
 let encodeExtensionDef = (e: extensionDef): JSON.t =>

package/src/admin/Platform_ComponentDefinitionsApi.res.mjs

@@ -115,6 +115,10 @@ function encodeQueryableDef(r) {
     [
       "statusField",
       Stdlib_Option.mapOr(r.statusField, null, prim => prim)
+    ],
+    [
+      "chapter",
+      Stdlib_Option.mapOr(r.chapter, null, prim => prim)
     ]
   ]);
 }
@@ -165,6 +169,10 @@ function encodeWritableDef(w) {
     [
       "events",
       w.events.map(encodeEventDef)
+    ],
+    [
+      "chapter",
+      Stdlib_Option.mapOr(w.chapter, null, prim => prim)
     ]
   ]);
 }
@@ -182,6 +190,10 @@ function encodeAutomationSliceDef(a) {
     [
       "producedCommandTypes",
       a.producedCommandTypes.map(prim => prim)
+    ],
+    [
+      "chapter",
+      Stdlib_Option.mapOr(a.chapter, null, prim => prim)
     ]
   ]);
 }
@@ -199,6 +211,14 @@ function encodeOutboundTranslationSliceDef(o) {
     [
       "inboundCommandTypes",
       o.inboundCommandTypes.map(prim => prim)
+    ],
+    [
+      "externalSystem",
+      Stdlib_Option.mapOr(o.externalSystem, null, prim => prim)
+    ],
+    [
+      "chapter",
+      Stdlib_Option.mapOr(o.chapter, null, prim => prim)
     ]
   ]);
 }
@@ -212,6 +232,14 @@ function encodeInboundTranslationSliceDef(i) {
     [
       "commandTypes",
       i.commandTypes.map(prim => prim)
+    ],
+    [
+      "externalSystem",
+      Stdlib_Option.mapOr(i.externalSystem, null, prim => prim)
+    ],
+    [
+      "chapter",
+      Stdlib_Option.mapOr(i.chapter, null, prim => prim)
     ]
   ]);
 }

package/src/plugin/component/Plugin.res

@@ -46,6 +46,7 @@ module type T = {
     ~inboundTranslationSlices: array<module(ReventlessInfra.InboundTranslationSlice.T)>=?,
     ~extensions: array<module(ReventlessInfra.Extension.Blueprint)>=?,
     ~extensionPoints: array<module(ReventlessInfra.ExtensionPointMapping.Mapping)>=?,
+    ~componentChapters: dict<string>=?,
   ) => Reventless.Plugin.pluginStructure
 }
 

package/src/plugin/component/Plugin_Builder.res

@@ -368,6 +368,30 @@ module Make = (
       // so only aggregates, read models, and DCB slice names are included.
 
       let extractTypes = schema => Reventless.DcbTag.extractAllVariantNames(schema)
+
+      // Chapter (intra-plugin grouping band) per component name, mirrored from the
+      // static pluginStructure so the hook surface reaches parity with it. The
+      // structure is the single source — it was populated by the generator's
+      // componentChapters map at makePluginDefinition time.
+      let chapterByName: Dict.t<string> = Dict.make()
+      switch pluginStructure {
+      | Some(ps) =>
+        let put = (n, c) =>
+          switch c {
+          | Some(ch) => chapterByName->Dict.set(n, ch)
+          | None => ()
+          }
+        ps.aggregates->Array.forEach(d => put(d.name, d.chapter))
+        ps.readModels->Array.forEach(d => put(d.name, d.chapter))
+        ps.stateChangeSlices->Array.forEach(d => put(d.name, d.chapter))
+        ps.stateViewSlices->Array.forEach(d => put(d.name, d.chapter))
+        ps.automationSlices->Array.forEach(d => put(d.name, d.chapter))
+        ps.outboundTranslationSlices->Array.forEach(d => put(d.name, d.chapter))
+        ps.inboundTranslationSlices->Array.forEach(d => put(d.name, d.chapter))
+      | None => ()
+      }
+      let chapterFor = (n: string): option<string> => chapterByName->Dict.get(n)
+
       // Build per-component schema data and register it for the deployed hook.
       let aggregateComponents = aggregates->Array.map((
         module(M: ReventlessInfra.Aggregate.T with type api = api),
@@ -382,6 +406,7 @@ module Make = (
           eventSchemas: [
             SchemaWalker.walk(M.Spec.name ++ ".event", M.Spec.eventSchema),
           ],
+          chapter: ?chapterFor(M.Spec.name),
         }
         Plugin_Helpers.componentSchemaRegistry->Dict.set(M.Spec.name, schema)
         ({name: M.Spec.name, kind: "Aggregate", schema}: Plugin_Helpers.pluginBuiltComponent)
@@ -393,6 +418,7 @@ module Make = (
         let qn = Api_Naming.queryFieldNamesForReadModel(~plugin=name, ~name=R.Spec.name)
         let schema: Plugin_Helpers.pluginDeployedSchema = {
           queryFields: [qn.singleFieldName, qn.listFieldName],
+          chapter: ?chapterFor(R.Spec.name),
         }
         Plugin_Helpers.componentSchemaRegistry->Dict.set(R.Spec.name, schema)
         ({name: R.Spec.name, kind: "ReadModel", schema}: Plugin_Helpers.pluginBuiltComponent)
@@ -421,6 +447,7 @@ module Make = (
             consumedEventTypes,
             producedCommandTypes: extractTypes(As.Spec.commandSchema),
             targetName: As.Spec.targetName,
+            chapter: ?chapterFor(As.Spec.name),
           },
         )
       })
@@ -434,6 +461,9 @@ module Make = (
             commandTypes: extractTypes(Ots.Spec.inboundCommandSchema),
             // Outbound slices may have no target (option); pass it through.
             targetName: ?Ots.Spec.targetName,
+            // Foreign system this slice publishes to (option); drives the external box.
+            externalSystem: ?Ots.Spec.externalSystem,
+            chapter: ?chapterFor(Ots.Spec.name),
           },
         )
       )
@@ -445,6 +475,9 @@ module Make = (
           {
             commandTypes: extractTypes(Its.Spec.commandSchema),
             targetName: Its.Spec.targetName,
+            // Foreign system this slice receives from (option); drives the external box.
+            externalSystem: ?Its.Spec.externalSystem,
+            chapter: ?chapterFor(Its.Spec.name),
           },
         )
       )
@@ -464,13 +497,17 @@ module Make = (
             commandTypes: extractTypes(Scs.Spec.commandSchema),
             eventTypes: extractEventTypes(Scs.Spec.eventSchema->S.castToUnknown),
             consumedEventTypes: extractEventTypes(Scs.Spec.consumedEventSchema->S.castToUnknown),
+            chapter: ?chapterFor(Scs.Spec.name),
           },
         )
       )
       stateViewSlices->Array.forEach((module(Svs: ReventlessInfra.StateViewSlice.T)) =>
         stateSchemas->Dict.set(
           Svs.Spec.name,
-          {consumedEventTypes: extractEventTypes(Svs.Spec.consumedEventSchema->S.castToUnknown)},
+          {
+            consumedEventTypes: extractEventTypes(Svs.Spec.consumedEventSchema->S.castToUnknown),
+            chapter: ?chapterFor(Svs.Spec.name),
+          },
         )
       )
 
@@ -993,6 +1030,7 @@ module Make = (
     ~inboundTranslationSlices: array<module(ReventlessInfra.InboundTranslationSlice.T)>=[],
     ~extensions: array<module(ReventlessInfra.Extension.Blueprint)>=[],
     ~extensionPoints: array<module(ReventlessInfra.ExtensionPointMapping.Mapping)>=[],
+    ~componentChapters: dict<string>=Dict.make(),
   ): Reventless.Plugin.pluginStructure =>
     Plugin_Structure.make(
       ~name,
@@ -1005,6 +1043,7 @@ module Make = (
       ~inboundTranslationSlices,
       ~extensions,
       ~extensionPoints,
+      ~componentChapters,
     )
 
   let make = (

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

@@ -89,7 +89,7 @@ function Make(Spec) {
         pages: pages
       };
     };
-    let makePluginDefinition = (name, aggregatesOpt, readModelsOpt, stateViewSlicesOpt, stateChangeSlicesOpt, automationSlicesOpt, outboundTranslationSlicesOpt, inboundTranslationSlicesOpt, extensionsOpt, extensionPointsOpt) => {
+    let makePluginDefinition = (name, aggregatesOpt, readModelsOpt, stateViewSlicesOpt, stateChangeSlicesOpt, automationSlicesOpt, outboundTranslationSlicesOpt, inboundTranslationSlicesOpt, extensionsOpt, extensionPointsOpt, componentChaptersOpt) => {
       let aggregates = aggregatesOpt !== undefined ? aggregatesOpt : [];
       let readModels = readModelsOpt !== undefined ? readModelsOpt : [];
       let stateViewSlices = stateViewSlicesOpt !== undefined ? stateViewSlicesOpt : [];
@@ -99,7 +99,8 @@ function Make(Spec) {
       let inboundTranslationSlices = inboundTranslationSlicesOpt !== undefined ? inboundTranslationSlicesOpt : [];
       let extensions = extensionsOpt !== undefined ? extensionsOpt : [];
       let extensionPoints = extensionPointsOpt !== undefined ? extensionPointsOpt : [];
-      return Plugin_Structure$ReventlessCore.make(name, aggregates, readModels, stateViewSlices, stateChangeSlices, automationSlices, outboundTranslationSlices, inboundTranslationSlices, extensions, extensionPoints);
+      let componentChapters = componentChaptersOpt !== undefined ? componentChaptersOpt : ({});
+      return Plugin_Structure$ReventlessCore.make(name, aggregates, readModels, stateViewSlices, stateChangeSlices, automationSlices, outboundTranslationSlices, inboundTranslationSlices, extensions, extensionPoints, componentChapters);
     };
     let make = (name, heartbeatInterval, extensionPointsOpt, extensionsOpt, aggregatesOpt, readModelsOpt, tasksOpt, stateChangeSlicesOpt, stateViewSlicesOpt, automationSlicesOpt, outboundTranslationSlicesOpt, inboundTranslationSlicesOpt, systemCallableComponentsOpt, uiFragments, pluginStructure, opts) => {
       let extensionPoints = extensionPointsOpt !== undefined ? extensionPointsOpt : [];
@@ -264,18 +265,36 @@ function Make(Spec) {
           allQueryDbs[param[0] + "Todo"] = param[1].queryDb;
         });
         let queryEngine = QueryEngineAdapter.make(allQueryDbs);
+        let chapterByName = {};
+        if (pluginStructure !== undefined) {
+          let put = (n, c) => {
+            if (c !== undefined) {
+              chapterByName[n] = c;
+              return;
+            }
+          };
+          pluginStructure.aggregates.forEach(d => put(d.name, d.chapter));
+          pluginStructure.readModels.forEach(d => put(d.name, d.chapter));
+          pluginStructure.stateChangeSlices.forEach(d => put(d.name, d.chapter));
+          pluginStructure.stateViewSlices.forEach(d => put(d.name, d.chapter));
+          pluginStructure.automationSlices.forEach(d => put(d.name, d.chapter));
+          pluginStructure.outboundTranslationSlices.forEach(d => put(d.name, d.chapter));
+          pluginStructure.inboundTranslationSlices.forEach(d => put(d.name, d.chapter));
+        }
         let aggregateComponents = aggregates.map(M => {
           let schema_commandTypes = DcbTag$Reventless.extractAllVariantNames(M.Spec.commandSchema);
           let schema_eventTypes = DcbTag$Reventless.extractAllVariantNames(M.Spec.eventSchema);
           let schema_errorTypes = DcbTag$Reventless.extractAllVariantNames(M.Spec.errorSchema);
           let schema_commandSchemas = [SchemaWalker$ReventlessCore.walk(M.Spec.name + ".command", M.Spec.commandSchema)];
           let schema_eventSchemas = [SchemaWalker$ReventlessCore.walk(M.Spec.name + ".event", M.Spec.eventSchema)];
+          let schema_chapter = chapterByName[M.Spec.name];
           let schema = {
             commandTypes: schema_commandTypes,
             eventTypes: schema_eventTypes,
             errorTypes: schema_errorTypes,
             commandSchemas: schema_commandSchemas,
-            eventSchemas: schema_eventSchemas
+            eventSchemas: schema_eventSchemas,
+            chapter: schema_chapter
           };
           Plugin_Helpers$ReventlessCore.componentSchemaRegistry[M.Spec.name] = schema;
           return {
@@ -290,8 +309,10 @@ function Make(Spec) {
             qn.singleFieldName,
             qn.listFieldName
           ];
+          let schema_chapter = chapterByName[R.Spec.name];
           let schema = {
-            queryFields: schema_queryFields
+            queryFields: schema_queryFields,
+            chapter: schema_chapter
           };
           Plugin_Helpers$ReventlessCore.componentSchemaRegistry[R.Spec.name] = schema;
           return {
@@ -306,20 +327,25 @@ function Make(Spec) {
           routingSchemas[As.Spec.name] = {
             consumedEventTypes: consumedEventTypes,
             producedCommandTypes: DcbTag$Reventless.extractAllVariantNames(As.Spec.commandSchema),
-            targetName: As.Spec.targetName
+            targetName: As.Spec.targetName,
+            chapter: chapterByName[As.Spec.name]
           };
         });
         outboundTranslationSlices.forEach(Ots => {
           routingSchemas[Ots.Spec.name] = {
             commandTypes: DcbTag$Reventless.extractAllVariantNames(Ots.Spec.inboundCommandSchema),
             consumedEventTypes: DcbTag$Reventless.extractVariantNames(Ots.Spec.consumedEventSchema),
-            targetName: Ots.Spec.targetName
+            targetName: Ots.Spec.targetName,
+            externalSystem: Ots.Spec.externalSystem,
+            chapter: chapterByName[Ots.Spec.name]
           };
         });
         inboundTranslationSlices.forEach(Its => {
           routingSchemas[Its.Spec.name] = {
             commandTypes: DcbTag$Reventless.extractAllVariantNames(Its.Spec.commandSchema),
-            targetName: Its.Spec.targetName
+            targetName: Its.Spec.targetName,
+            externalSystem: Its.Spec.externalSystem,
+            chapter: chapterByName[Its.Spec.name]
           };
         });
         let stateSchemas = {};
@@ -327,12 +353,14 @@ function Make(Spec) {
           stateSchemas[Scs.Spec.name] = {
             commandTypes: DcbTag$Reventless.extractAllVariantNames(Scs.Spec.commandSchema),
             eventTypes: DcbTag$Reventless.extractVariantNames(Scs.Spec.eventSchema),
-            consumedEventTypes: DcbTag$Reventless.extractVariantNames(Scs.Spec.consumedEventSchema)
+            consumedEventTypes: DcbTag$Reventless.extractVariantNames(Scs.Spec.consumedEventSchema),
+            chapter: chapterByName[Scs.Spec.name]
           };
         });
         stateViewSlices.forEach(Svs => {
           stateSchemas[Svs.Spec.name] = {
-            consumedEventTypes: DcbTag$Reventless.extractVariantNames(Svs.Spec.consumedEventSchema)
+            consumedEventTypes: DcbTag$Reventless.extractVariantNames(Svs.Spec.consumedEventSchema),
+            chapter: chapterByName[Svs.Spec.name]
           };
         });
         let enrichedComponents = (d, kind, schemas) => Object.keys(d).map(name => {

package/src/plugin/component/Plugin_BuiltHook.res

@@ -78,6 +78,12 @@ type pluginDeployedSchema = {
   /** For routing slices (automation / inbound + outbound translation): the name
    of the writable component this slice routes its commands to. */
   targetName?: string,
+  /** For inbound / outbound translation slices: the foreign system this slice
+   integrates with, mirrored from the static `pluginStructure` for hook parity.
+   Drives the deployed graph's external-system boundary box. Absent when the slice
+   names no external system. See the translation-slice defs on
+   `Reventless.Plugin.pluginStructure`. */
+  externalSystem?: string,
   sharedBy?: array<string>,
   extensionPointName?: string,
   providerPlugin?: string,
@@ -88,6 +94,11 @@ type pluginDeployedSchema = {
   eventSchemas?: array<typeSchema>,
   /** Field-level schema for the state type. */
   stateSchema?: typeSchema,
+  /** Intra-plugin grouping band (the "chapter") this component belongs to, mirrored
+   from the static `pluginStructure` for parity on the hook surface. Absent when the
+   component carries no chapter (lives directly under a kind-folder). See
+   `Reventless.Plugin.queryableDef.chapter`. */
+  chapter?: string,
 }
 
 // ---------------------------------------------------------------------------

package/src/plugin/component/Plugin_Structure.res

@@ -86,7 +86,15 @@ let make = (
   ~inboundTranslationSlices: array<module(ReventlessInfra.InboundTranslationSlice.T)>=[],
   ~extensions: array<module(ReventlessInfra.Extension.Blueprint)>=[],
   ~extensionPoints: array<module(ReventlessInfra.ExtensionPointMapping.Mapping)>=[],
+  // Component name → chapter (intra-plugin grouping band), captured at build time
+  // from each component's source folder by the plugin generator. A component whose
+  // spec name has no entry (or lives directly under a kind-folder) carries no chapter
+  // and renders flat. Keyed by `Spec.name`, which equals the source filename stem for
+  // every graph-node kind, so the generator can build this map from the discovered
+  // file paths. See `Codegen.chapterOf` and docs/plans/deployed-chapter-grouping.md.
+  ~componentChapters: dict<string>=Dict.make(),
 ): Reventless.Plugin.pluginStructure => {
+  let chapterOf = (compName: string): option<string> => componentChapters->Dict.get(compName)
   // Event schemas: filter out payload-less variants — DCB event-type lookups
   // can't WHERE-clause on bare-string events, so the plugin graph mustn't
   // claim cross-component edges that the runtime can't honour.
@@ -405,6 +413,7 @@ let make = (
         searchableFields,
         statusField: statusFieldFromStateSchema(stateSchema),
         visibility: visibilityTag(R.Spec.visibility),
+        chapter: chapterOf(R.Spec.name),
       }: Reventless.Plugin.queryableDef)
     })
 
@@ -427,6 +436,7 @@ let make = (
         searchableFields,
         statusField: statusFieldFromStateSchema(stateSchema),
         visibility: visibilityTag(SVS.Spec.visibility),
+        chapter: chapterOf(SVS.Spec.name),
       }: Reventless.Plugin.queryableDef)
     })
 
@@ -454,6 +464,7 @@ let make = (
         linkedViews: linkedSvsFor(produced),
         consistencyRead: consistencyReadFor(consumed),
         events: extractEventDefs(SCS.Spec.eventSchema->S.castToUnknown),
+        chapter: chapterOf(SCS.Spec.name),
       }: Reventless.Plugin.writableDef)
     })
 
@@ -475,6 +486,7 @@ let make = (
         linkedViews: Array.concat(linkedSvsFor(produced), linkedReadModelsFor(A.Spec.name)),
         consistencyRead: None,
         events: extractEventDefs(A.Spec.eventSchema->S.castToUnknown),
+        chapter: chapterOf(A.Spec.name),
       }: Reventless.Plugin.writableDef)
     })
 
@@ -497,6 +509,7 @@ let make = (
         consumedEventTypes: qualify(~prefix=name, allConsumedVariants),
         producedCommandTypes: qualify(~prefix=name, commandVariantNames(AS.Spec.commandSchema)),
         targetName: AS.Spec.targetName,
+        chapter: chapterOf(AS.Spec.name),
       }: Reventless.Plugin.automationSliceDef)
     })
 
@@ -509,6 +522,7 @@ let make = (
       inboundCommandTypes: qualify(~prefix=name, commandVariantNames(OTS.Spec.inboundCommandSchema)),
       targetName: OTS.Spec.targetName,
       externalSystem: OTS.Spec.externalSystem,
+      chapter: chapterOf(OTS.Spec.name),
     }: Reventless.Plugin.outboundTranslationSliceDef))
 
   // ── Inbound translation slices ────────────────────────────────────────────
@@ -519,6 +533,7 @@ let make = (
       commandTypes: qualify(~prefix=name, commandVariantNames(ITS.Spec.commandSchema)),
       targetName: ITS.Spec.targetName,
       externalSystem: ITS.Spec.externalSystem,
+      chapter: chapterOf(ITS.Spec.name),
     }: Reventless.Plugin.inboundTranslationSliceDef))
 
   // ── Extensions ───────────────────────────────────────────────────────────

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

@@ -67,7 +67,7 @@ function labelFieldsFromStateSchema(entityName, stateSchema) {
   }
 }
 
-function make(name, aggregatesOpt, readModelsOpt, stateViewSlicesOpt, stateChangeSlicesOpt, automationSlicesOpt, outboundTranslationSlicesOpt, inboundTranslationSlicesOpt, extensionsOpt, extensionPointsOpt) {
+function make(name, aggregatesOpt, readModelsOpt, stateViewSlicesOpt, stateChangeSlicesOpt, automationSlicesOpt, outboundTranslationSlicesOpt, inboundTranslationSlicesOpt, extensionsOpt, extensionPointsOpt, componentChaptersOpt) {
   let aggregates = aggregatesOpt !== undefined ? aggregatesOpt : [];
   let readModels = readModelsOpt !== undefined ? readModelsOpt : [];
   let stateViewSlices = stateViewSlicesOpt !== undefined ? stateViewSlicesOpt : [];
@@ -77,6 +77,7 @@ function make(name, aggregatesOpt, readModelsOpt, stateViewSlicesOpt, stateChang
   let inboundTranslationSlices = inboundTranslationSlicesOpt !== undefined ? inboundTranslationSlicesOpt : [];
   let extensions = extensionsOpt !== undefined ? extensionsOpt : [];
   let extensionPoints = extensionPointsOpt !== undefined ? extensionPointsOpt : [];
+  let componentChapters = componentChaptersOpt !== undefined ? componentChaptersOpt : ({});
   let qualify = (prefix, names) => names.map(n => prefix + "." + n);
   let isCreateCommandName = name => [
     "Add",
@@ -333,7 +334,8 @@ function make(name, aggregatesOpt, readModelsOpt, stateViewSlicesOpt, stateChang
       labelField: match[0],
       searchableFields: match[1],
       statusField: statusFieldFromStateSchema(stateSchema),
-      visibility: visibilityTag(R.Spec.visibility)
+      visibility: visibilityTag(R.Spec.visibility),
+      chapter: componentChapters[R.Spec.name]
     };
   });
   let stateViewDefs = stateViewSlices.map((SVS, i) => {
@@ -351,7 +353,8 @@ function make(name, aggregatesOpt, readModelsOpt, stateViewSlicesOpt, stateChang
       labelField: match$1[0],
       searchableFields: match$1[1],
       statusField: statusFieldFromStateSchema(stateSchema),
-      visibility: visibilityTag(SVS.Spec.visibility)
+      visibility: visibilityTag(SVS.Spec.visibility),
+      chapter: componentChapters[SVS.Spec.name]
     };
   });
   let stateChangeDefs = stateChangeSlices.map((SCS, i) => {
@@ -366,7 +369,8 @@ function make(name, aggregatesOpt, readModelsOpt, stateViewSlicesOpt, stateChang
       consumedEventTypes: consumed,
       linkedViews: linkedSvsFor(produced),
       consistencyRead: consistencyReadFor(consumed),
-      events: extractEventDefs(SCS.Spec.eventSchema)
+      events: extractEventDefs(SCS.Spec.eventSchema),
+      chapter: componentChapters[SCS.Spec.name]
     };
   });
   let aggregateDefs = aggregates.map((A, i) => {
@@ -379,7 +383,8 @@ function make(name, aggregatesOpt, readModelsOpt, stateViewSlicesOpt, stateChang
       consumedEventTypes: [],
       linkedViews: linkedSvsFor(produced).concat(linkedReadModelsFor(A.Spec.name)),
       consistencyRead: undefined,
-      events: extractEventDefs(A.Spec.eventSchema)
+      events: extractEventDefs(A.Spec.eventSchema),
+      chapter: componentChapters[A.Spec.name]
     };
   });
   let automationSliceDefs = automationSlices.map(AS => {
@@ -388,7 +393,8 @@ function make(name, aggregatesOpt, readModelsOpt, stateViewSlicesOpt, stateChang
       name: AS.Spec.name,
       consumedEventTypes: qualify(name, allConsumedVariants),
       producedCommandTypes: qualify(name, DcbTag$Reventless.extractAllVariantNames(AS.Spec.commandSchema)),
-      targetName: AS.Spec.targetName
+      targetName: AS.Spec.targetName,
+      chapter: componentChapters[AS.Spec.name]
     };
   });
   let outboundTranslationSliceDefs = outboundTranslationSlices.map(OTS => ({
@@ -396,13 +402,15 @@ function make(name, aggregatesOpt, readModelsOpt, stateViewSlicesOpt, stateChang
     consumedEventTypes: qualify(name, DcbTag$Reventless.extractVariantNames(OTS.Spec.consumedEventSchema)),
     inboundCommandTypes: qualify(name, DcbTag$Reventless.extractAllVariantNames(OTS.Spec.inboundCommandSchema)),
     targetName: OTS.Spec.targetName,
-    externalSystem: OTS.Spec.externalSystem
+    externalSystem: OTS.Spec.externalSystem,
+    chapter: componentChapters[OTS.Spec.name]
   }));
   let inboundTranslationSliceDefs = inboundTranslationSlices.map(ITS => ({
     name: ITS.Spec.name,
     commandTypes: qualify(name, DcbTag$Reventless.extractAllVariantNames(ITS.Spec.commandSchema)),
     targetName: ITS.Spec.targetName,
-    externalSystem: ITS.Spec.externalSystem
+    externalSystem: ITS.Spec.externalSystem,
+    chapter: componentChapters[ITS.Spec.name]
   }));
   let extensionDefs = extensions.map(E => {
     let delegateNames = E.mappings.map(M => M.delegateName);

package/tests/admin/Platform_ComponentDefinitionsApiTest.res

@@ -28,6 +28,7 @@ let qbl: queryableDef = {
   searchableFields: ["displayName"],
   statusField: None,
   visibility: None,
+  chapter: None,
 }
 
 let wbl: writableDef = {
@@ -38,6 +39,7 @@ let wbl: writableDef = {
   producedEventTypes: ["ProductAdded"],
   consumedEventTypes: [],
   events: [{name: "ProductAdded", schema: "{}", references: []}],
+  chapter: None,
 }
 
 let structure: pluginStructure = {
@@ -51,6 +53,7 @@ let structure: pluginStructure = {
       consumedEventTypes: ["StockLow"],
       producedCommandTypes: ["Restock"],
       targetName: "Product",
+      chapter: None,
     },
   ],
   outboundTranslationSlices: [
@@ -60,10 +63,17 @@ let structure: pluginStructure = {
       inboundCommandTypes: ["Ship"],
       targetName: None,
       externalSystem: None,
+      chapter: None,
     },
   ],
   inboundTranslationSlices: [
-    {name: "FromBilling", commandTypes: ["RecordPayment"], targetName: "Order", externalSystem: None},
+    {
+      name: "FromBilling",
+      commandTypes: ["RecordPayment"],
+      targetName: "Order",
+      externalSystem: None,
+      chapter: None,
+    },
   ],
   extensions: [
     {
@@ -143,6 +153,61 @@ describe("encodePluginStructureEntry", () => {
   testSync("encodes writableDef events", () =>
     expect(json->String.includes("\"events\":[{\"name\":\"ProductAdded\""))->toEqual(true)
   )
+
+  // Translation-slice externalSystem: absent on the fixture above (both None), so it
+  // must serialize as null — the "no external box" case.
+  testSync("encodes None outbound externalSystem as null", () =>
+    expect(json->String.includes("\"inboundCommandTypes\":[\"Ship\"],\"externalSystem\":null"))->toEqual(
+      true,
+    )
+  )
+
+  testSync("encodes None inbound externalSystem as null", () =>
+    expect(json->String.includes("\"commandTypes\":[\"RecordPayment\"],\"externalSystem\":null"))->toEqual(
+      true,
+    )
+  )
+})
+
+// A deployed-graph consumer draws the external-system boundary box off this field, so
+// a slice whose spec sets `externalSystem = Some("X")` must surface "X" on the wire for
+// both directions — the round-trip the plan pins.
+describe("translation-slice externalSystem round-trip", () => {
+  let externalStructure: pluginStructure = {
+    ...structure,
+    outboundTranslationSlices: [
+      {
+        name: "ToShipper",
+        consumedEventTypes: ["OrderPlaced"],
+        inboundCommandTypes: ["Ship"],
+        targetName: None,
+        externalSystem: Some("ShipperGateway"),
+        chapter: None,
+      },
+    ],
+    inboundTranslationSlices: [
+      {
+        name: "FromBilling",
+        commandTypes: ["RecordPayment"],
+        targetName: "Order",
+        externalSystem: Some("BillingProvider"),
+        chapter: None,
+      },
+    ],
+  }
+  let externalJson =
+    Platform_ComponentDefinitionsApi.encodePluginStructureEntry(
+      ~pluginId="Catalog",
+      externalStructure,
+    )->JSON.stringify
+
+  testSync("surfaces Some outbound externalSystem as its inner string", () =>
+    expect(externalJson->String.includes("\"externalSystem\":\"ShipperGateway\""))->toEqual(true)
+  )
+
+  testSync("surfaces Some inbound externalSystem as its inner string", () =>
+    expect(externalJson->String.includes("\"externalSystem\":\"BillingProvider\""))->toEqual(true)
+  )
 })
 
 describe("visibility filtering (deployed AutoUI hides Internal)", () => {
@@ -159,6 +224,7 @@ describe("visibility filtering (deployed AutoUI hides Internal)", () => {
     searchableFields: ["name"],
     statusField: None,
     visibility: Some("Internal"),
+    chapter: None,
   }
   let mixed: pluginStructure = {
     ...structure,
@@ -199,6 +265,7 @@ describe("allowedStates + statusField populated", () => {
     searchableFields: ["name"],
     statusField: Some("status"),
     visibility: None,
+    chapter: None,
   }
 
   let wblWithStates: writableDef = {
@@ -209,6 +276,7 @@ describe("allowedStates + statusField populated", () => {
     producedEventTypes: [],
     consumedEventTypes: [],
     events: [],
+    chapter: None,
   }
 
   let structureWithStates: pluginStructure = {

package/tests/admin/Platform_ComponentDefinitionsApiTest.res.mjs

@@ -39,7 +39,8 @@ let qbl = {
   labelField: "displayName",
   searchableFields: qbl_searchableFields,
   statusField: undefined,
-  visibility: undefined
+  visibility: undefined,
+  chapter: undefined
 };
 
 let wbl_commands = [cmd];
@@ -63,7 +64,8 @@ let wbl = {
   consumedEventTypes: wbl_consumedEventTypes,
   linkedViews: wbl_linkedViews,
   consistencyRead: undefined,
-  events: wbl_events
+  events: wbl_events,
+  chapter: undefined
 };
 
 let structure_readModels = [qbl];
@@ -78,7 +80,8 @@ let structure_automationSlices = [{
     name: "Restocker",
     consumedEventTypes: ["StockLow"],
     producedCommandTypes: ["Restock"],
-    targetName: "Product"
+    targetName: "Product",
+    chapter: undefined
   }];
 
 let structure_outboundTranslationSlices = [{
@@ -86,14 +89,16 @@ let structure_outboundTranslationSlices = [{
     consumedEventTypes: ["OrderPlaced"],
     inboundCommandTypes: ["Ship"],
     targetName: undefined,
-    externalSystem: undefined
+    externalSystem: undefined,
+    chapter: undefined
   }];
 
 let structure_inboundTranslationSlices = [{
     name: "FromBilling",
     commandTypes: ["RecordPayment"],
     targetName: "Order",
-    externalSystem: undefined
+    externalSystem: undefined,
+    chapter: undefined
   }];
 
 let structure_extensions = [{
@@ -168,6 +173,54 @@ globalThis.describe("encodePluginStructureEntry", () => {
   globalThis.test("encodes writableDef events", () => {
     globalThis.expect(json.includes("\"events\":[{\"name\":\"ProductAdded\"")).toEqual(true);
   });
+  globalThis.test("encodes None outbound externalSystem as null", () => {
+    globalThis.expect(json.includes("\"inboundCommandTypes\":[\"Ship\"],\"externalSystem\":null")).toEqual(true);
+  });
+  globalThis.test("encodes None inbound externalSystem as null", () => {
+    globalThis.expect(json.includes("\"commandTypes\":[\"RecordPayment\"],\"externalSystem\":null")).toEqual(true);
+  });
+});
+
+globalThis.describe("translation-slice externalSystem round-trip", () => {
+  let externalStructure_readModels = structure_readModels;
+  let externalStructure_stateViewSlices = structure_stateViewSlices;
+  let externalStructure_stateChangeSlices = structure_stateChangeSlices;
+  let externalStructure_aggregates = structure_aggregates;
+  let externalStructure_automationSlices = structure_automationSlices;
+  let externalStructure_outboundTranslationSlices = [{
+      name: "ToShipper",
+      consumedEventTypes: ["OrderPlaced"],
+      inboundCommandTypes: ["Ship"],
+      targetName: undefined,
+      externalSystem: "ShipperGateway",
+      chapter: undefined
+    }];
+  let externalStructure_inboundTranslationSlices = [{
+      name: "FromBilling",
+      commandTypes: ["RecordPayment"],
+      targetName: "Order",
+      externalSystem: "BillingProvider",
+      chapter: undefined
+    }];
+  let externalStructure_extensions = structure_extensions;
+  let externalStructure = {
+    readModels: externalStructure_readModels,
+    stateViewSlices: externalStructure_stateViewSlices,
+    stateChangeSlices: externalStructure_stateChangeSlices,
+    aggregates: externalStructure_aggregates,
+    automationSlices: externalStructure_automationSlices,
+    outboundTranslationSlices: externalStructure_outboundTranslationSlices,
+    inboundTranslationSlices: externalStructure_inboundTranslationSlices,
+    extensions: externalStructure_extensions,
+    extensionPoints: undefined
+  };
+  let externalJson = JSON.stringify(Platform_ComponentDefinitionsApi$ReventlessCore.encodePluginStructureEntry("Catalog", externalStructure));
+  globalThis.test("surfaces Some outbound externalSystem as its inner string", () => {
+    globalThis.expect(externalJson.includes("\"externalSystem\":\"ShipperGateway\"")).toEqual(true);
+  });
+  globalThis.test("surfaces Some inbound externalSystem as its inner string", () => {
+    globalThis.expect(externalJson.includes("\"externalSystem\":\"BillingProvider\"")).toEqual(true);
+  });
 });
 
 globalThis.describe("visibility filtering (deployed AutoUI hides Internal)", () => {
@@ -184,7 +237,8 @@ globalThis.describe("visibility filtering (deployed AutoUI hides Internal)", ()
     labelField: "name",
     searchableFields: internalQbl_searchableFields,
     statusField: undefined,
-    visibility: internalQbl_visibility
+    visibility: internalQbl_visibility,
+    chapter: undefined
   };
   let mixed_readModels = [
     qbl,
@@ -245,7 +299,8 @@ globalThis.describe("allowedStates + statusField populated", () => {
     labelField: "name",
     searchableFields: qblWithStatus_searchableFields,
     statusField: qblWithStatus_statusField,
-    visibility: undefined
+    visibility: undefined,
+    chapter: undefined
   };
   let wblWithStates_commands = [cmdWithStates];
   let wblWithStates_producedEventTypes = [];
@@ -259,7 +314,8 @@ globalThis.describe("allowedStates + statusField populated", () => {
     consumedEventTypes: wblWithStates_consumedEventTypes,
     linkedViews: wblWithStates_linkedViews,
     consistencyRead: undefined,
-    events: wblWithStates_events
+    events: wblWithStates_events,
+    chapter: undefined
   };
   let structureWithStates_readModels = [qblWithStatus];
   let structureWithStates_stateViewSlices = [];

package/tests/plugin/ManifestVisibilityTest.res.mjs

@@ -177,7 +177,7 @@ globalThis.describe("ReadModel visibility filter", () => {
 });
 
 globalThis.describe("Plugin_Structure.make — visibility tagging", () => {
-  let structure = Plugin_Structure$ReventlessCore.make("VisibilityPlugin", undefined, readModels, undefined, undefined, undefined, undefined, undefined, undefined, undefined);
+  let structure = Plugin_Structure$ReventlessCore.make("VisibilityPlugin", undefined, readModels, undefined, undefined, undefined, undefined, undefined, undefined, undefined, undefined);
   globalThis.test("readModels carries both Public and Internal entries", () => {
     globalThis.expect(structure.readModels.length).toBe(2);
   });

package/tests/plugin/PluginStructureTest.res

@@ -295,4 +295,38 @@ describe("Plugin_Structure.make — Phase 2 graph fields", () => {
       )->toBe(None)
     })
   })
+
+  // The generator captures each component's chapter (source-folder grouping band)
+  // and passes it as ~componentChapters; Plugin_Structure looks it up by Spec.name
+  // and threads it onto every def, so a deployed-graph consumer can render chapter
+  // bands without workspace access. See docs/plans/deployed-chapter-grouping.md.
+  describe("componentChapters threading", () => {
+    let chaptered = Plugin_Structure.make(
+      ~name="TestPlugin",
+      ~stateChangeSlices=[module(PsPlaceOrderSlice), module(PsShipOrderSlice)],
+      ~stateViewSlices=[module(PsOrdersViewSlice)],
+      // PlaceOrder + Orders live under a chapter; ShipOrder does not.
+      ~componentChapters=Dict.fromArray([("PlaceOrder", "Order"), ("Orders", "Order")]),
+    )
+
+    testSync("a chaptered state-change slice carries Some(chapter)", () => {
+      let placeOrder = chaptered.stateChangeSlices->Array.getUnsafe(0)
+      expect(placeOrder.chapter)->toEqual(Some("Order"))
+    })
+
+    testSync("a chaptered state-view slice carries Some(chapter)", () => {
+      let orders = chaptered.stateViewSlices->Array.getUnsafe(0)
+      expect(orders.chapter)->toEqual(Some("Order"))
+    })
+
+    testSync("a component absent from the map carries None", () => {
+      let shipOrder = chaptered.stateChangeSlices->Array.getUnsafe(1)
+      expect(shipOrder.chapter)->toEqual(None)
+    })
+
+    testSync("no ~componentChapters → every def is chapterless (None)", () => {
+      let placeOrder = structure.stateChangeSlices->Array.getUnsafe(0)
+      expect(placeOrder.chapter)->toEqual(None)
+    })
+  })
 })

package/tests/plugin/PluginStructureTest.res.mjs

@@ -183,7 +183,7 @@ let structure = Plugin_Structure$ReventlessCore.make("TestPlugin", undefined, un
 ], [
   PsPlaceOrderSlice,
   PsShipOrderSlice
-], undefined, undefined, undefined, undefined, undefined);
+], undefined, undefined, undefined, undefined, undefined, undefined);
 
 globalThis.describe("Plugin_Structure.make — Phase 2 graph fields", () => {
   globalThis.describe("stateChangeSlices", () => {
@@ -374,6 +374,37 @@ globalThis.describe("Plugin_Structure.make — Phase 2 graph fields", () => {
       globalThis.expect(Stdlib_Option.flatMap(orderIdField, s => getProperty(s, "x-reventless-id"))).toBe(undefined);
     });
   });
+  globalThis.describe("componentChapters threading", () => {
+    let chaptered = Plugin_Structure$ReventlessCore.make("TestPlugin", undefined, undefined, [PsOrdersViewSlice], [
+      PsPlaceOrderSlice,
+      PsShipOrderSlice
+    ], undefined, undefined, undefined, undefined, undefined, Object.fromEntries([
+      [
+        "PlaceOrder",
+        "Order"
+      ],
+      [
+        "Orders",
+        "Order"
+      ]
+    ]));
+    globalThis.test("a chaptered state-change slice carries Some(chapter)", () => {
+      let placeOrder = chaptered.stateChangeSlices[0];
+      globalThis.expect(placeOrder.chapter).toEqual("Order");
+    });
+    globalThis.test("a chaptered state-view slice carries Some(chapter)", () => {
+      let orders = chaptered.stateViewSlices[0];
+      globalThis.expect(orders.chapter).toEqual("Order");
+    });
+    globalThis.test("a component absent from the map carries None", () => {
+      let shipOrder = chaptered.stateChangeSlices[1];
+      globalThis.expect(shipOrder.chapter).toEqual(undefined);
+    });
+    globalThis.test("no ~componentChapters → every def is chapterless (None)", () => {
+      let placeOrder = structure.stateChangeSlices[0];
+      globalThis.expect(placeOrder.chapter).toEqual(undefined);
+    });
+  });
 });
 
 export {