Candidate packet for #1626: build.patch on 0bdd573ff, candidate manifest,
targeted gate (588/0 over plugins, business, bus, webui, cli) and 42/42
mutants killed.
Co-Authored-By: Claude Opus 5.5 <[email protected]>
7.5 KiB
Row 131 / #1626: the plug-in layer, kind registry and loader (round 1)
Builder: Dewey. Brief: docs/plans/2026-10-14_prd-1.2-build.md, step 6b.
Requirements: REQ-PLUG-1 (the plug-in layer), REQ-LIMIT-4 (the first two kinds,
usage-source and limit-check). The plugins write goes through step 5's write
path (REQ-ROLE-3). Base: see base.txt. Source is in a detached worktree; nothing
here is pushed, wired into a host process or written to Jason's organization file.
Governing rulings: lead decision 143 (in-repo modules only until Jason rules on Vikunja #286; no path from config) and sage-0301 (choices 1, 3, 4 and 5 as proposed; choice 2 changed).
What ships
| Path | Change |
|---|---|
packages/plugins/package.json |
new package @mosaic/plugins |
packages/plugins/src/kinds.mjs |
kind registry: usage-source and limit-check, interface version 1, each switched on by a list; checkPlugins for the organization file's plugins key |
packages/plugins/src/loader.mjs |
createLoader({log}) → {load, loaded, modules} |
packages/plugins/README.md |
kinds, export contract, adding a module, the key, the loader and its limits |
packages/plugins/tests/{helpers,kinds.test,loader.test}.mjs |
19 tests |
packages/business/src/business.mjs |
plugins in TOP_KEYS; checked with checkPlugins; returned frozen ({} when absent) |
packages/business/src/plugin-settings.mjs |
the host setter: the only writer of plugins, through organizationWriter |
packages/business/tests/plugin-settings.test.mjs |
3 tests: schema, setter success and log, setter refusals |
packages/business/README.md |
the plugins key and its writer |
scripts/stack-copy.sh |
whole packages/plugins in COPY_PATHS (approved, sage-0301) |
packages/cli/tests/stack-copy.test.mjs |
the copied-path list includes the plug-in sources |
No module of either kind ships. No core module imports a plug-in module by
name: business.mjs and plugin-settings.mjs import only kinds.mjs, and
nothing imports loader.mjs outside its tests. organization.mjs is untouched.
No limit ceiling is in code (Q150).
sage-0301 rulings, as built
- One writer.
pluginSettings({dir, rolesDir}).set(id, {revision, plugins}, actor)is the only writer. No broker verb, mosaic command, Settings form or chief-of-staff write was added. - A refused write throws a code and logs nothing.
setchecks the request shape (invalid-request: anything butrevisionandplugins, or a revision that isn't 64 hex) and the value (invalid-plugins, fromcheckPlugins) before the writer runs. The writer validates the whole document before itspreparedentry, so nothing reacheschanges.jsonl. The test checks the file bytes are unchanged and the log is empty after eleven refusals. A committed write logs actor, transaction and old and new names per kind, the same way a limit change does (pluginswith old null when the key was absent;plugins.<kind>with whole old and new lists after that). Load-time refusals go through the loader'slogcallback. - Last good modules per kind. A loader instance holds, per kind, the
modules from its last good load. Any refusal for a kind keeps them. A kind
refused on its first load has nothing on. The test loads
["meter","absent"]so a half-loaded list would show.load()andloaded()report what each kind actually has on. Every refusal callslogonce with{event: "plugin-refused", kind, name, code, message, kept}; the first-load test checks kind and name. The loader is not wired into any host process. - Export contract. Every module exports
interfaceVersion; usage-source exportsreadTurn; limit-check exportsmayLaunchandmustStop; both kinds switch on a list. The README carries the contract. These names bind row 124. Argument and return shapes are left to the calling rows. - What is checked.
packages/plugins,<kind>,<name>(each an lstat: exists, a directory, not a symlink) andindex.mjs(exists, a regular file, not a symlink); not the ancestors ofpackages/plugins. Just beforeimport,realpath(index.mjs)must equalrealpath(packages/plugins)/<kind>/<name>/index.mjs, and the import uses that expected path.
The check-then-import gap
For Darkwing, in those words: there is a check-then-import gap. The lstat
checks and the realpath comparison run, then import() opens the file by path.
Someone who can write packages/plugins as the host's user can swap
index.mjs (or a directory above it) between the realpath check and the open
inside import(). Node has no import-from-descriptor, so the loader cannot
close the gap. The checks catch mistakes, stale links and a link planted
before load; they do not stop a writer racing the host as the same user, and
such a writer could edit any core file anyway. The test with the checked
barrier swaps index.mjs for a symlink after the lstat checks and shows the
realpath check refusing it; it cannot show the narrower window after realpath.
The README states the same limit. Two related limits: a module runs with the
host's authority once imported (the loader does not sandbox it), and Node
caches modules by URL, so a changed index.mjs is not re-read until restart.
The packages/plugins symlink case is only reachable when Node keeps symlinked
paths (--preserve-symlinks); otherwise import.meta.url is already the real
path. The test runs that case in a child node --preserve-symlinks.
Acceptance, mapped
| Acceptance item | Where |
|---|---|
| a test for each refusal, old setting kept | loader.test.mjs: bad name, missing (absent dir, empty dir, dir as index), symlink (name dir, index, kind dir, packages/plugins, realpath swap), load-failed (syntax error, top-level throw), missing export (absent, non-function, half of limit-check, no interfaceVersion), interface version (2, string "1"); each through refusesKeepingOld, which checks the kept setting, the one refusal entry and the one log call |
| fixture module of each kind switched on from a test organization file, no core file changed | loader.test.mjs first test: a business document built with business test helpers, validated by validateBusinessDocument, its plugins passed to the loader; fixture modules written into a temp copy of the package |
| one mutant per check, each failing a test | MUTANTS.md, mutants.py, mutants/results.json |
plugins key in the schema, written through step 5's write path and logged like a limit change |
plugin-settings.test.mjs |
REQ ids are in each test name.
Gate (decision 136, targeted)
Approved list (sage-0301): plugins, business, bus, webui, cli, each
node --test tests/*.test.mjs (the command land-work.sh runs), via gate.sh.
Run 2026-10-15T16:20:28Z to 16:21:48Z in the slot Sage gave in sage-0310, on the
candidate as shipped in build.patch. Logs: gate/, summary gate-run.log.
| Package | Tests | Pass | Fail |
|---|---|---|---|
| plugins | 19 | 19 | 0 |
| business | 91 | 91 | 0 |
| bus | 171 | 171 | 0 |
| webui (includes pinned-copy.test.mjs) | 112 | 112 | 0 |
| cli (includes stack-copy.test.mjs) | 195 | 195 | 0 |
Not run: the other packages and the shell suites; Sage's full gate at the
landing target covers them (decision 136). BASE..refactor HEAD (ea5e70fa8 at
packet time) touches none of the candidate's paths.
Mutants: 42 of 42 killed (MUTANTS.md).
Overlap
Row 123 (Researcher) also edits packages/business/README.md. Sage orders the
landings; the second row rebases.