@reventlessdev/reventless-core 3.0.0-alpha.185 → 3.0.0-alpha.187

package/CHANGELOG.md

@@ -3,6 +3,21 @@
 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.187 (2026-07-28)
+
+### Features
+
+* **spec:** one semantic marker every typed semantic marks itself with ([aa18afc](https://github.com/ReventlessDev/reventless-core/commit/aa18afcf04c8edad9afe27e6fa4261d01e184da7))
+* **spec:** StorageRef — the first semantic type, declared on the field's type ([44f15c3](https://github.com/ReventlessDev/reventless-core/commit/44f15c37de71261d701d18a9f1ada6f481c4a8dc))
+
+
+# 3.0.0-alpha.186 (2026-07-27)
+
+### Features
+
+* **api:** event-history query — the Source A read counterpart ([9268b33](https://github.com/ReventlessDev/reventless-core/commit/9268b33a4835d4cd4bc79b38f19bc2b974853fa4))
+
+
 # 3.0.0-alpha.185 (2026-07-27)
 
 ### Bug Fixes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reventlessdev/reventless-core",
-  "version": "3.0.0-alpha.185",
+  "version": "3.0.0-alpha.187",
   "description": "Core package for Reventless framework",
   "license": "Apache-2.0",
   "jest": {
@@ -30,20 +30,20 @@
     "uuid": "^13.0.0",
     "@reventlessdev/rescript-effect": "0.1.0-alpha.31",
     "@reventlessdev/rescript-hash-object": "1.2.0-alpha.13",
-    "@reventlessdev/rescript-jest": "1.0.0-alpha.9",
     "@reventlessdev/rescript-fast-csv": "1.2.0-alpha.14",
     "@reventlessdev/rescript-node-streams": "1.1.0-alpha.13",
+    "@reventlessdev/rescript-jest": "1.0.0-alpha.9",
     "@reventlessdev/rescript-pulumi-pulumi": "2.3.0-alpha.17",
     "@reventlessdev/rescript-ssh2": "1.1.0-alpha.14",
-    "@reventlessdev/reventless-infra": "3.0.0-alpha.106",
     "@reventlessdev/rescript-uuid": "1.1.0-alpha.17",
-    "@reventlessdev/reventless-spec": "3.0.0-alpha.81",
-    "@reventlessdev/reventless-interop": "3.0.0-alpha.29"
+    "@reventlessdev/reventless-interop": "3.0.0-alpha.29",
+    "@reventlessdev/reventless-infra": "3.0.0-alpha.107",
+    "@reventlessdev/reventless-spec": "3.0.0-alpha.82"
   },
   "devDependencies": {
     "rescript": "12.3.0",
     "sury-ppx": "11.0.0-alpha.2",
-    "@reventlessdev/reventless-ppx": "1.0.0-alpha.56"
+    "@reventlessdev/reventless-ppx": "1.0.0-alpha.57"
   },
   "peerDependencies": {
     "rescript": "12.3.0"

package/src/components/Api/GraphQL_FragmentGenerator.res

@@ -62,6 +62,11 @@ let rec fromSchemaType = (
       collectedTypes->Array.push(`enum ${name} {\n  ${valuesStr}\n}`)
     }
     `${name}${bang}`
+  // GraphQL carries the value's shape, not its meaning: a storage ref is a
+  // String on the wire exactly as it is in the event log. The semantic reaches
+  // the UI through the field's JSON Schema, which is the channel that can
+  // express it.
+  | Semantic(_, inner) => fromSchemaType(~required, ~asInput, inner, collectedTypes, seenTypes)
   | Unknown => `String${bang}`
   }
 }
@@ -171,13 +176,14 @@ let emptyCapability: serverCapability = {filterFields: [], sortFields: []}
 // Convert a SchemaType.schemaType to its GraphQL scalar name (input position).
 // Mirrors the scalar branches of fromSchemaType — kept inline because we don't
 // emit `!`/list wrappers for filter inputs.
-let scalarOfSchemaType = (st: SchemaType.schemaType): string =>
+let rec scalarOfSchemaType = (st: SchemaType.schemaType): string =>
   switch st {
   | ScalarString => "String"
   | ScalarNumber => "Float"
   | ScalarBoolean => "Boolean"
   | ScalarBigInt => "String"
   | EntityId => "ID"
+  | Semantic(_, inner) => scalarOfSchemaType(inner)
   | _ => "String"
   }
 

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

@@ -71,6 +71,10 @@ function fromSchemaType(_required, _asInputOpt, _st, collectedTypes, seenTypes)
             collectedTypes.push(`enum ` + name$1 + ` {\n  ` + valuesStr + `\n}`);
           }
           return name$1 + bang;
+        case "Semantic" :
+          _st = st._1;
+          _asInputOpt = asInput;
+          continue;
       }
     }
   };
@@ -144,20 +148,28 @@ let emptyCapability = {
   sortFields: emptyCapability_sortFields
 };
 
-function scalarOfSchemaType(st) {
-  if (typeof st === "object") {
-    return "String";
-  }
-  switch (st) {
-    case "ScalarNumber" :
-      return "Float";
-    case "ScalarBoolean" :
-      return "Boolean";
-    case "EntityId" :
-      return "ID";
-    default:
-      return "String";
-  }
+function scalarOfSchemaType(_st) {
+  while (true) {
+    let st = _st;
+    if (typeof st !== "object") {
+      switch (st) {
+        case "ScalarNumber" :
+          return "Float";
+        case "ScalarBoolean" :
+          return "Boolean";
+        case "EntityId" :
+          return "ID";
+        default:
+          return "String";
+      }
+    } else {
+      if (st.TAG !== "Semantic") {
+        return "String";
+      }
+      _st = st._1;
+      continue;
+    }
+  };
 }
 
 function deriveServerCapability(schema) {

package/src/components/Api/SchemaType.res

@@ -9,6 +9,12 @@ type rec schemaType =
   | ArrayOf(schemaType)
   | ObjectRef(string, dict<schemaType>)
   | Enum(string, array<string>)
+  | /** A field whose type carries a semantic the IR has no dedicated shape for.
+        Wraps the shape the value actually has, so every consumer that only cares
+        about shape unwraps and is otherwise unaffected. `DateTime` and `EntityId`
+        are *not* expressed this way: they long predate the generic marker and
+        their JSON Schema `format` output is a published contract. */
+  Semantic(Reventless.Semantic.t, schemaType)
   | Unknown
 
 let isTagged = Reventless.DcbTag.isTagged
@@ -27,6 +33,26 @@ let isIdsFieldName = (name: string): bool => {
 }
 
 let rec fromSury = (~parentName: string, ~fieldName: string, schema: S.t<unknown>): schemaType => {
+  let shape = shapeOf(~parentName, ~fieldName, schema)
+  // Semantics the IR already has a dedicated shape for keep it: `dateTime` and
+  // `reference` are read below via `isDateTime` / `getTarget`, both of which now
+  // consult the generic marker, and their `format` output is a published
+  // contract. Every other semantic rides along as a wrapper, so surfacing a new
+  // one costs a value rather than a branch.
+  switch Reventless.Semantic.get(schema) {
+  | Some({id} as sem)
+    if id !== Reventless.Semantic.Id.dateTime && id !== Reventless.Semantic.Id.reference =>
+    Semantic(sem, shape)
+  | _ => shape
+  }
+}
+
+and shapeOf = (~parentName: string, ~fieldName: string, schema: S.t<unknown>): schemaType => {
+  // Two independent facts, checked independently. A DCB-tagged field is an
+  // entity id because it routes; a reference field is one because it points at
+  // an entity. Neither implies the other — a `@partitionTag` field carries no
+  // reference, and `Reference.toWithoutDcbTag` carries no tag — so collapsing
+  // these into one test would silently reclassify whichever case it dropped.
   if isTagged(schema) || Reventless.Reference.getTarget(schema)->Option.isSome {
     EntityId
   } else {

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

@@ -4,6 +4,7 @@ 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 DcbTag$Reventless from "@reventlessdev/reventless-spec/src/components/DcbTag.res.mjs";
 import * as DateTime$Reventless from "@reventlessdev/reventless-spec/src/types/DateTime.res.mjs";
+import * as Semantic$Reventless from "@reventlessdev/reventless-spec/src/semantic/Semantic.res.mjs";
 import * as Reference$Reventless from "@reventlessdev/reventless-spec/src/components/Reference.res.mjs";
 
 function isIdFieldName(name) {
@@ -27,6 +28,24 @@ function isIdsFieldName(name) {
 }
 
 function fromSury(parentName, fieldName, schema) {
+  let shape = shapeOf(parentName, fieldName, schema);
+  let sem = Semantic$Reventless.get(schema);
+  if (sem === undefined) {
+    return shape;
+  }
+  let id = sem.id;
+  if (id !== Semantic$Reventless.Id.dateTime && id !== Semantic$Reventless.Id.reference) {
+    return {
+      TAG: "Semantic",
+      _0: sem,
+      _1: shape
+    };
+  } else {
+    return shape;
+  }
+}
+
+function shapeOf(parentName, fieldName, schema) {
   if (DcbTag$Reventless.isTagged(schema) || Stdlib_Option.isSome(Reference$Reventless.getTarget(schema))) {
     return "EntityId";
   }
@@ -156,6 +175,7 @@ export {
   isIdFieldName,
   isIdsFieldName,
   fromSury,
+  shapeOf,
   fromSuryObject,
 }
 /* DcbTag-Reventless Not a pure module */

package/src/components/Api/SuryToJsonSchema.res

@@ -1,6 +1,8 @@
 // Shared utility: convert sury S.t<'a> schemas to JSON Schema objects.
 // Uses SchemaType as the shared intermediate representation.
 
+let log = Logger.fromEnv()
+
 // ── Helpers ──────────────────────────────────────────────────────────────
 
 let str = JSON.Encode.string
@@ -8,6 +10,18 @@ let str = JSON.Encode.string
 let jsonObject = (entries: array<(string, JSON.t)>): JSON.t =>
   JSON.Encode.object(Dict.fromArray(entries))
 
+// An absent plugin means "the declaring plugin's own", which the key's absence
+// says exactly. Writing an empty string instead would make "mine" and "unnamed"
+// indistinguishable to every reader.
+let withOptionalPlugin = (
+  entries: array<(string, JSON.t)>,
+  plugin: option<string>,
+): array<(string, JSON.t)> =>
+  switch plugin {
+  | Some(p) => entries->Array.concat([("plugin", JSON.Encode.string(p))])
+  | None => entries
+  }
+
 // Merge x-reventless-* extension properties from a Reventless.StateAnnotations.stateAnnotationSpec
 // into a property schema (a JSON Schema object). Returns the schema unchanged when the field
 // has no annotations or when the schema is not a JSON object.
@@ -70,7 +84,21 @@ let mergeAnnotations = (
     }
     switch spec.semantic->Array.find(((field, _)) => field === fieldName) {
     | Some((_, semanticId)) =>
-      obj->Dict.set("x-reventless-semantic", JSON.Encode.string(semanticId))
+      // The type wins. A typed declaration is better-sourced than an annotation
+      // — the compiler checked it and it cannot drift from the field's shape —
+      // so an annotation never overwrites one. A field carrying both is the
+      // domain saying two things about one value, which is worth hearing about
+      // rather than resolving in silence.
+      switch obj->Dict.get("x-reventless-semantic") {
+      | Some(fromType) =>
+        if fromType !== JSON.Encode.string(semanticId) {
+          log.warn(
+            ~comp="SuryToJsonSchema",
+            `field "${fieldName}" declares semantic "${semanticId}" by annotation but its type already carries ${fromType->JSON.stringify}; the type wins`,
+          )
+        }
+      | None => obj->Dict.set("x-reventless-semantic", JSON.Encode.string(semanticId))
+      }
     | None => ()
     }
     switch spec.metric->Array.find(((field, _)) => field === fieldName) {
@@ -107,9 +135,50 @@ let rec fromSchemaType = (st: SchemaType.schemaType): JSON.t =>
       ("type", str("string")),
       ("enum", JSON.Encode.array(values->Array.map(JSON.Encode.string))),
     ])
+  | Semantic(sem, inner) => fromSchemaType(inner)->withSemantic(sem)
   | Unknown => jsonObject([("type", str("string"))])
   }
 
+// Attach a type-carried semantic to a field's JSON Schema.
+//
+// This is the type path's emission point, and it is deliberately *not*
+// `mergeAnnotations`: that one is fed by the PPX-collected annotation spec,
+// which the PPX only ever collects on read-model `state` records. This walk is
+// schema-shape-driven and runs over every schema, commands and events included —
+// which is where a declaration like a storage ref has to live, since that is
+// where the value is first accepted.
+//
+// Both paths write the same `x-reventless-semantic` key, on purpose: one wire
+// format, whatever the source. The payload rides in sibling keys so a reader
+// that knows only the bare string still reads it correctly.
+and withSemantic = (fieldSchema: JSON.t, sem: Reventless.Semantic.t): JSON.t =>
+  switch fieldSchema->JSON.Decode.object {
+  | None => fieldSchema
+  | Some(obj) =>
+    obj->Dict.set("x-reventless-semantic", str(sem.id))
+    // The `type` discriminator is what lets a reader tell a type-carried
+    // semantic from an annotated one, and rank it above the annotation
+    // accordingly: the compiler checked this one, and it cannot drift from the
+    // field's shape.
+    obj->Dict.set("x-reventless-semantic-source", str("type"))
+    switch sem.payload {
+    | Plain => ()
+    | ReferenceTo({entity, plugin}) =>
+      obj->Dict.set(
+        "x-reventless-semantic-target",
+        jsonObject(withOptionalPlugin([("entity", str(entity))], plugin)),
+      )
+    | StoredIn({plugin, store}) =>
+      // An absent plugin means "this plugin's own store" — omit the key rather
+      // than writing an empty string, so a reader never has to tell those apart.
+      obj->Dict.set(
+        "x-reventless-semantic-target",
+        jsonObject(withOptionalPlugin([("store", str(store))], plugin)),
+      )
+    }
+    JSON.Encode.object(obj)
+  }
+
 and objectRefToJsonSchema = (
   ~annotations: option<Reventless.StateAnnotations.stateAnnotationSpec>=?,
   fields: dict<SchemaType.schemaType>,

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

@@ -1,9 +1,12 @@
 // Generated by ReScript, PLEASE EDIT WITH CARE
 
 import * as Stdlib_JSON from "@rescript/runtime/lib/es6/Stdlib_JSON.js";
+import * as Logger$ReventlessCore from "../../util/Logger.res.mjs";
 import * as SchemaType$ReventlessCore from "./SchemaType.res.mjs";
 import * as StateAnnotations$Reventless from "@reventlessdev/reventless-spec/src/components/StateAnnotations.res.mjs";
 
+let log = Logger$ReventlessCore.fromEnv();
+
 function str(prim) {
   return prim;
 }
@@ -12,6 +15,17 @@ function jsonObject(entries) {
   return Object.fromEntries(entries);
 }
 
+function withOptionalPlugin(entries, plugin) {
+  if (plugin !== undefined) {
+    return entries.concat([[
+        "plugin",
+        plugin
+      ]]);
+  } else {
+    return entries;
+  }
+}
+
 function mergeAnnotations(fieldSchema, fieldName, spec) {
   let obj = Stdlib_JSON.Decode.object(fieldSchema);
   if (obj === undefined) {
@@ -64,7 +78,15 @@ function mergeAnnotations(fieldSchema, fieldName, spec) {
   }
   let match$3 = spec.semantic.find(param => param[0] === fieldName);
   if (match$3 !== undefined) {
-    obj["x-reventless-semantic"] = match$3[1];
+    let semanticId = match$3[1];
+    let fromType = obj["x-reventless-semantic"];
+    if (fromType !== undefined) {
+      if (fromType !== semanticId) {
+        log.warn("SuryToJsonSchema", undefined, `field "` + fieldName + `" declares semantic "` + semanticId + `" by annotation but its type already carries ` + JSON.stringify(fromType) + `; the type wins`);
+      }
+    } else {
+      obj["x-reventless-semantic"] = semanticId;
+    }
   }
   let match$4 = spec.metric.find(param => param[0] === fieldName);
   if (match$4 !== undefined) {
@@ -167,8 +189,36 @@ function fromSchemaType(st) {
             st._1.map(prim => prim)
           ]
         ]);
+      case "Semantic" :
+        return withSemantic(fromSchemaType(st._1), st._0);
+    }
+  }
+}
+
+function withSemantic(fieldSchema, sem) {
+  let obj = Stdlib_JSON.Decode.object(fieldSchema);
+  if (obj === undefined) {
+    return fieldSchema;
+  }
+  obj["x-reventless-semantic"] = sem.id;
+  obj["x-reventless-semantic-source"] = "type";
+  let match = sem.payload;
+  if (typeof match === "object") {
+    if (match.TAG === "ReferenceTo") {
+      let match$1 = match._0;
+      obj["x-reventless-semantic-target"] = Object.fromEntries(withOptionalPlugin([[
+          "entity",
+          match$1.entity
+        ]], match$1.plugin));
+    } else {
+      let match$2 = match._0;
+      obj["x-reventless-semantic-target"] = Object.fromEntries(withOptionalPlugin([[
+          "store",
+          match$2.store
+        ]], match$2.plugin));
     }
   }
+  return obj;
 }
 
 function objectRefToJsonSchema(annotations, fields) {
@@ -231,12 +281,15 @@ function toJsonSchema(schema) {
 }
 
 export {
+  log,
   str,
   jsonObject,
+  withOptionalPlugin,
   mergeAnnotations,
   fromSchemaType,
+  withSemantic,
   objectRefToJsonSchema,
   deriveObjectSchema,
   toJsonSchema,
 }
-/* SchemaType-ReventlessCore Not a pure module */
+/* log Not a pure module */

package/src/plugin/component/Plugin_Builder.res

@@ -298,10 +298,15 @@ module Make = (
         ~mutationEntries,
         ~eventLogEntries,
       )
+      // The historical read counterpart of the Source A subscription — same
+      // event logs, same generation point, so the two cannot disagree about
+      // which streams exist.
+      let evtResult = Plugin_EventQuerySchema.generate(~plugin=name, ~eventLogEntries)
       let parts = GraphQL_Stitcher.decode(baseFragment)
       GraphQL_Stitcher.encode({
         ...parts,
-        types: Array.concat(parts.types, subResult.extraTypes),
+        types: Array.flat([parts.types, subResult.extraTypes, evtResult.extraTypes]),
+        queries: Array.concat(parts.queries, evtResult.queryFields),
         subscriptions: subResult.subscriptionFields,
         subscriptionSources: subResult.subscriptionSources,
       })
@@ -324,6 +329,11 @@ module Make = (
       })
     )
 
+    // Register the event-history query resolvers matching the SDL emitted above.
+    Spec.hooks.eventQueryResolverHook->Option.forEach(registerEventQueries =>
+      registerEventQueries({pluginName: name, eventLogEntries})
+    )
+
     // Register DCB StateChangeSlice publish functions in publishToAggregates so that
     // extensions whose Delegate is a DCB slice can dispatch commands to them.
     // All slices in a plugin share the same DCB command topic (same publishJsons).

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

@@ -32,6 +32,7 @@ import * as ExtensionMapping$ReventlessInfra from "@reventlessdev/reventless-inf
 import * as ExtensionPoint$ReventlessInterop from "@reventlessdev/reventless-interop/src/components/ExtensionPoint.res.mjs";
 import * as Heartbeat_Builder$ReventlessCore from "../../components/Heartbeat/Heartbeat_Builder.res.mjs";
 import * as ResourceAttribution$ReventlessCore from "../../ResourceAttribution.res.mjs";
+import * as Plugin_EventQuerySchema$ReventlessCore from "./Plugin_EventQuerySchema.res.mjs";
 import * as PluginExtensionPointSpec$ReventlessInfra from "@reventlessdev/reventless-infra/src/types/PluginExtensionPointSpec.res.mjs";
 import * as Plugin_SubscriptionSchema$ReventlessCore from "./Plugin_SubscriptionSchema.res.mjs";
 
@@ -226,11 +227,16 @@ function Make(Spec) {
         });
         let baseFragment = FragmentProvider.generateFragment(mutationEntries, queryEntries);
         let subResult = Plugin_SubscriptionSchema$ReventlessCore.generate(mutationEntries, eventLogEntries);
+        let evtResult = Plugin_EventQuerySchema$ReventlessCore.generate(extra$1, eventLogEntries);
         let parts = GraphQL_Stitcher$ReventlessCore.decode(baseFragment);
         let apiSchemaFragment = GraphQL_Stitcher$ReventlessCore.encode({
-          types: parts.types.concat(subResult.extraTypes),
+          types: [
+            parts.types,
+            subResult.extraTypes,
+            evtResult.extraTypes
+          ].flat(),
           mutations: parts.mutations,
-          queries: parts.queries,
+          queries: parts.queries.concat(evtResult.queryFields),
           subscriptions: subResult.subscriptionFields,
           subscriptionSources: subResult.subscriptionSources
         });
@@ -245,6 +251,10 @@ function Make(Spec) {
           eventLogEntries: eventLogEntries,
           subscriptionFields: GraphQL_Stitcher$ReventlessCore.decode(apiSchemaFragment).subscriptions
         }));
+        Stdlib_Option.forEach(Spec.hooks.eventQueryResolverHook, registerEventQueries => registerEventQueries({
+          pluginName: extra$1,
+          eventLogEntries: eventLogEntries
+        }));
         let slicePublishJsons = dcbResult.dcbPublishJsons;
         if (slicePublishJsons !== undefined) {
           stateChangeSlices.forEach(Sc => {

package/src/plugin/component/Plugin_EventQuerySchema.res

@@ -0,0 +1,121 @@
+// Plugin_EventQuerySchema.res
+// Generates the query counterpart of the Source A raw-event subscription:
+// one paginated `…EventHistory` connection per event log, so a client can ask
+// "what happened to this entity, in order, with who and when".
+//
+// Called by Plugin_Builder alongside Plugin_SubscriptionSchema, from the same
+// `eventLogEntries` array — so the query and the subscription can never drift
+// about which logs exist.
+//
+// The subscription (Plugin_SubscriptionSchema.sourceAFieldsAndTypes) answers
+// "something was just appended" and deliberately carries no envelope metadata.
+// This answers a historical question, so it carries the audit-relevant subset
+// of `Message.meta`: who (`user`), when (`time`), and the correlation /
+// causation chain. Transport and tracing fields (`ip`, `traceparent`,
+// `schemaVersion`) and the `headers` context bag are NOT exposed — `headers`
+// in particular carries cross-cutting context (tenant ids, feature flags) that
+// should not leave the server.
+
+open ReventlessInfra.Api
+
+// Shared supporting types, emitted once per fragment. The stitcher dedupes by
+// type name across fragments, so concatenating plugin + admin fragments stays
+// safe — the same contract `commandResultSdlTypes` relies on.
+let sharedSdlTypes: array<string> = [
+  `type EventMeta {
+  service: String!
+  time: String!
+  user: String
+  msgId: String!
+  correlationId: String!
+  causationId: String
+}`,
+  `type EventTag {
+  key: String!
+  value: String!
+}`,
+]
+
+let recordTypeName = (~plugin: string, ~displayName: string) =>
+  `${plugin}_${displayName}EventRecord`
+
+let historyFieldName = (~plugin: string, ~displayName: string) =>
+  `${plugin}_${displayName}EventHistory`
+
+let filterTypeName = (~plugin: string, ~displayName: string) =>
+  `${plugin}_${displayName}EventHistoryFilter`
+
+let recordSdl = (~typeName: string): string =>
+  `type ${typeName} {
+  position: String!
+  eventType: String!
+  payload: AWSJSON!
+  tags: [EventTag!]!
+  meta: EventMeta!
+  recordedAt: String!
+}`
+
+let connectionSdlTypes = (~typeName: string): array<string> => [
+  `type ${typeName}Edge {\n  node: ${typeName}!\n  cursor: String!\n}`,
+  `type ${typeName}Connection {\n  edges: [${typeName}Edge!]!\n  pageInfo: PageInfo!\n}`,
+]
+
+// `entityId` is the ergonomic filter and the audit-trail case: for an
+// aggregate log it matches the aggregate id, for a DCB log it matches ANY tag
+// value (the same semantics the MCP event-history handler uses).
+// `tagKey` + `tagValue` is the precise form, for a DCB event carrying several
+// ids where you mean one specific one.
+let filterSdl = (~typeName: string): string =>
+  `input ${typeName} {
+  entityId: ID
+  tagKey: String
+  tagValue: String
+  eventTypes: [String!]
+  user: String
+  timeFrom: String
+  timeTo: String
+}`
+
+type result = {
+  queryFields: array<string>,
+  extraTypes: array<string>,
+}
+
+/**
+Emit the event-history query field + supporting types for every distinct event
+log in `eventLogEntries`.
+
+Deduped by `displayName` exactly as the Source A subscription is: an aggregate
+and a DCB log that project the same display name describe one logical stream.
+*/
+let generate = (~plugin: string, ~eventLogEntries: array<eventLogSchemaEntry>): result => {
+  let seen: Set.t<string> = Set.make()
+  let queryFields: array<string> = []
+  let extraTypes: array<string> = []
+
+  eventLogEntries->Array.forEach(entry => {
+    let displayName = entry.displayName
+    if !(seen->Set.has(displayName)) {
+      seen->Set.add(displayName)
+      let typeName = recordTypeName(~plugin, ~displayName)
+      let filterName = filterTypeName(~plugin, ~displayName)
+      let fieldName = historyFieldName(~plugin, ~displayName)
+
+      extraTypes->Array.push(recordSdl(~typeName))
+      connectionSdlTypes(~typeName)->Array.forEach(t => extraTypes->Array.push(t))
+      extraTypes->Array.push(filterSdl(~typeName=filterName))
+
+      queryFields->Array.push(
+        `  ${fieldName}(filter: ${filterName}, first: Int, after: String, last: Int, before: String): ${typeName}Connection!`,
+      )
+    }
+  })
+
+  // Only pull in the shared types when this fragment actually emits a record
+  // type that references them — a plugin with no event logs stays untouched.
+  if queryFields->Array.length > 0 {
+    sharedSdlTypes->Array.forEach(t => extraTypes->Array.push(t))
+  }
+
+  {queryFields, extraTypes}
+}

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

@@ -0,0 +1,102 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+
+let sharedSdlTypes = [
+  `type EventMeta {
+  service: String!
+  time: String!
+  user: String
+  msgId: String!
+  correlationId: String!
+  causationId: String
+}`,
+  `type EventTag {
+  key: String!
+  value: String!
+}`
+];
+
+function recordTypeName(plugin, displayName) {
+  return plugin + `_` + displayName + `EventRecord`;
+}
+
+function historyFieldName(plugin, displayName) {
+  return plugin + `_` + displayName + `EventHistory`;
+}
+
+function filterTypeName(plugin, displayName) {
+  return plugin + `_` + displayName + `EventHistoryFilter`;
+}
+
+function recordSdl(typeName) {
+  return `type ` + typeName + ` {
+  position: String!
+  eventType: String!
+  payload: AWSJSON!
+  tags: [EventTag!]!
+  meta: EventMeta!
+  recordedAt: String!
+}`;
+}
+
+function connectionSdlTypes(typeName) {
+  return [
+    `type ` + typeName + `Edge {\n  node: ` + typeName + `!\n  cursor: String!\n}`,
+    `type ` + typeName + `Connection {\n  edges: [` + typeName + `Edge!]!\n  pageInfo: PageInfo!\n}`
+  ];
+}
+
+function filterSdl(typeName) {
+  return `input ` + typeName + ` {
+  entityId: ID
+  tagKey: String
+  tagValue: String
+  eventTypes: [String!]
+  user: String
+  timeFrom: String
+  timeTo: String
+}`;
+}
+
+function generate(plugin, eventLogEntries) {
+  let seen = new Set();
+  let queryFields = [];
+  let extraTypes = [];
+  eventLogEntries.forEach(entry => {
+    let displayName = entry.displayName;
+    if (seen.has(displayName)) {
+      return;
+    }
+    seen.add(displayName);
+    let typeName = recordTypeName(plugin, displayName);
+    let filterName = filterTypeName(plugin, displayName);
+    let fieldName = historyFieldName(plugin, displayName);
+    extraTypes.push(recordSdl(typeName));
+    connectionSdlTypes(typeName).forEach(t => {
+      extraTypes.push(t);
+    });
+    extraTypes.push(filterSdl(filterName));
+    queryFields.push(`  ` + fieldName + `(filter: ` + filterName + `, first: Int, after: String, last: Int, before: String): ` + typeName + `Connection!`);
+  });
+  if (queryFields.length !== 0) {
+    sharedSdlTypes.forEach(t => {
+      extraTypes.push(t);
+    });
+  }
+  return {
+    queryFields: queryFields,
+    extraTypes: extraTypes
+  };
+}
+
+export {
+  sharedSdlTypes,
+  recordTypeName,
+  historyFieldName,
+  filterTypeName,
+  recordSdl,
+  connectionSdlTypes,
+  filterSdl,
+  generate,
+}
+/* No side effect */

package/src/plugin/component/Plugin_Helpers.res

@@ -892,6 +892,19 @@ type mcpRegistrationParams = {
   subscriptionFields: array<string>,
 }
 
+// ---------------------------------------------------------------------------
+// Event-history query registration params. The SDL for these fields is emitted
+// by Plugin_EventQuerySchema from this same `eventLogEntries` array; this hook
+// hands a platform what it needs to register the matching resolvers. Kept apart
+// from mcpRegistrationParams (which carries the same two fields) because the
+// two consumers are unrelated: one registers GraphQL resolvers, the other MCP
+// resources, and either can exist without the other.
+// ---------------------------------------------------------------------------
+type eventQueryRegistrationParams = {
+  pluginName: string,
+  eventLogEntries: array<ReventlessInfra.Api.eventLogSchemaEntry>,
+}
+
 // Subscription infrastructure hook params — fired after allQueryDbs and allEventTopics
 // are assembled inside builderOutputs.  Lets the AWS platform wire StateTopic and
 // EventLogSubscription Lambdas without touching reventless-core.
@@ -943,6 +956,9 @@ type platformHooks = {
   subscriptionInfraHook?: subscriptionInfraParams => unit,
   // MCP tools and resources.
   mcpSchemaRegistrationHook?: mcpRegistrationParams => unit,
+  // Event-history query resolvers — the read counterpart of the Source A
+  // subscription (see Plugin_EventQuerySchema).
+  eventQueryResolverHook?: eventQueryRegistrationParams => unit,
   // ── AppSync resolver creation (AWS) ───────────────────────────────────
   preResolversSchemaHook?: (~name: string, ~version: string, Reventless.Plugin.apiSchemaFragment) => Pulumi.Output.t<unit>,
   // Admin equivalent of preResolversSchemaHook. Set by AWS platforms to push

package/tests/api/SuryToJsonSchemaTest.res

@@ -490,4 +490,133 @@ describe("SuryToJsonSchema:", () => {
       )->toBe(None)
     })
   })
+
+  // Reference-ness and DCB-tagged-ness are separate facts that happen to
+  // co-occur on `Reference.to_`. The schema walk tests them independently, and
+  // must keep doing so: a field can carry either alone, and a semantic type that
+  // is marked but deliberately *not* DCB-tagged (a storage ref, say) must not be
+  // dragged into entity-id classification by the other fact. Routing failures do
+  // not show up in a schema diff, so the distinction is pinned here executably.
+  describe("reference / DCB-tag decoupling:", () => {
+    let formatOf = (schema: JSON.t, fieldName: string): option<JSON.t> =>
+      getPropertyOf(schema, fieldName)->Option.flatMap(s => getProperty(s, "format"))
+
+    testSync("a DCB-tagged field with no reference is still an entity id", () => {
+      let schema = S.schema(s =>
+        {
+          "orderId": s.matches(Reventless.DcbTag.string),
+        }
+      )->S.castToUnknown
+      let json = SuryToJsonSchema.deriveObjectSchema(schema)
+      expect(formatOf(json, "orderId"))->toEqual(Some(JSON.Encode.string("uuid")))
+      expect(Reventless.Reference.getTarget(schema))->toBe(None)
+    })
+
+    testSync("a reference without a DCB tag is still an entity id", () => {
+      let field = Reventless.Reference.toWithoutDcbTag("Customer")
+      let schema = S.schema(s => {"customerId": s.matches(field)})->S.castToUnknown
+      let json = SuryToJsonSchema.deriveObjectSchema(schema)
+      expect(formatOf(json, "customerId"))->toEqual(Some(JSON.Encode.string("uuid")))
+      expect(Reventless.DcbTag.isTagged(field->S.castToUnknown))->toBe(false)
+    })
+
+    testSync("Reference.to_ carries both facts", () => {
+      let field = Reventless.Reference.to_("Customer")
+      expect(Reventless.DcbTag.isTagged(field->S.castToUnknown))->toBe(true)
+      expect(
+        Reventless.Reference.getTarget(field->S.castToUnknown)->Option.map(t => t.entity),
+      )->toEqual(Some("Customer"))
+    })
+
+    testSync("neither reference nor tag emits x-reventless-semantic on the wire", () => {
+      // `dateTime` and `reference` predate the generic marker and keep emitting
+      // `format`; adding the semantic key for them would change a published
+      // contract. Only semantics without a dedicated shape surface as the key.
+      let schema = S.schema(s =>
+        {
+          "customerId": s.matches(Reventless.Reference.to_("Customer")),
+          "placedAt": s.matches(Reventless.DateTime.string),
+        }
+      )->S.castToUnknown
+      let json = SuryToJsonSchema.deriveObjectSchema(schema)
+      let semanticOf = fieldName =>
+        getPropertyOf(json, fieldName)->Option.flatMap(s =>
+          getProperty(s, "x-reventless-semantic")
+        )
+      expect(semanticOf("customerId"))->toBe(None)
+      expect(semanticOf("placedAt"))->toBe(None)
+    })
+  })
+
+  // The reason the generic marker exists. `x-reventless-semantic` used to be
+  // emitted only by the annotation merge, which is fed by a PPX pass that only
+  // ever runs on read-model `state` records — so a command field could not carry
+  // a semantic at all. This walk is shape-driven and runs over every schema, so
+  // the declaration reaches the place the value is first accepted.
+  describe("type-carried semantics on a command field:", () => {
+    let semanticOf = (json, fieldName) =>
+      getPropertyOf(json, fieldName)->Option.flatMap(s => getProperty(s, "x-reventless-semantic"))
+
+    testSync("a storage-ref command field emits the semantic id", () => {
+      let schema = S.schema(s =>
+        {
+          "productId": s.matches(S.string),
+          "imageUrl": s.matches(Reventless.StorageRef.forStore(~store="productImages")),
+        }
+      )->S.castToUnknown
+      let json = SuryToJsonSchema.deriveObjectSchema(schema)
+      expect(semanticOf(json, "imageUrl"))->toEqual(Some(JSON.Encode.string("storageRef")))
+      expect(semanticOf(json, "productId"))->toBe(None)
+    })
+
+    testSync("it carries the store identity and marks the type as its source", () => {
+      let schema = S.schema(s =>
+        {
+          "imageUrl": s.matches(
+            Reventless.StorageRef.forStore(~plugin="catalog", ~store="productImages"),
+          ),
+        }
+      )->S.castToUnknown
+      let json = SuryToJsonSchema.deriveObjectSchema(schema)
+      let field = getPropertyOf(json, "imageUrl")
+      expect(field->Option.flatMap(s => getProperty(s, "x-reventless-semantic-source")))->toEqual(
+        Some(JSON.Encode.string("type")),
+      )
+      expect(field->Option.flatMap(s => getProperty(s, "x-reventless-semantic-target")))->toEqual(
+        Some(
+          JSON.Encode.object(
+            Dict.fromArray([
+              ("store", JSON.Encode.string("productImages")),
+              ("plugin", JSON.Encode.string("catalog")),
+            ]),
+          ),
+        ),
+      )
+    })
+
+    testSync("the underlying string shape is unchanged", () => {
+      // The marker refines an existing `string` field; nothing about what is
+      // stored changes, which is why it can be retrofitted onto a live schema.
+      let schema = S.schema(s =>
+        {"imageUrl": s.matches(Reventless.StorageRef.forStore(~store="productImages"))}
+      )->S.castToUnknown
+      let json = SuryToJsonSchema.deriveObjectSchema(schema)
+      expect(
+        getPropertyOf(json, "imageUrl")->Option.flatMap(s => getProperty(s, "type")),
+      )->toEqual(Some(JSON.Encode.string("string")))
+    })
+
+    testSync("a type-carried semantic beats an annotation naming the same field", () => {
+      let withSpec = (schema, spec) =>
+        schema->S.Metadata.set(~id=Reventless.StateAnnotations.stateAnnotationsId, spec)
+      let schema =
+        S.schema(s =>
+          {"imageUrl": s.matches(Reventless.StorageRef.forStore(~store="productImages"))}
+        )
+        ->S.castToUnknown
+        ->withSpec({...emptySpec, semantic: [("imageUrl", "image")]})
+      let json = SuryToJsonSchema.deriveObjectSchema(schema)
+      expect(semanticOf(json, "imageUrl"))->toEqual(Some(JSON.Encode.string("storageRef")))
+    })
+  })
 })

package/tests/api/SuryToJsonSchemaTest.res.mjs

@@ -5,7 +5,10 @@ import * as Stdlib_JSON from "@rescript/runtime/lib/es6/Stdlib_JSON.js";
 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 Primitive_string from "@rescript/runtime/lib/es6/Primitive_string.js";
+import * as DcbTag$Reventless from "@reventlessdev/reventless-spec/src/components/DcbTag.res.mjs";
 import * as DateTime$Reventless from "@reventlessdev/reventless-spec/src/types/DateTime.res.mjs";
+import * as Reference$Reventless from "@reventlessdev/reventless-spec/src/components/Reference.res.mjs";
+import * as StorageRef$Reventless from "@reventlessdev/reventless-spec/src/semantic/StorageRef.res.mjs";
 import * as StateAnnotations$Reventless from "@reventlessdev/reventless-spec/src/components/StateAnnotations.res.mjs";
 import * as SuryToJsonSchema$ReventlessCore from "../../src/components/Api/SuryToJsonSchema.res.mjs";
 
@@ -833,6 +836,107 @@ globalThis.describe("SuryToJsonSchema:", () => {
       globalThis.expect(Stdlib_Option.flatMap(entityIdSchema, s => getProperty(s, "x-reventless-id"))).toBe(undefined);
     });
   });
+  globalThis.describe("reference / DCB-tag decoupling:", () => {
+    let formatOf = (schema, fieldName) => Stdlib_Option.flatMap(getPropertyOf(schema, fieldName), s => getProperty(s, "format"));
+    globalThis.test("a DCB-tagged field with no reference is still an entity id", () => {
+      let schema = S.schema(s => ({
+        orderId: s.m(DcbTag$Reventless.string)
+      }));
+      let json = SuryToJsonSchema$ReventlessCore.deriveObjectSchema(schema);
+      globalThis.expect(formatOf(json, "orderId")).toEqual("uuid");
+      globalThis.expect(Reference$Reventless.getTarget(schema)).toBe(undefined);
+    });
+    globalThis.test("a reference without a DCB tag is still an entity id", () => {
+      let field = Reference$Reventless.toWithoutDcbTag(undefined, "Customer");
+      let schema = S.schema(s => ({
+        customerId: s.m(field)
+      }));
+      let json = SuryToJsonSchema$ReventlessCore.deriveObjectSchema(schema);
+      globalThis.expect(formatOf(json, "customerId")).toEqual("uuid");
+      globalThis.expect(DcbTag$Reventless.isTagged(field)).toBe(false);
+    });
+    globalThis.test("Reference.to_ carries both facts", () => {
+      let field = Reference$Reventless.to_(undefined, undefined, "Customer");
+      globalThis.expect(DcbTag$Reventless.isTagged(field)).toBe(true);
+      globalThis.expect(Stdlib_Option.map(Reference$Reventless.getTarget(field), t => t.entity)).toEqual("Customer");
+    });
+    globalThis.test("neither reference nor tag emits x-reventless-semantic on the wire", () => {
+      let schema = S.schema(s => ({
+        customerId: s.m(Reference$Reventless.to_(undefined, undefined, "Customer")),
+        placedAt: s.m(DateTime$Reventless.string)
+      }));
+      let json = SuryToJsonSchema$ReventlessCore.deriveObjectSchema(schema);
+      let semanticOf = fieldName => Stdlib_Option.flatMap(getPropertyOf(json, fieldName), s => getProperty(s, "x-reventless-semantic"));
+      globalThis.expect(semanticOf("customerId")).toBe(undefined);
+      globalThis.expect(semanticOf("placedAt")).toBe(undefined);
+    });
+  });
+  globalThis.describe("type-carried semantics on a command field:", () => {
+    let semanticOf = (json, fieldName) => Stdlib_Option.flatMap(getPropertyOf(json, fieldName), s => getProperty(s, "x-reventless-semantic"));
+    globalThis.test("a storage-ref command field emits the semantic id", () => {
+      let schema = S.schema(s => ({
+        productId: s.m(S.string),
+        imageUrl: s.m(StorageRef$Reventless.forStore(undefined, "productImages"))
+      }));
+      let json = SuryToJsonSchema$ReventlessCore.deriveObjectSchema(schema);
+      globalThis.expect(semanticOf(json, "imageUrl")).toEqual("storageRef");
+      globalThis.expect(semanticOf(json, "productId")).toBe(undefined);
+    });
+    globalThis.test("it carries the store identity and marks the type as its source", () => {
+      let schema = S.schema(s => ({
+        imageUrl: s.m(StorageRef$Reventless.forStore("catalog", "productImages"))
+      }));
+      let json = SuryToJsonSchema$ReventlessCore.deriveObjectSchema(schema);
+      let field = getPropertyOf(json, "imageUrl");
+      globalThis.expect(Stdlib_Option.flatMap(field, s => getProperty(s, "x-reventless-semantic-source"))).toEqual("type");
+      globalThis.expect(Stdlib_Option.flatMap(field, s => getProperty(s, "x-reventless-semantic-target"))).toEqual(Object.fromEntries([
+        [
+          "store",
+          "productImages"
+        ],
+        [
+          "plugin",
+          "catalog"
+        ]
+      ]));
+    });
+    globalThis.test("the underlying string shape is unchanged", () => {
+      let schema = S.schema(s => ({
+        imageUrl: s.m(StorageRef$Reventless.forStore(undefined, "productImages"))
+      }));
+      let json = SuryToJsonSchema$ReventlessCore.deriveObjectSchema(schema);
+      globalThis.expect(Stdlib_Option.flatMap(getPropertyOf(json, "imageUrl"), s => getProperty(s, "type"))).toEqual("string");
+    });
+    globalThis.test("a type-carried semantic beats an annotation naming the same field", () => {
+      let withSpec = (schema, spec) => S.Metadata.set(schema, StateAnnotations$Reventless.stateAnnotationsId, spec);
+      let schema = withSpec(S.schema(s => ({
+        imageUrl: s.m(StorageRef$Reventless.forStore(undefined, "productImages"))
+      })), {
+        ids: emptySpec_ids,
+        compositeIds: emptySpec_compositeIds,
+        subIds: emptySpec_subIds,
+        compositeSubIds: emptySpec_compositeSubIds,
+        indexes: emptySpec_indexes,
+        hidden: emptySpec_hidden,
+        summary: emptySpec_summary,
+        drillTargets: emptySpec_drillTargets,
+        drillTargetKeys: emptySpec_drillTargetKeys,
+        collapsed: emptySpec_collapsed,
+        scan: emptySpec_scan,
+        scanSort: emptySpec_scanSort,
+        semantic: [[
+            "imageUrl",
+            "image"
+          ]],
+        metric: emptySpec_metric,
+        status: undefined,
+        groupBy: undefined,
+        visibility: undefined
+      });
+      let json = SuryToJsonSchema$ReventlessCore.deriveObjectSchema(schema);
+      globalThis.expect(semanticOf(json, "imageUrl")).toEqual("storageRef");
+    });
+  });
 });
 
 export {

package/tests/plugin/Plugin_EventQuerySchemaTest.res

@@ -0,0 +1,98 @@
+open JestGlobals
+
+// The event-history query is the read counterpart of the Source A raw-event
+// subscription. These tests pin the two properties that make it safe to expose:
+// it is deduped per event log exactly as the subscription is, and it leaks none
+// of the transport / tenant-context fields of `Message.meta`.
+
+module SomeEvent = {
+  @schema
+  type event = Happened({thingId: string})
+}
+
+let entry = (~displayName): ReventlessInfra.Api.eventLogSchemaEntry => {
+  busKey: displayName ++ "AggrEventLog",
+  displayName,
+  eventSchema: SomeEvent.eventSchema->S.castToUnknown,
+}
+
+let allTypes = (r: Plugin_EventQuerySchema.result) => r.extraTypes->Array.join("\n")
+
+describe("Plugin_EventQuerySchema.generate", () => {
+  testSync("emits one history query per event log, plugin-prefixed", () => {
+    let r = Plugin_EventQuerySchema.generate(
+      ~plugin="Ordering",
+      ~eventLogEntries=[entry(~displayName="Order"), entry(~displayName="Shipment")],
+    )
+    expect(r.queryFields->Array.length)->toBe(2)
+    let joined = r.queryFields->Array.join("\n")
+    expect(joined->String.includes("Ordering_OrderEventHistory("))->toBe(true)
+    expect(joined->String.includes("Ordering_ShipmentEventHistory("))->toBe(true)
+    // Relay connection args + return type, identical in shape to every other
+    // list query — existing client pagination applies unchanged.
+    expect(joined->String.includes("first: Int, after: String, last: Int, before: String"))->toBe(
+      true,
+    )
+    expect(joined->String.includes(": Ordering_OrderEventRecordConnection!"))->toBe(true)
+  })
+
+  testSync("dedupes by display name — one logical stream, one field", () => {
+    let r = Plugin_EventQuerySchema.generate(
+      ~plugin="Ordering",
+      ~eventLogEntries=[entry(~displayName="Order"), entry(~displayName="Order")],
+    )
+    expect(r.queryFields->Array.length)->toBe(1)
+  })
+
+  testSync("record carries the audit-relevant meta subset and nothing else", () => {
+    let sdl = allTypes(
+      Plugin_EventQuerySchema.generate(
+        ~plugin="Ordering",
+        ~eventLogEntries=[entry(~displayName="Order")],
+      ),
+    )
+    expect(sdl->String.includes("type EventMeta {"))->toBe(true)
+    ["user", "time", "service", "msgId", "correlationId", "causationId"]->Array.forEach(f =>
+      expect(sdl->String.includes(f))->toBe(true)
+    )
+    // Transport / tracing detail and the cross-cutting context bag must not
+    // leave the server — see the module comment.
+    ["ip:", "traceparent", "schemaVersion", "headers"]->Array.forEach(f =>
+      expect(sdl->String.includes(f))->toBe(false)
+    )
+  })
+
+  testSync("record exposes position, payload, tags and both timestamps", () => {
+    let sdl = allTypes(
+      Plugin_EventQuerySchema.generate(
+        ~plugin="Ordering",
+        ~eventLogEntries=[entry(~displayName="Order")],
+      ),
+    )
+    expect(sdl->String.includes("type Ordering_OrderEventRecord {"))->toBe(true)
+    ["position: String!", "eventType: String!", "payload: AWSJSON!", "tags: [EventTag!]!", "meta: EventMeta!", "recordedAt: String!"]->Array.forEach(
+      f => expect(sdl->String.includes(f))->toBe(true),
+    )
+  })
+
+  testSync("filter offers the entity shortcut and the precise tag pair", () => {
+    let sdl = allTypes(
+      Plugin_EventQuerySchema.generate(
+        ~plugin="Ordering",
+        ~eventLogEntries=[entry(~displayName="Order")],
+      ),
+    )
+    expect(sdl->String.includes("input Ordering_OrderEventHistoryFilter {"))->toBe(true)
+    ["entityId: ID", "tagKey: String", "tagValue: String", "eventTypes: [String!]", "user: String", "timeFrom: String", "timeTo: String"]->Array.forEach(
+      f => expect(sdl->String.includes(f))->toBe(true),
+    )
+  })
+
+  testSync("a plugin with no event logs emits nothing at all", () => {
+    let r = Plugin_EventQuerySchema.generate(~plugin="Ordering", ~eventLogEntries=[])
+    expect(r.queryFields->Array.length)->toBe(0)
+    // Not even the shared types — an empty fragment stays byte-identical to
+    // what it was before this generator existed.
+    expect(r.extraTypes->Array.length)->toBe(0)
+  })
+})

package/tests/plugin/Plugin_EventQuerySchemaTest.res.mjs

@@ -0,0 +1,113 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as S from "sury/src/S.res.mjs";
+import * as Plugin_EventQuerySchema$ReventlessCore from "../../src/plugin/component/Plugin_EventQuerySchema.res.mjs";
+
+let eventSchema = S.schema(s => ({
+  TAG: "Happened",
+  thingId: s.m(S.string)
+}));
+
+let SomeEvent = {
+  eventSchema: eventSchema
+};
+
+function entry(displayName) {
+  return {
+    busKey: displayName + "AggrEventLog",
+    displayName: displayName,
+    eventSchema: eventSchema
+  };
+}
+
+function allTypes(r) {
+  return r.extraTypes.join("\n");
+}
+
+globalThis.describe("Plugin_EventQuerySchema.generate", () => {
+  globalThis.test("emits one history query per event log, plugin-prefixed", () => {
+    let r = Plugin_EventQuerySchema$ReventlessCore.generate("Ordering", [
+      entry("Order"),
+      entry("Shipment")
+    ]);
+    globalThis.expect(r.queryFields.length).toBe(2);
+    let joined = r.queryFields.join("\n");
+    globalThis.expect(joined.includes("Ordering_OrderEventHistory(")).toBe(true);
+    globalThis.expect(joined.includes("Ordering_ShipmentEventHistory(")).toBe(true);
+    globalThis.expect(joined.includes("first: Int, after: String, last: Int, before: String")).toBe(true);
+    globalThis.expect(joined.includes(": Ordering_OrderEventRecordConnection!")).toBe(true);
+  });
+  globalThis.test("dedupes by display name — one logical stream, one field", () => {
+    let r = Plugin_EventQuerySchema$ReventlessCore.generate("Ordering", [
+      entry("Order"),
+      entry("Order")
+    ]);
+    globalThis.expect(r.queryFields.length).toBe(1);
+  });
+  globalThis.test("record carries the audit-relevant meta subset and nothing else", () => {
+    let r = Plugin_EventQuerySchema$ReventlessCore.generate("Ordering", [entry("Order")]);
+    let sdl = r.extraTypes.join("\n");
+    globalThis.expect(sdl.includes("type EventMeta {")).toBe(true);
+    [
+      "user",
+      "time",
+      "service",
+      "msgId",
+      "correlationId",
+      "causationId"
+    ].forEach(f => {
+      globalThis.expect(sdl.includes(f)).toBe(true);
+    });
+    [
+      "ip:",
+      "traceparent",
+      "schemaVersion",
+      "headers"
+    ].forEach(f => {
+      globalThis.expect(sdl.includes(f)).toBe(false);
+    });
+  });
+  globalThis.test("record exposes position, payload, tags and both timestamps", () => {
+    let r = Plugin_EventQuerySchema$ReventlessCore.generate("Ordering", [entry("Order")]);
+    let sdl = r.extraTypes.join("\n");
+    globalThis.expect(sdl.includes("type Ordering_OrderEventRecord {")).toBe(true);
+    [
+      "position: String!",
+      "eventType: String!",
+      "payload: AWSJSON!",
+      "tags: [EventTag!]!",
+      "meta: EventMeta!",
+      "recordedAt: String!"
+    ].forEach(f => {
+      globalThis.expect(sdl.includes(f)).toBe(true);
+    });
+  });
+  globalThis.test("filter offers the entity shortcut and the precise tag pair", () => {
+    let r = Plugin_EventQuerySchema$ReventlessCore.generate("Ordering", [entry("Order")]);
+    let sdl = r.extraTypes.join("\n");
+    globalThis.expect(sdl.includes("input Ordering_OrderEventHistoryFilter {")).toBe(true);
+    [
+      "entityId: ID",
+      "tagKey: String",
+      "tagValue: String",
+      "eventTypes: [String!]",
+      "user: String",
+      "timeFrom: String",
+      "timeTo: String"
+    ].forEach(f => {
+      globalThis.expect(sdl.includes(f)).toBe(true);
+    });
+  });
+  globalThis.test("a plugin with no event logs emits nothing at all", () => {
+    let r = Plugin_EventQuerySchema$ReventlessCore.generate("Ordering", []);
+    globalThis.expect(r.queryFields.length).toBe(0);
+    globalThis.expect(r.extraTypes.length).toBe(0);
+  });
+});
+
+export {
+  SomeEvent,
+  entry,
+  allTypes,
+}
+/* eventSchema Not a pure module */