@reventlessdev/reventless-core 3.0.0-alpha.165 → 3.0.0-alpha.167

package/tests/api/GraphQL_StitcherTest.res

@@ -1,204 +1,6 @@
 open JestGlobals
 open GraphQL_Stitcher
 
-// A representative stitched schema: admin base (Platform_*) plus two domain
-// plugins (Catalog_*, Ordering_*). 4 Mutation + 4 Query root fields.
-let fullSchemaSdl = `type Node {
-  id: ID!
-}
-
-type Query {
-  node(id: ID!): Node
-  Platform_plugins: [Plugin]
-  Catalog_products: [Product]
-  Ordering_orders: [Order]
-}
-
-type Mutation {
-  Platform_connectPlugin(input: ConnectInput): ConnectResult
-  Catalog_addProduct(input: AddInput): Product
-  Catalog_updateProduct(input: UpdateInput): Product
-  Ordering_placeOrder(input: OrderInput): Order
-}`
-
-// The exact failure observed in alpha: a lifecycle window collapses the live
-// schema back to admin-base only — every Catalog_*/Ordering_* field gone.
-// 1 Mutation + 2 Query root fields.
-let collapsedSchemaSdl = `type Node {
-  id: ID!
-}
-
-type Query {
-  node(id: ID!): Node
-  Platform_plugins: [Plugin]
-}
-
-type Mutation {
-  Platform_connectPlugin(input: ConnectInput): ConnectResult
-}`
-
-// Real stitched shape: injectAwsAuthAll appends @aws_auth on its own indented
-// line after each Mutation field, so a field spans two physical lines.
-let authAnnotatedSdl = `type Mutation {
-  Platform_connectPlugin(input: ConnectInput): ConnectResult
-    @aws_auth(cognito_groups: ["Admin"])
-  Catalog_addProduct(input: AddInput): Product
-    @aws_auth(cognito_groups: ["User"])
-}
-
-type Query {
-  node(id: ID!): Node @aws_auth(cognito_groups: ["Admin"])
-}`
-
-describe("GraphQL_Stitcher.countRootTypeFields", () => {
-  testSync("counts Mutation fields", () => {
-    expect(countRootTypeFields(~sdl=fullSchemaSdl, ~typeName="Mutation"))->toBe(4)
-  })
-  testSync("counts Query fields", () => {
-    expect(countRootTypeFields(~sdl=fullSchemaSdl, ~typeName="Query"))->toBe(4)
-  })
-  testSync("ignores @aws_auth directive lines, counts each Mutation field once", () => {
-    expect(countRootTypeFields(~sdl=authAnnotatedSdl, ~typeName="Mutation"))->toBe(2)
-  })
-  testSync("ignores @aws_auth directive lines, counts each Query field once", () => {
-    expect(countRootTypeFields(~sdl=authAnnotatedSdl, ~typeName="Query"))->toBe(1)
-  })
-  testSync("missing type returns 0", () => {
-    expect(countRootTypeFields(~sdl=fullSchemaSdl, ~typeName="Subscription"))->toBe(0)
-  })
-  testSync("empty SDL returns 0", () => {
-    expect(countRootTypeFields(~sdl="", ~typeName="Mutation"))->toBe(0)
-  })
-})
-
-describe("GraphQL_Stitcher.isCatastrophicSchemaShrink", () => {
-  testSync("rejects the all-disconnected collapse (8 → 3 root fields, < 50%)", () => {
-    expect(
-      isCatastrophicSchemaShrink(~currentSdl=fullSchemaSdl, ~newSdl=collapsedSchemaSdl, ~threshold=0.5),
-    )->toBe(true)
-  })
-  testSync("allows an intentional small removal above threshold (8 → 7)", () => {
-    let minusOneSdl = `type Query {
-  node(id: ID!): Node
-  Platform_plugins: [Plugin]
-  Catalog_products: [Product]
-  Ordering_orders: [Order]
-}
-
-type Mutation {
-  Platform_connectPlugin(input: ConnectInput): ConnectResult
-  Catalog_addProduct(input: AddInput): Product
-  Ordering_placeOrder(input: OrderInput): Order
-}`
-    expect(
-      isCatastrophicSchemaShrink(~currentSdl=fullSchemaSdl, ~newSdl=minusOneSdl, ~threshold=0.5),
-    )->toBe(false)
-  })
-  testSync("allows the first push when there is no live schema to protect", () => {
-    expect(
-      isCatastrophicSchemaShrink(~currentSdl="", ~newSdl=fullSchemaSdl, ~threshold=0.5),
-    )->toBe(false)
-  })
-  testSync("allows an unchanged re-push (same SDL)", () => {
-    expect(
-      isCatastrophicSchemaShrink(~currentSdl=fullSchemaSdl, ~newSdl=fullSchemaSdl, ~threshold=0.5),
-    )->toBe(false)
-  })
-  testSync("allows a purely additive push even below threshold cardinality", () => {
-    // A tiny live schema growing into a big one drops nothing → never a clobber,
-    // regardless of the ratio.
-    expect(
-      isCatastrophicSchemaShrink(~currentSdl=collapsedSchemaSdl, ~newSdl=fullSchemaSdl, ~threshold=0.5),
-    )->toBe(false)
-  })
-  testSync("includes Subscription fields when judging a shrink", () => {
-    let withSubs = `type Query {
-  node(id: ID!): Node
-}
-
-type Mutation {
-  Ordering_placeOrder(input: OrderInput): Order
-}
-
-type Subscription {
-  onOrdering_Customer_Register: Customer
-  onOrdering_Customer_UpdateAddress: Customer
-  onCatalog_Product_Added: Product
-}`
-    // Dropping every Subscription field (and keeping Mutation/Query) is a shrink
-    // the Mutation+Query-only guard would have missed.
-    let subsGone = `type Query {
-  node(id: ID!): Node
-}
-
-type Mutation {
-  Ordering_placeOrder(input: OrderInput): Order
-}`
-    expect(
-      isCatastrophicSchemaShrink(~currentSdl=withSubs, ~newSdl=subsGone, ~threshold=0.5),
-    )->toBe(true)
-  })
-})
-
-describe("GraphQL_Stitcher.rootTypeFieldNames", () => {
-  testSync("lists Mutation field names", () => {
-    expect(rootTypeFieldNames(~sdl=fullSchemaSdl, ~typeName="Mutation"))->toEqual([
-      "Platform_connectPlugin",
-      "Catalog_addProduct",
-      "Catalog_updateProduct",
-      "Ordering_placeOrder",
-    ])
-  })
-  testSync("strips args and @aws_auth directive lines", () => {
-    expect(rootTypeFieldNames(~sdl=authAnnotatedSdl, ~typeName="Mutation"))->toEqual([
-      "Platform_connectPlugin",
-      "Catalog_addProduct",
-    ])
-  })
-  testSync("missing type returns []", () => {
-    expect(rootTypeFieldNames(~sdl=fullSchemaSdl, ~typeName="Subscription"))->toEqual([])
-  })
-})
-
-describe("GraphQL_Stitcher.missingRootFields", () => {
-  testSync("reports plugin fields absent from an admin-base clobber", () => {
-    // The alpha 2026-07-08 clobber: live schema is admin-base only. Every
-    // Catalog_*/Ordering_* field the deploy expects is missing → repair fires.
-    let missing = missingRootFields(~expectedSdl=fullSchemaSdl, ~liveSdl=collapsedSchemaSdl)
-    expect(missing->Array.includes("Catalog_addProduct"))->toBe(true)
-    expect(missing->Array.includes("Ordering_placeOrder"))->toBe(true)
-    expect(missing->Array.includes("Ordering_orders"))->toBe(true)
-  })
-  testSync("empty when live schema is a superset (intact)", () => {
-    expect(missingRootFields(~expectedSdl=fullSchemaSdl, ~liveSdl=fullSchemaSdl))->toEqual([])
-  })
-  testSync("detects an equal-cardinality field swap the count test misses", () => {
-    // Same number of root fields, but one Mutation field replaced by a foreign
-    // one — a swap. countRootTypeFields would report no drift; the name-set diff
-    // catches it.
-    let swapped = `type Query {
-  node(id: ID!): Node
-  Platform_plugins: [Plugin]
-  Catalog_products: [Product]
-  Ordering_orders: [Order]
-}
-
-type Mutation {
-  Platform_connectPlugin(input: ConnectInput): ConnectResult
-  Catalog_addProduct(input: AddInput): Product
-  Catalog_updateProduct(input: UpdateInput): Product
-  Foreign_strayField(input: OrderInput): Order
-}`
-    // Same count on both sides.
-    expect(countRootTypeFields(~sdl=swapped, ~typeName="Mutation"))->toBe(
-      countRootTypeFields(~sdl=fullSchemaSdl, ~typeName="Mutation"),
-    )
-    // But the expected Ordering_placeOrder is missing from the live (swapped) schema.
-    let missing = missingRootFields(~expectedSdl=fullSchemaSdl, ~liveSdl=swapped)
-    expect(missing->Array.includes("Ordering_placeOrder"))->toBe(true)
-  })
-})
-
 describe("GraphQL_Stitcher.subscriptionSources", () => {
   testSync("encode/decode round-trips the subscription→mutation source mapping", () => {
     let fragment = encode({
@@ -261,3 +63,35 @@ describe("GraphQL_Stitcher.subscriptionSources", () => {
     expect(fields->Array.includes("onPluginStatusChange"))->toBe(true)
   })
 })
+
+describe("GraphQL_Stitcher.stitchStandalone", () => {
+  let pluginFragment = encode({
+    types: [
+      `type Product implements Node {\n  id: ID!\n  name: String\n}`,
+      `union CommandResult = CommandAccepted | CommandRejected | CommandPending`,
+    ],
+    mutations: [`  Catalog_AddProduct(input: AddInput): CommandResult`],
+    queries: [`  Catalog_products: [Product]`],
+    subscriptions: [`  onCatalog_AddProduct(id: ID): CommandResult`],
+    subscriptionSources: [{field: "onCatalog_AddProduct", mutations: ["Catalog_AddProduct"]}],
+  })
+
+  testSync("renders a self-contained subgraph document with relay base types", () => {
+    let sdl = stitchStandalone(~fragment=pluginFragment)
+    expect(sdl)->toContain("interface Node {")
+    expect(sdl)->toContain("type PageInfo {")
+    expect(sdl)->toContain("type Product implements Node {")
+    expect(sdl)->toContain("Catalog_AddProduct(input: AddInput): CommandResult")
+    expect(sdl)->toContain("onCatalog_AddProduct(id: ID): CommandResult")
+  })
+
+  testSync("omits the global node query (the canonical base document owns it)", () => {
+    let sdl = stitchStandalone(~fragment=pluginFragment)
+    expect(sdl->String.includes("node(id: ID!): Node"))->toBe(false)
+  })
+
+  testSync("stitch keeps injecting the global node query (whole-schema path unchanged)", () => {
+    let sdl = stitch(~baseFragment=pluginFragment, ~pluginFragments=[])
+    expect(sdl)->toContain("node(id: ID!): Node")
+  })
+})

package/tests/api/GraphQL_StitcherTest.res.mjs

@@ -240,6 +240,38 @@ globalThis.describe("GraphQL_Stitcher.subscriptionSources", () => {
   });
 });
 
+globalThis.describe("GraphQL_Stitcher.stitchStandalone", () => {
+  let pluginFragment = GraphQL_Stitcher$ReventlessCore.encode({
+    types: [
+      `type Product implements Node {\n  id: ID!\n  name: String\n}`,
+      `union CommandResult = CommandAccepted | CommandRejected | CommandPending`
+    ],
+    mutations: [`  Catalog_AddProduct(input: AddInput): CommandResult`],
+    queries: [`  Catalog_products: [Product]`],
+    subscriptions: [`  onCatalog_AddProduct(id: ID): CommandResult`],
+    subscriptionSources: [{
+        field: "onCatalog_AddProduct",
+        mutations: ["Catalog_AddProduct"]
+      }]
+  });
+  globalThis.test("renders a self-contained subgraph document with relay base types", () => {
+    let sdl = GraphQL_Stitcher$ReventlessCore.stitchStandalone(pluginFragment);
+    globalThis.expect(sdl).toContain("interface Node {");
+    globalThis.expect(sdl).toContain("type PageInfo {");
+    globalThis.expect(sdl).toContain("type Product implements Node {");
+    globalThis.expect(sdl).toContain("Catalog_AddProduct(input: AddInput): CommandResult");
+    globalThis.expect(sdl).toContain("onCatalog_AddProduct(id: ID): CommandResult");
+  });
+  globalThis.test("omits the global node query (the canonical base document owns it)", () => {
+    let sdl = GraphQL_Stitcher$ReventlessCore.stitchStandalone(pluginFragment);
+    globalThis.expect(sdl.includes("node(id: ID!): Node")).toBe(false);
+  });
+  globalThis.test("stitch keeps injecting the global node query (whole-schema path unchanged)", () => {
+    let sdl = GraphQL_Stitcher$ReventlessCore.stitch(pluginFragment, []);
+    globalThis.expect(sdl).toContain("node(id: ID!): Node");
+  });
+});
+
 export {
   fullSchemaSdl,
   collapsedSchemaSdl,

package/src/admin/ApiFragmentRegistry/ApiFragmentRegistryBehavior.res

@@ -1,108 +0,0 @@
-@@reventless.behavior(ApiFragmentRegistrySpec)
-
-// NOTE: no `open Reventless.Plugin` — it would shadow the `encoded`/`protocol` labels reused
-// below when building the fragment snapshot (warning 45). The two Plugin types are qualified.
-
-// The current fragment for a plugin name plus its target API and the last recorded push
-// outcome (kept only to dedupe at-least-once redelivery of RecordApiFragmentPush).
-type registryEntry = {
-  fragment: Reventless.Plugin.apiSchemaFragment,
-  apiTarget: Reventless.Plugin.apiTarget,
-  lastPush: option<(bool, string, string)>, // (ok, message, at)
-}
-
-// Singleton aggregate: the WHOLE registry, keyed by pluginId, in one consistency boundary.
-type state = {entries: dict<registryEntry>}
-
-let initialState = {entries: Dict.make()}
-
-// Framework-internal aggregate outside an Aggregate/ folder — the Behavior.T snapshot/counter
-// fields are satisfied manually (mirrors PluginBehavior). The registry's history is short
-// (deploy-frequency writes), so persisted snapshots would buy nothing.
-let snapshot = None
-let atomicCounter = None
-
-// Immutable dict updates (no reliance on Dict.copy/Dict.delete): rebuild via toArray/fromArray
-// so evolve never mutates the replayed state.
-let entriesWith = (entries: dict<registryEntry>, pluginId, entry) =>
-  entries
-  ->Dict.toArray
-  ->Array.filter(((k, _)) => k != pluginId)
-  ->Array.concat([(pluginId, entry)])
-  ->Dict.fromArray
-
-let entriesWithout = (entries: dict<registryEntry>, pluginId) =>
-  entries->Dict.toArray->Array.filter(((k, _)) => k != pluginId)->Dict.fromArray
-
-let evolve = (state, event) =>
-  switch event {
-  | ApiFragmentRegistered({pluginId, fragment, apiTarget}) => {
-      entries: state.entries->entriesWith(pluginId, {fragment, apiTarget, lastPush: None}),
-    }
-  | ApiFragmentUpdated({pluginId, newFragment, apiTarget}) => {
-      entries: state.entries->entriesWith(pluginId, {fragment: newFragment, apiTarget, lastPush: None}),
-    }
-  | ApiFragmentDeregistered({pluginId}) => {entries: state.entries->entriesWithout(pluginId)}
-  | ApiFragmentPushRecorded({pluginId, ok, message, at}) =>
-    switch state.entries->Dict.get(pluginId) {
-    | Some(entry) => {
-        entries: state.entries->entriesWith(pluginId, {...entry, lastPush: Some((ok, message, at))}),
-      }
-    | None => state
-    }
-  // Derived echo — no fold change.
-  | ApiSchemaComputed(_) => state
-  }
-
-// The consistent registry snapshot AFTER the triggering change — one entry per registered plugin.
-let snapshotOf = (entries: dict<registryEntry>): array<ApiFragmentRegistrySpec.fragmentSnapshotEntry> =>
-  entries
-  ->Dict.toArray
-  ->Array.map(((pluginId, e)) => {
-    ApiFragmentRegistrySpec.pluginId,
-    encoded: e.fragment.encoded,
-    protocol: e.fragment.protocol,
-    apiTarget: e.apiTarget,
-  })
-
-// Emit the fact event plus ApiSchemaComputed{snapshot} folded from the POST-change state, so the
-// reactive push SideEffect stitches from consistent state. Idempotent no-ops emit nothing (and
-// therefore no push). RecordApiFragmentPush records the outcome only — it changes no fragments,
-// so it emits no ApiSchemaComputed (which also avoids a recompute loop).
-let decide = (state, command) => {
-  let withSchema = (fact: ApiFragmentRegistrySpec.event) => {
-    let next = evolve(state, fact)
-    Ok([fact, ApiSchemaComputed({snapshot: snapshotOf(next.entries)})])
-  }
-  switch command {
-  | RegisterApiFragment({pluginId, fragment, apiTarget, at}) =>
-    switch state.entries->Dict.get(pluginId) {
-    | None => withSchema(ApiFragmentRegistered({pluginId, fragment, apiTarget, at}))
-    // Idempotent: an unchanged re-registration (same fragment AND same target — a redeploy
-    // carrying the same schema, or a version supersession that didn't change the SDL) emits
-    // nothing. A target change with an identical fragment IS meaningful (the fields move between
-    // the Domain and Platform APIs), so it is not a no-op.
-    | Some({fragment: current, apiTarget: currentTarget})
-      if current == fragment && currentTarget == apiTarget =>
-      Ok([])
-    | Some({fragment: current}) =>
-      withSchema(
-        ApiFragmentUpdated({pluginId, previousFragment: current, newFragment: fragment, apiTarget, at}),
-      )
-    }
-  | DeregisterApiFragment({pluginId}) =>
-    switch state.entries->Dict.get(pluginId) {
-    | None => Ok([]) // idempotent — nothing registered
-    | Some(_) => withSchema(ApiFragmentDeregistered({pluginId: pluginId}))
-    }
-  | RecordApiFragmentPush({pluginId, ok, message, at}) =>
-    switch state.entries->Dict.get(pluginId) {
-    | None => Ok([]) // fragment deregistered in the meantime — nowhere to record
-    // Idempotent: an at-least-once redelivery carries the identical payload.
-    | Some({lastPush: Some((lastOk, lastMessage, lastAt))})
-      if lastOk == ok && lastMessage == message && lastAt == at =>
-      Ok([])
-    | Some(_) => Ok([ApiFragmentPushRecorded({pluginId, ok, message, at})])
-    }
-  }
-}

package/src/admin/ApiFragmentRegistry/ApiFragmentRegistryBehavior.res.mjs

@@ -1,190 +0,0 @@
-// Generated by ReScript, PLEASE EDIT WITH CARE
-
-import * as Primitive_object from "@rescript/runtime/lib/es6/Primitive_object.js";
-
-let initialState = {
-  entries: {}
-};
-
-function entriesWith(entries, pluginId, entry) {
-  return Object.fromEntries(Object.entries(entries).filter(param => param[0] !== pluginId).concat([[
-      pluginId,
-      entry
-    ]]));
-}
-
-function entriesWithout(entries, pluginId) {
-  return Object.fromEntries(Object.entries(entries).filter(param => param[0] !== pluginId));
-}
-
-function evolve(state, event) {
-  switch (event.TAG) {
-    case "ApiFragmentRegistered" :
-      return {
-        entries: entriesWith(state.entries, event.pluginId, {
-          fragment: event.fragment,
-          apiTarget: event.apiTarget,
-          lastPush: undefined
-        })
-      };
-    case "ApiFragmentUpdated" :
-      return {
-        entries: entriesWith(state.entries, event.pluginId, {
-          fragment: event.newFragment,
-          apiTarget: event.apiTarget,
-          lastPush: undefined
-        })
-      };
-    case "ApiFragmentDeregistered" :
-      return {
-        entries: entriesWithout(state.entries, event.pluginId)
-      };
-    case "ApiFragmentPushRecorded" :
-      let pluginId = event.pluginId;
-      let entry = state.entries[pluginId];
-      if (entry !== undefined) {
-        return {
-          entries: entriesWith(state.entries, pluginId, {
-            fragment: entry.fragment,
-            apiTarget: entry.apiTarget,
-            lastPush: [
-              event.ok,
-              event.message,
-              event.at
-            ]
-          })
-        };
-      } else {
-        return state;
-      }
-    case "ApiSchemaComputed" :
-      return state;
-  }
-}
-
-function snapshotOf(entries) {
-  return Object.entries(entries).map(param => {
-    let e = param[1];
-    return {
-      pluginId: param[0],
-      encoded: e.fragment.encoded,
-      protocol: e.fragment.protocol,
-      apiTarget: e.apiTarget
-    };
-  });
-}
-
-function decide(state, command) {
-  let withSchema = fact => {
-    let next = evolve(state, fact);
-    return {
-      TAG: "Ok",
-      _0: [
-        fact,
-        {
-          TAG: "ApiSchemaComputed",
-          snapshot: snapshotOf(next.entries)
-        }
-      ]
-    };
-  };
-  switch (command.TAG) {
-    case "RegisterApiFragment" :
-      let at = command.at;
-      let apiTarget = command.apiTarget;
-      let fragment = command.fragment;
-      let pluginId = command.pluginId;
-      let match = state.entries[pluginId];
-      if (match === undefined) {
-        return withSchema({
-          TAG: "ApiFragmentRegistered",
-          pluginId: pluginId,
-          fragment: fragment,
-          apiTarget: apiTarget,
-          at: at
-        });
-      }
-      let current = match.fragment;
-      if (Primitive_object.equal(current, fragment) && match.apiTarget === apiTarget) {
-        return {
-          TAG: "Ok",
-          _0: []
-        };
-      } else {
-        return withSchema({
-          TAG: "ApiFragmentUpdated",
-          pluginId: pluginId,
-          previousFragment: current,
-          newFragment: fragment,
-          apiTarget: apiTarget,
-          at: at
-        });
-      }
-    case "DeregisterApiFragment" :
-      let pluginId$1 = command.pluginId;
-      let match$1 = state.entries[pluginId$1];
-      if (match$1 !== undefined) {
-        return withSchema({
-          TAG: "ApiFragmentDeregistered",
-          pluginId: pluginId$1
-        });
-      } else {
-        return {
-          TAG: "Ok",
-          _0: []
-        };
-      }
-    case "RecordApiFragmentPush" :
-      let at$1 = command.at;
-      let message = command.message;
-      let ok = command.ok;
-      let pluginId$2 = command.pluginId;
-      let match$2 = state.entries[pluginId$2];
-      if (match$2 === undefined) {
-        return {
-          TAG: "Ok",
-          _0: []
-        };
-      }
-      let match$3 = match$2.lastPush;
-      if (match$3 !== undefined && match$3[0] === ok && match$3[1] === message && match$3[2] === at$1) {
-        return {
-          TAG: "Ok",
-          _0: []
-        };
-      }
-      return {
-        TAG: "Ok",
-        _0: [{
-            TAG: "ApiFragmentPushRecorded",
-            pluginId: pluginId$2,
-            ok: ok,
-            message: message,
-            at: at$1
-          }]
-      };
-      break;
-  }
-}
-
-let Spec;
-
-let snapshot;
-
-let atomicCounter;
-
-let moduleUrl = "@reventlessdev/reventless-core/src/admin/ApiFragmentRegistry/ApiFragmentRegistryBehavior.res.mjs";
-
-export {
-  Spec,
-  initialState,
-  snapshot,
-  atomicCounter,
-  entriesWith,
-  entriesWithout,
-  evolve,
-  snapshotOf,
-  decide,
-  moduleUrl,
-}
-/* No side effect */

package/src/admin/ApiFragmentRegistry/ApiFragmentRegistrySpec.res

@@ -1,71 +0,0 @@
-// ApiFragmentRegistry aggregate — the platform API-schema fragment registry, replacing the
-// raw `deploy-schema:*` keyspace (see docs/plans/event-sourced-fragment-registries.md).
-//
-// Modelled as a SINGLETON aggregate (fixed id, e.g. "registry"): the whole registry lives in
-// one consistency boundary / one event stream, so a fragment change reads the whole registry
-// with a single strongly-consistent partition read + snapshot — fixing the lagging-read
-// consistency AND the unbounded-scan cost of the earlier per-plugin DCB-slice design (deploy
-// validation #4). `pluginId` is a payload field here, not the aggregate id.
-//
-// Transitions are driven by the DEPLOY / DESTROY of a plugin stack: the deploy registers its
-// fragment as a SigV4 system caller against the Platform API, and only final retirement
-// (`pulumi destroy`, resolvers gone) deregisters. Version supersession must NOT deregister —
-// the registry is keyed by plugin NAME, so a successor's deploy overwrites its predecessor's
-// fragment in place. The registry is idempotent: re-registering an identical fragment is a
-// no-op, deregistering an absent fragment is a no-op — it never rejects a command.
-//
-// `RecordApiFragmentPush` is the write-back of the reactive schema-push SideEffect: after
-// stitching and pushing the composed schema it records the outcome (ok / error + message) on
-// the row of the plugin whose fragment change triggered the push, so the deploy waiter can
-// poll the push status instead of timing out on introspection. It is `@noApi` — dispatched
-// platform-side, never by a GraphQL caller.
-@@reventless.spec("ApiFragmentRegistry")
-
-open Reventless.Plugin
-
-// One entry of the consistent registry snapshot carried on `ApiSchemaComputed` — the whole
-// per-plugin fragment set AFTER the triggering change, folded from the aggregate's own
-// consistent state. The push SideEffect stitches per target from this snapshot (splitApi +
-// admin base are its deploy concerns), so consistency is guaranteed without any
-// eventually-consistent read.
-@schema
-type fragmentSnapshotEntry = {
-  pluginId: string,
-  encoded: string,
-  protocol: string,
-  apiTarget: apiTarget,
-}
-
-// `RegisterApiFragment` / `DeregisterApiFragment` ARE the GraphQL surface — the deploy calls
-// them as a SigV4 system caller against the Platform API (exposed via the standard admin-aggregate
-// path as `Platform_RegisterApiFragment` / `Platform_DeregisterApiFragment`; IAM via
-// `systemCallerFieldNames`). `at` is the registration timestamp, threaded so the read-model row
-// can surface registered/updated times.
-@schema
-type command =
-  | RegisterApiFragment({pluginId: string, fragment: apiSchemaFragment, apiTarget: apiTarget, at: string})
-  | DeregisterApiFragment({pluginId: string})
-  | @noApi RecordApiFragmentPush({pluginId: string, ok: bool, message: string, at: string})
-
-// The registry never rejects (idempotent register/deregister/record); this variant is never
-// returned.
-@schema
-type error = | RegistryError
-
-@schema
-type event =
-  | ApiFragmentRegistered({pluginId: string, fragment: apiSchemaFragment, apiTarget: apiTarget, at: string})
-  | ApiFragmentUpdated({
-      pluginId: string,
-      previousFragment: apiSchemaFragment,
-      newFragment: apiSchemaFragment,
-      apiTarget: apiTarget,
-      at: string,
-    })
-  | ApiFragmentDeregistered({pluginId: string})
-  | ApiFragmentPushRecorded({pluginId: string, ok: bool, message: string, at: string})
-  // Derived echo of the consistent registry contents after a fragment change — the reactive
-  // push SideEffect's trigger. Carries the full per-plugin snapshot so the SideEffect stitches
-  // from consistent state without a read. Does NOT change fold state (evolve ignores it), and
-  // is NOT projected by the ApiFragments read model.
-  | ApiSchemaComputed({snapshot: array<fragmentSnapshotEntry>})