docs(website): settle boot/shutdown dispatch and what a boot writes down #130

wtclaude · 2026-08-11T01:33:22Z

wtclaude commented

2026-08-11 01:33:22 +00:00

Docs half of phase 2 PR 5 of the module system. Code: website#132.

`MODULE_API.md`

§2.5 Lifecycle gains what the dispatch actually settled:

the reconcile's four steps in order, since the order is the design — clear the last boot's outcomes, write a row for every module on the volume, mark rows whose directory is gone, then dispatch onBoot;
the operator's disabled wins over any outcome — guarded, not booted, failure never re-recorded, because overwriting a decision with an outcome silently switches the module back on next boot;
a bookkeeping failure is not a boot failure — every write is individually caught;
a module with no onBoot still reaches started (having nothing to warm up is not the same as never having started, and the row has to agree with the guard);
a module whose onBoot threw gets no onShutdown — it is part-way through a warm-up it never finished;
why onBoot has no budget while onShutdown has five seconds: shutdown races the process being killed and boot does not, and a slow onBoot delaying the listener is the promise, not the bug.

§4.4 gains the failure_stage table: every failure recorded against the §4.3 step that produced it, which steps label themselves and which are inferred, and that every non-failing transition clears both stage and reason.

`MODULE_SYSTEM.md`

§2.4 records the new rule for a row whose directory is gone — startup_failed rather than left claiming enabled, since the boot reset has just moved it there and an uninstall would have left disabled.

§2.7 gets the PR 5 progress entry and its four decisions, and the progress line moves to PRs 1–5.

`BACKEND_DESIGN.md`

The installed_modules section gains the write path, now that one exists: where it happens on the boot path, what it writes, and that a disabled row is never overwritten.

AI-assisted (Claude Code).

🤖 Generated with Claude Code

https://claude.ai/code/session_018ocYxQWk3EhZe5gWRJXFU8

Docs half of phase 2 PR 5 of the module system. Code: **website#132**. ## `MODULE_API.md` **§2.5 Lifecycle** gains what the dispatch actually settled: - the reconcile's **four steps in order**, since the order is the design — clear the last boot's outcomes, write a row for every module on the volume, mark rows whose directory is gone, then dispatch `onBoot`; - **the operator's `disabled` wins over any outcome** — guarded, not booted, failure never re-recorded, because overwriting a decision with an outcome silently switches the module back on next boot; - **a bookkeeping failure is not a boot failure** — every write is individually caught; - a module with **no `onBoot` still reaches `started`** (having nothing to warm up is not the same as never having started, and the row has to agree with the guard); - a module whose **`onBoot` threw gets no `onShutdown`** — it is part-way through a warm-up it never finished; - **why `onBoot` has no budget while `onShutdown` has five seconds**: shutdown races the process being killed and boot does not, and a slow `onBoot` delaying the listener is the promise, not the bug. **§4.4** gains the `failure_stage` table: every failure recorded against the §4.3 step that produced it, which steps label themselves and which are inferred, and that every non-failing transition clears both stage and reason. ## `MODULE_SYSTEM.md` **§2.4** records the new rule for a row whose directory is gone — `startup_failed` rather than left claiming `enabled`, since the boot reset has just moved it there and an uninstall would have left `disabled`. **§2.7** gets the PR 5 progress entry and its four decisions, and the progress line moves to PRs 1–5. ## `BACKEND_DESIGN.md` The `installed_modules` section gains the write path, now that one exists: where it happens on the boot path, what it writes, and that a `disabled` row is never overwritten. AI-assisted (Claude Code). 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_018ocYxQWk3EhZe5gWRJXFU8

wtclaude added 1 commit 2026-08-11 01:33:23 +00:00

docs(website): settle boot/shutdown dispatch and what a boot writes down 004e217806

Records phase 2 PR 5 of the module system: the lifecycle hooks a module
registers, how they are dispatched, and what a boot does to installed_modules.

MODULE_API.md 2.5 gains the reconcile's four steps in order, the rules that fall
out of them (the operator's `disabled` wins over any outcome; a bookkeeping
failure is not a boot failure; a module with no onBoot still reaches `started`;
a module whose onBoot threw gets no onShutdown), and why onBoot has no timeout
while onShutdown has a five-second budget -- shutdown races the process being
killed and boot does not.

4.4 gains the failure_stage table: every failure is recorded against the 4.3
step that produced it, so the admin panel can say where a module broke and not
only what the message was.

MODULE_SYSTEM.md 2.4 records the new rule for a row whose directory is gone, and
2.7 the PR 5 progress entry with its four decisions. BACKEND_DESIGN.md's
installed_modules section gains the write path now that one exists.

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

whitlocktech merged commit e733ac0c9c into main

2026-08-11 02:32:50 +00:00

whitlocktech deleted branch docs/module-lifecycle

2026-08-11 02:32:50 +00:00

whitlocktech referenced this issue from a commit

2026-08-11 02:32:52 +00:00

Merge pull request 'docs(website): settle boot/shutdown dispatch and what a boot writes down' (#130) from docs/module-lifecycle into main

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: RunicGateway/docs#130