@reventlessdev/reventless-spec 3.0.0-alpha.63 → 3.0.0-alpha.65

package/src/generator/Discovery.res.mjs

@@ -1,61 +1,9 @@
 // Generated by ReScript, PLEASE EDIT WITH CARE
 
 import * as Nodepath from "node:path";
+import * as ComponentKind$Reventless from "../components/ComponentKind.res.mjs";
 import * as Generator_Node$Reventless from "./Generator_Node.res.mjs";
 
-function folderToComponentType(folder) {
-  switch (folder) {
-    case "Aggregate" :
-    case "Aggregates" :
-      return "Aggregate";
-    case "Automation" :
-    case "AutomationSlice" :
-    case "AutomationSlices" :
-    case "Automations" :
-      return "AutomationSlice";
-    case "ExtensionPoint" :
-    case "ExtensionPoints" :
-      return "ExtensionPoint";
-    case "Extension" :
-    case "Extensions" :
-      return "Extension";
-    case "InboundTranslation" :
-    case "InboundTranslationSlice" :
-    case "InboundTranslationSlices" :
-    case "InboundTranslations" :
-      return "InboundTranslationSlice";
-    case "OutboundTranslation" :
-    case "OutboundTranslationSlice" :
-    case "OutboundTranslationSlices" :
-    case "OutboundTranslations" :
-      return "OutboundTranslationSlice";
-    case "ReadModelStream" :
-    case "ReadModelStreams" :
-      return "ReadModelStream";
-    case "ReadModel" :
-    case "ReadModels" :
-      return "ReadModel";
-    case "StateChange" :
-    case "StateChangeSlice" :
-    case "StateChangeSlices" :
-    case "StateChanges" :
-      return "StateChangeSlice";
-    case "StateViewSliceStream" :
-    case "StateViewSliceStreams" :
-      return "StateViewSliceStream";
-    case "StateView" :
-    case "StateViewSlice" :
-    case "StateViewSlices" :
-    case "StateViews" :
-      return "StateViewSlice";
-    case "Task" :
-    case "Tasks" :
-      return "Task";
-    default:
-      return;
-  }
-}
-
 function isAlwaysExcludedDir(name) {
   if (name === "Plugin" || name === "tests") {
     return true;
@@ -146,7 +94,7 @@ function walkDir(dir, relDir, parentComponentType, epGroup, exclude, acc) {
       if (isAlwaysExcludedDir(entryName)) {
         return;
       }
-      let ct = folderToComponentType(entryName);
+      let ct = ComponentKind$Reventless.folderToKind(entryName);
       if (ct === undefined) {
         return walkDir(Nodepath.join(dir, entryName), relPath, parentComponentType, epGroup, exclude, acc);
       }
@@ -199,6 +147,8 @@ function scan(srcDir, exclude) {
   return acc;
 }
 
+let folderToComponentType = ComponentKind$Reventless.folderToKind;
+
 export {
   folderToComponentType,
   isAlwaysExcludedDir,

package/src/generator/Pairing.res

@@ -57,6 +57,12 @@ type resolved = {
   // StateChangeSlice stems carrying `@@reventless.async` — codegen emits
   // `Platform.StateChangeSlice.MakeAsync` for these (CommandPending response).
   asyncStateChangeSlices: Dict.t<bool>,
+  // Spec names of StateChangeSlices / StateViewSlices (incl. Stream) carrying
+  // `@@reventless.systemCallable` — codegen threads them as
+  // `~systemCallableComponents` on `Platform.Plugin.make` so the AWS provider
+  // emits the dual-auth `@aws_cognito_user_pools(...) @aws_iam` directive on
+  // their GraphQL fields (deploy-time SigV4 system callers). Sorted.
+  systemCallableComponents: array<string>,
   aggregates: array<aggregateDef>,
   readModels: array<readModelDef>,
   tasks: array<string>,
@@ -139,22 +145,21 @@ let extractTargetName = (filePath: string): option<string> => {
   }
 }
 
-// Returns true if the spec file declares `@@reventless.async` at the file
-// level (Aggregate or StateChangeSlice opt-in to CommandPending response).
-// Falls back to false on read errors so a transient FS failure can't flip
-// component to async — the safe default is sync.
-let hasAsyncAttribute = (filePath: string): bool => {
+// Returns true if the spec file declares the given file-level attribute
+// (e.g. `@@reventless.async`, `@@reventless.systemCallable`). Falls back to
+// false on read errors so a transient FS failure can't flip a component
+// into the opt-in behavior — the safe default is the attribute being absent.
+let hasFileAttribute = (filePath: string, ~attr: string): bool => {
   try {
     let content = Generator_Node.readFileSync(filePath)
     let found = ref(false)
     content->String.split("\n")->Array.forEach(line => {
       let trimmed = line->String.trimStart
-      // Match `@@reventless.async` and tolerate a payload arg in the future.
+      // Match the bare attribute and tolerate a payload arg in the future.
       if (
-        trimmed->String.startsWith("@@reventless.async ") ||
-        trimmed->String.startsWith("@@reventless.async(") ||
-        trimmed === "@@reventless.async" ||
-        trimmed->String.startsWith("@@reventless.async\n")
+        trimmed->String.startsWith(attr ++ " ") ||
+        trimmed->String.startsWith(attr ++ "(") ||
+        trimmed === attr
       ) {
         found := true
       }
@@ -165,6 +170,73 @@ let hasAsyncAttribute = (filePath: string): bool => {
   }
 }
 
+// `@@reventless.async` — Aggregate or StateChangeSlice opt-in to async
+// command dispatch (CommandPending response).
+let hasAsyncAttribute = (filePath: string): bool =>
+  hasFileAttribute(filePath, ~attr="@@reventless.async")
+
+// `@@reventless.systemCallable` — StateChangeSlice / StateViewSlice opt-in to
+// deploy-time IAM (SigV4) invocation of the component's GraphQL fields.
+let hasSystemCallableAttribute = (filePath: string): bool =>
+  hasFileAttribute(filePath, ~attr="@@reventless.systemCallable")
+
+// The effective spec name of a file: the explicit `@@reventless.spec("Name")`
+// payload when present, the filename stem otherwise (mirroring the PPX's name
+// derivation). Needed because `systemCallableComponents` is matched against
+// `Spec.name` at deploy time — a stem-only value would silently miss specs
+// with an explicit name override.
+let effectiveSpecName = (filePath: string, ~stem: string): string => {
+  try {
+    let content = Generator_Node.readFileSync(filePath)
+    let name = ref(None)
+    content->String.split("\n")->Array.forEach(line => {
+      let trimmed = line->String.trimStart
+      if trimmed->String.startsWith("@@reventless.spec(") {
+        let firstQuote = trimmed->String.indexOf("\"")
+        let lastQuote = trimmed->String.lastIndexOf("\"")
+        if firstQuote >= 0 && lastQuote > firstQuote {
+          name := Some(trimmed->String.slice(~start=firstQuote + 1, ~end=lastQuote))
+        }
+      }
+    })
+    name.contents->Option.getOr(stem)
+  } catch {
+  | _ => stem
+  }
+}
+
+// Partition the ExtensionPoint mapping files into flat (ungrouped) and grouped
+// `extensionPointDef`s: every mapping sharing an `epGroup` collects into one
+// grouped entry; the ungrouped ones share a single flat (`group: None`) entry.
+// Pure (no I/O) so the grouping is unit-testable — in particular the A8 fix:
+// `Option.getOr`'s eager default previously re-created the group's array every
+// iteration, so a group with ≥2 mappings collapsed to `[]` and the generator
+// emitted a `Plugin.res` referencing a never-generated module.
+let groupExtensionPoints = (epFiles: array<Discovery.discoveredFile>): array<extensionPointDef> => {
+  let epByGroup: Dict.t<array<string>> = Dict.make()
+  let flatEpMappings: array<string> = []
+
+  epFiles->Array.forEach(({stem, epGroup}) =>
+    switch epGroup {
+    | None => flatEpMappings->Array.push(stem)
+    | Some(g) =>
+      switch Dict.get(epByGroup, g) {
+      | Some(arr) => arr->Array.push(stem)
+      | None => Dict.set(epByGroup, g, [stem])
+      }
+    }
+  )
+
+  let extensionPoints: array<extensionPointDef> = []
+  if flatEpMappings->Array.length > 0 {
+    extensionPoints->Array.push({group: None, mappings: flatEpMappings->sortedStems})
+  }
+  Dict.toArray(epByGroup)->Array.forEach(((group, mappings)) =>
+    extensionPoints->Array.push({group: Some(group), mappings: mappings->sortedStems})
+  )
+  extensionPoints
+}
+
 let resolve = (discovered: array<Discovery.discoveredFile>, ~srcDir: string): resolved => {
   let eventMappings = findEventMappings(~srcDir)
 
@@ -181,6 +253,8 @@ let resolve = (discovered: array<Discovery.discoveredFile>, ~srcDir: string): re
   let aggregateSpecs: array<string> = []
   let aggregateSpecRelPaths: Dict.t<string> = Dict.make()
   let stateChangeSliceRelPaths: Dict.t<string> = Dict.make()
+  // Shared by StateViewSlice and StateViewSliceStream (stems are unique).
+  let stateViewSliceRelPaths: Dict.t<string> = Dict.make()
   let aggregateBehaviors: array<string> = []
   let readModelStems: array<string> = []
   // Stream-enabled read model spec stems (the `ReadModelStream/` folder).
@@ -204,9 +278,15 @@ let resolve = (discovered: array<Discovery.discoveredFile>, ~srcDir: string): re
         stateChangeSliceRelPaths->Dict.set(stem, relPath)
       }
     | StateViewSlice =>
-      if !isImplStem(stem) { stateViewSlices->Array.push(stem) }
+      if !isImplStem(stem) {
+        stateViewSlices->Array.push(stem)
+        stateViewSliceRelPaths->Dict.set(stem, relPath)
+      }
     | StateViewSliceStream =>
-      if !isImplStem(stem) { stateViewSlicesStream->Array.push(stem) }
+      if !isImplStem(stem) {
+        stateViewSlicesStream->Array.push(stem)
+        stateViewSliceRelPaths->Dict.set(stem, relPath)
+      }
     | AutomationSlice =>
       if !isImplStem(stem) {
         automationSlices->Array.push(stem)
@@ -309,35 +389,7 @@ let resolve = (discovered: array<Discovery.discoveredFile>, ~srcDir: string): re
   )
 
   // ── ExtensionPoint grouping ────────────────────────────────────────────────
-  let epByGroup: Dict.t<array<string>> = Dict.make()
-  let flatEpMappings: array<string> = []
-
-  epFiles->Array.forEach(({stem, epGroup}) => {
-    switch epGroup {
-    | None => flatEpMappings->Array.push(stem)
-    | Some(g) =>
-      // `Option.getOr`'s default is evaluated eagerly, so the previous shape
-      // re-created and re-set a fresh empty array every iteration — overwriting
-      // the group's real entry and pushing onto a now-detached array. A group
-      // with ≥2 mappings ended up empty, emitting a Plugin.res that referenced a
-      // never-generated module (`Array.getUnsafe(0)` on `[]`). Use a switch so
-      // the create branch runs only when the group is genuinely absent.
-      switch Dict.get(epByGroup, g) {
-      | Some(arr) => arr->Array.push(stem)
-      | None => Dict.set(epByGroup, g, [stem])
-      }
-    }
-  })
-
-  let extensionPoints: array<extensionPointDef> = []
-
-  if flatEpMappings->Array.length > 0 {
-    extensionPoints->Array.push({group: None, mappings: flatEpMappings->sortedStems})
-  }
-
-  Dict.toArray(epByGroup)->Array.forEach(((group, mappings)) => {
-    extensionPoints->Array.push({group: Some(group), mappings: mappings->sortedStems})
-  })
+  let extensionPoints = groupExtensionPoints(epFiles)
 
   // ── targetName extraction ──────────────────────────────────────────────────
   let buildTargets = (stems: array<string>, relPaths: Dict.t<string>): Dict.t<option<string>> => {
@@ -381,6 +433,24 @@ let resolve = (discovered: array<Discovery.discoveredFile>, ~srcDir: string): re
       })
       d
     },
+    systemCallableComponents: {
+      let names = []
+      let collect = (stems: array<string>, relPaths: Dict.t<string>) =>
+        stems->Array.forEach(stem => {
+          switch Dict.get(relPaths, stem) {
+          | None => ()
+          | Some(relPath) =>
+            let filePath = Generator_Node.join([srcDir, relPath])
+            if hasSystemCallableAttribute(filePath) {
+              names->Array.push(effectiveSpecName(filePath, ~stem))
+            }
+          }
+        })
+      collect(stateChangeSlices, stateChangeSliceRelPaths)
+      collect(stateViewSlices, stateViewSliceRelPaths)
+      collect(stateViewSlicesStream, stateViewSliceRelPaths)
+      names->sortedStems
+    },
     aggregates,
     readModels,
     tasks: tasks->sortedStems,

package/src/generator/Pairing.res.mjs

@@ -3,6 +3,7 @@
 import * as Nodefs from "node:fs";
 import * as Nodepath from "node:path";
 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 Generator_Node$Reventless from "./Generator_Node.res.mjs";
 
 let implSuffixForStateChange = "_Behavior";
@@ -112,7 +113,7 @@ function extractTargetName(filePath) {
   }
 }
 
-function hasAsyncAttribute(filePath) {
+function hasFileAttribute(filePath, attr) {
   try {
     let content = Nodefs.readFileSync(filePath, "utf8");
     let found = {
@@ -120,7 +121,7 @@ function hasAsyncAttribute(filePath) {
     };
     content.split("\n").forEach(line => {
       let trimmed = line.trimStart();
-      if (trimmed.startsWith("@@reventless.async ") || trimmed.startsWith("@@reventless.async(") || trimmed === "@@reventless.async" || trimmed.startsWith("@@reventless.async\n")) {
+      if (trimmed.startsWith(attr + " ") || trimmed.startsWith(attr + "(") || trimmed === attr) {
         found.contents = true;
         return;
       }
@@ -131,6 +132,71 @@ function hasAsyncAttribute(filePath) {
   }
 }
 
+function hasAsyncAttribute(filePath) {
+  return hasFileAttribute(filePath, "@@reventless.async");
+}
+
+function hasSystemCallableAttribute(filePath) {
+  return hasFileAttribute(filePath, "@@reventless.systemCallable");
+}
+
+function effectiveSpecName(filePath, stem) {
+  try {
+    let content = Nodefs.readFileSync(filePath, "utf8");
+    let name = {
+      contents: undefined
+    };
+    content.split("\n").forEach(line => {
+      let trimmed = line.trimStart();
+      if (!trimmed.startsWith("@@reventless.spec(")) {
+        return;
+      }
+      let firstQuote = trimmed.indexOf("\"");
+      let lastQuote = trimmed.lastIndexOf("\"");
+      if (firstQuote >= 0 && lastQuote > firstQuote) {
+        name.contents = trimmed.slice(firstQuote + 1 | 0, lastQuote);
+        return;
+      }
+    });
+    return Stdlib_Option.getOr(name.contents, stem);
+  } catch (exn) {
+    return stem;
+  }
+}
+
+function groupExtensionPoints(epFiles) {
+  let epByGroup = {};
+  let flatEpMappings = [];
+  epFiles.forEach(param => {
+    let epGroup = param.epGroup;
+    let stem = param.stem;
+    if (epGroup !== undefined) {
+      let arr = epByGroup[epGroup];
+      if (arr !== undefined) {
+        arr.push(stem);
+      } else {
+        epByGroup[epGroup] = [stem];
+      }
+      return;
+    }
+    flatEpMappings.push(stem);
+  });
+  let extensionPoints = [];
+  if (flatEpMappings.length !== 0) {
+    extensionPoints.push({
+      group: undefined,
+      mappings: sortedStems(flatEpMappings)
+    });
+  }
+  Object.entries(epByGroup).forEach(param => {
+    extensionPoints.push({
+      group: param[0],
+      mappings: sortedStems(param[1])
+    });
+  });
+  return extensionPoints;
+}
+
 function resolve(discovered, srcDir) {
   let eventMappings = findEventMappings(srcDir);
   let stateChangeSlices = [];
@@ -145,6 +211,7 @@ function resolve(discovered, srcDir) {
   let aggregateSpecs = [];
   let aggregateSpecRelPaths = {};
   let stateChangeSliceRelPaths = {};
+  let stateViewSliceRelPaths = {};
   let aggregateBehaviors = [];
   let readModelStems = [];
   let readModelStreamStems = [];
@@ -168,6 +235,7 @@ function resolve(discovered, srcDir) {
       case "StateViewSlice" :
         if (!isImplStem(stem)) {
           stateViewSlices.push(stem);
+          stateViewSliceRelPaths[stem] = relPath;
           return;
         } else {
           return;
@@ -175,6 +243,7 @@ function resolve(discovered, srcDir) {
       case "StateViewSliceStream" :
         if (!isImplStem(stem)) {
           stateViewSlicesStream.push(stem);
+          stateViewSliceRelPaths[stem] = relPath;
           return;
         } else {
           return;
@@ -249,7 +318,7 @@ function resolve(discovered, srcDir) {
       );
     if (behaviorStem !== undefined) {
       let relPath = aggregateSpecRelPaths[spec];
-      let isAsync = relPath !== undefined ? hasAsyncAttribute(Nodepath.join(srcDir, relPath)) : false;
+      let isAsync = relPath !== undefined ? hasFileAttribute(Nodepath.join(srcDir, relPath), "@@reventless.async") : false;
       return {
         spec: spec,
         behavior: behaviorStem,
@@ -275,35 +344,7 @@ function resolve(discovered, srcDir) {
     }
   };
   let readModels = Stdlib_Array.filterMap(sortedStems(readModelStems), rm => pairReadModel(false, rm)).concat(Stdlib_Array.filterMap(sortedStems(readModelStreamStems), rm => pairReadModel(true, rm)));
-  let epByGroup = {};
-  let flatEpMappings = [];
-  epFiles.forEach(param => {
-    let epGroup = param.epGroup;
-    let stem = param.stem;
-    if (epGroup !== undefined) {
-      let arr = epByGroup[epGroup];
-      if (arr !== undefined) {
-        arr.push(stem);
-      } else {
-        epByGroup[epGroup] = [stem];
-      }
-      return;
-    }
-    flatEpMappings.push(stem);
-  });
-  let extensionPoints = [];
-  if (flatEpMappings.length !== 0) {
-    extensionPoints.push({
-      group: undefined,
-      mappings: sortedStems(flatEpMappings)
-    });
-  }
-  Object.entries(epByGroup).forEach(param => {
-    extensionPoints.push({
-      group: param[0],
-      mappings: sortedStems(param[1])
-    });
-  });
+  let extensionPoints = groupExtensionPoints(epFiles);
   let buildTargets = (stems, relPaths) => {
     let dict = {};
     stems.forEach(stem => {
@@ -314,6 +355,20 @@ function resolve(discovered, srcDir) {
     return dict;
   };
   let d = {};
+  let names = [];
+  let collect = (stems, relPaths) => {
+    stems.forEach(stem => {
+      let relPath = relPaths[stem];
+      if (relPath === undefined) {
+        return;
+      }
+      let filePath = Nodepath.join(srcDir, relPath);
+      if (hasFileAttribute(filePath, "@@reventless.systemCallable")) {
+        names.push(effectiveSpecName(filePath, stem));
+        return;
+      }
+    });
+  };
   return {
     stateChangeSlices: sortedStems(stateChangeSlices),
     stateViewSlices: sortedStems(stateViewSlices),
@@ -326,11 +381,12 @@ function resolve(discovered, srcDir) {
     outboundTranslationSliceTargets: buildTargets(outboundTranslationSlices, outboundTranslationSliceRelPaths),
     asyncStateChangeSlices: (stateChangeSlices.forEach(stem => {
       let relPath = stateChangeSliceRelPaths[stem];
-      if (relPath !== undefined && hasAsyncAttribute(Nodepath.join(srcDir, relPath))) {
+      if (relPath !== undefined && hasFileAttribute(Nodepath.join(srcDir, relPath), "@@reventless.async")) {
         d[stem] = true;
         return;
       }
     }), d),
+    systemCallableComponents: (collect(stateChangeSlices, stateChangeSliceRelPaths), collect(stateViewSlices, stateViewSliceRelPaths), collect(stateViewSlicesStream, stateViewSliceRelPaths), sortedStems(names)),
     aggregates: aggregates,
     readModels: readModels,
     tasks: sortedStems(tasks),
@@ -349,7 +405,11 @@ export {
   findEventMappings,
   sortedStems,
   extractTargetName,
+  hasFileAttribute,
   hasAsyncAttribute,
+  hasSystemCallableAttribute,
+  effectiveSpecName,
+  groupExtensionPoints,
   resolve,
 }
 /* node:fs Not a pure module */

package/src/types/Behavior.res

@@ -72,6 +72,14 @@ module type T = {
   */
   let decide: (state, Spec.command) => result<array<Spec.event>, Spec.error>
 
+  /** Persisted-snapshot configuration (docs/plans/aggregate-snapshotting.md).
+      `None` — the default, auto-injected by `@@reventless.behavior` — keeps
+      full replay; `Some({interval, stateSchema})` writes a keep-one snapshot
+      every `interval` events and seeds cold replays from the latest one.
+      Enable with `@@reventless.snapshots(<interval>)` (requires
+      `@schema type state`) or a manual binding. */
+  let snapshot: option<Snapshot.config<state>>
+
   /** File URL of this module (`import.meta.url`). Used by AWS builders to derive
       the npm specifier for runtime dynamic imports. */
   let moduleUrl: string