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

package/CHANGELOG.md

@@ -3,6 +3,13 @@
 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.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.186",
   "description": "Core package for Reventless framework",
   "license": "Apache-2.0",
   "jest": {
@@ -29,16 +29,16 @@
     "sury": "11.0.0-alpha.4",
     "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-jest": "1.0.0-alpha.9",
+    "@reventlessdev/rescript-hash-object": "1.2.0-alpha.13",
     "@reventlessdev/rescript-node-streams": "1.1.0-alpha.13",
     "@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-interop": "3.0.0-alpha.29",
     "@reventlessdev/reventless-spec": "3.0.0-alpha.81",
-    "@reventlessdev/reventless-interop": "3.0.0-alpha.29"
+    "@reventlessdev/reventless-infra": "3.0.0-alpha.106"
   },
   "devDependencies": {
     "rescript": "12.3.0",

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/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 */