@reventlessdev/reventless-aws 3.0.0-alpha.277 → 3.0.0-alpha.279

package/src/adapter/StateTopic/StateTopic_AppSync.res

@@ -42,6 +42,47 @@
 //
 // Usage in Platform.res (once, after admin + plugins have wired):
 //   StateTopic_AppSync.finish(~eventsApi, ~opts)
+//
+// ── Tables that are not read models ──────────────────────────────────────────
+//
+// Nothing below the registration is read-model-specific: the relay routes per
+// record through STATE_TOPIC_MAP and derives the entity channel from the record's
+// own `Keys`. `makeForTable` is the front door for a component that provisions
+// its own DynamoDB table and wants the same descriptors — state that is a PRIMARY
+// record rather than a projection (a ledger accumulated by `ADD` increments,
+// say) is not a read model and must not be declared one, but its rows are exactly
+// the shape the relay expects.
+//
+//   StateTopic_AppSync.makeForTable(
+//     ~tableName=myTable.name,
+//     ~streamArn=myTable.streamArn,
+//     ~partitionKeyName=myTable.hashKey,
+//     ~topicName="Platform-UsageLedger",
+//     ~eventsApi,
+//     ~opts,
+//   )
+//
+// Three things a caller has to get right, none of which the type checker can:
+//
+//   1. TOPIC NAMING IS THE CALLER'S JOB, AND A MISMATCH IS SILENT. A read model
+//      derives its topic from the generated plural list field, so publisher and
+//      subscriber agree by construction. A self-provisioned table has no such
+//      field — the topic passed here is simply believed. Publishing to a channel
+//      nobody listens on succeeds, so a typo shows up as "live updates never
+//      arrive", not as an error. The topic belongs to whoever READS the data:
+//      change the reader and the registration together, in one commit.
+//
+//   2. THE TABLE MUST BE KEYED ON `id`. Checked at deploy time — see
+//      `StateTopic_AppSync_Helpers.checkPartitionKeyName` for why a build error
+//      beats the alternative. A sort key is fine (entity key becomes
+//      `{id}-{sortValue}`, which the reader must also know).
+//
+//   3. REGISTRATION IS OPT-IN, PER TABLE, AND NOT FREE UNDER LOAD. Never register
+//      a table just because it happens to have a stream. A stream is silent while
+//      the table is idle — which is why this beats polling for the common quiet
+//      case — but a write burst costs one relay invocation per record batch, and
+//      avoiding exactly that per-write work is often why such a table exists in
+//      the first place. Measure before enabling it on a write-hot table.
 
 open PulumiAws
 
@@ -84,12 +125,40 @@ let registry: dict<array<streamEntry>> = Dict.make()
 
 // ── Registration ──────────────────────────────────────────────────────────────
 
+/** Register any stream-enabled DynamoDB table with the relay. Read-model and
+    self-provisioned tables land in the SAME registry, so they share one `finish`,
+    one Lambda, one IAM statement and one STATE_TOPIC_MAP — see the module header
+    for the three things a self-provisioned caller has to get right. */
+let makeForTable = (
+  ~tableName: Pulumi.Output.t<string>,
+  ~streamArn: Pulumi.Output.t<string>,
+  ~partitionKeyName: Pulumi.Output.t<string>,
+  ~topicName: string,
+  ~eventsApi: AppSync_EventsApi.t,
+  ~opts as _: Pulumi.CustomResourceOptions.t,
+) => {
+  // The check rides ON the tableName that gets registered rather than sitting in
+  // an apply of its own, so it cannot rot into dead code: STATE_TOPIC_MAP is built
+  // from this Output, so the apply always runs and a violation fails the deploy.
+  let checkedTableName =
+    (tableName, partitionKeyName)
+    ->Pulumi.Output.all2
+    ->Pulumi.Output.apply(((tableName, partitionKeyName)) => {
+      StateTopic_AppSync_Helpers.checkPartitionKeyName(~tableName, ~partitionKeyName)
+      tableName
+    })
+
+  let key = eventsApi.name
+  let entries = registry->Dict.get(key)->Option.getOr([])
+  registry->Dict.set(key, entries->Array.concat([{tableName: checkedTableName, streamArn, topicName}]))
+}
+
 let make = (
   ~readModelName: string,
   ~topicName: string,
   ~allQueryDbs: ReventlessCore.QueryDb.allOutputs,
   ~eventsApi: AppSync_EventsApi.t,
-  ~opts as _: Pulumi.CustomResourceOptions.t,
+  ~opts: Pulumi.CustomResourceOptions.t,
 ) => {
   // Look up the QueryDb resources by ReadModel Spec.name, then find the
   // DynamoDB stream resource within them. Requires QueryDbStorage_DynamoDbStream.
@@ -98,12 +167,18 @@ let make = (
     ->ReventlessCore.Util.ReadModel.queryDbStorageResources(readModelName)
     ->Util_DynamoDbStream.findResource
 
-  let streamArn = Util_DynamoDbStream.streamArnFromDynamoDbTableResource(streamResource)
-  let tableName = streamResource.name
-
-  let key = eventsApi.name
-  let entries = registry->Dict.get(key)->Option.getOr([])
-  registry->Dict.set(key, entries->Array.concat([{tableName, streamArn, topicName}]))
+  makeForTable(
+    ~tableName=streamResource.name,
+    ~streamArn=Util_DynamoDbStream.streamArnFromDynamoDbTableResource(streamResource),
+    // QueryDbStorage_DynamoDb* keys every table it provisions on `id`, so here the
+    // check restates an invariant the framework already holds. It exists for the
+    // tables the framework did NOT create, which reach the registry via
+    // `makeForTable` and can be keyed anything.
+    ~partitionKeyName=StateTopic_AppSync_Helpers.entityKeyPartitionAttribute->Pulumi.Output.make,
+    ~topicName,
+    ~eventsApi,
+    ~opts,
+  )
 }
 
 // ── Finalize: build the shared Lambda + IAM + ESMs ────────────────────────────

package/src/adapter/StateTopic/StateTopic_AppSync.res.mjs

@@ -14,22 +14,33 @@ import * as Util_ReadModel$ReventlessCore from "@reventlessdev/reventless-core/s
 import * as AppSync_EventsApi$ReventlessAws from "../Api/AppSync_EventsApi.res.mjs";
 import * as Util_LambdaLogging$ReventlessAws from "../../util/Util_LambdaLogging.res.mjs";
 import * as Util_DynamoDbStream$ReventlessAws from "../../util/Util_DynamoDbStream.res.mjs";
+import * as StateTopic_AppSync_Helpers$ReventlessAws from "./StateTopic_AppSync_Helpers.res.mjs";
 
 let registry = {};
 
-function make(readModelName, topicName, allQueryDbs, eventsApi, param) {
-  let streamResource = Util_DynamoDbStream$ReventlessAws.findResource(Util_ReadModel$ReventlessCore.queryDbStorageResources(allQueryDbs, readModelName));
-  let streamArn = Util_DynamoDbStream$ReventlessAws.streamArnFromDynamoDbTableResource(streamResource);
-  let tableName = streamResource.name;
+function makeForTable(tableName, streamArn, partitionKeyName, topicName, eventsApi, param) {
+  let checkedTableName = Pulumi.all([
+    tableName,
+    partitionKeyName
+  ]).apply(param => {
+    let tableName = param[0];
+    StateTopic_AppSync_Helpers$ReventlessAws.checkPartitionKeyName(tableName, param[1]);
+    return tableName;
+  });
   let key = eventsApi.name;
   let entries = Stdlib_Option.getOr(registry[key], []);
   registry[key] = entries.concat([{
-      tableName: tableName,
+      tableName: checkedTableName,
       streamArn: streamArn,
       topicName: topicName
     }]);
 }
 
+function make(readModelName, topicName, allQueryDbs, eventsApi, opts) {
+  let streamResource = Util_DynamoDbStream$ReventlessAws.findResource(Util_ReadModel$ReventlessCore.queryDbStorageResources(allQueryDbs, readModelName));
+  makeForTable(streamResource.name, Util_DynamoDbStream$ReventlessAws.streamArnFromDynamoDbTableResource(streamResource), Pulumi.output(StateTopic_AppSync_Helpers$ReventlessAws.entityKeyPartitionAttribute), topicName, eventsApi, opts);
+}
+
 function finish(eventsApi, opts) {
   let key = eventsApi.name;
   let entries = registry[key];
@@ -144,6 +155,7 @@ function finish(eventsApi, opts) {
 
 export {
   registry,
+  makeForTable,
   make,
   finish,
 }

package/src/adapter/StateTopic/StateTopic_AppSync_Helpers.res

@@ -0,0 +1,36 @@
+// Pulumi-free helpers for the state-topic relay's deploy-time registration.
+//
+// Split out of `StateTopic_AppSync.res` so the key-schema check can be driven
+// headlessly — the registration module itself pulls in @pulumi/aws.
+
+/** The attribute name `StateTopic_AppSync_Ops.entityKeyFromRecord` looks for when
+    it builds a change descriptor's entity key from the stream record's `Keys`.
+    Every framework-provisioned QueryDb table uses it; a self-provisioned table
+    registered through `makeForTable` must too. */
+let entityKeyPartitionAttribute = "id"
+
+/** Reject a table whose partition attribute is not `id`.
+
+    The relay does not fail on such a table — it publishes descriptors carrying a
+    joined-and-sorted fallback key, which surfaces much later as clients
+    refetching the wrong entity. Turning that into a build error is the whole
+    point: the message names the table and its actual key so the fix is obvious
+    at the registration site.
+
+    At most one sort key needs no check — DynamoDB tables cannot have more than
+    one, so the relay's `{id}-{sortValue}` composition is total by construction.
+
+    Naming the table costs one thing worth knowing: the caller resolves the table
+    name to build the message, so on the very first deploy of a NEW table — where
+    that name is still unknown at preview — the failure lands during the update
+    rather than the preview. It fails the deploy either way. */
+let checkPartitionKeyName = (~tableName: string, ~partitionKeyName: string): unit =>
+  if partitionKeyName != entityKeyPartitionAttribute {
+    JsError.throwWithMessage(
+      `StateTopic: table "${tableName}" is keyed on "${partitionKeyName}", but the ` ++
+      `state-topic relay derives a change descriptor's entity key from an attribute ` ++
+      `named "${entityKeyPartitionAttribute}". Registering it would publish ` ++
+      `descriptors whose id does not match the row. Rename the partition key to ` ++
+      `"${entityKeyPartitionAttribute}", or do not register this table.`,
+    )
+  }

package/src/adapter/StateTopic/StateTopic_AppSync_Helpers.res.mjs

@@ -0,0 +1,17 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Stdlib_JsError from "@rescript/runtime/lib/es6/Stdlib_JsError.js";
+
+let entityKeyPartitionAttribute = "id";
+
+function checkPartitionKeyName(tableName, partitionKeyName) {
+  if (partitionKeyName !== entityKeyPartitionAttribute) {
+    return Stdlib_JsError.throwWithMessage(`StateTopic: table "` + tableName + `" is keyed on "` + partitionKeyName + `", but the state-topic relay derives a change descriptor's entity key from an attribute ` + (`named "` + entityKeyPartitionAttribute + `". Registering it would publish `) + `descriptors whose id does not match the row. Rename the partition key to ` + (`"` + entityKeyPartitionAttribute + `", or do not register this table.`));
+  }
+}
+
+export {
+  entityKeyPartitionAttribute,
+  checkPartitionKeyName,
+}
+/* No side effect */

package/tests/EventCollectorConnectLambdaPreviewTest.res

@@ -0,0 +1,143 @@
+open JestGlobals
+
+// Guards the preview-unknown decoupling in `EventCollectorChannel_Helpers.connectLambda`.
+//
+// The collector's role policy and its event-source mappings used to be created
+// inside ONE `Pulumi.Output.all3` apply over three unrelated input sets. Pulumi
+// skips an apply whose inputs are unknown, and a resource the program never
+// registers reads as a DELETE — so a single unknown input removed all of them
+// from the preview, including mappings that never read it. That is how switching
+// a plugin's slices to the stream builder deleted the plugin's event-log mapping:
+// the new view tables' computed `streamArn` is unknown in the preview that
+// enables it, and the view tables shared the apply with everything else.
+//
+// These tests drive `connectLambda` under Pulumi's mock runtime in preview mode
+// with a genuinely unknown view-table resource, and assert the two resources that
+// do not depend on it are still registered.
+
+// ── Pulumi mock runtime ──────────────────────────────────────────────────────
+
+type mockArgs = {@as("type") type_: string, name: string}
+type mockResult = {id: string, state: JSON.t}
+
+@module("@pulumi/pulumi") @scope("runtime")
+external setMocks: (
+  {"newResource": mockArgs => mockResult, "call": mockArgs => JSON.t},
+  string,
+  string,
+  bool,
+) => unit = "setMocks"
+
+// The engine's unknown-during-preview Output: resolved, but flagged not-known, so
+// `.apply` never fires while the value is still accepted as a resource INPUT.
+// Constructed the way the engine does rather than faked with a pending promise —
+// a promise that never settles would also stall resource registration, which is
+// the very difference under test.
+@module("@pulumi/pulumi") @new
+external makeOutput: (
+  Set.t<unit>,
+  promise<'a>,
+  promise<bool>,
+  promise<bool>,
+  promise<Set.t<unit>>,
+) => Pulumi.Output.t<'a> = "Output"
+
+let unknown = (): Pulumi.Output.t<'a> =>
+  makeOutput(
+    Set.make(),
+    Promise.resolve(%raw(`undefined`)),
+    Promise.resolve(false),
+    Promise.resolve(false),
+    Promise.resolve(Set.make()),
+  )
+
+let registered: array<(string, string)> = []
+
+beforeAll(() =>
+  setMocks(
+    {
+      "newResource": args => {
+        registered->Array.push((args.type_, args.name))
+        {id: args.name ++ "_id", state: JSON.Encode.object(Dict.make())}
+      },
+      "call": _ => JSON.Encode.object(Dict.make()),
+    },
+    "reventless-test",
+    "test",
+    true,
+  )
+)
+
+// Pulumi registers resources asynchronously; give the runtime a few ticks.
+let settle = async () => await Promise.make((resolve, _) => {
+  let _ = setTimeout(() => resolve(), 300)
+})
+
+let wasRegistered = (type_, name) =>
+  registered->Array.some(((t, n)) => t == type_ && n == name)
+
+// ── Fixtures ─────────────────────────────────────────────────────────────────
+
+// A view table whose fields never become known — what a QueryDb stream resource
+// looks like in the preview that first enables its stream.
+let unknownViewTable = ReventlessInfra.Adapter.make(
+  ~name=unknown(),
+  ~id=unknown(),
+  ~urn=unknown(),
+  ~service=unknown(),
+  ~resourceInfo=unknown(),
+)
+
+// A known event-log stream — the ESM source. Unaffected by the slice switch.
+let knownEventLogStream = ReventlessInfra.Adapter.make(
+  ~name="CatalogDcbEventLog-abc123"->Pulumi.Output.make,
+  ~id="stream-id"->Pulumi.Output.make,
+  ~urn="arn:aws:dynamodb:eu-west-1:123456789012:table/CatalogDcbEventLog-abc123/stream/2026-01-01T00:00:00.000"->Pulumi.Output.make,
+  ~service=AWS.DynamoDbStream.service->Pulumi.Output.make,
+  ~resourceInfo=ReventlessInfra.Adapter.StreamSource({
+    sourceUrn: "arn:aws:dynamodb:eu-west-1:123456789012:table/CatalogDcbEventLog-abc123/stream/2026-01-01T00:00:00.000",
+  })->Pulumi.Output.make,
+)
+
+let lambdaRole: PulumiAws.IAM.Role.t = {
+  arn: "arn:aws:iam::123456789012:role/AllStateViewSlicesRole"->Pulumi.Output.make,
+  name: "AllStateViewSlicesRole"->Pulumi.Output.make,
+  id: "AllStateViewSlicesRole"->Pulumi.Output.make,
+}
+
+let lambda: Pulumi.Output.t<PulumiAws.Lambda.Function.t> = Pulumi.Output.make({
+  PulumiAws.Lambda.Function.arn: "arn:aws:lambda:eu-west-1:123456789012:function:AllStateViewSlices"->Pulumi.Output.make,
+  id: "AllStateViewSlices"->Pulumi.Output.make,
+  name: "AllStateViewSlices"->Pulumi.Output.make,
+  invokeArn: "arn:aws:apigateway:invoke"->Pulumi.Output.make,
+})
+
+// ── Tests ────────────────────────────────────────────────────────────────────
+
+describe("EventCollectorChannel_Helpers.connectLambda under an unknown view table", () => {
+  let name = "AllStateViewSlices"
+
+  beforeAllAsync(async () => {
+    let _ = EventCollectorChannel_Helpers.connectLambda(
+      lambda,
+      name,
+      lambdaRole,
+      [],
+      Dict.fromArray([("DcbEventLog", {ReventlessInfra.EventTopic.resources: [knownEventLogStream]})]),
+      [unknownViewTable],
+      {},
+    )
+    await settle()
+  })
+
+  test("still registers the collector's role policy", async () => {
+    // The policy DOCUMENT genuinely depends on the unknown table, but the policy
+    // RESOURCE must not: an unknown input previews as "value unknown", whereas an
+    // unregistered resource previews as a delete.
+    expect(wasRegistered("aws:iam/rolePolicy:RolePolicy", name))->toBe(true)
+  })
+
+  test("still registers the event-log mapping, which never reads a view table", async () => {
+    expect(wasRegistered("aws:lambda/eventSourceMapping:EventSourceMapping", "CatalogDcbEventLog2" ++ name))->toBe(true)
+  })
+})

package/tests/EventCollectorConnectLambdaPreviewTest.res.mjs

@@ -0,0 +1,101 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Pulumi from "@pulumi/pulumi";
+import * as AWS$ReventlessAws from "../src/adapter/AWS.res.mjs";
+import * as Adapter$ReventlessInfra from "@reventlessdev/reventless-infra/src/adapter/Adapter.res.mjs";
+import * as EventCollectorChannel_Helpers$ReventlessAws from "../src/adapter/EventCollector/EventCollectorChannel_Helpers.res.mjs";
+
+function unknown() {
+  return new Pulumi.Output(new Set(), Promise.resolve(undefined), Promise.resolve(false), Promise.resolve(false), Promise.resolve(new Set()));
+}
+
+let registered = [];
+
+globalThis.beforeAll(() => {
+  Pulumi.runtime.setMocks({
+    newResource: args => {
+      registered.push([
+        args.type,
+        args.name
+      ]);
+      return {
+        id: args.name + "_id",
+        state: {}
+      };
+    },
+    call: param => ({})
+  }, "reventless-test", "test", true);
+});
+
+async function settle() {
+  return await new Promise((resolve, param) => {
+    setTimeout(() => resolve(), 300);
+  });
+}
+
+function wasRegistered(type_, name) {
+  return registered.some(param => {
+    if (param[0] === type_) {
+      return param[1] === name;
+    } else {
+      return false;
+    }
+  });
+}
+
+let unknownViewTable = Adapter$ReventlessInfra.make(unknown(), unknown(), unknown(), unknown(), unknown(), undefined, undefined, undefined, undefined, undefined);
+
+let knownEventLogStream = Adapter$ReventlessInfra.make(Pulumi.output("CatalogDcbEventLog-abc123"), Pulumi.output("stream-id"), Pulumi.output("arn:aws:dynamodb:eu-west-1:123456789012:table/CatalogDcbEventLog-abc123/stream/2026-01-01T00:00:00.000"), Pulumi.output(AWS$ReventlessAws.DynamoDbStream.service), Pulumi.output({
+  TAG: "StreamSource",
+  sourceUrn: "arn:aws:dynamodb:eu-west-1:123456789012:table/CatalogDcbEventLog-abc123/stream/2026-01-01T00:00:00.000"
+}), undefined, undefined, undefined, undefined, undefined);
+
+let lambdaRole_arn = Pulumi.output("arn:aws:iam::123456789012:role/AllStateViewSlicesRole");
+
+let lambdaRole_name = Pulumi.output("AllStateViewSlicesRole");
+
+let lambdaRole_id = Pulumi.output("AllStateViewSlicesRole");
+
+let lambdaRole = {
+  arn: lambdaRole_arn,
+  name: lambdaRole_name,
+  id: lambdaRole_id
+};
+
+let lambda = Pulumi.output({
+  arn: Pulumi.output("arn:aws:lambda:eu-west-1:123456789012:function:AllStateViewSlices"),
+  id: Pulumi.output("AllStateViewSlices"),
+  name: Pulumi.output("AllStateViewSlices"),
+  invokeArn: Pulumi.output("arn:aws:apigateway:invoke")
+});
+
+globalThis.describe("EventCollectorChannel_Helpers.connectLambda under an unknown view table", () => {
+  let name = "AllStateViewSlices";
+  globalThis.beforeAll(async () => {
+    EventCollectorChannel_Helpers$ReventlessAws.connectLambda(lambda, name, lambdaRole, [], Object.fromEntries([[
+        "DcbEventLog",
+        {
+          resources: [knownEventLogStream]
+        }
+      ]]), [unknownViewTable], {});
+    return await settle();
+  });
+  globalThis.test("still registers the collector's role policy", async () => {
+    globalThis.expect(wasRegistered("aws:iam/rolePolicy:RolePolicy", name)).toBe(true);
+  });
+  globalThis.test("still registers the event-log mapping, which never reads a view table", async () => {
+    globalThis.expect(wasRegistered("aws:lambda/eventSourceMapping:EventSourceMapping", "CatalogDcbEventLog2" + name)).toBe(true);
+  });
+});
+
+export {
+  unknown,
+  registered,
+  settle,
+  wasRegistered,
+  unknownViewTable,
+  knownEventLogStream,
+  lambdaRole,
+  lambda,
+}
+/*  Not a pure module */

package/tests/QueryInterceptor_LambdaTest.res

@@ -0,0 +1,87 @@
+// The read-path interceptor runtime: its contract, and the cold-start seam it
+// depends on for that contract to mean anything.
+//
+// The hook this handler consults is a module-level `ref`, and in a deployed
+// runtime only a `RuntimeExtension`'s `onColdStart` ever fills it. This runtime
+// is not built by a compiled entry shell, so it awaits `runtimeExtensionsReady`
+// itself — and the failure mode when it does not is silent by construction: the
+// hook reads `None`, every read is allowed, and interception costs a full Lambda
+// invocation per read while observing nothing. Nothing errors, so only a test
+// says so.
+
+open JestGlobals
+open ReventlessCore
+
+// Both names must resolve to the SAME promise. HandlerFactoryHelpers re-exports
+// this binding rather than defining its own precisely so the seam fires once per
+// process; a second definition would fire every registered extension's
+// `onColdStart` twice in any runtime that reached both modules.
+@module("../src/adapter/Runtime/RuntimeExtensionsReady.mjs")
+external readyFromOwnModule: promise<unit> = "runtimeExtensionsReady"
+
+@module("../src/adapter/Runtime/HandlerFactoryHelpers.mjs")
+external readyFromHelpers: promise<unit> = "runtimeExtensionsReady"
+
+let identity: Reventless.Identity.t = {
+  userId: "anonymous",
+  username: "anonymous",
+  groups: [],
+  provider: InMemory,
+}
+
+let read = (~readModelName="Product"): QueryInterceptor_Lambda.payload => {
+  readModelName,
+  arguments: JSON.Null,
+  identity,
+}
+
+// The handler ignores it; Lambda supplies the real one.
+let context: PulumiAws.Lambda.context = %raw(`{}`)
+
+describe("cold-start seam", () => {
+  test("one seam, one promise — the helpers re-export is not a second copy", async () => {
+    expect(readyFromHelpers === readyFromOwnModule)->toBe(true)
+  })
+})
+
+describe("interceptor handler", () => {
+  beforeEach(() => QueryDb_Callback.clearQueryInterceptor())
+
+  testPromise("no registered hook passes the read through", async () => {
+    let allowed = await QueryInterceptor_Lambda.handler(read(), context)
+    expect(allowed)->toBe(true)
+  })
+
+  testPromise("an allowing hook is consulted and the read proceeds", async () => {
+    let seen = ref([])
+    QueryDb_Callback.registerQueryInterceptor(async (
+      ~identity as _,
+      ~readModelName,
+      ~args as _,
+    ) => {
+      seen := seen.contents->Array.concat([readModelName])
+      QueryDb_Callback.Allow
+    })
+    let allowed = await QueryInterceptor_Lambda.handler(read(~readModelName="Order"), context)
+    expect((allowed, seen.contents))->toEqual((true, ["Order"]))
+  })
+
+  testPromise("a denying hook fails the read with the hook's own message", async () => {
+    // The refusal has to surface as a thrown error: the pipeline's response
+    // function turns `ctx.error` into a GraphQL field error, and a returned
+    // `false` would read as a successful read of nothing.
+    QueryDb_Callback.registerQueryInterceptor(async (
+      ~identity as _,
+      ~readModelName as _,
+      ~args as _,
+    ) => QueryDb_Callback.Deny("over the allowance"))
+    let message = try {
+      let _ = await QueryInterceptor_Lambda.handler(read(), context)
+      "did not throw"
+    } catch {
+    | JsExn(e) => e->JsExn.message->Option.getOr("no message")
+    | _ => "not a JS error"
+    }
+    expect(message)->Expect.toBe("over the allowance")
+  })
+})

package/tests/QueryInterceptor_LambdaTest.res.mjs

@@ -0,0 +1,103 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Stdlib_JsExn from "@rescript/runtime/lib/es6/Stdlib_JsExn.js";
+import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
+import * as Primitive_exceptions from "@rescript/runtime/lib/es6/Primitive_exceptions.js";
+import * as QueryDb_Callback$ReventlessCore from "@reventlessdev/reventless-core/src/components/QueryDb/QueryDb_Callback.res.mjs";
+import * as QueryInterceptor_Lambda$ReventlessAws from "../src/adapter/QueryDb/QueryInterceptor_Lambda.res.mjs";
+import * as HandlerFactoryHelpersMjs from "../src/adapter/Runtime/HandlerFactoryHelpers.mjs";
+import * as RuntimeExtensionsReadyMjs from "../src/adapter/Runtime/RuntimeExtensionsReady.mjs";
+
+let readyFromOwnModule = RuntimeExtensionsReadyMjs.runtimeExtensionsReady;
+
+let readyFromHelpers = HandlerFactoryHelpersMjs.runtimeExtensionsReady;
+
+let identity_groups = [];
+
+let identity = {
+  userId: "anonymous",
+  username: "anonymous",
+  groups: identity_groups,
+  provider: "InMemory"
+};
+
+function read(readModelNameOpt) {
+  let readModelName = readModelNameOpt !== undefined ? readModelNameOpt : "Product";
+  return {
+    readModelName: readModelName,
+    arguments: null,
+    identity: identity
+  };
+}
+
+let context = {};
+
+globalThis.describe("cold-start seam", () => {
+  globalThis.test("one seam, one promise — the helpers re-export is not a second copy", async () => {
+    globalThis.expect(readyFromHelpers === readyFromOwnModule).toBe(true);
+  });
+});
+
+globalThis.describe("interceptor handler", () => {
+  globalThis.beforeEach(() => QueryDb_Callback$ReventlessCore.clearQueryInterceptor());
+  globalThis.test("no registered hook passes the read through", async () => {
+    let readModelName = "Product";
+    let allowed = await QueryInterceptor_Lambda$ReventlessAws.handler({
+      readModelName: readModelName,
+      arguments: null,
+      identity: identity
+    }, context);
+    globalThis.expect(allowed).toBe(true);
+  });
+  globalThis.test("an allowing hook is consulted and the read proceeds", async () => {
+    let seen = {
+      contents: []
+    };
+    QueryDb_Callback$ReventlessCore.registerQueryInterceptor(async (param, readModelName, param$1) => {
+      seen.contents = seen.contents.concat([readModelName]);
+      return "Allow";
+    });
+    let readModelName = "Order";
+    let allowed = await QueryInterceptor_Lambda$ReventlessAws.handler({
+      readModelName: readModelName,
+      arguments: null,
+      identity: identity
+    }, context);
+    globalThis.expect([
+      allowed,
+      seen.contents
+    ]).toEqual([
+      true,
+      ["Order"]
+    ]);
+  });
+  globalThis.test("a denying hook fails the read with the hook's own message", async () => {
+    QueryDb_Callback$ReventlessCore.registerQueryInterceptor(async (param, param$1, param$2) => ({
+      TAG: "Deny",
+      _0: "over the allowance"
+    }));
+    let message;
+    try {
+      let readModelName = "Product";
+      await QueryInterceptor_Lambda$ReventlessAws.handler({
+        readModelName: readModelName,
+        arguments: null,
+        identity: identity
+      }, context);
+      message = "did not throw";
+    } catch (raw_e) {
+      let e = Primitive_exceptions.internalToException(raw_e);
+      message = e.RE_EXN_ID === "JsExn" ? Stdlib_Option.getOr(Stdlib_JsExn.message(e._1), "no message") : "not a JS error";
+    }
+    globalThis.expect(message).toBe("over the allowance");
+  });
+});
+
+export {
+  readyFromOwnModule,
+  readyFromHelpers,
+  identity,
+  read,
+  context,
+}
+/* readyFromOwnModule Not a pure module */