docs(engagement): the two walk defects, fixed — and what digest is #204

wtclaude · 2026-09-01T19:31:18Z

wtclaude commented

2026-09-01 19:31:18 +00:00

Companion to website#181, and a follow-on from #203 — which recorded the two defects Phase 13's acceptance walk found and left them for you to place.

Phase 13's as-built

"Neither is fixed here" becomes what the fix actually was: the atomic claim(key, value) on settings.db, both seeders claiming before inserting rather than stamping after, the claim-shaped stubs and the two Promise.all tests — including that reverting the fix makes the module test report every rule inserted twice, which is how it was checked.

Two files were describing a contract the code did not honour

That is why the second defect could exist, so it is worth fixing in the docs rather than only in the code:

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

No contract changed — the docs were right about what is permitted and the code was wrong — so no MODULE_API_VERSION bump, for the same reason website#181 takes none.

One mechanical note

BACKEND_DESIGN.md is committed with CRLF and the other two with LF. Writing all three the same way turned a one-line edit into a 3,684-line diff; this branch preserves each file's own endings, so the diff is 13 lines across 3 files.

AI-assisted: written with Claude Code.

🤖 Generated with Claude Code

Companion to **website#181**, and a follow-on from #203 — which recorded the two defects Phase 13's acceptance walk found and left them for you to place. ### Phase 13's as-built *"Neither is fixed here"* becomes what the fix actually was: the atomic `claim(key, value)` on `settings.db`, both seeders claiming before inserting rather than stamping after, the `claim`-shaped stubs and the two `Promise.all` tests — including that reverting the fix makes the module test report every rule inserted twice, which is how it was checked. ### Two files were describing a contract the code did not honour That is *why* the second defect could exist, so it is worth fixing in the docs rather than only in the code: - **`BACKEND_DESIGN.md`** — the `engagement_rules.template_keys` row said only that keys are shape-checked. It now says the load-bearing part: **`digest` is a key that is not a channel**, because it names a *mode's* body, and the rules validator rejected it until website#181 — which made every rule shipping one unsaveable from the Rules screen, core's own Team and news rules included. - **`MODULE_API.md` §2.4** — already told modules they may point `template_keys` at `notify.digest`, and never said what `digest` *was*. A module author reading that would reasonably have expected a channel. One bullet, next to the generic-bodies one that sends them there. **No contract changed** — the docs were right about what is permitted and the code was wrong — so no `MODULE_API_VERSION` bump, for the same reason website#181 takes none. ### One mechanical note `BACKEND_DESIGN.md` is committed with CRLF and the other two with LF. Writing all three the same way turned a one-line edit into a 3,684-line diff; this branch preserves each file's own endings, so the diff is **13 lines across 3 files**. - [x] AI-assisted: written with Claude Code. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

wtclaude added 1 commit 2026-09-01 19:31:20 +00:00

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

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>

whitlocktech merged commit 6601e410f4 into main

2026-09-01 19:34:00 +00:00

whitlocktech deleted branch docs/engagement-walk-fixes

2026-09-01 19:34:01 +00:00

whitlocktech referenced this issue from a commit

2026-09-01 19:34:02 +00:00

Merge pull request 'docs(engagement): the two walk defects, fixed — and what `digest` is' (#204) from docs/engagement-walk-fixes into main

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: RunicGateway/docs#204

docs(engagement): the two walk defects, fixed — and what digest is #204

Phase 13's as-built

Two files were describing a contract the code did not honour

One mechanical note

docs(engagement): the two walk defects, fixed — and what `digest` is #204