@reventlessdev/reventless-spec 3.0.0-alpha.169 → 3.0.0-alpha.171

package/src/codemod/RenameToDecision.res.mjs

@@ -0,0 +1,334 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Nodefs from "node:fs";
+import * as Nodepath from "node:path";
+import * as Belt_Array from "@rescript/runtime/lib/es6/Belt_Array.js";
+import * as Stdlib_Array from "@rescript/runtime/lib/es6/Stdlib_Array.js";
+import * as Stdlib_JsExn from "@rescript/runtime/lib/es6/Stdlib_JsExn.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 Primitive_object from "@rescript/runtime/lib/es6/Primitive_object.js";
+import * as Primitive_option from "@rescript/runtime/lib/es6/Primitive_option.js";
+import * as Primitive_string from "@rescript/runtime/lib/es6/Primitive_string.js";
+import * as CliArgs$Reventless from "../CliArgs.res.mjs";
+import * as Nodechild_process from "node:child_process";
+import * as Primitive_exceptions from "@rescript/runtime/lib/es6/Primitive_exceptions.js";
+
+let usage = `Usage: reventless-rename-to-decision [--dry-run] [<dir>]
+
+  <dir>      where to start; the default is the current directory
+  --dry-run  print what would change, change nothing
+
+  Renames every *_Behavior.res to *_Decision.res (git mv inside a git work tree,
+  with its compiled output beside it), and in every .res and .resi file:
+  @@reventless.behavior -> @@reventless.decision, Behavior_GWT -> Decision_GWT,
+  Reventless.Behavior -> Reventless.Decision, thenRefused -> thenForbidden, and
+  <Spec>_Behavior -> <Spec>_Decision. Skips node_modules and lib.`;
+
+function parseArgs(argv) {
+  return Stdlib_Result.map(Stdlib_Result.flatMap(CliArgs$Reventless.parse(undefined, ["dry-run"], undefined, undefined, argv), a => CliArgs$Reventless.atMost(a, 1)), a => ({
+    dir: Stdlib_Option.getOr(CliArgs$Reventless.positionals(a)[0], "."),
+    dryRun: CliArgs$Reventless.bool(a, "dry-run")
+  }));
+}
+
+let cli = {
+  bin: "reventless-rename-to-decision",
+  usage: usage,
+  parse: parseArgs
+};
+
+let replacements = [
+  [
+    /@@reventless\.behavior\b/g,
+    "@@reventless.decision"
+  ],
+  [
+    /\bBehavior_GWT\.BehaviorSpec\b/g,
+    "Decision_GWT.DecisionSpec"
+  ],
+  [
+    /\bBehavior_GWT\.Behavior\b/g,
+    "Decision_GWT.Decision"
+  ],
+  [
+    /\bBehavior_GWT\b/g,
+    "Decision_GWT"
+  ],
+  [
+    /\bReventless\.Behavior\b/g,
+    "Reventless.Decision"
+  ],
+  [
+    /\bStateChangeSlice\.Behavior\b/g,
+    "StateChangeSlice.Decision"
+  ],
+  [
+    /\bMapping_GWT\.FromBehavior\b/g,
+    "Mapping_GWT.FromDecision"
+  ],
+  [
+    /\bthenRefused\b/g,
+    "thenForbidden"
+  ],
+  [
+    /\b([A-Z][A-Za-z0-9]*)_Behavior\b/g,
+    "$1_Decision"
+  ]
+];
+
+let localBinding = /^(\s*)module Behavior = /m;
+
+function rewrite(source) {
+  let text = Stdlib_Array.reduce(replacements, source, (text, param) => text.replace(param[0], param[1]));
+  if (localBinding.test(text)) {
+    return text.replace(/^(\s*)module Behavior = /gm, "$1module Decision = ").replace(/\bBehavior\./g, "Decision.");
+  } else {
+    return text;
+  }
+}
+
+let skippedDirs = [
+  "node_modules",
+  "lib",
+  ".git"
+];
+
+function isSource(name) {
+  if (name.endsWith(".res")) {
+    return true;
+  } else {
+    return name.endsWith(".resi");
+  }
+}
+
+let companions = [
+  ".res",
+  ".resi",
+  ".res.mjs",
+  ".res.js",
+  ".res.cjs"
+];
+
+function walk(dir, files) {
+  Nodefs.readdirSync(dir, {
+    withFileTypes: true
+  }).forEach(entry => {
+    let name = entry.name;
+    let path = Nodepath.join(dir, name);
+    if (entry.isDirectory()) {
+      if (!skippedDirs.includes(name)) {
+        return walk(path, files);
+      } else {
+        return;
+      }
+    } else if (entry.isFile()) {
+      files.push(path);
+      return;
+    } else {
+      return;
+    }
+  });
+}
+
+let byPath = Primitive_string.compare;
+
+function plan(dir) {
+  let files = [];
+  walk(dir, files);
+  files.sort(byPath);
+  let present = new Set(files);
+  let moves = files.filter(path => path.endsWith("_Behavior.res")).flatMap(source => {
+    let stem = source.slice(0, source.length - 13 | 0);
+    return Stdlib_Array.filterMap(companions, suffix => {
+      let from = stem + "_Behavior" + suffix;
+      if (present.has(from)) {
+        return {
+          from: from,
+          to_: stem + "_Decision" + suffix
+        };
+      }
+    });
+  });
+  let edits = Stdlib_Array.filterMap(files, path => {
+    if (!isSource(Nodepath.basename(path))) {
+      return;
+    }
+    let contents = Nodefs.readFileSync(path, "utf8");
+    let rewritten = rewrite(contents);
+    if (rewritten === contents) {
+      return;
+    } else {
+      return {
+        path: path,
+        contents: rewritten
+      };
+    }
+  });
+  let match = moves.find(param => present.has(param.to_));
+  if (match !== undefined) {
+    return {
+      TAG: "Error",
+      _0: match.to_ + ` already exists, so ` + match.from + ` cannot take its name. Nothing was changed.`
+    };
+  } else {
+    return {
+      TAG: "Ok",
+      _0: {
+        moves: moves,
+        edits: edits
+      }
+    };
+  }
+}
+
+function git(cwd, args) {
+  return Nodechild_process.spawnSync("git", args, {
+    cwd: cwd,
+    encoding: "utf8",
+    stdio: [
+      "ignore",
+      "pipe",
+      "pipe"
+    ]
+  });
+}
+
+function succeeded(result) {
+  return Primitive_object.equal(Primitive_option.fromNullable(result.status), 0);
+}
+
+function isTracked(path) {
+  return succeeded(git(Nodepath.dirname(path), [
+    "ls-files",
+    "--error-unmatch",
+    "--",
+    Nodepath.basename(path)
+  ]));
+}
+
+function moveFile(param) {
+  let to_ = param.to_;
+  let from = param.from;
+  if (isTracked(from)) {
+    let result = git(Nodepath.dirname(from), [
+      "mv",
+      "--",
+      Nodepath.basename(from),
+      Nodepath.basename(to_)
+    ]);
+    if (succeeded(result)) {
+      return {
+        TAG: "Ok",
+        _0: undefined
+      };
+    } else {
+      return {
+        TAG: "Error",
+        _0: `git mv ` + from + `: ` + Stdlib_Option.getOr(Primitive_option.fromNullable(result.stderr), "").trim()
+      };
+    }
+  }
+  try {
+    Nodefs.renameSync(from, to_);
+    return {
+      TAG: "Ok",
+      _0: undefined
+    };
+  } catch (raw_e) {
+    let e = Primitive_exceptions.internalToException(raw_e);
+    if (e.RE_EXN_ID === "JsExn") {
+      return {
+        TAG: "Error",
+        _0: `rename ` + from + `: ` + Stdlib_Option.getOr(Stdlib_JsExn.message(e._1), "failed")
+      };
+    }
+    throw e;
+  }
+}
+
+function apply(param) {
+  param.edits.forEach(param => {
+    Nodefs.writeFileSync(param.path, param.contents, "utf8");
+  });
+  return Stdlib_Array.reduce(param.moves, {
+    TAG: "Ok",
+    _0: undefined
+  }, (done, move) => Stdlib_Result.flatMap(done, () => moveFile(move)));
+}
+
+function describe(param, dryRun) {
+  let edits = param.edits;
+  let moves = param.moves;
+  let verb = dryRun ? "would " : "";
+  let lines = Belt_Array.concatMany([
+    moves.map(param => verb + `move  ` + param.from + ` -> ` + param.to_),
+    edits.map(param => verb + `edit  ` + param.path)
+  ]);
+  let movedSources = moves.filter(param => param.from.endsWith(".res")).length;
+  lines.push((
+    dryRun ? "Would rename" : "Renamed"
+  ) + ` ` + movedSources.toString() + ` file(s) and ` + (
+    dryRun ? "edit" : "edited"
+  ) + ` ` + edits.length.toString() + `.`);
+  return lines;
+}
+
+function execute(param) {
+  let dir = param.dir;
+  if (!Nodefs.existsSync(dir)) {
+    return {
+      TAG: "Error",
+      _0: dir + ` does not exist.`
+    };
+  }
+  let dryRun = param.dryRun;
+  return Stdlib_Result.flatMap(plan(dir), plan => {
+    if (dryRun) {
+      return {
+        TAG: "Ok",
+        _0: describe(plan, dryRun)
+      };
+    } else {
+      return Stdlib_Result.map(apply(plan), () => describe(plan, dryRun));
+    }
+  });
+}
+
+function main() {
+  return CliArgs$Reventless.run(cli, undefined, undefined, async args => {
+    let lines = execute(args);
+    if (lines.TAG === "Ok") {
+      lines._0.forEach(line => {
+        console.log(line);
+      });
+      return;
+    }
+    console.error(`reventless-rename-to-decision: ` + lines._0);
+    process.exit(1);
+  });
+}
+
+export {
+  usage,
+  parseArgs,
+  cli,
+  replacements,
+  localBinding,
+  rewrite,
+  skippedDirs,
+  isSource,
+  companions,
+  walk,
+  byPath,
+  plan,
+  git,
+  succeeded,
+  isTracked,
+  moveFile,
+  apply,
+  describe,
+  execute,
+  main,
+}
+/* node:fs Not a pure module */

package/src/components/Aggregate.res

@@ -2,7 +2,7 @@
 Module type for an aggregate's identity and schema specification.
 
 Every aggregate defines a `Spec` module satisfying this type. The `Spec` is
-used by `Platform.Aggregate.Make` and by `Behavior.T` to fix the aggregate's
+used by `Platform.Aggregate.Make` and by `Decision.T` to fix the aggregate's
 command, event, and error types.
 
 @example

package/src/components/CapabilityManifest.res

@@ -76,7 +76,7 @@ let fromStructure = (structure: Plugin.pluginStructure): t => {
   let capabilityKeys =
     needs->Array.map(d => d.capability)->Belt.Set.String.fromArray->Belt.Set.String.toArray
   let capabilities = capabilityKeys->Array.filterMap(key =>
-    // An unrecognised capability is dropped rather than passed through: the
+    // An unrecognized capability is dropped rather than passed through: the
     // generator downstream renders a real `Platform.capability` arm, and a name
     // this build cannot map has no arm to render.
     CapabilityNeed.fromString(key)->Option.map(need => {

package/src/components/ComponentKind.res

@@ -4,7 +4,7 @@
 // (`generator/Discovery`) and the external tooling that classifies files by
 // folder (`reventless-gwt`'s `ComponentMeta`) both derive from this, so the two
 // can't drift — previously the generator accepted plural/short folder names that
-// the gwt discovery silently didn't recognise.
+// the gwt discovery silently didn't recognize.
 
 type t =
   | StateChangeSlice
@@ -99,7 +99,7 @@ let bodySuffixes = [
   "_Projections",
   "_Projection",
   "_Mappings",
-  "_Behavior",
+  "_Decision",
   "_Automation",
   "_Translation",
 ]

package/src/components/ComponentKind.res.mjs

@@ -112,7 +112,7 @@ let bodySuffixes = [
   "_Projections",
   "_Projection",
   "_Mappings",
-  "_Behavior",
+  "_Decision",
   "_Automation",
   "_Translation"
 ];

package/src/components/DcbScopeInference.res

@@ -46,10 +46,10 @@ The four rules (over the representation):
     and this module stays schema-agnostic by taking the name alone.
 
     `byTag` marks the exception: an identity the *name* does not declare, which an
-    adapter recognised from an explicit `@partitionTag`. A domain's own identifier
+    adapter recognized from an explicit `@partitionTag`. A domain's own identifier
     is often not suffixed — `sku`, `isbn`, `vin` — and without this the annotation
     naming one would be extracted as a hint and then dropped, because `seedOf`
-    only honours a hint already among the produced keys. So the escape hatch would
+    only honors a hint already among the produced keys. So the escape hatch would
     have worked for every field except the ones that need it.
 
     It is carried rather than folded in because removing the annotation removes

package/src/components/DcbTag.res

@@ -100,7 +100,7 @@ let dcbPartitionTagId: S.Metadata.Id.t<bool> = S.Metadata.Id.make(
 Internal sury metadata ID marking a tag field as *cross-partition* — readable
 across every partition that carries it (a secondary-tag read), not just the
 partition it is the partition key of. Opt-in; absence = the default
-partition-scoped behaviour. The scope is a property of the tag *key* and must
+partition-scoped behavior. The scope is a property of the tag *key* and must
 agree across every event type that carries it (the fence-scope half depends on
 it). See `docs/analysis/dcb-consistency-check-issues.md` Issue 13.
 */
@@ -497,7 +497,7 @@ tag the catalog's own events write. A key derived from `lineItems` would name a
 tag no producer has ever written, and the decision read would come back empty —
 the identical symptom to extracting no tags at all, from a different cause. An
 author who wants another key still writes `DcbTag.stringForKey` on the nested
-field, which `resolveTagKey` honours here as it does at the top level.
+field, which `resolveTagKey` honors here as it does at the top level.
 */
 let nestedRecordTags = (fieldSchema: S.t<unknown>, jsonValue: JSON.t): array<tag> =>
   switch nestedRecordProperties(fieldSchema) {
@@ -655,7 +655,7 @@ let extractVariantNames = (schema: S.t<'a>): array<string> => {
       // intentionally excluded here: DCB event-type lookups can't WHERE-clause
       // on bare-string events, so Plugin_Structure.consumedEventTypes and
       // related graph fields would otherwise claim cross-component edges the
-      // runtime can't honour. Callers that need every constructor (e.g.
+      // runtime can't honor. Callers that need every constructor (e.g.
       // mapping-mode `acceptedTags` filters that match a JSON envelope's
       // `event` TAG against the Delegate's full constructor set) should call
       // [`extractAllVariantNames`] instead.
@@ -729,7 +729,7 @@ let isVariantPayloadBearing = (schema: S.t<'a>, name: string): bool => {
 Extracts tags from a flat JSON object, expanding array values into per-element tags.
 
 For scalar tagged fields, behaves identically to `extractTagsFromProperties`.
-For array tagged fields, produces one tag per element. Tag keys honour an optional
+For array tagged fields, produces one tag per element. Tag keys honor an optional
 `DcbTag.stringForKey(~key=...)` override on the (inner) schema; otherwise the field
 name is used.
 
@@ -1123,7 +1123,7 @@ let idFieldsOfProperties = (properties: dict<S.t<unknown>>): array<DcbScopeInfer
   let isIdName = (name: string) => name->String.endsWith("Ids") || name->String.endsWith("Id")
   // An explicit `@partitionTag` declares an identity the naming convention cannot
   // express — a domain's own identifier is often unsuffixed (`sku`, `isbn`).
-  // Without this the hint is extracted and then ignored, since `seedOf` honours
+  // Without this the hint is extracted and then ignored, since `seedOf` honors
   // only a hint already among the produced keys, so the escape hatch would work
   // for every field except the ones that need it. Flagged, not folded in: taking
   // the annotation away takes the identity with it, which is what the redundancy

package/src/components/OutboundTranslationSlice.res

@@ -76,14 +76,14 @@ module type Spec = {
   /**
   Event sources this slice subscribes to, by topic key.
 
-  `[]` — the default and the historical behaviour — means this plugin's own DCB
+  `[]` — the default and the historical behavior — means this plugin's own DCB
   event log. Naming sources explicitly subscribes to them instead: an Aggregate's
   `Spec.name`, or a DCB source name (conventionally `"<pluginName>DcbEventLog"`),
   matching the keys `AutomationSlice` mappings already use.
 
   This exists because an outbound slice is the framework's one component for
   *calling an external service and feeding the answer back*, and that job is not
-  specific to DCB-modelled entities. An Aggregate whose events should trigger an
+  specific to DCB-modeled entities. An Aggregate whose events should trigger an
   outbound call had no route to one while this list was hard-wired.
 
   Unlike `AutomationSlice`, the sources are a flat list rather than per-source

package/src/components/Plugin.res

@@ -173,7 +173,7 @@ type commandDef = {
       means the command does not move the row. */
   targetState: option<string>,
   /** Where the from-set came from, ranking an inherited edge against an authored
-      one the way `queryableDef.labelFieldSource` does for its field:
+      one the way `readSideDef.labelFieldSource` does for its field:
 
       - `"derived"` — the component's own scenarios.
       - `"declared"` — its `commandTransition` switch.
@@ -204,7 +204,7 @@ type commandDef = {
 }
 
 @schema
-type queryableDef = {
+type readSideDef = {
   name: string,
   queryField: string,
   schema: string,
@@ -276,7 +276,7 @@ type errorDef = {
 }
 
 @schema
-type writableDef = {
+type writeSideDef = {
   name: string,
   commands: array<commandDef>,
   producedEventTypes: array<string>,
@@ -289,7 +289,7 @@ type writableDef = {
       required list still lacks the key — both admin resolvers heal absent ones to
       `[]` on read, and a new one must be added there too. */
   errors: array<errorDef>,
-  /** Chapter grouping band — see `queryableDef.chapter`. */
+  /** Chapter grouping band — see `readSideDef.chapter`. */
   chapter: option<string>,
 }
 
@@ -299,7 +299,7 @@ type automationSliceDef = {
   consumedEventTypes: array<string>,
   producedCommandTypes: array<string>,
   targetName: string,
-  /** Chapter grouping band — see `queryableDef.chapter`. */
+  /** Chapter grouping band — see `readSideDef.chapter`. */
   chapter: option<string>,
   /** The declared `schedule`, as the JSON of `Schedule.timeSchema`; `None` for an
       automation started by events only, and in a structure from before the field. */
@@ -314,7 +314,7 @@ type outboundTranslationSliceDef = {
   targetName: option<string>,
   // Foreign system this slice publishes to — drives the external box (Event Graph).
   externalSystem: option<string>,
-  /** Chapter grouping band — see `queryableDef.chapter`. */
+  /** Chapter grouping band — see `readSideDef.chapter`. */
   chapter: option<string>,
   /** The topics this slice subscribes to, as `Spec.sourceNames` declares them —
       an Aggregate's `Spec.name` or a DCB source name. `Some([])` is the declared
@@ -333,7 +333,7 @@ type inboundTranslationSliceDef = {
   targetName: string,
   // Foreign system this slice receives from — drives the external box (Event Graph).
   externalSystem: option<string>,
-  /** Chapter grouping band — see `queryableDef.chapter`. */
+  /** Chapter grouping band — see `readSideDef.chapter`. */
   chapter: option<string>,
   /** The roles any of its commands' rules name; see `commandDef`. */
   requiredRoles?: array<string>,
@@ -393,7 +393,7 @@ type extensionDef = {
 An extension point owned by a plugin, from the producer side.
 
 `sourceEventTypes` are the `Delegate`'s events feeding the published protocol,
-plugin-qualified to match `writableDef.producedEventTypes`. `commandTypes` is the
+plugin-qualified to match `writeSideDef.producedEventTypes`. `commandTypes` is the
 EP's inbound protocol — None (read as []) for a `command = unit` EP, which routes
 nothing. Definitions persisted before a field was added must be re-emitted.
 */
@@ -451,7 +451,7 @@ whole structure.
 while it walks the components, because it is the only party that knows which one
 carried the declaration. Nothing in this record is a string a developer typed.
 
-It records ORIGIN, not behaviour — a grafted file is the host's to edit
+It records ORIGIN, not behavior — a grafted file is the host's to edit
 afterwards. What answers "does it still behave like the trait" is the trait's own
 conformance suite, which runs in the consumer's build and is not this field.
 */
@@ -474,10 +474,10 @@ is fabricated and warned about, so it is the one shape to avoid. Regression suit
 */
 @schema
 type pluginStructure = {
-  readModels: array<queryableDef>,
-  stateViewSlices: array<queryableDef>,
-  stateChangeSlices: array<writableDef>,
-  aggregates: array<writableDef>,
+  readModels: array<readSideDef>,
+  stateViewSlices: array<readSideDef>,
+  stateChangeSlices: array<writeSideDef>,
+  aggregates: array<writeSideDef>,
   automationSlices: array<automationSliceDef>,
   outboundTranslationSlices: array<outboundTranslationSliceDef>,
   inboundTranslationSlices: array<inboundTranslationSliceDef>,
@@ -499,7 +499,7 @@ type pluginStructure = {
       component. Absent → None, read as []. The only signal a graft leaves that
       survives into a deployed plugin — every other one (the dependency, the
       variant spread, the rules alias, the conformance binding) is source-side.
-      A claim about origin, never about behaviour: see `Trait`. */
+      A claim about origin, never about behavior: see `Trait`. */
   traitDeclarations: option<array<traitDeclaration>>,
 }
 

package/src/components/Plugin.res.mjs

@@ -106,7 +106,7 @@ let commandDefSchema = Sury.$schema(s => ({
   ownerField: s.m(Sury.$option(Sury.string))
 }));
 
-let queryableDefSchema = Sury.$schema(s => ({
+let readSideDefSchema = Sury.$schema(s => ({
   name: s.m(Sury.string),
   queryField: s.m(Sury.string),
   schema: s.m(Sury.string),
@@ -141,7 +141,7 @@ let errorDefSchema = Sury.$schema(s => ({
   references: s.m(Sury.array(fieldReferenceSchema))
 }));
 
-let writableDefSchema = Sury.$schema(s => ({
+let writeSideDefSchema = Sury.$schema(s => ({
   name: s.m(Sury.string),
   commands: s.m(Sury.array(commandDefSchema)),
   producedEventTypes: s.m(Sury.array(Sury.string)),
@@ -239,10 +239,10 @@ let traitDeclarationSchema = Sury.$schema(s => ({
 }));
 
 let pluginStructureSchema = Sury.$schema(s => ({
-  readModels: s.m(Sury.array(queryableDefSchema)),
-  stateViewSlices: s.m(Sury.array(queryableDefSchema)),
-  stateChangeSlices: s.m(Sury.array(writableDefSchema)),
-  aggregates: s.m(Sury.array(writableDefSchema)),
+  readModels: s.m(Sury.array(readSideDefSchema)),
+  stateViewSlices: s.m(Sury.array(readSideDefSchema)),
+  stateChangeSlices: s.m(Sury.array(writeSideDefSchema)),
+  aggregates: s.m(Sury.array(writeSideDefSchema)),
   automationSlices: s.m(Sury.array(automationSliceDefSchema)),
   outboundTranslationSlices: s.m(Sury.array(outboundTranslationSliceDefSchema)),
   inboundTranslationSlices: s.m(Sury.array(inboundTranslationSliceDefSchema)),
@@ -290,10 +290,10 @@ export {
   commandLevelSchema,
   fieldReferenceSchema,
   commandDefSchema,
-  queryableDefSchema,
+  readSideDefSchema,
   eventDefSchema,
   errorDefSchema,
-  writableDefSchema,
+  writeSideDefSchema,
   automationSliceDefSchema,
   outboundTranslationSliceDefSchema,
   inboundTranslationSliceDefSchema,

package/src/components/Sensitive.res

@@ -9,7 +9,7 @@ facts about one field.
 It is declared where the field is declared, and read by anything that composes
 text somebody will read. That is the whole reason it lives here rather than
 beside whichever consumer happens to need it first: a marking that exists in one
-consumer is a marking the rest of the system cannot honour, and the domain model
+consumer is a marking the rest of the system cannot honor, and the domain model
 is the only place that knows which values are sensitive.
 
 ## Absent means "not stated", not "safe"

package/src/components/Snapshot.res

@@ -1,15 +1,15 @@
 // Per-aggregate persisted-snapshot configuration
 // (docs/plans/done/aggregate-snapshotting.md).
 //
-// Snapshotting is opt-in and lives on the Behavior module (where `state` is
-// defined): `Behavior.T.snapshot = None` (the default, auto-injected by
-// `@@reventless.behavior`) keeps full replay; `Some(config)` makes the
+// Snapshotting is opt-in and lives on the Decision module (where `state` is
+// defined): `Decision.T.snapshot = None` (the default, auto-injected by
+// `@@reventless.decision`) keeps full replay; `Some(config)` makes the
 // aggregate write a keep-one snapshot every `interval` events and seed cold
 // replays from the latest one. Snapshots are a read optimization only — the
 // OCC append remains the sole consistency primitive, and a missing, corrupt,
 // or schema-drifted snapshot degrades to full replay.
 //
-// Enable via the file-level attribute on a behavior file:
+// Enable via the file-level attribute on a decision file:
 //
 //   @@reventless.snapshots(100)
 //
@@ -20,7 +20,7 @@
 type config<'state> = {
   /** Write a snapshot after every N appended events. Required — no default. */
   interval: int,
-  /** Sury schema for the behavior's state — serializes the persisted snapshot
+  /** Sury schema for the decision's state — serializes the persisted snapshot
       and (hashed) gates staleness across state-shape changes. */
   stateSchema: S.t<'state>,
 }

package/src/components/StateAnnotations.res

@@ -161,7 +161,7 @@ type stateAnnotationSpec = {
   command's declared edge is written in terms of, a board draws its columns
   from and a state diagram renders. `Some(name)` when one such annotation
   exists; the PPX errors on duplicate `@lifecycle` annotations within the same
-  record. Codegen consumes this to populate `queryableDef.lifecycleField`, and
+  record. Codegen consumes this to populate `readSideDef.lifecycleField`, and
   falls back to a field literally named `"lifecycle"` whose shape is an enum
   when this annotation is absent — so a record whose field can honestly be
   called `lifecycle` declares one without ceremony.