@reventlessdev/trait-notification 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,110 @@
+# @reventlessdev/trait-notification
+
+A **domain trait**: telling somebody something happened. It holds a per-recipient
+contact directory and a kind × channel subscription matrix, and decides — per
+request — whether that becomes an addressed message, a suppression, or a record
+that nobody could be reached. The rules are a module the host calls; the types are
+the host's own:
+
+| Part | Where |
+|---|---|
+| The competency's rules | `src/Notification_Rules.res` (`empty`, `op`, `fact`, `decide`, `evolve`, `addressFor`) |
+| The host contract, as a type | `src/Notification.res` (`module type Binding`) |
+| The conformance suite | `src/Notification_Conformance.res` (`Make(Binding).register()`) |
+| The emitter | `src/Notification_Scaffold.res` (`emit(~config, ~into, ~tests)`) |
+
+`Notification_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.
+
+## What makes this one different
+
+The first two traits add arms to something the host already had. This one **brings
+its own components**: a StateChangeSlice, an outbound send, and two views, none of
+which the host had before. So the emitter writes more than either of the others —
+five files whole — and the host's part shrinks to two **relays**, which are printed
+rather than written because what a host's events *mean* is the one thing a trait
+cannot be told in names.
+
+It also never writes to the host. Not one field, not one arm: the directory, the
+matrix and the delivery log are all the trait's own state, so a host can graft this
+onto components that have no opinion about mail at all.
+
+## The rules it owns
+
+- **The address is resolved when the message is composed, not when the occurrence
+  happened.** A request names a recipient and a kind; the address comes off the
+  directory at decision time. Putting it on the occurrence instead would freeze a
+  mutable fact into an append-only log, and a recipient who changed their address
+  would have old occurrences confirmed to the old one.
+- **An absent choice falls back to a posture the host supplies.** The rule is the
+  trait's; the table is not — whether an unheard-from recipient should be notified
+  is per kind and per host, and a trait that hard-coded either answer would be
+  wrong for half of them.
+- **Three ways to send nothing, and they stay three facts.** A recipient who
+  declined is `Suppressed`; one who enabled a channel nobody holds an address for
+  is `Undeliverable`; one nobody announced is `Undeliverable` too. Collapsing the
+  second into the first would hide every delivery gap behind a legitimate
+  preference, permanently.
+- **Announcing an address already on file appends nothing.** The relay that feeds
+  it re-announces on every contact event a host publishes, and its row completes
+  on the publish rather than on an event coming back — so the no-op is safe, and
+  recording a change that did not happen would not be.
+
+Delivery itself is the platform's: the send slice reaches
+`Reventless.Capabilities.messaging`, declares the `Messaging` capability need, and
+takes its retry split from `Reventless.Messaging.retriable`.
+
+## Grafting a host
+
+1. **Run the emitter.** Every `--key` is a field of its config, and it validates
+   them, so a misspelled one is refused before anything is written.
+
+   ```
+   pnpm exec graft-trait @reventlessdev/trait-notification \
+     --into src/Notification --tests tests/Notification \
+     --chapter Notification --noun Recipient \
+     --categories OrderConfirmation,ShippingUpdate,Marketing \
+     --transactional OrderConfirmation,ShippingUpdate \
+     --contactSource Customer --contactEvents Registered,EmailUpdated \
+     --contactField email \
+     --occurrence OrderPlaced --occurrenceId orderId \
+     --occurrenceRecipient customerId --occurrenceCategory OrderConfirmation
+   ```
+
+2. **Write the two printed relays.** They arrive with their shape filled in and
+   their meaning marked `TODO(graft)`: which of your events announce a contact,
+   and what your notification actually says. The contact relay is an
+   `OutboundTranslationSlice` rather than an automation on purpose — an
+   automation's mapping is handed no source id, and an aggregate's event does not
+   repeat the id that addressed it.
+
+3. **Fill the emitted `TODO(graft)` markers.** The posture table, and the wording.
+   Nothing else is left open.
+
+4. **Provision a sender.** The send slice declares `Messaging`, so a deployment
+   that provisions none fails the deploy rather than queueing every message until
+   it is abandoned.
+
+## What the suite checks, and what it does not
+
+`Notification_Conformance` asserts the directory, the posture fallback, and the
+three ways to send nothing. It says nothing about your wording, your
+authorization, or what your views render — those are yours, and a rule the suite
+covers must not also live in your own tests.
+
+Two `Binding` members exist for the suite's sake and are worth reading before you
+fill them: `transactional` and `optional` must be kinds whose posture actually
+differs, and `unreachableChannel` is a channel your host announces no address for.
+A host that announces every channel it offers passes `None` and two assertions are
+skipped — which is the honest outcome, not a gap.
+
+## Limits worth knowing
+
+- **One address per channel.** An email is one address per person; a push token is
+  one per *install*, and a set that churns. The directory's shape allows several
+  channels but the announce path carries one address, so push is expressible and
+  not yet reachable — a recipient who enables it is recorded `Undeliverable`
+  rather than quietly skipped.
+- **No dedupe on `reference`.** The relay upstream is a TODO list, which publishes
+  once per item and resolves on the outcome. Keeping every reference ever seen in
+  a snapshotted state to re-check that guarantee would cost more than it buys.

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@reventlessdev/trait-notification",
+  "version": "1.0.0-alpha.1",
+  "description": "Notification domain trait: rules, host contract, conformance suite and emitter for a per-recipient contact directory, a kind x channel subscription matrix, and the decision to send, suppress or record a message as undeliverable",
+  "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/notification"
+  },
+  "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-notification",
+  "package-specs": {
+    "module": "esmodule",
+    "in-source": true
+  },
+  "namespace": "TraitNotification",
+  "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/Notification.res

@@ -0,0 +1,105 @@
+/**
+The host contract of the notification trait: a per-recipient contact directory, a
+kind × channel subscription matrix, and the decision to send, suppress or record
+a message as undeliverable.
+
+Like the attachments trait and unlike the geocoding one, the graft *is* a
+StateChangeSlice of the host, so the contract is over that slice. Unlike either,
+this trait **brings its own components** rather than adding arms to something the
+host already had — the slice, the send, and both views are its own, and only the
+two relays that feed it are shaped by the host.
+
+The rules live in `Notification_Rules` and are asserted through a host by
+`Notification_Conformance`; the spec surface the host maps onto them is written by
+`Notification_Scaffold`.
+
+## What this trait refuses to know
+
+What an occurrence *is*. It is told a recipient, a kind, and a reference; it is
+never told there was an order. That is why the two relays are the only files a
+graft has to be given, and everything else can be handed over whole.
+*/
+
+/**
+This trait's own account of itself — see `AddressGeocoding.declaration` for why the
+version is read rather than written.
+
+`SelfContained` is the whole reason this specimen was built third: it brings its own
+components and grafts by reading host events alone, writing nothing back. The two
+earlier traits share a posture; this one is the reason `posture` exists.
+*/
+let declaration: Reventless.Trait.t = {
+  trait: "@reventlessdev/trait-notification",
+  version: Reventless.PackageVersion.fromModuleUrl(%raw(`import.meta.url`)),
+  posture: SelfContained,
+}
+
+/**
+The platform capabilities a host of this trait needs, for its send slice's
+`capabilityNeeds` to name.
+
+Exported as a value rather than written into the emitted text, for the reason the
+geocoding trait exports its own: forgetting it is silent. An unprovisioned sender
+answers `Unavailable`, every send retries its budget, and every message this host
+was ever asked for is recorded as failed — a permanent wrong outcome with no error
+anywhere. A host that spells this gets a deploy-time refusal instead.
+
+It is also what lets a listing say what the trait needs without running the
+emitter: a literal buried in generated text is not a fact anything can read.
+*/
+let capabilityNeeds: array<Reventless.CapabilityNeed.t> = [Messaging]
+
+/** One host, bound.
+
+    `category` is abstract: a host's kinds are its own vocabulary, and the rules
+    hold for any of them. `posture` is the host's answer to the one question the
+    rules cannot settle — whether an unheard-from recipient should be notified —
+    and it is a member rather than a constant because it is per category. */
+module type Binding = {
+  /** The host's own kind-of-notification type. */
+  type category
+  /** Two kinds that differ in posture: one an unheard-from recipient gets, and
+      one they do not. A host with only transactional kinds cannot satisfy this,
+      which is the suite refusing to certify a matrix with nothing to choose. */
+  let transactional: category
+  let optional: category
+
+  module Spec: ReventlessGwt.Behavior_GWT.BehaviorSpec
+  module Behavior: ReventlessGwt.Behavior_GWT.Behavior with module Spec = Spec
+
+  /** History that brings the recipient into existence with nothing on file. */
+  let created: array<Spec.consumedEvent>
+
+  /** The competency's own facts, as the slice consumes them. */
+  let announcedC: string => Spec.consumedEvent
+  let subscribedC: (category, Notification_Rules.channel) => Spec.consumedEvent
+  let unsubscribedC: (category, Notification_Rules.channel) => Spec.consumedEvent
+
+  let announce: string => Spec.command
+  let subscribe: (category, Notification_Rules.channel) => Spec.command
+  let unsubscribe: (category, Notification_Rules.channel) => Spec.command
+  /** `reference` is the requester's key, echoed on whichever outcome follows. */
+  let request: (category, string) => Spec.command
+
+  /** The competency's facts, as the slice emits them. */
+  let announced: string => Spec.event
+  let subscribed: (category, Notification_Rules.channel) => Spec.event
+  let unsubscribed: (category, Notification_Rules.channel) => Spec.event
+  let requested: (category, string, Notification_Rules.channel, string) => Spec.event
+  let suppressed: (category, string) => Spec.event
+  let undeliverable: (category, string) => Spec.event
+
+  /** The refusal for managing preferences for somebody nobody has announced. */
+  let recipientUnknown: Spec.error
+
+  /** An address the host's announce command accepts, and the channel it lands on.
+      Email today for every host; named rather than assumed so the suite asserts
+      against the channel the host actually announces. */
+  let addressA: string
+  let addressB: string
+  let announcedChannel: Notification_Rules.channel
+  /** A channel the host announces no address for, so the suite can tell
+      "unreachable" apart from "not wanted". `None` for a host that announces
+      every channel it offers — the two assertions that need it are skipped. */
+  let unreachableChannel: option<Notification_Rules.channel>
+}

package/src/Notification.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-notification",
+  version: declaration_version,
+  posture: "SelfContained"
+};
+
+let capabilityNeeds = ["Messaging"];
+
+export {
+  declaration,
+  capabilityNeeds,
+}
+/* declaration Not a pure module */

package/src/Notification_Conformance.res

@@ -0,0 +1,137 @@
+/**
+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.
+
+What it asserts is the competency, not the host: the directory, the fallback to
+the host's posture, and — the part worth being strict about — that the three ways
+to send nothing stay three different facts.
+*/
+
+/** 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 notification trait`
+
+module Make = (B: Notification.Binding) => {
+  module G = ReventlessGwt.Behavior_GWT.Make(B.Spec, B.Behavior)
+  module R = Notification_Rules
+
+  let announced = Array.concat(B.created, [B.announcedC(B.addressA)])
+
+  let register = () =>
+    G.describe(suiteName(B.Spec.name), () => {
+      G.test("an announced contact is recorded", () =>
+        G.givenEvents(B.created)->G.whenCmd(B.announce(B.addressA))->G.thenEvent(
+          B.announced(B.addressA),
+        )
+      )
+
+      // The relay re-announces on every contact event a host publishes, and its
+      // row completes on the publish rather than on an event coming back — so
+      // saying nothing is safe here, and recording a change that did not happen
+      // is not.
+      G.test("re-announcing the address already on file is a no-op", () =>
+        G.givenEvents(announced)->G.whenCmd(B.announce(B.addressA))->G.thenNoEvent
+      )
+
+      G.test("a changed address is recorded", () =>
+        G.givenEvents(announced)->G.whenCmd(B.announce(B.addressB))->G.thenEvent(
+          B.announced(B.addressB),
+        )
+      )
+
+      // A person is at the other end of this one, so they are told rather than
+      // having a fact recorded about them.
+      G.test("managing preferences for an unannounced recipient is refused", () =>
+        G.givenEvents(B.created)
+        ->G.whenCmd(B.subscribe(B.optional, B.announcedChannel))
+        ->G.thenError(B.recipientUnknown)
+      )
+
+      G.test("opting in to a kind that is off by default is recorded", () =>
+        G.givenEvents(announced)
+        ->G.whenCmd(B.subscribe(B.optional, B.announcedChannel))
+        ->G.thenEvent(B.subscribed(B.optional, B.announcedChannel))
+      )
+
+      // Already on by the host's posture. Recording a subscription would say the
+      // recipient chose something they did not, and a later posture change would
+      // then not reach them.
+      G.test("subscribing to a kind already on by posture is a no-op", () =>
+        G.givenEvents(announced)
+        ->G.whenCmd(B.subscribe(B.transactional, B.announcedChannel))
+        ->G.thenNoEvent
+      )
+
+      G.test("opting out of a kind that is on is recorded", () =>
+        G.givenEvents(announced)
+        ->G.whenCmd(B.unsubscribe(B.transactional, B.announcedChannel))
+        ->G.thenEvent(B.unsubscribed(B.transactional, B.announcedChannel))
+      )
+
+      G.test("opting out of a kind already off is a no-op", () =>
+        G.givenEvents(announced)
+        ->G.whenCmd(B.unsubscribe(B.optional, B.announcedChannel))
+        ->G.thenNoEvent
+      )
+
+      // The posture doing its job: somebody who has never seen a settings screen
+      // still gets what they asked for by acting.
+      G.test("a transactional request goes out with no explicit subscription", () =>
+        G.givenEvents(announced)
+        ->G.whenCmd(B.request(B.transactional, "ref-1"))
+        ->G.thenEvent(
+          B.requested(B.transactional, "ref-1", B.announcedChannel, B.addressA),
+        )
+      )
+
+      G.test("the address on the request is the one currently on file", () =>
+        G.givenEvents(Array.concat(announced, [B.announcedC(B.addressB)]))
+        ->G.whenCmd(B.request(B.transactional, "ref-1"))
+        ->G.thenEvent(B.requested(B.transactional, "ref-1", B.announcedChannel, B.addressB))
+      )
+
+      G.test("an optional request is suppressed with no explicit subscription", () =>
+        G.givenEvents(announced)
+        ->G.whenCmd(B.request(B.optional, "ref-2"))
+        ->G.thenEvent(B.suppressed(B.optional, "ref-2"))
+      )
+
+      G.test("a recipient who opted out is suppressed", () =>
+        G.givenEvents(
+          Array.concat(announced, [B.unsubscribedC(B.transactional, B.announcedChannel)]),
+        )
+        ->G.whenCmd(B.request(B.transactional, "ref-3"))
+        ->G.thenEvent(B.suppressed(B.transactional, "ref-3"))
+      )
+
+      // The case the directory exists for.
+      G.test("a request for a recipient nobody announced is undeliverable", () =>
+        G.givenEvents(B.created)
+        ->G.whenCmd(B.request(B.transactional, "ref-4"))
+        ->G.thenEvent(B.undeliverable(B.transactional, "ref-4"))
+      )
+
+      // Wanted, and unreachable — the distinction the whole `Undeliverable` arm
+      // exists for. Skipped by a host that announces an address for every channel
+      // it offers, because there is then no way to be in this state.
+      switch B.unreachableChannel {
+      | None => ()
+      | Some(channel) =>
+        G.test("a channel with no address on file is undeliverable, not suppressed", () =>
+          G.givenEvents(
+            Array.concat(
+              announced,
+              [
+                B.subscribedC(B.transactional, channel),
+                B.unsubscribedC(B.transactional, B.announcedChannel),
+              ],
+            ),
+          )
+          ->G.whenCmd(B.request(B.transactional, "ref-5"))
+          ->G.thenEvent(B.undeliverable(B.transactional, "ref-5"))
+        )
+      }
+    })
+}