docs(engagement): the two walk defects, fixed -- and what digest is

Follows docs#203, which recorded the two defects Phase 13's acceptance walk found
and left them for placing. They are fixed in website#181, so Phase 13's as-built
says so and says what the fix was rather than leaving a reader to find the PR.

Two other files were describing a contract the code did not honour, which is why
the second defect could exist at all:

  * BACKEND_DESIGN's `template_keys` column row said only that keys are
    shape-checked. It now says the one thing that was actually load-bearing --
    `digest` is a key that is NOT a channel, because it names a MODE's body --
    and that the rules validator rejected it until website#181, which made every
    rule shipping one unsaveable from the Rules screen, core's own included.
  * MODULE_API 2.4 already told modules they may point `template_keys` at
    `notify.digest` and never said what `digest` was. A module author reading it
    would reasonably have expected it to be a channel. One bullet, next to the
    generic-bodies one that sends them there.

No contract changed; the docs were right and the code was wrong. No
MODULE_API_VERSION bump for the same reason.

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
2026-09-01 14:31:00 -05:00
parent 924204f8ba
commit b3dd2c7cbb
3 changed files with 13 additions and 3 deletions

View File

@@ -508,7 +508,7 @@ is only harmless while the default is off. Existing subscriptions are carried ac
| audience_segment_id | INT NULL | a composed segment (§5.1a). **Deliberately no FK** — see below |
| max_sends_per_hour | INT NOT NULL DEFAULT 100 | the hard per-rule ceiling (§7.1 Q3), counted in `engagement_sends` and enforced before an outbox row is written |
| channels | JSON NOT NULL | `['email','inapp']` — a rule may span channels |
| template_keys | JSON NOT NULL | `{ email: 'idoc-warning' }`. Keys are shape-checked, not existence-checked: templates are Phase 5 |
| template_keys | JSON NOT NULL | `{ email: 'idoc-warning' }`. Keys are shape-checked, not existence-checked: templates are Phase 5. Every key is one of the rule's `channels` **plus one that is not a channel at all**: `digest` names the body the digest worker renders for a rule whose email channel an individual set to digest mode, so it belongs to a mode and can never appear in `channels`. The rules validator rejected it until website#181, which made every rule shipping one — core's own Team and news rules included — unsaveable from the Rules screen |
| conditions | JSON NULL | a small closed and/or/not grammar over the trigger's **declared** variables |
| cooldown_seconds | INT NOT NULL DEFAULT 0 | 0 = no cooldown |
| delay_seconds | INT NOT NULL DEFAULT 0 | the grace window (§4.2a) |