docs(events): Phase 2 as built — the runner #210

wtclaude · 2026-09-02T11:33:10Z

wtclaude commented

2026-09-02 11:33:10 +00:00

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

Two files, and the diff is additive except for two table rows.

`EVENTS.md`

§E, §F and §L gain what building the runner settled. Six things:

A parked step is running with a NULL lease. The step-status row says so, because the ENUM has no state for "waiting on a human" and adding one would be a table ALTER that CREATE TABLE IF NOT EXISTS never delivers to an existing deployment. The reclaim was written to take back only a lease that is non-NULL and expired — which is what lets a cue posted on Friday still be waiting on Monday.
Two success-envelope members, written into §F beside the rule they qualify: { ok: true, await: 'human' } parks, { ok: true, holdFor: <seconds> } finishes and delays what follows. Members rather than special cases keyed on an action id, so the runner never names a verb and Phase 7 hands a module the same door.
A holdFor on the last step of a phase holds the NEXT phase. The later phase's steps do not exist at that moment, so the instant crosses the boundary. See the finding below.
What happens to a run whose concurrency key is held: it stays scheduled and lets its own grace window decide. Failing it at once would say the system broke when it correctly declined to overlap two events; queueing it would let an event announced for 8pm start at 11pm, which is what missed exists to prevent.
n in §L's retry(n) is EVENT_STEP_MAX_ATTEMPTS, and all three on_failure dispositions write the STEP failed — the disposition governs the run. skipped is left for a human's skip control in Phase 3, because a status meaning both "nobody ran this" and "this failed and we moved on" makes the run console's summary line unreadable.
A new §L row: health degrades on the FIRST retry, not on the eventual failure. An event whose announcements are landing on the second attempt is having trouble now.

Plus a note on what "materialise" covers in this phase (the grace window only — the validator accepts kind: 'manual' alone until Phase 4) and one saying Phase 2 added no routes at all, so nobody reads the still-absent live controls as a regression.

`EVENTS_PLAN.md`

Marks Phase 2 complete, and records the four org-lead decisions (2026-09-02) and the three things the build settled on its own — including the two that are corrections rather than choices:

A live lease is not re-enterable, not even by the process that took it. The first claimTick carried an OR claimed_by = ? escape for a tick re-entering its own claim — which is precisely the overrun this phase's CAS is meant to protect against, since setInterval fires whether or not the last callback returned.
A wait as the last step of a phase used to mean nothing. Found by writing the test; the test was then re-run against the unfixed code to confirm it fails.

It also records where the claim paths are actually proved, and why that needed a second test file: engagement Phase 4a's cooldown claim was green against its stub and always allowed the send against a real server, because the connector defaults foundRows: true. A stub can only ever agree with whoever wrote it.

Verify

docs has no CI. Every relative link and anchor in both files was checked by hand — all resolve. The working tree is CRLF under core.autocrlf=true, so both files were read universal-newline and written back \r\n; git diff --numstat is 62/2 and 65/0, and the two deletions are the two table rows that were genuinely rewritten.

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

The docs half of Event System **Phase 2**. Pairs with `RunicGateway/website` `feat/events-phase-2`. Two files, and the diff is **additive except for two table rows**. ## `EVENTS.md` §E, §F and §L gain what building the runner settled. Six things: - **A parked step is `running` with a NULL lease.** The step-status row says so, because the ENUM has no state for "waiting on a human" and adding one would be a table `ALTER` that `CREATE TABLE IF NOT EXISTS` never delivers to an existing deployment. The reclaim was written to take back only a lease that is **non-NULL and expired** — which is what lets a cue posted on Friday still be waiting on Monday. - **Two success-envelope members**, written into §F beside the rule they qualify: `{ ok: true, await: 'human' }` parks, `{ ok: true, holdFor: <seconds> }` finishes and delays what follows. Members rather than special cases keyed on an action id, so the runner never names a verb and Phase 7 hands a module the same door. - **A `holdFor` on the last step of a phase holds the NEXT phase.** The later phase's steps do not exist at that moment, so the instant crosses the boundary. See the finding below. - **What happens to a run whose concurrency key is held**: it stays `scheduled` and lets its own grace window decide. Failing it at once would say the system broke when it correctly declined to overlap two events; queueing it would let an event announced for 8pm start at 11pm, which is what `missed` exists to prevent. - **`n` in §L's `retry(n)`** is `EVENT_STEP_MAX_ATTEMPTS`, and **all three `on_failure` dispositions write the STEP `failed`** — the disposition governs the run. `skipped` is left for a human's skip control in Phase 3, because a status meaning both "nobody ran this" and "this failed and we moved on" makes the run console's summary line unreadable. - **A new §L row: health degrades on the FIRST retry**, not on the eventual failure. An event whose announcements are landing on the second attempt is having trouble *now*. Plus a note on what "materialise" covers in this phase (the grace window only — the validator accepts `kind: 'manual'` alone until Phase 4) and one saying Phase 2 added **no routes at all**, so nobody reads the still-absent live controls as a regression. ## `EVENTS_PLAN.md` Marks Phase 2 complete, and records the **four org-lead decisions** (2026-09-02) and the **three things the build settled on its own** — including the two that are corrections rather than choices: - **A live lease is not re-enterable, not even by the process that took it.** The first `claimTick` carried an `OR claimed_by = ?` escape for a tick re-entering its own claim — which is precisely the overrun this phase's CAS is meant to protect against, since `setInterval` fires whether or not the last callback returned. - **A wait as the last step of a phase used to mean nothing.** Found by writing the test; the test was then re-run against the unfixed code to confirm it fails. It also records where the claim paths are actually proved, and why that needed a second test file: engagement Phase 4a's cooldown claim was green against its stub and always allowed the send against a real server, because the connector defaults `foundRows: true`. A stub can only ever agree with whoever wrote it. ## Verify `docs` has no CI. Every relative link and anchor in both files was checked by hand — all resolve. The working tree is CRLF under `core.autocrlf=true`, so both files were read universal-newline and written back `\r\n`; `git diff --numstat` is **62/2** and **65/0**, and the two deletions are the two table rows that were genuinely rewritten. --- - [x] AI-assisted: authored with Claude Code (Claude Opus).

wtclaude added 1 commit 2026-09-02 11:33:13 +00:00

docs(events): Phase 2 as built - the runner 76b2276d36

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

EVENTS.md gains what the runner settled: the parked step (`running` with a NULL
lease), the two success-envelope members `await: 'human'` and `holdFor`, the
answer for a run whose concurrency key is held, `n` in §L's `retry(n)`, the rule
that all three `on_failure` dispositions write the step `failed`, and the health
transition on the first retry rather than the eventual failure.

EVENTS_PLAN.md marks Phase 2 complete and records the four org-lead decisions
and the three things the build settled on its own.

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

wtclaude referenced this pull request from RunicGateway/website

2026-09-02 11:33:47 +00:00

feat(events): the runner (Phase 2) #184

whitlocktech merged commit 1feca4e70d into edge

2026-09-02 11:35:01 +00:00

whitlocktech deleted branch docs/events-phase-2

2026-09-02 11:35:02 +00:00

whitlocktech referenced this issue from a commit

2026-09-02 11:35:03 +00:00

Merge pull request 'docs(events): Phase 2 as built — the runner' (#210) from docs/events-phase-2 into edge

Sign in to join this conversation.