@reventlessdev/reventless-aws 3.0.0-alpha.183 → 3.0.0-alpha.185

package/CHANGELOG.md

@@ -3,6 +3,20 @@
 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.185 (2026-07-08)
+
+### Bug Fixes
+
+* **reventless-aws:** thread partitionTag into deployed DCB command Lambda append ([68f0859](https://github.com/ReventlessDev/reventless-core/commit/68f0859d3d5e44f6217a5dc0d8537cfec3d21194))
+
+
+# 3.0.0-alpha.184 (2026-07-08)
+
+### Bug Fixes
+
+* **reventless-aws:** exclude internal rows from Platform_Plugins connection scan ([df14af2](https://github.com/ReventlessDev/reventless-core/commit/df14af2cbd70d49062f2afc03418cdbf18d151d6))
+
+
 # 3.0.0-alpha.183 (2026-07-08)
 
 ### Bug Fixes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reventlessdev/reventless-aws",
-  "version": "3.0.0-alpha.183",
+  "version": "3.0.0-alpha.185",
   "description": "AWS adapters for Reventless",
   "license": "Apache-2.0",
   "dependencies": {
@@ -11,14 +11,14 @@
     "@reventlessdev/rescript-aws-sdk": "2.2.0-alpha.20",
     "@reventlessdev/rescript-effect": "0.1.0-alpha.25",
     "@reventlessdev/rescript-jest": "1.0.0-alpha.6",
-    "@reventlessdev/rescript-pulumi-aws": "2.4.0-alpha.46",
     "@reventlessdev/rescript-pulumi-pulumi": "2.3.0-alpha.14",
     "@reventlessdev/rescript-uuid": "1.1.0-alpha.14",
-    "@reventlessdev/reventless-core": "3.0.0-alpha.145",
-    "@reventlessdev/reventless-infra": "3.0.0-alpha.90",
+    "@reventlessdev/reventless-core": "3.0.0-alpha.146",
+    "@reventlessdev/rescript-pulumi-aws": "2.4.0-alpha.47",
+    "@reventlessdev/reventless-infra": "3.0.0-alpha.91",
     "@reventlessdev/reventless-interop": "3.0.0-alpha.24",
-    "@reventlessdev/reventless-postgres": "3.0.0-alpha.9",
-    "@reventlessdev/reventless-spec": "3.0.0-alpha.68"
+    "@reventlessdev/reventless-postgres": "3.0.0-alpha.10",
+    "@reventlessdev/reventless-spec": "3.0.0-alpha.69"
   },
   "devDependencies": {
     "rescript": "^12.3.0",

package/src/adapter/QueryDb/QueryDbResolvers_AppSync.res

@@ -57,6 +57,17 @@ export function response(ctx) {
 }
 `->Pulumi.Input.make
 
+/** The discriminator attribute whose absence marks an internal bookkeeping row for a
+    read model whose physical DynamoDB table co-hosts rows written outside the projection.
+    Only the Plugins admin RM has this: its table also holds `deploy-schema:*` /
+    `plugin-info:*` / `deploy-schema-hash:*` rows (Platform.res preResolversSchemaHook)
+    that carry no `name`. Returning `Some(attr)` makes the Connection Scan emit an
+    `attribute_exists(#attr)` filter so those rows never reach the non-null GraphQL schema.
+    `name` is the already-capitalized read-model name (spec name, e.g. "Plugins").
+    See docs/plans/platform-plugins-admin-connection-null-rows.md. */
+let internalRowRequiredAttr = (name: string): option<string> =>
+  name == "Plugins" ? Some("name") : None
+
 let make: ReventlessCore.QueryDb_Adapter.resolversMaker<api, role> = (
   ~name: string,
   ~api: api,
@@ -217,6 +228,15 @@ let make: ReventlessCore.QueryDb_Adapter.resolversMaker<api, role> = (
       )->Array.forEach(msg => log.warn(~comp="QueryDbResolvers_AppSync", msg))
     | None => ()
     }
+    // The Plugins admin RM's DynamoDB table co-hosts deploy-time infra rows
+    // (`deploy-schema:<name>`, `plugin-info:<name>`, `deploy-schema-hash:<apiId>`)
+    // written directly by the platform (Platform.res preResolversSchemaHook), not by
+    // the projection. Those rows carry no `name` attribute, so an unfiltered Scan
+    // resolves `name: String!` to null → non-null violation that nulls the entire
+    // Platform_PluginConnection. Exclude them with an `attribute_exists(#name)` filter
+    // (prefix-agnostic: real plugin rows always carry `name`, internal rows never do).
+    // See docs/plans/platform-plugins-admin-connection-null-rows.md.
+    let requireAttribute = internalRowRequiredAttr(name)
     let resolverAll = makeQueryResolver(
       ~resolverName=fieldNameForAll->String.capitalize,
       ~field=fieldNameForAll->Pulumi.Input.make,
@@ -226,6 +246,7 @@ let make: ReventlessCore.QueryDb_Adapter.resolversMaker<api, role> = (
           ~filterFields=filterFieldNames,
           ~rangeFields=rangeFieldNames,
           ~sortFields=sortFieldNames,
+          ~requireAttribute?,
         )
       } else {
         Resolver.Functions.listAllItems

package/src/adapter/QueryDb/QueryDbResolvers_AppSync.res.mjs

@@ -58,6 +58,12 @@ export function response(ctx) {
 `;
 }
 
+function internalRowRequiredAttr(name) {
+  if (name === "Plugins") {
+    return "name";
+  }
+}
+
 function make(name, api, apiRole, dataSourceName, indexes, subIdField, idResolverConfigs, idsResolverConfigs, param, opts) {
   let name$1 = Stdlib_String.capitalize(name);
   let registryEntry = Plugin_Helpers$ReventlessCore.queryFieldNamesRegistry[name$1];
@@ -100,7 +106,8 @@ function make(name, api, apiRole, dataSourceName, indexes, subIdField, idResolve
       ).concat(Stdlib_Array.filterMap(indexes, param => param.subIdField));
       GraphQL_FragmentGenerator$ReventlessCore.validateScanSortAlignment(stateSchemaOpt, name$1, knownSortFields).forEach(msg => log.warn("QueryDbResolvers_AppSync", undefined, msg));
     }
-    let resolverAll = makeQueryResolver(Stdlib_String.capitalize(fieldNameForAll), fieldNameForAll, connectionSpec ? AppSync_Resolver_Functions$PulumiAws.listAllItemsConnection(labelField, filterFieldNames, rangeFieldNames, sortFieldNames) : AppSync_Resolver_Functions$PulumiAws.listAllItems);
+    let requireAttribute = internalRowRequiredAttr(name$1);
+    let resolverAll = makeQueryResolver(Stdlib_String.capitalize(fieldNameForAll), fieldNameForAll, connectionSpec ? AppSync_Resolver_Functions$PulumiAws.listAllItemsConnection(labelField, filterFieldNames, rangeFieldNames, sortFieldNames, requireAttribute) : AppSync_Resolver_Functions$PulumiAws.listAllItems);
     let resolversByIndex = indexes.map(indexConfig => {
       let index = indexConfig.index;
       let stripLeadingBy = s => {
@@ -238,6 +245,7 @@ export {
   log,
   queryInterceptorConfig,
   interceptorCode,
+  internalRowRequiredAttr,
   make,
 }
 /* log Not a pure module */

package/src/adapter/Runtime/DcbCommandTopicEntryPoint.mjs

@@ -12,6 +12,7 @@ import { tag as requestContextTag } from "@reventlessdev/reventless-core/src/Req
 import {
   extractVariantNames,
   deriveEffectiveScope,
+  derivePartitionTag,
 } from "@reventlessdev/reventless-spec/src/components/DcbTag.res.mjs";
 import { $$String as IdString } from "@reventlessdev/reventless-spec/src/types/Id.res.mjs";
 import { Make as dcbEventLogOperationsMake } from "@reventlessdev/reventless-core/src/components/DcbEventLog/DcbEventLog_Operations.res.mjs";
@@ -89,6 +90,61 @@ function getIdStringSchema() {
 // can drive the real `cmdGenHandler` end-to-end against DynamoDB Local.
 export async function buildHandlersForConfig(config, opts = {}) {
   const loadModule = opts.loadModule ?? dynamicImport;
+
+  // Load all spec/behavior pairs first. Both the decision-query scope
+  // (crossPartitionTagKeys / tagKeysByEventType) AND the storage `partitionTag`
+  // are derived from the produced event schemas, and the DynamoDB storage ops
+  // below must be built with them — so slices load before anything else.
+  const loadedSlices = await Promise.all(
+    config.stateChangeSliceModules.map(async ({ spec, behavior }) => {
+      const specModule = await loadModule(spec);
+      const behaviorModule = await loadModule(behavior);
+      const patchedSpec = patchSpecId(specModule);
+      return { patchedSpec, behaviorModule };
+    })
+  );
+
+  // Single source of truth with Dcb_Builder.res: prefer slice-graph inference
+  // (which classifies cross-partition `@ref` reference reads), falling back to
+  // annotations only on ambiguity. Re-deriving from annotations alone here
+  // silently dropped inferred cross-partition reads, so every reference-guarded
+  // command was rejected on the deployed path — see
+  // docs/analysis/dcb-runtime-scope-annotation-drift.md.
+  const { crossPartitionTagKeys, tagKeysByEventType } = deriveEffectiveScope(
+    loadedSlices.map(({ patchedSpec }) => ({
+      name: patchedSpec.name,
+      commandSchema: patchedSpec.commandSchema,
+      consumedEventSchema: patchedSpec.consumedEventSchema,
+      eventSchema: patchedSpec.eventSchema,
+    }))
+  );
+
+  // Derive the storage partition tag the SAME way Dcb_Builder.res does at
+  // deploy time (over the produced event schemas). This MUST reach the DynamoDB
+  // `append` — without it `partitionTag` defaults to `None`, the composite-fence
+  // collapse (gated on `Composite`) never fires, and a `@compositePartitionTag`
+  // slice writes one fence PER MEMBER instead of one synthetic composite fence.
+  // A deploy-time fan-out sharing low-cardinality members (environment, plugin,
+  // …) then turns those member fences hot → TransactionConflict → retries
+  // exhausted. The deploy-time adapter (DcbEventLogStorage_DynamoDb.make) already
+  // threads it; the deployed Lambda dropped it. See
+  // docs/plans/dcb-composite-fence-residual-burst-contention.md.
+  // `derivePartitionTag` throws only on a misconfigured spec, which the deploy
+  // would already have rejected; guard defensively so a runtime edge case
+  // degrades to the (old) untagged behaviour rather than crashing cold start.
+  let partitionTag = undefined;
+  try {
+    partitionTag = derivePartitionTag(
+      loadedSlices.map(({ patchedSpec }) => [
+        patchedSpec.name,
+        patchedSpec.moduleUrl ?? patchedSpec.name,
+        patchedSpec.eventSchema,
+      ])
+    );
+  } catch (err) {
+    log.warn("could not derive partitionTag; falling back to untagged fences: " + (err && err.message), { comp: "DcbCommandTopicRuntime" });
+  }
+
   // `pgConnection`, when present in HANDLER_CONFIG, selects the Postgres DCB
   // runtime (dcbEventLogTableName doubles as the `dcb_event.log_name`); absence
   // keeps the DynamoDB path byte-identical. NB: this swaps only the *storage*
@@ -108,10 +164,18 @@ export async function buildHandlersForConfig(config, opts = {}) {
       })()
     : (() => {
         const resolvedTable = { name: config.dcbEventLogTableName };
+        // Positional args match the ReScript-compiled signatures:
+        //   read(table, crossPartitionTagKeys)
+        //   append(table, partitionTag, crossPartitionTagKeys)
+        //   readStream(table, crossPartitionTagKeys)
+        // Threading partitionTag activates the composite-fence collapse; threading
+        // crossPartitionTagKeys routes single-tag `@crossPartition` reads to the
+        // per-tag GSI and bumps their fences on every carrier — matching the
+        // deploy-time adapter's storage ops exactly.
         return {
-          read: read(resolvedTable),
-          append: append(resolvedTable),
-          readStream: readStream(resolvedTable),
+          read: read(resolvedTable, crossPartitionTagKeys),
+          append: append(resolvedTable, partitionTag, crossPartitionTagKeys),
+          readStream: readStream(resolvedTable, crossPartitionTagKeys),
         };
       })();
 
@@ -126,34 +190,6 @@ export async function buildHandlersForConfig(config, opts = {}) {
     publishJson: async (_name, _meta, _json) => {},
   });
 
-  // Load all spec/behavior pairs first, then derive the per-plugin
-  // tagKeysByEventType / crossPartitionTagKeys across the produced event
-  // schemas — mirroring Dcb_Builder.res's build-time derivation — so the
-  // runtime slice callback receives the same values it would in-process.
-  const loadedSlices = await Promise.all(
-    config.stateChangeSliceModules.map(async ({ spec, behavior }) => {
-      const specModule = await loadModule(spec);
-      const behaviorModule = await loadModule(behavior);
-      const patchedSpec = patchSpecId(specModule);
-      return { patchedSpec, behaviorModule };
-    })
-  );
-
-  // Single source of truth with Dcb_Builder.res: prefer slice-graph inference
-  // (which classifies cross-partition `@ref` reference reads), falling back to
-  // annotations only on ambiguity. Re-deriving from annotations alone here
-  // silently dropped inferred cross-partition reads, so every reference-guarded
-  // command was rejected on the deployed path — see
-  // docs/analysis/dcb-runtime-scope-annotation-drift.md.
-  const { crossPartitionTagKeys, tagKeysByEventType } = deriveEffectiveScope(
-    loadedSlices.map(({ patchedSpec }) => ({
-      name: patchedSpec.name,
-      commandSchema: patchedSpec.commandSchema,
-      consumedEventSchema: patchedSpec.consumedEventSchema,
-      eventSchema: patchedSpec.eventSchema,
-    }))
-  );
-
   loadedSlices.forEach(({ patchedSpec, behaviorModule }) => {
     const sliceCallback = stateChangeSliceCallbackMake(patchedSpec)(behaviorModule);
     const commandSchema = patchedSpec.commandSchema;

package/tests/QueryDbResolvers_AppSyncTest.res

@@ -0,0 +1,40 @@
+open JestGlobals
+
+// Regression guard for docs/plans/platform-plugins-admin-connection-null-rows.md:
+// the Plugins admin RM shares its DynamoDB table with internal bookkeeping rows
+// (`deploy-schema:*`, `plugin-info:*`, `deploy-schema-hash:*`) that carry no `name`.
+// The auto-generated Connection Scan must exclude them, or `name: String!` resolves
+// to null and nulls the entire Platform_PluginConnection ("No data" on the page).
+
+// `Pulumi.Input.make` is `%identity`, so a generated resolver's `Pulumi.Input.t<string>`
+// IS the underlying JS string — recover it with Obj.magic for assertion.
+let codeOf = (input: Pulumi.Input.t<string>): string => Obj.magic(input)
+
+describe("QueryDbResolvers_AppSync.internalRowRequiredAttr", () => {
+  testSync("Plugins RM requires the `name` discriminator", () => {
+    expect(QueryDbResolvers_AppSync.internalRowRequiredAttr("Plugins"))->toEqual(Some("name"))
+  })
+
+  testSync("ordinary read models require nothing (unchanged behaviour)", () => {
+    expect(QueryDbResolvers_AppSync.internalRowRequiredAttr("Products"))->toEqual(None)
+    expect(QueryDbResolvers_AppSync.internalRowRequiredAttr("Orders"))->toEqual(None)
+  })
+})
+
+describe("AppSync_Resolver_Retrying.Functions.listAllItemsConnection", () => {
+  testSync("with ~requireAttribute emits an attribute_exists filter that excludes internal rows", () => {
+    let code =
+      AppSync_Resolver_Retrying.Functions.listAllItemsConnection(
+        ~labelField="name",
+        ~requireAttribute="name",
+      )->codeOf
+    expect(code->String.includes("attribute_exists(#name)"))->toBe(true)
+    expect(code->String.includes("names['#name'] = 'name'"))->toBe(true)
+  })
+
+  testSync("without ~requireAttribute emits no attribute_exists filter (default read models unchanged)", () => {
+    let code =
+      AppSync_Resolver_Retrying.Functions.listAllItemsConnection(~labelField="name")->codeOf
+    expect(code->String.includes("attribute_exists"))->toBe(false)
+  })
+})

package/tests/QueryDbResolvers_AppSyncTest.res.mjs

@@ -0,0 +1,35 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as AppSync_Resolver_Functions$PulumiAws from "@reventlessdev/rescript-pulumi-aws/src/AppSync/AppSync_Resolver_Functions.res.mjs";
+import * as QueryDbResolvers_AppSync$ReventlessAws from "../src/adapter/QueryDb/QueryDbResolvers_AppSync.res.mjs";
+
+function codeOf(input) {
+  return input;
+}
+
+globalThis.describe("QueryDbResolvers_AppSync.internalRowRequiredAttr", () => {
+  globalThis.test("Plugins RM requires the `name` discriminator", () => {
+    globalThis.expect(QueryDbResolvers_AppSync$ReventlessAws.internalRowRequiredAttr("Plugins")).toEqual("name");
+  });
+  globalThis.test("ordinary read models require nothing (unchanged behaviour)", () => {
+    globalThis.expect(QueryDbResolvers_AppSync$ReventlessAws.internalRowRequiredAttr("Products")).toEqual(undefined);
+    globalThis.expect(QueryDbResolvers_AppSync$ReventlessAws.internalRowRequiredAttr("Orders")).toEqual(undefined);
+  });
+});
+
+globalThis.describe("AppSync_Resolver_Retrying.Functions.listAllItemsConnection", () => {
+  globalThis.test("with ~requireAttribute emits an attribute_exists filter that excludes internal rows", () => {
+    let code = AppSync_Resolver_Functions$PulumiAws.listAllItemsConnection("name", undefined, undefined, undefined, "name");
+    globalThis.expect(code.includes("attribute_exists(#name)")).toBe(true);
+    globalThis.expect(code.includes("names['#name'] = 'name'")).toBe(true);
+  });
+  globalThis.test("without ~requireAttribute emits no attribute_exists filter (default read models unchanged)", () => {
+    let code = AppSync_Resolver_Functions$PulumiAws.listAllItemsConnection("name", undefined, undefined, undefined, undefined);
+    globalThis.expect(code.includes("attribute_exists")).toBe(false);
+  });
+});
+
+export {
+  codeOf,
+}
+/*  Not a pure module */

package/tests/integration/DcbCommandTopicEntryPoint_IntegrationTest.res

@@ -59,6 +59,64 @@ let runOneAppSyncEvent: (string, JSON.t) => promise<JSON.t> = %raw(`
   }
 `)
 
+// Same as `runOneAppSyncEvent` but wires the composite-partition fixture
+// (EpCompositeSlice) through the real entry point. Proves the deployed path
+// derives and threads `partitionTag = Composite(...)` into the DynamoDB
+// `append` — the fix for the residual burst-contention bug.
+let runOneCompositeEvent: (string, JSON.t) => promise<JSON.t> = %raw(`
+  async (tableName, event) => {
+    const { buildHandlersForConfig } = await import(
+      "@reventlessdev/reventless-aws/src/adapter/Runtime/DcbCommandTopicEntryPoint.mjs"
+    );
+    const Effect = await import("effect/Effect");
+    const { tag: requestContextTag } = await import(
+      "@reventlessdev/reventless-core/src/RequestContext.res.mjs"
+    );
+    const { commandOutcomeToJson } = await import(
+      "@reventlessdev/reventless-core/src/components/CommandTopic/CommandTopic_Helpers.res.mjs"
+    );
+
+    const loadModule = async (specifier) => {
+      if (specifier === "ep-composite://spec") return await import("./EpCompositeSlice.res.mjs");
+      if (specifier === "ep-composite://behavior") return await import("./EpCompositeSliceBehavior.res.mjs");
+      throw new Error("unknown test specifier: " + specifier);
+    };
+
+    const config = {
+      pluginName: "EpCompositePlugin",
+      dcbEventLogTableName: tableName,
+      stateChangeSliceModules: [{ spec: "ep-composite://spec", behavior: "ep-composite://behavior" }],
+      queueUrl: "https://sqs.eu-west-1.amazonaws.com/000000000000/ep-composite-queue",
+    };
+
+    const [, cmdGenHandler] = await buildHandlersForConfig(config, { loadModule });
+
+    const effect = cmdGenHandler(event)
+      .pipe(Effect.provideService(requestContextTag, { correlationId: "ep-composite" }));
+    const outcome = await Effect.runPromise(effect);
+    return commandOutcomeToJson(outcome);
+  }
+`)
+
+let buildAddResourceEvent = (~environment, ~resourceName): JSON.t => {
+  // `command` is the command type name as a plain string — the shape AppSync's
+  // direct-invoke resolver sends and `CommandGenerator.payload.command: string`
+  // expects.
+  let arguments = Dict.fromArray([
+    ("environment", environment->JSON.Encode.string),
+    ("resourceName", resourceName->JSON.Encode.string),
+  ])
+  let meta = Dict.fromArray([
+    ("user", "ep-composite"->JSON.Encode.string),
+    ("ip", JSON.Encode.null),
+  ])
+  Dict.fromArray([
+    ("command", "AddResource"->JSON.Encode.string),
+    ("arguments", arguments->JSON.Encode.object),
+    ("meta", meta->JSON.Encode.object),
+  ])->JSON.Encode.object
+}
+
 let buildAppSyncEvent = (widgetId): JSON.t => {
   // CommandGenerator payload: `{command, arguments, meta, identity?}` — the
   // exact shape AppSync's direct-invoke resolver sends (matches the resolver
@@ -98,4 +156,51 @@ describe("DcbCommandTopicEntryPoint integration", () => {
       expect(s->String.includes("CommandAccepted"))->toBe(true)
     },
   )
+
+  // Residual composite-fence burst contention
+  // (docs/plans/dcb-composite-fence-residual-burst-contention.md).
+  //
+  // The entry point must derive `partitionTag = Composite(...)` and thread it
+  // into the DynamoDB `append`, so a `@compositePartitionTag` slice collapses to
+  // ONE synthetic composite fence per entity. Without the thread (the bug),
+  // `partitionTag` defaults to None, the collapse never fires, and each append
+  // fences on its individual members — the shared low-cardinality `environment`
+  // member then serialises/rejects distinct resources.
+  testAsync(
+    "composite-partition burst: distinct resources sharing a prefix all commit, only composite fences written",
+    async () => {
+      let table = await H.createDcbTableWithTagKeys(
+        "EpComposite_" ++ Date.now()->Float.toString,
+        ["environment", "resourceName"],
+      )
+      let env = "prod"
+      let resourceNames = ["res-a", "res-b", "res-c", "res-d", "res-e"]
+
+      // Concurrent burst — simulates the deploy-sync fan-out that surfaced the
+      // `retries exhausted` cascade on alpha.
+      let outcomes =
+        await resourceNames
+        ->Array.map(resourceName =>
+          runOneCompositeEvent(table.name, buildAddResourceEvent(~environment=env, ~resourceName))
+        )
+        ->Promise.all
+
+      // Every distinct composite entity must commit — none may conflict on the
+      // shared `environment` prefix.
+      outcomes->Array.forEach(outcomeJson => {
+        let s = outcomeJson->JSON.stringifyAny->Option.getOr("<unserializable>")
+        expect(s->String.includes("CommandAccepted"))->toBe(true)
+      })
+
+      // Mechanism-level proof: the only fence rows are the synthetic composite
+      // fences (`fence#__dcb_composite__:…`) — one per entity — with NO
+      // per-member `fence#environment:…` / `fence#resourceName:…` rows.
+      let fenceIds = await H.scanFenceIds(table)
+      let compositeFencePrefix = "fence#" ++ DcbEventLogStorage_DynamoDb_Runtime.compositeFenceTagKey
+      expect(fenceIds->Array.length)->toBe(resourceNames->Array.length)
+      fenceIds->Array.forEach(id => expect(id->String.startsWith(compositeFencePrefix))->toBe(true))
+
+      await H.deleteTable(table)
+    },
+  )
 })

package/tests/integration/DcbCommandTopicEntryPoint_IntegrationTest.res.mjs

@@ -2,6 +2,7 @@
 
 import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
 import * as DcbIntegrationHarness$ReventlessAws from "./DcbIntegrationHarness.res.mjs";
+import * as DcbEventLogStorage_DynamoDb_Runtime$ReventlessAws from "../../src/adapter/DcbEventLog/DcbEventLogStorage_DynamoDb_Runtime.res.mjs";
 
 let runOneAppSyncEvent = (async (tableName, event) => {
     const { buildHandlersForConfig } = await import(
@@ -36,6 +37,76 @@ let runOneAppSyncEvent = (async (tableName, event) => {
     return commandOutcomeToJson(outcome);
   });
 
+let runOneCompositeEvent = (async (tableName, event) => {
+    const { buildHandlersForConfig } = await import(
+      "@reventlessdev/reventless-aws/src/adapter/Runtime/DcbCommandTopicEntryPoint.mjs"
+    );
+    const Effect = await import("effect/Effect");
+    const { tag: requestContextTag } = await import(
+      "@reventlessdev/reventless-core/src/RequestContext.res.mjs"
+    );
+    const { commandOutcomeToJson } = await import(
+      "@reventlessdev/reventless-core/src/components/CommandTopic/CommandTopic_Helpers.res.mjs"
+    );
+
+    const loadModule = async (specifier) => {
+      if (specifier === "ep-composite://spec") return await import("./EpCompositeSlice.res.mjs");
+      if (specifier === "ep-composite://behavior") return await import("./EpCompositeSliceBehavior.res.mjs");
+      throw new Error("unknown test specifier: " + specifier);
+    };
+
+    const config = {
+      pluginName: "EpCompositePlugin",
+      dcbEventLogTableName: tableName,
+      stateChangeSliceModules: [{ spec: "ep-composite://spec", behavior: "ep-composite://behavior" }],
+      queueUrl: "https://sqs.eu-west-1.amazonaws.com/000000000000/ep-composite-queue",
+    };
+
+    const [, cmdGenHandler] = await buildHandlersForConfig(config, { loadModule });
+
+    const effect = cmdGenHandler(event)
+      .pipe(Effect.provideService(requestContextTag, { correlationId: "ep-composite" }));
+    const outcome = await Effect.runPromise(effect);
+    return commandOutcomeToJson(outcome);
+  });
+
+function buildAddResourceEvent(environment, resourceName) {
+  let $$arguments = Object.fromEntries([
+    [
+      "environment",
+      environment
+    ],
+    [
+      "resourceName",
+      resourceName
+    ]
+  ]);
+  let meta = Object.fromEntries([
+    [
+      "user",
+      "ep-composite"
+    ],
+    [
+      "ip",
+      null
+    ]
+  ]);
+  return Object.fromEntries([
+    [
+      "command",
+      "AddResource"
+    ],
+    [
+      "arguments",
+      $$arguments
+    ],
+    [
+      "meta",
+      meta
+    ]
+  ]);
+}
+
 function buildAppSyncEvent(widgetId) {
   let command = Object.fromEntries([[
       "AddWidget",
@@ -79,6 +150,31 @@ globalThis.describe("DcbCommandTopicEntryPoint integration", () => {
     let s = Stdlib_Option.getOr(JSON.stringify(outcomeJson), "<unserializable>");
     globalThis.expect(s.includes("CommandAccepted")).toBe(true);
   });
+  globalThis.test("composite-partition burst: distinct resources sharing a prefix all commit, only composite fences written", async () => {
+    let table = await DcbIntegrationHarness$ReventlessAws.createDcbTableWithTagKeys("EpComposite_" + Date.now().toString(), [
+      "environment",
+      "resourceName"
+    ]);
+    let resourceNames = [
+      "res-a",
+      "res-b",
+      "res-c",
+      "res-d",
+      "res-e"
+    ];
+    let outcomes = await Promise.all(resourceNames.map(resourceName => runOneCompositeEvent(table.name, buildAddResourceEvent("prod", resourceName))));
+    outcomes.forEach(outcomeJson => {
+      let s = Stdlib_Option.getOr(JSON.stringify(outcomeJson), "<unserializable>");
+      globalThis.expect(s.includes("CommandAccepted")).toBe(true);
+    });
+    let fenceIds = await DcbIntegrationHarness$ReventlessAws.scanFenceIds(table);
+    let compositeFencePrefix = "fence#" + DcbEventLogStorage_DynamoDb_Runtime$ReventlessAws.compositeFenceTagKey;
+    globalThis.expect(fenceIds.length).toBe(resourceNames.length);
+    fenceIds.forEach(id => {
+      globalThis.expect(id.startsWith(compositeFencePrefix)).toBe(true);
+    });
+    return await DcbIntegrationHarness$ReventlessAws.deleteTable(table);
+  });
 });
 
 let H;
@@ -86,6 +182,8 @@ let H;
 export {
   H,
   runOneAppSyncEvent,
+  runOneCompositeEvent,
+  buildAddResourceEvent,
   buildAppSyncEvent,
 }
 /* runOneAppSyncEvent Not a pure module */

package/tests/integration/DcbIntegrationHarness.res

@@ -73,6 +73,54 @@ let createDcbTable = async (tableName): Util_DynamoDb_Runtime.resolvedTable => {
   }
 }
 
+// Like `createDcbTable` but with a caller-supplied set of `tag_<key>` GSI names
+// plus `tag_composite`. Used by the composite-partition scenarios whose member
+// keys (e.g. `environment`, `resourceName`) are not in the default online-shop
+// `gsiNames` superset.
+let createDcbTableWithTagKeys = async (
+  tableName,
+  tagKeys: array<string>,
+): Util_DynamoDb_Runtime.resolvedTable => {
+  let indexNames =
+    tagKeys->Array.map(k => `tag_${k}`)->Array.concat(["tag_composite"])
+  let attributeDefinitions = Array.concat(
+    [attrDef("id"), attrDef("position")],
+    indexNames->Array.map(attrDef),
+  )
+  let input =
+    Dict.fromArray([
+      ("TableName", s(tableName)),
+      ("AttributeDefinitions", attributeDefinitions->JSON.Encode.array),
+      ("KeySchema", [keyEl("id", "HASH"), keyEl("position", "RANGE")]->JSON.Encode.array),
+      ("GlobalSecondaryIndexes", indexNames->Array.map(gsi)->JSON.Encode.array),
+      ("BillingMode", s("PAY_PER_REQUEST")),
+    ])->JSON.Encode.object
+  let _ = await send(createTableCommand(input))
+  {
+    Util_DynamoDb_Runtime.id: tableName,
+    name: tableName,
+    arn: `arn:aws:dynamodb:local:000000000000:table/${tableName}`,
+    hashKey: "id",
+  }
+}
+
+// Returns the `id`s of every fence sentinel row in the table (`id` begins with
+// `fence#`). Lets a test assert the fence *shape* directly — the mechanism-level
+// signal that the composite collapse fired (one `fence#__dcb_composite__:…` per
+// entity) rather than per-member `fence#<member>:…` rows.
+let scanFenceIds = async (table: Util_DynamoDb_Runtime.resolvedTable): array<string> => {
+  let items = await Util_DynamoDb_Runtime.scanStream({tableName: table.name})
+    ->Stream.runCollect
+    ->Effect.runPromise
+  items->Array.filterMap(item =>
+    item
+    ->JSON.Decode.object
+    ->Option.flatMap(obj => obj->Dict.get("id"))
+    ->Option.flatMap(JSON.Decode.string)
+    ->Option.flatMap(id => id->String.startsWith("fence#") ? Some(id) : None)
+  )
+}
+
 let deleteTable = async (table: Util_DynamoDb_Runtime.resolvedTable) => {
   let input = Dict.fromArray([("TableName", s(table.name))])->JSON.Encode.object
   let _ = await send(deleteTableCommand(input))

package/tests/integration/DcbIntegrationHarness.res.mjs

@@ -1,5 +1,10 @@
 // Generated by ReScript, PLEASE EDIT WITH CARE
 
+import * as Stream from "@reventlessdev/rescript-effect/src/Stream.res.mjs";
+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 Effect from "effect/Effect";
 import * as ClientDynamodb from "@aws-sdk/client-dynamodb";
 import * as DynamoDb_DynamoDb$AwsSdk from "@reventlessdev/rescript-aws-sdk/src/DynamoDb_DynamoDb.res.mjs";
 import * as Util_DynamoDb_Runtime$ReventlessAws from "../../src/util/Util_DynamoDb_Runtime.res.mjs";
@@ -111,6 +116,58 @@ async function createDcbTable(tableName) {
   };
 }
 
+async function createDcbTableWithTagKeys(tableName, tagKeys) {
+  let indexNames = tagKeys.map(k => `tag_` + k).concat(["tag_composite"]);
+  let attributeDefinitions = [
+    attrDef("id"),
+    attrDef("position")
+  ].concat(indexNames.map(attrDef));
+  let input = Object.fromEntries([
+    [
+      "TableName",
+      tableName
+    ],
+    [
+      "AttributeDefinitions",
+      attributeDefinitions
+    ],
+    [
+      "KeySchema",
+      [
+        keyEl("id", "HASH"),
+        keyEl("position", "RANGE")
+      ]
+    ],
+    [
+      "GlobalSecondaryIndexes",
+      indexNames.map(gsi)
+    ],
+    [
+      "BillingMode",
+      "PAY_PER_REQUEST"
+    ]
+  ]);
+  let cmd = new ClientDynamodb.CreateTableCommand(input);
+  await DynamoDb_DynamoDb$AwsSdk.client().send(cmd);
+  return {
+    id: tableName,
+    name: tableName,
+    arn: `arn:aws:dynamodb:local:000000000000:table/` + tableName,
+    hashKey: "id"
+  };
+}
+
+async function scanFenceIds(table) {
+  let items = await Effect.runPromise(Stream.runCollect(Util_DynamoDb_Runtime$ReventlessAws.scanStream({
+    TableName: table.name
+  })));
+  return Stdlib_Array.filterMap(items, item => Stdlib_Option.flatMap(Stdlib_Option.flatMap(Stdlib_Option.flatMap(Stdlib_JSON.Decode.object(item), obj => obj["id"]), Stdlib_JSON.Decode.string), id => {
+    if (id.startsWith("fence#")) {
+      return id;
+    }
+  }));
+}
+
 async function deleteTable(table) {
   let input = Object.fromEntries([[
       "TableName",
@@ -154,9 +211,11 @@ export {
   gsi,
   gsiNames,
   createDcbTable,
+  createDcbTableWithTagKeys,
+  scanFenceIds,
   deleteTable,
   counter,
   freshTable,
   setFence,
 }
-/* @aws-sdk/client-dynamodb Not a pure module */
+/* Stream Not a pure module */

package/tests/integration/EpCompositeSlice.res

@@ -0,0 +1,39 @@
+// Composite-partition slice fixture for `DcbCommandTopicEntryPoint_IntegrationTest`.
+//
+// Reproduces the deploy-sync workload shape from
+// docs/plans/dcb-composite-fence-residual-burst-contention.md: a
+// `@compositePartitionTag` over a low-cardinality prefix (`environment`) plus a
+// high-cardinality tail (`resourceName`). Distinct resources sharing the same
+// `environment` must NOT contend — but only if the entry point threads
+// `partitionTag = Composite(...)` into the DynamoDB `append`, activating the
+// single-composite-fence collapse. Without that thread the slice writes one
+// fence per member and the shared `environment` member goes hot.
+//
+// Explicit `@s.matches(Reventless.DcbTag.compositePartitionMember(...))` form
+// (not the `@compositePartitionTag` PPX shorthand) because reventless-ppx is not
+// wired into reventless-aws's rescript.json — same reason as EpTestSlice.
+
+@schema
+type consumedEvent = ResourceAdded({environment: string, resourceName: string})
+
+@schema
+type command = AddResource({
+  environment: @s.matches(Reventless.DcbTag.compositePartitionMember(~position=0, ~sep="/")) string,
+  resourceName: @s.matches(Reventless.DcbTag.compositePartitionMember(~position=1, ~sep="/")) string,
+})
+
+@schema
+type error = AlreadyAdded
+
+@schema
+type event = ResourceAdded({
+  environment: @s.matches(Reventless.DcbTag.compositePartitionMember(~position=0, ~sep="/")) string,
+  resourceName: @s.matches(Reventless.DcbTag.compositePartitionMember(~position=1, ~sep="/")) string,
+})
+
+let name = "EpCompositeSlice"
+let moduleUrl = "ep-test://EpCompositeSlice"
+let commandAuthorization = (_: command): Reventless.Authorization.permission => AllowAnonymous
+let readConsistency = Reventless.ReadConsistency.EscalateOnRetry
+
+// `module Id = Reventless.Id.String` — patched in by `patchSpecId` at runtime.

package/tests/integration/EpCompositeSlice.res.mjs

@@ -0,0 +1,46 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as S from "sury/src/S.res.mjs";
+import * as DcbTag$Reventless from "@reventlessdev/reventless-spec/src/components/DcbTag.res.mjs";
+
+let consumedEventSchema = S.schema(s => ({
+  TAG: "ResourceAdded",
+  environment: s.m(S.string),
+  resourceName: s.m(S.string)
+}));
+
+let commandSchema = S.schema(s => ({
+  TAG: "AddResource",
+  environment: s.m(DcbTag$Reventless.compositePartitionMember(0, "/")),
+  resourceName: s.m(DcbTag$Reventless.compositePartitionMember(1, "/"))
+}));
+
+let errorSchema = S.literal("AlreadyAdded");
+
+let eventSchema = S.schema(s => ({
+  TAG: "ResourceAdded",
+  environment: s.m(DcbTag$Reventless.compositePartitionMember(0, "/")),
+  resourceName: s.m(DcbTag$Reventless.compositePartitionMember(1, "/"))
+}));
+
+function commandAuthorization(param) {
+  return "AllowAnonymous";
+}
+
+let name = "EpCompositeSlice";
+
+let moduleUrl = "ep-test://EpCompositeSlice";
+
+let readConsistency = "EscalateOnRetry";
+
+export {
+  consumedEventSchema,
+  commandSchema,
+  errorSchema,
+  eventSchema,
+  name,
+  moduleUrl,
+  commandAuthorization,
+  readConsistency,
+}
+/* consumedEventSchema Not a pure module */

package/tests/integration/EpCompositeSliceBehavior.res

@@ -0,0 +1,22 @@
+// Behavior pair for `EpCompositeSlice`. Append-on-empty / reject-on-seen, per
+// composite entity: the decision read is scoped to one `{environment,
+// resourceName}` composite, so a fresh resource sees empty state and appends,
+// while a duplicate of the same composite key sees `true` and is rejected.
+
+type state = bool
+
+let initialState = false
+
+let evolve = (_state, _event: EpCompositeSlice.consumedEvent) => true
+
+let decide = (state, command: EpCompositeSlice.command): result<
+  array<EpCompositeSlice.event>,
+  EpCompositeSlice.error,
+> =>
+  switch (state, command) {
+  | (true, _) => Error(AlreadyAdded)
+  | (false, AddResource({environment, resourceName})) =>
+    Ok([ResourceAdded({environment, resourceName})])
+  }
+
+let moduleUrl = "ep-test://EpCompositeSliceBehavior"

package/tests/integration/EpCompositeSliceBehavior.res.mjs

@@ -0,0 +1,36 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+
+function evolve(_state, _event) {
+  return true;
+}
+
+function decide(state, command) {
+  if (state) {
+    return {
+      TAG: "Error",
+      _0: "AlreadyAdded"
+    };
+  } else {
+    return {
+      TAG: "Ok",
+      _0: [{
+          TAG: "ResourceAdded",
+          environment: command.environment,
+          resourceName: command.resourceName
+        }]
+    };
+  }
+}
+
+let initialState = false;
+
+let moduleUrl = "ep-test://EpCompositeSliceBehavior";
+
+export {
+  initialState,
+  evolve,
+  decide,
+  moduleUrl,
+}
+/* No side effect */