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

package/src/plugin/component/Plugin_Structure.res

@@ -157,6 +157,70 @@ let labelFieldsFromStateSchema = (
     }
   }
 
+// ── Per-variant event / error field extraction (Phase 6.3) ───────────────────
+// Mirrors toCommandDef/extractCommandDefs for emitted events: name (TAG const),
+// payload JSON Schema, and cross-entity references. Module-level rather than
+// inside `make` because the synthetic Platform_Admin structure — hand-written,
+// because its components never pass through `make` — has to derive its defs the
+// same way, and a second copy of this walk would be free to drift from this one.
+
+let toEventDef = (v: S.t<unknown>): option<Reventless.Plugin.eventDef> => {
+  let mkDef = (~variantName, ~properties) => {
+    let references =
+      properties
+      ->Dict.toArray
+      ->Array.filterMap(((fieldName, fieldSchema)) =>
+        Reventless.Reference.getTarget(fieldSchema)->Option.map(target => (
+          {
+            Reventless.Plugin.fieldName,
+            entity: target.entity,
+            plugin: target.plugin,
+          }: Reventless.Plugin.fieldReference
+        ))
+      )
+    ({
+      Reventless.Plugin.name: variantName,
+      // Derived for the same reason as `commandDef.schema`: an event's field
+      // markers are the write side's half of the same vocabulary.
+      schema: v->SuryToJsonSchema.deriveObjectSchema->JSON.stringify,
+      references,
+    }: Reventless.Plugin.eventDef)
+  }
+  switch v {
+  | Object({properties}) =>
+    properties
+    ->Dict.get("TAG")
+    ->Option.flatMap(tagSchema =>
+      switch tagSchema {
+      | String({const: ?Some(variantName)}) => Some(mkDef(~variantName, ~properties))
+      | _ => None
+      }
+    )
+  // Payload-less event variants (`| Archived`) compile to a bare string literal.
+  // DCB-projection lookups can't WHERE-clause on them, so they stay out of
+  // producedEventTypes/consumedEventTypes; but the full `events` list carries them
+  // so the event graph can still draw the emitted (orphan) event node.
+  | String({const: ?Some(variantName)}) => Some(mkDef(~variantName, ~properties=Dict.make()))
+  | _ => None
+  }
+}
+
+let extractEventDefs = (eventSchema: S.t<unknown>): array<Reventless.Plugin.eventDef> =>
+  switch eventSchema {
+  | Union({anyOf}) => anyOf->Array.filterMap(toEventDef)
+  | _ => toEventDef(eventSchema)->Option.mapOr([], def => [def])
+  }
+
+// Declared errors walk identically to emitted events — an error variant is a
+// variant, and the payload-less form (`| CategoryNotFound`) is the common case
+// the bare-string branch above already handles. Reusing the walk rather than
+// copying it keeps the two from drifting; only the def type differs, so that a
+// consumer (and the SDL) can tell a refusal from a fact.
+let extractErrorDefs = (errorSchema: S.t<unknown>): array<Reventless.Plugin.errorDef> =>
+  extractEventDefs(errorSchema)->Array.map(({name, schema, references}) => (
+    {name, schema, references}: Reventless.Plugin.errorDef
+  ))
+
 let make = (
   type api role,
   ~name: string,
@@ -330,57 +394,6 @@ let make = (
       ->Option.mapOr([], def => [def])
     }
 
-  // ── Per-variant event field extraction (Phase 6.3) ─────────────────────────
-  // Mirrors toCommandDef/extractCommandDefs for emitted events: name (TAG const),
-  // payload JSON Schema, and cross-entity references.
-
-  let toEventDef = (v: S.t<unknown>): option<Reventless.Plugin.eventDef> => {
-    let mkDef = (~variantName, ~properties) => {
-      let references =
-        properties
-        ->Dict.toArray
-        ->Array.filterMap(((fieldName, fieldSchema)) =>
-          Reventless.Reference.getTarget(fieldSchema)->Option.map(target => (
-            {
-              Reventless.Plugin.fieldName,
-              entity: target.entity,
-              plugin: target.plugin,
-            }: Reventless.Plugin.fieldReference
-          ))
-        )
-      ({
-        Reventless.Plugin.name: variantName,
-        // Derived for the same reason as `commandDef.schema` above: an event's
-        // field markers are the write side's half of the same vocabulary.
-        schema: v->SuryToJsonSchema.deriveObjectSchema->JSON.stringify,
-        references,
-      }: Reventless.Plugin.eventDef)
-    }
-    switch v {
-    | Object({properties}) =>
-      properties
-      ->Dict.get("TAG")
-      ->Option.flatMap(tagSchema =>
-        switch tagSchema {
-        | String({const: ?Some(variantName)}) => Some(mkDef(~variantName, ~properties))
-        | _ => None
-        }
-      )
-    // Payload-less event variants (`| Archived`) compile to a bare string literal.
-    // DCB-projection lookups can't WHERE-clause on them, so they stay out of
-    // producedEventTypes/consumedEventTypes; but the full `events` list carries them
-    // so the event graph can still draw the emitted (orphan) event node.
-    | String({const: ?Some(variantName)}) => Some(mkDef(~variantName, ~properties=Dict.make()))
-    | _ => None
-    }
-  }
-
-  let extractEventDefs = (eventSchema: S.t<unknown>): array<Reventless.Plugin.eventDef> =>
-    switch eventSchema {
-    | Union({anyOf}) => anyOf->Array.filterMap(toEventDef)
-    | _ => toEventDef(eventSchema)->Option.mapOr([], def => [def])
-    }
-
   // ── Per-component event type extraction ────────────────────────────────────
 
   let scsProduced =
@@ -704,6 +717,7 @@ let make = (
         linkedViews: linkedSvsFor(produced),
         consistencyRead: consistencyReadFor(consumed),
         events: extractEventDefs(SCS.Spec.eventSchema->S.castToUnknown),
+        errors: extractErrorDefs(SCS.Spec.errorSchema->S.castToUnknown),
         chapter: chapterOf(SCS.Spec.name),
       }: Reventless.Plugin.writableDef)
     })
@@ -726,6 +740,7 @@ let make = (
         linkedViews: Array.concat(linkedSvsFor(produced), linkedReadModelsFor(A.Spec.name)),
         consistencyRead: None,
         events: extractEventDefs(A.Spec.eventSchema->S.castToUnknown),
+        errors: extractErrorDefs(A.Spec.errorSchema->S.castToUnknown),
         chapter: chapterOf(A.Spec.name),
       }: Reventless.Plugin.writableDef)
     })

package/src/plugin/component/Plugin_Structure.res.mjs

@@ -140,6 +140,62 @@ function labelFieldsFromStateSchema(entityName, stateSchema) {
   };
 }
 
+function toEventDef(v) {
+  let mkDef = (variantName, properties) => {
+    let references = Stdlib_Array.filterMap(Object.entries(properties), param => {
+      let fieldName = param[0];
+      return Stdlib_Option.map(Reference$Reventless.getTarget(param[1]), target => ({
+        fieldName: fieldName,
+        entity: target.entity,
+        plugin: target.plugin
+      }));
+    });
+    return {
+      name: variantName,
+      schema: JSON.stringify(SuryToJsonSchema$ReventlessCore.deriveObjectSchema(v)),
+      references: references
+    };
+  };
+  switch (v.type) {
+    case "string" :
+      let variantName = v.const;
+      if (variantName !== undefined) {
+        return mkDef(variantName, {});
+      } else {
+        return;
+      }
+    case "object" :
+      let properties = v.properties;
+      return Stdlib_Option.flatMap(properties["TAG"], tagSchema => {
+        if (tagSchema.type !== "string") {
+          return;
+        }
+        let variantName = tagSchema.const;
+        if (variantName !== undefined) {
+          return mkDef(variantName, properties);
+        }
+      });
+    default:
+      return;
+  }
+}
+
+function extractEventDefs(eventSchema) {
+  if (eventSchema.type === "union") {
+    return Stdlib_Array.filterMap(eventSchema.anyOf, toEventDef);
+  } else {
+    return Stdlib_Option.mapOr(toEventDef(eventSchema), [], def => [def]);
+  }
+}
+
+function extractErrorDefs(errorSchema) {
+  return extractEventDefs(errorSchema).map(param => ({
+    name: param.name,
+    schema: param.schema,
+    references: param.references
+  }));
+}
+
 function make(name, aggregatesOpt, readModelsOpt, stateViewSlicesOpt, stateChangeSlicesOpt, automationSlicesOpt, outboundTranslationSlicesOpt, inboundTranslationSlicesOpt, extensionsOpt, extensionPointsOpt, componentChaptersOpt) {
   let aggregates = aggregatesOpt !== undefined ? aggregatesOpt : [];
   let readModels = readModelsOpt !== undefined ? readModelsOpt : [];
@@ -268,52 +324,6 @@ function make(name, aggregatesOpt, readModelsOpt, stateViewSlicesOpt, stateChang
       return Stdlib_Option.mapOr(toCommandDef(isAggregate, mutationFieldFor, commandSchema, commandSchema), [], def => [def]);
     }
   };
-  let toEventDef = v => {
-    let mkDef = (variantName, properties) => {
-      let references = Stdlib_Array.filterMap(Object.entries(properties), param => {
-        let fieldName = param[0];
-        return Stdlib_Option.map(Reference$Reventless.getTarget(param[1]), target => ({
-          fieldName: fieldName,
-          entity: target.entity,
-          plugin: target.plugin
-        }));
-      });
-      return {
-        name: variantName,
-        schema: JSON.stringify(SuryToJsonSchema$ReventlessCore.deriveObjectSchema(v)),
-        references: references
-      };
-    };
-    switch (v.type) {
-      case "string" :
-        let variantName = v.const;
-        if (variantName !== undefined) {
-          return mkDef(variantName, {});
-        } else {
-          return;
-        }
-      case "object" :
-        let properties = v.properties;
-        return Stdlib_Option.flatMap(properties["TAG"], tagSchema => {
-          if (tagSchema.type !== "string") {
-            return;
-          }
-          let variantName = tagSchema.const;
-          if (variantName !== undefined) {
-            return mkDef(variantName, properties);
-          }
-        });
-      default:
-        return;
-    }
-  };
-  let extractEventDefs = eventSchema => {
-    if (eventSchema.type === "union") {
-      return Stdlib_Array.filterMap(eventSchema.anyOf, toEventDef);
-    } else {
-      return Stdlib_Option.mapOr(toEventDef(eventSchema), [], def => [def]);
-    }
-  };
   let scsProduced = stateChangeSlices.map(SCS => [
     SCS.Spec.name,
     qualify(name, DcbTag$Reventless.extractVariantNames(SCS.Spec.eventSchema))
@@ -541,6 +551,7 @@ function make(name, aggregatesOpt, readModelsOpt, stateViewSlicesOpt, stateChang
       linkedViews: linkedSvsFor(produced),
       consistencyRead: consistencyReadFor(consumed),
       events: extractEventDefs(SCS.Spec.eventSchema),
+      errors: extractErrorDefs(SCS.Spec.errorSchema),
       chapter: componentChapters[SCS.Spec.name]
     };
   });
@@ -555,6 +566,7 @@ function make(name, aggregatesOpt, readModelsOpt, stateViewSlicesOpt, stateChang
       linkedViews: linkedSvsFor(produced).concat(linkedReadModelsFor(A.Spec.name)),
       consistencyRead: undefined,
       events: extractEventDefs(A.Spec.eventSchema),
+      errors: extractErrorDefs(A.Spec.errorSchema),
       chapter: componentChapters[A.Spec.name]
     };
   });
@@ -641,6 +653,9 @@ export {
   statusFieldFromStateSchema,
   labelFieldSourceToString,
   labelFieldsFromStateSchema,
+  toEventDef,
+  extractEventDefs,
+  extractErrorDefs,
   make,
 }
 /* log Not a pure module */

package/tests/admin/Platform_ComponentDefinitionsApiTest.res

@@ -41,6 +41,7 @@ let wbl: writableDef = {
   producedEventTypes: ["ProductAdded"],
   consumedEventTypes: [],
   events: [{name: "ProductAdded", schema: "{}", references: []}],
+  errors: [{name: "ProductAlreadyExists", schema: "{}", references: []}],
   chapter: None,
 }
 
@@ -162,6 +163,17 @@ describe("encodePluginStructureEntry", () => {
     expect(json->String.includes("\"events\":[{\"name\":\"ProductAdded\""))->toEqual(true)
   )
 
+  // The refusals a caller has to handle travel beside the facts it can observe.
+  testSync("encodes writableDef errors", () =>
+    expect(json->String.includes("\"errors\":[{\"name\":\"ProductAlreadyExists\""))->toEqual(true)
+  )
+
+  testSync("declares Platform_ErrorDef and the errors field in the shared write-side SDL", () => {
+    let sdl = Platform_ComponentDefinitionsApi.sdlTypes->Array.join("\n")
+    expect(sdl->String.includes("type Platform_ErrorDef"))->toEqual(true)
+    expect(sdl->String.includes("errors: [Platform_ErrorDef!]!"))->toEqual(true)
+  })
+
   // Translation-slice externalSystem: absent on the fixture above (both None), so it
   // must serialize as null — the "no external box" case. The leading field keeps the
   // two directions apart; `targetName` sits between them and is pinned here too.
@@ -292,6 +304,7 @@ describe("allowedStates + statusField populated", () => {
     producedEventTypes: [],
     consumedEventTypes: [],
     events: [],
+    errors: [],
     chapter: None,
   }
 
@@ -325,4 +338,12 @@ describe("allowedStates + statusField populated", () => {
   testSync("encodes populated statusField as the field name string", () =>
     expect(json->String.includes("\"statusField\":\"status\""))->toEqual(true)
   )
+
+  // "declares no errors" is an empty list, never null — the SDL types `errors` as
+  // non-null, and a structure is re-derived on every build, so there is no third
+  // "cannot say" state to encode.
+  testSync("encodes a component with no declared errors as an empty array, not null", () => {
+    expect(json->String.includes("\"errors\":[]"))->toEqual(true)
+    expect(json->String.includes("\"errors\":null"))->toEqual(false)
+  })
 })

package/tests/admin/Platform_ComponentDefinitionsApiTest.res.mjs

@@ -61,6 +61,12 @@ let wbl_events = [{
     references: []
   }];
 
+let wbl_errors = [{
+    name: "ProductAlreadyExists",
+    schema: "{}",
+    references: []
+  }];
+
 let wbl = {
   name: "Product",
   commands: wbl_commands,
@@ -69,6 +75,7 @@ let wbl = {
   linkedViews: wbl_linkedViews,
   consistencyRead: undefined,
   events: wbl_events,
+  errors: wbl_errors,
   chapter: undefined
 };
 
@@ -182,6 +189,14 @@ globalThis.describe("encodePluginStructureEntry", () => {
   globalThis.test("encodes writableDef events", () => {
     globalThis.expect(json.includes("\"events\":[{\"name\":\"ProductAdded\"")).toEqual(true);
   });
+  globalThis.test("encodes writableDef errors", () => {
+    globalThis.expect(json.includes("\"errors\":[{\"name\":\"ProductAlreadyExists\"")).toEqual(true);
+  });
+  globalThis.test("declares Platform_ErrorDef and the errors field in the shared write-side SDL", () => {
+    let sdl = Platform_ComponentDefinitionsApi$ReventlessCore.sdlTypes.join("\n");
+    globalThis.expect(sdl.includes("type Platform_ErrorDef")).toEqual(true);
+    globalThis.expect(sdl.includes("errors: [Platform_ErrorDef!]!")).toEqual(true);
+  });
   globalThis.test("encodes None outbound externalSystem as null", () => {
     globalThis.expect(json.includes("\"inboundCommandTypes\":[\"Ship\"],\"targetName\":null,\"externalSystem\":null")).toEqual(true);
   });
@@ -326,6 +341,7 @@ globalThis.describe("allowedStates + statusField populated", () => {
   let wblWithStates_consumedEventTypes = [];
   let wblWithStates_linkedViews = ["Plugin"];
   let wblWithStates_events = [];
+  let wblWithStates_errors = [];
   let wblWithStates = {
     name: "Plugin",
     commands: wblWithStates_commands,
@@ -334,6 +350,7 @@ globalThis.describe("allowedStates + statusField populated", () => {
     linkedViews: wblWithStates_linkedViews,
     consistencyRead: undefined,
     events: wblWithStates_events,
+    errors: wblWithStates_errors,
     chapter: undefined
   };
   let structureWithStates_readModels = [qblWithStatus];
@@ -367,6 +384,10 @@ globalThis.describe("allowedStates + statusField populated", () => {
   globalThis.test("encodes populated statusField as the field name string", () => {
     globalThis.expect(json.includes("\"statusField\":\"status\"")).toEqual(true);
   });
+  globalThis.test("encodes a component with no declared errors as an empty array, not null", () => {
+    globalThis.expect(json.includes("\"errors\":[]")).toEqual(true);
+    globalThis.expect(json.includes("\"errors\":null")).toEqual(false);
+  });
 });
 
 export {

package/tests/commandtopic/CommandOutcomeHookTest.res

@@ -0,0 +1,258 @@
+// The command-outcome hook, at the property the side-channels don't have: it fires on the
+// fire-and-forget dispatch path — no acceptedResultChannel/rejectedResultChannel is installed
+// anywhere in this file — for both write-side component kinds, carrying the owning component
+// and telling a domain rejection apart from an infrastructure failure.
+
+open JestGlobals
+
+// ── StateChangeSlice arm (the aggregate arm reuses AggregateFixtures as-is) ──
+
+let dcbMock = DcbFixtures.makeMockStorage()
+
+module TestDcbOps: DcbEventLog_Operations.Ops = {
+  let name = "TestDcbEventLog"
+  let serviceName = "TestDcbEventLog"
+  let storage = dcbMock.operations
+  let publishJson = dcbMock.mockPublishJson
+}
+
+module EventLogOps = DcbEventLog_Operations.Make(TestDcbOps)
+
+let dcbEventLog: DcbEventLog.operations = {
+  read: EventLogOps.read,
+  append: EventLogOps.append,
+  readStream: EventLogOps.readStream,
+  appendStream: EventLogOps.appendStream,
+}
+
+module SliceBehavior = {
+  type state = DcbFixtures.TestCommandSpec.state
+  let initialState = DcbFixtures.TestCommandSpec.initialState
+  let evolve = DcbFixtures.TestCommandSpec.evolve
+  let decide = DcbFixtures.TestCommandSpec.decide
+  let moduleUrl = DcbFixtures.TestCommandSpec.moduleUrl
+}
+
+module SliceHandler = StateChangeSlice_Callback.Make(DcbFixtures.TestCommandSpec, SliceBehavior)
+
+let sliceItem = (reference, command): CommandTopic.topicItem<
+  Message.command'<Reventless.Id.String.t, DcbFixtures.TestCommandSpec.command>,
+> => {
+  command: {
+    id: Reventless.Id.String.makeFromString("cmd-" ++ reference),
+    meta: DcbFixtures.testMeta,
+    command,
+  },
+  reference,
+}
+
+let runSlice = (reference, command) =>
+  SliceHandler.handleCommands(dcbEventLog, Stream.fromIterable([sliceItem(reference, command)]))
+  ->Effect.runPromise
+
+let runAgg = (~aggId="agg-1", reference, command) =>
+  Stream.fromIterable([AggregateFixtures.makeTopicItem(~aggId, reference, command)])
+  ->AggregateFixtures.TestHandler.handleCommands
+  ->Effect.runPromise
+
+// ── Capture ──
+
+let observed: ref<array<CommandTopic_Helpers.commandOutcomeReport>> = ref([])
+
+// Flattened for readable assertions: (component, reference, disposition, errorCode, eventCount).
+let seen = () =>
+  observed.contents->Array.map(r =>
+    switch r.outcome {
+    | OutcomeAccepted({eventCount}) => (r.component, r.reference, "accepted", "", eventCount)
+    | OutcomeRejected({errorCode, cause}) => (
+        r.component,
+        r.reference,
+        switch cause {
+        | DomainRejection => "rejected/domain"
+        | InfrastructureFailure => "rejected/infrastructure"
+        },
+        errorCode,
+        0,
+      )
+    }
+  )
+
+let record = () =>
+  CommandTopic_Helpers.registerCommandOutcome(r =>
+    observed := observed.contents->Array.concat([r])
+  )
+
+let _ = beforeEach(() => {
+  AggregateFixtures.mock.reset()
+  AggregateFixtures.TestHandler.resetCache()
+  dcbMock.reset()
+  SliceHandler.resetCache()
+  observed := []
+  CommandTopic_Helpers.clearCommandOutcome()
+  RuntimeExtension.reset()
+})
+
+describe("CommandTopic command-outcome hook:", () => {
+  describe("aggregate", () => {
+    testPromise("observes an accepted command with no side-channel installed", async () => {
+      record()
+      let results = await runAgg("ref-1", AggregateFixtures.AggSpec.Create({name: "Widget"}))
+
+      expect(results)->toEqual([Ok("ref-1")])
+      expect(seen())->toEqual([("TestAggregate", "ref-1", "accepted", "", 1)])
+    })
+
+    testPromise("carries the entity id of an accepted command", async () => {
+      record()
+      let _ = await runAgg(~aggId="agg-7", "ref-1", AggregateFixtures.AggSpec.Create({name: "W"}))
+
+      let entityId = switch (observed.contents->Array.getUnsafe(0)).outcome {
+      | OutcomeAccepted({entityId}) => entityId
+      | OutcomeRejected(_) => None
+      }
+      expect(entityId)->toEqual(Some("agg-7"))
+    })
+
+    testPromise("reports a decide rejection as domain, with the declared error code", async () => {
+      // Seed before registering, so only the second (rejected) Create is observed.
+      let _ = await runAgg("ref-seed", AggregateFixtures.AggSpec.Create({name: "Widget"}))
+      record()
+      let results = await runAgg("ref-1", AggregateFixtures.AggSpec.Create({name: "Widget"}))
+
+      expect(results)->toEqual([Ok("ref-1")])
+      expect(seen())->toEqual([
+        ("TestAggregate", "ref-1", "rejected/domain", "AlreadyExists", 0),
+      ])
+    })
+
+    testPromise("reports a failed append as infrastructure, not a domain rejection", async () => {
+      record()
+      AggregateFixtures.mock.failNextAppend := true
+      let _ = await runAgg("ref-1", AggregateFixtures.AggSpec.Create({name: "Widget"}))
+
+      // `decide` said Ok here — the store is what failed, and the hook has to say so.
+      expect(seen())->toEqual([
+        ("TestAggregate", "ref-1", "rejected/infrastructure", "AppendFailed", 0),
+      ])
+    })
+
+    testPromise("observes every command of a mixed batch", async () => {
+      let _ = await runAgg("ref-seed", AggregateFixtures.AggSpec.Create({name: "Widget"}))
+      record()
+      let _ =
+        await Stream.fromIterable([
+          AggregateFixtures.makeTopicItem("ref-1", AggregateFixtures.AggSpec.Rename({newName: "A"})),
+          AggregateFixtures.makeTopicItem("ref-2", AggregateFixtures.AggSpec.Create({name: "B"})),
+          AggregateFixtures.makeTopicItem("ref-3", AggregateFixtures.AggSpec.Rename({newName: "C"})),
+        ])
+        ->AggregateFixtures.TestHandler.handleCommands
+        ->Effect.runPromise
+
+      expect(seen())->toEqual([
+        ("TestAggregate", "ref-1", "accepted", "", 2),
+        ("TestAggregate", "ref-2", "rejected/domain", "AlreadyExists", 0),
+        ("TestAggregate", "ref-3", "accepted", "", 2),
+      ])
+    })
+  })
+
+  describe("state-change slice", () => {
+    testPromise("observes an accepted command with no side-channel installed", async () => {
+      record()
+      let _ = await runSlice(
+        "ref-1",
+        DcbFixtures.TestCommandSpec.CreateItem({itemId: "item-1", name: "Test"}),
+      )
+
+      expect(seen())->toEqual([
+        ("TestStateChangeSlice", DcbFixtures.testMeta.msgId, "accepted", "", 1),
+      ])
+    })
+
+    testPromise("reports a decide rejection as domain, with the declared error code", async () => {
+      let _ = await runSlice(
+        "ref-seed",
+        DcbFixtures.TestCommandSpec.CreateItem({itemId: "item-1", name: "Test"}),
+      )
+      record()
+      let _ = await runSlice(
+        "ref-1",
+        DcbFixtures.TestCommandSpec.CreateItem({itemId: "item-1", name: "Again"}),
+      )
+
+      expect(seen())->toEqual([
+        (
+          "TestStateChangeSlice",
+          DcbFixtures.testMeta.msgId,
+          "rejected/domain",
+          "ItemAlreadyExists",
+          0,
+        ),
+      ])
+    })
+
+    testPromise("reports exhausted append conflicts as infrastructure", async () => {
+      record()
+      // One more failure than the retry loop can absorb.
+      dcbMock.failNextAppends := 4
+      let _ = await runSlice(
+        "ref-1",
+        DcbFixtures.TestCommandSpec.CreateItem({itemId: "item-1", name: "Test"}),
+      )
+
+      expect(seen())->toEqual([
+        ("TestStateChangeSlice", DcbFixtures.testMeta.msgId, "rejected/infrastructure", "Conflict", 0),
+      ])
+    })
+  })
+
+  describe("registration", () => {
+    testPromise("with nothing registered nothing is observed and the command is unaffected", async () => {
+      let results = await runAgg("ref-1", AggregateFixtures.AggSpec.Create({name: "Widget"}))
+
+      expect(results)->toEqual([Ok("ref-1")])
+      expect(AggregateFixtures.mock.getAll()->Array.length)->toBe(1)
+      expect(observed.contents->Array.length)->toBe(0)
+    })
+
+    testPromise("clearCommandOutcome stops observation", async () => {
+      record()
+      CommandTopic_Helpers.clearCommandOutcome()
+      let _ = await runAgg("ref-1", AggregateFixtures.AggSpec.Create({name: "Widget"}))
+
+      expect(observed.contents->Array.length)->toBe(0)
+    })
+
+    testPromise("an out-of-tree extension can register it from onColdStart", async () => {
+      // The hook needs no registration path of its own: it has the shape the cold-start
+      // seam already reaches, so an extension picks it up alongside the other four.
+      module Accountant: RuntimeExtension.Extension = {
+        let moduleUrl = "file:///pkg/accountant.res.mjs"
+        let onColdStart = (~runtimeKind as _, ~component as _, ~plugin as _, ~platform as _) =>
+          record()
+      }
+      RuntimeExtension.use(module(Accountant: RuntimeExtension.Extension))
+      RuntimeExtension.notifyColdStart(
+        ~runtimeKind=ComponentType.Aggregate,
+        ~component="AllAggregates",
+        ~plugin=Some("Catalog"),
+        ~platform=Some("Shop"),
+      )
+
+      let _ = await runAgg("ref-1", AggregateFixtures.AggSpec.Create({name: "Widget"}))
+
+      expect(seen())->toEqual([("TestAggregate", "ref-1", "accepted", "", 1)])
+    })
+
+    testPromise("a throwing hook is swallowed and the command still succeeds", async () => {
+      CommandTopic_Helpers.registerCommandOutcome(_ =>
+        JsError.throwWithMessage("hook exploded")
+      )
+      let results = await runAgg("ref-1", AggregateFixtures.AggSpec.Create({name: "Widget"}))
+
+      // The outcome the hook observes has already happened — an observer must not undo it.
+      expect(results)->toEqual([Ok("ref-1")])
+      expect(AggregateFixtures.mock.getAll()->Array.length)->toBe(1)
+    })
+  })
+})