Skip to content

Native modules: Bun, Nix shell, container; /modules explain and timings (#364, #365) - #417

Merged
raiseCatError merged 2 commits into
devfrom
feature/v021-modules
Oct 18, 2026
Merged

raiseCatError merged 2 commits into
devfrom
feature/v021-modules

Conversation

@raiseCatError

Copy link
Copy Markdown
Owner

Stacked on #416 (/track) → #415 → #414 → #413 → #412 → #411. Merge in order.

What

Modules (#364)

These are the remaining safe candidates from the coverage matrix. All three follow the existing rules: declarative files, allowlisted variables and marker-file presence only, and nothing is ever run.

Module Pack Facts
Bun nmsh.project requested version from .bun-version, or package.json (packageManager: "bun@…" is exact, engines.bun is a range); active version from the install location; onCommand (bun, bunx); recommended when bun.lock(b), bunfig.toml or .bun-version exists
Nix shell nmsh.environment IN_NIX_SHELL → pure / impure (active for older nix that sets 1); recommended for flake.nix / shell.nix
Container nmsh.system CODESPACES / REMOTE_CONTAINERS = true, then /run/.containerenv (Podman) or /.dockerenv (Docker) presence; contents are never read

Supporting changes:

  • IN_NIX_SHELL, REMOTE_CONTAINERS and CODESPACES join the shell's allowlisted value report. The snapshot protocol carries uppercase names only, which is why Nix's lowercase name is not used.
  • The pack schema's requires bound rises from 16 to 24, the same as modules. The project pack needed a 17th capability. The bound was undocumented, and the larger limit still holds packs to a fixed size.
  • Existing icons are reused (code, cubes); no new code points were guessed.

Diagnostics (#365)

dev already shows per-module Why, Source (scope and trust), Cache (TTL, invalidation, refresh) and per-capability state, age and timing. This adds the two gaps the issue lists:

  • /modules explain writes, for each configured module, its surface, whether it is on screen and why, and each source's state, age, last collection time and evidence summary.
  • /modules timings writes the slowest last collections, with honest wording when nothing was measured.

Both are written as transcript blocks from the engine's snapshots: no values are shown and nothing is collected.

The coverage matrix (docs/design/native-module-coverage.md) is updated with a dated v0.21 review. Kotlin/Scala, Lua and Haskell remain candidates, with reasons given.

Tests

  • contextCapabilities.test.ts:
    • Bun from each source, with a Homebrew-layout active version and a mismatch;
    • a hostile package.json (an injected packageManager, a non-object engines) stays inert data;
    • the bun sentinel is never run;
    • Nix states;
    • container precedence, decided by the real marker files only.
  • moduleReport.test.ts: parse; explain (routing, off, uninstalled, inert evidence, snapshot-only); timings (order, bound, empty).
  • 50 context, module, pack, prompt, rail, strip and Ask files pass. One count assertion changed (nmsh.project · 17 modules).

Not verified

Physical checks: docs/testing/v021-physical-qa.md section 6 (Nix and container need such hosts). Not run.

Refs #364, #365, #410

…mings (#364, #365)

Bun's requested version comes from .bun-version or package.json
(packageManager, engines.bun) and the active one from its install location;
the Nix shell module reads IN_NIX_SHELL; the container module names Docker,
Podman, a dev container or Codespaces from marker files and host variables.
Nothing is run. IN_NIX_SHELL, REMOTE_CONTAINERS and CODESPACES join the shell's
allowlisted environment report. A Context Pack may now require 24
capabilities (as many as its modules), since the project pack needed a 17th.

/modules explain and /modules timings write plain-text reports from the
engine's snapshots: each configured module's surface, visibility reason and
sources' state, age and timing; or the slowest last collections. No value is
shown and nothing is collected to produce them.
@raiseCatError
raiseCatError changed the base branch from feature/v021-track to dev October 18, 2026 14:13
@raiseCatError
raiseCatError merged commit ac543bd into dev Oct 18, 2026
20 of 24 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant