docs(events): Phase 1 as built — schema, CRUD and the core action registry #209

wtclaude · 2026-09-02T04:28:57Z

wtclaude commented

2026-09-02 04:28:57 +00:00

The docs half of Event System Phase 1. Pairs with RunicGateway/website feat/events-phase-1.

Three files.

`BACKEND_DESIGN.md`

Gains the six event tables, column by column, and the eleven admin routes — written where the other table groups live, in the same shape, because the argument for a column belongs beside the column.

`EVENTS.md` — four things the build settled that §D and §F had left open

event_definitions.spec, the working copy. §D's column list does not name one because §D describes what a published event is made of — but "editing a draft is free; no version exists yet" means the draft has to live somewhere, and it cannot be an event_versions row: that table is immutable and a run pins one, so a mutable unpublished row in it would be exactly what versioning exists to prevent. series_order is the same kind of addition.
A param's example is required, on optional params too, matching registerEventTriggers. It is the authoring form's placeholder, one word at declaration time and unreconstructable afterwards.
The authoring side of dormancy. §F said what happens at dispatch; the save path draws the same line one step earlier, in the shape engagement_rules established — a saved step may keep an unregistered action, a new step may not add one, and a dormant step blocks the publish rather than the save.
Publish re-validates against the registries as they stand at that moment, not from the save that wrote the spec.

Plus two routes the § API surface table did not name — GET /admin/events/:id (the list serves a summary; the editor needs the tree) and GET /admin/events/series (a form cannot offer a value it cannot enumerate) — and a note saying which of that table's rows Phase 1 deliberately did not build.

`EVENTS_PLAN.md`

Marks Phase 1 complete, names those four settlements, and states the two deliberate absences so a reviewer does not read them as gaps:

The live run controls and verify are absent rather than stubbed — nothing is in flight until P2, and a control that answers 200 and does nothing is worse than one that is not there.
Core's three perform() bodies answer { ok: false, retry: false } rather than { ok: true } — ok: true on an action that did nothing is a recorded world change that did not occur, which is the exact mistake §F's failure default exists to prevent.

Not done here

api-route-inventory.json is not resynced. It has been stale since engagement Phase 2 and is 47 routes behind; catching it up in this PR would bury a 13-route change under an unrelated 47.

Verify

docs has no CI. Every relative link and anchor introduced here was checked by hand.

AI-assisted: authored with Claude Code (Claude Opus).

The docs half of Event System **Phase 1**. Pairs with `RunicGateway/website` `feat/events-phase-1`. Three files. ## `BACKEND_DESIGN.md` Gains **the six event tables**, column by column, and **the eleven admin routes** — written where the other table groups live, in the same shape, because the argument for a column belongs beside the column. ## `EVENTS.md` — four things the build settled that §D and §F had left open - **`event_definitions.spec`**, the working copy. §D's column list does not name one because §D describes what a *published* event is made of — but "editing a draft is free; no version exists yet" means the draft has to live somewhere, and it cannot be an `event_versions` row: that table is immutable and a run pins one, so a mutable unpublished row in it would be exactly what versioning exists to prevent. `series_order` is the same kind of addition. - **A param's `example` is required**, on optional params too, matching `registerEventTriggers`. It is the authoring form's placeholder, one word at declaration time and unreconstructable afterwards. - **The authoring side of dormancy.** §F said what happens at *dispatch*; the save path draws the same line one step earlier, in the shape `engagement_rules` established — a saved step may keep an unregistered action, a new step may not add one, and a dormant step blocks the **publish** rather than the save. - **Publish re-validates against the registries as they stand at that moment**, not from the save that wrote the spec. Plus two routes the § API surface table did not name — `GET /admin/events/:id` (the list serves a summary; the editor needs the tree) and `GET /admin/events/series` (a form cannot offer a value it cannot enumerate) — and a note saying which of that table's rows Phase 1 deliberately did **not** build. ## `EVENTS_PLAN.md` Marks Phase 1 complete, names those four settlements, and states the **two deliberate absences** so a reviewer does not read them as gaps: 1. The live run controls and `verify` are absent rather than stubbed — nothing is in flight until P2, and a control that answers `200` and does nothing is worse than one that is not there. 2. Core's three `perform()` bodies answer `{ ok: false, retry: false }` rather than `{ ok: true }` — `ok: true` on an action that did nothing is a recorded world change that did not occur, which is the exact mistake §F's failure default exists to prevent. ## Not done here `api-route-inventory.json` is **not** resynced. It has been stale since engagement Phase 2 and is 47 routes behind; catching it up in this PR would bury a 13-route change under an unrelated 47. ## Verify `docs` has no CI. Every relative link and anchor introduced here was checked by hand. --- - [x] AI-assisted: authored with Claude Code (Claude Opus).

wtclaude added 1 commit 2026-09-02 04:28:58 +00:00

docs(events): Phase 1 as built — schema, CRUD and the core action registry 9ba119dc5a

The docs half of RunicGateway/website#<n>. Three files.

**BACKEND_DESIGN.md** gains the six event tables, column by column, and the
eleven admin routes. Written where the other table groups are, in the same
shape, because the argument for a column belongs beside the column.

**EVENTS.md** records four things the build settled that §D and §F had left
open:

  - `event_definitions.spec`, the working copy. §D's column list does not name
    one because §D describes what a PUBLISHED event is made of — but "editing a
    draft is free; no version exists yet" means the draft has to live somewhere,
    and it cannot be an `event_versions` row: that table is immutable and a run
    pins one, so a mutable unpublished row in it would be exactly what
    versioning exists to prevent.
  - A param's `example` is REQUIRED, on optional params too, the same rule
    `registerEventTriggers` makes of a variable's example and for the same
    reason: it is the authoring form's placeholder, one word at declaration
    time and unreconstructable afterwards.
  - The authoring side of dormancy. §F said what happens at DISPATCH; the save
    path draws the same line one step earlier, in the shape `engagement_rules`
    established — a saved step may keep an unregistered action, a new step may
    not add one, and a dormant step blocks the publish rather than the save.
  - Publish re-validates against the registries as they stand at that moment,
    not from the save that wrote the spec.

Plus two routes the § API surface table did not name — `GET /admin/events/:id`
(the list serves a summary; the editor needs the tree) and `GET
/admin/events/series` (a form cannot offer a value it cannot enumerate) — and a
note stating which of that table's rows Phase 1 deliberately did not build.

**EVENTS_PLAN.md** marks Phase 1 complete, names those four settlements, and
states the two deliberate absences so a reviewer does not read them as gaps:
the live run controls are not stubbed, and core's three `perform()` bodies
answer `{ ok: false }` rather than `{ ok: true }` — `ok: true` on an action
that did nothing is a recorded world change that did not occur.

`api-route-inventory.json` is NOT resynced here. It has been stale since
engagement Phase 2 and is 47 routes behind; catching it up in this PR would
bury a 13-route change under an unrelated 47.

Co-Authored-By: Claude <noreply@anthropic.com>

wtclaude referenced this issue from a commit

2026-09-02 04:29:16 +00:00

feat(events): schema, CRUD and the core action registry (Phase 1)

wtclaude referenced this pull request from RunicGateway/website

2026-09-02 04:29:40 +00:00

feat(events): schema, CRUD and the core action registry (Phase 1) #183

whitlocktech merged commit e4b7fa3d7e into edge

2026-09-02 04:38:43 +00:00

whitlocktech deleted branch docs/events-phase-1

2026-09-02 04:38:44 +00:00

whitlocktech referenced this issue from a commit

2026-09-02 04:38:44 +00:00