@reventlessdev/trait-attachments 1.0.0-alpha.5 → 1.0.0-alpha.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reventlessdev/trait-attachments",
-  "version": "1.0.0-alpha.5",
+  "version": "1.0.0-alpha.7",
   "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": [
@@ -13,8 +13,8 @@
   "dependencies": {
     "sury": "11.0.0-rc.2",
     "sury-ppx": "11.0.0-rc.2",
-    "@reventlessdev/reventless-gwt": "1.0.0-alpha.203",
-    "@reventlessdev/reventless-spec": "3.0.0-alpha.129"
+    "@reventlessdev/reventless-spec": "3.0.0-alpha.131",
+    "@reventlessdev/reventless-gwt": "1.0.0-alpha.205"
   },
   "devDependencies": {
     "rescript": "12.3.0"

package/src/Attachments.res

@@ -43,13 +43,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 +74,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 +107,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 +135,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

@@ -17,13 +17,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 +37,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 +47,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 +61,48 @@ 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 +110,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 +133,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 +153,31 @@ 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 +190,17 @@ 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

@@ -77,6 +77,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 +156,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 +190,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) {
@@ -206,3 +229,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 */

package/src/Attachments_Scaffold.res

@@ -126,6 +126,7 @@ type names = {
   attached: string,
   removed: string,
   primarySet: string,
+  effectiveChanged: string,
   altTextSet: string,
   notFound: string,
   notAttached: string,
@@ -151,6 +152,9 @@ let namesOf = (c: config): names => {
     attached: subject ++ "Attached",
     removed: subject ++ "Removed",
     primarySet: c.entity ++ "Primary" ++ c.noun ++ "Set",
+    // Named for what it states — the one that now stands — rather than for the
+    // command that moved it, because most of the time no command did.
+    effectiveChanged: c.entity ++ "Effective" ++ c.noun ++ "Changed",
     altTextSet: subject ++ "AltTextSet",
     notFound: c.entity ++ "NotFound",
     notAttached: subject ++ "NotAttached",
@@ -335,6 +339,7 @@ let sliceSpec = (c: config): string => {
     `  | ${n.removed}({ ${c.file}: ${ref}})`,
     ...primaryArm(""),
     `  | ${n.altTextSet}({ ${c.file}: ${ref}, altText: string})`,
+    `  | ${n.effectiveChanged}({ ${c.file}?: ${ref}})`,
     `  // TODO(graft): add the events this host's own refusal turns on — whatever`,
     `  // moves it into a state where attachments may not be changed.`,
     ``,
@@ -385,6 +390,10 @@ let sliceSpec = (c: config): string => {
     `  | ${n.removed}({ ${c.entityId}: string, ${c.file}: ${ref}})`,
     ...primaryArm(`${c.entityId}: string, `),
     `  | ${n.altTextSet}({ ${c.entityId}: string, ${c.file}: ${ref}, altText: string})`,
+    `  // The member a reader should now show, or none. A conclusion rather than a`,
+    `  // decision: most of the moves that change it — a first attachment, a removal`,
+    `  // promoting the next — are nobody's choice, so nothing else announces them.`,
+    `  | ${n.effectiveChanged}({ ${c.entityId}: string, ${c.file}?: ${ref}})`,
     ``,
     ...commandTransitionBinding(c),
     `// The graft's own record of itself. Nothing else survives into a deployed`,
@@ -426,6 +435,7 @@ let sliceBehavior = (c: config): string => {
       ? []
       : [`  | ${n.primarySet}({${c.file}}) => fold(PrimarySet({ref: ${c.file}}))`]),
     `  | ${n.altTextSet}({${c.file}, altText}) => fold(AltTextSet({ref: ${c.file}, altText}))`,
+    `  | ${n.effectiveChanged}({${c.file}: ?ref}) => fold(EffectiveChanged({ref: ref}))`,
     `  // TODO(graft): fold this host's own events into its own state.`,
     `  }`,
     `}`,
@@ -492,6 +502,10 @@ let sliceBehavior = (c: config): string => {
     `    ${single ? "Some(" : ""}${n.altTextSet}({${c.entityId}, ${c.file}: ref, altText})${single
         ? ")"
         : ""}`,
+    `  | Attachments.EffectiveChanged({ref}) =>`,
+    `    ${single ? "Some(" : ""}${n.effectiveChanged}({${c.entityId}, ${c.file}: ?ref})${single
+        ? ")"
+        : ""}`,
     `  }`,
     ``,
     `let decide = (state, command) =>`,
@@ -544,16 +558,22 @@ let conformanceBinding = (c: config): string => {
     `  module Behavior = ${n.slice}_Behavior`,
     ``,
     `  // Annotated: the slice consumes and emits same-named constructors.`,
-    `  let created: array<${n.slice}.consumedEvent> = [${createdValue}]`,
-    `  let attachedC = (ref): ${n.slice}.consumedEvent => ${n.attached}({ ${c.file}: ref})`,
-    `  let removedC = (ref): ${n.slice}.consumedEvent => ${n.removed}({ ${c.file}: ref})`,
+    `  // The same facts as the slice consumes them: no ${c.entityId}, because the`,
+    `  // partition already says which entity they belong to.`,
+    `  module Consumed = {`,
+    `    let created: array<${n.slice}.consumedEvent> = [${createdValue}]`,
+    `    let attached = (ref): ${n.slice}.consumedEvent => ${n.attached}({ ${c.file}: ref})`,
+    `    let removed = (ref): ${n.slice}.consumedEvent => ${n.removed}({ ${c.file}: ref})`,
     ...(single
       ? []
       : [
-          `  let primarySetC = (ref): ${n.slice}.consumedEvent => ${n.primarySet}({ ${c.file}: ref})`,
+          `    let primarySet = (ref): ${n.slice}.consumedEvent => ${n.primarySet}({ ${c.file}: ref})`,
         ]),
-    `  let altTextSetC = (ref, altText): ${n.slice}.consumedEvent =>`,
-    `    ${n.altTextSet}({ ${c.file}: ref, altText})`,
+    `    let altTextSet = (ref, altText): ${n.slice}.consumedEvent =>`,
+    `      ${n.altTextSet}({ ${c.file}: ref, altText})`,
+    `    let effectiveChanged = (ref): ${n.slice}.consumedEvent =>`,
+    `      ${n.effectiveChanged}({ ${c.file}: ?ref})`,
+    `  }`,
     ``,
     `  let attach = ref => ${n.slice}.${n.attachCmd}({ ${c.entityId}: "${id}", ${c.file}: ref})`,
     ...(single
@@ -577,6 +597,8 @@ let conformanceBinding = (c: config): string => {
         ]),
     `  let altTextSet = (ref, altText) =>`,
     `    ${n.slice}.${n.altTextSet}({ ${c.entityId}: "${id}", ${c.file}: ref, altText})`,
+    `  let effectiveChanged = ref =>`,
+    `    ${n.slice}.${n.effectiveChanged}({ ${c.entityId}: "${id}", ${c.file}: ?ref})`,
     `  let notAttached = ${n.slice}.${n.notAttached}`,
     `}`,
     ``,

package/src/Attachments_Scaffold.res.mjs

@@ -43,6 +43,7 @@ function namesOf(c) {
     attached: subject + "Attached",
     removed: subject + "Removed",
     primarySet: c.entity + "Primary" + c.noun + "Set",
+    effectiveChanged: c.entity + "Effective" + c.noun + "Changed",
     altTextSet: subject + "AltTextSet",
     notFound: c.entity + "NotFound",
     notAttached: subject + "NotAttached"
@@ -189,6 +190,7 @@ function sliceSpec(c) {
     primaryArm(""),
     [
       `  | ` + n.altTextSet + `({ ` + c.file + `: ` + ref + `, altText: string})`,
+      `  | ` + n.effectiveChanged + `({ ` + c.file + `?: ` + ref + `})`,
       `  // TODO(graft): add the events this host's own refusal turns on — whatever`,
       `  // moves it into a state where attachments may not be changed.`,
       ``
@@ -235,6 +237,10 @@ function sliceSpec(c) {
     primaryArm(c.entityId + `: string, `),
     [
       `  | ` + n.altTextSet + `({ ` + c.entityId + `: string, ` + c.file + `: ` + ref + `, altText: string})`,
+      `  // The member a reader should now show, or none. A conclusion rather than a`,
+      `  // decision: most of the moves that change it — a first attachment, a removal`,
+      `  // promoting the next — are nobody's choice, so nothing else announces them.`,
+      `  | ` + n.effectiveChanged + `({ ` + c.entityId + `: string, ` + c.file + `?: ` + ref + `})`,
       ``
     ],
     commandTransitionBinding(c),
@@ -273,6 +279,7 @@ function sliceBehavior(c) {
     single ? [] : [`  | ` + n.primarySet + `({` + c.file + `}) => fold(PrimarySet({ref: ` + c.file + `}))`],
     [
       `  | ` + n.altTextSet + `({` + c.file + `, altText}) => fold(AltTextSet({ref: ` + c.file + `, altText}))`,
+      `  | ` + n.effectiveChanged + `({` + c.file + `: ?ref}) => fold(EffectiveChanged({ref: ref}))`,
       `  // TODO(graft): fold this host's own events into its own state.`,
       `  }`,
       `}`,
@@ -332,6 +339,12 @@ function sliceBehavior(c) {
       ) + n.altTextSet + `({` + c.entityId + `, ` + c.file + `: ref, altText})` + (
         single ? ")" : ""
       ),
+      `  | Attachments.EffectiveChanged({ref}) =>`,
+      `    ` + (
+        single ? "Some(" : ""
+      ) + n.effectiveChanged + `({` + c.entityId + `, ` + c.file + `: ?ref})` + (
+        single ? ")" : ""
+      ),
       `  }`,
       ``,
       `let decide = (state, command) =>`,
@@ -373,14 +386,20 @@ function conformanceBinding(c) {
       `  module Behavior = ` + n.slice + `_Behavior`,
       ``,
       `  // Annotated: the slice consumes and emits same-named constructors.`,
-      `  let created: array<` + n.slice + `.consumedEvent> = [` + createdValue + `]`,
-      `  let attachedC = (ref): ` + n.slice + `.consumedEvent => ` + n.attached + `({ ` + c.file + `: ref})`,
-      `  let removedC = (ref): ` + n.slice + `.consumedEvent => ` + n.removed + `({ ` + c.file + `: ref})`
+      `  // The same facts as the slice consumes them: no ` + c.entityId + `, because the`,
+      `  // partition already says which entity they belong to.`,
+      `  module Consumed = {`,
+      `    let created: array<` + n.slice + `.consumedEvent> = [` + createdValue + `]`,
+      `    let attached = (ref): ` + n.slice + `.consumedEvent => ` + n.attached + `({ ` + c.file + `: ref})`,
+      `    let removed = (ref): ` + n.slice + `.consumedEvent => ` + n.removed + `({ ` + c.file + `: ref})`
     ],
-    single ? [] : [`  let primarySetC = (ref): ` + n.slice + `.consumedEvent => ` + n.primarySet + `({ ` + c.file + `: ref})`],
+    single ? [] : [`    let primarySet = (ref): ` + n.slice + `.consumedEvent => ` + n.primarySet + `({ ` + c.file + `: ref})`],
     [
-      `  let altTextSetC = (ref, altText): ` + n.slice + `.consumedEvent =>`,
-      `    ` + n.altTextSet + `({ ` + c.file + `: ref, altText})`,
+      `    let altTextSet = (ref, altText): ` + n.slice + `.consumedEvent =>`,
+      `      ` + n.altTextSet + `({ ` + c.file + `: ref, altText})`,
+      `    let effectiveChanged = (ref): ` + n.slice + `.consumedEvent =>`,
+      `      ` + n.effectiveChanged + `({ ` + c.file + `: ?ref})`,
+      `  }`,
       ``,
       `  let attach = ref => ` + n.slice + `.` + n.attachCmd + `({ ` + c.entityId + `: "` + id + `", ` + c.file + `: ref})`
     ],
@@ -402,6 +421,8 @@ function conformanceBinding(c) {
     [
       `  let altTextSet = (ref, altText) =>`,
       `    ` + n.slice + `.` + n.altTextSet + `({ ` + c.entityId + `: "` + id + `", ` + c.file + `: ref, altText})`,
+      `  let effectiveChanged = ref =>`,
+      `    ` + n.slice + `.` + n.effectiveChanged + `({ ` + c.entityId + `: "` + id + `", ` + c.file + `: ?ref})`,
       `  let notAttached = ` + n.slice + `.` + n.notAttached,
       `}`,
       ``,