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

package/src/components/Api/AppSync_SdlDecorate.res.mjs

@@ -3,7 +3,6 @@
 import * as Stdlib_Array from "@rescript/runtime/lib/es6/Stdlib_Array.js";
 import * as Stdlib_String from "@rescript/runtime/lib/es6/Stdlib_String.js";
 import * as GraphQL_Stitcher$ReventlessCore from "@reventlessdev/reventless-core/src/components/Api/GraphQL_Stitcher.res.mjs";
-import * as GraphQL_PushPlanner$ReventlessCore from "@reventlessdev/reventless-core/src/components/Api/GraphQL_PushPlanner.res.mjs";
 
 function injectAwsSubscribe(sdl, sources) {
   if (sources.length === 0) {
@@ -80,39 +79,48 @@ let sharedIamTypeNames = [
   "PageInfo",
   "CommandAccepted",
   "CommandRejected",
-  "CommandPending",
-  "Platform_ApiFragmentEntry"
+  "CommandPending"
 ];
 
 function stampSharedIamTypes(sdl) {
   return Stdlib_Array.reduce(sharedIamTypeNames, sdl, (acc, name) => acc.replace(`type ` + name + ` {`, `type ` + name + ` @aws_cognito_user_pools @aws_iam {`));
 }
 
-function planAwsPushes(rawAdminBase, iamFieldNames, fragments, splitApi) {
-  let authBase = injectAwsAuthAll(rawAdminBase, "Admin", iamFieldNames);
-  let targeted = fragments.map(f => {
-    let match = f.target;
-    let tmp = match === "Platform" ? "Platform" : "Domain";
-    return {
-      fragment: {
-        encoded: f.encoded,
-        protocol: f.protocol
-      },
-      target: tmp
-    };
-  });
-  let allFrags = targeted.map(t => t.fragment);
-  let sources = GraphQL_Stitcher$ReventlessCore.collectSubscriptionSources(rawAdminBase, allFrags);
-  return GraphQL_PushPlanner$ReventlessCore.planPushes(authBase, targeted, splitApi).map(plan => {
-    let sdl = stampSharedIamTypes(injectAwsSubscribe(plan.sdl, sources));
-    let match = plan.api;
-    let api;
-    api = match === "DomainApi" ? "DomainApi" : "PlatformApi";
-    return {
-      api: api,
-      sdl: sdl
-    };
-  });
+let canonicalTypeNames = [
+  "PageInfo",
+  "CommandAccepted",
+  "CommandRejected",
+  "CommandPending"
+];
+
+function stampCanonicalTypes(sdl) {
+  return sdl.split("\n").map(line => {
+    let isObjectDef = canonicalTypeNames.some(name => line.startsWith(`type ` + name + ` `));
+    let isNodeDef = line.startsWith("interface Node ") || line.startsWith("interface Node{");
+    let isUnionDef = line.startsWith("union CommandResult ") || line.startsWith("union CommandResult=");
+    if (line.includes("@canonical")) {
+      return line;
+    }
+    if (isObjectDef || isNodeDef) {
+      let braceIdx = Stdlib_String.indexOfOpt(line, "{");
+      if (braceIdx === undefined) {
+        return line;
+      }
+      let head = line.slice(0, braceIdx).trimEnd();
+      let tail = line.slice(braceIdx);
+      return head + ` @canonical ` + tail;
+    }
+    if (!isUnionDef) {
+      return line;
+    }
+    let eqIdx = Stdlib_String.indexOfOpt(line, "=");
+    if (eqIdx === undefined) {
+      return line;
+    }
+    let head$1 = line.slice(0, eqIdx).trimEnd();
+    let tail$1 = line.slice(eqIdx);
+    return head$1 + ` @canonical ` + tail$1;
+  }).join("\n");
 }
 
 export {
@@ -121,6 +129,7 @@ export {
   injectAwsAuthAll,
   sharedIamTypeNames,
   stampSharedIamTypes,
-  planAwsPushes,
+  canonicalTypeNames,
+  stampCanonicalTypes,
 }
 /* GraphQL_Stitcher-ReventlessCore Not a pure module */

package/src/components/Plugin.res.mjs

@@ -28,8 +28,7 @@ function Make(HooksConfig) {
     hooks: HooksConfig.hooks
   })({})({
     makeApiResource: AppSync_Adapter$ReventlessAws.makeApiResource,
-    generateFragment: AppSync_Adapter$ReventlessAws.generateFragment,
-    updateSchema: AppSync_Adapter$ReventlessAws.updateSchema
+    generateFragment: AppSync_Adapter$ReventlessAws.generateFragment
   })({
     make: RuntimeEnvironment_Lambda$ReventlessAws.make,
     groupBySource: RuntimeEnvironment_Lambda$ReventlessAws.groupBySource,

package/tests/AppSync_AdapterTest.res

@@ -652,3 +652,187 @@ describe("Split mode — empty base fragment", () => {
     expect(sdl)->toContain("Platform_Plugin")
   })
 })
+
+// ── Merged mode — canonical source documents ─────────────────────────────────
+//
+// On the merge path (merged-api-push-free-composition, Phase 3) the platform-
+// owned source APIs carry their schemas DECLARATIVELY: the admin base (or, in
+// split mode, the bare relay base) stitched with an empty plugin list and
+// stamped @canonical. These tests pin the assembled documents' load-bearing
+// properties; Platform.res composes exactly this pipeline.
+
+describe("Merged mode — canonical source documents", () => {
+  let assembleCanonicalSourceSdl = (~baseFragment) =>
+    AppSync_Adapter.stitchStandaloneWithAwsDirectives(~fragment=baseFragment)
+    ->AppSync_SdlDecorate.stampCanonicalTypes
+
+  // Mirrors Platform.res's domainBaseFragment: no component fields, one
+  // Platform_ping so the Query type is non-empty.
+  let domainBaseFragment = ReventlessCore.GraphQL_Stitcher.encode({
+    types: [],
+    mutations: [],
+    queries: ["  Platform_ping: String"],
+    subscriptions: [],
+    subscriptionSources: [],
+  })
+
+  let adminSourceSdl = assembleCanonicalSourceSdl(
+    ~baseFragment=AppSync_Adapter.injectAwsAuthAll(
+      ReventlessCore.AdminApi.baseFragment(~cloner=false),
+      ~group="Admin",
+    ),
+  )
+
+  let domainBaseSourceSdl = assembleCanonicalSourceSdl(~baseFragment=domainBaseFragment)
+
+  testSync("no AWS source document carries the global node query (dropped — see plan)", () => {
+    expect(adminSourceSdl)->not_->toContain("node(id: ID!): Node")
+    expect(domainBaseSourceSdl)->not_->toContain("node(id: ID!): Node")
+    // The Node interface and global IDs stay — they are what makes a future
+    // node() possible without a schema migration.
+    expect(adminSourceSdl)->toContain("interface Node")
+  })
+
+  testSync("admin source document stamps @canonical on the shared traversal types", () => {
+    expect(adminSourceSdl)->toContain("type PageInfo @aws_cognito_user_pools @aws_iam @canonical {")
+    expect(adminSourceSdl)->toContain("interface Node @canonical {")
+    expect(adminSourceSdl)->toContain("union CommandResult @canonical =")
+    expect(adminSourceSdl)->toContain(
+      "type CommandAccepted @aws_cognito_user_pools @aws_iam @canonical {",
+    )
+  })
+
+  testSync("admin source document keeps admin fields and shared-type IAM stamps", () => {
+    expect(adminSourceSdl)->toContain("Platform_Plugin")
+    // Type-level dual-auth on the shared traversal types (stampSharedIamTypes);
+    // no FIELD carries @aws_iam anymore — the SigV4 register/deregister surface
+    // died with the fragment registry.
+    expect(adminSourceSdl)->toContain("type PageInfo @aws_cognito_user_pools @aws_iam")
+  })
+
+  testSync("Domain base source document (split mode) is relay types + Platform_ping only", () => {
+    expect(domainBaseSourceSdl)->toContain("Platform_ping: String")
+    expect(domainBaseSourceSdl)->toContain("interface Node @canonical {")
+    expect(domainBaseSourceSdl)->toContain("type PageInfo")
+    // No admin or plugin fields on the split-mode Domain source.
+    expect(domainBaseSourceSdl)->not_->toContain("Platform_Plugin")
+    // No mutations → no CommandResult family on this source.
+    expect(domainBaseSourceSdl)->not_->toContain("union CommandResult")
+  })
+
+  // Phase 4: the plugin-stack subgraph document pushed to the plugin's own
+  // source API.
+  let pluginFragment = ReventlessCore.GraphQL_Stitcher.encode({
+    types: [
+      "type MyPlugin_Item implements Node {\n  id: ID!\n  name: String!\n}",
+      "type CommandAccepted {\n  msgId: ID!\n  eventCount: Int!\n}",
+    ],
+    mutations: ["MyPlugin_Item_Create(name: String!): CommandResult"],
+    queries: ["MyPlugin_Item(id: ID!): MyPlugin_Item"],
+    subscriptions: ["onMyPlugin_Item_Create(id: ID): CommandResult"],
+    subscriptionSources: [
+      {field: "onMyPlugin_Item_Create", mutations: ["MyPlugin_Item_Create"]},
+    ],
+  })
+
+  testSync("plugin subgraph document is standalone: relay types included, node omitted", () => {
+    let sdl = AppSync_Adapter.stitchStandaloneWithAwsDirectives(~fragment=pluginFragment)
+    expect(sdl)->toContain("interface Node")
+    expect(sdl)->toContain("type PageInfo")
+    expect(sdl)->toContain("MyPlugin_Item_Create")
+    expect(sdl)->not_->toContain("node(id: ID!): Node")
+  })
+
+  testSync("plugin subgraph document carries @aws_subscribe + shared-type IAM stamps, no @canonical", () => {
+    let sdl = AppSync_Adapter.stitchStandaloneWithAwsDirectives(~fragment=pluginFragment)
+    expect(sdl)->toContain(`@aws_subscribe(mutations: ["MyPlugin_Item_Create"])`)
+    expect(sdl)->toContain("type CommandAccepted @aws_cognito_user_pools @aws_iam {")
+    // Plugin subgraphs stay unstamped — the admin source's canonical defs win.
+    expect(sdl)->not_->toContain("@canonical")
+  })
+})
+
+// ── waitForMergeSuccess — association merge-status poll ─────────────────────
+
+describe("AppSync_Adapter.waitForMergeSuccess", () => {
+  // Fake AppSync client: `send` yields the canned responses in order and
+  // repeats the last one when the poll outruns the script.
+  let makeFakeClient = (
+    responses: array<AppSync_Adapter.getSourceApiAssociationResult>,
+  ): AppSync_Adapter.appSyncClient => {
+    let i = ref(0)
+    let fake = {
+      "send": _cmd => {
+        let idx = Math.Int.min(i.contents, responses->Array.length - 1)
+        i := i.contents + 1
+        Promise.resolve(responses->Array.getUnsafe(idx))
+      },
+    }
+    fake->Obj.magic
+  }
+
+  let response = (~status, ~detail=?): AppSync_Adapter.getSourceApiAssociationResult => {
+    sourceApiAssociation: Some({
+      sourceApiAssociationStatus: Some(status),
+      sourceApiAssociationStatusDetail: detail,
+    }),
+  }
+
+  test("resolves once the association reports MERGE_SUCCESS", async () => {
+    let client = makeFakeClient([
+      response(~status="MERGE_SCHEDULED"),
+      response(~status="MERGE_IN_PROGRESS"),
+      response(~status="MERGE_SUCCESS"),
+    ])
+    await AppSync_Adapter.waitForMergeSuccess(
+      client,
+      ~associationId="assoc-1",
+      ~mergedApiIdentifier="merged-1",
+      ~delayMs=1,
+    )
+  })
+
+  test("throws with the AWS status detail on MERGE_FAILED", async () => {
+    let client = makeFakeClient([
+      response(
+        ~status="MERGE_FAILED",
+        ~detail="Unable to resolve conflict on object with name SharedThing.x",
+      ),
+    ])
+    let message = ref("")
+    try {
+      await AppSync_Adapter.waitForMergeSuccess(
+        client,
+        ~associationId="assoc-1",
+        ~mergedApiIdentifier="merged-1",
+        ~delayMs=1,
+      )
+    } catch {
+    | exn =>
+      message :=
+        exn->JsExn.fromException->Option.flatMap(JsExn.message)->Option.getOr("(no message)")
+    }
+    expect(message.contents)->toContain("MERGE_FAILED")
+    expect(message.contents)->toContain("SharedThing.x")
+  })
+
+  test("times out after maxAttempts on a status that never settles", async () => {
+    let client = makeFakeClient([response(~status="MERGE_IN_PROGRESS")])
+    let message = ref("")
+    try {
+      await AppSync_Adapter.waitForMergeSuccess(
+        client,
+        ~associationId="assoc-1",
+        ~mergedApiIdentifier="merged-1",
+        ~maxAttempts=2,
+        ~delayMs=1,
+      )
+    } catch {
+    | exn =>
+      message :=
+        exn->JsExn.fromException->Option.flatMap(JsExn.message)->Option.getOr("(no message)")
+    }
+    expect(message.contents)->toContain("timed out")
+    expect(message.contents)->toContain("MERGE_IN_PROGRESS")
+  })
+})

package/tests/AppSync_AdapterTest.res.mjs

@@ -1,11 +1,14 @@
 // Generated by ReScript, PLEASE EDIT WITH CARE
 
 import * as S from "sury/src/S.res.mjs";
+import * as Stdlib_JsExn from "@rescript/runtime/lib/es6/Stdlib_JsExn.js";
 import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
 import * as Stdlib_JsError from "@rescript/runtime/lib/es6/Stdlib_JsError.js";
+import * as Primitive_exceptions from "@rescript/runtime/lib/es6/Primitive_exceptions.js";
 import * as AdminApi$ReventlessCore from "@reventlessdev/reventless-core/src/admin/AdminApi.res.mjs";
 import * as AppSync_Adapter$ReventlessAws from "../src/components/Api/AppSync_Adapter.res.mjs";
 import * as GraphQL_Stitcher$ReventlessCore from "@reventlessdev/reventless-core/src/components/Api/GraphQL_Stitcher.res.mjs";
+import * as AppSync_SdlDecorate$ReventlessAws from "../src/components/Api/AppSync_SdlDecorate.res.mjs";
 import * as PluginBaseFragment$ReventlessCore from "@reventlessdev/reventless-core/src/plugin/api/PluginBaseFragment.res.mjs";
 
 globalThis.describe("AppSync_Adapter.sha256Hex", () => {
@@ -603,6 +606,139 @@ globalThis.describe("Split mode — empty base fragment", () => {
   });
 });
 
+globalThis.describe("Merged mode — canonical source documents", () => {
+  let domainBaseFragment = GraphQL_Stitcher$ReventlessCore.encode({
+    types: [],
+    mutations: [],
+    queries: ["  Platform_ping: String"],
+    subscriptions: [],
+    subscriptionSources: []
+  });
+  let baseFragment = AppSync_Adapter$ReventlessAws.injectAwsAuthAll(AdminApi$ReventlessCore.baseFragment(false), "Admin", undefined);
+  let adminSourceSdl = AppSync_SdlDecorate$ReventlessAws.stampCanonicalTypes(AppSync_Adapter$ReventlessAws.stitchStandaloneWithAwsDirectives(baseFragment));
+  let domainBaseSourceSdl = AppSync_SdlDecorate$ReventlessAws.stampCanonicalTypes(AppSync_Adapter$ReventlessAws.stitchStandaloneWithAwsDirectives(domainBaseFragment));
+  globalThis.test("no AWS source document carries the global node query (dropped — see plan)", () => {
+    globalThis.expect(adminSourceSdl).not.toContain("node(id: ID!): Node");
+    globalThis.expect(domainBaseSourceSdl).not.toContain("node(id: ID!): Node");
+    globalThis.expect(adminSourceSdl).toContain("interface Node");
+  });
+  globalThis.test("admin source document stamps @canonical on the shared traversal types", () => {
+    globalThis.expect(adminSourceSdl).toContain("type PageInfo @aws_cognito_user_pools @aws_iam @canonical {");
+    globalThis.expect(adminSourceSdl).toContain("interface Node @canonical {");
+    globalThis.expect(adminSourceSdl).toContain("union CommandResult @canonical =");
+    globalThis.expect(adminSourceSdl).toContain("type CommandAccepted @aws_cognito_user_pools @aws_iam @canonical {");
+  });
+  globalThis.test("admin source document keeps admin fields and shared-type IAM stamps", () => {
+    globalThis.expect(adminSourceSdl).toContain("Platform_Plugin");
+    globalThis.expect(adminSourceSdl).toContain("type PageInfo @aws_cognito_user_pools @aws_iam");
+  });
+  globalThis.test("Domain base source document (split mode) is relay types + Platform_ping only", () => {
+    globalThis.expect(domainBaseSourceSdl).toContain("Platform_ping: String");
+    globalThis.expect(domainBaseSourceSdl).toContain("interface Node @canonical {");
+    globalThis.expect(domainBaseSourceSdl).toContain("type PageInfo");
+    globalThis.expect(domainBaseSourceSdl).not.toContain("Platform_Plugin");
+    globalThis.expect(domainBaseSourceSdl).not.toContain("union CommandResult");
+  });
+  let pluginFragment = GraphQL_Stitcher$ReventlessCore.encode({
+    types: [
+      "type MyPlugin_Item implements Node {\n  id: ID!\n  name: String!\n}",
+      "type CommandAccepted {\n  msgId: ID!\n  eventCount: Int!\n}"
+    ],
+    mutations: ["MyPlugin_Item_Create(name: String!): CommandResult"],
+    queries: ["MyPlugin_Item(id: ID!): MyPlugin_Item"],
+    subscriptions: ["onMyPlugin_Item_Create(id: ID): CommandResult"],
+    subscriptionSources: [{
+        field: "onMyPlugin_Item_Create",
+        mutations: ["MyPlugin_Item_Create"]
+      }]
+  });
+  globalThis.test("plugin subgraph document is standalone: relay types included, node omitted", () => {
+    let sdl = AppSync_Adapter$ReventlessAws.stitchStandaloneWithAwsDirectives(pluginFragment);
+    globalThis.expect(sdl).toContain("interface Node");
+    globalThis.expect(sdl).toContain("type PageInfo");
+    globalThis.expect(sdl).toContain("MyPlugin_Item_Create");
+    globalThis.expect(sdl).not.toContain("node(id: ID!): Node");
+  });
+  globalThis.test("plugin subgraph document carries @aws_subscribe + shared-type IAM stamps, no @canonical", () => {
+    let sdl = AppSync_Adapter$ReventlessAws.stitchStandaloneWithAwsDirectives(pluginFragment);
+    globalThis.expect(sdl).toContain(`@aws_subscribe(mutations: ["MyPlugin_Item_Create"])`);
+    globalThis.expect(sdl).toContain("type CommandAccepted @aws_cognito_user_pools @aws_iam {");
+    globalThis.expect(sdl).not.toContain("@canonical");
+  });
+});
+
+globalThis.describe("AppSync_Adapter.waitForMergeSuccess", () => {
+  let makeFakeClient = responses => {
+    let i = {
+      contents: 0
+    };
+    return {
+      send: _cmd => {
+        let idx = Math.min(i.contents, responses.length - 1 | 0);
+        i.contents = i.contents + 1 | 0;
+        return Promise.resolve(responses[idx]);
+      }
+    };
+  };
+  globalThis.test("resolves once the association reports MERGE_SUCCESS", async () => {
+    let client = makeFakeClient([
+      {
+        sourceApiAssociation: {
+          sourceApiAssociationStatus: "MERGE_SCHEDULED",
+          sourceApiAssociationStatusDetail: undefined
+        }
+      },
+      {
+        sourceApiAssociation: {
+          sourceApiAssociationStatus: "MERGE_IN_PROGRESS",
+          sourceApiAssociationStatusDetail: undefined
+        }
+      },
+      {
+        sourceApiAssociation: {
+          sourceApiAssociationStatus: "MERGE_SUCCESS",
+          sourceApiAssociationStatusDetail: undefined
+        }
+      }
+    ]);
+    return await AppSync_Adapter$ReventlessAws.waitForMergeSuccess(client, "assoc-1", "merged-1", undefined, undefined, 1);
+  });
+  globalThis.test("throws with the AWS status detail on MERGE_FAILED", async () => {
+    let client = makeFakeClient([{
+        sourceApiAssociation: {
+          sourceApiAssociationStatus: "MERGE_FAILED",
+          sourceApiAssociationStatusDetail: "Unable to resolve conflict on object with name SharedThing.x"
+        }
+      }]);
+    let message = "";
+    try {
+      await AppSync_Adapter$ReventlessAws.waitForMergeSuccess(client, "assoc-1", "merged-1", undefined, undefined, 1);
+    } catch (raw_exn) {
+      let exn = Primitive_exceptions.internalToException(raw_exn);
+      message = Stdlib_Option.getOr(Stdlib_Option.flatMap(Stdlib_JsExn.fromException(exn), Stdlib_JsExn.message), "(no message)");
+    }
+    globalThis.expect(message).toContain("MERGE_FAILED");
+    globalThis.expect(message).toContain("SharedThing.x");
+  });
+  globalThis.test("times out after maxAttempts on a status that never settles", async () => {
+    let client = makeFakeClient([{
+        sourceApiAssociation: {
+          sourceApiAssociationStatus: "MERGE_IN_PROGRESS",
+          sourceApiAssociationStatusDetail: undefined
+        }
+      }]);
+    let message = "";
+    try {
+      await AppSync_Adapter$ReventlessAws.waitForMergeSuccess(client, "assoc-1", "merged-1", 2, undefined, 1);
+    } catch (raw_exn) {
+      let exn = Primitive_exceptions.internalToException(raw_exn);
+      message = Stdlib_Option.getOr(Stdlib_Option.flatMap(Stdlib_JsExn.fromException(exn), Stdlib_JsExn.message), "(no message)");
+    }
+    globalThis.expect(message).toContain("timed out");
+    globalThis.expect(message).toContain("MERGE_IN_PROGRESS");
+  });
+});
+
 export {
   decodeFragment,
 }

package/tests/AppSync_SdlDecorateTest.res

@@ -67,10 +67,10 @@ describe("AppSync_SdlDecorate.injectAwsSubscribe", () => {
   })
 })
 
-describe("AppSync_Adapter.stitchWithAwsDirectives", () => {
-  testSync("assembles neutral fragments into AWS-dialect SDL", () => {
-    let baseFragment = ReventlessCore.GraphQL_Stitcher.encode({
-      types: [],
+describe("AppSync_Adapter.stitchStandaloneWithAwsDirectives", () => {
+  testSync("assembles a neutral fragment into an AWS-dialect standalone document", () => {
+    let fragment = ReventlessCore.GraphQL_Stitcher.encode({
+      types: [`type PluginStatusChangeEvent {\n  pluginId: ID!\n}`],
       mutations: [`  Platform_PluginStatusChanged(pluginId: ID!, status: PluginStatus!): PluginStatusChangeEvent`],
       queries: [],
       subscriptions: [`  onPluginStatusChange: PluginStatusChangeEvent`],
@@ -78,19 +78,11 @@ describe("AppSync_Adapter.stitchWithAwsDirectives", () => {
         {field: "onPluginStatusChange", mutations: ["Platform_PluginStatusChanged"]},
       ],
     })
-    let pluginFragment = ReventlessCore.GraphQL_Stitcher.encode({
-      types: [`type PluginStatusChangeEvent {\n  pluginId: ID!\n}`],
-      mutations: [`  Catalog_AddProduct(input: AddInput): CommandResult`],
-      queries: [],
-      subscriptions: [`  onCatalog_AddProduct(id: ID): CommandResult`],
-      subscriptionSources: [{field: "onCatalog_AddProduct", mutations: ["Catalog_AddProduct"]}],
-    })
-    let sdl = AppSync_Adapter.stitchWithAwsDirectives(
-      ~baseFragment,
-      ~pluginFragments=[pluginFragment],
-    )
+    let sdl = AppSync_Adapter.stitchStandaloneWithAwsDirectives(~fragment)
     expect(sdl)->toContain(`@aws_subscribe(mutations: ["Platform_PluginStatusChanged"])`)
-    expect(sdl)->toContain(`@aws_subscribe(mutations: ["Catalog_AddProduct"])`)
+    // Standalone documents never carry the global node query (dropped on AWS —
+    // see the merged-api plan's Relay node resolution).
+    expect(sdl)->not_->toContain("node(id: ID!): Node")
   })
 })
 
@@ -126,82 +118,37 @@ describe("AppSync_SdlDecorate.injectAwsAuthAll", () => {
   })
 })
 
-describe("AppSync_SdlDecorate.planAwsPushes", () => {
-  // Neutral admin base: a system-callable mutation + a shared traversal type.
-  let rawAdminBase = ReventlessCore.GraphQL_Stitcher.encode({
-    types: [`type CommandAccepted {\n  id: ID!\n}`],
-    mutations: [`  Platform_RegisterApiFragment(input: ApiFragmentInput): CommandResult`],
-    queries: [],
-    subscriptions: [],
-    subscriptionSources: [],
-  })
-  let iamFieldNames = ["Platform_RegisterApiFragment"]
-  let mkFrag = (~mutation, ~target): AppSync_SdlDecorate.targetedFragmentInput => {
-    encoded: ReventlessCore.GraphQL_Stitcher.encode({
-      types: [],
-      mutations: [mutation],
-      queries: [],
-      subscriptions: [],
-      subscriptionSources: [],
-    }).encoded,
-    protocol: "graphql",
-    target,
-  }
-  let platformFrag = mkFrag(~mutation=`  Inspector_Ping: CommandResult`, ~target="Platform")
-  let domainFrag = mkFrag(~mutation=`  Catalog_AddProduct(input: AddInput): CommandResult`, ~target="Domain")
-
-  testSync("split mode: Platform API carries admin base (dual-auth) + Platform frags; Domain API excludes the admin base", () => {
-    let plans = AppSync_SdlDecorate.planAwsPushes(
-      ~rawAdminBase,
-      ~iamFieldNames,
-      ~fragments=[platformFrag, domainFrag],
-      ~splitApi=true,
-    )
-    expect(plans->Array.length)->toBe(2)
-    let platformPlan = plans->Array.find(p => p.api == "PlatformApi")->Option.getOrThrow
-    let domainPlan = plans->Array.find(p => p.api == "DomainApi")->Option.getOrThrow
-    // Admin base mutation lands on the Platform API with dual-auth (system caller).
-    expect(platformPlan.sdl)->toContain("Platform_RegisterApiFragment")
-    expect(platformPlan.sdl)->toContain(`@aws_cognito_user_pools(cognito_groups: ["Admin"]) @aws_iam`)
-    // Platform-target plugin field present on the Platform API.
-    expect(platformPlan.sdl)->toContain("Inspector_Ping")
-    // Shared traversal type stamped once on the assembled SDL.
-    expect(platformPlan.sdl)->toContain(`type CommandAccepted @aws_cognito_user_pools @aws_iam {`)
-    // Domain-target field on the Domain API; admin base absent (empty base in split mode).
-    expect(domainPlan.sdl)->toContain("Catalog_AddProduct")
-    expect(domainPlan.sdl->String.includes("Platform_RegisterApiFragment"))->toBe(false)
-  })
 
-  testSync("unified mode: a single Domain API carries admin base + all frags", () => {
-    let plans = AppSync_SdlDecorate.planAwsPushes(
-      ~rawAdminBase,
-      ~iamFieldNames,
-      ~fragments=[platformFrag, domainFrag],
-      ~splitApi=false,
-    )
-    expect(plans->Array.length)->toBe(1)
-    let plan = plans->Array.getUnsafe(0)
-    expect(plan.api)->toBe("DomainApi")
-    expect(plan.sdl)->toContain("Platform_RegisterApiFragment")
-    expect(plan.sdl)->toContain("Inspector_Ping")
-    expect(plan.sdl)->toContain("Catalog_AddProduct")
+describe("AppSync_SdlDecorate.stampSharedIamTypes", () => {
+  testSync("stamps the CommandResult members", () => {
+    let sdl = AppSync_SdlDecorate.stampSharedIamTypes("type CommandAccepted {\n  id: ID!\n}")
+    expect(sdl)->toContain("type CommandAccepted @aws_cognito_user_pools @aws_iam {")
   })
 })
 
-describe("AppSync_SdlDecorate.stampSharedIamTypes", () => {
-  // Regression: the deploy waiter polls the IAM-callable Platform_ApiFragments query via
-  // SigV4; its return type Platform_ApiFragmentEntry must carry the type-level @aws_iam or
-  // the SigV4 caller reaches the query field but gets "Not Authorized to access <field> on
-  // type Platform_ApiFragmentEntry" (deploy validation #7).
-  testSync("stamps Platform_ApiFragmentEntry with dual-auth", () => {
-    let sdl = AppSync_SdlDecorate.stampSharedIamTypes(
-      "type Platform_ApiFragmentEntry {\n  pluginId: String!\n  pushStatus: String!\n}",
+describe("AppSync_SdlDecorate.stampCanonicalTypes", () => {
+  testSync("stamps shared object types, the Node interface, and the CommandResult union", () => {
+    let sdl = AppSync_SdlDecorate.stampCanonicalTypes(
+      "interface Node {\n  id: ID!\n}\n\ntype PageInfo {\n  hasNextPage: Boolean!\n}\n\nunion CommandResult = CommandAccepted | CommandRejected | CommandPending\n\ntype CommandAccepted {\n  msgId: ID!\n}",
     )
-    expect(sdl)->toContain("type Platform_ApiFragmentEntry @aws_cognito_user_pools @aws_iam {")
+    expect(sdl)->toContain("interface Node @canonical {")
+    expect(sdl)->toContain("type PageInfo @canonical {")
+    expect(sdl)->toContain("union CommandResult @canonical = CommandAccepted")
+    expect(sdl)->toContain("type CommandAccepted @canonical {")
   })
 
-  testSync("still stamps the CommandResult members", () => {
-    let sdl = AppSync_SdlDecorate.stampSharedIamTypes("type CommandAccepted {\n  id: ID!\n}")
-    expect(sdl)->toContain("type CommandAccepted @aws_cognito_user_pools @aws_iam {")
+  testSync("composes after stampSharedIamTypes and leaves other types alone", () => {
+    let sdl =
+      AppSync_SdlDecorate.stampSharedIamTypes(
+        "type PageInfo {\n  hasNextPage: Boolean!\n}\n\ntype Product {\n  id: ID!\n}",
+      )->AppSync_SdlDecorate.stampCanonicalTypes
+    expect(sdl)->toContain("type PageInfo @aws_cognito_user_pools @aws_iam @canonical {")
+    expect(sdl)->toContain("type Product {")
+    expect(sdl->String.includes("type Product @canonical"))->toBe(false)
+  })
+
+  testSync("is idempotent", () => {
+    let once = AppSync_SdlDecorate.stampCanonicalTypes("type PageInfo {\n  x: Int\n}")
+    expect(AppSync_SdlDecorate.stampCanonicalTypes(once))->toBe(once)
   })
 })