@reventlessdev/reventless-aws 3.0.0-alpha.208 → 3.0.0-alpha.210

package/src/Platform.res

@@ -9,7 +9,9 @@
 //   module App = MyPlugin.Make(Platform)
 //
 // Custom config:
-//   module Platform = Platform.MakeWithConfig({let splitApi = false; let cloner = true})
+//   module Platform = Platform.MakeWithConfig({
+//     let splitApi = false; let mergedApi = false; let cloner = true
+//   })
 
 let log = ReventlessCore.Logger.fromEnv()
 
@@ -17,14 +19,6 @@ let log = ReventlessCore.Logger.fromEnv()
 // runtime RUNTIME_SCHEMA_SHRINK_THRESHOLD in AdminEventCollectorEntryPoint.mjs).
 // A push whose stitched SDL has fewer than (threshold × live) root fields is
 // refused as a likely stale concurrent-deploy stitch. Default 0.5; override via
-// DEPLOY_SCHEMA_SHRINK_THRESHOLD; values outside (0, 1) fall back to the default.
-@val @scope("process") external processEnv: Dict.t<string> = "env"
-let deploySchemaShrinkThreshold: float =
-  switch processEnv->Dict.get("DEPLOY_SCHEMA_SHRINK_THRESHOLD")->Option.flatMap(Float.fromString) {
-  | Some(n) if n > 0. && n < 1. => n
-  | _ => 0.5
-  }
-
 // API config ref — populated during MakeWithConfig so slice builders
 // can access api/apiRole outside the functor constraint.
 //
@@ -59,6 +53,17 @@ let getSplitApiOutputs = () => splitApiOutputsRef.contents
 module MakeWithConfig = (
   Config: {
     let splitApi: bool
+    /** Merged-API composition (docs/plans/merged-api-push-free-composition.md).
+        `true` (the default — `Make()` sets it): the platform creates AppSync
+        MERGED APIs and the platform-owned APIs are ordinary SOURCE APIs with
+        declarative schemas; plugin stacks (deployPlugin) create their own
+        source API and associate it against the platform's exported merged-API
+        ARN. No fragment registration, no reactive schema push. `false` keeps
+        the legacy push path until its Phase-5 retirement — switching an
+        already-deployed platform in either direction requires wiping its
+        stacks. Supported with deployPlatform + deployPlugin (makePlatform
+        predates the merge path); all stacks of one platform must agree. */
+    let mergedApi: bool
     let cloner: bool
     let commandHandlerConfig: ReventlessCore.Runtime.commandHandlerConfigs
     /** B2.3c platform toggle. When `Some`, every DCB EventLog is Postgres-backed
@@ -117,6 +122,8 @@ module MakeWithConfig = (
     // (DynamoDB scan) and the schema-push SideEffect — admin store, off Postgres too.
     QueryDbBackend.exempt(ReventlessCore.ApiFragmentsReadModelSpec.name)
   })
+  let mergedApiMode = Config.mergedApi
+
   type api = Types.AppSync.api
   type role = Types.AppSync.role
   type apiTarget = Domain | Platform
@@ -153,9 +160,59 @@ module MakeWithConfig = (
     }: PulumiAws.IAM.Role.t)
   }
 
+  // ── Merged-mode source SDL assembly (merged-api plan, Phase 3) ────────────
+  // Empty base fragment — no types, no mutations, no queries. Used by the
+  // plugin Api in split mode (so plugin schema has no core fields) and as the
+  // base of the split-mode Domain source document below.
+  let emptyBaseFragment = ReventlessCore.GraphQL_Stitcher.encode({
+    types: [],
+    mutations: [],
+    queries: [],
+    subscriptions: [],
+    subscriptionSources: [],
+  })
+
+  // The canonical base document for a merged API's platform-owned source:
+  // stitched with an EMPTY plugin list (the stitch injects the relay base
+  // types and the global `node` query — only these canonical documents carry
+  // `node`), AWS-dialect decorated, and `@canonical`-stamped so the platform-
+  // owned shared types win over every plugin source's standalone copy
+  // (divergence is shadowed, not MERGE_FAILED — Phase-0 finding 1).
+  let assembleCanonicalSourceSdl = (~baseFragment): string =>
+    AppSync_Adapter.stitchWithAwsDirectives(~baseFragment, ~pluginFragments=[])
+    ->AppSync_SdlDecorate.stampCanonicalTypes
+
+  // Admin base as a source-API document — same assembly as the push path's
+  // preAdminResolversSchemaHook, plus the canonical stamp.
+  let adminSourceSdl = (): string =>
+    assembleCanonicalSourceSdl(
+      ~baseFragment=AppSync_Adapter.injectAwsAuthAll(
+        ReventlessCore.AdminApi.baseFragment(~cloner=Config.cloner),
+        ~group="Admin",
+        ~iamFieldNames=ReventlessCore.AdminApi.systemCallerFieldNames,
+      ),
+    )
+
+  // Split-mode Domain source document: relay base + `node` only — the Domain
+  // merged API's canonical owner (plugin fields come from plugin sources).
+  let relayBaseSourceSdl = (): string => assembleCanonicalSourceSdl(~baseFragment=emptyBaseFragment)
+
   let (domainApi, domainApiRole, platformApi, platformApiRole) = switch platformStackRef {
   | None =>
-    let (api, role) = AppSync_Adapter.makeApiResource(~name="DomainApi", ~opts={})
+    let (api, role) = if mergedApiMode {
+      // Merged mode: the Domain API is an ordinary GRAPHQL source API with a
+      // DECLARATIVE schema. Unified: it carries the admin base (the canonical
+      // document). Split: it carries only the relay base + `node`; the admin
+      // base lives on the Platform source API created in deployPlatform.
+      let schema = if Config.splitApi {
+        relayBaseSourceSdl()
+      } else {
+        adminSourceSdl()
+      }
+      AppSync_Adapter.makeSourceApiResource(~name="DomainApi", ~schema, ~opts={})
+    } else {
+      AppSync_Adapter.makeApiResource(~name="DomainApi", ~opts={})
+    }
     // In platform/monolithic mode the platform API is not yet known — it is created
     // during deployPlatform/makePlatform and the ref is updated there.
     (api, role, api, role)
@@ -261,7 +318,51 @@ module MakeWithConfig = (
         makePhantomRole(platformApiRoleArn)
       })
 
-    (phantomApi, phantomRole, phantomPlatformApi, phantomPlatformRole)
+    if mergedApiMode {
+      // Merged mode (merged-api plan, Phase 4): the plugin stack owns a real
+      // SOURCE API — the single writer for its subgraph schema and resolvers.
+      // It fills all four API slots (resolver wiring is target-agnostic here;
+      // apiTarget only decides WHICH merged API the association in
+      // deployPlugin points at). The user pool comes from the platform's
+      // exports so Cognito primary auth matches across all sources of the
+      // merged endpoint — the plugin stack provisions no pool/client.
+      let cognitoPoolIdOutput: Pulumi.Output.t<option<string>> =
+        stackRef->Pulumi.StackReference.getOutput("cognitoUserPoolId")
+      let cognitoRegionOutput: Pulumi.Output.t<option<string>> =
+        stackRef->Pulumi.StackReference.getOutput("cognitoRegion")
+      let userPoolConfig =
+        (cognitoPoolIdOutput, cognitoRegionOutput, defaultOutput)
+        ->Pulumi.Output.all3
+        ->Pulumi.Output.apply(((directPoolId, directRegion, default)) => {
+          let getFromDefault = key =>
+            default
+            ->Option.flatMap(d => d->JSON.Decode.object)
+            ->Option.flatMap(d => d->Dict.get(key))
+            ->Option.flatMap(v => v->JSON.Decode.string)
+          let userPoolId =
+            directPoolId
+            ->Option.orElse(getFromDefault("cognitoUserPoolId"))
+            ->Option.getOrThrow(
+              ~message="Platform stack does not export 'cognitoUserPoolId' — redeploy the platform stack first",
+            )
+          let awsRegion = directRegion->Option.orElse(getFromDefault("cognitoRegion"))
+          (
+            {
+              userPoolId,
+              ?awsRegion,
+              defaultAction: PulumiAws.AppSync.GraphQLApi.ALLOW,
+            }: PulumiAws.AppSync.GraphQLApi.userPoolConfig
+          )
+        })
+      let (api, role) = AppSync_Adapter.makePluginSourceApiResource(
+        ~name="PluginSourceApi",
+        ~userPoolConfig,
+        ~opts={},
+      )
+      (api, role, api, role)
+    } else {
+      (phantomApi, phantomRole, phantomPlatformApi, phantomPlatformRole)
+    }
   }
 
   // Expose api/apiRole as Platform.T value bindings so DCB slice builders
@@ -588,15 +689,8 @@ module MakeWithConfig = (
   // The API-fragment registry is a SINGLETON AGGREGATE now (not a DCB slice) — see
   // ApiFragmentRegistryAggregate / ApiFragmentsReadModel below.
 
-  // Empty base fragment — no types, no mutations, no queries.
-  // Used by the plugin Api in split mode so plugin schema has no core fields.
-  let emptyBaseFragment = ReventlessCore.GraphQL_Stitcher.encode({
-    types: [],
-    mutations: [],
-    queries: [],
-    subscriptions: [],
-    subscriptionSources: [],
-  })
+  // (emptyBaseFragment — the empty split-mode plugin base — is defined above,
+  // next to the merged-mode source SDL assembly that shares it.)
 
   module Api = {
     module Make = (
@@ -622,34 +716,6 @@ module MakeWithConfig = (
 
   // AWS platform hooks — all AWS-specific callbacks defined as a record.
   // In-memory hooks (mutationResolverHook etc.) are absent (optional = None).
-  let deploySchemaPrefix = "deploy-schema:"
-  let deploySchemaPlatformPrefix = "deploy-schema-platform:"
-  let deploySchemaHashPrefix = "deploy-schema-hash:"
-
-  let readSchemaHash = async (~tableName: string, ~apiId: string): option<string> => {
-    open AwsSdk.DynamoDb.DocumentClient
-    let key = Dict.fromArray([("id", `${deploySchemaHashPrefix}${apiId}`->JSON.Encode.string)])
-    try {
-      let result = await GetCommand.send(GetCommand.make({GetCommand.tableName, key}))
-      result.item
-      ->Option.flatMap(item => item->JSON.Decode.object)
-      ->Option.flatMap(d => d->Dict.get("hash"))
-      ->Option.flatMap(v => v->JSON.Decode.string)
-    } catch {
-    | _ => None
-    }
-  }
-
-  let writeSchemaHash = async (~tableName: string, ~apiId: string, ~hash: string): unit => {
-    open AwsSdk.DynamoDb.DocumentClient
-    let item =
-      Dict.fromArray([
-        ("id", `${deploySchemaHashPrefix}${apiId}`->JSON.Encode.string),
-        ("hash", hash->JSON.Encode.string),
-      ])->JSON.Encode.object
-    let _ = await PutCommand.send(PutCommand.make({PutCommand.tableName, item}))
-  }
-
   // (Deploy-time retire hook removed: supersession is now decided by the
   // name-keyed Plugin aggregate (VersionSuperseded) — no RM scan drives a command.)
 
@@ -667,6 +733,12 @@ module MakeWithConfig = (
   // plugins built afterwards read hooksApiRef (Domain/deploy-target). See platformHooks.adminApi.
   let hooksAdminApiRef: ref<option<ReventlessCore.Plugin_Helpers.hookedValue<unknown>>> = ref(None)
 
+  // Merged mode (plugin stack): the subgraph schema-push Output produced by
+  // preResolversSchemaHook, captured so deployPlugin can sequence the
+  // SourceApiAssociation behind it (the association's initial merge needs the
+  // source schema to exist on the plugin's source API).
+  let mergedSchemaPushedRef: ref<option<Pulumi.Output.t<unit>>> = ref(None)
+
   let resolveHookedApi = (): Types.AppSync.api =>
     switch hooksApiRef.contents {
     | Some({val}) => Obj.magic(val)
@@ -874,69 +946,107 @@ module MakeWithConfig = (
     // makePlatform / deployPlatform before Admin.construct fires, is visible):
     //   - split mode: platformApi from splitApiOutputsRef
     //   - unified mode / not-yet-populated: domainApi
-    preAdminResolversSchemaHook: (~adminBarrier) => {
-      // The admin-base SDL stitches AdminApi.baseFragment with an EMPTY plugin
-      // list, and startSchemaCreation REPLACES the whole schema. In split mode
-      // the admin schema belongs on the PlatformApi ONLY — the DomainApi carries
-      // plugin fields (emptyBaseFragment). If we pushed the admin-base-only SDL
-      // to the DomainApi it would wipe every plugin field, leaving exactly the
-      // admin-base set (the alpha 2026-07-08 clobber). So in split mode we push
-      // ONLY when the PlatformApi is known; if the ref is not yet populated we
-      // SKIP (never fall back to domainApi). Unified mode legitimately shares one
-      // API, so an unpopulated ref there means domainApi.
-      let targetApiOpt = switch (Config.splitApi, splitApiOutputsRef.contents) {
-      | (_, Some({platformApi})) => Some(platformApi)
-      | (false, None) => Some(domainApi)
-      | (true, None) => None
-      }
-      switch targetApiOpt {
-      | None =>
-        log.error(
-          ~comp="preAdminResolversSchemaHook",
-          "split mode but the PlatformApi is not available at hook time — SKIPPING the admin schema push to avoid clobbering the DomainApi (pushing admin-base here would wipe every plugin field)",
-        )
+    preAdminResolversSchemaHook: (~adminBarrier) =>
+      if mergedApiMode {
+        // Merged mode: the admin base SDL is DECLARATIVE on the source API
+        // resource (makeSourceApiResource) — the provider runs
+        // StartSchemaCreation + poll before the resource resolves, so admin
+        // resolvers chained on the API are already ordered after the schema
+        // is ACTIVE. No push.
         adminBarrier
-      | Some(targetApi) =>
-        let adminBaseFragment = AppSync_Adapter.injectAwsAuthAll(
-          ReventlessCore.AdminApi.baseFragment(~cloner=Config.cloner),
-          ~group="Admin",
-          // The ApiFragmentRegistry register/deregister mutations + the Platform_ApiFragments
-          // status query are invoked by the plugin/standalone deploy as a SigV4 system caller, so
-          // they carry the dual-auth (@aws_cognito_user_pools @aws_iam) directive.
-          ~iamFieldNames=ReventlessCore.AdminApi.systemCallerFieldNames,
-        )
-        let sdl = AppSync_Adapter.stitchWithAwsDirectives(
-          ~baseFragment=adminBaseFragment,
-          ~pluginFragments=[],
-        )
-        (targetApi, adminBarrier)
-        ->Pulumi.Output.all2
-        ->Pulumi.Output.flatMap(((api, _)) =>
-          api.id->Pulumi.Output.flatMap(apiId => {
-            log.info(~comp="preAdminResolversSchemaHook", `Pushing admin schema to ${apiId}`)
-            let client = AppSync_Adapter.getClient()
-            client
-            ->AppSync_Adapter.startSchemaCreationRetrying({apiId, definition: sdl})
-            ->Promise.then(async _ => {
+      } else {
+        // The admin-base SDL stitches AdminApi.baseFragment with an EMPTY plugin
+        // list, and startSchemaCreation REPLACES the whole schema. In split mode
+        // the admin schema belongs on the PlatformApi ONLY — the DomainApi carries
+        // plugin fields (emptyBaseFragment). If we pushed the admin-base-only SDL
+        // to the DomainApi it would wipe every plugin field, leaving exactly the
+        // admin-base set (the alpha 2026-07-08 clobber). So in split mode we push
+        // ONLY when the PlatformApi is known; if the ref is not yet populated we
+        // SKIP (never fall back to domainApi). Unified mode legitimately shares one
+        // API, so an unpopulated ref there means domainApi.
+        let targetApiOpt = switch (Config.splitApi, splitApiOutputsRef.contents) {
+        | (_, Some({platformApi})) => Some(platformApi)
+        | (false, None) => Some(domainApi)
+        | (true, None) => None
+        }
+        switch targetApiOpt {
+        | None =>
+          log.error(
+            ~comp="preAdminResolversSchemaHook",
+            "split mode but the PlatformApi is not available at hook time — SKIPPING the admin schema push to avoid clobbering the DomainApi (pushing admin-base here would wipe every plugin field)",
+          )
+          adminBarrier
+        | Some(targetApi) =>
+          let adminBaseFragment = AppSync_Adapter.injectAwsAuthAll(
+            ReventlessCore.AdminApi.baseFragment(~cloner=Config.cloner),
+            ~group="Admin",
+            // The ApiFragmentRegistry register/deregister mutations + the Platform_ApiFragments
+            // status query are invoked by the plugin/standalone deploy as a SigV4 system caller, so
+            // they carry the dual-auth (@aws_cognito_user_pools @aws_iam) directive.
+            ~iamFieldNames=ReventlessCore.AdminApi.systemCallerFieldNames,
+          )
+          let sdl = AppSync_Adapter.stitchWithAwsDirectives(
+            ~baseFragment=adminBaseFragment,
+            ~pluginFragments=[],
+          )
+          (targetApi, adminBarrier)
+          ->Pulumi.Output.all2
+          ->Pulumi.Output.flatMap(((api, _)) =>
+            api.id->Pulumi.Output.flatMap(apiId => {
+              log.info(~comp="preAdminResolversSchemaHook", `Pushing admin schema to ${apiId}`)
+              let client = AppSync_Adapter.getClient()
+              client
+              ->AppSync_Adapter.startSchemaCreationRetrying({apiId, definition: sdl})
+              ->Promise.then(async _ => {
+                log.info(
+                  ~comp="preAdminResolversSchemaHook",
+                  "startSchemaCreation called, waiting for ACTIVE",
+                )
+                await AppSync_Adapter.waitForSchemaActive(client, apiId)
+                log.info(~comp="preAdminResolversSchemaHook", "schema is ACTIVE")
+              })
+              ->Pulumi.Output.fromPromise
+            })
+          )
+        }
+      },
+
+    // Staged deploy (deployPlugin against a running platform): register the
+    // plugin's fragment via the Platform API (SigV4); the reactive ApiSchemaPush
+    // SideEffect stitches + pushes cumulatively. The legacy all-at-once
+    // deploy-schema:* write+scan+push path was retired in Phase 4b (makePlatform
+    // with plugins is no longer supported on AWS).
+    preResolversSchemaHook: (~name, ~version, pluginFragment) =>
+      if mergedApiMode {
+        // Merged mode (merged-api plan, Phase 4): push the plugin's standalone
+        // subgraph document to the plugin's OWN source API — a single writer
+        // by construction, so no SigV4 registration, no reactive stitcher, no
+        // waiter, no drift check, no destroy-path deregistration. The returned
+        // Output gates resolver creation (as on the push path) and deployPlugin
+        // additionally sequences the SourceApiAssociation behind it (the
+        // initial merge needs the source schema present). Under AUTO_MERGE
+        // every later schema update here re-merges automatically.
+        let sdl = AppSync_Adapter.stitchStandaloneWithAwsDirectives(~fragment=pluginFragment)
+        let pushed =
+          domainApi->Pulumi.Output.flatMap(api =>
+            api.id->Pulumi.Output.flatMap(apiId => {
               log.info(
-                ~comp="preAdminResolversSchemaHook",
-                "startSchemaCreation called, waiting for ACTIVE",
+                ~comp="preResolversSchemaHook",
+                `Pushing subgraph schema for ${name}@${version} to source API ${apiId}`,
               )
-              await AppSync_Adapter.waitForSchemaActive(client, apiId)
-              log.info(~comp="preAdminResolversSchemaHook", "schema is ACTIVE")
+              let client = AppSync_Adapter.getClient()
+              client
+              ->AppSync_Adapter.startSchemaCreationRetrying({apiId, definition: sdl})
+              ->Promise.then(async _ => {
+                await AppSync_Adapter.waitForSchemaActive(client, apiId)
+                log.info(~comp="preResolversSchemaHook", "subgraph schema is ACTIVE")
+              })
+              ->Pulumi.Output.fromPromise
             })
-            ->Pulumi.Output.fromPromise
-          })
-        )
-      }
-    },
-
-    // Accumulate fragments across independent plugin deployments: each plugin
-    // writes its fragment to the Plugin RM table (keyed "deploy-schema:<name>")
-    // at deploy time. The hook then scans for ALL deploy-schema entries and
-    // stitches them together — ensuring the schema is cumulative rather than
-    // overwritten by each plugin deployment.
-    preResolversSchemaHook: (~name, ~version, pluginFragment) => {
+          )
+        mergedSchemaPushedRef := Some(pushed)
+        pushed
+      } else {
       log.info(
         ~comp="preResolversSchemaHook",
         `Pushing schema for plugin ${name}@${version} to AppSync`,
@@ -956,344 +1066,16 @@ module MakeWithConfig = (
         }
         registerFragmentViaApi(~name, ~fragment=pluginFragment, ~apiTargetName)
       | None =>
-        // All-at-once (makePlatform): platform + plugins deploy in one stack, so the
-        // reactive writer is dormant — keep the direct deploy-time stitch + push below.
-
-      // Select DynamoDB key prefix and target AppSync API based on the current deploy target.
-      // Domain plugins use "deploy-schema:" and the Domain API (default behaviour).
-      // Platform plugins use a separate "deploy-schema-platform:" namespace and the Core API,
-      // so their cumulative schema is kept independent from the Domain API's schema.
-      let (schemaPrefix, targetApi) = switch capturedDeployTarget {
-      | Domain => (deploySchemaPrefix, domainApi)
-      | Platform =>
-        let api = switch apiConfigRef.contents {
-        | Some({platformApi}) => platformApi
-        | None => domainApi // fallback: Core API not yet constructed
-        }
-        (deploySchemaPlatformPrefix, api)
-      }
-
-      // Read a string output from the platform StackReference, falling back to
-      // the bundled "default" output object if the named export is not present
-      // (matches the layout Pulumi emits when a stack uses a single default
-      // export rather than per-key exports).
-      let readStackRefString = (stackRef, key) => {
-        let direct: Pulumi.Output.t<option<JSON.t>> =
-          stackRef->Pulumi.StackReference.getOutput(key)
-        let defaultOutput: Pulumi.Output.t<option<JSON.t>> =
-          stackRef->Pulumi.StackReference.getOutput("default")
-        (direct, defaultOutput)
-        ->Pulumi.Output.all2
-        ->Pulumi.Output.apply(((direct, default)) =>
-          switch direct->Option.flatMap(v => v->JSON.Decode.string) {
-          | Some(name) => Some(name)
-          | None =>
-            default
-            ->Option.flatMap(d => d->JSON.Decode.object)
-            ->Option.flatMap(d => d->Dict.get(key))
-            ->Option.flatMap(v => v->JSON.Decode.string)
-          }
+        // makePlatform(~plugins=[…]) all-at-once deploy-schema push retired in Phase 4b.
+        // Staged deployPlatform + deployPlugin (register + reactive SideEffect push) is the
+        // sole supported AWS deploy path. deployPlatform deploys no plugins, so this hook only
+        // fires for makePlatform-with-plugins — no longer supported on AWS.
+        failwith(
+          "makePlatform(~plugins=[…]) is no longer supported on AWS — deploy the platform with " ++
+          "deployPlatform and each plugin with deployPlugin (staged register + reactive push).",
         )
       }
-
-      // Prefer the dedicated PluginSchemaPersistence table (post-platform-fix);
-      // fall back to the Plugin RM table for backward compatibility with
-      // platforms deployed before the schema-persistence table existed. The
-      // Plugin RM table must not be reused for new schema-fragment writes —
-      // doing so leaks deploy-schema rows through the Platform_Plugins AppSync
-      // Connection resolver.
-      let schemaPersistenceTableNameOutput: Pulumi.Output.t<option<string>> = switch platformStackRef {
-      | Some(stackRef) =>
-        (
-          readStackRefString(stackRef, "pluginSchemaPersistenceTableName"),
-          readStackRefString(stackRef, "pluginRmTableName"),
-        )
-        ->Pulumi.Output.all2
-        ->Pulumi.Output.apply(((dedicated, legacy)) =>
-          switch dedicated {
-          | Some(_) as s => s
-          | None => legacy
-          }
-        )
-      | None => Pulumi.Output.make(None)
-      }
-
-      schemaPersistenceTableNameOutput
-      ->Pulumi.Output.flatMap(tableNameOpt => {
-        // Write this plugin's fragment to DynamoDB, then scan all deploy-schema
-        // entries to collect every deployed plugin's fragment.
-        let writeAndScanFragments = () =>
-          switch tableNameOpt {
-          | None =>
-            log.info(
-              ~comp="preResolversSchemaHook",
-              "No pluginSchemaPersistenceTableName / pluginRmTableName — skipping fragment persistence",
-            )
-            Promise.resolve([pluginFragment])
-          | Some(tableName) =>
-            open AwsSdk.DynamoDb.DocumentClient
-            // Write this plugin's fragment so subsequent plugin deployments find it.
-            let deployItem =
-              Dict.fromArray([
-                ("id", `${schemaPrefix}${name}`->JSON.Encode.string),
-                ("fragment", pluginFragment.encoded->JSON.Encode.string),
-              ])->JSON.Encode.object
-            log.info(
-              ~comp="preResolversSchemaHook",
-              `Writing deploy-schema entry for ${name} to ${tableName}`,
-            )
-            // Paginated scan — accumulate every deploy-schema entry across pages.
-            // A single ScanCommand returns at most 1 MB before yielding a
-            // LastEvaluatedKey; loop until the table is exhausted so a platform
-            // with many plugin fragments never stitches a partial schema.
-            let scanAllDeploySchemaItems = async () => {
-              let allItems = []
-              let startKey = ref(None)
-              let more = ref(true)
-              while more.contents {
-                let result = await ScanCommand.send(
-                  ScanCommand.make({
-                    ScanCommand.tableName: tableName,
-                    filterExpression: "begins_with(#id, :prefix)",
-                    expressionAttributeNames: Dict.fromArray([("#id", "id")]),
-                    expressionAttributeValues: Dict.fromArray([
-                      (":prefix", schemaPrefix->JSON.Encode.string),
-                    ]),
-                    exclusiveStartKey: ?startKey.contents,
-                  }),
-                )
-                result.items->Option.getOr([])->Array.forEach(item => allItems->Array.push(item))
-                switch result.lastEvaluatedKey {
-                | Some(_) as k => startKey := k
-                | None => more := false
-                }
-              }
-              allItems
-            }
-
-            PutCommand.send(PutCommand.make({PutCommand.tableName: tableName, item: deployItem}))
-            ->Promise.then(_ => {
-              // Scan for all deploy-schema entries from previously deployed plugins.
-              log.info(
-                ~comp="preResolversSchemaHook",
-                `Scanning ${tableName} for deploy-schema entries`,
-              )
-              scanAllDeploySchemaItems()
-            })
-            ->Promise.then(items => {
-              let fragments = items->Array.filterMap(item => {
-                try {
-                  let obj = item->JSON.stringify->JSON.parseOrThrow
-                  switch obj->JSON.Decode.object->Option.flatMap(d => d->Dict.get("fragment")) {
-                  | Some(fragmentJson) =>
-                    switch fragmentJson->JSON.Decode.string {
-                    | Some(encoded) =>
-                      Some({Reventless.Plugin.encoded, protocol: "graphql"})
-                    | None => None
-                    }
-                  | None => None
-                  }
-                } catch {
-                | _ => None
-                }
-              })
-              log.info(
-                ~comp="preResolversSchemaHook",
-                `Found ${fragments->Array.length->Int.toString} deploy-schema entries`,
-              )
-              Promise.resolve(fragments)
-            })
-            ->Promise.catch(err => {
-              let msg =
-                err
-                ->JsExn.fromException
-                ->Option.flatMap(JsExn.message)
-                ->Option.getOr("unknown")
-              log.info(
-                ~comp="preResolversSchemaHook",
-                `DynamoDB write/scan failed (${msg}) — using current plugin only`,
-              )
-              Promise.resolve([pluginFragment])
-            })
-          }
-
-        targetApi->Pulumi.Output.flatMap(api =>
-          api.id->Pulumi.Output.flatMap(apiId => {
-            // Serialise write-row → scan → stitch → push under the shared
-            // schema-push lease so a concurrent peer's stale scan can't clobber
-            // this stack's fields (see AppSync_Adapter.withSchemaPushLock).
-            let runSchemaPush = () => {
-            writeAndScanFragments()
-            ->Promise.then(async allPluginFragments => {
-              // Base fragment selection:
-              // - Platform target: always include admin base (the Core API owns admin ops).
-              // - Domain target, split mode: empty base (admin lives on Core API).
-              // - Domain target, unified mode: include admin base (single API has everything).
-              // Use capturedDeployTarget (set synchronously above) — currentDeployTarget has
-              // been reset to Domain by deployPlugin before this async callback runs.
-              let baseFragment = switch capturedDeployTarget {
-              | Platform =>
-                AppSync_Adapter.injectAwsAuthAll(
-                  ReventlessCore.AdminApi.baseFragment(~cloner=Config.cloner),
-                  ~group="Admin",
-                  ~iamFieldNames=ReventlessCore.AdminApi.systemCallerFieldNames,
-                )
-              | Domain =>
-                if Config.splitApi {
-                  emptyBaseFragment
-                } else {
-                  AppSync_Adapter.injectAwsAuthAll(
-                    ReventlessCore.AdminApi.baseFragment(~cloner=Config.cloner),
-                    ~group="Admin",
-                  )
-                }
-              }
-              let sdl = AppSync_Adapter.stitchWithAwsDirectives(
-                ~baseFragment,
-                ~pluginFragments=allPluginFragments,
-              )
-              let currentHash = AppSync_Adapter.sha256Hex(sdl)
-              let storedHash = switch tableNameOpt {
-              | Some(tn) => await readSchemaHash(~tableName=tn, ~apiId)
-              | None => None
-              }
-              let client = AppSync_Adapter.getClient()
-
-              // Introspect the live schema once — reused for the hash-match
-              // drift/repair check and the catastrophic-shrink guard on the push.
-              let liveSdl = await AppSync_Adapter.getIntrospectionSdl(client, apiId)
-
-              // The stored hash records what the DEPLOY last pushed. A runtime
-              // re-stitch (mkUpdateApiSchema) can clobber the live schema
-              // out-of-band WITHOUT updating this hash, so a matching hash does
-              // not guarantee the live schema is intact. Before trusting the
-              // hash to skip the push, introspect the live schema and confirm it
-              // still carries at least as many root-type (Mutation + Query +
-              // Subscription) fields as the SDL we would push. If it has drifted
-              // (shrunk) — or cannot be introspected despite a stored hash, which
-              // means a real failure rather than a first deploy — force the
-              // repair push so a clobbered schema heals on the next deploy.
-              let countRoots = s =>
-                ReventlessCore.GraphQL_Stitcher.countRootTypeFields(~sdl=s, ~typeName="Mutation") +
-                ReventlessCore.GraphQL_Stitcher.countRootTypeFields(~sdl=s, ~typeName="Query") +
-                ReventlessCore.GraphQL_Stitcher.countRootTypeFields(
-                  ~sdl=s,
-                  ~typeName="Subscription",
-                )
-              // Identity-aware drift check (not a bare count): the live schema is
-              // "intact" only when it is a SUPERSET of every root field we would
-              // push. Comparing name SETS heals equal-cardinality drift and field
-              // *swaps* — an admin-base clobber that leaves the DomainApi with the
-              // SAME number of root fields but the WRONG ones (admin-base instead
-              // of plugin fields) has a matching count yet is missing every
-              // expected plugin field, so a count test would wrongly skip.
-              let missingFields = ReventlessCore.GraphQL_Stitcher.missingRootFields(
-                ~expectedSdl=sdl,
-                ~liveSdl,
-              )
-              let skipPush = switch storedHash {
-              | Some(prev) if prev == currentHash =>
-                if liveSdl == "" {
-                  log.info(
-                    ~comp="preResolversSchemaHook",
-                    `hash matches but live schema could not be introspected — forcing repair push (check appsync:GetIntrospectionSchema permission)`,
-                  )
-                  false
-                } else if missingFields->Array.length > 0 {
-                  log.info(
-                    ~comp="preResolversSchemaHook",
-                    `hash matches but live schema is missing ${missingFields
-                      ->Array.length
-                      ->Int.toString} expected root field(s) (e.g. ${missingFields
-                      ->Array.slice(~start=0, ~end=5)
-                      ->Array.join(", ")}) — forcing repair push`,
-                  )
-                  false
-                } else {
-                  log.info(
-                    ~comp="preResolversSchemaHook",
-                    `SDL unchanged (hash ${currentHash->String.slice(
-                        ~start=0,
-                        ~end=12,
-                      )}…) and live schema is a superset of the expected root fields (${countRoots(
-                        liveSdl,
-                      )->Int.toString} live); skipping push`,
-                  )
-                  true
-                }
-              | _ => false
-              }
-              if !skipPush {
-                // Shrink guard — deploy-time counterpart of the runtime
-                // mkUpdateApiSchema guard (AdminEventCollectorEntryPoint.mjs).
-                // Plugin/service stacks share one AppSync API and StartSchemaCreation
-                // REPLACES the whole schema. A concurrent peer that scanned the
-                // deploy-schema table before this stack wrote its fragment row
-                // stitches an SDL missing this stack's fields; pushing it would drop
-                // the live fields and orphan their resolvers (NotFoundException: No
-                // field named X). Refuse a push that would catastrophically shrink
-                // the live schema — the field-owner's own deploy (whose scan includes
-                // its freshly-written row) pushes the complete set.
-                // isCatastrophicSchemaShrink returns false when the live schema is
-                // empty (first deploy / introspection unavailable), so the initial
-                // push still proceeds.
-                if (
-                  ReventlessCore.GraphQL_Stitcher.isCatastrophicSchemaShrink(
-                    ~currentSdl=liveSdl,
-                    ~newSdl=sdl,
-                    ~threshold=deploySchemaShrinkThreshold,
-                  )
-                ) {
-                  log.error(
-                    ~comp="preResolversSchemaHook",
-                    `ABORTED schema push for ${apiId}: stitched SDL (${countRoots(
-                        sdl,
-                      )->Int.toString} root field(s)) would catastrophically shrink the live schema (${countRoots(
-                        liveSdl,
-                      )->Int.toString} root field(s), threshold ${deploySchemaShrinkThreshold->Float.toString}) — refusing to clobber resolvers (likely a stale concurrent-deploy scan)`,
-                  )
-                } else {
-                  log.info(
-                    ~comp="preResolversSchemaHook",
-                    `Pushing schema to API ${apiId} (${allPluginFragments->Array.length->Int.toString} plugin fragments, new hash: ${currentHash->String.slice(~start=0, ~end=12)}…)`,
-                  )
-                  await client->AppSync_Adapter.startSchemaCreationRetrying({
-                    apiId,
-                    definition: sdl,
-                  })
-                  log.info(
-                    ~comp="preResolversSchemaHook",
-                    "startSchemaCreation called, waiting for ACTIVE",
-                  )
-                  await AppSync_Adapter.waitForSchemaActive(client, apiId)
-                  log.info(~comp="preResolversSchemaHook", "Schema is ACTIVE")
-                  switch tableNameOpt {
-                  | Some(tn) =>
-                    await writeSchemaHash(~tableName=tn, ~apiId, ~hash=currentHash)
-                  | None => ()
-                  }
-                }
-              }
-
-              // No deploy-time retire scan: the name-keyed Plugin aggregate
-              // decides supersession itself (VersionSuperseded) when the new
-              // version connects, so the manifest carries only the current
-              // version without any RM-read-driven command.
-            })
-            }
-
-            (
-              switch tableNameOpt {
-              | Some(tableName) =>
-                AppSync_Adapter.withSchemaPushLock(~tableName, ~apiId, runSchemaPush)
-              | None => runSchemaPush()
-              }
-            )->Pulumi.Output.fromPromise
-          })
-        )
-      })
-      }
-    },
+      },
     // DCB EventLog created hook — extracts DynamoDB table name for DCB CommandTopic Lambda handler.
     // Postgres-backed DCB logs (B2.3c) create no table, so there is no resource to read:
     // the DCB command Lambda derives its `dcb_event.log_name` from the plugin name and
@@ -1647,6 +1429,14 @@ module MakeWithConfig = (
   // In unified mode, makePlatform is a no-op (schema stitching handled by events).
   let makePlatform = (~version, ~plugins: array<module(PluginMaker)>) => {
     log.info(~comp="Platform", `v${version}`)
+    if mergedApiMode {
+      // Merged-API composition is wired in deployPlatform only (the sole
+      // supported staged AWS deploy path) — makePlatform predates it.
+      failwith(
+        "mergedApi mode is supported with deployPlatform only — deploy the platform with " ++
+        "deployPlatform and each plugin with deployPlugin.",
+      )
+    }
     // Create scheduler and populate platform context refs so Plugin_Builder
     // can read them without app plugins having to pass them through.
     let scheduler = makeScheduler()
@@ -1837,6 +1627,18 @@ module MakeWithConfig = (
     bundleVersion: string,
   }
 
+  // Merged-mode outputs of deployPlatform — the merged API(s), plus the
+  // deploy-time merge gates (Outputs that resolve on MERGE_SUCCESS and fail
+  // the deploy on MERGE_FAILED; folded into the ARN exports so they are
+  // consumed). platformMerged == domainMerged in unified mode, mirroring the
+  // platformApi/domainApi convention.
+  type mergedApiOutputs = {
+    domainMerged: AppSync_MergedApi.t,
+    platformMerged: AppSync_MergedApi.t,
+    domainMergeGate: Pulumi.Output.t<unit>,
+    platformMergeGate: Pulumi.Output.t<unit>,
+  }
+
   let deployPlatform = (~version, ~hostUiBundle: option<hostUiBundleConfig>=?) => {
     log.info(~comp="Platform:deployPlatform", `v${version}`)
     let scheduler = makeScheduler()
@@ -1847,12 +1649,79 @@ module MakeWithConfig = (
     // Phase 2: create the Platform API resource early — before Admin.construct —
     // so admin resolvers are attached to the correct API in split mode.
     // In unified mode this is the same resource as the Domain API.
+    // On the merge path the Platform API is an ordinary GRAPHQL source API
+    // carrying the admin canonical document declaratively.
     let (platformApi, platformApiRole) = if Config.splitApi {
-      AppSync_Adapter.makeApiResource(~name="PlatformApi", ~opts={})
+      if mergedApiMode {
+        AppSync_Adapter.makeSourceApiResource(~name="PlatformApi", ~schema=adminSourceSdl(), ~opts={})
+      } else {
+        AppSync_Adapter.makeApiResource(~name="PlatformApi", ~opts={})
+      }
     } else {
       (domainApi, domainApiRole)
     }
 
+    // ── Merged-API composition (merged-api plan, Phase 3) ──────────────────
+    // Create the merged API(s) and associate the platform-owned source(s).
+    // Plugin stacks associate their own source APIs against the exported
+    // merged-API ARN (Phase 4); `pulumi destroy` of a plugin stack deletes
+    // its association — retirement by construction.
+    let mergedOutputs = if mergedApiMode {
+      AppSync_MergedApi.assertCompatiblePrimaryAuth(
+        ~sourceMode=AppSync_MergedApi.authenticationTypeName(
+          AppSync_Adapter.primaryAuthenticationType,
+        ),
+        ~mergedMode=AppSync_MergedApi.primaryAuthMode,
+      )
+      let domainMerged = AppSync_MergedApi.make(~name="DomainMergedApi", ~opts={})
+      if Config.splitApi {
+        // Split: admin source → Platform merged API; the relay-base Domain
+        // source (the Domain merged API's canonical owner) → Domain merged.
+        let platformMerged = AppSync_MergedApi.make(~name="PlatformMergedApi", ~opts={})
+        let platformAssoc = AppSync_MergedApi.associateSource(
+          ~name="PlatformAdminSourceAssociation",
+          ~mergedApi=platformMerged,
+          ~sourceApi=platformApi,
+          ~opts={},
+        )
+        let domainAssoc = AppSync_MergedApi.associateSource(
+          ~name="DomainBaseSourceAssociation",
+          ~mergedApi=domainMerged,
+          ~sourceApi=domainApi,
+          ~opts={},
+        )
+        Some({
+          domainMerged,
+          platformMerged,
+          domainMergeGate: AppSync_MergedApi.mergeStatusGate(
+            ~mergedApi=domainMerged,
+            ~association=domainAssoc,
+          ),
+          platformMergeGate: AppSync_MergedApi.mergeStatusGate(
+            ~mergedApi=platformMerged,
+            ~association=platformAssoc,
+          ),
+        })
+      } else {
+        // Unified: the single source API carries the admin canonical document.
+        let assoc = AppSync_MergedApi.associateSource(
+          ~name="DomainAdminSourceAssociation",
+          ~mergedApi=domainMerged,
+          ~sourceApi=domainApi,
+          ~opts={},
+        )
+        let gate = AppSync_MergedApi.mergeStatusGate(~mergedApi=domainMerged, ~association=assoc)
+        Some({
+          domainMerged,
+          platformMerged: domainMerged,
+          domainMergeGate: gate,
+          platformMergeGate: gate,
+        })
+      }
+    } else {
+      None
+    }
+
     // Admin DCB mutation resolvers bind to the Platform API (split mode) or the shared api
     // (unified). Recorded now that the Platform API resource exists, so the admin's deferred
     // dcbConnectFn (via ~onAdminApi) targets it rather than the Domain/deploy-target hooksApiRef.
@@ -1890,47 +1759,9 @@ module MakeWithConfig = (
       // (Heartbeat, ForwardCommand). None here keeps the deploy-time path
       // unchanged; the .mjs entry point supplies a real implementation.
       let manageSubscriptions = None
-      let updateApiSchema = Some(async (queryEngine: Reventless.QueryEngine.operations) => {
-        open Reventless.QueryEngine.Filter
-        let apiId = domainApiId->Pulumi.Output.get
-        let plugins = await queryEngine.scan(
-          ~readModelName="Plugins",
-          ~filterConfigs=[("status", Contains, String("Connected"))],
-          ~limit=1000,
-        )
-        let fragments = plugins->Array.filterMap(json =>
-          try {
-            let state = json->S.parseOrThrow(ReventlessCore.PluginsReadModelSpec.stateSchema)
-            // Exclude Platform-target plugins — their schema belongs on the PlatformApi,
-            // not the DomainApi. Absent apiTarget defaults to "Domain".
-            switch state.apiTarget {
-            | Some("Platform") => None
-            | _ => state.apiSchemaFragment
-            }
-          } catch {
-          | _ => None
-          }
-        )
-        // In split mode, the plugin API only has plugin schema (admin is on the core API).
-        // In unified mode, stitch admin + plugins into the single shared API.
-        let baseFragment = if Config.splitApi {
-          emptyBaseFragment
-        } else {
-          AppSync_Adapter.injectAwsAuthAll(
-            ReventlessCore.AdminApi.baseFragment(~cloner=Config.cloner),
-            ~group="Admin",
-            ~iamFieldNames=ReventlessCore.AdminApi.systemCallerFieldNames,
-          )
-        }
-        let sdl = AppSync_Adapter.stitchWithAwsDirectives(
-          ~baseFragment,
-          ~pluginFragments=fragments,
-        )
-        await AppSync_Adapter.getClient()->AppSync_Adapter.startSchemaCreationRetrying({
-          apiId,
-          definition: sdl,
-        })
-      })
+      // Runtime connect-driven schema self-heal retired in Phase 4b — the reactive
+      // ApiSchemaPush SideEffect (on ApiFragmentRegistry events) is the single writer.
+      let updateApiSchema = None
     })
 
     // Phase 2: Admin resolvers go on the Platform API (platformApi) in split mode,
@@ -1960,18 +1791,26 @@ module MakeWithConfig = (
     // deploy caller fires RegisterApiFragment); makePlatform pushes the schema directly.
     let apiSchemaPushEventTopics = ReventlessCore.Aggregate.allEventTopics(admin.aggregatesOutputs)
     let apiSchemaPushCmdTopics = ReventlessCore.Aggregate.allCommandTopics(admin.aggregatesOutputs)
-    let apiSchemaPushCmdTopicUrl =
-      admin.aggregatesOutputs
-      ->Dict.get(ReventlessCore.ApiFragmentRegistrySpec.name)
-      ->Option.map(agg =>
-        agg.commandTopic->Pulumi.Output.flatMap(ct =>
-          switch ct.resources->Array.get(0) {
-          | Some(r) => r.id
-          | None => Pulumi.Output.make("")
-          }
-        )
+    // MUST be a `switch`, NOT `->Option.map(...)->Option.getOr(...)`. The map/getOr form
+    // materialises an `option<Pulumi.Output.t<string>>`, and wrapping a Pulumi Output in a
+    // ReScript option collapses the nested Output to `undefined` at runtime (the documented
+    // "option(Pulumi.Output.t) doesn't work" pitfall). That made API_SCHEMA_PUSH_CMD_TOPIC_URL
+    // resolve to undefined → Pulumi dropped the env var → the ApiSchemaPush runtime logged
+    // "no command-topic URL configured — skipping" and never pushed/recorded, so the deploy
+    // waiter timed out. Verified via local `pulumi preview`: map/getOr → isValidOutput=false;
+    // switch → isValidOutput=true.
+    let apiSchemaPushCmdTopicUrl = switch admin.aggregatesOutputs->Dict.get(
+      ReventlessCore.ApiFragmentRegistrySpec.name,
+    ) {
+    | Some(agg) =>
+      agg.commandTopic->Pulumi.Output.flatMap(ct =>
+        switch ct.resources->Array.get(0) {
+        | Some(r) => r.id
+        | None => Pulumi.Output.make("")
+        }
       )
-      ->Option.getOr(Pulumi.Output.make(""))
+    | None => Pulumi.Output.make("")
+    }
     let apiSchemaPushEnv = Dict.fromArray([
       ("API_SCHEMA_PUSH_DOMAIN_API_ID", domainApiId->Pulumi.Output.asInput),
       (
@@ -2029,19 +1868,6 @@ module MakeWithConfig = (
     | None => None
     }
 
-    // Dedicated DynamoDB table for deploy-time schema-fragment persistence
-    // (deploy-schema:<name>, deploy-schema-platform:<name>, deploy-schema-hash:<apiId>).
-    // Previously these infrastructure rows shared the Plugin RM table, which
-    // caused them to leak through Platform_Plugins' auto-generated AppSync
-    // Connection resolver (an unfiltered Scan). Hosting them on their own
-    // table keeps Plugin RM = Plugin aggregate entities only and restores
-    // parity with the in-memory adapter (which has no preResolversSchemaHook).
-    let pluginSchemaPersistenceTable = Util.DynamoDb.makeTable(
-      "PluginSchemaPersistence",
-      ~attributes=[{name: "id", type_: "S"}],
-      ~opts={},
-    )
-
     PluginExtensionPointRuntime_Builder.registerPluginExtensionPoint(
       ~pluginReadModelTableName?,
       ~schedulerRoleArn=hooks.schedulerRoleUrn.contents,
@@ -2075,34 +1901,8 @@ module MakeWithConfig = (
       ~eventTopicArn=pluginEpEventTopicArn,
       ~appSyncApiId=domainApiId,
       ~pluginReadModelTableName?,
-      // Runtime schema stitch reads deploy-time fragments from this durable table
-      // rather than the lifecycle-volatile Plugin RM Connected rows.
-      ~pluginSchemaPersistenceTableName=pluginSchemaPersistenceTable.name,
       ~schedulerRoleArn=hooks.schedulerRoleUrn.contents,
       ~clonerEnabled=Config.cloner,
-      // 2e: the reactive ApiFragmentRegistry single writer (admin EventCollector).
-      // The Platform AppSync id it pushes Platform-target fragments to (unified →
-      // domainApi, since platformApi == domainApi); the ApiFragments StateViewSlice
-      // table it re-folds from; the admin DCB command-topic FIFO URL it dispatches
-      // RecordApiFragmentPush to (captured during Admin.construct); and the mode flag.
-      ~platformApiId=platformApi->Pulumi.Output.flatMap(api => api.id),
-      // NB: must NOT be `->Option.map(r => r.name)`. `apiFragmentRegistryTableName`
-      // is `option<Pulumi.Output.t<string>>` (the forbidden pattern, CLAUDE.md code
-      // smells). The generic `Option.map` body runs `Primitive_option.some(r.name)`,
-      // and because a Pulumi Output lifts arbitrary property access, `some` inspects
-      // `.BS_PRIVATE_NESTED_SOME_NONE`, mis-reads the Output as a nested option, and
-      // stores the sentinel `{BS_PRIVATE_NESTED_SOME_NONE: 0}` instead of the Output —
-      // so the consumer's `tableOutput->Pulumi.Output.apply` crashes with
-      // "apply is not a function". A `Some(r.name)` LITERAL compiles unboxed (bare
-      // r.name), preserving the Output — the same dodge `pluginReadModelTableName` uses.
-      ~apiFragmentRegistryTableName=?switch admin.readModelsOutputs
-      ->Dict.get("ApiFragments")
-      ->Option.flatMap(rm => rm.queryDb.resources->Array.get(0)) {
-      | Some(r) => Some(r.name)
-      | None => None
-      },
-      ~adminDcbCmdTopicUrl=?AutomationSliceRuntime_Builder_Single.getDcbQueueUrl(),
-      ~splitApi=Config.splitApi,
       (),
     )
 
@@ -2197,6 +1997,44 @@ module MakeWithConfig = (
     )
     Pulumi.Pulumi.export("domainApiRoleArn", domainApiRole->Pulumi.Output.flatMap(role => role.arn))
 
+    // Merged-API exports — plugin stacks associate their source APIs against
+    // these ARNs (this replaces the SigV4 RegisterApiFragment handshake as the
+    // cross-stack wiring on the merge path), and `mergedApiPrimaryAuth` is the
+    // primary-auth contract source APIs must match. The ARN exports are gated
+    // on the merge-status poll so a MERGE_FAILED fails the deploy loudly
+    // instead of silently serving the last-good merged schema.
+    switch mergedOutputs {
+    | Some({domainMerged, platformMerged, domainMergeGate, platformMergeGate}) =>
+      let mergeGatedArn = (merged: AppSync_MergedApi.t, gate: Pulumi.Output.t<unit>) =>
+        (
+          merged.api->Pulumi.Output.flatMap((api: PulumiAws.AppSync.GraphQLApi.t) => api.arn),
+          gate,
+        )
+        ->Pulumi.Output.all2
+        ->Pulumi.Output.apply(((arn, _)) => arn)
+      let mergedEndpoint = (merged: AppSync_MergedApi.t) =>
+        merged.api->Pulumi.Output.flatMap((api: PulumiAws.AppSync.GraphQLApi.t) =>
+          api.uris->Pulumi.Output.apply(uris => uris.graphQL)
+        )
+      Pulumi.Pulumi.export("domainMergedApiArn", mergeGatedArn(domainMerged, domainMergeGate))
+      Pulumi.Pulumi.export(
+        "domainMergedApiId",
+        domainMerged.api->Pulumi.Output.flatMap((api: PulumiAws.AppSync.GraphQLApi.t) => api.id),
+      )
+      Pulumi.Pulumi.export("domainMergedApiEndpoint", mergedEndpoint(domainMerged))
+      Pulumi.Pulumi.export("platformMergedApiArn", mergeGatedArn(platformMerged, platformMergeGate))
+      Pulumi.Pulumi.export(
+        "platformMergedApiId",
+        platformMerged.api->Pulumi.Output.flatMap((api: PulumiAws.AppSync.GraphQLApi.t) => api.id),
+      )
+      Pulumi.Pulumi.export("platformMergedApiEndpoint", mergedEndpoint(platformMerged))
+      Pulumi.Pulumi.export(
+        "mergedApiPrimaryAuth",
+        Pulumi.Output.make(AppSync_MergedApi.primaryAuthMode),
+      )
+    | None => ()
+    }
+
     // Events API exports — consumed by plugin stacks to wire Source B (StateTopic) Lambdas.
     switch domainEventsApiOpt {
     | Some(eventsApi) =>
@@ -2215,14 +2053,6 @@ module MakeWithConfig = (
     | None => ()
     }
 
-    // Export the dedicated schema-persistence table name. preResolversSchemaHook
-    // prefers this over pluginRmTableName so deploy-schema rows no longer share
-    // the Plugin RM table.
-    Pulumi.Pulumi.export(
-      "pluginSchemaPersistenceTableName",
-      pluginSchemaPersistenceTable.name,
-    )
-
     // (No pluginAggrCmdTopicUrl export: the deploy-time retire hook that
     // published Retire commands to the Plugin aggregate queue is gone —
     // supersession is decided by the aggregate on connect.)
@@ -2241,11 +2071,22 @@ module MakeWithConfig = (
     )
 
     // Fire onPlatformDeployed hook with resolved platform metadata.
-    let resolvedDomainApiEndpoint = domainApi->Pulumi.Output.flatMap(api =>
+    // Client-facing endpoints: on the merge path clients query the MERGED
+    // endpoints (the source-API endpoints stay exported for coexisting
+    // push-path stacks) — these also feed the host-UI config.json below.
+    let clientDomainApi = switch mergedOutputs {
+    | Some({domainMerged}) => domainMerged.api
+    | None => domainApi
+    }
+    let clientPlatformApi = switch mergedOutputs {
+    | Some({platformMerged}) => platformMerged.api
+    | None => platformApi
+    }
+    let resolvedDomainApiEndpoint = clientDomainApi->Pulumi.Output.flatMap(api =>
       api.uris->Pulumi.Output.apply(uris => uris.graphQL)
     )
     let resolvedDomainApiRoleArn = domainApiRole->Pulumi.Output.flatMap(role => role.arn)
-    let resolvedPlatformApiEndpoint = platformApi->Pulumi.Output.flatMap(api =>
+    let resolvedPlatformApiEndpoint = clientPlatformApi->Pulumi.Output.flatMap(api =>
       api.uris->Pulumi.Output.apply(uris => uris.graphQL)
     )
     let resolvedPlatformApiRoleArn = platformApiRole->Pulumi.Output.flatMap(role => role.arn)
@@ -2465,6 +2306,97 @@ module MakeWithConfig = (
     let pluginOutputs = pluginComponent->ReventlessCore.Component.outputs
     ReventlessCore.Plugin_Helpers.exportPluginOutputs(pluginOutputs)
 
+    // ── Merged-API association (merged-api plan, Phase 4) ───────────────────
+    // Associate this plugin's source API with the platform's merged API —
+    // this replaces the SigV4 RegisterApiFragment handshake + reactive push +
+    // waiter as the schema-composition mechanism. `pulumi destroy` deletes
+    // the association + source API: retirement by construction. Create-time
+    // 409s (AWS serializes association creates per merged API) surface as a
+    // deploy failure — retry concurrent FIRST-TIME plugin deploys; steady-
+    // state schema updates never re-create the association.
+    switch (mergedApiMode, platformStackRef) {
+    | (true, Some(stackRef)) =>
+      let defaultOutput: Pulumi.Output.t<option<JSON.t>> =
+        stackRef->Pulumi.StackReference.getOutput("default")
+      let getMergedExport = (key: string): Pulumi.Output.t<string> => {
+        let direct: Pulumi.Output.t<option<string>> =
+          stackRef->Pulumi.StackReference.getOutput(key)
+        (direct, defaultOutput)
+        ->Pulumi.Output.all2
+        ->Pulumi.Output.apply(((direct, default)) =>
+          switch direct {
+          | Some(v) => v
+          | None =>
+            default
+            ->Option.flatMap(d => d->JSON.Decode.object)
+            ->Option.flatMap(d => d->Dict.get(key))
+            ->Option.flatMap(v => v->JSON.Decode.string)
+            ->Option.getOrThrow(
+              ~message=`Platform stack does not export '${key}' — deploy the platform with mergedApi=true first`,
+            )
+          }
+        )
+      }
+      // apiTarget collapses to "which merged API ARN the association points at".
+      let mergedApiArn = switch apiTarget {
+      | Domain => getMergedExport("domainMergedApiArn")
+      | Platform => getMergedExport("platformMergedApiArn")
+      }
+      // Primary-auth contract check (checked invariant, not a convention) —
+      // folded into the ARN the association consumes so it always runs.
+      let checkedMergedApiArn =
+        (mergedApiArn, getMergedExport("mergedApiPrimaryAuth"))
+        ->Pulumi.Output.all2
+        ->Pulumi.Output.apply(((arn, mergedMode)) => {
+          AppSync_MergedApi.assertCompatiblePrimaryAuth(
+            ~sourceMode=AppSync_MergedApi.authenticationTypeName(
+              AppSync_Adapter.primaryAuthenticationType,
+            ),
+            ~mergedMode,
+          )
+          arn
+        })
+      // Sequence the association behind the subgraph schema push (the
+      // intra-stack replacement of the schemaPushed cross-stack gate).
+      let schemaPushed = switch mergedSchemaPushedRef.contents {
+      | Some(pushed) => pushed
+      | None => Pulumi.Output.make()
+      }
+      let arnAfterSchemaPush =
+        (checkedMergedApiArn, schemaPushed)
+        ->Pulumi.Output.all2
+        ->Pulumi.Output.apply(((arn, _)) => arn)
+      let association = AppSync_MergedApi.associateSourceWithMergedArn(
+        ~name="PluginSourceAssociation",
+        ~mergedApiArn=arnAfterSchemaPush,
+        ~sourceApi=domainApi,
+        ~opts={},
+      )
+      // Fail the deploy loudly on MERGE_FAILED — the gate is folded into the
+      // exported association id so it is always consumed.
+      let mergeGate = AppSync_MergedApi.mergeStatusGateWith(
+        ~mergedApiIdentifier=checkedMergedApiArn,
+        ~association,
+      )
+      Pulumi.Pulumi.export(
+        "sourceApiAssociationId",
+        (association.associationId, mergeGate)
+        ->Pulumi.Output.all2
+        ->Pulumi.Output.apply(((id, _)) => id),
+      )
+      Pulumi.Pulumi.export(
+        "pluginSourceApiId",
+        domainApi->Pulumi.Output.flatMap(api => api.id),
+      )
+      Pulumi.Pulumi.export(
+        "pluginSourceApiEndpoint",
+        domainApi->Pulumi.Output.flatMap(api =>
+          api.uris->Pulumi.Output.apply(uris => uris.graphQL)
+        ),
+      )
+    | _ => ()
+    }
+
     // B2.3d: provision the Postgres change-feed relay (plugin-stack mode — this
     // plugin's Postgres DCB log(s) + collector queue were registered during P.make()).
     provisionPgChangeFeedRelay()
@@ -2543,6 +2475,7 @@ module Make = (): (
 ) => {
   include MakeWithConfig({
     let splitApi = true
+    let mergedApi = true
     let cloner = false
     let commandHandlerConfig: ReventlessCore.Runtime.commandHandlerConfigs = {}
     let pgConnection = None