@reventlessdev/reventless-spec 3.0.0-alpha.74 → 3.0.0-alpha.76

package/CHANGELOG.md

@@ -3,6 +3,21 @@
 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.76 (2026-07-12)
+
+### Features
+
+* **admin:** make the API fragment registry per-target (Domain | Platform) ([30491a9](https://github.com/ReventlessDev/reventless-core/commit/30491a9e14b4236c98cc756efb6de68ede1e77d7))
+* **admin:** retire the Plugin-aggregate UI-fragment path in favour of the registry slices ([1dbc708](https://github.com/ReventlessDev/reventless-core/commit/1dbc708e7439b34ff970cc3d963d7835a8c6fd48))
+
+
+# 3.0.0-alpha.75 (2026-07-11)
+
+### Features
+
+* **infra:** add DeployBootstrap seam for generated deploy programs ([f0dc868](https://github.com/ReventlessDev/reventless-core/commit/f0dc8686396d21e7b39667eb0825b2e57fe4dabf))
+
+
 # 3.0.0-alpha.74 (2026-07-11)
 
 ### Bug Fixes

package/README.md

@@ -1,114 +1,109 @@
-[![npm version](https://img.shields.io/npm/v/@reventlessdev/reventless-spec.svg?label=version)](https://www.npmjs.com/package/@reventlessdev/reventless-spec)
-[![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)
-
-# `reventless-spec`
-
-Specification types and interfaces for Reventless applications.
-
-## Usage
-
-- Add `@reventlessdev/reventless-spec` to your dependencies in `package.json`.
-- Add `@reventlessdev/reventless-spec` to your dependencies in `rescript.json`.
-- For general information see this monorepo's [readme](../../README.md)
-
-## Installation
+[![npm](https://img.shields.io/npm/v/@reventlessdev/reventless-spec.svg?label=npm)](https://www.npmjs.com/package/@reventlessdev/reventless-spec)
+[![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)
+
+# @reventlessdev/reventless-spec
+
+> ⚠️ **Alpha.** APIs and on-disk formats can change without notice between releases.
+> Pin exact versions and expect breaking changes.
+
+The **specification layer** of [Reventless](https://docs.reventless.dev) — a
+spec-driven, event-sourced CQRS framework written in [ReScript](https://rescript-lang.org).
+This package holds the type specifications and module-type interfaces that the rest of the
+framework is built on: the contracts application domain code implements (commands, events,
+behaviors, projections) and the component-kind vocabulary the whole framework shares. It
+has **no** runtime, cloud, or storage dependency, so domain code can declare its shape
+against `reventless-spec` without pulling in an implementation. Modules are exposed under
+the `Reventless` namespace.
+
+## What it provides
+
+ReScript modules, consumed by adding the package to your `rescript.json` `dependencies`.
+
+**Domain contracts (`types/`)**
+
+- **`Message`** — the envelope metadata carried by every event and command (`meta`,
+  `event'<>`, `command'<>`), used for audit, correlation, tracing, and routing.
+- **`Behavior`** — the module type application code implements to define aggregate business
+  logic: `initialState`, `evolve(state, event)`, and `decide(command, state)`.
+- **`Projection`** — `Source` / `Target` module types describing a read model projected
+  from an aggregate's events.
+- **`Handler`** — function signatures for handling commands, events, and errors.
+- **`SideEffect`** — module type for an imperative side effect triggered by aggregate events
+  (read-only access to the query engine; emits no events).
+- **`StoredEvent`** — the logical envelope for an event as it lives in storage; single
+  source of truth for the on-disk event shape.
+- **`Authorization`** / **`Identity`** — provider-agnostic permission rules evaluated against
+  a resolved identity.
+- **`QueryEngine`** — typed filter values and operations for read-model queries.
+- **`Id`**, **`EventMapping`**, **`ReadConsistency`**, **`Schedule`**, **`Visibility`** —
+  supporting spec types for identifiers, event translation, consistency, scheduling, and
+  exposure.
+
+**Component vocabulary (`components/`)**
+
+- **`ComponentKind`** — the single source of truth for the Reventless component-kind
+  vocabulary (aggregates, read models, tasks, extension points, DCB slices), including every
+  accepted folder spelling and body-file suffix.
+- Per-kind spec modules: `Aggregate`, `ReadModel`, `Task`, `ExtensionPoint`, `Plugin`, and
+  the DCB slices (`StateChangeSlice`, `StateViewSlice`, `AutomationSlice`,
+  `InboundTranslationSlice`, `OutboundTranslationSlice`), plus DCB tagging/validation helpers.
+
+**`generate-plugin` CLI**
+
+`reventless-spec` ships a `generate-plugin` binary that auto-generates `src/Plugin.res` from
+a plugin's folder structure, classifying `.res` files by their parent folder name — no
+hand-authored composition root required.
 
 ```bash
-npm install @reventlessdev/reventless-spec
-```
-
-Add to your `rescript.json`:
-
-```json
-{
-  "bs-dependencies": ["@reventlessdev/reventless-spec"]
-}
+generate-plugin src/          # generate src/Plugin.res from the src/ folder
 ```
 
----
+Wire it into your build via a `prebuild` script so it runs before `rescript build`. The
+generated `Plugin.res` is committed to git, so CI compiles it directly.
 
-## `generate-plugin` CLI
+## Where it fits
 
-`reventless-spec` ships a `generate-plugin` binary that auto-generates `src/Plugin.res` from a plugin's folder structure. This eliminates the need to maintain a hand-authored composition root.
+`reventless-spec` is the foundation package in the Reventless framework:
 
-### Setup
-
-Add to your plugin's `package.json`:
-
-```json
-{
-  "scripts": {
-    "generate": "generate-plugin src/",
-    "prebuild": "npm run generate",
-    "build": "rescript build"
-  }
-}
 ```
-
-### Usage
-
-```bash
-generate-plugin src/          # generate src/Plugin.res from the src/ folder
-npm run build                 # prebuild runs generate automatically, then compiles
+reventless-spec (specifications)  ← this package
+  ↓
+reventless-core (provider-agnostic framework)
+  ↓
+reventless-aws / reventless-postgres / reventless-local (storage & deployment adapters)
 ```
 
-### Folder conventions
+- [`@reventlessdev/reventless-core`](https://www.npmjs.com/package/@reventlessdev/reventless-core)
+  builds on these specs to provide the runtime building blocks.
+- [`@reventlessdev/reventless-infra`](https://www.npmjs.com/package/@reventlessdev/reventless-infra)
+  layers deploy-time infrastructure types on top of the same specs.
 
-The generator classifies `.res` files by their parent folder name. Chapter folders (e.g. `Product/`, `Customer/`) are transparent — only the leaf folder name matters.
+You normally obtain `reventless-spec` transitively by scaffolding an app rather than
+installing it on its own.
 
-| Folder | Component |
-|---|---|
-| `Aggregate[s]` | Aggregate — must be paired with a `*Behavior.res` |
-| `ReadModel[s]` | Read model — must be paired with a `*Projections.res` |
-| `Task[s]` | Task |
-| `ExtensionPoint[s]` | Extension point mapping |
-| `Extension[s]` | Extension mapping |
-| `StateChange[s][Slice[s]]` | DCB StateChangeSlice |
-| `StateView[s][Slice[s]]` | DCB StateViewSlice |
-| `Automation[s][Slice[s]]` | DCB AutomationSlice |
-| `InboundTranslation[s][Slice[s]]` | DCB InboundTranslationSlice |
-| `OutboundTranslation[s][Slice[s]]` | DCB OutboundTranslationSlice |
+## Install
 
-Always excluded: `Plugin/`, `tests/`, `lib/`, `*Test.res`, `*Fixtures.res`.
-
-### `plugin.json` (optional)
+```bash
+pnpm add @reventlessdev/reventless-spec
+```
 
-Place `src/plugin.json` to override defaults:
+Then register it as a ReScript dependency in `rescript.json`:
 
 ```json
 {
-  "name": "Catalog",
-  "heartbeatInterval": 60,
-  "exclude": ["Product/StateChangeSlice/Experimental.res", "Analytics/**"]
+  "dependencies": ["@reventlessdev/reventless-spec"]
 }
 ```
 
-| Field | Default |
-|---|---|
-| `name` | Derived from `package.json` `"name"` — unscoped, hyphens/underscores → PascalCase |
-| `heartbeatInterval` | `60` |
-| `exclude` | `[]` — file paths or globs relative to `src/` |
-
-### Extension file convention
-
-Each file in `Extension/` must expose its mapping as `module Mapping`:
-
-```rescript
-// OrdersExtension.res
-open ReventlessInfra.ExtensionMapping
-
-module Mapping = {
-  module ExtensionPoint = OrderingSpec.OrdersExtensionPoint
-  module Delegate = ProductDemand
-  // ...
-}
-```
+Requires ReScript `^12.3.0` (peer dependency).
 
-The generator references it as `OrdersExtension.Mapping`.
+## Links
 
-### Namespace note
+- 📚 Documentation — [docs.reventless.dev](https://docs.reventless.dev)
+- 📦 Repository — [ReventlessDev/reventless-core](https://github.com/ReventlessDev/reventless-core)
+- 📋 [Changelog](./CHANGELOG.md)
 
-Plugin packages should use a **suffixed namespace** (e.g. `CatalogPlugin`, `OrderingPlugin`). Never use a bare name like `Ordering` — it shadows OCaml's built-in `Ordering` type used by comparisons.
+## License
 
-The generated `Plugin.res` is **committed to git** — CI compiles it directly without re-running the generator.
+[Apache-2.0](https://opensource.org/licenses/Apache-2.0)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reventlessdev/reventless-spec",
-  "version": "3.0.0-alpha.74",
+  "version": "3.0.0-alpha.76",
   "description": "Specifications for Reventless",
   "license": "Apache-2.0",
   "bin": {
@@ -22,7 +22,7 @@
   },
   "devDependencies": {
     "rescript": "^12.3.0",
-    "@reventlessdev/rescript-jest": "1.0.0-alpha.6"
+    "@reventlessdev/rescript-jest": "1.0.0-alpha.7"
   },
   "peerDependencies": {
     "rescript": "^12.3.0"

package/src/components/Plugin.res

@@ -92,6 +92,16 @@ Encoded as JSON for transport; protocol identifies the schema format (e.g. "grap
 @schema
 type apiSchemaFragment = {encoded: string, protocol: string}
 
+/**
+The API a plugin's GraphQL fields are stitched into: the Domain API (the default —
+application plugins) or the Platform API (platform-level plugins such as an inspector,
+which contribute fields alongside the admin base). Serializes as the bare string
+"Domain" / "Platform". Consumed by the schema-fragment registry to maintain one
+cumulative schema per API.
+*/
+@schema
+type apiTarget = Domain | Platform
+
 // Sury's nullableAsOption creates T | undefined | null which fails jsonableValidation
 // inside union variant payloads. js_nullable creates T | null (no undefined) which is
 // JSON-safe and passes jsonableValidation in all contexts.
@@ -403,8 +413,6 @@ type pluginDefinition = {
   // Uses @s.matches(stringOptionSchema) — js_nullable creates string | null (not string | undefined),
   // which passes sury's jsonableValidation inside union variant payloads.
   apiTarget: @s.matches(stringOptionSchema) option<string>,
-  // UI fragment manifest contributed by this plugin (optional, absent for pure backend plugins).
-  uiFragments: @s.matches(uiFragmentManifestOptionSchema) option<uiFragmentManifest>,
   // Component graph metadata — populated by makePluginDefinition; absent for older protocol versions.
   structure: @s.matches(pluginStructureOptionSchema) option<pluginStructure>,
   // DCB EventLog definition for plugins that bundle a DcbEventLog component.

package/src/components/Plugin.res.mjs

@@ -38,6 +38,11 @@ let apiSchemaFragmentSchema = S.schema(s => ({
   protocol: s.m(S.string)
 }));
 
+let apiTargetSchema = S.union([
+  S.literal("Domain"),
+  S.literal("Platform")
+]);
+
 let apiSchemaFragmentOptionSchema = SuryResMjs.js_nullable(apiSchemaFragmentSchema);
 
 let dcbEventLogOptionSchema = SuryResMjs.js_nullable(dcbEventLogDefinitionSchema);
@@ -214,7 +219,6 @@ let pluginDefinitionSchema = S.schema(s => ({
   extensionProtocols: s.m(S.array(extensionProtocolSchema)),
   apiSchemaFragment: s.m(apiSchemaFragmentOptionSchema),
   apiTarget: s.m(stringOptionSchema),
-  uiFragments: s.m(uiFragmentManifestOptionSchema),
   structure: s.m(pluginStructureOptionSchema),
   dcbEventLog: s.m(dcbEventLogOptionSchema),
   kind: s.m(pluginKindSchema)
@@ -233,6 +237,7 @@ export {
   dcbEventLogDefinitionSchema,
   extensionProtocolSchema,
   apiSchemaFragmentSchema,
+  apiTargetSchema,
   apiSchemaFragmentOptionSchema,
   dcbEventLogOptionSchema,
   stringOptionSchema,

package/src/generator/Codegen.res

@@ -458,6 +458,10 @@ let renderMain = (~config: Config.config): string => {
     "// AUTO-GENERATED — do not edit. Run `npm run generate` to update.",
     "// " ++ name ++ " plugin — AWS deployment.",
     "",
+    // Deploy-time bootstrap seam (no-op unless a package registers a
+    // contribution). PreDeploy runs before the platform/plugin graph builds.
+    "ReventlessInfra.DeployBootstrap.run(PreDeploy)",
+    "",
     "module Platform = ReventlessAws.Platform.Make()",
     "module " ++ name ++ " = Plugin.Make(Platform)",
     "",
@@ -465,6 +469,9 @@ let renderMain = (~config: Config.config): string => {
     "  ~plugin=module(" ++ name ++ "),",
     ")",
     "",
+    // PostDeploy runs after the graph is registered (exports, cross-stack output).
+    "ReventlessInfra.DeployBootstrap.run(PostDeploy)",
+    "",
   ]->Array.join("\n")
 }
 

package/src/generator/Codegen.res.mjs

@@ -300,12 +300,16 @@ function renderMain(config) {
     "// AUTO-GENERATED — do not edit. Run `npm run generate` to update.",
     "// " + name + " plugin — AWS deployment.",
     "",
+    "ReventlessInfra.DeployBootstrap.run(PreDeploy)",
+    "",
     "module Platform = ReventlessAws.Platform.Make()",
     "module " + name + " = Plugin.Make(Platform)",
     "",
     "let default = Platform.deployPlugin(",
     "  ~plugin=module(" + name + "),",
     ")",
+    "",
+    "ReventlessInfra.DeployBootstrap.run(PostDeploy)",
     ""
   ].join("\n");
 }