@reventlessdev/reventless-spec 3.0.0-alpha.100

package/src/components/Plugin.res.mjs

@@ -0,0 +1,264 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as S from "sury/src/S.res.mjs";
+import * as Offload$Reventless from "../semantic/Offload.res.mjs";
+import * as SuryResMjs from "sury/src/Sury.res.mjs";
+
+let pluginKindSchema = S.union([
+  S.literal("Domain"),
+  S.literal("PlatformInfrastructure"),
+  S.literal("Commercial"),
+  S.literal("Marketplace")
+]);
+
+let extensionPointDefinitionSchema = S.schema(s => ({
+  name: s.m(S.string),
+  commandTopic: s.m(S.string),
+  eventTopic: s.m(S.string)
+}));
+
+let extensionDefinitionSchema = S.schema(s => ({
+  name: s.m(S.string),
+  extensionPointName: s.m(S.string),
+  dcbSources: s.m(S.array(S.string))
+}));
+
+let dcbEventLogDefinitionSchema = S.schema(s => ({
+  name: s.m(S.string),
+  eventTopicArn: s.m(S.string)
+}));
+
+let extensionProtocolSchema = S.schema(s => ({
+  extensionPointName: s.m(S.string),
+  commandVersion: s.m(S.string),
+  eventVersion: s.m(S.string)
+}));
+
+let apiSchemaFragmentSchema = S.schema(s => ({
+  encoded: s.m(S.string),
+  protocol: s.m(S.string)
+}));
+
+let apiTargetSchema = S.union([
+  S.literal("Domain"),
+  S.literal("Platform")
+]);
+
+let apiSchemaFragmentOffloadSchema = Offload$Reventless.optionSchema(undefined, "pluginApiFragments", undefined, apiSchemaFragmentSchema);
+
+let dcbEventLogOptionSchema = SuryResMjs.js_nullable(dcbEventLogDefinitionSchema);
+
+let stringOptionSchema = SuryResMjs.js_nullable(S.string);
+
+let stringArrayOptionSchema = SuryResMjs.js_nullable(S.array(S.string));
+
+let boolOptionSchema = SuryResMjs.js_nullable(S.bool);
+
+let panelManifestEntrySchema = S.schema(s => ({
+  fragmentId: s.m(S.string),
+  title: s.m(S.string),
+  description: s.m(S.string),
+  positions: s.m(S.array(S.string)),
+  requiredAccess: s.m(stringOptionSchema)
+}));
+
+let menuEntrySchema = S.schema(s => ({
+  label: s.m(S.string),
+  icon: s.m(stringOptionSchema),
+  group: s.m(stringOptionSchema),
+  sortOrder: s.m(S.int)
+}));
+
+let pageManifestEntrySchema = S.schema(s => ({
+  fragmentId: s.m(S.string),
+  title: s.m(S.string),
+  menuEntry: s.m(menuEntrySchema),
+  requiredAccess: s.m(stringOptionSchema)
+}));
+
+let uiFragmentManifestSchema = S.schema(s => ({
+  remoteEntryUrl: s.m(S.string),
+  panels: s.m(S.array(panelManifestEntrySchema)),
+  pages: s.m(S.array(pageManifestEntrySchema))
+}));
+
+let uiFragmentManifestOptionSchema = SuryResMjs.js_nullable(uiFragmentManifestSchema);
+
+let commandLevelSchema = S.union([
+  S.literal("Collection"),
+  S.literal("Instance")
+]);
+
+let fieldReferenceSchema = S.schema(s => ({
+  fieldName: s.m(S.string),
+  entity: s.m(S.string),
+  plugin: s.m(stringOptionSchema)
+}));
+
+let commandDefSchema = S.schema(s => ({
+  name: s.m(S.string),
+  schema: s.m(S.string),
+  level: s.m(commandLevelSchema),
+  aggregateIdField: s.m(stringOptionSchema),
+  mutationField: s.m(S.string),
+  references: s.m(S.array(fieldReferenceSchema)),
+  allowedStates: s.m(stringArrayOptionSchema),
+  targetState: s.m(stringOptionSchema),
+  apiExposed: s.m(boolOptionSchema)
+}));
+
+let queryableDefSchema = S.schema(s => ({
+  name: s.m(S.string),
+  queryField: s.m(S.string),
+  schema: s.m(S.string),
+  consumedEventTypes: s.m(S.array(S.string)),
+  linkedWriteSide: s.m(S.array(S.string)),
+  labelField: s.m(S.string),
+  searchableFields: s.m(S.array(S.string)),
+  labelFieldSource: s.m(stringOptionSchema),
+  statusField: s.m(stringOptionSchema),
+  visibility: s.m(stringOptionSchema),
+  chapter: s.m(stringOptionSchema)
+}));
+
+let eventDefSchema = S.schema(s => ({
+  name: s.m(S.string),
+  schema: s.m(S.string),
+  references: s.m(S.array(fieldReferenceSchema))
+}));
+
+let writableDefSchema = S.schema(s => ({
+  name: s.m(S.string),
+  commands: s.m(S.array(commandDefSchema)),
+  producedEventTypes: s.m(S.array(S.string)),
+  consumedEventTypes: s.m(S.array(S.string)),
+  linkedViews: s.m(S.array(S.string)),
+  consistencyRead: s.m(stringOptionSchema),
+  events: s.m(S.array(eventDefSchema)),
+  chapter: s.m(stringOptionSchema)
+}));
+
+let automationSliceDefSchema = S.schema(s => ({
+  name: s.m(S.string),
+  consumedEventTypes: s.m(S.array(S.string)),
+  producedCommandTypes: s.m(S.array(S.string)),
+  targetName: s.m(S.string),
+  chapter: s.m(stringOptionSchema)
+}));
+
+let outboundTranslationSliceDefSchema = S.schema(s => ({
+  name: s.m(S.string),
+  consumedEventTypes: s.m(S.array(S.string)),
+  inboundCommandTypes: s.m(S.array(S.string)),
+  targetName: s.m(stringOptionSchema),
+  externalSystem: s.m(stringOptionSchema),
+  chapter: s.m(stringOptionSchema)
+}));
+
+let inboundTranslationSliceDefSchema = S.schema(s => ({
+  name: s.m(S.string),
+  commandTypes: s.m(S.array(S.string)),
+  targetName: s.m(S.string),
+  externalSystem: s.m(stringOptionSchema),
+  chapter: s.m(stringOptionSchema)
+}));
+
+let extensionDefSchema = S.schema(s => ({
+  name: s.m(S.string),
+  delegateNames: s.m(S.array(S.string)),
+  eventTypes: s.m(S.array(S.string)),
+  commandTypes: s.m(S.array(S.string))
+}));
+
+let extensionPointDefSchema = S.schema(s => ({
+  name: s.m(S.string),
+  delegateNames: s.m(S.array(S.string)),
+  sourceEventTypes: s.m(S.array(S.string)),
+  commandTypes: s.m(stringArrayOptionSchema)
+}));
+
+let extensionPointDefArrayOptionSchema = SuryResMjs.js_nullable(S.array(extensionPointDefSchema));
+
+let requiredStoreDeclarationSchema = S.schema(s => ({
+  store: s.m(S.string),
+  component: s.m(S.string),
+  field: s.m(S.string),
+  annotation: s.m(stringOptionSchema)
+}));
+
+let requiredStoreDeclarationArrayOptionSchema = SuryResMjs.js_nullable(S.array(requiredStoreDeclarationSchema));
+
+let pluginStructureSchema = S.schema(s => ({
+  readModels: s.m(S.array(queryableDefSchema)),
+  stateViewSlices: s.m(S.array(queryableDefSchema)),
+  stateChangeSlices: s.m(S.array(writableDefSchema)),
+  aggregates: s.m(S.array(writableDefSchema)),
+  automationSlices: s.m(S.array(automationSliceDefSchema)),
+  outboundTranslationSlices: s.m(S.array(outboundTranslationSliceDefSchema)),
+  inboundTranslationSlices: s.m(S.array(inboundTranslationSliceDefSchema)),
+  extensions: s.m(S.array(extensionDefSchema)),
+  extensionPoints: s.m(extensionPointDefArrayOptionSchema),
+  requiredStores: s.m(stringArrayOptionSchema),
+  requiredStoreDeclarations: s.m(requiredStoreDeclarationArrayOptionSchema)
+}));
+
+let pluginStructureOffloadSchema = Offload$Reventless.optionSchema(undefined, "pluginStructures", undefined, pluginStructureSchema);
+
+let pluginDefinitionSchema = S.schema(s => ({
+  id: s.m(S.string),
+  name: s.m(S.string),
+  version: s.m(S.string),
+  extensionPoints: s.m(S.array(extensionPointDefinitionSchema)),
+  extensions: s.m(S.array(extensionDefinitionSchema)),
+  eventCollector: s.m(S.string),
+  extensionProtocols: s.m(S.array(extensionProtocolSchema)),
+  apiSchemaFragment: s.m(apiSchemaFragmentOffloadSchema),
+  apiTarget: s.m(stringOptionSchema),
+  structure: s.m(pluginStructureOffloadSchema),
+  dcbEventLog: s.m(dcbEventLogOptionSchema),
+  kind: s.m(pluginKindSchema)
+}));
+
+let nameSchema = S.string;
+
+let versionSchema = S.string;
+
+export {
+  nameSchema,
+  versionSchema,
+  pluginKindSchema,
+  extensionPointDefinitionSchema,
+  extensionDefinitionSchema,
+  dcbEventLogDefinitionSchema,
+  extensionProtocolSchema,
+  apiSchemaFragmentSchema,
+  apiTargetSchema,
+  apiSchemaFragmentOffloadSchema,
+  dcbEventLogOptionSchema,
+  stringOptionSchema,
+  stringArrayOptionSchema,
+  boolOptionSchema,
+  panelManifestEntrySchema,
+  menuEntrySchema,
+  pageManifestEntrySchema,
+  uiFragmentManifestSchema,
+  uiFragmentManifestOptionSchema,
+  commandLevelSchema,
+  fieldReferenceSchema,
+  commandDefSchema,
+  queryableDefSchema,
+  eventDefSchema,
+  writableDefSchema,
+  automationSliceDefSchema,
+  outboundTranslationSliceDefSchema,
+  inboundTranslationSliceDefSchema,
+  extensionDefSchema,
+  extensionPointDefSchema,
+  extensionPointDefArrayOptionSchema,
+  requiredStoreDeclarationSchema,
+  requiredStoreDeclarationArrayOptionSchema,
+  pluginStructureSchema,
+  pluginStructureOffloadSchema,
+  pluginDefinitionSchema,
+}
+/* pluginKindSchema Not a pure module */

package/src/components/PluginName.res

@@ -0,0 +1,39 @@
+// Single source of truth for deriving a plugin's PascalCase name from its npm
+// package name, and for resolving the final plugin name from the (optional)
+// plugin.json `name` and package.json `name`. The plugin generator
+// (`generator/Config`) and the external tooling that reconstructs the domain
+// graph (`reventless-gwt`'s `LocalHost`) both derive from this, so the two can't
+// drift — a drift here silently breaks graph plugin keys (the graph would key
+// plugins under names that don't match the ones the generator bakes into
+// `Plugin.res`). See [[reference_ppx_spec_name_single_strip]] for the sibling
+// spec-name derivation.
+
+// "@scope/my-catalog" → "MyCatalog", "online-shop" → "OnlineShop".
+let fromPackageName = (packageName: string): string => {
+  let base = switch packageName->String.split("/") {
+  | [_scope, local] => local
+  | [local] => local
+  | parts => parts->Array.getUnsafe(parts->Array.length - 1)
+  }
+  base
+  ->String.split("-")
+  ->Array.flatMap(part => part->String.split("_"))
+  ->Array.map(word =>
+    if word === "" {
+      ""
+    } else {
+      word->String.slice(~start=0, ~end=1)->String.toUpperCase ++
+        word->String.slice(~start=1, ~end=word->String.length)
+    }
+  )
+  ->Array.join("")
+}
+
+// plugin.json `name` wins; else PascalCase(package.json `name`); else "Plugin".
+// The two callers each read the raw fields with their own node bindings, then
+// share this precedence so the resolution can never diverge.
+let resolve = (~pluginJsonName: option<string>, ~packageJsonName: option<string>): string =>
+  switch pluginJsonName {
+  | Some(name) => name
+  | None => packageJsonName->Option.map(fromPackageName)->Option.getOr("Plugin")
+  }

package/src/components/PluginName.res.mjs

@@ -0,0 +1,45 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
+
+function fromPackageName(packageName) {
+  let parts = packageName.split("/");
+  let len = parts.length;
+  let base;
+  if (len >= 3) {
+    base = parts[parts.length - 1 | 0];
+  } else {
+    switch (len) {
+      case 0 :
+        base = parts[parts.length - 1 | 0];
+        break;
+      case 1 :
+        base = parts[0];
+        break;
+      case 2 :
+        base = parts[1];
+        break;
+    }
+  }
+  return base.split("-").flatMap(part => part.split("_")).map(word => {
+    if (word === "") {
+      return "";
+    } else {
+      return word.slice(0, 1).toUpperCase() + word.slice(1, word.length);
+    }
+  }).join("");
+}
+
+function resolve(pluginJsonName, packageJsonName) {
+  if (pluginJsonName !== undefined) {
+    return pluginJsonName;
+  } else {
+    return Stdlib_Option.getOr(Stdlib_Option.map(packageJsonName, fromPackageName), "Plugin");
+  }
+}
+
+export {
+  fromPackageName,
+  resolve,
+}
+/* No side effect */

package/src/components/ReadModel.res

@@ -0,0 +1,199 @@
+/**
+Specifies how the sub-ID of a projected state row is supplied at query time.
+
+- `Field(name)` — the sub-ID comes from a field in the query response
+- `Argument(name)` — the sub-ID is passed as a GraphQL resolver argument
+- `NoSubId` — the read model has no sub-ID dimension
+*/
+type subId =
+  | Field(string)
+  | Argument(string)
+  | NoSubId
+
+/**
+Whether the GraphQL resolver field resolves to a single value or to a list.
+
+- `Single(fieldName)` — returns one item by ID
+- `Multi(fieldName)` — returns an array of items
+*/
+type resolvedField =
+  | Single(string)
+  | Multi(string)
+
+/** Source configuration for a single-ID GraphQL resolver. */
+type idResolverSourceConfig = {
+  idField: string,
+  subId: subId,
+  resolvedField: resolvedField,
+}
+
+/**
+Specifies which DynamoDB table field serves as the primary key in the resolver target.
+
+- `Index(indexName)` — resolve against an index using only the index ID
+- `IndexWithId(indexName, idField)` — resolve against an index with an explicit ID field
+- `Id` — resolve against the table's primary key
+*/
+type targetIdField =
+  | Index(string)
+  | IndexWithId(string, string)
+  | Id
+
+/** Target configuration for a single-ID GraphQL resolver. */
+type idResolverTargetConfig = {
+  pluginName?: string,
+  tableName: string,
+  idField: targetIdField,
+  subIdField?: string,
+}
+
+type resolveConfig<'source, 'target> = {
+  source: 'source,
+  target: 'target,
+}
+
+/** Configuration for a GraphQL resolver that resolves a single ID field. */
+type idResolverConfig = resolveConfig<idResolverSourceConfig, idResolverTargetConfig>
+
+/** Source configuration for a multi-ID (array) GraphQL resolver. */
+type idsResolverSourceConfig = {
+  idsField: string,
+  resolvedField: string,
+}
+
+/** Target configuration for a multi-ID (array) GraphQL resolver. */
+type idsResolverTargetConfig = {
+  pluginName?: string,
+  tableName: string,
+  subIdField?: string,
+}
+
+/** Configuration for a GraphQL resolver that resolves an array of ID fields. */
+type idsResolverConfig = resolveConfig<idsResolverSourceConfig, idsResolverTargetConfig>
+
+/** AppSync authorization rule associating a DynamoDB table with a Cognito group. */
+type authorization = {
+  tableName: string,
+  group: string,
+}
+
+/** How much of a DynamoDB global secondary index is projected into the index. */
+type projectionType = KEYS_ONLY | ALL | INCLUDE(array<string>)
+
+/**
+Configuration for a DynamoDB Global Secondary Index on a read model table.
+
+- `index` — the index name
+- `type_` — the DynamoDB attribute type of the index key (`"S"`, `"N"`, etc.)
+- `idField` / `subIdField` — index key field overrides (set to synthetic `_name_pk`/`_name_sk` for composite keys)
+- `pkFields` / `skFields` — source state field names for composite pk/sk; runtime uses these to compute synthetic attribute values
+- `pkSep` / `skSep` — separator for composite pk/sk concatenation (default `"/"`)
+- `projectionType` — which attributes are projected into the index
+- `authorization` — optional AppSync authorization rule
+*/
+type indexConfig = {
+  index: string,
+  type_: string,
+  idField?: string,
+  subIdField?: string,
+  pkFields?: array<string>,
+  pkSep?: string,
+  skFields?: array<string>,
+  skSep?: string,
+  projectionType: projectionType,
+  authorization?: authorization,
+}
+
+/**
+Composite-key configuration for a read model that has both a primary ID and a sub-ID.
+
+- `subIdField` — the DynamoDB range-key attribute name
+- `getSubId` — extracts the sub-ID string from a projected state value
+*/
+type subIdConfig<'state> = {
+  subIdField: string,
+  getSubId: 'state => string,
+}
+
+/**
+Infrastructure configuration for a read model.
+
+- `idResolvers` — GraphQL resolvers for single-ID lookups
+- `idsResolvers` — GraphQL resolvers for multi-ID (array) lookups
+- `indexes` — additional DynamoDB global secondary indexes
+
+Use the `config` factory function to build this with defaults.
+*/
+type config = {
+  idResolvers: array<idResolverConfig>,
+  idsResolvers: array<idsResolverConfig>,
+  indexes: array<indexConfig>,
+}
+
+/**
+Builds a `ReadModel.config` with all optional fields defaulting to empty arrays.
+
+@example
+```rescript
+// CategoriesReadModel.res
+let config = ReadModel.config()
+```
+*/
+let config = (~idResolvers=[], ~idsResolvers=[], ~indexes=[]) => {
+  idResolvers,
+  idsResolvers,
+  indexes,
+}
+
+/**
+Module type for a read model's identity and schema specification.
+
+@example
+```rescript
+// CategoriesReadModel.res
+module Id = Id.String
+let name = "Categories"
+
+@schema
+type state = {categoryId: string, name: string, archived: bool}
+
+let config = ReadModel.config()
+let subIdConfig = None
+```
+*/
+module type Spec = {
+  module Id: Id.T
+
+  /** Logical read model name, used as the DynamoDB table-name prefix. */
+  let name: string
+  let moduleUrl: string
+
+  /** The projected state type stored in the read model. Must carry `@schema`. */
+  @schema
+  type state
+
+  /** Sury schema for the state type — generated automatically by `@schema`. */
+  let stateSchema: S.t<state>
+
+  /** Infrastructure configuration (indexes, resolvers). */
+  let config: config
+
+  /** Optional composite-key configuration. `None` for single-key tables. */
+  let subIdConfig: option<subIdConfig<state>>
+
+  /** Authorization rule evaluated at the GraphQL resolver entry before any
+      query is resolved. Auto-injected by `@@reventless.spec` and on
+      structurally-detected inline spec modules — defaults to
+      `AllowAuthenticated`; override at the file/module level with
+      `@@reventless.authorize(<rule>)`. */
+  let authorization: Authorization.permission
+
+  /** AutoUI visibility hint. Auto-injected by `@@reventless.spec` and on
+      structurally-detected inline spec modules — defaults to
+      `Visibility.Public`; override at the file/module level with
+      `@@reventless.visibility(Internal)` to hide from the AutoUI manifest.
+      Does not affect GraphQL exposure, authorization, or resolver
+      provisioning. */
+  let visibility: Visibility.t
+}
+

package/src/components/ReadModel.res.mjs

@@ -0,0 +1,18 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+
+function config(idResolversOpt, idsResolversOpt, indexesOpt) {
+  let idResolvers = idResolversOpt !== undefined ? idResolversOpt : [];
+  let idsResolvers = idsResolversOpt !== undefined ? idsResolversOpt : [];
+  let indexes = indexesOpt !== undefined ? indexesOpt : [];
+  return {
+    idResolvers: idResolvers,
+    idsResolvers: idsResolvers,
+    indexes: indexes
+  };
+}
+
+export {
+  config,
+}
+/* No side effect */

package/src/components/Reference.res

@@ -0,0 +1,55 @@
+/** Identifies which entity a reference field points to. */
+type target = Semantic.referenceTarget
+
+/**
+A sury string schema annotated as an entity reference field.
+
+Use with `@s.matches(Reference.to_("EntityName"))` on command/event fields that
+carry a foreign-entity ID. Also implies DCB tag semantics so the field is
+automatically queryable in DCB event logs.
+
+Pass `~key` to override the DCB tag key (defaults to the field name). The
+`@ref` ppx shorthand supplies it automatically for plural `*Ids: array<string>`
+fields (singularizing, e.g. `productIds` → tag key `productId`) so they share a
+tag key with their singular-named producer events.
+
+Prefer the `@ref("EntityName")` ppx shorthand over writing `@s.matches(...)` by hand.
+
+@example
+```rescript
+@schema type command =
+  | PlaceOrder({
+      orderId: @s.matches(DcbTag.string) string,
+      customerId: @s.matches(Reference.to_("Customer")) string,
+    })
+```
+*/
+let to_ = (~plugin=?, ~key=?, entity: string): S.t<string> => {
+  // Reference-ness and DCB-tagged-ness are two independent facts that happen to
+  // co-occur here: this constructor declares both. `toWithoutDcbTag` declares
+  // only the first, and plain `DcbTag.string` only the second — so no consumer
+  // may infer either one from the other.
+  let base =
+    S.string
+    ->S.Metadata.set(~id=DcbTag.dcbTagId, true)
+    ->Semantic.mark(~id=Semantic.Id.reference, ~payload=ReferenceTo({entity, plugin}))
+  switch key {
+  | Some(k) => base->S.Metadata.set(~id=DcbTag.dcbTagKeyOverrideId, k)
+  | None => base
+  }
+}
+
+/** Returns the reference target if the schema carries `Reference.to_(...)` metadata. */
+let getTarget = (schema: S.t<unknown>): option<target> =>
+  switch Semantic.get(schema) {
+  | Some({payload: ReferenceTo(target)}) => Some(target)
+  | _ => None
+  }
+
+/**
+Like `to_` but does not imply DCB tag semantics.
+Use with `@ref("Entity") @noDcbTag` when the field references another entity
+but should not participate in content-based event routing.
+*/
+let toWithoutDcbTag = (~plugin=?, entity: string): S.t<string> =>
+  S.string->Semantic.mark(~id=Semantic.Id.reference, ~payload=ReferenceTo({entity, plugin}))

package/src/components/Reference.res.mjs

@@ -0,0 +1,50 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as S from "sury/src/S.res.mjs";
+import * as DcbTag$Reventless from "./DcbTag.res.mjs";
+import * as Semantic$Reventless from "../semantic/Semantic.res.mjs";
+
+function to_(plugin, key, entity) {
+  let base = Semantic$Reventless.mark(S.Metadata.set(S.string, DcbTag$Reventless.dcbTagId, true), Semantic$Reventless.Id.reference, {
+    TAG: "ReferenceTo",
+    _0: {
+      entity: entity,
+      plugin: plugin
+    }
+  });
+  if (key !== undefined) {
+    return S.Metadata.set(base, DcbTag$Reventless.dcbTagKeyOverrideId, key);
+  } else {
+    return base;
+  }
+}
+
+function getTarget(schema) {
+  let match = Semantic$Reventless.get(schema);
+  if (match === undefined) {
+    return;
+  }
+  let target = match.payload;
+  if (typeof target !== "object" || target.TAG !== "ReferenceTo") {
+    return;
+  } else {
+    return target._0;
+  }
+}
+
+function toWithoutDcbTag(plugin, entity) {
+  return Semantic$Reventless.mark(S.string, Semantic$Reventless.Id.reference, {
+    TAG: "ReferenceTo",
+    _0: {
+      entity: entity,
+      plugin: plugin
+    }
+  });
+}
+
+export {
+  to_,
+  getTarget,
+  toWithoutDcbTag,
+}
+/* S Not a pure module */

package/src/components/Snapshot.res

@@ -0,0 +1,26 @@
+// Per-aggregate persisted-snapshot configuration
+// (docs/plans/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
+// 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:
+//
+//   @@reventless.snapshots(100)
+//
+// which injects `let snapshot = Some({interval: 100, stateSchema})` (requires
+// `@schema type state` so sury generates the schema), or hand-write the
+// binding for full control.
+
+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
+      and (hashed) gates staleness across state-shape changes. */
+  stateSchema: S.t<'state>,
+}

package/src/components/Snapshot.res.mjs

@@ -0,0 +1,2 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+/* This output is empty. Its source's type definitions, externals and/or unused code got optimized away. */