@reventlessdev/trait-notification 1.0.0-alpha.1 → 1.0.0-alpha.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reventlessdev/trait-notification",
-  "version": "1.0.0-alpha.1",
+  "version": "1.0.0-alpha.11",
   "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": [
@@ -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.199",
-    "@reventlessdev/reventless-spec": "3.0.0-alpha.125"
+    "@reventlessdev/reventless-gwt": "1.0.0-alpha.209",
+    "@reventlessdev/reventless-spec": "3.0.0-alpha.135"
   },
   "devDependencies": {
     "rescript": "12.3.0"

package/src/Notification.res

@@ -19,7 +19,6 @@ 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.
@@ -67,19 +66,46 @@ module type Binding = {
   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
+  /** 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 recipient id, because the partition already
+      says whose it is. 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 `announcedC` against
+      `announced`, 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 recipient into existence with nothing on file. */
+    let created: array<Spec.consumedEvent>
+    let announced: string => Spec.consumedEvent
+    let subscribed: (category, Notification_Rules.channel) => Spec.consumedEvent
+    let unsubscribed: (category, Notification_Rules.channel) => Spec.consumedEvent
+    /** A source taken over, as the slice reads it back. Claims are per source
+        and not per recipient, so a host produces these from wherever it keeps
+        them — what this contract requires is only that the decision can see
+        them. */
+    let claimed: (string, string) => Spec.consumedEvent
+    let released: string => 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. */
+  /** `reference` is the requester's key, echoed on whichever outcome follows.
+      The host's own relay's request: `Default` origin, from `defaultSource`. */
   let request: (category, string) => Spec.command
+  /** The same, with the two fields the handover turns on spelled out. */
+  let requestFrom: (
+    category,
+    string,
+    ~source: string,
+    ~origin: Notification_Rules.origin,
+  ) => Spec.command
+  /** The source `request` above comes from, and one nothing ever claims. */
+  let defaultSource: string
 
   /** The competency's facts, as the slice emits them. */
   let announced: string => Spec.event
@@ -88,6 +114,12 @@ module type Binding = {
   let requested: (category, string, Notification_Rules.channel, string) => Spec.event
   let suppressed: (category, string) => Spec.event
   let undeliverable: (category, string) => Spec.event
+  /** `(reference, source)` — the request another producer owns. */
+  let deferred: (string, string) => Spec.event
+  /** `requested` as it comes out for a `Configured` request. A separate member
+      because *which* rule asked is the host's own shape — the trait's fact
+      carries no origin at all, so it cannot construct this one. */
+  let requestedConfigured: (category, string, Notification_Rules.channel, string) => Spec.event
 
   /** The refusal for managing preferences for somebody nobody has announced. */
   let recipientUnknown: Spec.error

package/src/Notification_Conformance.res

@@ -6,7 +6,6 @@ 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
@@ -17,14 +16,14 @@ 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 announced = Array.concat(B.Consumed.created, [B.Consumed.announced(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),
-        )
+        G.givenEvents(B.Consumed.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
@@ -36,15 +35,15 @@ module Make = (B: Notification.Binding) => {
       )
 
       G.test("a changed address is recorded", () =>
-        G.givenEvents(announced)->G.whenCmd(B.announce(B.addressB))->G.thenEvent(
-          B.announced(B.addressB),
-        )
+        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.givenEvents(B.Consumed.created)
         ->G.whenCmd(B.subscribe(B.optional, B.announcedChannel))
         ->G.thenError(B.recipientUnknown)
       )
@@ -81,13 +80,11 @@ module Make = (B: Notification.Binding) => {
       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.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.givenEvents(Array.concat(announced, [B.Consumed.announced(B.addressB)]))
         ->G.whenCmd(B.request(B.transactional, "ref-1"))
         ->G.thenEvent(B.requested(B.transactional, "ref-1", B.announcedChannel, B.addressB))
       )
@@ -100,7 +97,7 @@ module Make = (B: Notification.Binding) => {
 
       G.test("a recipient who opted out is suppressed", () =>
         G.givenEvents(
-          Array.concat(announced, [B.unsubscribedC(B.transactional, B.announcedChannel)]),
+          Array.concat(announced, [B.Consumed.unsubscribed(B.transactional, B.announcedChannel)]),
         )
         ->G.whenCmd(B.request(B.transactional, "ref-3"))
         ->G.thenEvent(B.suppressed(B.transactional, "ref-3"))
@@ -108,11 +105,79 @@ module Make = (B: Notification.Binding) => {
 
       // The case the directory exists for.
       G.test("a request for a recipient nobody announced is undeliverable", () =>
-        G.givenEvents(B.created)
+        G.givenEvents(B.Consumed.created)
         ->G.whenCmd(B.request(B.transactional, "ref-4"))
         ->G.thenEvent(B.undeliverable(B.transactional, "ref-4"))
       )
 
+      // ── The handover ────────────────────────────────────────────────────────
+      //
+      // A second producer takes over one source and the compiled table yields on
+      // that source alone. The first of these is the one that matters most: it is
+      // the assertion that a host with nobody claiming anything behaves exactly as
+      // it did before any of this existed.
+
+      G.test("with nothing claimed, a default request is decided as usual", () =>
+        G.givenEvents(announced)
+        ->G.whenCmd(
+          B.requestFrom(B.transactional, "ref-6", ~source=B.defaultSource, ~origin=Default),
+        )
+        ->G.thenEvent(B.requested(B.transactional, "ref-6", B.announcedChannel, B.addressA))
+      )
+
+      G.test("a default request for a claimed source is deferred", () =>
+        G.givenEvents(
+          Array.concat(announced, [B.Consumed.claimed("other:Source", "second-producer")]),
+        )
+        ->G.whenCmd(
+          B.requestFrom(B.transactional, "ref-7", ~source="other:Source", ~origin=Default),
+        )
+        ->G.thenEvent(B.deferred("ref-7", "other:Source"))
+      )
+
+      // The claim is per source, not per recipient or per deployment: the table
+      // keeps firing everywhere it was not taken over. Without this, a single
+      // claim would silence the whole competency.
+      G.test("a claim on one source leaves every other source alone", () =>
+        G.givenEvents(
+          Array.concat(announced, [B.Consumed.claimed("other:Source", "second-producer")]),
+        )
+        ->G.whenCmd(
+          B.requestFrom(B.transactional, "ref-8", ~source=B.defaultSource, ~origin=Default),
+        )
+        ->G.thenEvent(B.requested(B.transactional, "ref-8", B.announcedChannel, B.addressA))
+      )
+
+      // The producer that owns the source is the one that must get through, or
+      // the handover would silence the entry rather than move it.
+      G.test("a configured request for a claimed source goes through", () =>
+        G.givenEvents(
+          Array.concat(announced, [B.Consumed.claimed("other:Source", "second-producer")]),
+        )
+        ->G.whenCmd(
+          B.requestFrom(B.transactional, "ref-9", ~source="other:Source", ~origin=Configured),
+        )
+        ->G.thenEvent(
+          B.requestedConfigured(B.transactional, "ref-9", B.announcedChannel, B.addressA),
+        )
+      )
+
+      G.test("a released source stops deferring", () =>
+        G.givenEvents(
+          Array.concat(
+            announced,
+            [
+              B.Consumed.claimed("other:Source", "second-producer"),
+              B.Consumed.released("other:Source"),
+            ],
+          ),
+        )
+        ->G.whenCmd(
+          B.requestFrom(B.transactional, "ref-10", ~source="other:Source", ~origin=Default),
+        )
+        ->G.thenEvent(B.requested(B.transactional, "ref-10", B.announcedChannel, B.addressA))
+      )
+
       // 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.
@@ -124,8 +189,8 @@ module Make = (B: Notification.Binding) => {
             Array.concat(
               announced,
               [
-                B.subscribedC(B.transactional, channel),
-                B.unsubscribedC(B.transactional, B.announcedChannel),
+                B.Consumed.subscribed(B.transactional, channel),
+                B.Consumed.unsubscribed(B.transactional, B.announcedChannel),
               ],
             ),
           )

package/src/Notification_Conformance.res.mjs

@@ -13,26 +13,34 @@ function Make(B) {
     evolve: $$let.evolve,
     decide: $$let.decide
   });
-  let announced = B.created.concat([B.announcedC(B.addressA)]);
+  let announced = B.Consumed.created.concat([B.Consumed.announced(B.addressA)]);
   let register = () => G.describe(suiteName(B.Spec.name), () => {
-    G.test("an announced contact is recorded", () => G.thenEvent(G.whenCmd(G.givenEvents(B.created), B.announce(B.addressA)), B.announced(B.addressA)));
+    G.test("an announced contact is recorded", () => G.thenEvent(G.whenCmd(G.givenEvents(B.Consumed.created), B.announce(B.addressA)), B.announced(B.addressA)));
     G.test("re-announcing the address already on file is a no-op", () => G.thenNoEvent(G.whenCmd(G.givenEvents(announced), B.announce(B.addressA))));
     G.test("a changed address is recorded", () => G.thenEvent(G.whenCmd(G.givenEvents(announced), B.announce(B.addressB)), B.announced(B.addressB)));
-    G.test("managing preferences for an unannounced recipient is refused", () => G.thenError(G.whenCmd(G.givenEvents(B.created), B.subscribe(B.optional, B.announcedChannel)), B.recipientUnknown));
+    G.test("managing preferences for an unannounced recipient is refused", () => G.thenError(G.whenCmd(G.givenEvents(B.Consumed.created), B.subscribe(B.optional, B.announcedChannel)), B.recipientUnknown));
     G.test("opting in to a kind that is off by default is recorded", () => G.thenEvent(G.whenCmd(G.givenEvents(announced), B.subscribe(B.optional, B.announcedChannel)), B.subscribed(B.optional, B.announcedChannel)));
     G.test("subscribing to a kind already on by posture is a no-op", () => G.thenNoEvent(G.whenCmd(G.givenEvents(announced), B.subscribe(B.transactional, B.announcedChannel))));
     G.test("opting out of a kind that is on is recorded", () => G.thenEvent(G.whenCmd(G.givenEvents(announced), B.unsubscribe(B.transactional, B.announcedChannel)), B.unsubscribed(B.transactional, B.announcedChannel)));
     G.test("opting out of a kind already off is a no-op", () => G.thenNoEvent(G.whenCmd(G.givenEvents(announced), B.unsubscribe(B.optional, B.announcedChannel))));
     G.test("a transactional request goes out with no explicit subscription", () => G.thenEvent(G.whenCmd(G.givenEvents(announced), B.request(B.transactional, "ref-1")), B.requested(B.transactional, "ref-1", B.announcedChannel, B.addressA)));
-    G.test("the address on the request is the one currently on file", () => G.thenEvent(G.whenCmd(G.givenEvents(announced.concat([B.announcedC(B.addressB)])), B.request(B.transactional, "ref-1")), B.requested(B.transactional, "ref-1", B.announcedChannel, B.addressB)));
+    G.test("the address on the request is the one currently on file", () => G.thenEvent(G.whenCmd(G.givenEvents(announced.concat([B.Consumed.announced(B.addressB)])), B.request(B.transactional, "ref-1")), B.requested(B.transactional, "ref-1", B.announcedChannel, B.addressB)));
     G.test("an optional request is suppressed with no explicit subscription", () => G.thenEvent(G.whenCmd(G.givenEvents(announced), B.request(B.optional, "ref-2")), B.suppressed(B.optional, "ref-2")));
-    G.test("a recipient who opted out is suppressed", () => G.thenEvent(G.whenCmd(G.givenEvents(announced.concat([B.unsubscribedC(B.transactional, B.announcedChannel)])), B.request(B.transactional, "ref-3")), B.suppressed(B.transactional, "ref-3")));
-    G.test("a request for a recipient nobody announced is undeliverable", () => G.thenEvent(G.whenCmd(G.givenEvents(B.created), B.request(B.transactional, "ref-4")), B.undeliverable(B.transactional, "ref-4")));
+    G.test("a recipient who opted out is suppressed", () => G.thenEvent(G.whenCmd(G.givenEvents(announced.concat([B.Consumed.unsubscribed(B.transactional, B.announcedChannel)])), B.request(B.transactional, "ref-3")), B.suppressed(B.transactional, "ref-3")));
+    G.test("a request for a recipient nobody announced is undeliverable", () => G.thenEvent(G.whenCmd(G.givenEvents(B.Consumed.created), B.request(B.transactional, "ref-4")), B.undeliverable(B.transactional, "ref-4")));
+    G.test("with nothing claimed, a default request is decided as usual", () => G.thenEvent(G.whenCmd(G.givenEvents(announced), B.requestFrom(B.transactional, "ref-6", B.defaultSource, "Default")), B.requested(B.transactional, "ref-6", B.announcedChannel, B.addressA)));
+    G.test("a default request for a claimed source is deferred", () => G.thenEvent(G.whenCmd(G.givenEvents(announced.concat([B.Consumed.claimed("other:Source", "second-producer")])), B.requestFrom(B.transactional, "ref-7", "other:Source", "Default")), B.deferred("ref-7", "other:Source")));
+    G.test("a claim on one source leaves every other source alone", () => G.thenEvent(G.whenCmd(G.givenEvents(announced.concat([B.Consumed.claimed("other:Source", "second-producer")])), B.requestFrom(B.transactional, "ref-8", B.defaultSource, "Default")), B.requested(B.transactional, "ref-8", B.announcedChannel, B.addressA)));
+    G.test("a configured request for a claimed source goes through", () => G.thenEvent(G.whenCmd(G.givenEvents(announced.concat([B.Consumed.claimed("other:Source", "second-producer")])), B.requestFrom(B.transactional, "ref-9", "other:Source", "Configured")), B.requestedConfigured(B.transactional, "ref-9", B.announcedChannel, B.addressA)));
+    G.test("a released source stops deferring", () => G.thenEvent(G.whenCmd(G.givenEvents(announced.concat([
+      B.Consumed.claimed("other:Source", "second-producer"),
+      B.Consumed.released("other:Source")
+    ])), B.requestFrom(B.transactional, "ref-10", "other:Source", "Default")), B.requested(B.transactional, "ref-10", B.announcedChannel, B.addressA)));
     let channel = B.unreachableChannel;
     if (channel !== undefined) {
       return G.test("a channel with no address on file is undeliverable, not suppressed", () => G.thenEvent(G.whenCmd(G.givenEvents(announced.concat([
-        B.subscribedC(B.transactional, channel),
-        B.unsubscribedC(B.transactional, B.announcedChannel)
+        B.Consumed.subscribed(B.transactional, channel),
+        B.Consumed.unsubscribed(B.transactional, B.announcedChannel)
       ])), B.request(B.transactional, "ref-5")), B.undeliverable(B.transactional, "ref-5")));
     }
   });

package/src/Notification_Rule.res

@@ -0,0 +1,244 @@
+/**
+One notification rule as a value: which stream of occurrences it answers to, who
+it is for, which kind it is, and what it says.
+
+The shape a compiled table and a configured one both hold. That is why the filter
+is a typed tree and not an expression string — a string needs a parser at
+evaluation time, and a parser that runs on data from outside is an injection
+surface. It is also why the wording is `Reventless.Template` source: readable
+text rather than ReScript interpolation, rendered against the payload's schema so
+a semantic formats itself and a `@sensitive` field is withheld.
+*/
+/** How a field is compared. */
+@schema
+type comparison =
+  | Eq
+  | Ne
+  | Lt
+  | Lte
+  | Gt
+  | Gte
+  | Contains
+
+/** What it is compared against. */
+@schema
+type literal =
+  | Text(string)
+  | Number(float)
+  | Flag(bool)
+
+/** Whether a rule answers to this occurrence. */
+@schema
+type rec predicate =
+  | Always
+  | Compare({path: string, op: comparison, value: literal})
+  | All(array<predicate>)
+  | Any(array<predicate>)
+  | Not(predicate)
+
+/** One wording, in one locale. Both fields are `Reventless.Template` sources. */
+@schema
+type content = {locale: string, subject: string, body: string}
+
+/** The stream of occurrences a rule answers to, as the two halves of the
+    `"<log>:<eventType>"` a claim is made against. */
+@schema
+type source = {log: string, eventType: string}
+
+/** How a rule's occurrences reach the recipient: one message each, or gathered
+    into one message per window.
+
+    Routing is a field on the rule and not a negotiation between producers. A
+    digest is scheduler-driven and therefore its own component, but *which*
+    occurrences are its to gather is a table entry — so a relay serves the half it
+    can deliver and leaves the rest, with nothing to arbitrate.
+
+    `windowSeconds` is the one thing a digest cannot read off the rule. Where a
+    window starts and ends is the gathering component's own, deliberately: aligning
+    to a local midnight is a decision this table has no input for. */
+@schema
+type delivery =
+  | Immediate
+  | Digest({windowSeconds: int})
+
+@schema
+type t = {
+  /** Stable, because it is also the namespace of every reference this rule's
+      requests carry — renaming it re-keys their delivery rows. */
+  id: string,
+  /** Which version of this rule wrote a message, for the request to record. */
+  version: string,
+  source: source,
+  filter: predicate,
+  /** The host's kind of notification, as a key — see `Notification_Rules.category`. */
+  category: string,
+  delivery: delivery,
+  /** Where in the payload the person to notify is named. */
+  recipientPath: string,
+  /** What the notification is about: the component's name as the deployment
+      registers it, and where that row's own id sits in the payload. */
+  subjectType: string,
+  subjectPath: string,
+  content: array<content>,
+}
+
+/** The stream this rule answers to, in the form a claim is made against. */
+let sourceId = (rule: t) => `${rule.source.log}:${rule.source.eventType}`
+
+/** The correlation key a request carries. One per rule per subject, so an order
+    that is placed and then ships is two notifications and two delivery rows. */
+let referenceFor = (~ruleId: string, ~subject: string) => `${ruleId}:${subject}`
+
+let reference = (rule: t, ~subject: string) => referenceFor(~ruleId=rule.id, ~subject)
+
+let byId = (rules: array<t>, id: string) => rules->Array.find(rule => rule.id == id)
+
+/** Whether the per-event relay is the one that delivers this rule. A digest's
+    occurrences are gathered by its own component, so the relay passes over them
+    rather than sending one message each. */
+let isImmediate = (rule: t) => rule.delivery == Immediate
+
+/** Every rule answering to one occurrence. Two rules on one event type are two
+    notifications, which is what makes adding one a table change and not a code
+    change. */
+let forEvent = (rules: array<t>, ~log: string, ~eventType: string) =>
+  rules->Array.filter(rule => rule.source.log == log && rule.source.eventType == eventType)
+
+/** A mismatch of kinds is `false`, `Ne` included: a filter that cannot be read
+    against this payload does not fire. */
+let compare = (actual: JSON.t, op: comparison, expected: literal): bool => {
+  let ordered = (a, b) =>
+    switch op {
+    | Eq => a == b
+    | Ne => a != b
+    | Lt => a < b
+    | Lte => a <= b
+    | Gt => a > b
+    | Gte => a >= b
+    | Contains => false
+    }
+  switch (actual, expected) {
+  | (String(a), Text(b)) => op == Contains ? a->String.includes(b) : ordered(a, b)
+  | (Number(a), Number(b)) => ordered(a, b)
+  | (Boolean(a), Flag(b)) =>
+    switch op {
+    | Eq => a == b
+    | Ne => a != b
+    | _ => false
+    }
+  | (Array(items), Text(b)) =>
+    op == Contains &&
+      items->Array.some(item =>
+        switch item {
+        | String(text) => text == b
+        | _ => false
+        }
+      )
+  | _ => false
+  }
+}
+
+let rec matches = (predicate: predicate, ~payload: JSON.t): bool =>
+  switch predicate {
+  | Always => true
+  | Compare({path, op, value}) =>
+    switch Reventless.Template.lookup(payload, path) {
+    | Some(actual) => compare(actual, op, value)
+    | None => false
+    }
+  | All(parts) => parts->Array.every(part => matches(part, ~payload))
+  | Any(parts) => parts->Array.some(part => matches(part, ~payload))
+  | Not(part) => !matches(part, ~payload)
+  }
+
+let stringAt = (payload: JSON.t, path: string) =>
+  switch Reventless.Template.lookup(payload, path) {
+  | Some(String(text)) => Some(text)
+  | _ => None
+  }
+
+/** Who to notify. `None` is a rule whose path does not name a person in this
+    payload, which is a rule that cannot be acted on rather than one that sends
+    to nobody. */
+let recipientOf = (rule: t, ~payload: JSON.t) => stringAt(payload, rule.recipientPath)
+
+/** What it is about. Empty is legal — a notification about nothing in particular
+    is a real case, and a fabricated subject is worse than an absent one. */
+let subjectOf = (rule: t, ~payload: JSON.t) => stringAt(payload, rule.subjectPath)->Option.getOr("")
+
+/** The wording to use, the asked-for locale if the rule has it and the first
+    otherwise. Which locale to ask for is the caller's — nothing here knows who
+    is being written to. */
+let contentFor = (rule: t, ~locale: option<string>=?) =>
+  switch locale {
+  | Some(wanted) =>
+    switch rule.content->Array.find(entry => entry.locale == wanted) {
+    | Some(_) as found => found
+    | None => rule.content->Array.get(0)
+    }
+  | None => rule.content->Array.get(0)
+  }
+
+// A template that does not parse falls back to its own source: the renderer's
+// posture is that a fault is visible rather than silent, and `validate` is what
+// keeps a compiled table from reaching this.
+let render = (source: string, ~payload: JSON.t, ~schema: S.t<'a>) =>
+  Reventless.Template.renderSource(source, ~payload, ~schema)->Result.getOr(source)
+
+/** The rendered `(subject, body)`. */
+let compose = (rule: t, ~payload: JSON.t, ~schema: S.t<'a>, ~locale: option<string>=?) =>
+  switch contentFor(rule, ~locale?) {
+  | None => ("", "")
+  | Some({subject, body}) => (render(subject, ~payload, ~schema), render(body, ~payload, ~schema))
+  }
+
+/**
+The problems in a table, empty when it is sound.
+
+What a compiled table's own test asserts, so `compose`'s fallbacks and
+`recipientOf`'s `None` stay unreachable in a build rather than merely unlikely.
+`sample` is one payload of the shape the table's rules read.
+
+`~digestRouted` says whether this deployment has a component that gathers
+digests. It defaults to `false` because most do not, and there a `Digest` rule is
+a rule whose occurrences the per-event relay passes over and nobody else picks
+up — silence, which is the failure this competency is careful about everywhere
+else.
+*/
+let validate = (rules: array<t>, ~digestRouted: bool=false, ~sample: JSON.t): array<string> =>
+  rules->Array.flatMap(rule => {
+    let problems = []
+    let note = message => problems->Array.push(`${rule.id}: ${message}`)
+    if rule.id == "" {
+      note("a rule needs an id — it is the namespace of every reference it writes")
+    }
+    if Array.length(rule.content) == 0 {
+      note("no wording at all")
+    }
+    rule.content->Array.forEach(({locale, subject, body}) =>
+      [("subject", subject), ("body", body)]->Array.forEach(
+        ((which, template)) =>
+          switch Reventless.Template.parse(template) {
+          | Ok(_) => ()
+          | Error(why) => note(`${locale} ${which} does not parse — ${why}`)
+          },
+      )
+    )
+    if recipientOf(rule, ~payload=sample) == None {
+      note(`recipientPath "${rule.recipientPath}" names nobody in the sample payload`)
+    }
+    if stringAt(sample, rule.subjectPath) == None {
+      note(`subjectPath "${rule.subjectPath}" resolves to nothing in the sample payload`)
+    }
+    switch rule.delivery {
+    | Immediate => ()
+    | Digest({windowSeconds}) =>
+      if !digestRouted {
+        note("delivered as a digest, and nothing in this deployment gathers one")
+      }
+      if windowSeconds <= 0 {
+        note(`a digest window of ${windowSeconds->Int.toString}s gathers nothing`)
+      }
+    }
+    problems
+  })