@reventlessdev/trait-attachments 1.0.0-alpha.4 → 1.0.0-alpha.40

package/README.md

@@ -43,12 +43,14 @@ Unlike the geocoding trait this one writes nothing back into its host: the graft
 ```sh
 pnpm exec graft-trait @reventlessdev/trait-attachments \
   --into src/Product --tests tests/Product \
-  --entity Product --entityId productId --noun Image \
-  --file productImage --created ProductAdded --view Products
+  --entity Product --entityId productId --entityIdType CatalogSpec.ProductId \
+  --noun Image --file productImage --created ProductAdded --view Products
 ```
 
    The field is named for the store it draws from, and `--noun` is what this host calls
-   one attachment — it runs through every name the graft declares.
+   one attachment — it runs through every name the graft declares. `--entityIdType` names
+   the host's identity module, so the emitted ids are typed; leave it out for a host that
+   keeps its ids as strings.
 
 2. Fill the `TODO(graft)` markers. They are the host's own policy: the events its
    refusal turns on, the error it raises, and the `else if` in `decide` that raises it

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reventlessdev/trait-attachments",
-  "version": "1.0.0-alpha.4",
+  "version": "1.0.0-alpha.40",
   "description": "Attachments domain trait: rules, host contract, conformance suite and emitter for an ordered set of stored files on an entity, with a primary and captions",
   "license": "Apache-2.0",
   "files": [
@@ -11,16 +11,16 @@
     "README.md"
   ],
   "dependencies": {
-    "sury": "11.0.0-rc.2",
-    "sury-ppx": "11.0.0-rc.2",
-    "@reventlessdev/reventless-gwt": "1.0.0-alpha.202",
-    "@reventlessdev/reventless-spec": "3.0.0-alpha.128"
+    "sury": "11.0.0",
+    "sury-ppx": "11.0.0",
+    "@reventlessdev/reventless-gwt": "1.0.0-alpha.238",
+    "@reventlessdev/reventless-spec": "3.0.0-alpha.160"
   },
   "devDependencies": {
-    "rescript": "12.3.0"
+    "rescript": "12.3.1"
   },
   "peerDependencies": {
-    "rescript": "12.3.0"
+    "rescript": "^12.3.1"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org"

package/src/Attachments.res

@@ -6,7 +6,6 @@ contract is over that slice. The rules live in `Attachments_Rules` and are asser
 through a host by `Attachments_Conformance`; the spec surface the host maps onto
 them is written by `Attachments_Scaffold`.
 */
-
 /**
 This trait's own account of itself — see `AddressGeocoding.declaration` for why the
 version is read rather than written.
@@ -43,13 +42,27 @@ module type Binding = {
   module Spec: ReventlessGwt.Behavior_GWT.BehaviorSpec
   module Behavior: ReventlessGwt.Behavior_GWT.Behavior with module Spec = Spec
 
-  /** History that brings the entity into existence with an empty set. */
-  let created: array<Spec.consumedEvent>
-  /** The set's own facts, as the slice consumes them. */
-  let attachedC: ref => Spec.consumedEvent
-  let removedC: ref => Spec.consumedEvent
-  let primarySetC: ref => Spec.consumedEvent
-  let altTextSetC: (ref, string) => Spec.consumedEvent
+  /** The same facts as the slice **consumes** them, for building history.
+
+      A slice declares `consumedEvent` and `event` separately and they differ —
+      the consumed form carries no entity id, because the partition already
+      says which entity it belongs to. So a suite needs both spellings of the
+      same fact: one to lay down history, one to assert what was emitted.
+
+      Grouped rather than suffixed. The pairs used to read `attachedC` against
+      `attached`, which said "consumed" only to someone who already knew — and
+      in a codebase where every binding also carries commands, a bare `C` reads
+      just as naturally as one. */
+  module Consumed: {
+    /** History that brings the entity into existence with an empty set. */
+    let created: array<Spec.consumedEvent>
+    let attached: ref => Spec.consumedEvent
+    let removed: ref => Spec.consumedEvent
+    let primarySet: ref => Spec.consumedEvent
+    /** The conclusion — see `Attachments_Rules.fact`. */
+    let effectiveChanged: option<ref> => Spec.consumedEvent
+    let altTextSet: (ref, string) => Spec.consumedEvent
+  }
 
   let attach: ref => Spec.command
   let remove: ref => Spec.command
@@ -60,6 +73,10 @@ module type Binding = {
   let attached: ref => Spec.event
   let removed: ref => Spec.event
   let primarySet: ref => Spec.event
+  /** The member a reader should now show, or `None` where the set has none.
+      Every graft declares it, whatever its cardinality: a subscriber reading it
+      must not have to know how many members the host allows. */
+  let effectiveChanged: option<ref> => Spec.event
   let altTextSet: (ref, string) => Spec.event
   /** The refusal for a primary or caption on a ref that is not in the set. */
   let notAttached: Spec.error
@@ -89,13 +106,19 @@ module type SingleBinding = {
   module Spec: ReventlessGwt.Behavior_GWT.BehaviorSpec
   module Behavior: ReventlessGwt.Behavior_GWT.Behavior with module Spec = Spec
 
-  /** History that brings the entity into existence with an empty set. */
-  let created: array<Spec.consumedEvent>
-  /** The set's own facts, as the slice consumes them. No `primarySetC`: nothing
-      emits one. */
-  let attachedC: ref => Spec.consumedEvent
-  let removedC: ref => Spec.consumedEvent
-  let altTextSetC: (ref, string) => Spec.consumedEvent
+  /** The facts as the slice **consumes** them — see `Binding.Consumed`. No
+      `primarySet`: at this cardinality nothing emits one. */
+  module Consumed: {
+    /** History that brings the entity into existence with an empty set. */
+    let created: array<Spec.consumedEvent>
+    let attached: ref => Spec.consumedEvent
+    let removed: ref => Spec.consumedEvent
+    let altTextSet: (ref, string) => Spec.consumedEvent
+    /** Declared at this cardinality too even though `attached`/`removed` imply
+        it here: a subscriber must not have to know how many members a host
+        allows to know what to read. */
+    let effectiveChanged: option<ref> => Spec.consumedEvent
+  }
 
   let attach: ref => Spec.command
   /** Remove whatever is held. Takes no ref — there is only one, and asking the
@@ -111,6 +134,8 @@ module type SingleBinding = {
   let attached: ref => Spec.event
   let removed: ref => Spec.event
   let altTextSet: (ref, string) => Spec.event
+  /** The member a reader should now show, or `None` where nothing is held. */
+  let effectiveChanged: option<ref> => Spec.event
   /** The refusal for a caption on a ref that is not held. */
   let notAttached: Spec.error
 }

package/src/Attachments_Conformance.res

@@ -2,7 +2,6 @@
 The conformance suite, run by a host against its own graft. `Make(Binding).register()`
 inside a Jest test file registers one `describe` block over the binding.
 */
-
 /** The suite's title, composed once and read twice: the suite registers it,
     and `certify-trait` computes the same string to find the run's assertions in
     a test report. Exported rather than inlined so neither side parses the
@@ -17,13 +16,15 @@ let suiteName = (host: string) => `${host} conforms to the attachments trait`
 module Make = (B: Attachments.Binding) => {
   module G = ReventlessGwt.Behavior_GWT.Make(B.Spec, B.Behavior)
 
-  let withA = Array.concat(B.created, [B.attachedC(B.refA)])
-  let withAB = Array.concat(withA, [B.attachedC(B.refB)])
+  let withA = Array.concat(B.Consumed.created, [B.Consumed.attached(B.refA)])
+  let withAB = Array.concat(withA, [B.Consumed.attached(B.refB)])
 
   let register = () =>
     G.describe(suiteName(B.Spec.name), () => {
       G.test("the first attachment is appended", () =>
-        G.givenEvents(B.created)->G.whenCmd(B.attach(B.refA))->G.thenEvent(B.attached(B.refA))
+        G.givenEvents(B.Consumed.created)
+        ->G.whenCmd(B.attach(B.refA))
+        ->G.thenEvents([B.attached(B.refA), B.effectiveChanged(Some(B.refA))])
       )
 
       G.test("attaching a ref already in the set is a no-op", () =>
@@ -35,7 +36,9 @@ module Make = (B: Attachments.Binding) => {
       )
 
       G.test("removing an attached ref is appended", () =>
-        G.givenEvents(withA)->G.whenCmd(B.remove(B.refA))->G.thenEvent(B.removed(B.refA))
+        G.givenEvents(withA)
+        ->G.whenCmd(B.remove(B.refA))
+        ->G.thenEvents([B.removed(B.refA), B.effectiveChanged(None)])
       )
 
       G.test("removing a ref not in the set is a no-op", () =>
@@ -43,9 +46,9 @@ module Make = (B: Attachments.Binding) => {
       )
 
       G.test("a removed ref can be attached again", () =>
-        G.givenEvents(Array.concat(withA, [B.removedC(B.refA)]))
+        G.givenEvents(Array.concat(withA, [B.Consumed.removed(B.refA)]))
         ->G.whenCmd(B.attach(B.refA))
-        ->G.thenEvent(B.attached(B.refA))
+        ->G.thenEvents([B.attached(B.refA), B.effectiveChanged(Some(B.refA))])
       )
 
       G.test("the primary must be in the set", () =>
@@ -57,27 +60,50 @@ module Make = (B: Attachments.Binding) => {
       )
 
       G.test("choosing another primary is appended", () =>
-        G.givenEvents(withAB)->G.whenCmd(B.setPrimary(B.refB))->G.thenEvent(B.primarySet(B.refB))
+        G.givenEvents(withAB)
+        ->G.whenCmd(B.setPrimary(B.refB))
+        ->G.thenEvents([B.primarySet(B.refB), B.effectiveChanged(Some(B.refB))])
       )
 
       G.test("choosing the current primary is a no-op", () =>
-        G.givenEvents(Array.concat(withAB, [B.primarySetC(B.refB)]))
+        G.givenEvents(Array.concat(withAB, [B.Consumed.primarySet(B.refB)]))
         ->G.whenCmd(B.setPrimary(B.refB))
         ->G.thenNoEvent
       )
 
       G.test("removing the chosen primary lets the first remaining stand in", () =>
-        G.givenEvents(Array.concat(withAB, [B.primarySetC(B.refB), B.removedC(B.refB)]))
+        G.givenEvents(
+          Array.concat(withAB, [B.Consumed.primarySet(B.refB), B.Consumed.removed(B.refB)]),
+        )
         ->G.whenCmd(B.setPrimary(B.refA))
         ->G.thenNoEvent
       )
 
+      // The two moves nobody decides. Neither produces a fact of its own — the
+      // set simply resolves differently afterwards — which is why anything
+      // outside it could not follow the primary before this was announced.
+      G.test("removing the member that stood in promotes the next, and says so", () =>
+        G.givenEvents(withAB)
+        ->G.whenCmd(B.remove(B.refA))
+        ->G.thenEvents([B.removed(B.refA), B.effectiveChanged(Some(B.refB))])
+      )
+
+      G.test("removing the chosen primary announces the one that stands in", () =>
+        G.givenEvents(Array.concat(withAB, [B.Consumed.primarySet(B.refB)]))
+        ->G.whenCmd(B.remove(B.refB))
+        ->G.thenEvents([B.removed(B.refB), B.effectiveChanged(Some(B.refA))])
+      )
+
       G.test("a caption needs its ref in the set", () =>
         G.givenEvents(withA)
         ->G.whenCmd(B.setAltText(B.refB, "side"))
         ->G.thenError(B.notAttached)
       )
 
+      // One fact and no second one: a caption moves no file, so the conclusion
+      // is unchanged and must not be announced. This is what stops an
+      // implementation appending it after every command rather than after the
+      // ones that move it.
       G.test("a caption is appended", () =>
         G.givenEvents(withA)
         ->G.whenCmd(B.setAltText(B.refA, "front"))
@@ -85,7 +111,7 @@ module Make = (B: Attachments.Binding) => {
       )
 
       G.test("repeating the caption is a no-op", () =>
-        G.givenEvents(Array.concat(withA, [B.altTextSetC(B.refA, "front")]))
+        G.givenEvents(Array.concat(withA, [B.Consumed.altTextSet(B.refA, "front")]))
         ->G.whenCmd(B.setAltText(B.refA, "front"))
         ->G.thenNoEvent
       )
@@ -108,12 +134,14 @@ single image wants exactly as much as a gallery member does.
 module MakeSingle = (B: Attachments.SingleBinding) => {
   module G = ReventlessGwt.Behavior_GWT.Make(B.Spec, B.Behavior)
 
-  let withA = Array.concat(B.created, [B.attachedC(B.refA)])
+  let withA = Array.concat(B.Consumed.created, [B.Consumed.attached(B.refA)])
 
   let register = () =>
     G.describe(suiteName(B.Spec.name), () => {
       G.test("the first attachment is appended", () =>
-        G.givenEvents(B.created)->G.whenCmd(B.attach(B.refA))->G.thenEvent(B.attached(B.refA))
+        G.givenEvents(B.Consumed.created)
+        ->G.whenCmd(B.attach(B.refA))
+        ->G.thenEvents([B.attached(B.refA), B.effectiveChanged(Some(B.refA))])
       )
 
       G.test("attaching the ref already held is a no-op", () =>
@@ -126,21 +154,25 @@ module MakeSingle = (B: Attachments.SingleBinding) => {
       G.test("a second ref replaces the first rather than joining it", () =>
         G.givenEvents(withA)
         ->G.whenCmd(B.attach(B.refB))
-        ->G.thenEvents([B.removed(B.refA), B.attached(B.refB)])
+        ->G.thenEvents([B.removed(B.refA), B.attached(B.refB), B.effectiveChanged(Some(B.refB))])
       )
 
       G.test("clearing a held set removes what it holds", () =>
-        G.givenEvents(withA)->G.whenCmd(B.clear)->G.thenEvent(B.removed(B.refA))
+        G.givenEvents(withA)
+        ->G.whenCmd(B.clear)
+        ->G.thenEvents([B.removed(B.refA), B.effectiveChanged(None)])
       )
 
       G.test("clearing an empty set is a no-op", () =>
-        G.givenEvents(B.created)->G.whenCmd(B.clear)->G.thenNoEvent
+        G.givenEvents(B.Consumed.created)->G.whenCmd(B.clear)->G.thenNoEvent
       )
 
       G.test("a replaced ref can be attached again", () =>
-        G.givenEvents(Array.concat(withA, [B.removedC(B.refA), B.attachedC(B.refB)]))
+        G.givenEvents(
+          Array.concat(withA, [B.Consumed.removed(B.refA), B.Consumed.attached(B.refB)]),
+        )
         ->G.whenCmd(B.attach(B.refA))
-        ->G.thenEvents([B.removed(B.refB), B.attached(B.refA)])
+        ->G.thenEvents([B.removed(B.refB), B.attached(B.refA), B.effectiveChanged(Some(B.refA))])
       )
 
       // The caption names no ref either, so what it lands on is whatever is
@@ -153,17 +185,21 @@ module MakeSingle = (B: Attachments.SingleBinding) => {
       )
 
       G.test("a caption follows a replacement onto the new ref", () =>
-        G.givenEvents(Array.concat(withA, [B.removedC(B.refA), B.attachedC(B.refB)]))
+        G.givenEvents(
+          Array.concat(withA, [B.Consumed.removed(B.refA), B.Consumed.attached(B.refB)]),
+        )
         ->G.whenCmd(B.setAltText("side"))
         ->G.thenEvent(B.altTextSet(B.refB, "side"))
       )
 
       G.test("captioning an empty set is refused", () =>
-        G.givenEvents(B.created)->G.whenCmd(B.setAltText("front"))->G.thenError(B.notAttached)
+        G.givenEvents(B.Consumed.created)
+        ->G.whenCmd(B.setAltText("front"))
+        ->G.thenError(B.notAttached)
       )
 
       G.test("repeating the caption is a no-op", () =>
-        G.givenEvents(Array.concat(withA, [B.altTextSetC(B.refA, "front")]))
+        G.givenEvents(Array.concat(withA, [B.Consumed.altTextSet(B.refA, "front")]))
         ->G.whenCmd(B.setAltText("front"))
         ->G.thenNoEvent
       )

package/src/Attachments_Conformance.res.mjs

@@ -1,5 +1,6 @@
 // Generated by ReScript, PLEASE EDIT WITH CARE
 
+import * as Primitive_option from "@rescript/runtime/lib/es6/Primitive_option.js";
 import * as Behavior_GWT$ReventlessGwt from "@reventlessdev/reventless-gwt/src/Behavior_GWT.res.mjs";
 
 function suiteName(host) {
@@ -13,26 +14,46 @@ function Make(B) {
     evolve: $$let.evolve,
     decide: $$let.decide
   });
-  let withA = B.created.concat([B.attachedC(B.refA)]);
-  let withAB = withA.concat([B.attachedC(B.refB)]);
+  let withA = B.Consumed.created.concat([B.Consumed.attached(B.refA)]);
+  let withAB = withA.concat([B.Consumed.attached(B.refB)]);
   let register = () => G.describe(suiteName(B.Spec.name), () => {
-    G.test("the first attachment is appended", () => G.thenEvent(G.whenCmd(G.givenEvents(B.created), B.attach(B.refA)), B.attached(B.refA)));
+    G.test("the first attachment is appended", () => G.thenEvents(G.whenCmd(G.givenEvents(B.Consumed.created), B.attach(B.refA)), [
+      B.attached(B.refA),
+      B.effectiveChanged(Primitive_option.some(B.refA))
+    ]));
     G.test("attaching a ref already in the set is a no-op", () => G.thenNoEvent(G.whenCmd(G.givenEvents(withA), B.attach(B.refA))));
     G.test("a second ref extends the set rather than replacing it", () => G.thenEvent(G.whenCmd(G.givenEvents(withA), B.attach(B.refB)), B.attached(B.refB)));
-    G.test("removing an attached ref is appended", () => G.thenEvent(G.whenCmd(G.givenEvents(withA), B.remove(B.refA)), B.removed(B.refA)));
+    G.test("removing an attached ref is appended", () => G.thenEvents(G.whenCmd(G.givenEvents(withA), B.remove(B.refA)), [
+      B.removed(B.refA),
+      B.effectiveChanged(undefined)
+    ]));
     G.test("removing a ref not in the set is a no-op", () => G.thenNoEvent(G.whenCmd(G.givenEvents(withA), B.remove(B.refB))));
-    G.test("a removed ref can be attached again", () => G.thenEvent(G.whenCmd(G.givenEvents(withA.concat([B.removedC(B.refA)])), B.attach(B.refA)), B.attached(B.refA)));
+    G.test("a removed ref can be attached again", () => G.thenEvents(G.whenCmd(G.givenEvents(withA.concat([B.Consumed.removed(B.refA)])), B.attach(B.refA)), [
+      B.attached(B.refA),
+      B.effectiveChanged(Primitive_option.some(B.refA))
+    ]));
     G.test("the primary must be in the set", () => G.thenError(G.whenCmd(G.givenEvents(withA), B.setPrimary(B.refB)), B.notAttached));
     G.test("the first attached is the primary until one is chosen", () => G.thenNoEvent(G.whenCmd(G.givenEvents(withAB), B.setPrimary(B.refA))));
-    G.test("choosing another primary is appended", () => G.thenEvent(G.whenCmd(G.givenEvents(withAB), B.setPrimary(B.refB)), B.primarySet(B.refB)));
-    G.test("choosing the current primary is a no-op", () => G.thenNoEvent(G.whenCmd(G.givenEvents(withAB.concat([B.primarySetC(B.refB)])), B.setPrimary(B.refB))));
+    G.test("choosing another primary is appended", () => G.thenEvents(G.whenCmd(G.givenEvents(withAB), B.setPrimary(B.refB)), [
+      B.primarySet(B.refB),
+      B.effectiveChanged(Primitive_option.some(B.refB))
+    ]));
+    G.test("choosing the current primary is a no-op", () => G.thenNoEvent(G.whenCmd(G.givenEvents(withAB.concat([B.Consumed.primarySet(B.refB)])), B.setPrimary(B.refB))));
     G.test("removing the chosen primary lets the first remaining stand in", () => G.thenNoEvent(G.whenCmd(G.givenEvents(withAB.concat([
-      B.primarySetC(B.refB),
-      B.removedC(B.refB)
+      B.Consumed.primarySet(B.refB),
+      B.Consumed.removed(B.refB)
     ])), B.setPrimary(B.refA))));
+    G.test("removing the member that stood in promotes the next, and says so", () => G.thenEvents(G.whenCmd(G.givenEvents(withAB), B.remove(B.refA)), [
+      B.removed(B.refA),
+      B.effectiveChanged(Primitive_option.some(B.refB))
+    ]));
+    G.test("removing the chosen primary announces the one that stands in", () => G.thenEvents(G.whenCmd(G.givenEvents(withAB.concat([B.Consumed.primarySet(B.refB)])), B.remove(B.refB)), [
+      B.removed(B.refB),
+      B.effectiveChanged(Primitive_option.some(B.refA))
+    ]));
     G.test("a caption needs its ref in the set", () => G.thenError(G.whenCmd(G.givenEvents(withA), B.setAltText(B.refB, "side")), B.notAttached));
     G.test("a caption is appended", () => G.thenEvent(G.whenCmd(G.givenEvents(withA), B.setAltText(B.refA, "front")), B.altTextSet(B.refA, "front")));
-    G.test("repeating the caption is a no-op", () => G.thenNoEvent(G.whenCmd(G.givenEvents(withA.concat([B.altTextSetC(B.refA, "front")])), B.setAltText(B.refA, "front"))));
+    G.test("repeating the caption is a no-op", () => G.thenNoEvent(G.whenCmd(G.givenEvents(withA.concat([B.Consumed.altTextSet(B.refA, "front")])), B.setAltText(B.refA, "front"))));
   });
   return {
     G: G,
@@ -49,30 +70,38 @@ function MakeSingle(B) {
     evolve: $$let.evolve,
     decide: $$let.decide
   });
-  let withA = B.created.concat([B.attachedC(B.refA)]);
+  let withA = B.Consumed.created.concat([B.Consumed.attached(B.refA)]);
   let register = () => G.describe(suiteName(B.Spec.name), () => {
-    G.test("the first attachment is appended", () => G.thenEvent(G.whenCmd(G.givenEvents(B.created), B.attach(B.refA)), B.attached(B.refA)));
+    G.test("the first attachment is appended", () => G.thenEvents(G.whenCmd(G.givenEvents(B.Consumed.created), B.attach(B.refA)), [
+      B.attached(B.refA),
+      B.effectiveChanged(Primitive_option.some(B.refA))
+    ]));
     G.test("attaching the ref already held is a no-op", () => G.thenNoEvent(G.whenCmd(G.givenEvents(withA), B.attach(B.refA))));
     G.test("a second ref replaces the first rather than joining it", () => G.thenEvents(G.whenCmd(G.givenEvents(withA), B.attach(B.refB)), [
       B.removed(B.refA),
-      B.attached(B.refB)
+      B.attached(B.refB),
+      B.effectiveChanged(Primitive_option.some(B.refB))
+    ]));
+    G.test("clearing a held set removes what it holds", () => G.thenEvents(G.whenCmd(G.givenEvents(withA), B.clear), [
+      B.removed(B.refA),
+      B.effectiveChanged(undefined)
     ]));
-    G.test("clearing a held set removes what it holds", () => G.thenEvent(G.whenCmd(G.givenEvents(withA), B.clear), B.removed(B.refA)));
-    G.test("clearing an empty set is a no-op", () => G.thenNoEvent(G.whenCmd(G.givenEvents(B.created), B.clear)));
+    G.test("clearing an empty set is a no-op", () => G.thenNoEvent(G.whenCmd(G.givenEvents(B.Consumed.created), B.clear)));
     G.test("a replaced ref can be attached again", () => G.thenEvents(G.whenCmd(G.givenEvents(withA.concat([
-      B.removedC(B.refA),
-      B.attachedC(B.refB)
+      B.Consumed.removed(B.refA),
+      B.Consumed.attached(B.refB)
     ])), B.attach(B.refA)), [
       B.removed(B.refB),
-      B.attached(B.refA)
+      B.attached(B.refA),
+      B.effectiveChanged(Primitive_option.some(B.refA))
     ]));
     G.test("a caption lands on the ref that is held", () => G.thenEvent(G.whenCmd(G.givenEvents(withA), B.setAltText("front")), B.altTextSet(B.refA, "front")));
     G.test("a caption follows a replacement onto the new ref", () => G.thenEvent(G.whenCmd(G.givenEvents(withA.concat([
-      B.removedC(B.refA),
-      B.attachedC(B.refB)
+      B.Consumed.removed(B.refA),
+      B.Consumed.attached(B.refB)
     ])), B.setAltText("side")), B.altTextSet(B.refB, "side")));
-    G.test("captioning an empty set is refused", () => G.thenError(G.whenCmd(G.givenEvents(B.created), B.setAltText("front")), B.notAttached));
-    G.test("repeating the caption is a no-op", () => G.thenNoEvent(G.whenCmd(G.givenEvents(withA.concat([B.altTextSetC(B.refA, "front")])), B.setAltText("front"))));
+    G.test("captioning an empty set is refused", () => G.thenError(G.whenCmd(G.givenEvents(B.Consumed.created), B.setAltText("front")), B.notAttached));
+    G.test("repeating the caption is a no-op", () => G.thenNoEvent(G.whenCmd(G.givenEvents(withA.concat([B.Consumed.altTextSet(B.refA, "front")])), B.setAltText("front"))));
   });
   return {
     G: G,

package/src/Attachments_Rules.res

@@ -7,11 +7,15 @@ A host maps its own constructors onto `op` and `fact` and keeps the spec surface
 the variants, their annotations, its own refusals. Nothing here knows what an
 entity is. `Attachments_Conformance` asserts these rules through a host.
 */
-
 /** The stored file's reference. A `StorageRef` path today, so `string` carries it
     without a wrapper the host would have to unwrap on every arm. */
 type ref = string
 
+// `@schema` so `Attachments_Scaffold`'s config can take this very type rather
+// than a second spelling of it. A graft's config and the rule it selects being
+// the same value is the point: a config that could say `"single"` where the
+// rules say `Single` is a config that can be misspelled.
+
 /**
 How many members a host's set may hold.
 
@@ -27,14 +31,12 @@ resolves to a no-op through the rules it already has (the only member is already
 the effective primary), which is why `Single` needs no branch for it and why the
 scaffold simply declines to emit the command rather than the rules refusing it.
 */
-// `@schema` so `Attachments_Scaffold`'s config can take this very type rather
-// than a second spelling of it. A graft's config and the rule it selects being
-// the same value is the point: a config that could say `"single"` where the
-// rules say `Single` is a config that can be misspelled.
 @schema
 type cardinality =
-  | /** An unbounded, ordered set: a gallery. */ Many
-  | /** At most one member, replaced rather than added to. */ Single
+  /** An unbounded, ordered set: a gallery. */
+  | Many
+  /** At most one member, replaced rather than added to. */
+  | Single
 
 /** Refolded per decision, never stored — a StateChangeSlice's state is. */
 type t = {
@@ -48,20 +50,20 @@ let empty = {attached: [], primary: None, altTexts: []}
 
 /** What a host asks the set to do. */
 type op =
-  | /** `altText` is the caption a host may supply with the file itself. */
-  Attach({ref: ref, altText: option<string>})
+  /** `altText` is the caption a host may supply with the file itself. */
+  | Attach({ref: ref, altText: option<string>})
   | Remove({ref: ref})
-  | /** Empty the set, whatever it holds.
+  /** Empty the set, whatever it holds.
 
         The op a bounded set's remove command maps onto: with one member there is
         no ref for the caller to name, and naming it would be asking them to
         repeat what the row already says. Well defined at either cardinality —
         an unbounded host that wants a "remove them all" command gets it here
         rather than by looping its own remove. */
-  Clear
+  | Clear
   | SetPrimary({ref: ref})
   | SetAltText({ref: ref, altText: string})
-  | /** Caption whichever member is the primary, without naming it.
+  /** Caption whichever member is the primary, without naming it.
 
         The counterpart of `Clear`, and the op a bounded set's caption command
         maps onto — with one member there is nothing to name. It is not
@@ -69,7 +71,7 @@ type op =
         sees, so "caption the hero" is a command an unbounded host wants too,
         and resolving it here through `effectivePrimary` is what keeps the
         answer the same as the member a projection puts first. */
-  SetPrimaryAltText({altText: string})
+  | SetPrimaryAltText({altText: string})
 
 /** What the set decided, for the host to name in its own event. */
 type fact =
@@ -77,6 +79,25 @@ type fact =
   | Removed({ref: ref})
   | PrimarySet({ref: ref})
   | AltTextSet({ref: ref, altText: string})
+  /** The member a reader should now show, or `None` where the set has none.
+
+        **A conclusion, not a decision.** `PrimarySet` records that somebody
+        chose; this records what the set resolved to, however it got there —
+        which is a different fact, and the one anything outside the set can act
+        on. The two coincide on an explicit choice and diverge everywhere else:
+        the first attachment stands in with nobody choosing, and removing the
+        one that stood in promotes the next.
+
+        Emitted at **both** cardinalities even though a `Single` host could
+        derive it from its own `Attached`/`Removed` pair, for the reason
+        `decide` gives below for not collapsing those two: a fact that only some
+        grafts emit makes a subscriber ask how many members the host allows,
+        which is not its business.
+
+        Optional because "there is no longer one to show" is as much a change as
+        any other, and a subscriber that cannot be told it keeps showing a file
+        the set no longer holds. */
+  | EffectiveChanged({ref: option<ref>})
 
 /** The primary a reader should show: the one chosen, else the first attached, so
     a set never shows no file while it holds one. The read model applies the same
@@ -137,6 +158,10 @@ let evolve = (t, fact) =>
       altTexts: t.altTexts->Array.filter(((r, _)) => r != ref),
     }
   | PrimarySet({ref}) => {...t, primary: Some(ref)}
+  // Carries no state of its own: it is what `effectivePrimary` already answers,
+  // said out loud. Folding it would be storing a derivation beside the values it
+  // derives from, which is the one way the two could disagree.
+  | EffectiveChanged(_) => t
   | AltTextSet({ref, altText}) => {
       ...t,
       altTexts: t.altTexts->Array.filter(((r, _)) => r != ref)->Array.concat([(ref, altText)]),
@@ -167,7 +192,7 @@ and an event log records both. Collapsing them into a single "replaced" fact
 would make a host declare an event that only bounded hosts have, which is one
 more way the two cardinalities' emitted surfaces could diverge.
 */
-let decide = (t, ~cardinality: cardinality=Many, op): result<array<fact>, [#NotAttached]> =>
+let decideFacts = (t, ~cardinality: cardinality=Many, op): result<array<fact>, [#NotAttached]> =>
   switch op {
   | Attach({ref, altText}) =>
     if t.attached->Array.includes(ref) {
@@ -179,12 +204,7 @@ let decide = (t, ~cardinality: cardinality=Many, op): result<array<fact>, [#NotA
       // individually rather than through `Clear` so the facts read the same
       // whether one was there or (through some history nothing produces) more.
       | Single =>
-        Ok(
-          Array.concat(
-            t.attached->Array.map(r => Removed({ref: r})),
-            [Attached({ref, altText})],
-          ),
-        )
+        Ok(Array.concat(t.attached->Array.map(r => Removed({ref: r})), [Attached({ref, altText})]))
       }
     }
   | Remove({ref}) => t.attached->Array.includes(ref) ? Ok([Removed({ref: ref})]) : Ok([])
@@ -206,3 +226,26 @@ let decide = (t, ~cardinality: cardinality=Many, op): result<array<fact>, [#NotA
     | None => Error(#NotAttached)
     }
   }
+
+/**
+The set's own facts, followed by `EffectiveChanged` when those facts moved which
+member a reader should show.
+
+Appended rather than woven into each arm because the question is the same one
+after every op: fold what was decided, ask `effectivePrimary` again, and say so
+if the answer differs. An arm that had to remember to announce would eventually
+be an arm that forgot — and the ops where it moves without anybody choosing (a
+first attachment, a removal that promotes the next) are exactly the ones where
+forgetting is easiest.
+*/
+let decide = (t, ~cardinality: cardinality=Many, op): result<array<fact>, [#NotAttached]> =>
+  switch decideFacts(t, ~cardinality, op) {
+  | Error(_) as e => e
+  | Ok(facts) =>
+    let after = facts->Array.reduce(t, evolve)
+    Ok(
+      effectivePrimary(t) == effectivePrimary(after)
+        ? facts
+        : facts->Array.concat([EffectiveChanged({ref: effectivePrimary(after)})]),
+    )
+  }

package/src/Attachments_Rules.res.mjs

@@ -1,6 +1,7 @@
 // Generated by ReScript, PLEASE EDIT WITH CARE
 
 import * as Sury from "sury";
+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 Primitive_object from "@rescript/runtime/lib/es6/Primitive_object.js";
 import * as Primitive_option from "@rescript/runtime/lib/es6/Primitive_option.js";
@@ -84,6 +85,8 @@ function evolve(t, fact) {
             fact.altText
           ]])
       };
+    case "EffectiveChanged" :
+      return t;
   }
 }
 
@@ -112,7 +115,7 @@ function setAltText(t, ref, altText) {
   }
 }
 
-function decide(t, cardinalityOpt, op) {
+function decideFacts(t, cardinalityOpt, op) {
   let cardinality = cardinalityOpt !== undefined ? cardinalityOpt : "Many";
   if (typeof op !== "object") {
     return {
@@ -209,6 +212,23 @@ function decide(t, cardinalityOpt, op) {
   }
 }
 
+function decide(t, cardinalityOpt, op) {
+  let cardinality = cardinalityOpt !== undefined ? cardinalityOpt : "Many";
+  let e = decideFacts(t, cardinality, op);
+  if (e.TAG !== "Ok") {
+    return e;
+  }
+  let facts = e._0;
+  let after = Stdlib_Array.reduce(facts, t, evolve);
+  return {
+    TAG: "Ok",
+    _0: Primitive_object.equal(effectivePrimary(t), effectivePrimary(after)) ? facts : facts.concat([{
+          TAG: "EffectiveChanged",
+          ref: effectivePrimary(after)
+        }])
+  };
+}
+
 export {
   cardinalitySchema,
   empty,
@@ -218,6 +238,7 @@ export {
   primaryFirst,
   evolve,
   setAltText,
+  decideFacts,
   decide,
 }
 /* cardinalitySchema Not a pure module */