@reventlessdev/reventless-aws 3.0.0-alpha.209 → 3.0.0-alpha.211

package/src/Platform.res

@@ -13,10 +13,6 @@
 
 let log = ReventlessCore.Logger.fromEnv()
 
-// Deploy-time schema-push shrink-guard threshold (deploy-time analogue of the
-// 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
 // API config ref — populated during MakeWithConfig so slice builders
 // can access api/apiRole outside the functor constraint.
 //
@@ -105,9 +101,6 @@ module MakeWithConfig = (
     // Lambda (DynamoDB scan) — keep it off the Postgres selection like the other
     // admin stores.
     QueryDbBackend.exempt(ReventlessCore.UiFragments.name)
-    // The ApiFragments read model backs the Platform_ApiFragments status query
-    // (DynamoDB scan) and the schema-push SideEffect — admin store, off Postgres too.
-    QueryDbBackend.exempt(ReventlessCore.ApiFragmentsReadModelSpec.name)
   })
   type api = Types.AppSync.api
   type role = Types.AppSync.role
@@ -126,134 +119,112 @@ module MakeWithConfig = (
     ->Pulumi.Config.get("stack")
     ->Option.map(stack => Pulumi.StackReference.make(stack))
 
-  // Helper: build a phantom GraphQLApi.t from resolved id + endpoint strings.
-  let makePhantomApi = (apiId, apiEndpoint): PulumiAws.AppSync.GraphQLApi.t => ({
-    id: Pulumi.Output.make(apiId),
-    arn: Pulumi.Output.make(""),
-    name: Pulumi.Output.make(""),
-    uris: Pulumi.Output.make(({graphQL: apiEndpoint, realtime: ""}: PulumiAws.AppSync.GraphQLApi.uris)),
-  }: PulumiAws.AppSync.GraphQLApi.t)
-
-  // Helper: build a phantom IAM.Role.t from a resolved role ARN.
-  let makePhantomRole = (apiRoleArn): PulumiAws.IAM.Role.t => {
-    let roleName =
-      apiRoleArn->String.split("/")->Array.at(-1)->Option.getOr(apiRoleArn)
-    ({
-      arn: Pulumi.Output.make(apiRoleArn),
-      id: Pulumi.Output.make(roleName),
-      name: Pulumi.Output.make(roleName),
-    }: 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.
+  // Split-mode Domain base fragment. No component fields — the Domain merged
+  // API's fields come from plugin sources; this document only anchors the
+  // canonical relay base types. `Platform_ping` exists because a GraphQL
+  // schema cannot have an empty Query type (unresolved → null; spike
+  // precedent). The global `node` query is NOT emitted on AWS — see the
+  // "Relay node resolution" section of the merged-api plan (never resolved on
+  // any deployed AWS platform, zero consumers; the Node interface and global
+  // IDs stay).
+  let domainBaseFragment = ReventlessCore.GraphQL_Stitcher.encode({
+    types: [],
+    mutations: [],
+    queries: ["  Platform_ping: String"],
+    subscriptions: [],
+    subscriptionSources: [],
+  })
+
+  // The canonical base document for a merged API's platform-owned source:
+  // rendered standalone (relay base types included, no global `node` query),
+  // 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.stitchStandaloneWithAwsDirectives(~fragment=baseFragment)
+    ->AppSync_SdlDecorate.stampCanonicalTypes
+
+  // Admin base as a source-API document — auth-decorated (all fields Admin,
+  // Cognito-only; the deploy-time SigV4 system-caller fields died with the
+  // fragment registry) plus the canonical stamp.
+  let adminSourceSdl = (): string =>
+    assembleCanonicalSourceSdl(
+      ~baseFragment=AppSync_Adapter.injectAwsAuthAll(
+        ReventlessCore.AdminApi.baseFragment(~cloner=Config.cloner),
+        ~group="Admin",
+      ),
+    )
+
+  // Split-mode Domain source document: relay base types + Platform_ping — the
+  // Domain merged API's canonical owner (plugin fields come from plugin sources).
+  let domainBaseSourceSdl = (): string => assembleCanonicalSourceSdl(~baseFragment=domainBaseFragment)
 
   let (domainApi, domainApiRole, platformApi, platformApiRole) = switch platformStackRef {
   | None =>
-    let (api, role) = AppSync_Adapter.makeApiResource(~name="DomainApi", ~opts={})
+    // 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 document; the admin base lives on
+    // the Platform source API created in deployPlatform.
+    let schema = if Config.splitApi {
+      domainBaseSourceSdl()
+    } else {
+      adminSourceSdl()
+    }
+    let (api, role) = AppSync_Adapter.makeSourceApiResource(~name="DomainApi", ~schema, ~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)
   | Some(stackRef) =>
-    // Plugin mode — reconstruct phantom API/role from the platform's exported IDs.
-    // Consumers only access api.id and role.arn, so other fields are unused.
+    // Plugin 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.
     //
     // In ESM mode, Pulumi exports are inside the "default" output.
     // Try top-level field first (CJS), fall back to "default".<field> (ESM).
     let defaultOutput: Pulumi.Output.t<option<JSON.t>> =
       stackRef->Pulumi.StackReference.getOutput("default")
-
-    // ── Domain API (application mutations) ──────────────────────────────────
-    let domainApiIdOutput: Pulumi.Output.t<option<string>> =
-      stackRef->Pulumi.StackReference.getOutput("domainApiId")
-    let domainApiEndpointOutput: Pulumi.Output.t<option<string>> =
-      stackRef->Pulumi.StackReference.getOutput("domainApiEndpoint")
-    let domainApiRoleArnOutput: Pulumi.Output.t<option<string>> =
-      stackRef->Pulumi.StackReference.getOutput("domainApiRoleArn")
-
-    let phantomApi: Types.AppSync.api =
-      (domainApiIdOutput, domainApiEndpointOutput, defaultOutput)
+    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(((directId, directEndpoint, default)) => {
-        let apiId = switch directId {
-        | Some(id) => id
-        | None =>
-          default
-          ->Option.flatMap(d => d->JSON.Decode.object)
-          ->Option.flatMap(d => d->Dict.get("domainApiId"))
-          ->Option.flatMap(v => v->JSON.Decode.string)
-          ->Option.getOrThrow
-        }
-        let apiEndpoint = switch directEndpoint {
-        | Some(ep) => ep
-        | None =>
-          default
-          ->Option.flatMap(d => d->JSON.Decode.object)
-          ->Option.flatMap(d => d->Dict.get("domainApiEndpoint"))
-          ->Option.flatMap(v => v->JSON.Decode.string)
-          ->Option.getOrThrow(
-            ~message="Platform stack does not export 'domainApiEndpoint' — redeploy the platform stack first",
-          )
-        }
-        makePhantomApi(apiId, apiEndpoint)
-      })
-    let phantomRole: Types.AppSync.role =
-      (domainApiRoleArnOutput, defaultOutput)
-      ->Pulumi.Output.all2
-      ->Pulumi.Output.apply(((direct, default)) => {
-        let domainApiRoleArn = switch direct {
-        | Some(arn) => arn
-        | None =>
-          default
-          ->Option.flatMap(d => d->JSON.Decode.object)
-          ->Option.flatMap(d => d->Dict.get("domainApiRoleArn"))
-          ->Option.flatMap(v => v->JSON.Decode.string)
-          ->Option.getOrThrow
-        }
-        makePhantomRole(domainApiRoleArn)
-      })
-
-    // ── Platform API (admin / Platform_Sync* resolvers) ─────────────────────
-    let platformApiIdOutput: Pulumi.Output.t<option<string>> =
-      stackRef->Pulumi.StackReference.getOutput("platformApiId")
-    let platformApiEndpointOutput: Pulumi.Output.t<option<string>> =
-      stackRef->Pulumi.StackReference.getOutput("platformApiEndpoint")
-    let platformApiRoleArnOutput: Pulumi.Output.t<option<string>> =
-      stackRef->Pulumi.StackReference.getOutput("platformApiRoleArn")
-
-    let phantomPlatformApi: Types.AppSync.api =
-      (platformApiIdOutput, platformApiEndpointOutput, defaultOutput)
-      ->Pulumi.Output.all3
-      ->Pulumi.Output.apply(((directPlatId, directPlatEndpoint, default)) => {
+      ->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 platformApiId =
-          directPlatId
-          ->Option.orElse(getFromDefault("platformApiId"))
-          ->Option.getOrThrow
-        let platformApiEndpoint =
-          directPlatEndpoint
-          ->Option.orElse(getFromDefault("platformApiEndpoint"))
-          ->Option.getOrThrow
-        makePhantomApi(platformApiId, platformApiEndpoint)
-      })
-    let phantomPlatformRole: Types.AppSync.role =
-      (platformApiRoleArnOutput, defaultOutput)
-      ->Pulumi.Output.all2
-      ->Pulumi.Output.apply(((directPlat, 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 platformApiRoleArn =
-          directPlat
-          ->Option.orElse(getFromDefault("platformApiRoleArn"))
-          ->Option.getOrThrow
-        makePhantomRole(platformApiRoleArn)
+        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
+        )
       })
-
-    (phantomApi, phantomRole, phantomPlatformApi, phantomPlatformRole)
+    let (api, role) = AppSync_Adapter.makePluginSourceApiResource(
+      ~name="PluginSourceApi",
+      ~userPoolConfig,
+      ~opts={},
+    )
+    (api, role, api, role)
   }
 
   // Expose api/apiRole as Platform.T value bindings so DCB slice builders
@@ -577,37 +548,8 @@ module MakeWithConfig = (
     ReventlessCore.UiFragments,
     ReventlessCore.UiFragments_Projection,
   )
-  // 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: [],
-  })
-
-  module Api = {
-    module Make = (
-      FragmentConfig: {
-        let baseFragment: ReventlessInfra.Api.schemaFragment
-      },
-    ): ReventlessInfra.Api.T => {
-      module Builder = ReventlessCore.Api_Builder.Make(AppSync_Adapter)
-      // In split mode, the plugin API uses an empty base fragment so plugin schema
-      // has no core fields. In unified mode, use the provided base fragment as-is.
-      let effectiveBaseFragment = if Config.splitApi {
-        emptyBaseFragment
-      } else {
-        FragmentConfig.baseFragment
-      }
-      let make = (~name, ~opts=?) =>
-        Builder.make(~name, ~baseFragment=effectiveBaseFragment, ~opts?)
-    }
-  }
+  // (domainBaseFragment — the split-mode Domain source base — is defined above,
+  // next to the merged-mode source SDL assembly that uses it.)
 
   // ── Typed identity casts — see Platform_Casts.res for rationale ─────────
   open Platform_Casts
@@ -631,6 +573,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)
@@ -645,153 +593,6 @@ module MakeWithConfig = (
     | None => resolveHookedApi()
     }
 
-  // ── Phase 3: staged-deploy API-fragment registration ────────────────────────
-  // When a plugin deploys against an ALREADY-RUNNING platform (plugin-stack mode),
-  // it registers its API-schema fragment with the platform via the Platform API
-  // (SigV4 system caller) instead of writing deploy-schema:* rows and pushing the
-  // schema itself. The platform-side reactive single writer (Plan 2e) stitches and
-  // pushes; this waits on the push status so resolver creation (gated on the
-  // returned Output) proceeds only once the plugin's fields are ACTIVE — or fails
-  // with the stitch error. Used only in plugin-stack mode; makePlatform (all-at-once)
-  // keeps the direct deploy-time push (the reactive writer is dormant there).
-  @val external registerWaiterSetTimeout: (unit => unit, int) => unit = "setTimeout"
-  let deployWaiterDelay = (ms: int): promise<unit> =>
-    Promise.make((resolve, _) => registerWaiterSetTimeout(() => resolve(), ms))
-
-  // Poll the platform's Platform_ApiFragments status query until the plugin's row
-  // shows a push that landed at/after our registration time (`sinceAt`) — a fresh
-  // "ok" means our fields are live; a fresh "error" surfaces the stitch failure. An
-  // older "ok" is a stale prior deploy's and is ignored (ISO strings sort lexically).
-  let waitForApiFragmentPush = async (~endpoint, ~region, ~pluginId, ~sinceAt) => {
-    let query = "query { Platform_ApiFragments { pluginId pushStatus pushMessage pushedAt } }"
-    let maxAttempts = 90 // ~3 min at 2s intervals
-    let rec loop = async attempt =>
-      if attempt >= maxAttempts {
-        JsError.throwWithMessage(
-          `Timed out (>3min) waiting for the platform to push ${pluginId}'s API fragment — check the AdminEventCollector Lambda logs.`,
-        )
-      } else {
-        let data = await Util_AppSync_Caller.sendQuery(~endpoint, ~region, ~queryString=query)
-        let row =
-          data
-          ->Option.flatMap(JSON.Decode.object)
-          ->Option.flatMap(d => d->Dict.get("Platform_ApiFragments"))
-          ->Option.flatMap(JSON.Decode.array)
-          ->Option.getOr([])
-          ->Array.find(entry =>
-            entry
-            ->JSON.Decode.object
-            ->Option.flatMap(e => e->Dict.get("pluginId"))
-            ->Option.flatMap(JSON.Decode.string) == Some(pluginId)
-          )
-          ->Option.flatMap(JSON.Decode.object)
-        switch row {
-        | Some(e) =>
-          let field = k => e->Dict.get(k)->Option.flatMap(JSON.Decode.string)->Option.getOr("")
-          let status = field("pushStatus")
-          let fresh = field("pushedAt") >= sinceAt
-          if fresh && status == "ok" {
-            log.info(~comp="registerFragmentViaApi", `${pluginId} schema push confirmed ACTIVE`)
-          } else if fresh && status == "error" {
-            JsError.throwWithMessage(`Schema push failed for ${pluginId}: ${field("pushMessage")}`)
-          } else {
-            await deployWaiterDelay(2000)
-            await loop(attempt + 1)
-          }
-        | None =>
-          await deployWaiterDelay(2000)
-          await loop(attempt + 1)
-        }
-      }
-    await loop(0)
-  }
-
-  let registerFragmentViaApi = (
-    ~name: string,
-    ~fragment: Reventless.Plugin.apiSchemaFragment,
-    ~apiTargetName: string,
-  ): Pulumi.Output.t<unit> => {
-    // Platform_RegisterApiFragment is an admin systemCallable mutation on the Platform
-    // API (regardless of the plugin's apiTarget, which is passed as the enum argument).
-    let platformApi = switch apiConfigRef.contents {
-    | Some({platformApi}) => platformApi
-    | None => domainApi
-    }
-    let region =
-      Pulumi.Config.make(Some("aws"))->Pulumi.Config.get("region")->Option.getOr("unknown")
-    let endpointOutput =
-      platformApi
-      ->Pulumi.Output.flatMap(api => api.uris)
-      ->Pulumi.Output.apply(uris => uris.graphQL)
-    // Deregister-on-destroy: a dynamic resource whose `delete` handler sends
-    // Platform_DeregisterApiFragment when the plugin stack is destroyed (final
-    // retirement). It never replaces on a version bump, so supersession does NOT
-    // deregister — only a genuine `pulumi destroy` removes the fields.
-    let _ = ApiFragmentDeregistration.make(
-      ~name=`${name}ApiFragmentRegistration`,
-      ~pluginId=name,
-      ~endpoint=endpointOutput->Pulumi.Output.asInput,
-      ~region,
-    )
-    endpointOutput
-    ->Pulumi.Output.flatMap(endpoint => {
-      let run = async () => {
-        let at = Date.make()->Date.toISOString
-        // The registry is a SINGLETON aggregate — the mutation `id` arg is the fixed
-        // constant, `pluginId` (a payload field) carries the plugin name.
-        let variables = {
-          "id": "registry",
-          "pluginId": name,
-          "fragment": {"encoded": fragment.encoded, "protocol": fragment.protocol},
-          "apiTarget": Util_AppSync_Caller.graphqlEnum(apiTargetName),
-          "at": at,
-        }
-        let selection = "{ __typename ... on CommandAccepted { eventCount } ... on CommandRejected { errorCode errorDetail } }"
-        log.info(
-          ~comp="registerFragmentViaApi",
-          `Registering API fragment for ${name} (${apiTargetName}) via ${endpoint}`,
-        )
-        let result = await Util_AppSync_Caller.sendMutation(
-          ~endpoint,
-          ~region,
-          ~mutation="Platform_ApiFragmentRegistry_RegisterApiFragment",
-          ~selection,
-          ~variables,
-        )
-        let outcome =
-          result
-          ->Option.flatMap(JSON.Decode.object)
-          ->Option.flatMap(d => d->Dict.get("Platform_ApiFragmentRegistry_RegisterApiFragment"))
-          ->Option.flatMap(JSON.Decode.object)
-        switch outcome {
-        | Some(cmd) =>
-          let typename =
-            cmd->Dict.get("__typename")->Option.flatMap(JSON.Decode.string)->Option.getOr("")
-          switch typename {
-          | "CommandRejected" =>
-            let code =
-              cmd->Dict.get("errorCode")->Option.flatMap(JSON.Decode.string)->Option.getOr("unknown")
-            JsError.throwWithMessage(`RegisterApiFragment rejected for ${name}: ${code}`)
-          | "CommandAccepted" =>
-            // eventCount 0 ⇒ idempotent no-op (unchanged fragment) — fields already live,
-            // proceed without waiting; >0 ⇒ a real change, wait for the reactive push.
-            let eventCount =
-              cmd->Dict.get("eventCount")->Option.flatMap(JSON.Decode.float)->Option.getOr(0.0)
-            if eventCount > 0.0 {
-              await waitForApiFragmentPush(~endpoint, ~region, ~pluginId=name, ~sinceAt=at)
-            } else {
-              log.info(~comp="registerFragmentViaApi", `${name} fragment unchanged — no push needed`)
-            }
-          | _ => await waitForApiFragmentPush(~endpoint, ~region, ~pluginId=name, ~sinceAt=at)
-          }
-        | None =>
-          // Unparseable result (mutation may have failed) — fall back to polling.
-          await waitForApiFragmentPush(~endpoint, ~region, ~pluginId=name, ~sinceAt=at)
-        }
-      }
-      run()->Pulumi.Output.fromPromise
-    })
-  }
 
   let hooks: ReventlessCore.Plugin_Helpers.platformHooks = {
     // AWS uses Interstack for admin extension points — leave ref at empty dict.
@@ -838,97 +639,39 @@ 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)",
-        )
-        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, _)) =>
+    // 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.
+    preAdminResolversSchemaHook: (~adminBarrier) => adminBarrier,
+
+    // Push the plugin's standalone subgraph document to the plugin's OWN
+    // source API — a single writer by construction. The returned Output gates
+    // resolver creation 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.
+    preResolversSchemaHook: (~name, ~version, pluginFragment) => {
+      let sdl = AppSync_Adapter.stitchStandaloneWithAwsDirectives(~fragment=pluginFragment)
+      let pushed =
+        domainApi->Pulumi.Output.flatMap(api =>
           api.id->Pulumi.Output.flatMap(apiId => {
-            log.info(~comp="preAdminResolversSchemaHook", `Pushing admin schema to ${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 _ => {
-              log.info(
-                ~comp="preAdminResolversSchemaHook",
-                "startSchemaCreation called, waiting for ACTIVE",
-              )
               await AppSync_Adapter.waitForSchemaActive(client, apiId)
-              log.info(~comp="preAdminResolversSchemaHook", "schema is ACTIVE")
+              log.info(~comp="preResolversSchemaHook", "subgraph 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) => {
-      log.info(
-        ~comp="preResolversSchemaHook",
-        `Pushing schema for plugin ${name}@${version} to AppSync`,
-      )
-
-      // Capture deploy target synchronously — deployPlugin resets currentDeployTarget to
-      // Domain after P.make() returns, before any Pulumi.Output async callbacks run.
-      let capturedDeployTarget = currentDeployTarget.contents
-
-      switch platformStackRef {
-      | Some(_) =>
-        // Phase 3 — staged deploy against a running platform (deployPlugin): register the
-        // fragment via the Platform API; the reactive single writer (2e) stitches + pushes.
-        let apiTargetName = switch capturedDeployTarget {
-        | Domain => "Domain"
-        | Platform => "Platform"
-        }
-        registerFragmentViaApi(~name, ~fragment=pluginFragment, ~apiTargetName)
-      | None =>
-        // 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).",
-        )
-      }
+      mergedSchemaPushedRef := Some(pushed)
+      pushed
     },
     // 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:
@@ -1112,49 +855,6 @@ module MakeWithConfig = (
     PluginReadModelMappings,
   )
 
-  // Admin-internal ApiFragmentRegistry singleton aggregate — the platform API-schema
-  // fragment registry (docs/plans/event-sourced-fragment-registries.md). Threaded into
-  // Admin.construct's ~aggregates so registerAdminAggregateMutations wires
-  // Platform_ApiFragmentRegistry_RegisterApiFragment / _DeregisterApiFragment via the
-  // standard CommandGenerator auto-flow (RecordApiFragmentPush carries `@noApi`). IAM
-  // dual-auth for the SigV4 deploy caller comes from AdminApi.systemCallerFieldNames.
-  module ApiFragmentRegistryAggregate: (
-    ReventlessInfra.Aggregate.T with type api = Types.AppSync.api
-  ) = Aggregate_Builder_Single.Make(
-    ReventlessCore.ApiFragmentRegistrySpec,
-    ReventlessCore.ApiFragmentRegistryBehavior,
-    ReventlessInfra.NoEventMappings.Make(ReventlessCore.ApiFragmentRegistrySpec),
-  )
-
-  // Admin ApiFragments read model — per-plugin status rows off the aggregate's event
-  // topic (DynamoDB stream), backing the Platform_ApiFragments status query.
-  module ApiFragmentsReadModelMappings: Reventless.Projection.Mappings
-    with module Target := ReventlessCore.ApiFragmentsReadModelSpec = {
-    module M = ReventlessCore.ApiFragmentsProjection.Mappings
-    module type Mapping = M.Mapping
-    let moduleUrl: string = ReventlessCore.ApiFragmentsProjection.moduleUrl
-    let mappings: array<module(Mapping)> = ReventlessCore.ApiFragmentsProjection.mappings
-  }
-  // NoResolver builder: the ApiFragments RM's query surface is the dedicated
-  // Platform_ApiFragments Lambda (declared in baseFragment), NOT an auto-generated
-  // Connection resolver — so it must not emit AppSync query resolvers (they'd orphan
-  // against the static pushed baseFragment: "No field named apiFragments on type Query").
-  // Still stream-projects the table from the aggregate's event stream. Mirrors local's
-  // MakeNoResolver.
-  module ApiFragmentsReadModel = ReadModel_Builder_NoResolver_Stream.Make(
-    ReventlessCore.ApiFragmentsReadModelSpec,
-    ApiFragmentsReadModelMappings,
-  )
-
-  // Admin SideEffectHandler hosting the reactive schema-push side effect (ApiSchemaPush).
-  // Subscribes to the ApiFragmentRegistry aggregate's DynamoDB stream (single-shard for a
-  // singleton → naturally serialized, no concurrent StartSchemaCreation) and, on each
-  // ApiSchemaComputed, stitches + pushes the schema per target API, then records the
-  // outcome via RecordApiFragmentPush. Wired in deployPlatform (the staged path where the
-  // deploy caller fires RegisterApiFragment); makePlatform builds the schema directly and
-  // never triggers it.
-  module AdminApiSchemaPushHandler = SideEffectHandler_Single.Make()
-
   module type PluginMaker = {
     let make: unit => Plugin.component
   }
@@ -1283,185 +983,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}`)
-    // Create scheduler and populate platform context refs so Plugin_Builder
-    // can read them without app plugins having to pass them through.
-    let scheduler = makeScheduler()
-    hooks.scheduler := Some(scheduler)
-    hooks.api := Some(domainApi->wrapHookedValue)
-    hooks.apiRole := Some(domainApiRole->wrapHookedValue)
-
-    // 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.
-    let (platformApi, platformApiRole) = if Config.splitApi {
-      AppSync_Adapter.makeApiResource(~name="PlatformApi", ~opts={})
-    } else {
-      (domainApi, domainApiRole)
-    }
-
-    // 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.
-    hooks.adminApi := Some(platformApi->wrapHookedValue)
-
-    // Update splitApiOutputsRef and apiConfig with the now-known Platform API.
-    if Config.splitApi {
-      splitApiOutputsRef := Some({platformApi, platformApiRole})
-      switch apiConfigRef.contents {
-      | Some(c) =>
-        apiConfigRef := Some({
-          domainApi: c.domainApi,
-          domainApiRole: c.domainApiRole,
-          platformApi: platformApi,
-          platformApiRole: platformApiRole,
-        })
-      | None => ()
-      }
-    }
-
-    // Phase 2: Admin resolvers go on the Platform API (platformApi) in split mode,
-    // on the shared Domain API in unified mode.
-    let admin = Admin.construct(
-      ~version,
-      ~extensionPoints=[],
-      ~aggregates=[module(PluginAggregate), module(ApiFragmentRegistryAggregate)],
-      ~readModels=[module(PluginReadModel), module(ApiFragmentsReadModel)],
-      ~scheduler,
-      ~resourceNaming=Util_ResourceNaming.operations,
-      ~api=platformApi,
-      ~apiRole=platformApiRole,
-      ~stateChangeSlices=[module(UiFragmentRegistrySlice)],
-      ~stateViewSlices=[module(UiFragmentsViewSlice)],
-      ~automationSlices=[],
-      ~outboundTranslationSlices=[],
-      ~inboundTranslationSlices=[],
-    )
-
-    // Mount the Platform_ComponentDefinitions Lambda resolver on the Platform API
-    // (split mode) or Domain API (unified mode — platformApi == domainApi above).
-    // Also register the Plugin RM table with the AllAggregates Lambda runtime
-    // so its in-Lambda plugin status gate can read plugin status at command
-    // dispatch time (Part 2.3 of the resolver plan).
-    switch admin.readModelsOutputs->Dict.get("Plugins") {
-    | Some(pluginRm) =>
-      switch pluginRm.queryDb.resources->Array.get(0) {
-      | Some(r) =>
-        Platform_ComponentDefinitions_Lambda.make(
-          ~api=platformApi,
-          ~pluginReadModelTableName=r.name,
-          ~opts={},
-        )
-        AggregateRuntime_Builder_Single.setPluginReadModelTable(~name=r.name)
-      | None => ()
-      }
-    | None => ()
-    }
-
-    // Mount the Platform_UIFragments Lambda resolver — scans the UiFragments
-    // StateViewSlice table provisioned above and returns one entry per registered
-    // plugin UI.
-    switch admin.stateViewSlicesOutputs->Dict.get("UiFragments") {
-    | Some(rm) =>
-      switch rm.queryDb.resources->Array.get(0) {
-      | Some(r) =>
-        Platform_UIFragments_Lambda.make(
-          ~api=platformApi,
-          ~uiFragmentRegistryTableName=r.name,
-          ~schemaReady=admin.adminSchemaPushed,
-          ~opts={},
-        )
-      | None => ()
-      }
-    | None => ()
-    }
-
-    // Mount the Platform_ApiFragments Lambda resolver — scans the ApiFragments
-    // StateViewSlice table and returns the push-status row per plugin (the deploy
-    // waiter polls this). The query field is in the pushed admin base but was
-    // unresolved on AWS until now.
-    switch admin.readModelsOutputs->Dict.get("ApiFragments") {
-    | Some(rm) =>
-      switch rm.queryDb.resources->Array.get(0) {
-      | Some(r) =>
-        Platform_ApiFragments_Lambda.make(
-          ~api=platformApi,
-          ~apiFragmentRegistryTableName=r.name,
-          ~schemaReady=admin.adminSchemaPushed,
-          ~opts={},
-        )
-      | None => ()
-      }
-    | None => ()
-    }
-
-    // Build each plugin.
-    let pluginComponents = plugins->Array.map(plugin => {
-      module P = unpack(plugin)
-      P.make()
-    })
-
-    // Note: StateTopic_AppSync.finish runs from inside subscriptionInfraHook
-    // (Phase 4 wiring above), not here — Plugin_Builder fires the hook from
-    // within a Pulumi.Output.apply chain, so finishing synchronously here would
-    // see an empty registry.
-
-    // Export first plugin's outputs (monolithic mode = typically single plugin).
-    switch pluginComponents->Array.get(0) {
-    | Some(pluginComponent) =>
-      let pluginOutputs = pluginComponent->ReventlessCore.Component.outputs
-      ReventlessCore.Plugin_Helpers.exportPluginOutputs(pluginOutputs)
-    | None => ()
-    }
-
-    // B2.3d: provision the Postgres change-feed relay (monolithic mode — all plugins
-    // built above, so the DcbBackend relay registry is complete).
-    provisionPgChangeFeedRelay()
-
-    // B3.2b: provision the shared PgQueryResolver Lambda + AppSync data source for
-    // Postgres-backed read models (monolithic mode). Runs after construct so the
-    // resolver-binding registry (QueryDbResolvers_Lambda.make) and the ReadModel
-    // spec-module registry are complete; it fulfils the deferred `dataSourceName`
-    // the Postgres storage maker handed to the (schema-pushed) resolvers. App read
-    // model resolvers attach to the Domain API. Plugin-stack mode is deferred —
-    // it needs a per-stack data-source name to avoid collisions on the shared API.
-    switch QueryDbBackend.get() {
-    | Some(sel) => PgQueryResolver_Builder.provision(~api=domainApi, ~selection=sel, ~opts={})
-    | None => ()
-    }
-
-    // Admin schema push is fired by preAdminResolversSchemaHook from inside
-    // Admin.construct (with createResolvers gated on it). Only exports below.
-    if Config.splitApi {
-      // Platform API exports (split mode).
-      Pulumi.Pulumi.export("platformApiId", platformApi->Pulumi.Output.flatMap(api => api.id))
-      Pulumi.Pulumi.export(
-        "platformApiEndpoint",
-        platformApi->Pulumi.Output.flatMap(api =>
-          api.uris->Pulumi.Output.apply(uris => uris.graphQL)
-        ),
-      )
-      Pulumi.Pulumi.export("platformApiRoleArn", platformApiRole->Pulumi.Output.flatMap(role => role.arn))
-    } else {
-      // Platform API exports (unified mode — same resource as Domain API).
-      Pulumi.Pulumi.export("platformApiId", domainApi->Pulumi.Output.flatMap(api => api.id))
-      Pulumi.Pulumi.export(
-        "platformApiEndpoint",
-        domainApi->Pulumi.Output.flatMap(api =>
-          api.uris->Pulumi.Output.apply(uris => uris.graphQL)
-        ),
-      )
-      Pulumi.Pulumi.export("platformApiRoleArn", domainApiRole->Pulumi.Output.flatMap(role => role.arn))
-    }
-
-    // Domain API exports.
-    Pulumi.Pulumi.export("domainApiId", domainApi->Pulumi.Output.flatMap(api => api.id))
-    Pulumi.Pulumi.export(
-      "domainApiEndpoint",
-      domainApi->Pulumi.Output.flatMap(api =>
-        api.uris->Pulumi.Output.apply(uris => uris.graphQL)
-      ),
+    let _ = plugins
+    // Retired with the merged-API cutover: on AWS the platform deploys with
+    // deployPlatform (staged) and each plugin with deployPlugin — makePlatform
+    // predates the merge path and never gained merged wiring.
+    failwith(
+      "makePlatform is not supported on AWS — deploy the platform with deployPlatform and " ++
+      "each plugin with deployPlugin (merged-API composition).",
     )
-    Pulumi.Pulumi.export("domainApiRoleArn", domainApiRole->Pulumi.Output.flatMap(role => role.arn))
   }
 
   // Optional host UI shell bundle: a static SPA (e.g. reventless-ui's host-shell)
@@ -1473,6 +1002,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 +1024,73 @@ 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={})
+      AppSync_Adapter.makeSourceApiResource(~name="PlatformApi", ~schema=adminSourceSdl(), ~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 = {
+      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,
+        })
+      }
+    }
+
     // 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.
@@ -1526,8 +1128,8 @@ module MakeWithConfig = (
       // (Heartbeat, ForwardCommand). None here keeps the deploy-time path
       // unchanged; the .mjs entry point supplies a real implementation.
       let manageSubscriptions = None
-      // Runtime connect-driven schema self-heal retired in Phase 4b — the reactive
-      // ApiSchemaPush SideEffect (on ApiFragmentRegistry events) is the single writer.
+      // No runtime schema writer exists under merged-API composition — every
+      // source API is its own single writer.
       let updateApiSchema = None
     })
 
@@ -1536,8 +1138,8 @@ module MakeWithConfig = (
     let admin = Admin.construct(
       ~version,
       ~extensionPoints=[module(PluginExtensionPoint)],
-      ~aggregates=[module(PluginAggregate), module(ApiFragmentRegistryAggregate)],
-      ~readModels=[module(PluginReadModel), module(ApiFragmentsReadModel)],
+      ~aggregates=[module(PluginAggregate)],
+      ~readModels=[module(PluginReadModel)],
       ~scheduler,
       ~resourceNaming=Util_ResourceNaming.operations,
       ~api=platformApi,
@@ -1549,79 +1151,6 @@ module MakeWithConfig = (
       ~inboundTranslationSlices=[],
     )
 
-    // Reactive schema-push SideEffect (docs/plans/event-sourced-fragment-registries.md §
-    // Reactive writer design). Host ApiSchemaPush on an admin SideEffectHandler subscribed to
-    // the ApiFragmentRegistry aggregate's event topic (its DynamoDB stream). Deploy-derived
-    // config the runtime-pure push reads at invocation time is injected as Lambda env
-    // (~extraEnvVars); ~targets grants SQS send to the aggregate command topic (for the
-    // RecordApiFragmentPush write-back). Only in deployPlatform (the staged path where the
-    // deploy caller fires RegisterApiFragment); makePlatform pushes the schema directly.
-    let apiSchemaPushEventTopics = ReventlessCore.Aggregate.allEventTopics(admin.aggregatesOutputs)
-    let apiSchemaPushCmdTopics = ReventlessCore.Aggregate.allCommandTopics(admin.aggregatesOutputs)
-    // 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("")
-        }
-      )
-    | None => Pulumi.Output.make("")
-    }
-    let apiSchemaPushEnv = Dict.fromArray([
-      ("API_SCHEMA_PUSH_DOMAIN_API_ID", domainApiId->Pulumi.Output.asInput),
-      (
-        "API_SCHEMA_PUSH_PLATFORM_API_ID",
-        platformApi->Pulumi.Output.flatMap(api => api.id)->Pulumi.Output.asInput,
-      ),
-      (
-        "API_SCHEMA_PUSH_SPLIT_API",
-        Pulumi.Output.make(Config.splitApi ? "true" : "false")->Pulumi.Output.asInput,
-      ),
-      (
-        "API_SCHEMA_PUSH_CLONER",
-        Pulumi.Output.make(Config.cloner ? "true" : "false")->Pulumi.Output.asInput,
-      ),
-      ("API_SCHEMA_PUSH_CMD_TOPIC_URL", apiSchemaPushCmdTopicUrl->Pulumi.Output.asInput),
-    ])
-    // ApiSchemaPush ignores the injected queryEngine (it self-wires push + write-back from
-    // env); an empty one satisfies the SideEffectHandler contract. `scheduler`/`queryEngine`
-    // are Outputs, so make() runs inside their apply; finish() (which builds the shared
-    // Lambda from the registered handlers) is registered on apiSchemaPushCmdTopics
-    // immediately after make() so it runs AFTER make's own deferred forEventCollector apply
-    // on that same Output (Pulumi runs same-Output apply callbacks in registration order).
-    let apiSchemaPushQueryEngine = QueryEngine.DynamoDb.make(Dict.make())
-    let _ =
-      (scheduler, apiSchemaPushQueryEngine)
-      ->Pulumi.Output.all2
-      ->Pulumi.Output.apply(((sched, qe)) => {
-        let _ = AdminApiSchemaPushHandler.make(
-          ~name="AdminApiSchemaPush",
-          ~sideEffects=[module(ApiSchemaPush)],
-          ~allEventTopics=apiSchemaPushEventTopics,
-          ~allCommandTopics=apiSchemaPushCmdTopics,
-          ~targets=[ReventlessCore.ApiFragmentRegistrySpec.name],
-          ~queryEngine=qe,
-          ~scheduler=sched,
-          ~resourceNaming=Util_ResourceNaming.operations,
-          ~extraEnvVars=apiSchemaPushEnv,
-          ~opts={},
-        )
-        let _ = apiSchemaPushCmdTopics->Pulumi.Output.apply(_ =>
-          SideEffectHandlerRuntime_Builder_Single.finish()
-        )
-      })
-
     // Extract Plugin RM table name as Output.t<string>.
     // IMPORTANT: Do NOT use option<Pulumi.Output.t<…>> — Pulumi Outputs use property
     // lifting, which breaks ReScript's internal option encoding (BS_PRIVATE_NESTED_SOME_NONE).
@@ -1707,25 +1236,6 @@ module MakeWithConfig = (
     | None => ()
     }
 
-    // Mount the Platform_ApiFragments Lambda resolver — scans the ApiFragments
-    // StateViewSlice table and returns the push-status row per plugin (the deploy
-    // waiter polls this). The query field is in the pushed admin base but was
-    // unresolved on AWS until now.
-    switch admin.readModelsOutputs->Dict.get("ApiFragments") {
-    | Some(rm) =>
-      switch rm.queryDb.resources->Array.get(0) {
-      | Some(r) =>
-        Platform_ApiFragments_Lambda.make(
-          ~api=platformApi,
-          ~apiFragmentRegistryTableName=r.name,
-          ~schemaReady=admin.adminSchemaPushed,
-          ~opts={},
-        )
-      | None => ()
-      }
-    | None => ()
-    }
-
     // Note: StateTopic_AppSync.finish runs from inside subscriptionInfraHook
     // (Phase 4 wiring above), not here — see the note in deployPlatform.
 
@@ -1764,6 +1274,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 +1348,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,24 +1583,106 @@ 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 platformStackRef {
+    | 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()
 
     // B3.2b/c: provision this plugin stack's PgQueryResolver Lambda + AppSync data
-    // source for its Postgres-backed read models (registered during P.make()). App
-    // read model resolvers attach to the Domain API. Per-plugin Lambda + auto-named
-    // data source, so plugin stacks don't collide. The node(id) resolver is skipped
-    // in plugin-stack mode — it's a single shared Query.node field only one stack
-    // may own (monolithic-only; see PgQueryResolver_Builder.provision).
+    // source for its Postgres-backed read models (registered during P.make()).
+    // Resolvers attach to this plugin's own source API.
     switch QueryDbBackend.get() {
-    | Some(sel) =>
-      PgQueryResolver_Builder.provision(
-        ~api=domainApi,
-        ~selection=sel,
-        ~opts={},
-        ~createNodeResolver=false,
-      )
+    | Some(sel) => PgQueryResolver_Builder.provision(~api=domainApi, ~selection=sel, ~opts={})
     | None => ()
     }