@reventlessdev/trait-attachments 1.0.0-alpha.1

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2019-2026 Martin Lorenz
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,62 @@
+# @reventlessdev/trait-attachments
+
+A **domain trait**: an ordered set of stored files on an entity — attach, remove,
+choose the primary, caption — as domain facts. The rules are a module the host calls;
+the types are the host's own:
+
+| Part | Where |
+|---|---|
+| The set's rules | `src/Attachments_Rules.res` (`empty`, `op`, `fact`, `decide`, `evolve`, `primaryOf`) |
+| The host contract, as a type | `src/Attachments.res` (`module type Binding`) |
+| The conformance suite | `src/Attachments_Conformance.res` (`Make(Binding).register()`) |
+| The emitter | `src/Attachments_Scaffold.res` (`emit(~config, ~into, ~tests)`) |
+
+`Attachments_Rules` is compiled code a host imports at runtime, so a change to it is a
+behavior change for every host: version it `fix:`/`feat:` accordingly.
+
+The graft *is* a StateChangeSlice, so the emitter writes nearly all of it: the slice
+spec, its behavior and the conformance binding, whole. Only the view's projection is
+printed as a patch — the view already exists, and placing an arm in an ordered `switch`
+is an AST operation a text splice gets silently wrong.
+
+Storage is the platform's (`UploadableImage.t` names the store; mint, presign and
+pending-expiry are shipped). This package owns the rules of the *set*:
+
+- **Attach and remove are idempotent** — a ref already in the set, or already out
+  of it, appends nothing; a removed ref can come back.
+- **The primary is one of the set.** Until one is chosen the first attached stands
+  in; choosing the current primary appends nothing; removing the chosen one lets
+  the first remaining stand in again.
+- **A caption belongs to a member** — refused for a ref that is not attached,
+  a no-op when repeated.
+- **The read model carries the primary as one string** beside the set, so a card
+  or a gallery tile has an image to draw without reading the set.
+
+Unlike the geocoding trait this one writes nothing back into its host: the graft
+*is* a StateChangeSlice of the host, so the contract is over that slice.
+
+## Grafting a host
+
+1. Run the emitter. Every `--key` is a field of its config, and it validates them, so
+   run it once to be told what it wants:
+
+```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
+```
+
+   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.
+
+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
+   ahead of the set's rules. A graft with no extra refusal is a complete graft, so
+   leaving them is legitimate.
+
+3. Paste the projection patch, and run the emitted conformance binding — 14 assertions,
+   over your constructors, not the trait's.
+
+The specimen hosts are `examples/online-shop-hybrid/catalog`'s `ProductImages` and
+`CategoryImages`.

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@reventlessdev/trait-attachments",
+  "version": "1.0.0-alpha.1",
+  "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": [
+    "src/**/*.res",
+    "src/**/*.resi",
+    "src/**/*.res.mjs",
+    "rescript.json",
+    "README.md"
+  ],
+  "dependencies": {
+    "sury": "11.0.0-rc.2",
+    "sury-ppx": "11.0.0-rc.2",
+    "@reventlessdev/reventless-gwt": "1.0.0-alpha.199",
+    "@reventlessdev/reventless-spec": "3.0.0-alpha.125"
+  },
+  "devDependencies": {
+    "rescript": "12.3.0"
+  },
+  "peerDependencies": {
+    "rescript": "12.3.0"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ReventlessDev/reventless-core.git",
+    "directory": "traits/attachments"
+  },
+  "scripts": {
+    "build": "rescript build",
+    "start": "rescript watch",
+    "clean": "rescript clean",
+    "rebuild": "pnpm run clean && pnpm run build",
+    "test": "echo \"The conformance suite runs in its hosts; see README.md.\""
+  }
+}

package/rescript.json

@@ -0,0 +1,27 @@
+{
+  "name": "@reventlessdev/trait-attachments",
+  "package-specs": {
+    "module": "esmodule",
+    "in-source": true
+  },
+  "namespace": "TraitAttachments",
+  "ppx-flags": [
+    "sury-ppx/bin"
+  ],
+  "warnings": {
+    "error": "-44+101"
+  },
+  "sources": [
+    {
+      "dir": "src",
+      "subdirs": true
+    }
+  ],
+  "dependencies": [
+    "sury",
+    "@reventlessdev/reventless-spec",
+    "@reventlessdev/reventless-gwt"
+  ],
+  "compiler-flags": [],
+  "suffix": ".res.mjs"
+}

package/src/Attachments.res

@@ -0,0 +1,66 @@
+/**
+The host contract of the attachments trait: an ordered set of stored files on
+an entity, with a primary and a caption per member. Unlike the geocoding trait this
+one writes nothing back — the graft *is* a StateChangeSlice of the host — so the
+contract is over that slice. The rules live in `Attachments_Rules` and are asserted
+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.
+
+`WritesBack`: the graft's commands append this trait's facts onto the host's own
+slice, which is what a host grafting it is asking for.
+*/
+let declaration: Reventless.Trait.t = {
+  trait: "@reventlessdev/trait-attachments",
+  version: Reventless.PackageVersion.fromModuleUrl(%raw(`import.meta.url`)),
+  posture: WritesBack,
+}
+
+/**
+The platform capabilities a host of this trait needs: **none**.
+
+Not an oversight and not a placeholder. What this trait needs is an object
+*store*, and a store need is declared by the field that carries `@storageRef` —
+it travels as `pluginStructure.requiredStores`, keyed by `(plugin, store)`, and
+`CapabilityNeed` deliberately excludes it. So the empty list is the true answer,
+and stating it lets a listing distinguish "needs nothing brokered" from "nobody
+has said".
+*/
+let capabilityNeeds: array<Reventless.CapabilityNeed.t> = []
+
+/** One host, bound. `ref` is the stored file's reference (a `StorageRef` today),
+    abstract so a richer attachment identity is a re-instantiation, not a break. */
+module type Binding = {
+  type ref
+  /** Two refs that differ. */
+  let refA: ref
+  let refB: ref
+
+  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
+
+  let attach: ref => Spec.command
+  let remove: ref => Spec.command
+  let setPrimary: ref => Spec.command
+  let setAltText: (ref, string) => Spec.command
+
+  /** The set's facts, as the slice emits them. */
+  let attached: ref => Spec.event
+  let removed: ref => Spec.event
+  let primarySet: 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
+}

package/src/Attachments.res.mjs

@@ -0,0 +1,19 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as PackageVersion$Reventless from "@reventlessdev/reventless-spec/src/PackageVersion.res.mjs";
+
+let declaration_version = PackageVersion$Reventless.fromModuleUrl(import.meta.url);
+
+let declaration = {
+  trait: "@reventlessdev/trait-attachments",
+  version: declaration_version,
+  posture: "WritesBack"
+};
+
+let capabilityNeeds = [];
+
+export {
+  declaration,
+  capabilityNeeds,
+}
+/* declaration Not a pure module */

package/src/Attachments_Conformance.res

@@ -0,0 +1,88 @@
+/**
+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
+    other's prose. */
+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 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.test("attaching a ref already in the set is a no-op", () =>
+        G.givenEvents(withA)->G.whenCmd(B.attach(B.refA))->G.thenNoEvent
+      )
+
+      G.test("a second ref extends the set rather than replacing it", () =>
+        G.givenEvents(withA)->G.whenCmd(B.attach(B.refB))->G.thenEvent(B.attached(B.refB))
+      )
+
+      G.test("removing an attached ref is appended", () =>
+        G.givenEvents(withA)->G.whenCmd(B.remove(B.refA))->G.thenEvent(B.removed(B.refA))
+      )
+
+      G.test("removing a ref not in the set is a no-op", () =>
+        G.givenEvents(withA)->G.whenCmd(B.remove(B.refB))->G.thenNoEvent
+      )
+
+      G.test("a removed ref can be attached again", () =>
+        G.givenEvents(Array.concat(withA, [B.removedC(B.refA)]))
+        ->G.whenCmd(B.attach(B.refA))
+        ->G.thenEvent(B.attached(B.refA))
+      )
+
+      G.test("the primary must be in the set", () =>
+        G.givenEvents(withA)->G.whenCmd(B.setPrimary(B.refB))->G.thenError(B.notAttached)
+      )
+
+      G.test("the first attached is the primary until one is chosen", () =>
+        G.givenEvents(withAB)->G.whenCmd(B.setPrimary(B.refA))->G.thenNoEvent
+      )
+
+      G.test("choosing another primary is appended", () =>
+        G.givenEvents(withAB)->G.whenCmd(B.setPrimary(B.refB))->G.thenEvent(B.primarySet(B.refB))
+      )
+
+      G.test("choosing the current primary is a no-op", () =>
+        G.givenEvents(Array.concat(withAB, [B.primarySetC(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.whenCmd(B.setPrimary(B.refA))
+        ->G.thenNoEvent
+      )
+
+      G.test("a caption needs its ref in the set", () =>
+        G.givenEvents(withA)
+        ->G.whenCmd(B.setAltText(B.refB, "side"))
+        ->G.thenError(B.notAttached)
+      )
+
+      G.test("a caption is appended", () =>
+        G.givenEvents(withA)
+        ->G.whenCmd(B.setAltText(B.refA, "front"))
+        ->G.thenEvent(B.altTextSet(B.refA, "front"))
+      )
+
+      G.test("repeating the caption is a no-op", () =>
+        G.givenEvents(Array.concat(withA, [B.altTextSetC(B.refA, "front")]))
+        ->G.whenCmd(B.setAltText(B.refA, "front"))
+        ->G.thenNoEvent
+      )
+    })
+}

package/src/Attachments_Conformance.res.mjs

@@ -0,0 +1,49 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Behavior_GWT$ReventlessGwt from "@reventlessdev/reventless-gwt/src/Behavior_GWT.res.mjs";
+
+function suiteName(host) {
+  return host + ` conforms to the attachments trait`;
+}
+
+function Make(B) {
+  let $$let = B.Behavior;
+  let G = Behavior_GWT$ReventlessGwt.Make(B.Spec)({
+    initialState: $$let.initialState,
+    evolve: $$let.evolve,
+    decide: $$let.decide
+  });
+  let withA = B.created.concat([B.attachedC(B.refA)]);
+  let withAB = withA.concat([B.attachedC(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("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 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("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("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.setPrimary(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"))));
+  });
+  return {
+    G: G,
+    withA: withA,
+    withAB: withAB,
+    register: register
+  };
+}
+
+export {
+  suiteName,
+  Make,
+}
+/* Behavior_GWT-ReventlessGwt Not a pure module */

package/src/Attachments_Rules.res

@@ -0,0 +1,101 @@
+/**
+The set's rules, compiled once and called by every host: attach and remove are
+idempotent, the primary is one of the set with the first attached standing in
+until one is chosen, and a caption belongs to a member.
+
+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
+
+/** Refolded per decision, never stored — a StateChangeSlice's state is. */
+type t = {
+  attached: array<ref>,
+  /** Only the one chosen explicitly; see `effectivePrimary`. */
+  primary: option<ref>,
+  altTexts: array<(ref, string)>,
+}
+
+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>})
+  | Remove({ref: ref})
+  | SetPrimary({ref: ref})
+  | SetAltText({ref: ref, altText: string})
+
+/** What the set decided, for the host to name in its own event. */
+type fact =
+  | Attached({ref: ref, altText: option<string>})
+  | Removed({ref: ref})
+  | PrimarySet({ref: ref})
+  | AltTextSet({ref: ref, altText: string})
+
+/** 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
+    rule over its own rows, which is why this takes the two values and not `t`. */
+let primaryOf = (~chosen: option<ref>, ~attached: array<ref>) =>
+  switch chosen {
+  | Some(_) as p => p
+  | None => attached->Array.get(0)
+  }
+
+let effectivePrimary = t => primaryOf(~chosen=t.primary, ~attached=t.attached)
+
+let altTextOf = (t, ref) => t.altTexts->Array.find(((r, _)) => r == ref)->Option.map(((_, t)) => t)
+
+let evolve = (t, fact) =>
+  switch fact {
+  | Attached({ref, altText}) =>
+    t.attached->Array.includes(ref)
+      ? t
+      : {
+          ...t,
+          attached: t.attached->Array.concat([ref]),
+          altTexts: switch altText {
+          | Some(text) => t.altTexts->Array.concat([(ref, text)])
+          | None => t.altTexts
+          },
+        }
+  | Removed({ref}) => {
+      attached: t.attached->Array.filter(r => r != ref),
+      primary: t.primary == Some(ref) ? None : t.primary,
+      altTexts: t.altTexts->Array.filter(((r, _)) => r != ref),
+    }
+  | PrimarySet({ref}) => {...t, primary: Some(ref)}
+  | AltTextSet({ref, altText}) => {
+      ...t,
+      altTexts: t.altTexts->Array.filter(((r, _)) => r != ref)->Array.concat([(ref, altText)]),
+    }
+  }
+
+/** `Ok(None)` is the no-op a retried command must produce; the one refusal the set
+    owns is a primary or a caption on a ref it does not hold. */
+let decide = (t, op): result<option<fact>, [#NotAttached]> =>
+  switch op {
+  | Attach({ref, altText}) =>
+    t.attached->Array.includes(ref) ? Ok(None) : Ok(Some(Attached({ref, altText})))
+  | Remove({ref}) => t.attached->Array.includes(ref) ? Ok(Some(Removed({ref: ref}))) : Ok(None)
+  | SetPrimary({ref}) =>
+    if !(t.attached->Array.includes(ref)) {
+      Error(#NotAttached)
+    } else if effectivePrimary(t) == Some(ref) {
+      Ok(None)
+    } else {
+      Ok(Some(PrimarySet({ref: ref})))
+    }
+  | SetAltText({ref, altText}) =>
+    if !(t.attached->Array.includes(ref)) {
+      Error(#NotAttached)
+    } else if altTextOf(t, ref) == Some(altText) {
+      Ok(None)
+    } else {
+      Ok(Some(AltTextSet({ref, altText})))
+    }
+  }