dsh-composition-doctor 0.2.2 → 0.4.0

package/dist/core/failure-explainer.js

@@ -0,0 +1,205 @@
+export const maxFailureLogBytes = 1024 * 1024;
+const titles = {
+    'duplicate-loader-entry': 'Duplicate loader entry id', 'bundle-unavailable': 'Profile bundle cannot be resolved',
+    'bundle-patch-unavailable': 'Bundle patch is unavailable', 'patch-target-missing': 'Patch entry not found',
+    'peer-incompatible': 'Plugin peer/version incompatibility', 'config-replacement': 'Whole-config replacement / row override'
+};
+const ids = {
+    'duplicate-loader-entry': ['duplicate-loader-declarations', 'duplicate-row-in-same-layer', 'intentional-row-override'],
+    'bundle-unavailable': ['bundle-not-installed'],
+    'bundle-patch-unavailable': ['bundle-patch-missing', 'bundle-patch-unavailable', 'bundle-patch-invalid', 'bundle-patch-unsafe'],
+    'patch-target-missing': ['unmatched-patch-target'], 'peer-incompatible': ['peer-version-mismatch', 'peer-version-facts-unavailable'],
+    'config-replacement': ['row-config-replacement-risk', 'intentional-row-override']
+};
+/** No raw log lines, stack traces, URLs, paths or values are persisted. */
+export function safeFailureEntity(value) {
+    return /^(?:@[a-z0-9_.-]+\/)?[a-z0-9_][a-z0-9_.:-]{0,159}$/i.test(value) &&
+        !/(?:^(?:sk-|gh[pousr]_|eyJ)|token|password|credential|secret|authorization)/i.test(value) ? value : undefined;
+}
+export function matchFailureSignatures(log) {
+    const signatures = new Map();
+    const entity = '(?:@[a-z0-9_.-]+/)?[a-z0-9_][a-z0-9_.:-]{0,159}';
+    const add = (pattern, value) => {
+        const candidate = value === undefined ? undefined : safeFailureEntity(value);
+        if (value !== undefined && candidate === undefined)
+            return;
+        const signature = { pattern, ...(candidate === undefined ? {} : { entity: candidate }) };
+        if (signatures.size < 32)
+            signatures.set(`${pattern}:${candidate ?? ''}`, signature);
+    };
+    // Bound the work before matching; strip terminal control sequences, never render them.
+    const text = log.slice(0, maxFailureLogBytes).replace(/\x1b\[[0-?]*[ -/]*[@-~]/g, '');
+    for (const line of text.split(/\r?\n/)) {
+        if (line.length > 4096)
+            continue;
+        let match = new RegExp(`duplicate loader entry id:\\s*["']?(${entity})(?=["'\\s]|$)`, 'i').exec(line);
+        if (match)
+            add('duplicate-loader-entry', match[1]);
+        match = new RegExp(`cannot resolve profile bundle ["'](${entity})["']`, 'i').exec(line);
+        if (match)
+            add('bundle-unavailable', match[1]);
+        match = new RegExp(`patch:\\s*entry ["'](${entity})["'] not found`, 'i').exec(line);
+        if (match)
+            add('patch-target-missing', match[1]);
+        if (/failed to read overlay\b/i.test(line)) {
+            match = new RegExp(`node_modules[\\\\/](${entity.replace('/', '[\\\\/]')})[\\\\/]cordis\\.patch\\.ya?ml(?=[\\s:]|$)`, 'i').exec(line);
+            add('bundle-patch-unavailable', match?.[1]?.replaceAll('\\', '/'));
+        }
+        match = new RegExp(`incompatible-version:\\s*(${entity})(?=[\\s,]|$)`, 'i').exec(line);
+        if (match)
+            add('peer-incompatible', match[1]);
+        match = new RegExp(`Plugin (${entity})@[0-9][a-z0-9.+-]* is incompatible with dsh [0-9][a-z0-9.+-]*: peerDependencies`, 'i').exec(line);
+        if (match)
+            add('peer-incompatible', match[1]);
+        else if (/\bERR_PNPM_PEER_DEP_ISSUES\b|\bplugin compatibility failure\b/.test(line))
+            add('peer-incompatible');
+    }
+    return [...signatures.values()];
+}
+function path(row) {
+    return { source: row.source, ...(row.layer === undefined ? {} : { layer: row.layer }),
+        ...(row.packageName === undefined ? {} : { packageName: row.packageName }),
+        ...(row.id === undefined ? {} : { rowId: row.id }), rowKey: row.key, provenance: row.provenance, evidence: row.evidenceMode };
+}
+function distinctRows(rows) {
+    // Preserve same-layer duplicates with their own row keys.
+    return [...new Map(rows.map((row) => [row.key, row])).values()];
+}
+function diagnosticEntities(diagnostic) {
+    return [...new Set(diagnostic.evidence.flatMap((item) => {
+            return [item.packageName, item.subject].filter((name) => name !== undefined && safeFailureEntity(name) !== undefined);
+        }))];
+}
+function explain(signature, report, reported) {
+    const { pattern, entity } = signature;
+    const allRows = report.compositionFacts?.rows ?? [];
+    const rowPattern = pattern === 'duplicate-loader-entry' || pattern === 'patch-target-missing' || pattern === 'config-replacement';
+    const rows = allRows.filter((row) => rowPattern ? row.id === entity :
+        row.packageName === entity || row.provenance.some((step) => step.source === entity));
+    const diagnostics = report.diagnostics.filter((item) => ids[pattern].includes(item.id) &&
+        (entity === undefined || diagnosticEntities(item).includes(entity)));
+    let paths = distinctRows(rows).map(path);
+    let cause = 'unknown: the reported signature has no supporting condition in the selected profile evidence.';
+    let observed = false;
+    let evidenceLevel = 'unknown';
+    const unknowns = ['Runtime failure and plugin behavior: not observed / not-run.'];
+    let remediation = 'Check the selected profile directory and capture the first DSH error. Compare it with the observed rows; do not remove a plugin based on a log string alone.';
+    if (pattern === 'duplicate-loader-entry') {
+        const inserted = distinctRows(rows.filter((row) => row.operation === 'insert' || row.operation === 'declare'));
+        const composed = distinctRows(rows.filter((row) => row.evidenceMode === 'composed'));
+        const candidates = composed.length > 1 ? composed : inserted;
+        paths = candidates.map(path);
+        if (candidates.length > 1) {
+            observed = true;
+            evidenceLevel = composed.length > 1 ? 'composed' : 'static';
+            cause = evidenceLevel === 'static'
+                ? `${entity} is introduced by ${candidates.length} separate loader declarations. Both inserts use the same id; the final loader outcome is unknown until composition/runtime is observed.`
+                : `${entity} occurs more than once in the observed composed tree. These entries share a loader id; runtime rejection was not observed by Doctor.`;
+        }
+        else
+            unknowns.push('Two independent loader insert paths were not observed. An update or provenance patch chain is not a second insertion.');
+        remediation = 'Review the listed bundle declarations and profile patch. Keep one intended insertion for this id after checking its config; use why row and impact bundle for details.';
+    }
+    else if (pattern === 'config-replacement') {
+        const updates = rows.filter((row) => row.operation === 'update' && row.replacement.state !== 'no');
+        const replacements = rows.filter((row) => row.evidenceMode === 'composed' && row.replacement.state === 'yes');
+        const chain = rows.filter((row) => row.provenance.length > 1);
+        if (updates.length > 0 || replacements.length > 0 || chain.length > 0) {
+            observed = true;
+            evidenceLevel = replacements.length > 0 || chain.some((row) => row.evidenceMode === 'composed') ? 'composed' : 'static';
+            cause = replacements.length > 0 ? 'The composition provider explicitly reports a replacement for this row.' : updates.length > 0
+                ? 'The profile declares a config update for this row. DSH patch semantics replace the whole config rather than deep-merge its keys.'
+                : 'The public composition source chain records this row being patched by a later source. Whole-config replacement is unknown without explicit replacement evidence.';
+            const previous = rows.filter((row) => row.operation === 'insert' || row.operation === 'declare');
+            if (previous.length > 0 && updates.length > 0) {
+                const dropped = previous.flatMap((row) => row.configKeys).filter((key) => !updates[updates.length - 1].configKeys.includes(key));
+                if (dropped.length > 0)
+                    cause += ` The later declaration omits ${new Set(dropped).size} earlier config key(s); this is a static difference, not proof of runtime data loss.`;
+            }
+            unknowns.push('Prior effective values, field ownership and runtime effects are unknown. A source chain alone does not prove removed keys.');
+        }
+        remediation = 'Review the earlier row and the later patch together. Include required non-secret fields in the complete replacement config, then compare snapshots/diff or run preflight before upgrading.';
+    }
+    else if (pattern === 'patch-target-missing') {
+        const composedMissing = diagnostics.some((item) => item.evidence.some((entry) => entry.evidenceKind === 'composed' && entry.subject === entity));
+        const updates = rows.filter((row) => row.operation === 'update');
+        const introduction = rows.some((row) => row.operation === 'insert' || row.operation === 'declare');
+        if (composedMissing || (updates.length > 0 && !introduction && !rows.some((row) => row.evidenceMode === 'composed'))) {
+            observed = true;
+            evidenceLevel = composedMissing ? 'composed' : 'static';
+            cause = composedMissing ? 'The public dump provider reports that this patch target did not match a composed row.' :
+                'A patch targets this id, but no insertion is present in the permitted selected profile metadata. A built-in, home or CLI layer could still supply it; final absence is unknown.';
+        }
+        remediation = 'Compare the patch id with the intended bundle row. Check whether the bundle is declared and available; inspect home/CLI layers manually if they supply the row.';
+    }
+    else {
+        const supporting = diagnostics.filter((item) => pattern !== 'peer-incompatible' || item.id === 'peer-version-mismatch');
+        if (supporting.length > 0 && entity !== undefined) {
+            observed = true;
+            evidenceLevel = 'static';
+            cause = pattern === 'bundle-unavailable' ? 'This bundle is declared in dsh.profile.bundles, but the bounded resolver cannot read its package metadata inside the selected profile. An installation-level bundle or external link may still exist.' :
+                pattern === 'bundle-patch-unavailable' ? 'The declared bundle has missing, invalid or disallowed patch metadata. Its manifest declaration does not supply an observable loader contribution.' :
+                    supporting.map((item) => item.evidence.map((entry) => entry.detail).join('; ')).join('; ');
+        }
+        paths = [...paths, ...diagnostics.flatMap((item) => item.evidence.map((entry) => ({ source: entry.source,
+                ...(entry.packageName === undefined ? {} : { packageName: entry.packageName }), provenance: [], evidence: entry.evidenceKind })))];
+        remediation = pattern === 'peer-incompatible' ? 'Compare the installed plugin peer range with the selected DSH version. Choose a tested compatible pair or rehearse it with preflight; a peer warning alone does not prove a crash.' :
+            pattern === 'bundle-unavailable' ? 'Review package.json → dsh.profile.bundles and the intended installed package or link. Confirm installation-level resolution manually before reinstalling anything.' :
+                'Review the bundle manifest → dsh.bundle.patch and packaged YAML file. Check the publisher tarball contents; do not substitute or execute a file suggested by the log.';
+        if (pattern === 'peer-incompatible' && !observed)
+            unknowns.push('The selected runtime version or exact affected package is unknown. Log-reported versions are not trusted runtime facts.');
+    }
+    if (evidenceLevel === 'static')
+        unknowns.push('Final composition: unknown. Home/CLI overlays and installation-level bundles are not inspected by the default static reader.');
+    if (entity === undefined)
+        unknowns.push('Offending entity: unknown; multiple packages may fit. No package was selected by guessing.');
+    const entityObserved = entity !== undefined && (rows.length > 0 || diagnostics.some((item) => diagnosticEntities(item).includes(entity)) || report.compositionFacts?.nodes.some((node) => node.entity === 'bundle' && node.label === entity) === true);
+    if (entity !== undefined && !entityObserved)
+        unknowns.push('Reported entity: not observed in selected profile/composition metadata.');
+    if (paths.length === 0)
+        unknowns.push('Provenance: unavailable / not observed.');
+    return { pattern, detectedFailure: `${titles[pattern]}${entity === undefined ? '' : `: ${entity}`}`, origin: reported ? 'reported-by-log' : 'observed-from-composition',
+        ...(!entityObserved || entity === undefined ? {} : { matchedEntity: { kind: rowPattern ? 'row' : 'package', id: entity } }),
+        causeStatus: observed ? 'observable-condition' : 'unknown', observableCause: cause,
+        provenancePaths: [...new Map(paths.map((entry) => [`${entry.rowKey ?? ''}|${entry.source}|${entry.layer ?? ''}|${entry.packageName ?? ''}`, entry])).values()], evidenceLevel, unknowns, manualRemediation: remediation, relatedDiagnostics: diagnostics };
+}
+/** Pure matching/explanation layer; log strings cannot create composition facts. */
+export function explainFailures({ report, log }) {
+    const reported = log !== undefined;
+    const signatures = reported ? matchFailureSignatures(log) : [];
+    if (!reported) {
+        const add = (pattern, entity) => {
+            if (safeFailureEntity(entity) !== undefined && !signatures.some((item) => item.pattern === pattern && item.entity === entity))
+                signatures.push({ pattern, entity });
+        };
+        const rows = report.compositionFacts?.rows ?? [];
+        for (const row of rows) {
+            if (row.id === undefined)
+                continue;
+            if (rows.filter((other) => other.id === row.id && (other.operation === 'insert' || other.operation === 'declare')).length > 1 ||
+                rows.filter((other) => other.id === row.id && other.evidenceMode === 'composed').length > 1)
+                add('duplicate-loader-entry', row.id);
+            if (row.operation === 'update' && !rows.some((other) => other.id === row.id && (other.operation === 'insert' || other.operation === 'declare')))
+                add('patch-target-missing', row.id);
+            if ((row.operation === 'update' && row.replacement.state !== 'no') || row.provenance.length > 1 || row.replacement.state === 'yes')
+                add('config-replacement', row.id);
+        }
+        for (const diagnostic of report.diagnostics) {
+            for (const pattern of ['bundle-unavailable', 'bundle-patch-unavailable', 'peer-incompatible']) {
+                if (!ids[pattern].includes(diagnostic.id) || diagnostic.id === 'peer-version-facts-unavailable')
+                    continue;
+                for (const name of [...new Set(diagnostic.evidence.map((entry) => entry.packageName ?? entry.subject).filter((value) => value !== undefined))])
+                    add(pattern, name);
+            }
+        }
+    }
+    const explanations = signatures.slice(0, 50).map((signature) => explain(signature, report, reported));
+    const unreadable = report.diagnostics.filter((item) => ['profile-patch-invalid', 'bundle-inventory-manifest-invalid', 'runtime-composition-unavailable', 'composed-dump-parse-failed'].includes(item.id)).map((item) => item.id);
+    return { schemaVersion: 1, outcome: explanations.some((item) => item.causeStatus === 'observable-condition') ? 'explained' :
+            explanations.length > 0 || (!reported && unreadable.length > 0) ? 'unknown' : reported ? 'no-match' : 'no-supported-issues', profile: '<PROFILE>', runtime: 'not-observed',
+        input: { log: reported ? 'reported-by-log' : 'not-provided', recognizedSignatures: signatures.length,
+            truncated: signatures.length > 50 || (reported && signatures.length >= 32) || (log !== undefined && new TextEncoder().encode(log).length > maxFailureLogBytes) }, explanations,
+        unknowns: ['A recognized log signature is a report, not trusted composition or runtime evidence.', 'An absence of supported findings is not a healthy runtime verification.', ...unreadable.map((id) => `Metadata coverage incomplete: ${id}.`)],
+        nextStep: reported ? 'Review the named source paths. If the cause is unknown, verify the profile selection and compare a public dump, why row, snapshot/diff or preflight.' :
+            'To focus on a startup symptom: dsh-doctor diagnose --profile <dir> --log <file> (or pipe DSH stderr to diagnose).' };
+}

package/dist/core/failure-profile.js

@@ -0,0 +1,110 @@
+import { lstat, readFile, realpath } from 'node:fs/promises';
+import { isAbsolute, relative } from 'node:path';
+import { parse } from 'yaml';
+import { valid, validRange } from 'semver';
+import { resolveComposition } from './composition-adapter.js';
+import { safeFailureEntity } from './failure-explainer.js';
+function record(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function note(id, source, packageName, detail) {
+    return { id, severity: 'warning', title: detail,
+        evidence: [{ source, ...(packageName === undefined ? {} : { packageName, subject: packageName }), detail, evidenceKind: 'static' }],
+        explanation: detail, remediation: 'Review the declared bundle patch and selected profile. Doctor did not change either.' };
+}
+/** Parse declarations, never simulate a runtime tree or evaluate YAML tags. */
+function declarations(text, source, layer, layerOrder, bundle) {
+    const parsed = parse(text, { maxAliasCount: 50, logLevel: 'silent', customTags: [
+            { tag: 'tag:yaml.org,2002:js', resolve: () => '<runtime value: not-run>' },
+            { tag: 'tag:yaml.org,2002:js/function', resolve: () => '<runtime value: not-run>' }
+        ] });
+    const entries = Array.isArray(parsed) ? parsed : layer === 'cordis.yml' && record(parsed) ? parsed.plugins : undefined;
+    if (!Array.isArray(entries))
+        throw new Error('Patch must be a top-level array');
+    const rows = [];
+    const add = (entry, operation) => {
+        if (!record(entry))
+            return;
+        rows.push({ ...(typeof entry.id === 'string' && safeFailureEntity(entry.id) !== undefined ? { id: entry.id } : {}),
+            ...(typeof entry.name === 'string' && safeFailureEntity(entry.name) !== undefined ? { name: entry.name } : {}),
+            source, layer, layerOrder, provenance: [bundle ?? source], operation, evidenceKind: 'static',
+            ...(operation === 'update' && !('config' in entry) ? { replacement: false } : {}),
+            ...('config' in entry ? { configKeys: record(entry.config) ? Object.keys(entry.config).filter((key) => /^[a-z_][\w.-]{0,127}$/i.test(key)).sort() : [],
+                ...(operation === 'update' ? { replacement: true, replacementBasis: 'derived' } : {}) } : {}) });
+    };
+    for (const entry of entries) {
+        if (!record(entry))
+            continue;
+        if ('insert' in entry) {
+            if (!Array.isArray(entry.insert))
+                throw new Error('Insert must be an array');
+            for (const inserted of entry.insert)
+                add(inserted, 'insert');
+        }
+        else
+            add(entry, layer === 'cordis.yml' ? 'declare' : 'update');
+    }
+    return rows;
+}
+/** Default diagnose reads only selected profile metadata and declared YAML patches.
+ * It does not look up executables, launch DSH, import packages or run lifecycles. */
+export async function readFailureComposition(input, composed = false) {
+    const rows = [];
+    const diagnostics = [...input.inventoryDiagnostics];
+    const root = await realpath(input.profileDir);
+    for (const [index, pkg] of input.installedPackages.entries()) {
+        if (pkg.bundlePatch === undefined)
+            continue;
+        try {
+            const path = await realpath(pkg.bundlePatch);
+            const rel = relative(root, path);
+            // A manifest is untrusted: a patch declaration is not permission to read secrets.
+            if (isAbsolute(rel) || rel.startsWith('..') || !/\.(?:yml|yaml)$/i.test(path) ||
+                /(?:^|[\\/])(?:\.env[^\\/]*|[^\\/]*(?:credential|token|secret|password)[^\\/]*|sessions?|chats?|workspace)(?:[\\/]|$)/i.test(rel)) {
+                diagnostics.push(note('bundle-patch-unsafe', pkg.packageJsonSource, pkg.name, 'Declared patch is outside the permitted YAML metadata surface.'));
+                continue;
+            }
+            const meta = await lstat(path);
+            if (!meta.isFile() || meta.size > 1024 * 1024)
+                throw new Error('Patch unavailable');
+            rows.push(...declarations(await readFile(path, 'utf8'), path, `dsh.profile.bundles[${index}]: ${pkg.name}`, index, pkg.name));
+        }
+        catch {
+            // No parser snippets, values, or raw filesystem error text enter the report.
+            diagnostics.push(note('bundle-patch-invalid', pkg.packageJsonSource, pkg.name, 'Declared bundle patch is missing, unreadable, oversized or invalid YAML.'));
+        }
+    }
+    for (const file of input.files) {
+        if (file.relativePath !== 'cordis.yml' && file.relativePath !== 'cordis.patch.yml')
+            continue;
+        try {
+            rows.push(...declarations(file.text, file.relativePath, file.relativePath, input.installedPackages.length + (file.relativePath === 'cordis.yml' ? 0 : 1)));
+        }
+        catch {
+            diagnostics.push(note('profile-patch-invalid', file.relativePath, undefined, 'Selected profile YAML is invalid or not a supported top-level array.'));
+        }
+    }
+    const safeRange = (value) => value !== undefined && value.length <= 256 && validRange(value) !== null ? value : undefined;
+    const packages = input.installedPackages.filter((pkg) => safeFailureEntity(pkg.name) !== undefined).map((pkg) => ({
+        ...pkg, installedVersion: pkg.installedVersion !== undefined && valid(pkg.installedVersion) !== null ? pkg.installedVersion : undefined
+    }));
+    const peers = packages.flatMap((pkg) => [
+        { packageName: pkg.name, source: pkg.packageJsonSource, evidenceKind: 'static', cordis: safeRange(pkg.peerCordis), node: safeRange(pkg.engineNode) },
+        ...Object.entries(pkg.dshPeers ?? (pkg.peerDsh === undefined ? {} : { '@deepseek-ai/dsh': pkg.peerDsh })).map(([dshPackage, range]) => ({
+            packageName: pkg.name, source: pkg.packageJsonSource, evidenceKind: 'static', dshPackage,
+            dsh: ['workspace:^', 'workspace:~', 'workspace:*'].includes(range) ? range : safeRange(range)
+        }))
+    ]);
+    const base = { profileDir: root, rows, installedPackages: packages,
+        adapterDiagnostics: diagnostics, evidenceMode: 'static', runtimeObservation: { observed: false },
+        metadataCoverage: input.metadataCoverage, peerRequirements: peers,
+        runtime: { node: process.versions.node, platform: process.platform } };
+    if (!composed)
+        return base;
+    const observed = await resolveComposition(input);
+    // Preserve declarations separately via their evidence kind; a dump that dedupes
+    // rows cannot upgrade a static duplicate-path finding into a composed collision.
+    return { ...base, rows: [...rows, ...observed.rows.filter((row) => row.evidenceKind === 'composed')],
+        adapterDiagnostics: [...diagnostics, ...observed.adapterDiagnostics],
+        evidenceMode: observed.evidenceMode === 'composed' ? 'mixed' : 'static' };
+}

package/dist/core/package-provenance.js

@@ -36,6 +36,8 @@ export async function inspectInstalledPackage(profileDir, name, requestedSpec) {
     const resolvedSource = await realpath(source);
     if (!within(profileRoot, resolvedSource))
         throw new Error(`Bundle package resolves outside the selected profile: ${name}`);
+    if (!/[\\/]package\.json$/i.test(resolvedSource) || /(?:^|[\\/])(?:\.env[^\\/]*|workspace|sessions?|chats?|[^\\/]*(?:credentials?|tokens?|secrets?|password)[^\\/]*)(?:[\\/]|$)/i.test(resolvedSource))
+        throw new Error('Bundle manifest is outside the permitted metadata surface');
     const manifest = JSON.parse(await readFile(resolvedSource, 'utf8'));
     const dsh = record(manifest.dsh);
     const bundle = record(dsh?.bundle);
@@ -44,6 +46,7 @@ export async function inspectInstalledPackage(profileDir, name, requestedSpec) {
     const engines = record(manifest.engines);
     const scripts = record(manifest.scripts);
     const peerDsh = string(peers?.['@deepseek-ai/dsh']);
+    const dshPeers = Object.fromEntries(Object.entries(peers ?? {}).filter(([key, value]) => /^@deepseek-ai\/dsh(?:-[a-z0-9_.-]+)?$/i.test(key) && typeof value === 'string'));
     const peerCordis = string(peers?.['@deepseek-ai/cordis']) ?? string(peers?.cordis) ?? string(peers?.['@cordisjs/core']);
     const engineNode = string(engines?.node);
     const repository = repositoryValue(manifest.repository);
@@ -73,6 +76,7 @@ export async function inspectInstalledPackage(profileDir, name, requestedSpec) {
         modifiedAt: fileStat.mtime.toISOString(),
         ...(Array.isArray(manifest.os) ? { platform: manifest.os.filter((item) => typeof item === 'string') } : {}),
         ...(peerDsh === undefined ? {} : { peerDsh }),
+        ...(Object.keys(dshPeers).length === 0 ? {} : { dshPeers }),
         ...(peerCordis === undefined ? {} : { peerCordis }),
         ...(engineNode === undefined ? {} : { engineNode }),
         ...(scripts === undefined ? {} : { lifecycleScripts: ['preinstall', 'install', 'postinstall', 'prepare'].filter((key) => typeof scripts[key] === 'string') })

package/dist/core/preflight/npm-artifact.js

@@ -1,5 +1,5 @@
 import { createHash, randomBytes } from 'node:crypto';
-import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { lstat, mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
 import { basename, resolve } from 'node:path';
 import { gunzipSync } from 'node:zlib';
 function text(bytes) {
@@ -56,7 +56,23 @@ async function atomicWrite(path, bytes) {
     const temporaryPath = `${path}.${randomBytes(12).toString('hex')}.partial`;
     try {
         await writeFile(temporaryPath, bytes, { flag: 'wx' });
-        await rename(temporaryPath, path);
+        try {
+            await rename(temporaryPath, path);
+        }
+        catch (error) {
+            // Windows can refuse a competing rename after another downloader has
+            // already published this exact artifact. Accept only identical regular
+            // files; never unlink an existing cache entry to work around the race.
+            const code = error.code;
+            if (code !== 'EPERM' && code !== 'EEXIST')
+                throw error;
+            const existing = await lstat(path).catch(() => undefined);
+            if (!existing?.isFile() || existing.isSymbolicLink())
+                throw error;
+            const published = await readFile(path).catch(() => undefined);
+            if (published === undefined || !published.equals(Buffer.from(bytes)))
+                throw error;
+        }
     }
     finally {
         await rm(temporaryPath, { force: true }).catch(() => undefined);

package/dist/core/rules.js

@@ -1,4 +1,5 @@
 import { satisfies as semverSatisfies } from 'semver';
+import { buildCompositionFacts, redactDiagnosticPaths } from './composition-provenance.js';
 function evidence(source, subject, detail, evidenceKind, packageName, version) {
     return { source, subject, detail, evidenceKind, ...(packageName === undefined ? {} : { packageName }), ...(version === undefined ? {} : { version }) };
 }
@@ -29,6 +30,8 @@ function satisfiesRange(version, range) {
     if (parseVersion(version) === undefined || range.trim().length === 0)
         return undefined;
     try {
+        if (['workspace:^', 'workspace:~', 'workspace:*'].includes(range))
+            return true;
         return semverSatisfies(version, range, { includePrerelease: true });
     }
     catch {
@@ -46,7 +49,8 @@ function peerDiagnostics(model) {
             if (range === undefined)
                 continue;
             const actual = runtime[fact];
-            const item = evidence(peer.source, `${peer.packageName}:${fact}`, `requires ${fact} ${range}; observed ${actual ?? 'unknown'}`, peer.evidenceKind, peer.packageName);
+            const label = fact === 'dsh' ? peer.dshPackage ?? fact : fact;
+            const item = evidence(peer.source, `${peer.packageName}:${fact}`, `requires ${label} ${range}; observed ${actual ?? 'unknown'}`, peer.evidenceKind, peer.packageName);
             if (actual === undefined) {
                 diagnostics.push(diagnostic('peer-version-facts-unavailable', 'warning', 'Runtime version fact is unavailable', [item], `The ${fact} version needed to evaluate ${peer.packageName} was not supplied.`, 'Provide the selected runtime version or treat this static compatibility finding as unproven.'));
                 continue;
@@ -85,12 +89,16 @@ function rowKeys(row) {
 function rowDiagnostics(rows) {
     const diagnostics = [];
     for (const [id, group] of groups(rows.filter((row) => row.id !== undefined), (row) => row.id)) {
+        const inserts = group.filter((row) => row.operation === 'insert' || row.operation === 'declare');
+        if (inserts.length > 1) {
+            diagnostics.push(diagnostic('duplicate-loader-declarations', 'warning', 'Multiple loader declarations introduce the same row id', inserts.map((row) => evidence(row.source, id, 'An independent declaration introduces this loader id.', row.evidenceKind, row.name)), 'Separate insertion declarations share a loader id; static evidence does not prove the final loader outcome.', 'Review the bundle and profile insertion paths; retain the intended declaration and configuration manually.'));
+        }
         const layers = groups(group, (row) => row.layer ?? row.source);
         if (layers.size === 1 && group.length > 1) {
             diagnostics.push(diagnostic('duplicate-row-in-same-layer', 'warning', 'Duplicate composition row id in one layer', group.map((row) => evidence(row.source, id, `row id ${id} is declared more than once in the same layer`, row.evidenceKind, row.name)), `The DSH public row semantics do not establish which declaration should win within one layer for ${id}.`, 'Give the row a unique id or verify the final resolved tree with a public dump provider.'));
             continue;
         }
-        if (layers.size < 2)
+        if (layers.size < 2 || inserts.length === group.length)
             continue;
         const ordered = [...group].sort((left, right) => (left.layerOrder ?? Number.MAX_SAFE_INTEGER) - (right.layerOrder ?? Number.MAX_SAFE_INTEGER));
         const previous = ordered[ordered.length - 2];
@@ -157,6 +165,18 @@ export function analyseComposition(model) {
     }
     diagnostics.sort((left, right) => left.id.localeCompare(right.id) || left.title.localeCompare(right.title) || left.evidence[0]?.source.localeCompare(right.evidence[0]?.source ?? '') || 0);
     const evidenceMode = runtimeObserved ? 'runtime-observed' : requestedMode === 'runtime-observed' ? 'composed' : requestedMode;
-    const unverifiedFindings = diagnostics.filter((item) => item.id === 'runtime-composition-unavailable' || item.evidence.some((entry) => entry.evidenceKind === 'static')).map((item) => item.id);
-    return { schemaVersion: 1, evidenceSchemaVersion: 2, generatedAt: new Date().toISOString(), profileDir: model.profileDir, evidenceMode, runtimeObserved, ...(model.metadataCoverage === undefined ? {} : { metadataCoverage: model.metadataCoverage }), unverifiedFindings, diagnostics };
+    const redactedDiagnostics = redactDiagnosticPaths(diagnostics, model);
+    const unverifiedFindings = redactedDiagnostics.filter((item) => item.id === 'runtime-composition-unavailable' || item.evidence.some((entry) => entry.evidenceKind === 'static')).map((item) => item.id);
+    const reportBase = {
+        schemaVersion: 1,
+        evidenceSchemaVersion: 2,
+        generatedAt: new Date().toISOString(),
+        profileDir: '<PROFILE>',
+        evidenceMode,
+        runtimeObserved,
+        ...(model.metadataCoverage === undefined ? {} : { metadataCoverage: model.metadataCoverage }),
+        unverifiedFindings,
+        diagnostics: redactedDiagnostics
+    };
+    return { ...reportBase, compositionFacts: buildCompositionFacts({ ...model, evidenceMode }, redactedDiagnostics) };
 }

package/dist/core/snapshot.js

@@ -53,7 +53,7 @@ function snapshotFromModel(model, input) {
     const hashes = Object.fromEntries((input?.files ?? []).filter((file) => ['package.json', 'pnpm-lock.yaml', 'package-lock.json', 'yarn.lock'].includes(file.relativePath)).map((file) => [file.relativePath, file.sha256]));
     return {
         schemaVersion: 2,
-        doctorVersion: '0.1.3',
+        doctorVersion: '0.4.0',
         runtime: { ...(model.runtime?.dsh === undefined ? {} : { dsh: model.runtime.dsh }), ...(model.runtime?.cordis === undefined ? {} : { cordis: model.runtime.cordis }), node: model.runtime?.node ?? process.versions.node, platform: model.runtime?.platform ?? process.platform },
         profile: { ...(profileName === undefined ? {} : { name: profileName }), ...(manifest === undefined ? {} : { manifestHash: manifest.sha256 }) },
         packages: sortJson(packages),

package/dist/reports/failure.js

@@ -0,0 +1,23 @@
+export function renderFailure(result, markdown = false) {
+    const lines = [markdown ? '# DSH Composition Doctor — Failure Explanation' : 'DSH Composition Doctor — Failure Explanation', '',
+        `Profile: ${result.profile}; runtime: ${result.runtime}`, ''];
+    if (result.explanations.length === 0)
+        lines.push(result.outcome === 'no-match'
+            ? 'No supported failure signature matched. Cause: unknown.' : result.outcome === 'unknown' ? 'Selected metadata could not be fully inspected. Cause: unknown.' : 'No supported composition issue was observed. Runtime health: unknown.', '');
+    for (const item of result.explanations.slice(0, markdown ? 50 : 3)) {
+        lines.push(`${markdown ? '## ' : ''}${item.detectedFailure}`, `${item.origin}; evidence: ${item.evidenceLevel}`, '', `Cause: ${item.observableCause}`, '');
+        for (const [index, path] of item.provenancePaths.entries()) {
+            lines.push(`Path ${index + 1}: ${path.packageName === undefined ? '' : `bundle ${path.packageName} → `}${path.source}`, `  ${path.layer === undefined ? 'layer: unknown' : `layer: ${path.layer}`}${path.rowId === undefined ? '' : ` → row: ${path.rowId}`}`);
+            if (path.provenance.length > (markdown ? 0 : 1))
+                lines.push(`  provenance: ${path.provenance.map((step) => `${step.relation}: ${step.source} (${step.basis})`).join(' → ')}`);
+        }
+        const unknown = markdown ? item.unknowns.join(' ') : `runtime not observed / not-run${item.evidenceLevel === 'static' ? '; final composition unknown' : ''}${item.causeStatus === 'unknown' ? '; cause unproven' : ''}.`;
+        lines.push('', `Unknown: ${unknown}`, `Next: ${item.manualRemediation}`, '');
+    }
+    if (!markdown && result.explanations.length > 3)
+        lines.push(`${result.explanations.length - 3} more explanation(s); use --format json or markdown.`, '');
+    if (markdown || result.explanations.length === 0 || result.input.log === 'not-provided')
+        lines.push(result.nextStep);
+    lines.push('Doctor did not modify your profile.', '');
+    return lines.join('\n');
+}

package/dist/reports/markdown.js

@@ -1,3 +1,4 @@
+import { renderFailure } from './failure.js';
 function formatEvidence(item) {
     const subject = item.subject === undefined ? '' : ` — ${item.subject}`;
     const packageLabel = item.packageName === undefined ? '' : ` (${item.packageName}${item.version === undefined ? '' : `@${item.version}`})`;
@@ -9,7 +10,8 @@ function formatDiagnostic(item) {
 }
 export function renderMarkdown(report) {
     const summary = ['error', 'warning', 'info'].map((severity) => `${severity}: ${report.diagnostics.filter((item) => item.severity === severity).length}`).join(', ');
-    const body = report.diagnostics.length === 0 ? 'No diagnostics were produced.' : report.diagnostics.map(formatDiagnostic).join('\n\n');
+    const diagnosticBody = report.diagnostics.length === 0 ? 'No diagnostics were produced.' : report.diagnostics.map(formatDiagnostic).join('\n\n');
+    const body = report.failureExplanation === undefined ? diagnosticBody : `${renderFailure(report.failureExplanation, true)}\n${diagnosticBody}`;
     const coverage = report.metadataCoverage === undefined ? '' : `\nMetadata coverage: ${report.metadataCoverage.mode}; unscanned: ${report.metadataCoverage.unscannedSurfaces.join('; ')}\n`;
     return `# DSH Composition Doctor Report\n\nSchema: ${report.schemaVersion}; evidence schema: ${report.evidenceSchemaVersion}\n\nProfile: \`${report.profileDir}\`\n\nGenerated: ${report.generatedAt}\n\nEvidence mode: ${report.evidenceMode}; runtime observed: ${report.runtimeObserved ? 'yes' : 'no'}\n${coverage}\nSummary: ${summary}\n\n${body}\n`;
 }

package/dist/reports/schema.js

@@ -12,6 +12,73 @@ export const analysisReportJsonSchema = {
         evidenceMode: { enum: ['static', 'composed', 'runtime-observed', 'mixed'] },
         runtimeObserved: { type: 'boolean' },
         unverifiedFindings: { type: 'array', items: { type: 'string' } },
+        failureExplanation: {
+            type: 'object', required: ['schemaVersion', 'outcome', 'profile', 'runtime', 'input', 'explanations', 'unknowns', 'nextStep'],
+            properties: {
+                schemaVersion: { const: 1 }, outcome: { enum: ['explained', 'unknown', 'no-match', 'no-supported-issues'] },
+                profile: { const: '<PROFILE>' }, runtime: { const: 'not-observed' },
+                input: { type: 'object', required: ['log', 'recognizedSignatures', 'truncated'], properties: {
+                        log: { enum: ['not-provided', 'reported-by-log'] }, recognizedSignatures: { type: 'integer', minimum: 0 }, truncated: { type: 'boolean' }
+                    }, additionalProperties: false },
+                explanations: { type: 'array', items: {
+                        type: 'object', required: ['pattern', 'detectedFailure', 'origin', 'causeStatus', 'observableCause', 'provenancePaths', 'evidenceLevel', 'unknowns', 'manualRemediation', 'relatedDiagnostics'],
+                        properties: {
+                            pattern: { enum: ['duplicate-loader-entry', 'bundle-unavailable', 'bundle-patch-unavailable', 'patch-target-missing', 'peer-incompatible', 'config-replacement'] },
+                            detectedFailure: { type: 'string' }, origin: { enum: ['reported-by-log', 'observed-from-composition'] },
+                            matchedEntity: { type: 'object', required: ['kind', 'id'], properties: { kind: { enum: ['row', 'package'] }, id: { type: 'string' } }, additionalProperties: false },
+                            causeStatus: { enum: ['observable-condition', 'unknown'] }, observableCause: { type: 'string' },
+                            provenancePaths: { type: 'array', items: { type: 'object', required: ['source', 'provenance', 'evidence'], properties: {
+                                        source: { type: 'string' }, layer: { type: 'string' }, packageName: { type: 'string' }, rowId: { type: 'string' }, rowKey: { type: 'string' },
+                                        provenance: { type: 'array', items: { type: 'object', required: ['source', 'sourceBasis', 'relation', 'basis'], properties: { source: { type: 'string' }, sourceBasis: { const: 'observed' }, relation: { enum: ['introduced', 'patched-by'] }, basis: { enum: ['observed', 'derived'] } }, additionalProperties: false } },
+                                        evidence: { enum: ['static', 'composed', 'runtime-observed'] }
+                                    }, additionalProperties: false } },
+                            evidenceLevel: { enum: ['static', 'composed', 'runtime-observed', 'unknown'] },
+                            unknowns: { type: 'array', items: { type: 'string' } }, manualRemediation: { type: 'string' },
+                            relatedDiagnostics: { type: 'array', items: { type: 'object' } }
+                        }, additionalProperties: false
+                    } },
+                unknowns: { type: 'array', items: { type: 'string' } }, nextStep: { type: 'string' }
+            }, additionalProperties: false
+        },
+        compositionFacts: {
+            type: 'object',
+            required: ['schemaVersion', 'evidenceMode', 'nodes', 'edges', 'rows', 'unknownSurfaces'],
+            properties: {
+                schemaVersion: { const: 1 },
+                evidenceMode: { enum: ['static', 'composed', 'runtime-observed', 'mixed'] },
+                nodes: { type: 'array', items: {
+                        type: 'object', required: ['id', 'entity', 'label'],
+                        properties: {
+                            id: { type: 'string' }, entity: { enum: ['bundle', 'source', 'layer', 'row', 'diagnostic'] }, label: { type: 'string' },
+                            source: { type: 'string' }, layer: { type: 'string' }, layerOrder: { type: 'number' },
+                            packageName: { type: 'string' }, packageVersion: { type: 'string' },
+                            evidenceMode: { enum: ['static', 'composed', 'runtime-observed'] }, rowKey: { type: 'string' }, diagnosticId: { type: 'string' }
+                        }, additionalProperties: false
+                    } },
+                edges: { type: 'array', items: {
+                        type: 'object', required: ['from', 'to', 'relation', 'basis', 'evidenceMode'],
+                        properties: {
+                            from: { type: 'string' }, to: { type: 'string' },
+                            relation: { enum: ['introduced', 'patched-by', 'source-of', 'contains', 'diagnosed-by', 'package-source'] },
+                            basis: { enum: ['observed', 'derived'] }, evidenceMode: { enum: ['static', 'composed', 'runtime-observed'] }
+                        }, additionalProperties: false
+                    } },
+                rows: { type: 'array', items: {
+                        type: 'object', required: ['entity', 'key', 'source', 'sourceBasis', 'provenance', 'replacement', 'configKeys', 'configKeysBasis', 'evidenceMode', 'relatedDiagnosticIds', 'unknown'],
+                        properties: {
+                            entity: { const: 'row' }, key: { type: 'string' }, id: { type: 'string' }, name: { type: 'string' },
+                            operation: { enum: ['insert', 'update', 'declare'] },
+                            source: { type: 'string' }, sourceBasis: { const: 'observed' }, layer: { type: 'string' }, layerOrder: { type: 'number' },
+                            provenance: { type: 'array', items: { type: 'object', required: ['source', 'sourceBasis', 'relation', 'basis'], properties: { source: { type: 'string' }, sourceBasis: { const: 'observed' }, relation: { enum: ['introduced', 'patched-by'] }, basis: { enum: ['observed', 'derived'] } }, additionalProperties: false } },
+                            replacement: { type: 'object', required: ['state', 'basis'], properties: { state: { enum: ['yes', 'no', 'unknown'] }, basis: { enum: ['observed', 'derived', 'unknown'] } }, additionalProperties: false },
+                            configKeys: { type: 'array', items: { type: 'string' } }, configKeysBasis: { enum: ['observed', 'derived'] }, evidenceMode: { enum: ['static', 'composed', 'runtime-observed'] },
+                            packageName: { type: 'string' }, packageVersion: { type: 'string' }, relatedDiagnosticIds: { type: 'array', items: { type: 'string' } },
+                            removedConfigKeys: { type: 'array', items: { type: 'string' } }, unknown: { type: 'array', items: { type: 'string' } }
+                        }, additionalProperties: false
+                    } },
+                unknownSurfaces: { type: 'array', items: { type: 'string' } }
+            }, additionalProperties: false
+        },
         diagnostics: {
             type: 'array',
             items: {

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "dsh-composition-doctor",
-  "version": "0.2.2",
+  "version": "0.4.0",
   "private": false,
-  "description": "Read-only DSH and Cordis composition diagnostics, snapshots, diffs, and isolated preflight.",
+  "description": "Explain DSH plugin failures through observable composition paths. Read-only, offline by default, with snapshots and upgrade preflight.",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -60,6 +60,8 @@
     "test": "pnpm build && vitest run",
     "typecheck": "tsc --noEmit",
     "build": "tsc && node scripts/build-client.mjs",
-    "dsh-doctor": "node dist/cli/main.js"
+    "dsh-doctor": "node dist/cli/main.js",
+    "smoke:pack": "node scripts/pack-smoke.mjs",
+    "demo:failure": "node scripts/failure-demo.mjs"
   }
 }