Challenge reload uses stale ESM module after same-name package upgrade

[tomcasaburi]

Problem

Replacing an installed challenge package while bitsocial daemon is running can leave the daemon executing the old package code even though:

• bitsocial challenge list reports the new version;
• POST /api/challenges/reload returns ok: true and reports the new version.

A daemon restart then makes the new behavior appear.

Root cause

loadChallengesIntoPKC() imports every installed package from the same entry URL on every reload:

const imported = await import(pathToFileURL(entryPath).href);

Node caches ESM modules by URL. The installer atomically replaces the package at the same destination path, so reloading the unchanged URL returns the previously evaluated module. The endpoint therefore updates metadata from the new package.json while assigning the old cached factory back to PKC.challenges[name].

The current integration test only installs a new package name, so it does not exercise replacement of an already-imported package.

Scope / ownership

This should be solvable in bitsocial-cli only:

• bitsocial-cli owns package installation and loadChallengesIntoPKC();
• bitsocial-cli owns /api/challenges/reload;
• the loader already assigns factories into the mutable PKC.challenges registry.

No pkc-js API change appears necessary.

The maintained Bitsocial challenge packages currently build to a single bundled dist/index.js, so importing the entry under a stable content/version-specific URL is sufficient for the supported packages. Prefer a content-derived key over an ever-changing nonce so repeated reloads of unchanged code do not create unnecessary module instances. If arbitrary multi-file package graphs are intended to be hot-reloadable too, document the bundled-entry constraint or use a generation-specific real path.

Proposed fix

• Make loadChallengesIntoPKC() import changed challenge entry code under a URL that changes when the installed package contents change.
• Keep repeated reloads of unchanged package contents stable/idempotent.
• Ensure the reload response cannot claim a new version while the previous factory remains active.
• Preserve startup loading and installation of entirely new challenge names.

Regression test

Extend test/cli/challenge-integration.test.ts:

1. Install and exercise test-challenge@1.0.0.
2. While the daemon remains running, replace it with test-challenge@2.0.0 under the same package name, with observably different challenge text/answer.
3. Let the install command trigger reload, or call /api/challenges/reload.
4. Assert the response reports v2 and a publication exercises v2 behavior without restarting the daemon.
5. Optionally reload again without changing files and assert behavior remains v2.

Acceptance criteria

• Same-name challenge upgrades take effect without restarting bitsocial daemon.
• Reported package version and active factory behavior agree.
• The regression test fails against the current loader and passes with the fix.
• No pkc-js modification is required unless the investigation uncovers a concrete missing API.

[Rinse12]

Reproduced. Confirmed the root cause as described: loadChallengesIntoPKC() imports each package from a stable file:// URL, so Node's ESM cache returns the previously evaluated module after challenge install swaps a new build into the same destination path. Metadata comes from the freshly-read package.json, so the reload response reports the new version while PKC.challenges[name] gets the old factory reassigned.

Also verified on the pkc-js side that no API change is needed: resolveChallengeFactoryByName() reads pkc.settings.challenges[name] (falling back to the shared pkcJsChallenges registry that the loader mutates) on every challenge request, so a running community picks up a replaced factory immediately — the ESM cache is the only thing in the way.

Red tests added on branch test/challenge-stale-module-reload-124:

• test/cli/challenge-loader-module-cache.test.ts — fast, no daemon: load v1, swap the package dir for v2 at the same path, reload, assert the active factory matches the reported version. A second test asserts reloading unchanged contents does not create a new module instance.
• test/cli/challenge-integration.test.ts — the regression test described in the issue: upgrade test-challenge 1.0.0 → 2.0.0 under a running daemon, reload, assert a publication exercises v2 behavior without a restart, and that a repeat reload keeps v2 active.

Both fail today with expected '1+1' to be '3+3', after passing the assertion that the reload response reports test-challenge@2.0.0 — exactly the version/behavior disagreement in the issue.

Fix to follow in a separate PR.

[Rinse12]

Reproduction tests opened as #125 (draft — CI red by design). Fix will follow in a separate PR stacked on test/challenge-stale-module-reload-124.

[Rinse12]

Consolidated into a single PR: #125 now carries both the reproduction tests and the fix (test commit first, fix commit second, so the red→green transition is visible in the branch history). It is out of draft.

Fix: import each challenge entry under a URL keyed on a sha256 of the package's own source instead of the bare file path. Changed contents → new key → the entry re-evaluates; unchanged contents → byte-identical key → cached → same factory identity, so repeated reloads stay idempotent. Content-derived rather than a nonce, per the issue's guidance.

Documented constraint at the import site: only the entry module re-evaluates, since relative imports inside a package do not inherit the query. Challenge packages are expected to ship a bundled entry point.

Full suite locally: 41 files, 313 passed, 1 skipped.

[Rinse12]

Follow-up in the same PR (#125): checking whether bitsocial challenge install <newer-version> updates a running daemon immediately turned up a second path to the same stale-code symptom, independent of the module cache.

install.ts and remove.ts fired their best-effort reload at a hardcoded http://localhost:9138, so a daemon started with --pkcRpcUrl never learned about an install — and the POST was sent regardless of which data path the running daemon served. Reload targets now come from the state files running daemons write (DaemonState.pkcRpcUrl), filtered to daemons serving the same data path. Covered by unit tests for the url/data-path derivation plus an integration test that runs challenge install against a daemon on a dynamic port with no explicit reload call anywhere.

Separate gap, deliberately not fixed here: loadChallengesIntoPKC() only adds to the registry, so challenge remove still leaves the removed factory registered until restart. Un-registering needs care because PKC.challenges is pkc-js's built-in registry — deleting a key that shadowed a built-in (e.g. a package named question) would destroy the built-in. Happy to open a separate issue for it if wanted.