@reventlessdev/reventless-core 3.0.0-alpha.214 → 3.0.0-alpha.216

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.216 (2026-08-08)
+
+### Features
+
+* **core,spec:** surface a write-side component's declared error types ([c9c2505](https://github.com/ReventlessDev/reventless-core/commit/c9c25057c70595fe27d73447c9aef9b451f86168))
+* **core:** add a runtime hook for command outcomes ([f2092a8](https://github.com/ReventlessDev/reventless-core/commit/f2092a8f9a8d8d7feee4f3de19bea7297a250cbd))
+
+
+# 3.0.0-alpha.215 (2026-08-08)
+
+### Features
+
+* **core,aws,local:** add the RuntimeExtension cold-start seam ([143e30e](https://github.com/ReventlessDev/reventless-core/commit/143e30eeded6232ce7f0fcc18328939b2917bb31))
+
+
 # 3.0.0-alpha.214 (2026-08-07)
 
 ### Features

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reventlessdev/reventless-core",
-  "version": "3.0.0-alpha.214",
+  "version": "3.0.0-alpha.216",
   "description": "Core package for Reventless framework",
   "license": "Apache-2.0",
   "jest": {
@@ -28,17 +28,17 @@
   "dependencies": {
     "sury": "11.0.0-alpha.4",
     "uuid": "^13.0.0",
-    "@reventlessdev/rescript-effect": "0.1.0-alpha.32",
-    "@reventlessdev/rescript-hash-object": "1.2.0-alpha.14",
     "@reventlessdev/rescript-fast-csv": "2.0.0-alpha.2",
+    "@reventlessdev/rescript-effect": "0.1.0-alpha.32",
     "@reventlessdev/rescript-jest": "1.0.0-alpha.10",
+    "@reventlessdev/rescript-hash-object": "1.2.0-alpha.14",
+    "@reventlessdev/rescript-node": "2.0.0-alpha.2",
     "@reventlessdev/rescript-pulumi-pulumi": "2.3.0-alpha.18",
-    "@reventlessdev/rescript-ssh2": "2.0.0-alpha.2",
     "@reventlessdev/rescript-uuid": "2.0.0-alpha.0",
-    "@reventlessdev/rescript-node": "2.0.0-alpha.2",
-    "@reventlessdev/reventless-infra": "3.0.0-alpha.127",
+    "@reventlessdev/rescript-ssh2": "2.0.0-alpha.2",
+    "@reventlessdev/reventless-infra": "3.0.0-alpha.128",
     "@reventlessdev/reventless-interop": "3.0.0-alpha.30",
-    "@reventlessdev/reventless-spec": "3.0.0-alpha.101"
+    "@reventlessdev/reventless-spec": "3.0.0-alpha.102"
   },
   "devDependencies": {
     "rescript": "12.3.0",

package/src/adapter/RuntimeExtension/RuntimeExtension.res

@@ -0,0 +1,194 @@
+/**
+Runtime hook: every provisioned runtime announces its cold start, so an extension
+can register the runtime callback hooks the framework already ships — before the
+runtime handles its first request.
+
+No-op by default. Zero behavioral change unless an extension registers one via
+`use` before the platform/plugin build: nothing is bundled, no env var is set, and
+no code runs.
+
+`Monitoring` and `EventLogProvisioning` are the deploy-time half of this shape —
+they let an extension attach behaviour to *what gets provisioned*. This is the
+runtime half: *what runs inside it*. Without it,
+`CommandGenerator_Callback.registerCommandInterceptor`,
+`QueryDb_Callback.registerQueryInterceptor` and the two
+`EventPublish_Callback` publish hooks are unreachable in a deployed runtime —
+each is a module-level `ref` consulted on the hot path, so it is useless unless
+something calls the registrar in the same process first, and the framework-owned
+entry shells import only framework and domain modules. Per-command authorisation,
+request tracing, rate limiting and request accounting are all built from those
+hooks, and each one is otherwise a change to the framework itself.
+
+What an extension does at cold start is deliberately NOT a framework concern.
+This only exposes the choke point through which the framework says "a runtime of
+this kind just started, here is who it is" and leaves the reaction to the
+listener.
+
+See `docs/plans/done/runtime-extension-seam.md`.
+*/
+
+/**
+What every registered extension is handed at cold start. Kept to the runtime's
+IDENTITY on purpose: an extension registering a command interceptor needs to know
+which runtime it is inside, not that runtime's storage ops or specs. Widening this
+to internals would make it a second, informal handler API — and the four hooks it
+exists to reach already receive their own per-request payloads
+(`commandInterceptor` gets `~componentName` / `~tag` / `~args` on every call).
+
+`~runtimeKind` is the modelling kind of the component the runtime runs — the same
+`ComponentType.t` every AWS runtime builder already passes to
+`RuntimeEnvironment_Lambda.makeFromCodeAsset`, so there is no third taxonomy to
+keep in step with `Monitoring.unitKind` and `ResourceAttribution.Role`.
+
+`~component` is the runtime's STATIC logical name — the shared Lambda's name where
+several components of one kind share a runtime (`AllAggregatesCmdHandler`), the
+component's own name where it does not. It identifies the runtime, not a single
+model element; use the per-request `~componentName` on the interception hooks to
+tell hosted components apart.
+
+`~plugin` / `~platform` are the owning plugin and platform, taken at provisioning
+time from the ambient `ResourceAttribution` context (the same source `AWS_Tags`,
+`Monitoring.notify` and `EventLogProvisioning.notify` use) and carried into the
+runtime as configuration — the runtime has no ambient deploy context of its own.
+Both are `None` for a runtime provisioned outside any plugin construct.
+*/
+type coldStartHook = (
+  ~runtimeKind: ComponentType.t,
+  ~component: string,
+  ~plugin: option<string>,
+  ~platform: option<string>,
+) => unit
+
+/**
+A runtime extension, registered by an extension (a deploy program) before the
+platform builds. `onColdStart` is called once per runtime process, before that
+runtime handles its first request.
+
+`moduleUrl` is the extension module's own `import.meta.url`. It is what makes the
+seam reachable in a *deployed* runtime: registering a first-class module only
+populates the deploy program's process, and the Lambda is a different one, so the
+framework bundles the module's package into the code archive and names the module
+in the runtime's config for the entry shell to import. Spec and behavior modules
+are carried into runtimes the same way. The convention matches
+`@@reventless.spec`'s injected `let moduleUrl`, so a ReScript extension can lift
+it from there.
+
+**Synchronous.** An async hook would have to be awaited before the first request
+and would put extension latency on every cold path. An extension needing I/O can
+start it here and not block on it.
+
+**Fired once, in registration order.** Unlike `EventLogProvisioning` there is no
+scarce resource here (no stream-reader budget), so several extensions compose —
+tracing and accounting are independent concerns. They run in the order they were
+registered; an extension that depends on another having run first is relying on
+its host's statement order, which is the only ordering the framework can promise.
+
+**A throwing extension does not take the runtime down.** Each hook is isolated:
+the failure is logged at ERROR and the remaining extensions still run. Failing the
+runtime instead would turn a broken extension into an outage, which is a worse
+trade than a loud, skipped hook.
+*/
+module type Extension = {
+  let moduleUrl: string
+  let onColdStart: coldStartHook
+}
+
+let extensions: ref<array<module(Extension)>> = ref([])
+
+/**
+Register a runtime extension. Must run before the platform/plugin build in the
+deploy program (plain statement order — the registry is read when each runtime's
+code archive and config are built). Additive: call once per extension.
+
+There is no `Noop` default to register. The neutral state is the empty registry,
+which is also the state that bundles nothing and sets no env var; a registered
+do-nothing extension would still cost a package in every runtime's archive.
+*/
+let use = (e: module(Extension)) => extensions := extensions.contents->Array.concat([e])
+
+/**
+Drop every registration. Test-support only — deploy programs never call this.
+*/
+let reset = () => extensions := []
+
+/** True when no extension is registered — the default. Deploy-time backends use
+    this to skip bundling and config emission entirely, so a deployment that
+    registers nothing produces a byte-identical archive. */
+let isEmpty = () => extensions.contents->Array.length == 0
+
+/**
+The `import.meta.url` of every registered extension, in registration order. Read
+by the provider's code-archive builder to bundle each extension's package and to
+name the modules a deployed runtime imports at cold start.
+*/
+let moduleUrls = (): array<string> =>
+  extensions.contents->Array.map(e => {
+    module E = unpack(e)
+    E.moduleUrl
+  })
+
+let log = Logger.fromEnv()
+
+/**
+Run one hook, isolated. A throwing extension is logged at ERROR and skipped; the
+caller keeps going. See the failure-policy note on `Extension`.
+*/
+let runHook = (
+  hook: coldStartHook,
+  ~index: int,
+  ~runtimeKind: ComponentType.t,
+  ~component: string,
+  ~plugin: option<string>,
+  ~platform: option<string>,
+) =>
+  try hook(~runtimeKind, ~component, ~plugin, ~platform) catch {
+  | exn =>
+    let message =
+      exn->JsExn.fromException->Option.flatMap(JsExn.message)->Option.getOr("unknown error")
+    log.error(
+      ~comp="RuntimeExtension",
+      `extension ${index->Int.toString} threw at cold start of ${runtimeKind->ComponentType.toString}(${component}); skipped: ${message}`,
+    )
+  }
+
+/**
+Fire the given cold-start hooks, in order, each isolated from the others. Used by
+runtimes that resolve their extensions themselves — a deployed entry point loads
+its extension modules dynamically, so it holds hooks rather than first-class
+modules.
+*/
+let notifyColdStartHooks = (
+  ~hooks: array<coldStartHook>,
+  ~runtimeKind: ComponentType.t,
+  ~component: string,
+  ~plugin: option<string>,
+  ~platform: option<string>,
+) =>
+  hooks->Array.forEachWithIndex((hook, index) =>
+    hook->runHook(~index, ~runtimeKind, ~component, ~plugin, ~platform)
+  )
+
+/**
+Announce a runtime's cold start to every extension registered in THIS process.
+Called by in-process runtimes (the local platform), where the deploy program and
+the runtime share a process so the registry is already populated. A deployed
+runtime cannot use this — its registry is empty until it imports the extension
+modules named in its config — and calls `notifyColdStartHooks` instead. No-op
+until an extension registers.
+*/
+let notifyColdStart = (
+  ~runtimeKind: ComponentType.t,
+  ~component: string,
+  ~plugin: option<string>,
+  ~platform: option<string>,
+) =>
+  notifyColdStartHooks(
+    ~hooks=extensions.contents->Array.map(e => {
+      module E = unpack(e)
+      E.onColdStart
+    }),
+    ~runtimeKind,
+    ~component,
+    ~plugin,
+    ~platform,
+  )

package/src/adapter/RuntimeExtension/RuntimeExtension.res.mjs

@@ -0,0 +1,60 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+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 Primitive_exceptions from "@rescript/runtime/lib/es6/Primitive_exceptions.js";
+import * as Logger$ReventlessCore from "../../util/Logger.res.mjs";
+import * as ComponentType$ReventlessCore from "../../ComponentType.res.mjs";
+
+let extensions = {
+  contents: []
+};
+
+function use(e) {
+  extensions.contents = extensions.contents.concat([e]);
+}
+
+function reset() {
+  extensions.contents = [];
+}
+
+function isEmpty() {
+  return extensions.contents.length === 0;
+}
+
+function moduleUrls() {
+  return extensions.contents.map(e => e.moduleUrl);
+}
+
+let log = Logger$ReventlessCore.fromEnv();
+
+function runHook(hook, index, runtimeKind, component, plugin, platform) {
+  try {
+    return hook(runtimeKind, component, plugin, platform);
+  } catch (raw_exn) {
+    let exn = Primitive_exceptions.internalToException(raw_exn);
+    let message = Stdlib_Option.getOr(Stdlib_Option.flatMap(Stdlib_JsExn.fromException(exn), Stdlib_JsExn.message), "unknown error");
+    return log.error("RuntimeExtension", undefined, `extension ` + index.toString() + ` threw at cold start of ` + ComponentType$ReventlessCore.toString(runtimeKind) + `(` + component + `); skipped: ` + message);
+  }
+}
+
+function notifyColdStartHooks(hooks, runtimeKind, component, plugin, platform) {
+  hooks.forEach((hook, index) => runHook(hook, index, runtimeKind, component, plugin, platform));
+}
+
+function notifyColdStart(runtimeKind, component, plugin, platform) {
+  notifyColdStartHooks(extensions.contents.map(e => e.onColdStart), runtimeKind, component, plugin, platform);
+}
+
+export {
+  extensions,
+  use,
+  reset,
+  isEmpty,
+  moduleUrls,
+  log,
+  runHook,
+  notifyColdStartHooks,
+  notifyColdStart,
+}
+/* log Not a pure module */

package/src/admin/Platform_Admin_Structure.res

@@ -98,6 +98,10 @@ let pluginAggregate: writableDef = {
   linkedViews: ["Plugins"],
   consistencyRead: None,
   events: [],
+  // Derived rather than left empty like `events` above: the two admin commands can
+  // be refused, and `[]` here would read as "this aggregate never rejects". Uses
+  // the same walk `Plugin_Structure` applies to every other write side.
+  errors: Plugin_Structure.extractErrorDefs(PluginSpec.errorSchema->S.castToUnknown),
   chapter: None,
 }
 

package/src/admin/Platform_Admin_Structure.res.mjs

@@ -7,6 +7,8 @@ import * as Stdlib_Array from "@rescript/runtime/lib/es6/Stdlib_Array.js";
 import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
 import * as DcbTag$Reventless from "@reventlessdev/reventless-spec/src/components/DcbTag.res.mjs";
 import * as Api_Naming$ReventlessCore from "../components/Api/Api_Naming.res.mjs";
+import * as PluginSpec$ReventlessCore from "../plugin/lifecycle/PluginSpec.res.mjs";
+import * as Plugin_Structure$ReventlessCore from "../plugin/component/Plugin_Structure.res.mjs";
 import * as SuryToJsonSchema$ReventlessCore from "../components/Api/SuryToJsonSchema.res.mjs";
 import * as PluginBaseFragment$ReventlessCore from "../plugin/api/PluginBaseFragment.res.mjs";
 import * as PluginsReadModelSpec$ReventlessCore from "../plugin/lifecycle/PluginsReadModelSpec.res.mjs";
@@ -105,6 +107,8 @@ let pluginAggregate_linkedViews = ["Plugins"];
 
 let pluginAggregate_events = [];
 
+let pluginAggregate_errors = Plugin_Structure$ReventlessCore.extractErrorDefs(PluginSpec$ReventlessCore.errorSchema);
+
 let pluginAggregate = {
   name: "Plugin",
   commands: pluginAggregate_commands,
@@ -113,6 +117,7 @@ let pluginAggregate = {
   linkedViews: pluginAggregate_linkedViews,
   consistencyRead: undefined,
   events: pluginAggregate_events,
+  errors: pluginAggregate_errors,
   chapter: undefined
 };
 

package/src/admin/Platform_ComponentDefinitionsApi.res

@@ -20,7 +20,11 @@ let sdlTypes: array<string> = [
   `type Platform_FieldReference {\n  fieldName: String!\n  entity: String!\n  plugin: String\n}`,
   `type Platform_CommandDef {\n  name: String!\n  schema: String!\n  level: String!\n  aggregateIdField: String\n  mutationField: String!\n  references: [Platform_FieldReference!]!\n  allowedStates: [String!]\n  targetState: String\n  apiExposed: Boolean\n}`,
   `type Platform_EventDef {\n  name: String!\n  schema: String!\n  references: [Platform_FieldReference!]!\n}`,
-  `type Platform_WriteSideDef {\n  name: String!\n  commands: [Platform_CommandDef!]!\n  linkedViews: [String!]!\n  consistencyRead: String\n  producedEventTypes: [String!]!\n  consumedEventTypes: [String!]!\n  events: [Platform_EventDef!]!\n  chapter: String\n}`,
+  // Same fields as Platform_EventDef, kept a distinct type because a refusal is not
+  // a fact: a caller selecting `errors` is asking what a command can be rejected
+  // with, and the two lists must stay independently evolvable.
+  `type Platform_ErrorDef {\n  name: String!\n  schema: String!\n  references: [Platform_FieldReference!]!\n}`,
+  `type Platform_WriteSideDef {\n  name: String!\n  commands: [Platform_CommandDef!]!\n  linkedViews: [String!]!\n  consistencyRead: String\n  producedEventTypes: [String!]!\n  consumedEventTypes: [String!]!\n  events: [Platform_EventDef!]!\n  errors: [Platform_ErrorDef!]!\n  chapter: String\n}`,
   `type Platform_ReadSideDef {\n  name: String!\n  queryField: String!\n  schema: String!\n  consumedEventTypes: [String!]!\n  linkedWriteSide: [String!]!\n  labelField: String!\n  searchableFields: [String!]!\n  labelFieldSource: String\n  statusField: String\n  visibility: String\n  chapter: String\n}`,
   `type Platform_AutomationSliceDef {\n  name: String!\n  consumedEventTypes: [String!]!\n  producedCommandTypes: [String!]!\n  targetName: String\n  chapter: String\n}`,
   `type Platform_OutboundTranslationSliceDef {\n  name: String!\n  consumedEventTypes: [String!]!\n  inboundCommandTypes: [String!]!\n  targetName: String\n  externalSystem: String\n  chapter: String\n}`,
@@ -102,6 +106,13 @@ let encodeEventDef = (e: eventDef): JSON.t =>
     ("references", e.references->Array.map(encodeFieldReference)->JSON.Encode.array),
   ])->JSON.Encode.object
 
+let encodeErrorDef = (e: errorDef): JSON.t =>
+  Dict.fromArray([
+    ("name", JSON.Encode.string(e.name)),
+    ("schema", JSON.Encode.string(e.schema)),
+    ("references", e.references->Array.map(encodeFieldReference)->JSON.Encode.array),
+  ])->JSON.Encode.object
+
 let encodeWritableDef = (w: writableDef): JSON.t =>
   Dict.fromArray([
     ("name", JSON.Encode.string(w.name)),
@@ -115,6 +126,10 @@ let encodeWritableDef = (w: writableDef): JSON.t =>
     ("consumedEventTypes", encodeStrings(w.consumedEventTypes)),
     // Phase 6.3: emitted-event field schemas (None → [] on the wire).
     ("events", w.events->Array.map(encodeEventDef)->JSON.Encode.array),
+    // Declared errors — the refusals a caller has to handle. `[]` is the honest
+    // answer for a component that declares none; the structure is re-derived on
+    // every build, so it never stands in for "cannot say".
+    ("errors", w.errors->Array.map(encodeErrorDef)->JSON.Encode.array),
     ("chapter", w.chapter->Option.mapOr(JSON.Encode.null, JSON.Encode.string)),
   ])->JSON.Encode.object
 

package/src/admin/Platform_ComponentDefinitionsApi.res.mjs

@@ -8,7 +8,8 @@ let sdlTypes = [
   `type Platform_FieldReference {\n  fieldName: String!\n  entity: String!\n  plugin: String\n}`,
   `type Platform_CommandDef {\n  name: String!\n  schema: String!\n  level: String!\n  aggregateIdField: String\n  mutationField: String!\n  references: [Platform_FieldReference!]!\n  allowedStates: [String!]\n  targetState: String\n  apiExposed: Boolean\n}`,
   `type Platform_EventDef {\n  name: String!\n  schema: String!\n  references: [Platform_FieldReference!]!\n}`,
-  `type Platform_WriteSideDef {\n  name: String!\n  commands: [Platform_CommandDef!]!\n  linkedViews: [String!]!\n  consistencyRead: String\n  producedEventTypes: [String!]!\n  consumedEventTypes: [String!]!\n  events: [Platform_EventDef!]!\n  chapter: String\n}`,
+  `type Platform_ErrorDef {\n  name: String!\n  schema: String!\n  references: [Platform_FieldReference!]!\n}`,
+  `type Platform_WriteSideDef {\n  name: String!\n  commands: [Platform_CommandDef!]!\n  linkedViews: [String!]!\n  consistencyRead: String\n  producedEventTypes: [String!]!\n  consumedEventTypes: [String!]!\n  events: [Platform_EventDef!]!\n  errors: [Platform_ErrorDef!]!\n  chapter: String\n}`,
   `type Platform_ReadSideDef {\n  name: String!\n  queryField: String!\n  schema: String!\n  consumedEventTypes: [String!]!\n  linkedWriteSide: [String!]!\n  labelField: String!\n  searchableFields: [String!]!\n  labelFieldSource: String\n  statusField: String\n  visibility: String\n  chapter: String\n}`,
   `type Platform_AutomationSliceDef {\n  name: String!\n  consumedEventTypes: [String!]!\n  producedCommandTypes: [String!]!\n  targetName: String\n  chapter: String\n}`,
   `type Platform_OutboundTranslationSliceDef {\n  name: String!\n  consumedEventTypes: [String!]!\n  inboundCommandTypes: [String!]!\n  targetName: String\n  externalSystem: String\n  chapter: String\n}`,
@@ -152,6 +153,23 @@ function encodeEventDef(e) {
   ]);
 }
 
+function encodeErrorDef(e) {
+  return Object.fromEntries([
+    [
+      "name",
+      e.name
+    ],
+    [
+      "schema",
+      e.schema
+    ],
+    [
+      "references",
+      e.references.map(encodeFieldReference)
+    ]
+  ]);
+}
+
 function encodeWritableDef(w) {
   return Object.fromEntries([
     [
@@ -182,6 +200,10 @@ function encodeWritableDef(w) {
       "events",
       w.events.map(encodeEventDef)
     ],
+    [
+      "errors",
+      w.errors.map(encodeErrorDef)
+    ],
     [
       "chapter",
       Stdlib_Option.mapOr(w.chapter, null, prim => prim)
@@ -341,6 +363,7 @@ export {
   isPublicQueryable,
   encodeQueryableDef,
   encodeEventDef,
+  encodeErrorDef,
   encodeWritableDef,
   encodeAutomationSliceDef,
   encodeOutboundTranslationSliceDef,

package/src/components/Aggregate/Aggregate_Callback.res

@@ -284,13 +284,25 @@ module Make = (
     outcomes->Array.map(((reference, outcome, _meta)) =>
       switch outcome {
       | CmdRejected({errorCode, errorDetail}) =>
-        CommandTopic_Helpers.reportRejected(reference, {errorCode, errorDetail})
+        CommandTopic_Helpers.reportRejected(
+          ~component=Spec.name,
+          ~cause=DomainRejection,
+          reference,
+          {errorCode, errorDetail},
+        )
         Ok(reference)
       | CmdOk(_) if appendSucceeded =>
-        CommandTopic_Helpers.reportAccepted(reference, {entityId, eventCount: appendedEventCount})
+        CommandTopic_Helpers.reportAccepted(
+          ~component=Spec.name,
+          reference,
+          {entityId, eventCount: appendedEventCount},
+        )
         Ok(reference)
       | CmdOk(_) =>
+        // The decision succeeded and the append did not — infrastructure, not the model.
         CommandTopic_Helpers.reportRejected(
+          ~component=Spec.name,
+          ~cause=InfrastructureFailure,
           reference,
           {errorCode: "AppendFailed", errorDetail: appendErrorDetail},
         )

package/src/components/Aggregate/Aggregate_Callback.res.mjs

@@ -200,7 +200,7 @@ function Make(Spec) {
         let reference = param[0];
         if (outcome.TAG === "CmdOk") {
           if (appendSucceeded) {
-            CommandTopic_Helpers$ReventlessCore.reportAccepted(reference, {
+            CommandTopic_Helpers$ReventlessCore.reportAccepted(Spec.name, reference, {
               entityId: entityId,
               eventCount: appendedEventCount
             });
@@ -209,7 +209,7 @@ function Make(Spec) {
               _0: reference
             };
           } else {
-            CommandTopic_Helpers$ReventlessCore.reportRejected(reference, {
+            CommandTopic_Helpers$ReventlessCore.reportRejected(Spec.name, "InfrastructureFailure", reference, {
               errorCode: "AppendFailed",
               errorDetail: appendErrorDetail
             });
@@ -219,7 +219,7 @@ function Make(Spec) {
             };
           }
         }
-        CommandTopic_Helpers$ReventlessCore.reportRejected(reference, {
+        CommandTopic_Helpers$ReventlessCore.reportRejected(Spec.name, "DomainRejection", reference, {
           errorCode: outcome.errorCode,
           errorDetail: outcome.errorDetail
         });

package/src/components/CommandTopic/CommandTopic.res.mjs

@@ -23,6 +23,14 @@ function filter(allCommandTopics, names) {
 
 let componentType = "CommandTopic";
 
+let commandOutcomeHook = CommandTopic_Helpers$ReventlessCore.commandOutcomeHook;
+
+let registerCommandOutcome = CommandTopic_Helpers$ReventlessCore.registerCommandOutcome;
+
+let clearCommandOutcome = CommandTopic_Helpers$ReventlessCore.clearCommandOutcome;
+
+let fireCommandOutcome = CommandTopic_Helpers$ReventlessCore.fireCommandOutcome;
+
 let acceptedResultChannel = CommandTopic_Helpers$ReventlessCore.acceptedResultChannel;
 
 let rejectedResultChannel = CommandTopic_Helpers$ReventlessCore.rejectedResultChannel;
@@ -50,6 +58,10 @@ let getHandlers = CommandTopic_Helpers$ReventlessCore.getHandlers;
 export {
   componentType,
   NotPublishedToChannel,
+  commandOutcomeHook,
+  registerCommandOutcome,
+  clearCommandOutcome,
+  fireCommandOutcome,
   acceptedResultChannel,
   rejectedResultChannel,
   reportAccepted,

package/src/components/CommandTopic/CommandTopic_Helpers.res

@@ -18,6 +18,71 @@ is the JSON-stringified error payload (or empty string for payload-less variants
 */
 type rejectedResult = {errorCode: string, errorDetail: string}
 
+/**
+Why a command was refused.
+
+`DomainRejection` is `Behavior.decide` returning `Error` — the model declining the command,
+which is the model working. `InfrastructureFailure` is the decision never landing: an event-log
+append that failed outright or exhausted its conflict retries. Both arrive on `reportRejected`,
+so without this a consumer would read a broken event log as a business rejection.
+*/
+type refusalCause = DomainRejection | InfrastructureFailure
+
+/**
+What became of one command. Constructors are prefixed to stay clear of `commandOutcome`'s
+`Accepted`/`Rejected` below — that type is the producer-facing result shape (and the GraphQL
+`CommandResult` union); this one is the observation, and carries the refusal cause it doesn't.
+*/
+type observedOutcome =
+  | OutcomeAccepted({entityId: option<string>, eventCount: int})
+  | OutcomeRejected({errorCode: string, errorDetail: string, cause: refusalCause})
+
+/** `reference` is the command's `meta.msgId` on every current transport. */
+type commandOutcomeReport = {
+  component: string,
+  reference: string,
+  outcome: observedOutcome,
+}
+
+type commandOutcomeHook = commandOutcomeReport => unit
+
+/**
+Module-level outcome hook, in the shape the `RuntimeExtension` cold-start seam already reaches
+— so an extension registers it from `onColdStart` alongside the interception and publish hooks,
+and no new registration path is needed. None = no-op (default).
+*/
+let commandOutcomeHook: ref<option<commandOutcomeHook>> = ref(None)
+
+let registerCommandOutcome = (hook: commandOutcomeHook) => {
+  commandOutcomeHook.contents = Some(hook)
+}
+
+let clearCommandOutcome = () => {
+  commandOutcomeHook.contents = None
+}
+
+// Fired from reportAccepted/reportRejected below, which both write-side kinds call
+// unconditionally — so this sees fire-and-forget dispatches too, not just the ones a
+// producer awaited on the side-channels.
+//
+// A throwing hook is logged and swallowed: the outcome it observes has already happened,
+// and letting an observer fail a completed command would make an extension an outage
+// (the same failure policy the cold-start seam settled on).
+let fireCommandOutcome = (~component: string, ~reference: string, outcome: observedOutcome) =>
+  commandOutcomeHook.contents->Option.forEach(hook =>
+    switch hook({component, reference, outcome}) {
+    | () => ()
+    | exception err =>
+      EffectLogger.logError(
+        ~comp=`CommandTopic(${component})`,
+        `command-outcome hook threw (ignored): ${err
+          ->JsExn.fromException
+          ->Option.flatMap(JsExn.message)
+          ->Option.getOr("unknown")}`,
+      )->Effect.runSync
+    }
+  )
+
 // Side-channel for publishJsonsAndWait result propagation.
 // Set by runInlineAndCollect before invoking the handler; cleared after.
 // Callback implementations call reportAccepted during inline dispatch.
@@ -28,11 +93,32 @@ let acceptedResultChannel: ref<option<(string, acceptedResult) => unit>> = ref(N
 // `Rejected` outcomes that carry the real error code and detail.
 let rejectedResultChannel: ref<option<(string, rejectedResult) => unit>> = ref(None)
 
-let reportAccepted = (reference: string, result: acceptedResult) =>
+// `~component` is the owning component's `Spec.name`: an outcome isn't interpretable without
+// knowing which component produced it, and the side-channel (keyed per inline dispatch) never
+// had to say. `~cause` is required rather than defaulted so a new rejection site has to state
+// which kind it is instead of silently reporting infrastructure as a domain decision.
+let reportAccepted = (~component: string, reference: string, result: acceptedResult) => {
   acceptedResultChannel.contents->Option.forEach(cb => cb(reference, result))
+  fireCommandOutcome(
+    ~component,
+    ~reference,
+    OutcomeAccepted({entityId: result.entityId, eventCount: result.eventCount}),
+  )
+}
 
-let reportRejected = (reference: string, result: rejectedResult) =>
+let reportRejected = (
+  ~component: string,
+  ~cause: refusalCause,
+  reference: string,
+  result: rejectedResult,
+) => {
   rejectedResultChannel.contents->Option.forEach(cb => cb(reference, result))
+  fireCommandOutcome(
+    ~component,
+    ~reference,
+    OutcomeRejected({errorCode: result.errorCode, errorDetail: result.errorDetail, cause}),
+  )
+}
 
 // Placed here (rather than CommandTopic.res) so runInlineAndCollect can use commandOutcome
 // without importing Adapter.res → @pulumi/pulumi. Re-exported by CommandTopic via include.