docs(website): record phase 4 slice 3, and the boot-order defect it created #143

wtclaude · 2026-08-12T12:58:29Z

wtclaude commented

2026-08-12 12:58:29 +00:00

Docs half of RunicGateway/website#144 (phase 4, slice 3 — the declarative Docker path). Merge this first.

MODULE_SYSTEM.md

The slice 3 write-up in §2.7.2: why MODULES spells out the id and the version (the offline no-op has to be a file read, not a fetch), the four decisions, the defect below, and a table of what the smoke proved against the real published v0.3.0 on a fresh database.

Two sections are corrected, not merely extended:

§2.5 promised "a declarative module set resolved at container start" and did not anticipate that two install surfaces need a rule about who wins. They do, and it is: the declaration owns what is on the volume, the row owns whether a module runs. Uninstalling a declared module from the panel returns its files at the next start and leaves it disabled.
Decision 4's "resolution runs before the server starts" is true of the scan, not of the process. It runs inside start(), before app.js is required — which is what buys it the database, and therefore the admin-managed host allowlist and the provenance columns. A pre-flight script would have had neither.

MODULE_API.md

§2.6 no longer says the fragments are replayed by ensureSchema(). They are for every caller except the server, which now scans the volume later than it ensures the schema and so replays them itself.

That was a live defect for an afternoon and the shape of it is the part worth keeping: it announced itself only as the no module scan in this process — skipping schema fragment replay line, which is correct output for npm run seed and means the opposite in a booting server — and on a database whose tables already existed, the module started perfectly. Every suite in that repo stubs either the loader or the pool, so none could see it; booting against an empty database did.

Nothing about the contract moves — fragments still run after core's tables exist and before any onBoot — so MODULE_API_VERSION is unchanged. §2.5's lifecycle diagram gains the resolution step ahead of require(module).

BACKEND_DESIGN.md

The boot sequence in the source tree, and MODULES beside the module_source_hosts setting it installs through — including that it is not a settings row and not editable from the panel.

The route manifest is unchanged (166 public + 2 internal), so api-route-inventory.json needs no refresh this slice.

Docs only.

AI disclosure

This contribution was AI-assisted (Claude Code).

🤖 Generated with Claude Code

Docs half of **RunicGateway/website#144** (phase 4, slice 3 — the declarative Docker path). Merge this first. ## MODULE_SYSTEM.md The slice 3 write-up in §2.7.2: why `MODULES` spells out the id and the version (the offline no-op has to be a file read, not a fetch), the four decisions, the defect below, and a table of what the smoke proved against the real published v0.3.0 on a fresh database. **Two sections are corrected, not merely extended:** - **§2.5** promised "a declarative module set resolved at container start" and did not anticipate that two install surfaces need a rule about who wins. They do, and it is: the declaration owns what is **on the volume**, the row owns whether a module **runs**. Uninstalling a declared module from the panel returns its files at the next start and leaves it disabled. - **Decision 4's** "resolution runs before the server starts" is true of the *scan*, not of the process. It runs inside `start()`, before `app.js` is required — which is what buys it the database, and therefore the admin-managed host allowlist and the provenance columns. A pre-flight script would have had neither. ## MODULE_API.md §2.6 no longer says the fragments are replayed by `ensureSchema()`. They are for every caller except the server, which now scans the volume *later* than it ensures the schema and so replays them itself. That was a live defect for an afternoon and the shape of it is the part worth keeping: it announced itself only as the `no module scan in this process — skipping schema fragment replay` line, which is **correct output for `npm run seed`** and means the opposite in a booting server — and on a database whose tables already existed, the module started perfectly. Every suite in that repo stubs either the loader or the pool, so none could see it; booting against an empty database did. Nothing about the contract moves — fragments still run after core's tables exist and before any `onBoot` — so **`MODULE_API_VERSION` is unchanged**. §2.5's lifecycle diagram gains the resolution step ahead of `require(module)`. ## BACKEND_DESIGN.md The boot sequence in the source tree, and `MODULES` beside the `module_source_hosts` setting it installs through — including that it is not a settings row and not editable from the panel. The route manifest is unchanged (166 public + 2 internal), so `api-route-inventory.json` needs no refresh this slice. --- Docs only. ### AI disclosure - [x] This contribution was AI-assisted (Claude Code). 🤖 Generated with [Claude Code](https://claude.com/claude-code)

wtclaude added 1 commit 2026-08-12 12:58:31 +00:00

docs(website): record slice 3, and the boot-order defect it created 102ea6db19

MODULE_SYSTEM.md §2.7.2 gains the slice 3 write-up: why the id and version are
written out in MODULES (the offline no-op has to be a file read, not a fetch),
the four decisions, and the table of what the smoke proved against the real
v0.3.0 release on a fresh database.

Two sections are corrected rather than extended. §2.5's "declarative module set"
promise did not anticipate that the two install surfaces need a rule about who
wins — the declaration owns the volume, the row owns whether a module runs — and
decision 4's "resolution runs before the server starts" is true of the SCAN, not
of the process: it runs inside start(), which is what buys it the database.

MODULE_API.md §2.6 no longer says the fragments are replayed by ensureSchema().
They are, for every caller except the server, which scans the volume later than
it ensures the schema and so replays them itself. That was a live defect for an
afternoon: it announced itself only as the "no module scan in this process" skip
line, which is correct output for `npm run seed` and means the opposite in a
booting server, and on a database that already had the tables the module started
perfectly. Nothing in the contract moves, so MODULE_API_VERSION is unchanged.

BACKEND_DESIGN.md: the boot sequence in the tree, and MODULES beside the
module_source_hosts setting it installs through.

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

whitlocktech merged commit 49ab5a1266 into main

2026-08-12 13:02:02 +00:00

whitlocktech deleted branch docs/module-phase4-slice3

2026-08-12 13:02:03 +00:00

whitlocktech referenced this issue from a commit

2026-08-12 13:02:04 +00:00

Merge pull request 'docs(website): record phase 4 slice 3, and the boot-order defect it created' (#143) from docs/module-phase4-slice3 into main

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: RunicGateway/docs#143