60 lines
3.3 KiB
Markdown
60 lines
3.3 KiB
Markdown
---
|
|
status: resolved
|
|
opened: 2026-10-03
|
|
located-in:
|
|
- mesh-tools
|
|
fixed-by: mesh-tools #32
|
|
amended-design:
|
|
---
|
|
|
|
# 209 — A bundle's own copy of the SDK registers into a registry the runtime never reads
|
|
|
|
## What was observed
|
|
|
|
2026-10-03, preparing [design 38](../../03-DESIGN/01-to-be/38-building-the-operators-machine.md)
|
|
WP4 — the first module whose tools bundle the node's runtime would load beside its own. Before the
|
|
manifest changed, a probe on the laptop did what the runtime does: a process holding one copy of
|
|
`@novox/mesh-sdk` imported a bundle in another directory that carried its own copy, and the bundle
|
|
called `registerModuleTools` as every tools entrypoint does.
|
|
|
|
```
|
|
registrations seen by host after importing bundle: 0
|
|
```
|
|
|
|
The import succeeds, the bundle registers, and the runtime's `collectTools` sees nothing. The
|
|
runtime would log the bundle as loaded and answer `tools` for the module with an empty list: silent,
|
|
and indistinguishable from a module that serves nothing by choice.
|
|
|
|
## Why it matters beyond this instance
|
|
|
|
WP3 found that *a TypeScript bundle must carry its dependencies*, and the toolchain copies them in
|
|
so a bundle starts anywhere. Among them is the SDK. The runtime imports a bundle in-process, and
|
|
the language resolves a bare import from the importing file's own tree — so every bundle brings a
|
|
second SDK into the process: its own registry of tools and its own broker handle. The SDK's registry
|
|
is a module-level list, and the runtime reads only the one it imported itself.
|
|
|
|
Every module from WP4 on is loaded this way. The runtime's tests never met it because their fixture
|
|
bundles sit under the runtime's own tree and resolve the same copy. Nothing in design 38 WP1 or WP3
|
|
says which SDK a loaded bundle speaks to, and the one-runtime record
|
|
([ADR 0175](../../02-DECISIONS/0175-one-tool-runtime-per-node-serves-every-modules-tools-on-the-host-side.md))
|
|
assumes without saying that it is the runtime's.
|
|
|
|
## Diagnosis
|
|
|
|
Owner mesh-tools (`node-tools`): the runtime imports a bundle's entrypoint and counts the
|
|
registrations that appear after it, through the SDK it imported; the bundle's `import "@novox/mesh-sdk/tools"`
|
|
resolves to the copy under the bundle's own `node_modules`. **Fix direction:** the runtime resolves
|
|
every import of the SDK, from whichever bundle, as if the runtime had written it — one registry,
|
|
one broker — and leaves everything else a bundle carries to the bundle's own tree. A test loads a
|
|
bundle from a directory holding its own copy of the SDK and asserts its tools are served. The
|
|
toolchain keeps copying dependencies in: a bundle launched as a process ([ADR 0188](../../02-DECISIONS/0188-a-modules-own-code-is-bundles-in-any-language-and-a-tools-bundle-speaks-mcp-to-the-runtime.md))
|
|
needs them, and an imported one is simply not allowed to bring a second SDK.
|
|
|
|
## Resolution
|
|
|
|
2026-10-03, mesh-tools #32: the runtime installs a synchronous resolve hook before the first bundle is
|
|
imported, sending every import of the SDK, from whichever bundle, to its own copy; a bundle's other
|
|
dependencies still resolve from its own tree, and a bundle launched as a process is untouched. The test
|
|
loads a bundle from a directory holding its own copy of the SDK and its own dependency, and sees its
|
|
tool served with the dependency's answer. Proven live by WP4's proof in design 38.
|