dsh-composition-doctor 0.3.0 → 0.4.0

package/dist/client/report-view.js

@@ -107,6 +107,44 @@ function renderConflictGraph(document, graph) {
     section.append(list);
     return section;
 }
+export function createFailureExplanation(document, report) {
+    const section = document.createElement('section');
+    section.dataset.failureExplanation = 'true';
+    const heading = document.createElement('h3');
+    heading.textContent = 'Failure Explanation';
+    section.append(heading);
+    const result = report.failureExplanation;
+    if (result === undefined) {
+        const message = document.createElement('p');
+        message.textContent = 'No failure explanation in this report. Run dsh-doctor diagnose --profile <dir> --report-dir <doctor-reports> to create one.';
+        section.append(message);
+        return section;
+    }
+    const status = document.createElement('p');
+    status.textContent = `Outcome: ${result.outcome}; runtime: ${result.runtime}. Log signatures are reported claims, not composition evidence.`;
+    section.append(status);
+    for (const explanation of result.explanations) {
+        const details = document.createElement('details');
+        const summary = document.createElement('summary');
+        summary.textContent = `${explanation.detectedFailure} (${explanation.origin}; ${explanation.evidenceLevel})`;
+        const cause = document.createElement('p');
+        cause.textContent = explanation.observableCause;
+        const paths = document.createElement('pre');
+        paths.textContent = explanation.provenancePaths.map((path) => `${path.packageName ?? 'profile'} → ${path.source} → ${path.layer ?? 'unknown layer'} → ${path.rowId ?? 'unknown row'}\n${path.provenance.map((step) => `${step.relation}: ${step.source} (${step.basis})`).join(' → ')}`).join('\n\n');
+        const unknown = document.createElement('p');
+        unknown.textContent = `Unknown: ${explanation.unknowns.join(' ')}`;
+        const diagnostics = document.createElement('p');
+        diagnostics.textContent = `Related diagnostics: ${explanation.relatedDiagnostics.map((item) => item.id).join(', ') || 'none observed'}`;
+        const remediation = document.createElement('p');
+        remediation.textContent = `Manual next step: ${explanation.manualRemediation}`;
+        details.append(summary, cause, paths, diagnostics, unknown, remediation);
+        section.append(details);
+    }
+    const next = document.createElement('p');
+    next.textContent = `${result.nextStep} Doctor did not modify your profile.`;
+    section.append(next);
+    return section;
+}
 export function createCompositionExplorer(document, report) {
     const section = document.createElement('section');
     section.setAttribute('aria-labelledby', 'dsh-composition-doctor-explorer');
@@ -166,6 +204,10 @@ export function createCompositionExplorer(document, report) {
                 }
             });
             select.dataset.compositionNode = node.id;
+            if (report.failureExplanation?.explanations.some((item) => item.provenancePaths.some((path) => path.rowKey === node.rowKey && node.rowKey !== undefined || path.packageName === node.packageName && node.packageName !== undefined))) {
+                select.dataset.failureRelated = 'true';
+                select.textContent = `${node.entity}: ${node.label} [failure evidence]`;
+            }
             item.append(select);
             const outgoing = graph.edges.filter((edge) => edge.from === node.id);
             if (outgoing.length > 0) {
@@ -286,6 +328,7 @@ export function createReportView(document = globalThis.document, translate = (ke
         status.textContent = `Generated: ${report.generatedAt}. Profile: ${report.profileDir}. Diagnostics: ${model.counts.error} error, ${model.counts.warning} warning, ${model.counts.info} info.`;
         status.append(document.createTextNode(' '), badge);
         root.append(renderConflictGraph(document, model.graph));
+        root.append(createFailureExplanation(document, report));
         root.append(createCompositionExplorer(document, report));
         const list = document.createElement('ul');
         for (const diagnostic of report.diagnostics) {

package/dist/client.js

@@ -37,6 +37,39 @@ window.__ModuleLoader__.load({
 		// src/client/report-view.ts
 		var import_react = require("react");
 		
+		// src/reports/failure.ts
+		function renderFailure(result, markdown = false) {
+		  const lines = [
+		    markdown ? "# DSH Composition Doctor \u2014 Failure Explanation" : "DSH Composition Doctor \u2014 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 === void 0 ? "" : `bundle ${path.packageName} \u2192 `}${path.source}`,
+		        `  ${path.layer === void 0 ? "layer: unknown" : `layer: ${path.layer}`}${path.rowId === void 0 ? "" : ` \u2192 row: ${path.rowId}`}`
+		      );
+		      if (path.provenance.length > (markdown ? 0 : 1)) lines.push(`  provenance: ${path.provenance.map((step) => `${step.relation}: ${step.source} (${step.basis})`).join(" \u2192 ")}`);
+		    }
+		    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");
+		}
+		
 		// src/reports/markdown.ts
 		function formatEvidence(item) {
 		  const subject = item.subject === void 0 ? "" : ` \u2014 ${item.subject}`;
@@ -56,7 +89,9 @@ window.__ModuleLoader__.load({
 		}
 		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 === void 0 ? diagnosticBody : `${renderFailure(report.failureExplanation, true)}
+		${diagnosticBody}`;
 		  const coverage = report.metadataCoverage === void 0 ? "" : `
 		Metadata coverage: ${report.metadataCoverage.mode}; unscanned: ${report.metadataCoverage.unscannedSurfaces.join("; ")}
 		`;
@@ -171,6 +206,45 @@ window.__ModuleLoader__.load({
 		  section.append(list);
 		  return section;
 		}
+		function createFailureExplanation(document, report) {
+		  const section = document.createElement("section");
+		  section.dataset.failureExplanation = "true";
+		  const heading = document.createElement("h3");
+		  heading.textContent = "Failure Explanation";
+		  section.append(heading);
+		  const result = report.failureExplanation;
+		  if (result === void 0) {
+		    const message = document.createElement("p");
+		    message.textContent = "No failure explanation in this report. Run dsh-doctor diagnose --profile <dir> --report-dir <doctor-reports> to create one.";
+		    section.append(message);
+		    return section;
+		  }
+		  const status = document.createElement("p");
+		  status.textContent = `Outcome: ${result.outcome}; runtime: ${result.runtime}. Log signatures are reported claims, not composition evidence.`;
+		  section.append(status);
+		  for (const explanation of result.explanations) {
+		    const details = document.createElement("details");
+		    const summary = document.createElement("summary");
+		    summary.textContent = `${explanation.detectedFailure} (${explanation.origin}; ${explanation.evidenceLevel})`;
+		    const cause = document.createElement("p");
+		    cause.textContent = explanation.observableCause;
+		    const paths = document.createElement("pre");
+		    paths.textContent = explanation.provenancePaths.map((path) => `${path.packageName ?? "profile"} \u2192 ${path.source} \u2192 ${path.layer ?? "unknown layer"} \u2192 ${path.rowId ?? "unknown row"}
+		${path.provenance.map((step) => `${step.relation}: ${step.source} (${step.basis})`).join(" \u2192 ")}`).join("\n\n");
+		    const unknown = document.createElement("p");
+		    unknown.textContent = `Unknown: ${explanation.unknowns.join(" ")}`;
+		    const diagnostics = document.createElement("p");
+		    diagnostics.textContent = `Related diagnostics: ${explanation.relatedDiagnostics.map((item) => item.id).join(", ") || "none observed"}`;
+		    const remediation = document.createElement("p");
+		    remediation.textContent = `Manual next step: ${explanation.manualRemediation}`;
+		    details.append(summary, cause, paths, diagnostics, unknown, remediation);
+		    section.append(details);
+		  }
+		  const next = document.createElement("p");
+		  next.textContent = `${result.nextStep} Doctor did not modify your profile.`;
+		  section.append(next);
+		  return section;
+		}
 		function createCompositionExplorer(document, report) {
 		  const section = document.createElement("section");
 		  section.setAttribute("aria-labelledby", "dsh-composition-doctor-explorer");
@@ -226,6 +300,10 @@ window.__ModuleLoader__.load({
 		        }
 		      });
 		      select.dataset.compositionNode = node.id;
+		      if (report.failureExplanation?.explanations.some((item2) => item2.provenancePaths.some((path) => path.rowKey === node.rowKey && node.rowKey !== void 0 || path.packageName === node.packageName && node.packageName !== void 0))) {
+		        select.dataset.failureRelated = "true";
+		        select.textContent = `${node.entity}: ${node.label} [failure evidence]`;
+		      }
 		      item.append(select);
 		      const outgoing = graph.edges.filter((edge) => edge.from === node.id);
 		      if (outgoing.length > 0) {
@@ -349,6 +427,7 @@ window.__ModuleLoader__.load({
 		    status.textContent = `Generated: ${report.generatedAt}. Profile: ${report.profileDir}. Diagnostics: ${model.counts.error} error, ${model.counts.warning} warning, ${model.counts.info} info.`;
 		    status.append(document.createTextNode(" "), badge);
 		    root.append(renderConflictGraph(document, model.graph));
+		    root.append(createFailureExplanation(document, report));
 		    root.append(createCompositionExplorer(document, report));
 		    const list = document.createElement("ul");
 		    for (const diagnostic of report.diagnostics) {

package/dist/core/bundle-inventory.js

@@ -3,12 +3,12 @@ import { inspectInstalledPackage } from './package-provenance.js';
 function record(value) {
     return value !== null && typeof value === 'object' && !Array.isArray(value) ? value : undefined;
 }
-function diagnostic(id, title, source, detail) {
+function diagnostic(id, title, source, detail, packageName) {
     return {
         id,
         severity: 'warning',
         title,
-        evidence: [{ source, detail, evidenceKind: 'static' }],
+        evidence: [{ source, detail, evidenceKind: 'static', ...(packageName === undefined ? {} : { packageName, subject: packageName }) }],
         explanation: detail,
         remediation: 'Install the declared bundle in the selected profile or provide the missing public manifest/patch metadata.'
     };
@@ -32,7 +32,10 @@ function bundleNames(manifest) {
 export async function inspectBundleInventory(profileDir, packageJsonText) {
     let manifest;
     try {
-        manifest = JSON.parse(packageJsonText);
+        const parsed = record(JSON.parse(packageJsonText));
+        if (parsed === undefined)
+            throw new Error('Manifest must be an object');
+        manifest = parsed;
     }
     catch {
         return { packages: [], diagnostics: [diagnostic('bundle-inventory-manifest-invalid', 'Profile package manifest is invalid', 'package.json', 'The profile package.json could not be parsed, so dsh.profile.bundles cannot be inspected.')] };
@@ -48,18 +51,18 @@ export async function inspectBundleInventory(profileDir, packageJsonText) {
                     await access(fact.bundlePatch);
                 }
                 catch {
-                    diagnostics.push(diagnostic('bundle-patch-missing', 'Bundle patch metadata is missing', fact.packageJsonSource, `${declared.name} declares dsh.bundle.patch at ${fact.bundlePatch}, but that file is not readable.`));
+                    diagnostics.push(diagnostic('bundle-patch-missing', 'Bundle patch metadata is missing', fact.packageJsonSource, 'The declared dsh.bundle.patch file is not readable.', declared.name));
                 }
             }
             else {
-                diagnostics.push(diagnostic('bundle-patch-unavailable', 'Bundle patch metadata is unavailable', fact.packageJsonSource, `${declared.name} has no readable dsh.bundle.patch declaration.`));
+                diagnostics.push(diagnostic('bundle-patch-unavailable', 'Bundle patch metadata is unavailable', fact.packageJsonSource, 'The bundle has no readable dsh.bundle.patch declaration.', declared.name));
             }
             if (fact.integrity === undefined && fact.gitRef === undefined) {
                 diagnostics.push(diagnostic('bundle-provenance-unavailable', 'Bundle immutable provenance is unavailable', fact.packageJsonSource, `${declared.name} has neither registry integrity nor a fixed Git reference in its readable manifest.`));
             }
         }
         catch (error) {
-            diagnostics.push(diagnostic('bundle-not-installed', 'Declared bundle is not installed or readable', 'package.json', `${declared.name}${declared.requestedSpec === undefined ? '' : `@${declared.requestedSpec}`} could not be resolved from the selected profile: ${error instanceof Error ? error.message : String(error)}`));
+            diagnostics.push(diagnostic('bundle-not-installed', 'Declared bundle is not installed or readable', 'package.json', 'The declared bundle could not be resolved inside the selected profile.', /^(?:@[a-z0-9_.-]+\/)?[a-z0-9_.-]+$/i.test(declared.name) ? declared.name : undefined));
         }
     }
     return { packages, diagnostics };

package/dist/core/composition-provenance.js

@@ -58,6 +58,7 @@ export function buildCompositionFacts(model, diagnostics) {
     const nodes = new Map();
     const edgeMap = new Map();
     const rows = [];
+    const keyOccurrences = new Map();
     const packages = model.installedPackages ?? [];
     const reportMode = model.evidenceMode ?? 'static';
     const addNode = (node) => nodes.set(node.id, node);
@@ -68,7 +69,10 @@ export function buildCompositionFacts(model, diagnostics) {
     }
     for (const [index, row] of model.rows.entries()) {
         const rowIdentity = row.id ?? row.name ?? `${normalizeCompositionSource(row.source, model.profileDir)}:${index}`;
-        const rowKey = `row:${stableKey(`${rowIdentity}|${normalizeCompositionSource(row.source, model.profileDir)}|${row.layer ?? ''}|${row.layerOrder ?? index}`)}`;
+        const keyBase = `row:${stableKey(`${rowIdentity}|${normalizeCompositionSource(row.source, model.profileDir)}|${row.layer ?? ''}|${row.layerOrder ?? index}`)}`;
+        const occurrence = keyOccurrences.get(keyBase) ?? 0;
+        keyOccurrences.set(keyBase, occurrence + 1);
+        const rowKey = occurrence === 0 ? keyBase : `${keyBase}:${occurrence}`;
         const chain = row.provenance === undefined ? [] : [...row.provenance];
         const chainSources = chain.map((source) => normalizeCompositionSource(source, model.profileDir));
         const source = normalizeCompositionSource(row.source, model.profileDir);
@@ -104,6 +108,7 @@ export function buildCompositionFacts(model, diagnostics) {
             }));
         const fact = {
             entity: 'row', key: rowKey,
+            ...(row.operation === undefined ? {} : { operation: row.operation }),
             ...(row.id === undefined ? {} : { id: row.id }),
             ...(row.name === undefined ? {} : { name: row.name }),
             source,

package/dist/core/dsh-dump-parser.js

@@ -106,7 +106,7 @@ export function parseDshDump(stdout, stderr = '') {
     for (const detail of unmatched)
         diagnostics.push({
             id: 'unmatched-patch-target', severity: 'warning', title: 'Resolved patch target did not match a row',
-            evidence: [{ source: '<DSH stderr>', detail, evidenceKind: 'composed' }],
+            evidence: [{ source: '<DSH stderr>', detail, evidenceKind: 'composed', ...(detail.match(/entry ["']([a-z0-9_.:-]+)["'] not found/i)?.[1] === undefined ? {} : { subject: detail.match(/entry ["']([a-z0-9_.:-]+)["'] not found/i)[1] }) }],
             explanation: 'The public DSH dump reported a patch target that did not match a resolved row.',
             remediation: 'Verify the patch row id against the selected bundle/profile composition.'
         });

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') })