Files
jason.woltjeandClaude Opus 5.5 09447eb677 docs: add Dewey row 131 r1 packet (plug-in kind registry and loader)
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]>
2026-10-15 11:23:33 -05:00

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

  1. 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.
  2. A refused write throws a code and logs nothing. set checks the request shape (invalid-request: anything but revision and plugins, or a revision that isn't 64 hex) and the value (invalid-plugins, from checkPlugins) before the writer runs. The writer validates the whole document before its prepared entry, so nothing reaches changes.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 (plugins with old null when the key was absent; plugins.<kind> with whole old and new lists after that). Load-time refusals go through the loader's log callback.
  3. 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() and loaded() report what each kind actually has on. Every refusal calls log once 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.
  4. Export contract. Every module exports interfaceVersion; usage-source exports readTurn; limit-check exports mayLaunch and mustStop; 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.
  5. What is checked. packages/plugins, <kind>, <name> (each an lstat: exists, a directory, not a symlink) and index.mjs (exists, a regular file, not a symlink); not the ancestors of packages/plugins. Just before import, realpath(index.mjs) must equal realpath(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.