@reventlessdev/reventless-core 3.0.0-alpha.155 → 3.0.0-alpha.157

package/CHANGELOG.md

@@ -3,6 +3,29 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# 3.0.0-alpha.157 (2026-07-12)
+
+### Features
+
+* **admin:** event-source the API fragment registry as admin DCB slices (Phase 2b) ([3fc40d2](https://github.com/ReventlessDev/reventless-core/commit/3fc40d247c54bf66ed84d625959f08299aa04a98))
+* **admin:** event-source the UI fragment registry as admin DCB slices ([711581e](https://github.com/ReventlessDev/reventless-core/commit/711581e77c626e7d0fc35db8ec351f62a70bd8f2))
+* **admin:** expose the API fragment registry as system-callable mutations (Phase 2d) ([8b1ec49](https://github.com/ReventlessDev/reventless-core/commit/8b1ec49813e67f303bc86d60470c9b95d2a8408e))
+* **admin:** make the API fragment registry per-target (Domain | Platform) ([30491a9](https://github.com/ReventlessDev/reventless-core/commit/30491a9e14b4236c98cc756efb6de68ede1e77d7))
+* **admin:** populate the API fragment registry on connect + status query (Phase 2c) ([106d96c](https://github.com/ReventlessDev/reventless-core/commit/106d96c904e135f8360d53e582f395c107db704a))
+* **admin:** react to ApiFragment* events with a schema single writer (Phase 2e) ([59f9e46](https://github.com/ReventlessDev/reventless-core/commit/59f9e46c154d8ca2a34537974722014fc279de3e))
+* **admin:** retire the Plugin-aggregate UI-fragment path in favour of the registry slices ([1dbc708](https://github.com/ReventlessDev/reventless-core/commit/1dbc708e7439b34ff970cc3d963d7835a8c6fd48))
+* **admin:** serve Platform_UIFragments from the new UiFragmentRegistry slices ([7a47533](https://github.com/ReventlessDev/reventless-core/commit/7a47533acc95977fbeeb6375e94449056b655abc))
+* **api:** neutralize core-emitted SDL — [@aws](https://github.com/aws)_subscribe moves to the AWS adapter (Phase 2a) ([9b27ec8](https://github.com/ReventlessDev/reventless-core/commit/9b27ec8f6ab2b7453b1c50b9891e89781ec3b31a))
+
+
+# 3.0.0-alpha.156 (2026-07-11)
+
+**Note:** Version bump only for package @reventlessdev/reventless-core
+
+
+
+
+
 # 3.0.0-alpha.155 (2026-07-11)
 
 ### Bug Fixes

package/README.md

@@ -1,173 +1,72 @@
-[![npm version](https://img.shields.io/npm/v/@reventlessdev/reventless.svg?label=version)](https://www.npmjs.com/package/@reventlessdev/reventless)
-[![GitHub package version](https://img.shields.io/github/v/release/ReventlessDev/reventless-core?label=release)](https://github.com/ReventlessDev/reventless-core/releases)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Changelog](https://img.shields.io/badge/📋-Changelog-blue)](./CHANGELOG.md)
+[![npm](https://img.shields.io/npm/v/@reventlessdev/reventless-core.svg?label=npm)](https://www.npmjs.com/package/@reventlessdev/reventless-core)
+[![License: Apache-2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+[![Docs](https://img.shields.io/badge/docs-reventless.dev-blue)](https://docs.reventless.dev)
 
-# Reventless
+# @reventlessdev/reventless-core
 
-Reventless is a toolkit for event-sourced CQRS applications on serverless infrastructure written in ReasonML.
+> ⚠️ **Alpha.** APIs and on-disk formats can change without notice between releases.
+> Pin exact versions and expect breaking changes.
 
-It's based on the following technologies:
+The **provider-agnostic core** of [Reventless](https://docs.reventless.dev) — a
+spec-driven, event-sourced CQRS framework written in [ReScript](https://rescript-lang.org).
+This package is the runtime you model your domain against: the type-safe building blocks
+for commands, events, projections, and the behaviors that evolve state — with **no** cloud
+or storage dependency. The provider-specific adapters live in separate packages
+(see [Where it fits](#where-it-fits)).
 
-* [Serverless](https://serverless.com)
-* [ReasonML](https://reasonml.github.io/) using [Bucklescript](https://bucklescript.github.io/)
-* Event-Sourced
-* CQRS
+## What it provides
 
-## Getting started developing Reventless
-### 1. Install Node 12.x (LTS)
-We use `fnm` to manage the locally installed node-version.  
-The currently used/tested node version is stated in the `.node-version` file.
+ReScript modules, consumed by adding the package to your `rescript.json` `dependencies`:
 
-#### [fnm](https://github.com/Schniz/fnm)
-> Fast and simple Node.js version manager, built in native ReasonML
+- **`Message`** — command / event message contracts and their service interface.
+- **`Behavior`** — the write-side behavior spec: event-sourced state transitions
+  (`evolve(state, event) => state`).
+- **`Projection`** / **`ProjectionMapper`** — read models projected from event streams.
+- **`Mapper`** / **`Mapper1toN`** / **`MapperNto1`** — cross-component event translation
+  (encode/decode between a source and a target contract).
+- **`ComponentType`** — the hierarchical component-kind vocabulary.
+- **`PluginRuntimeOperations`** — the provider-agnostic interface a runtime adapter implements.
+- **`RequestContext`** — per-invocation context threaded through the effect pipeline.
+- **`Env`** — environment access.
 
-*Note: Currently this tool has no windows-support and is unlikely to be added in the near future.*
+Domain code written against these modules is provider-agnostic: the same components run
+unchanged on any adapter.
 
-Go to your reventless-directory and execute [`fnm use`](https://github.com/Schniz/fnm#fnm-use-version) in a shell to just set you node version to the one stated in `.node-version`. (maybe you want to set your default node version by calling [`fnm default <version>`](https://github.com/Schniz/fnm#fnm-default-version))
+## Where it fits
 
-### 2. Install BuckleScript (which comes bundled with reason)
-Currently used and supported version is bs-platform 5.2.1.
+`reventless-core` is one package in the Reventless framework. It builds on
+[`@reventlessdev/reventless-spec`](https://www.npmjs.com/package/@reventlessdev/reventless-spec)
+(type specifications) and is paired at runtime with a storage/cloud adapter:
 
-[Reason Docs](https://reasonml.github.io/docs/en/installation)  
-[Unofficial Community Docs](https://reasonml.org/docs/manual/latest/installation)
+- [`@reventlessdev/reventless-aws`](https://www.npmjs.com/package/@reventlessdev/reventless-aws) — AWS (DynamoDB, Lambda, SQS, SNS, S3)
+- [`@reventlessdev/reventless-postgres`](https://www.npmjs.com/package/@reventlessdev/reventless-postgres) — Postgres event log + query DB
+- [`@reventlessdev/reventless-local`](https://www.npmjs.com/package/@reventlessdev/reventless-local) — in-memory / SQLite platform for local dev and tests
 
-The docs suggest to globally install `bs-platform` (by running `npm install -g bs-platform`), but to avoid version-conflicts it's better to just locally install `bs-platform` when needed or run `npx`. Run the following command to install `bs-platform` locally without adding it to `package.json`:
-```
-npm install bs-platform@5.2.1 --no-save
-```
-
-### 3. Install Dependencies
-```
-npm install
-```
-
-### 3. Build Project
-```
-npm run build
-```
-
-Or in development, to run a watcher:
-```
-npm run start
-```
+You normally obtain `reventless-core` transitively by scaffolding an app rather than
+installing it on its own.
 
-If you use Visual Studio Code, use the [reason-vscode](https://marketplace.visualstudio.com/items?itemName=jaredly.reason-vscode) plugin, which auto-builds the project on save by default.
-Otherwise, see https://reasonml.github.io/docs/en/editor-plugins.
+## Install
 
-*Note: Don't run the watcher and use the editor-plugin at the same time, since they may conflict with each other.*
-
-### 4. Test Project
-Run Test-Suite once:
-```
-npm run test
-```
-
-Run Test-Suite continously on file changes:
-```
-npm run dev
+```bash
+pnpm add @reventlessdev/reventless-core
 ```
 
-The Bucklescript bindings for [Jest](https://jestjs.io/) are used as dev-dependency: [bs-jest](https://github.com/glennsl/bs-jest)
-
+Then register it as a ReScript dependency in `rescript.json`:
 
-
-#### Test Example
-This tests the function f in the file/module Try:
-```
-// __tests__/try_test.re
-open Jest
-
-describe("Try should return...", () => {
-    open Expect
-    test("the same text given a count of 0", () => {
-        expect(Try.f("test", 0)) |> toBe("test")
-    })
-
-    test("the text doubled given a count of 1", () => {
-        expect(Try.f("test", 1)) |> toBe("testtest")
-    })
-})
-```
-File Try:
-```
-// src/Try.re
-let rec f = (text: string, count: int) => {
-    if(count <= 0) text
-    else f(text ++ text, count - 1)
+```json
+{
+  "dependencies": ["@reventlessdev/reventless-core"]
 }
 ```
 
-### 5. Deployment
-**TODO: This should be moved to a separate chapter on how to use Reventless in a project.**
-
-Before running `npm run deploy`, make sure to update the `.env` file. (Copy your Pulumi Access Token from your profile preferences into the `.env` file.)
-You also need to set the environment variable like `export AWS_SDK_LOAD_CONFIG=1` and hava a file at `~/.aws/config`:
-```
-[default]
-region = eu-west-1
-output = json
-```
-
-This command will run 3 Shell-Scripts:
-  * `./scripts/pre-deploy.sh`: Move everything in `./node_modules/bs-platform` to a tmp-directory, but the JS-lib
-  * `./scripts/pulumi-up.sh`: Read `PULUMI_ACCESS_TOKEN` and `PULUMI_STACK` from the `.env` file and run `pulumi up` to actually deploy (This script will be only executed, if `pre-deploy` exited successfully.)
-  * `./scripts/post-deploy.sh`: Move `bs-platform` back into place from tmp-directory.
-
-
-**NOTE**: The `./scripts/pulumi-up.sh` exports the environment variable `PULUMI_ACCESS_TOKEN` to make it to the Pulumi CLI available. Export another value and set a `#` before the apropriate line inside`.env` to use another token.
-
-
-## Setup environment for local development of actual project and framework side by side -- DEPRECATED
-
-
-**🚨 We encountered some deployment issues, when using npm link. Therefore we discourage using this technic for the time being❗**
-
-### Setup the new project
-* add a new "deploy key" in [gitlab](https://github.com/atos-austria/reason/reventless/settings/repository/deploy_token/create#js-deploy-tokens)
-* add "private repository" with the new deploy-token to the new project: `"reventless": "git+https://USER-TOKEN:PASSWORD-TOKEN@github.com/atos-austria/reason/reventless.git"`
-* run `npm install` for the new project
-
-### Setup the framework project to use the local version in the new version
-* clone the framework repo into a local directory
-* run `npm link` inside the framework's directory
-* run `npm link reventless` inside the new project's directory
-
-## Go back to using the actual framwork-repo as dependency
-### Unlink
-[Medium Post](https://medium.com/@alexishevia/the-magic-behind-npm-link-d94dcb3a81af)
-
-* run `npm unlink --no-save reventless` in the new project's directory
-* run `npm unlink` in the framework's directory
-
-### Alternative
-[Medium Post](https://medium.com/dailyjs/how-to-use-npm-link-7375b6219557)
-
-* run `npm uninstall --no-save reventless && npm install` inside the new project's directory
-* OPTIONAL: to delete the global symlink of the framework run `npm uninstall` inside the framework's directory
-
-## Ressources
-* [Project Wiki](https://github.com/atos-austria/reason/reventless/wikis/home)
-
-# Coding Guidelines
-
-* `<Component>.Make.createComponent` (binding to `Component.js` constructor): Pass any additional parameters (besides `componentType`, `name`, `opts`) directly to the `construct` function (using partial application), like this: `createComponent(~componentType, ~name, ~construct=construct(~param1, ~param2), ~opts)`
-
-# Code-Smells
-
-## ReasonML
-
-* `...->ignore`
-
-## Pulumi
+Requires ReScript `^12.3.0` (peer dependency).
 
-* `...->Pulumi.Output.apply(_, ...)`
-* `...->Pulumi.Output.all->Pulumi.Output.apply(...)`
-* type `option(Pulumi.Output.t('a))`: Rescript's js option encoding and Pulumi's Output lifting mechanics interact badly! - Therefore, such a type is not possible to use!
+## Links
 
-# Common issues
+- 📚 Documentation — [docs.reventless.dev](https://docs.reventless.dev)
+- 📦 Repository — [ReventlessDev/reventless-core](https://github.com/ReventlessDev/reventless-core)
+- 📋 [Changelog](./CHANGELOG.md)
 
-## `error: Duplicate resource URN 'urn:pulumi:dev::wm-raw::aws:sqs/queue:Queue::FIFODeadLetterQueue'; try giving it a unique name` during deployment
+## License
 
-This error usually occurs due to multiple different versions of `@reventless/reventless` or `@reventless/reventless-aws` being present in the dependencies (npm). To verify, call `npm ls @reventless/reventless` / `npm ls @reventless/reventless-aws` and verify there is only a single version present.
-To fix this use desired ranges in the dependencies definition (package.json) of the project and check upstream version ranges as well. (You can also use `npm why <packageName>` to see where a specific version is coming from.)
+[Apache-2.0](https://opensource.org/licenses/Apache-2.0)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reventlessdev/reventless-core",
-  "version": "3.0.0-alpha.155",
+  "version": "3.0.0-alpha.157",
   "description": "Core package for Reventless framework",
   "license": "Apache-2.0",
   "jest": {
@@ -28,22 +28,22 @@
   "dependencies": {
     "sury": "11.0.0-alpha.4",
     "uuid": "^13.0.0",
-    "@reventlessdev/rescript-effect": "0.1.0-alpha.26",
-    "@reventlessdev/rescript-fast-csv": "1.2.0-alpha.11",
-    "@reventlessdev/rescript-hash-object": "1.2.0-alpha.10",
-    "@reventlessdev/rescript-jest": "1.0.0-alpha.6",
-    "@reventlessdev/rescript-node-streams": "1.1.0-alpha.10",
-    "@reventlessdev/rescript-pulumi-pulumi": "2.3.0-alpha.14",
-    "@reventlessdev/rescript-ssh2": "1.1.0-alpha.11",
-    "@reventlessdev/rescript-uuid": "1.1.0-alpha.14",
-    "@reventlessdev/reventless-infra": "3.0.0-alpha.96",
-    "@reventlessdev/reventless-interop": "3.0.0-alpha.25",
-    "@reventlessdev/reventless-spec": "3.0.0-alpha.74"
+    "@reventlessdev/rescript-effect": "0.1.0-alpha.27",
+    "@reventlessdev/rescript-jest": "1.0.0-alpha.7",
+    "@reventlessdev/rescript-hash-object": "1.2.0-alpha.11",
+    "@reventlessdev/rescript-fast-csv": "1.2.0-alpha.12",
+    "@reventlessdev/rescript-node-streams": "1.1.0-alpha.11",
+    "@reventlessdev/rescript-pulumi-pulumi": "2.3.0-alpha.15",
+    "@reventlessdev/rescript-ssh2": "1.1.0-alpha.12",
+    "@reventlessdev/reventless-infra": "3.0.0-alpha.98",
+    "@reventlessdev/rescript-uuid": "1.1.0-alpha.15",
+    "@reventlessdev/reventless-interop": "3.0.0-alpha.26",
+    "@reventlessdev/reventless-spec": "3.0.0-alpha.76"
   },
   "devDependencies": {
     "rescript": "^12.3.0",
     "sury-ppx": "11.0.0-alpha.2",
-    "@reventlessdev/reventless-ppx": "1.0.0-alpha.52"
+    "@reventlessdev/reventless-ppx": "1.0.0-alpha.53"
   },
   "peerDependencies": {
     "rescript": "^12.3.0"

package/src/admin/AdminApi.res

@@ -25,9 +25,55 @@ let mutationEntries = (~cloner: bool) => {
 
 let queryEntries = PluginBaseFragment.queryEntries
 
+// ApiFragmentRegistry admin mutations — the real GraphQL surface of the ApiFragmentRegistry
+// StateChangeSlice: the plugin / standalone-service deploy calls `Platform_RegisterApiFragment` /
+// `Platform_DeregisterApiFragment` as a SigV4 system caller. Field names + arg SDL + the nested
+// `fragment` input type are derived from the slice's `commandSchema` via the SAME
+// `Api_Naming.sliceMutationFields` (admin "Platform" prefix) + `GraphQL_FragmentGenerator` path
+// that the DCB builder uses, so the field declared here in the STATIC admin base is byte-identical
+// to the one the DCB resolver binds to (`RecordApiFragmentPush` is `@noApi`, filtered out).
+//
+// These live in `baseFragment` ONLY, never in the shared `mutationEntries`: only the static base is
+// pushed to AppSync (`Platform.res` preAdminResolversSchemaHook), whereas the constructed admin
+// fragment (`Platform_Admin.construct`) already carries them via `dcbResult.mutationEntries`. Adding
+// them to `mutationEntries` — which feeds both — would duplicate the fields in the constructed
+// fragment. They are folded into `baseFragment`'s own `generate` call (not a separate one) so its
+// shared `seenTypes` dedups the shared `CommandResult` type family instead of re-emitting it.
+let apiFragmentRegistryMutationEntries: array<mutationSchemaEntry> = {
+  let commandSchema = ApiFragmentRegistry.commandSchema->S.castToUnknown
+  let fieldSpecs = Api_Naming.sliceMutationFields(
+    ~plugin="Platform",
+    ~slice=ApiFragmentRegistry.name,
+    ~commandSchema,
+  )
+  if fieldSpecs->Array.length === 0 {
+    []
+  } else {
+    [
+      {
+        ReventlessInfra.Api.fieldNames: fieldSpecs->Array.map(((f, _)) => f),
+        commandSchema,
+      },
+    ]
+  }
+}
+
+// Admin fields a deploy-time system caller (machine credentials — SigV4/IAM on AWS) invokes: the
+// two ApiFragmentRegistry mutations (the deploy's register/deregister write path) and
+// `Platform_ApiFragments` (the deploy waiter's push-status poll). Provider-neutral by design — the
+// AWS adapter threads these into `injectAwsAuthAll`'s `~iamFieldNames` so only these fields carry
+// the dual-auth (`@aws_cognito_user_pools @aws_iam`) directive; every other admin field stays
+// Cognito-only. Derived from the same mutation entries so the names never drift from the SDL.
+let systemCallerFieldNames =
+  apiFragmentRegistryMutationEntries
+  ->Array.flatMap(e => e.fieldNames)
+  ->Array.concat([Platform_ApiFragmentsApi.queryFieldName])
+
 // UIFragment lifecycle Source C subscriptions.
-// Mutations are called by the backend when UIFragment events occur;
-// AppSync routes via @aws_subscribe to onUIFragmentChange subscribers.
+// Mutations are called by the backend when UIFragment events occur; the
+// subscription→mutation fan-in is carried as neutral `subscriptionSource`
+// metadata (providers add their own routing — AppSync via `@aws_subscribe`
+// appended at push time, the local platform via its PubSub bridge).
 // manifest is serialised as a JSON string (String scalar, not AWSJSON).
 
 let uiFragmentSubscriptionTypes = [
@@ -41,12 +87,21 @@ let uiFragmentMutationFields = [
   `  Platform_UIFragmentDeregistered(pluginId: ID!): UIFragmentChangeEvent`,
 ]
 
-let uiFragmentSubscriptionField = `  onUIFragmentChange: UIFragmentChangeEvent\n    @aws_subscribe(mutations: ["Platform_UIFragmentRegistered", "Platform_UIFragmentUpdated", "Platform_UIFragmentDeregistered"])`
+let uiFragmentSubscriptionField = `  onUIFragmentChange: UIFragmentChangeEvent`
+
+let uiFragmentSubscriptionSource: GraphQL_Stitcher.subscriptionSource = {
+  field: "onUIFragmentChange",
+  mutations: [
+    "Platform_UIFragmentRegistered",
+    "Platform_UIFragmentUpdated",
+    "Platform_UIFragmentDeregistered",
+  ],
+}
 
 // Plugin lifecycle Source C subscription. Mirrors the UIFragment pattern: the
 // platform invokes `Platform_PluginStatusChanged` after writing the new status
-// to the Plugin read model; AppSync routes that mutation via `@aws_subscribe`
-// to live `onPluginStatusChange` subscribers (host shell). The status enum
+// to the Plugin read model; the provider routes that mutation to live
+// `onPluginStatusChange` subscribers (host shell). The status enum
 // matches `PluginsReadModelSpec.status` so consumers can mirror tier 1 / tier 2
 // transitions exactly.
 let pluginStatusSubscriptionTypes = [
@@ -58,31 +113,46 @@ let pluginStatusMutationFields = [
   `  Platform_PluginStatusChanged(pluginId: ID!, status: PluginStatus!): PluginStatusChangeEvent`,
 ]
 
-let pluginStatusSubscriptionField = `  onPluginStatusChange: PluginStatusChangeEvent\n    @aws_subscribe(mutations: ["Platform_PluginStatusChanged"])`
+let pluginStatusSubscriptionField = `  onPluginStatusChange: PluginStatusChangeEvent`
+
+let pluginStatusSubscriptionSource: GraphQL_Stitcher.subscriptionSource = {
+  field: "onPluginStatusChange",
+  mutations: ["Platform_PluginStatusChanged"],
+}
 
 let baseFragment = (~cloner: bool) => {
-  let base = GraphQL_FragmentGenerator.generate(~mutationEntries=mutationEntries(~cloner), ~queryEntries)
+  let base = GraphQL_FragmentGenerator.generate(
+    ~mutationEntries=Array.concat(mutationEntries(~cloner), apiFragmentRegistryMutationEntries),
+    ~queryEntries,
+  )
   let parts = GraphQL_Stitcher.decode(base)
   // Source C subscriptions for the admin Plugin aggregate mutations.
   // The standard auto-resolver flow (CommandGeneratorResolvers_AppSync.make)
   // always creates a Subscription.onX resolver per mutation field; without the
   // matching SDL fields, AppSync's CreateResolver fails with "Type not found".
-  let pluginAggregateSubscriptionFields =
+  let (pluginAggregateSubscriptionFields, pluginAggregateSubscriptionSources) =
     Plugin_SubscriptionSchema.sourceCFields(~mutationEntries=PluginBaseFragment.pluginAggregateMutationEntries)
   GraphQL_Stitcher.encode({
     types: parts.types
     ->Array.concat(uiFragmentSubscriptionTypes)
     ->Array.concat(pluginStatusSubscriptionTypes)
     ->Array.concat(Platform_ComponentDefinitionsApi.sdlTypes)
-    ->Array.concat(Platform_UIFragmentsApi.sdlTypes),
+    ->Array.concat(Platform_UIFragmentsApi.sdlTypes)
+    ->Array.concat(Platform_ApiFragmentsApi.sdlTypes),
     queries: Array.concat(
       parts.queries,
-      [Platform_ComponentDefinitionsApi.sdlQueryField, Platform_UIFragmentsApi.sdlQueryField],
+      [
+        Platform_ComponentDefinitionsApi.sdlQueryField,
+        Platform_UIFragmentsApi.sdlQueryField,
+        Platform_ApiFragmentsApi.sdlQueryField,
+      ],
     ),
     mutations: parts.mutations
     ->Array.concat(uiFragmentMutationFields)
     ->Array.concat(pluginStatusMutationFields),
     subscriptions: [uiFragmentSubscriptionField, pluginStatusSubscriptionField]
     ->Array.concat(pluginAggregateSubscriptionFields),
+    subscriptionSources: [uiFragmentSubscriptionSource, pluginStatusSubscriptionSource]
+    ->Array.concat(pluginAggregateSubscriptionSources),
   })
 }

package/src/admin/AdminApi.res.mjs

@@ -4,7 +4,9 @@ import * as S from "sury/src/S.res.mjs";
 import * as Api_Naming$ReventlessCore from "../components/Api/Api_Naming.res.mjs";
 import * as GraphQL_Stitcher$ReventlessCore from "../components/Api/GraphQL_Stitcher.res.mjs";
 import * as PluginBaseFragment$ReventlessCore from "../plugin/api/PluginBaseFragment.res.mjs";
+import * as ApiFragmentRegistry$ReventlessCore from "./ApiFragmentRegistry/StateChangeSlice/ApiFragmentRegistry.res.mjs";
 import * as Platform_UIFragmentsApi$ReventlessCore from "./Platform_UIFragmentsApi.res.mjs";
+import * as Platform_ApiFragmentsApi$ReventlessCore from "./Platform_ApiFragmentsApi.res.mjs";
 import * as GraphQL_FragmentGenerator$ReventlessCore from "../components/Api/GraphQL_FragmentGenerator.res.mjs";
 import * as Plugin_SubscriptionSchema$ReventlessCore from "../plugin/component/Plugin_SubscriptionSchema.res.mjs";
 import * as Platform_ComponentDefinitionsApi$ReventlessCore from "./Platform_ComponentDefinitionsApi.res.mjs";
@@ -31,6 +33,15 @@ function mutationEntries(cloner) {
   }
 }
 
+let fieldSpecs = Api_Naming$ReventlessCore.sliceMutationFields("Platform", ApiFragmentRegistry$ReventlessCore.name, ApiFragmentRegistry$ReventlessCore.commandSchema);
+
+let apiFragmentRegistryMutationEntries = fieldSpecs.length === 0 ? [] : [{
+      fieldNames: fieldSpecs.map(param => param[0]),
+      commandSchema: ApiFragmentRegistry$ReventlessCore.commandSchema
+    }];
+
+let systemCallerFieldNames = apiFragmentRegistryMutationEntries.flatMap(e => e.fieldNames).concat([Platform_ApiFragmentsApi$ReventlessCore.queryFieldName]);
+
 let uiFragmentSubscriptionTypes = [
   `enum UIFragmentChangeKind {\n  Registered\n  Updated\n  Deregistered\n}`,
   `type UIFragmentChangeEvent {\n  pluginId: ID!\n  changeKind: UIFragmentChangeKind!\n  manifest: String\n}`
@@ -42,7 +53,18 @@ let uiFragmentMutationFields = [
   `  Platform_UIFragmentDeregistered(pluginId: ID!): UIFragmentChangeEvent`
 ];
 
-let uiFragmentSubscriptionField = `  onUIFragmentChange: UIFragmentChangeEvent\n    @aws_subscribe(mutations: ["Platform_UIFragmentRegistered", "Platform_UIFragmentUpdated", "Platform_UIFragmentDeregistered"])`;
+let uiFragmentSubscriptionField = `  onUIFragmentChange: UIFragmentChangeEvent`;
+
+let uiFragmentSubscriptionSource_mutations = [
+  "Platform_UIFragmentRegistered",
+  "Platform_UIFragmentUpdated",
+  "Platform_UIFragmentDeregistered"
+];
+
+let uiFragmentSubscriptionSource = {
+  field: "onUIFragmentChange",
+  mutations: uiFragmentSubscriptionSource_mutations
+};
 
 let pluginStatusSubscriptionTypes = [
   `enum PluginStatus {\n  Connected\n  Disconnected\n  Inactive\n  Retired\n}`,
@@ -51,23 +73,35 @@ let pluginStatusSubscriptionTypes = [
 
 let pluginStatusMutationFields = [`  Platform_PluginStatusChanged(pluginId: ID!, status: PluginStatus!): PluginStatusChangeEvent`];
 
-let pluginStatusSubscriptionField = `  onPluginStatusChange: PluginStatusChangeEvent\n    @aws_subscribe(mutations: ["Platform_PluginStatusChanged"])`;
+let pluginStatusSubscriptionField = `  onPluginStatusChange: PluginStatusChangeEvent`;
+
+let pluginStatusSubscriptionSource_mutations = ["Platform_PluginStatusChanged"];
+
+let pluginStatusSubscriptionSource = {
+  field: "onPluginStatusChange",
+  mutations: pluginStatusSubscriptionSource_mutations
+};
 
 function baseFragment(cloner) {
-  let base = GraphQL_FragmentGenerator$ReventlessCore.generate(mutationEntries(cloner), PluginBaseFragment$ReventlessCore.queryEntries);
+  let base = GraphQL_FragmentGenerator$ReventlessCore.generate(mutationEntries(cloner).concat(apiFragmentRegistryMutationEntries), PluginBaseFragment$ReventlessCore.queryEntries);
   let parts = GraphQL_Stitcher$ReventlessCore.decode(base);
-  let pluginAggregateSubscriptionFields = Plugin_SubscriptionSchema$ReventlessCore.sourceCFields(PluginBaseFragment$ReventlessCore.pluginAggregateMutationEntries);
+  let match = Plugin_SubscriptionSchema$ReventlessCore.sourceCFields(PluginBaseFragment$ReventlessCore.pluginAggregateMutationEntries);
   return GraphQL_Stitcher$ReventlessCore.encode({
-    types: parts.types.concat(uiFragmentSubscriptionTypes).concat(pluginStatusSubscriptionTypes).concat(Platform_ComponentDefinitionsApi$ReventlessCore.sdlTypes).concat(Platform_UIFragmentsApi$ReventlessCore.sdlTypes),
+    types: parts.types.concat(uiFragmentSubscriptionTypes).concat(pluginStatusSubscriptionTypes).concat(Platform_ComponentDefinitionsApi$ReventlessCore.sdlTypes).concat(Platform_UIFragmentsApi$ReventlessCore.sdlTypes).concat(Platform_ApiFragmentsApi$ReventlessCore.sdlTypes),
     mutations: parts.mutations.concat(uiFragmentMutationFields).concat(pluginStatusMutationFields),
     queries: parts.queries.concat([
       Platform_ComponentDefinitionsApi$ReventlessCore.sdlQueryField,
-      Platform_UIFragmentsApi$ReventlessCore.sdlQueryField
+      Platform_UIFragmentsApi$ReventlessCore.sdlQueryField,
+      Platform_ApiFragmentsApi$ReventlessCore.sdlQueryField
     ]),
     subscriptions: [
       uiFragmentSubscriptionField,
       pluginStatusSubscriptionField
-    ].concat(pluginAggregateSubscriptionFields)
+    ].concat(match[0]),
+    subscriptionSources: [
+      uiFragmentSubscriptionSource,
+      pluginStatusSubscriptionSource
+    ].concat(match[1])
   });
 }
 
@@ -78,12 +112,16 @@ export {
   cloneMutationEntry,
   mutationEntries,
   queryEntries,
+  apiFragmentRegistryMutationEntries,
+  systemCallerFieldNames,
   uiFragmentSubscriptionTypes,
   uiFragmentMutationFields,
   uiFragmentSubscriptionField,
+  uiFragmentSubscriptionSource,
   pluginStatusSubscriptionTypes,
   pluginStatusMutationFields,
   pluginStatusSubscriptionField,
+  pluginStatusSubscriptionSource,
   baseFragment,
 }
 /* cloneArgsSchema Not a pure module */

package/src/admin/ApiFragmentRegistry/StateChangeSlice/ApiFragmentRegistry.res

@@ -0,0 +1,65 @@
+// ApiFragmentRegistry StateChangeSlice — the write side of the platform API-schema
+// fragment registry, replacing the raw `deploy-schema:*` keyspace (see
+// docs/plans/event-sourced-fragment-registries.md).
+//
+// Unlike the UiFragmentRegistry (connect/disconnect-driven), this registry's 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 single-writer schema-push automation:
+// 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 a
+// deploy waiter can poll the push status instead of timing out on introspection.
+@@reventless.spec
+
+open Reventless.Plugin
+
+// `at` is the registration timestamp, stamped from the incoming command meta by the
+// dispatching mapping — the StateViewSlice projection has no event meta, so time must
+// ride the payload. Inline records let the ppx auto-tag `pluginId` (scoping the decision
+// read to one plugin name). `message` is a plain string ("" = none) — option fields in
+// variant payloads don't survive the T|null wire contract cleanly.
+//
+// `apiTarget` is the API this plugin's fields belong to — Domain (the default) or Platform.
+// A plugin assigned to the Platform API (e.g. a platform inspector) stitches into the
+// Platform-API schema, not the Domain-API one; the single-writer push automation groups
+// fragments by this target and maintains one cumulative schema per API.
+// `RegisterApiFragment` / `DeregisterApiFragment` ARE the GraphQL surface — the deploy calls them
+// as a SigV4 system caller against the Platform API (exposed as `Platform_RegisterApiFragment` /
+// `Platform_DeregisterApiFragment`). `RecordApiFragmentPush` is `@noApi`: it is the internal
+// write-back of the single-writer schema-push automation, dispatched platform-side, never by a
+// GraphQL caller.
+@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})
+
+// This slice reads exactly the events it writes, so consumedEvent IS event — one inline
+// event type, no duplicate-constructor collision, ppx auto-tags `pluginId` on both roles.
+@schema
+type consumedEvent = event