@reventlessdev/reventless-aws 3.0.0-alpha.209 → 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()
 
@@ -51,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
@@ -109,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
@@ -145,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)
@@ -253,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
@@ -580,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 = (
@@ -631,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)
@@ -838,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 _ => {
-              log.info(
-                ~comp="preAdminResolversSchemaHook",
-                "startSchemaCreation called, waiting for ACTIVE",
-              )
-              await AppSync_Adapter.waitForSchemaActive(client, apiId)
-              log.info(~comp="preAdminResolversSchemaHook", "schema is ACTIVE")
+      } 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
             })
-            ->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) => {
+    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="preResolversSchemaHook",
+                `Pushing subgraph schema for ${name}@${version} to source API ${apiId}`,
+              )
+              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
+            })
+          )
+        mergedSchemaPushedRef := Some(pushed)
+        pushed
+      } else {
       log.info(
         ~comp="preResolversSchemaHook",
         `Pushing schema for plugin ${name}@${version} to AppSync`,
@@ -929,7 +1075,7 @@ module MakeWithConfig = (
           "deployPlatform and each plugin with deployPlugin (staged register + reactive push).",
         )
       }
-    },
+      },
     // 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
@@ -1283,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()
@@ -1473,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()
@@ -1483,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.
@@ -1764,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) =>
@@ -1800,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)
@@ -2024,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()
@@ -2102,6 +2475,7 @@ module Make = (): (
 ) => {
   include MakeWithConfig({
     let splitApi = true
+    let mergedApi = true
     let cloner = false
     let commandHandlerConfig: ReventlessCore.Runtime.commandHandlerConfigs = {}
     let pgConnection = None