dsh-composition-doctor 0.1.2 → 0.2.0

package/dist/core/preflight.js

@@ -2,17 +2,20 @@ import { createHash } from 'node:crypto';
 import { mkdtemp, rm, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join, resolve } from 'node:path';
-import { parse, stringify } from 'yaml';
 import { resolveComposition } from './composition-adapter.js';
+import { tryDshDump } from './dsh-dump-provider.js';
 import { readProfile } from './profile-reader.js';
-import { redact } from './redaction.js';
+import { redact, redactYamlPreservingTags } from './redaction.js';
 import { analyseComposition } from './rules.js';
+import { resolveDshArtifact } from './preflight/artifact-resolver.js';
+import { resolveCandidateArtifact } from './preflight/candidate-artifact-resolver.js';
+import { evaluatePackageResolution } from './preflight/package-resolution.js';
 const yamlFiles = new Set(['cordis.yml', 'cordis.patch.yml']);
 const lockFiles = new Set(['pnpm-lock.yaml', 'package-lock.json', 'yarn.lock']);
 const packageNamePattern = /^(?:@[a-z0-9_.-]+\/)?[a-z0-9_.-]+$/i;
 const versionPattern = /^[0-9]+\.[0-9]+\.[0-9]+(?:-[0-9a-z.-]+)?(?:\+[0-9a-z.-]+)?$/i;
 function evidence(source, subject, detail, severity) {
-    return { source, subject, detail, ...(severity === undefined ? {} : { severity }) };
+    return { source, subject, detail, evidenceKind: 'static', ...(severity === undefined ? {} : { severity }) };
 }
 /** A digest of the allow-listed metadata surface; file contents are never returned. */
 export function profileFingerprint(input) {
@@ -30,13 +33,17 @@ function safeCandidate(value) {
     const version = value.slice(at + 1);
     return packageNamePattern.test(name) && versionPattern.test(version);
 }
+function candidateParts(value) {
+    const at = value.lastIndexOf('@');
+    return { name: value.slice(0, at), version: value.slice(at + 1) };
+}
 function safeMetadataText(relativePath, text) {
     try {
         if (relativePath === 'package.json') {
             return `${JSON.stringify(redact(JSON.parse(text)), null, 2)}\n`;
         }
         if (yamlFiles.has(relativePath)) {
-            return stringify(redact(parse(text)));
+            return redactYamlPreservingTags(text);
         }
     }
     catch {
@@ -45,7 +52,8 @@ function safeMetadataText(relativePath, text) {
     }
     return undefined;
 }
-async function prepareIsolatedProfile(input, directory, evidenceItems) {
+async function prepareIsolatedProfile(input, directory, candidates, evidenceItems) {
+    let wroteManifest = false;
     for (const file of input.files) {
         if (lockFiles.has(file.relativePath)) {
             evidenceItems.push(evidence(file.relativePath, 'lockfile-not-copied', 'Lockfile content is excluded from the rehearsal directory; its source hash remains available in snapshots.'));
@@ -56,7 +64,28 @@ async function prepareIsolatedProfile(input, directory, evidenceItems) {
             evidenceItems.push(evidence(file.relativePath, 'metadata-not-copied', 'Metadata was not copied because it could not be safely parsed.'));
             continue;
         }
+        if (file.relativePath === 'package.json' && candidates.length > 0) {
+            const manifest = JSON.parse(safeText);
+            const dependencies = manifest.dependencies !== null && typeof manifest.dependencies === 'object' ? manifest.dependencies : {};
+            for (const candidate of candidates) {
+                const { name, version } = candidateParts(candidate);
+                dependencies[name] = version;
+            }
+            manifest.dependencies = dependencies;
+            await writeFile(join(directory, file.relativePath), `${JSON.stringify(manifest, null, 2)}\n`, { encoding: 'utf8', flag: 'wx' });
+            wroteManifest = true;
+            continue;
+        }
         await writeFile(join(directory, file.relativePath), safeText, { encoding: 'utf8', flag: 'wx' });
+        if (file.relativePath === 'package.json')
+            wroteManifest = true;
+    }
+    if (!wroteManifest && candidates.length > 0) {
+        const dependencies = Object.fromEntries(candidates.map((candidate) => {
+            const { name, version } = candidateParts(candidate);
+            return [name, version];
+        }));
+        await writeFile(join(directory, 'package.json'), `${JSON.stringify({ name: 'dsh-doctor-isolated-profile', private: true, dependencies }, null, 2)}\n`, { encoding: 'utf8', flag: 'wx' });
     }
 }
 function runtimeForTarget(model, targetDsh) {
@@ -88,6 +117,9 @@ export async function runPreflight(options) {
     let tempDirectory;
     let smokeOutcome = 'pass';
     let smokeDetail = 'No isolated smoke test was run.';
+    let packageResolutionOutcome = 'not-run';
+    let packageResolutionDetail = 'No candidate package was supplied.';
+    const packageResolutions = [];
     let diagnostics = [];
     let profileDir = requestedProfile;
     let extraWarning = false;
@@ -96,7 +128,11 @@ export async function runPreflight(options) {
             evidenceItems.push(evidence(requestedProfile, 'target-dsh-invalid', 'Target DSH version must be an explicit semantic version.', 'error'));
             return {
                 schemaVersion: 1, outcome: 'fail', profileDir: requestedProfile, targetDsh: options.targetDsh,
-                candidates: [], evidence: evidenceItems, diagnostics, smokeTest: { outcome: 'fail', detail: 'The target DSH version was rejected before rehearsal.' }
+                candidates: [], evidence: evidenceItems, diagnostics, smokeTest: { outcome: 'fail', detail: 'The target DSH version was rejected before rehearsal.' },
+                compositionSmoke: { outcome: 'fail', detail: 'The target DSH version was rejected before rehearsal.' },
+                packageResolutionSmoke: { outcome: 'not-run', detail: 'Target version validation failed before package resolution.' },
+                packageResolutions: [],
+                runtimeSmoke: { outcome: 'not-run', detail: 'Runtime execution was not attempted.' }
             };
         }
         const input = await readProfile({ profileDir: requestedProfile });
@@ -109,19 +145,66 @@ export async function runPreflight(options) {
             evidenceItems.push(evidence(profileDir, 'candidate-validation', `${invalidCandidates.length} candidate value(s) were omitted because they are not a simple package@version reference.`, 'warning'));
         }
         const candidates = options.candidates.filter(safeCandidate);
+        const artifact = await resolveDshArtifact({ targetDsh: options.targetDsh, dshBin: options.dshBin, dshPackage: options.dshPackage, online: options.online, cacheDir: options.artifactCacheDir, packageManagerCacheDirs: options.packageManagerCacheDirs });
+        const artifactProvenance = [artifact.detail, `source=${artifact.source}`, `requested=${artifact.requestedVersion}`, ...(artifact.resolvedVersion === undefined ? [] : [`resolved=${artifact.resolvedVersion}`]), ...(artifact.integrity === undefined ? [] : [`integrity=${artifact.integrity}`]), ...(artifact.sha512 === undefined ? [] : [`sha512=${artifact.sha512}`])].join(' ');
+        evidenceItems.push(evidence(profileDir, 'target-artifact', artifactProvenance, artifact.kind === 'unavailable' || !artifact.targetVersionVerified ? 'warning' : undefined));
+        packageResolutions.push(evaluatePackageResolution({ packageName: '@deepseek-ai/dsh', requestedVersion: options.targetDsh, resolvedVersion: artifact.resolvedVersion, manifest: artifact.manifest, source: artifact.source, integrity: artifact.integrity, sha512: artifact.sha512, runtime: { dsh: options.targetDsh, node: process.versions.node, platform: process.platform } }));
+        const artifactDiagnostics = artifact.kind === 'unavailable'
+            ? [{ id: 'artifact-unavailable', severity: 'warning', title: 'Target DSH artifact unavailable', evidence: [{ source: profileDir, subject: 'target-artifact', detail: artifact.detail, evidenceKind: 'static' }], explanation: 'The requested target DSH release was not available from the permitted offline artifact sources.', remediation: 'Provide --dsh-bin, --dsh-package, a local tarball, or an installed target artifact; use --online only when network resolution is explicitly intended.' }]
+            : !artifact.targetVersionVerified
+                ? [{ id: 'artifact-version-unverified', severity: 'warning', title: 'Target DSH release is unverified', evidence: [{ source: artifact.path ?? profileDir, subject: 'target-artifact', detail: artifact.detail, evidenceKind: 'static' }], explanation: 'A local artifact candidate was found, but its version was not verified as the requested release.', remediation: 'Run the harness with a locally available exact release and verify its public --version output.' }]
+                : [];
+        if (artifactDiagnostics.length > 0 || artifact.kind === 'unavailable')
+            extraWarning = true;
         evidenceItems.push(evidence(profileDir, 'target-dsh', `Rehearsal target is DSH ${options.targetDsh}.`));
         evidenceItems.push(evidence(profileDir, 'candidate-plugins', `${candidates.length} validated candidate plugin reference(s) supplied; values are not copied into the real profile.`));
-        evidenceItems.push(evidence(profileDir, 'network-policy', options.online ? 'Online mode was requested, but this adapter performs no network operation.' : 'Offline mode enforced; no network operation was attempted.'));
-        if (options.online)
+        const candidateResolutions = [];
+        for (const candidate of candidates) {
+            evidenceItems.push(evidence(profileDir, 'candidate-accepted', `${candidate} was accepted as an exact package@version reference.`));
+            const resolution = await resolveCandidateArtifact(requestedProfile, candidate, options.online, options.artifactCacheDir, options.packageManagerCacheDirs);
+            candidateResolutions.push(resolution);
+            evidenceItems.push(evidence(profileDir, resolution.status === 'resolved' ? 'candidate-artifact-resolved' : 'candidate-declaration-recorded', resolution.detail, resolution.status === 'resolved' ? undefined : 'warning'));
+            packageResolutions.push(resolution.status === 'resolved' && resolution.artifact !== undefined
+                ? evaluatePackageResolution({ packageName: resolution.artifact.name, requestedVersion: resolution.artifact.requestedVersion, resolvedVersion: resolution.artifact.installedVersion, manifest: resolution.artifact.manifest, source: resolution.artifact.source, integrity: resolution.artifact.integrity, sha512: resolution.artifact.sha512, runtime: { dsh: options.targetDsh, node: process.versions.node, platform: process.platform } })
+                : { packageName: candidateParts(candidate).name, requestedVersion: candidateParts(candidate).version, status: 'unavailable', source: 'unavailable', checks: { artifact: 'unknown' }, evidence: [{ source: profileDir, subject: candidate, detail: resolution.detail, evidenceKind: 'static', severity: 'warning' }] });
+            evidenceItems.push(evidence(profileDir, 'candidate-package-not-installed', `${candidate} was not downloaded or installed.`));
+            evidenceItems.push(evidence(profileDir, 'candidate-runtime-unverified', `${candidate} was not loaded, so runtime compatibility is unverified.`, 'warning'));
+        }
+        const nonCompatible = packageResolutions.filter((resolution) => resolution.status !== 'compatible');
+        packageResolutionOutcome = nonCompatible.some((resolution) => resolution.status === 'incompatible') ? 'fail' : nonCompatible.length > 0 ? 'warning' : 'pass';
+        packageResolutionDetail = packageResolutions.length === 0
+            ? 'No target or candidate package artifact was available for package-resolution checks.'
+            : `${nonCompatible.length} of ${packageResolutions.length} package artifact resolution(s) are not proven compatible; no package-manager install or lifecycle was executed.`;
+        if (candidates.length > 0)
             extraWarning = true;
+        evidenceItems.push(evidence(profileDir, 'network-policy', options.online ? 'Online mode was explicitly requested; exact registry artifacts may be downloaded into Doctor-owned cache only.' : 'Offline mode enforced; no network operation was attempted.'));
         tempDirectory = await mkdtemp(join(tmpdir(), 'dsh-doctor-'));
-        await prepareIsolatedProfile(input, tempDirectory, evidenceItems);
+        await prepareIsolatedProfile(input, tempDirectory, candidates, evidenceItems);
         evidenceItems.push(evidence(tempDirectory, 'isolated-profile', 'Only redacted, allow-listed composition metadata was copied into the temporary profile.'));
         try {
             const isolatedInput = await readProfile({ profileDir: tempDirectory });
-            const isolatedModel = runtimeForTarget(await resolveComposition(isolatedInput), options.targetDsh);
+            const staticModel = runtimeForTarget(await resolveComposition(isolatedInput), options.targetDsh);
+            const dumped = artifact.kind === 'dsh-bin' && artifact.path !== undefined ? await tryDshDump(isolatedInput, { dshBin: artifact.path }) : undefined;
+            const isolatedModel = dumped === undefined ? staticModel : { ...staticModel, rows: dumped.rows, adapterDiagnostics: [...staticModel.adapterDiagnostics.filter((item) => item.id !== 'runtime-composition-unavailable'), ...dumped.diagnostics], evidenceMode: 'composed' };
             const report = analyseComposition(isolatedModel);
-            diagnostics = report.diagnostics;
+            const candidateDiagnostics = candidateResolutions.filter((resolution) => resolution.status === 'unavailable').map((resolution) => {
+                const candidate = resolution.candidate;
+                const { name, version } = candidateParts(candidate);
+                return {
+                    id: 'candidate-artifact-unavailable', severity: 'warning', title: 'Candidate artifact was not resolved',
+                    evidence: [{ source: tempDirectory ?? profileDir, subject: candidate, packageName: name, version, detail: resolution.detail, evidenceKind: 'static' }],
+                    explanation: 'A package declaration is not evidence that the candidate package manifest or runtime can be loaded.',
+                    remediation: 'Provide a local exact artifact or use an explicit supported online resolver, then re-run the isolated rehearsal.'
+                };
+            });
+            const packageDiagnostics = packageResolutions.filter((resolution) => resolution.status !== 'compatible').map((resolution) => ({
+                id: `package-resolution-${resolution.status}`, severity: resolution.status === 'incompatible' ? 'error' : 'warning',
+                title: `Package resolution is ${resolution.status}`,
+                evidence: [...resolution.evidence],
+                explanation: `Package metadata resolution for ${resolution.packageName}@${resolution.requestedVersion} is ${resolution.status}.`,
+                remediation: resolution.status === 'unavailable' ? 'Provide an exact local artifact or use explicit --online registry resolution.' : 'Supply the missing runtime facts or use a compatible package version.'
+            }));
+            diagnostics = [...artifactDiagnostics, ...report.diagnostics, ...candidateDiagnostics, ...packageDiagnostics];
             const errors = diagnostics.filter((item) => item.severity === 'error').length;
             const warnings = diagnostics.filter((item) => item.severity === 'warning').length;
             smokeOutcome = errors > 0 ? 'fail' : warnings > 0 ? 'warning' : 'pass';
@@ -172,6 +255,10 @@ export async function runPreflight(options) {
         evidence: evidenceItems,
         diagnostics,
         smokeTest: { outcome: smokeOutcome, detail: smokeDetail },
+        compositionSmoke: { outcome: smokeOutcome, detail: smokeDetail },
+        packageResolutionSmoke: { outcome: packageResolutionOutcome, detail: packageResolutionDetail },
+        packageResolutions,
+        runtimeSmoke: { outcome: 'not-run', detail: 'Third-party runtime execution requires an explicit supported isolation backend; the temporary directory is not a security sandbox.' },
         ...(before === undefined ? {} : { realProfileFingerprintBefore: before }),
         ...(after === undefined ? {} : { realProfileFingerprintAfter: after }),
         ...(tempDirectory === undefined ? {} : { tempDirectory })

package/dist/core/profile-reader.js

@@ -1,6 +1,7 @@
 import { createHash } from 'node:crypto';
 import { lstat, readFile, realpath, stat } from 'node:fs/promises';
 import { resolve } from 'node:path';
+import { inspectBundleInventory } from './bundle-inventory.js';
 const allowedFiles = [
     'cordis.yml',
     'cordis.patch.yml',
@@ -52,5 +53,19 @@ export async function readProfile({ profileDir }) {
             throw error;
         }
     }
-    return { profileDir: resolvedRoot, files };
+    const packageFile = files.find((file) => file.relativePath === 'package.json');
+    const inventory = packageFile === undefined
+        ? { packages: [], diagnostics: [] }
+        : await inspectBundleInventory(resolvedRoot, packageFile.text);
+    return {
+        profileDir: resolvedRoot,
+        files,
+        installedPackages: inventory.packages,
+        inventoryDiagnostics: inventory.diagnostics,
+        metadataCoverage: {
+            mode: 'allow-listed-root-metadata',
+            scannedFiles: files.map((file) => file.relativePath).sort(),
+            unscannedSurfaces: ['non-declared nested plugin manifests and non-selected package metadata', 'environment files and values', 'private keys, tokens, sessions, and workspace source files']
+        }
+    };
 }

package/dist/core/redaction.js

@@ -1,4 +1,5 @@
-const secretProperty = /key|token|secret|password|credential|authorization/i;
+import { visit, parseDocument, Scalar } from 'yaml';
+const secretProperty = /key|token|secret|password|credential|authorization|cookie|private|passphrase|session|env/i;
 export function redact(value) {
     const seen = new WeakMap();
     const visit = (current) => {
@@ -23,3 +24,29 @@ export function redact(value) {
     };
     return visit(value);
 }
+/**
+ * Redact YAML through its AST.  In particular, this preserves custom tags
+ * such as !!js instead of round-tripping through a plain JavaScript value.
+ * Tagged values are never executed.
+ */
+export function redactYamlPreservingTags(text) {
+    const document = parseDocument(text, { keepSourceTokens: true });
+    visit(document, {
+        Pair: (_key, pair) => {
+            const key = pair.key instanceof Scalar ? String(pair.key.value) : String(pair.key ?? '');
+            if (!secretProperty.test(key))
+                return;
+            if (pair.value instanceof Scalar) {
+                pair.value.value = '[REDACTED]';
+            }
+            else {
+                // A secret collection is replaced as a scalar; no value is evaluated,
+                // and an unsupported collection shape is not silently copied.
+                pair.value = document.createNode('[REDACTED]');
+            }
+        }
+    });
+    if (document.errors.length > 0)
+        throw document.errors[0];
+    return String(document);
+}

package/dist/core/rules.js

@@ -64,9 +64,9 @@ function peerDiagnostics(model) {
 function bundleDiagnostics(bundles) {
     const diagnostics = [];
     for (const bundle of bundles) {
-        if (bundle.gitRef !== undefined && bundle.gitRef.length > 0)
+        if ((bundle.gitRef !== undefined && bundle.gitRef.length > 0) || (bundle.integrity !== undefined && bundle.integrity.length > 0))
             continue;
-        diagnostics.push(diagnostic('missing-provenance', 'warning', 'Bundle provenance is unavailable', [evidence(bundle.source, bundle.name, 'No Git ref or immutable provenance was declared.', bundle.evidenceKind, bundle.name, bundle.version)], `The origin of ${bundle.name} cannot be verified from the selected metadata.`, 'Record an immutable Git ref, registry integrity hash, or other package provenance in the selected profile metadata.'));
+        diagnostics.push(diagnostic('missing-provenance', 'warning', 'Bundle provenance is unavailable', [evidence(bundle.source, bundle.name, 'No Git ref or registry integrity was observed.', bundle.evidenceKind, bundle.name, bundle.version)], `The origin of ${bundle.name} cannot be verified from the selected metadata.`, 'Record an immutable Git ref or registry integrity hash in the selected package metadata.'));
     }
     for (const [name, group] of groups(bundles.filter((bundle) => bundle.profile !== undefined), (bundle) => bundle.name)) {
         if (new Set(group.map((bundle) => bundle.version ?? 'unknown')).size < 2)
@@ -75,22 +75,69 @@ function bundleDiagnostics(bundles) {
     }
     return diagnostics;
 }
-export function analyseComposition(model) {
-    const diagnostics = [...model.adapterDiagnostics];
-    for (const [id, rows] of groups(model.rows.filter((row) => row.id !== undefined), (row) => row.id)) {
-        if (rows.length < 2)
+function rowKeys(row) {
+    if (row.configKeys !== undefined)
+        return new Set(row.configKeys);
+    if (row.config !== null && typeof row.config === 'object' && !Array.isArray(row.config))
+        return new Set(Object.keys(row.config));
+    return new Set();
+}
+function rowDiagnostics(rows) {
+    const diagnostics = [];
+    for (const [id, group] of groups(rows.filter((row) => row.id !== undefined), (row) => row.id)) {
+        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;
-        diagnostics.push(diagnostic('duplicate-row-id', 'error', 'Duplicate composition row id', rows.map((row) => evidence(row.source, id, `row id ${id}`, row.evidenceKind, row.name)), `Multiple concrete composition rows claim the id ${id}.`, 'Give one row a unique id or remove the duplicate declaration.'));
+        }
+        if (layers.size < 2)
+            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];
+        const current = ordered[ordered.length - 1];
+        diagnostics.push(diagnostic('intentional-row-override', 'info', 'Later composition layer overrides a row', [evidence(previous.source, id, `row id ${id} is overridden by a later layer`, previous.evidenceKind, previous.name), evidence(current.source, id, `row id ${id} replaces the earlier row`, current.evidenceKind, current.name)], `The same row id occurs across layers, which is compatible with DSH patch precedence when the later layer intentionally owns the row.`, 'Confirm the resolved provenance and keep the override documented.'));
+        const missing = [...rowKeys(previous)].filter((key) => !rowKeys(current).has(key)).sort();
+        if (missing.length > 0 && (current.replacement === true || current.configKeys !== undefined)) {
+            diagnostics.push(diagnostic('row-config-replacement-risk', 'warning', 'Row replacement drops earlier config keys', [evidence(current.source, id, `replacement omits keys: ${missing.join(', ')}`, current.evidenceKind, current.name)], `The later row replacement for ${id} does not contain all keys observed in the earlier config. Secret values are not included.`, 'Copy the required non-secret config keys into the replacing row or verify that their absence is intentional.'));
+        }
     }
-    for (const [claim, values] of groups(model.uiClaims ?? [], (value) => `${value.kind}:${value.value}`)) {
+    return diagnostics;
+}
+function uiMode(claim) {
+    if (claim.mode !== undefined)
+        return claim.mode;
+    if (claim.kind === 'sidebar')
+        return 'list-contribution';
+    if (claim.kind === 'web-route')
+        return 'exact-route';
+    return 'single-owner';
+}
+function uiDiagnostics(claims) {
+    const diagnostics = [];
+    for (const [claim, values] of groups(claims, (value) => `${uiMode(value)}:${value.kind}:${value.value}`)) {
         if (values.length < 2)
             continue;
-        diagnostics.push(diagnostic('ui-ownership-conflict', 'error', 'Duplicate UI ownership claim', values.map((value) => evidence(value.source, claim, `${value.kind} ${value.value}`, value.evidenceKind, value.packageName, value.version)), `Multiple concrete declarations claim the same ${claim} UI surface.`, 'Assign the UI surface to one package or give each declaration a distinct slot, layout, sidebar entry, or route.'));
+        const mode = uiMode(values[0]);
+        if (mode === 'list-contribution' && new Set(values.map((value) => value.contributionId ?? value.packageName ?? value.source)).size > 1)
+            continue;
+        const severity = mode === 'prefix-route' ? 'warning' : 'error';
+        const id = mode === 'exact-route' ? 'ui-exact-route-conflict' : mode === 'fallback-owner' ? 'ui-fallback-owner-conflict' : 'ui-ownership-conflict';
+        diagnostics.push(diagnostic(id, severity, mode === 'exact-route' ? 'Exact web route has multiple owners' : 'UI ownership claim conflicts', values.map((value) => evidence(value.source, claim, `${value.kind} ${value.value}`, value.evidenceKind, value.packageName, value.version)), mode === 'prefix-route' ? `Multiple prefix route claims may shadow one another; ownership is not proven.` : `Multiple concrete declarations claim the same ${claim} surface.`, 'Assign one owner, or provide distinct list contribution ids where the public UI API allows multiple contributors.'));
+    }
+    return diagnostics;
+}
+export function analyseComposition(model) {
+    const diagnostics = [...model.adapterDiagnostics];
+    const requestedMode = model.evidenceMode ?? 'static';
+    const runtimeObserved = requestedMode === 'runtime-observed' && model.runtimeObservation?.observed === true;
+    if (requestedMode === 'runtime-observed' && !runtimeObserved) {
+        diagnostics.push(diagnostic('runtime-observation-unavailable', 'warning', 'Runtime observation is unavailable', [], 'The model requested runtime-observed evidence without a successful isolated runtime observation.', 'Keep this finding composed or static until a supported isolation backend returns observed runtime facts.'));
     }
+    diagnostics.push(...rowDiagnostics(model.rows), ...uiDiagnostics(model.uiClaims ?? []));
     for (const [hook, values] of groups((model.hooks ?? []).filter((value) => value.hook === 'tools/pre-execute' || value.hook === 'tools/execute' || value.hook === 'tools/post-execute'), (value) => value.hook)) {
         if (values.length < 2)
             continue;
-        diagnostics.push(diagnostic('hook-order-risk', 'warning', 'Multiple tool waterfall registrations', values.map((value) => evidence(value.source, hook, `registered ${hook}`, value.evidenceKind, value.packageName, value.version)), `Multiple listeners register ${hook}; static metadata does not establish their runtime order.`, 'Declare explicit ordering where the public DSH API supports it, then verify the resolved hook order in an isolated fixture.'));
+        diagnostics.push(diagnostic('hook-order-risk', 'warning', 'Multiple tool waterfall registrations', values.map((value) => evidence(value.source, hook, `registered ${hook}`, value.evidenceKind, value.packageName, value.version)), `Multiple listeners register ${hook}; runtime listener order is unverified.`, 'Declare explicit ordering where the public DSH API supports it, then verify the resolved hook order in an isolated fixture.'));
     }
     for (const [path, writes] of groups(model.patchWrites ?? [], (write) => write.path)) {
         if (writes.length < 2)
@@ -101,10 +148,15 @@ export function analyseComposition(model) {
     const platform = model.runtime?.platform;
     for (const requirement of model.platforms ?? []) {
         const item = evidence(requirement.source, requirement.packageName, `supports ${requirement.supported.join(', ')}; observed ${platform ?? 'unknown'}`, requirement.evidenceKind, requirement.packageName);
-        if (platform === undefined || !requirement.supported.includes(platform)) {
+        const excluded = requirement.supported.includes(`!${platform ?? ''}`);
+        const positive = requirement.supported.filter((value) => !value.startsWith('!'));
+        const supported = platform !== undefined && !excluded && (positive.length === 0 || positive.includes(platform));
+        if (!supported) {
             diagnostics.push(diagnostic('platform-mismatch', 'warning', 'Declared platform does not include selected runtime', [item], platform === undefined ? `No runtime platform was supplied for ${requirement.packageName}.` : `${requirement.packageName} declares ${requirement.supported.join(', ')}, not ${platform}.`, 'Use a supported platform or verify an intentional override in an isolated fixture.'));
         }
     }
     diagnostics.sort((left, right) => left.id.localeCompare(right.id) || left.title.localeCompare(right.title) || left.evidence[0]?.source.localeCompare(right.evidence[0]?.source ?? '') || 0);
-    return { schemaVersion: 1, generatedAt: new Date().toISOString(), profileDir: model.profileDir, diagnostics };
+    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 };
 }

package/dist/core/snapshot.js

@@ -1,59 +1,73 @@
+import { basename, isAbsolute, relative } from 'node:path';
+import { analyseComposition } from './rules.js';
 import { resolveComposition } from './composition-adapter.js';
-function isRecord(value) {
-    return value !== null && typeof value === 'object' && !Array.isArray(value);
+function isRecord(value) { return value !== null && typeof value === 'object' && !Array.isArray(value); }
+function normalizedSource(source, profileDir) {
+    if (!isAbsolute(source))
+        return source.replaceAll('\\', '/');
+    const value = relative(profileDir, source).replaceAll('\\', '/');
+    return value.startsWith('../') || value === '..' ? `<EXTERNAL>/${basename(source)}` : `<PROFILE>/${value}`;
 }
-function stringMap(value) {
-    if (!isRecord(value))
-        return [];
-    return Object.entries(value).flatMap(([name, version]) => typeof version === 'string' ? [[name, version]] : []);
+function sortJson(values) { return [...values].sort((left, right) => JSON.stringify(left).localeCompare(JSON.stringify(right))); }
+function packageSnapshot(fact) {
+    return {
+        name: fact.name,
+        ...(fact.requestedSpec === undefined ? {} : { requestedSpec: fact.requestedSpec }),
+        ...(fact.installedVersion === undefined ? {} : { installedVersion: fact.installedVersion }),
+        packageJsonSource: `<BUNDLE:${fact.name}>/package.json`,
+        ...(fact.bundlePatch === undefined ? {} : { bundlePatch: `<BUNDLE:${fact.name}>/${basename(fact.bundlePatch)}` }),
+        ...(fact.repository === undefined ? {} : { repository: fact.repository }),
+        ...(fact.gitRef === undefined ? {} : { gitRef: fact.gitRef }),
+        ...(fact.integrity === undefined ? {} : { integrity: fact.integrity }),
+        ...(fact.platform === undefined ? {} : { platform: [...fact.platform].sort() }),
+        ...(fact.peerDsh === undefined ? {} : { peerDsh: fact.peerDsh }),
+        ...(fact.peerCordis === undefined ? {} : { peerCordis: fact.peerCordis }),
+        ...(fact.engineNode === undefined ? {} : { engineNode: fact.engineNode })
+    };
 }
-function sortBySource(values) {
-    return [...values].sort((left, right) => left.source.localeCompare(right.source) || JSON.stringify(left).localeCompare(JSON.stringify(right)));
+function packageFromBundle(bundle, profileDir) {
+    return { name: bundle.name, ...(bundle.requestedSpec === undefined ? {} : { requestedSpec: bundle.requestedSpec }), ...(bundle.version === undefined ? {} : { installedVersion: bundle.version }), packageJsonSource: normalizedSource(bundle.source, profileDir), ...(bundle.repository === undefined ? {} : { repository: bundle.repository }), ...(bundle.gitRef === undefined ? {} : { gitRef: bundle.gitRef }), ...(bundle.integrity === undefined ? {} : { integrity: bundle.integrity }) };
 }
-function manifestSnapshot(input) {
-    const file = input.files.find((candidate) => candidate.relativePath === 'package.json');
+function lockKind(input) {
+    const file = input?.files.find((item) => ['pnpm-lock.yaml', 'package-lock.json', 'yarn.lock'].includes(item.relativePath));
     if (file === undefined)
-        return { plugins: [], peers: [], platforms: [] };
+        return {};
+    return { kind: file.relativePath === 'pnpm-lock.yaml' ? 'pnpm' : file.relativePath === 'yarn.lock' ? 'yarn' : 'npm', lockfileHash: file.sha256 };
+}
+function snapshotFromModel(model, input) {
+    const profileDir = model.profileDir;
+    const report = analyseComposition(model);
+    const manifest = input?.files.find((candidate) => candidate.relativePath === 'package.json');
+    let profileName;
     try {
-        const manifest = JSON.parse(file.text);
-        const packageName = typeof manifest.name === 'string' ? manifest.name : undefined;
-        const plugins = [...stringMap(manifest.dependencies), ...stringMap(manifest.devDependencies)]
-            .map(([name, version]) => ({ name, version, source: file.relativePath }))
-            .sort((left, right) => left.name.localeCompare(right.name) || left.version.localeCompare(right.version));
-        const peers = packageName === undefined ? [] : [{
-                packageName,
-                source: file.relativePath,
-                ...Object.fromEntries(stringMap(manifest.peerDependencies).filter(([name]) => name === '@deepseek-ai/dsh' || name === '@deepseek-ai/cordis' || name === 'node').map(([name, range]) => [name === '@deepseek-ai/dsh' ? 'dsh' : name === '@deepseek-ai/cordis' ? 'cordis' : 'node', range]))
-            }];
-        const platforms = packageName === undefined || !Array.isArray(manifest.os) ? [] : [{ packageName, source: file.relativePath, supported: manifest.os.filter((platform) => typeof platform === 'string').sort() }];
-        return { ...(packageName === undefined ? {} : { packageName }), plugins, peers, platforms };
-    }
-    catch {
-        return { plugins: [], peers: [], platforms: [] };
+        profileName = manifest === undefined ? undefined : JSON.parse(manifest.text).name;
     }
-}
-function snapshotFromModel(model, profile, hashes, plugins = []) {
+    catch { /* hash-only metadata is still valid */ }
+    const packages = model.installedPackages?.map(packageSnapshot) ?? model.bundles?.map((bundle) => packageFromBundle(bundle, profileDir)) ?? [];
+    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: 1,
-        profile,
-        plugins: [...plugins].sort((left, right) => left.name.localeCompare(right.name) || (left.version ?? '').localeCompare(right.version ?? '')),
-        rows: model.rows.map(({ id, name, source }) => ({ ...(id === undefined ? {} : { id }), ...(name === undefined ? {} : { name }), source })).sort((left, right) => left.source.localeCompare(right.source) || (left.id ?? '').localeCompare(right.id ?? '')),
-        hooks: sortBySource((model.hooks ?? []).map(({ hook, source, packageName, version }) => ({ hook, source, ...(packageName === undefined ? {} : { packageName }), ...(version === undefined ? {} : { version }) }))),
-        uiClaims: sortBySource((model.uiClaims ?? []).map(({ kind, value, source, packageName, version }) => ({ kind, value, source, ...(packageName === undefined ? {} : { packageName }), ...(version === undefined ? {} : { version }) }))),
-        peers: sortBySource((model.peerRequirements ?? []).map(({ packageName, source, dsh, cordis, node }) => ({ packageName, source, ...(dsh === undefined ? {} : { dsh }), ...(cordis === undefined ? {} : { cordis }), ...(node === undefined ? {} : { node }) }))),
-        platforms: sortBySource((model.platforms ?? []).map(({ packageName, source, supported }) => ({ packageName, source, supported: [...supported].sort() }))),
-        bundles: sortBySource((model.bundles ?? []).map(({ name, version, source, gitRef, profile: bundleProfile }) => ({ name, source, ...(version === undefined ? {} : { version }), ...(gitRef === undefined ? {} : { gitRef }), ...(bundleProfile === undefined ? {} : { profile: bundleProfile }) }))),
+        schemaVersion: 2,
+        doctorVersion: '0.1.3',
+        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),
+        rows: model.rows.map((row) => ({ ...(row.id === undefined ? {} : { id: row.id }), ...(row.name === undefined ? {} : { name: row.name }), source: normalizedSource(row.source, profileDir), ...(row.layer === undefined ? {} : { layer: row.layer }), ...(row.configKeys === undefined ? {} : { configKeys: [...row.configKeys].sort() }), ...(row.replacement === true ? { replacement: true } : {}) })).sort((left, right) => JSON.stringify(left).localeCompare(JSON.stringify(right))),
+        hooks: sortJson((model.hooks ?? []).map(({ hook, source, packageName, version }) => ({ hook, source: normalizedSource(source, profileDir), ...(packageName === undefined ? {} : { packageName }), ...(version === undefined ? {} : { version }) }))),
+        uiClaims: sortJson((model.uiClaims ?? []).map(({ kind, value, source, packageName, version, mode, contributionId }) => ({ kind, value, source: normalizedSource(source, profileDir), ...(packageName === undefined ? {} : { packageName }), ...(version === undefined ? {} : { version }), ...(mode === undefined ? {} : { mode }), ...(contributionId === undefined ? {} : { contributionId }) }))),
+        conflicts: sortJson(report.diagnostics.map((item) => ({ id: item.id, severity: item.severity, subjects: item.evidence.map((entry) => `${normalizedSource(entry.source, profileDir)}:${entry.subject ?? ''}`).sort() }))),
+        packageManager: lockKind(input),
         hashes
     };
 }
-/** Creates a structural, redacted snapshot from already allow-listed profile input or a resolved model. */
 export async function createSnapshot(input) {
-    if ('files' in input) {
-        const manifest = manifestSnapshot(input);
-        const hashes = Object.fromEntries(input.files
-            .filter((file) => file.relativePath === 'package.json' || file.relativePath === 'pnpm-lock.yaml' || file.relativePath === 'package-lock.json' || file.relativePath === 'yarn.lock')
-            .map((file) => [file.relativePath, file.sha256]));
-        return snapshotFromModel(await resolveComposition(input), { path: input.profileDir, ...(manifest.packageName === undefined ? {} : { packageName: manifest.packageName }) }, hashes, manifest.plugins);
-    }
-    return snapshotFromModel(input, { path: input.profileDir }, {}, input.bundles?.map(({ name, version, source }) => ({ name, source, ...(version === undefined ? {} : { version }) })) ?? []);
+    if ('files' in input)
+        return snapshotFromModel(await resolveComposition(input), input);
+    return snapshotFromModel(input);
+}
+export function isSnapshotV2(value) { return isRecord(value) && value.schemaVersion === 2 && Array.isArray(value.packages) && isRecord(value.profile); }
+export function isSnapshotV1(value) { return isRecord(value) && value.schemaVersion === 1 && Array.isArray(value.plugins); }
+export function legacyPlugins(snapshot) {
+    if (isSnapshotV1(snapshot))
+        return snapshot.plugins;
+    return snapshot.packages.map((item) => ({ name: item.name, ...(item.installedVersion === undefined ? {} : { version: item.installedVersion }), source: item.packageJsonSource }));
 }

package/dist/plugin/index.js

@@ -1,13 +1,15 @@
 import { lstat, readFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
 import z from '@deepseek-ai/schemastery';
+import { defaultReportDirectory, resolveReportDirectory } from '../reports/location.js';
 export const name = 'dsh-composition-doctor';
 /** Public Cordis service dependency supplied by dsh-host-webserver. */
 export const inject = ['webServer'];
-export const Config = z.object({ reportDir: z.string() });
+export const Config = z.object({ reportDir: z.string().default(defaultReportDirectory) });
 export const latestReportPath = '/dsh-composition-doctor/reports/latest';
+const maxReportBytes = 2 * 1024 * 1024;
 function reportDirectory(config) {
-    return resolve(config.reportDir ?? '.dsh-composition-doctor/reports');
+    return resolveReportDirectory(config.reportDir);
 }
 function send(response, status, body) {
     response.statusCode = status;
@@ -33,8 +35,12 @@ async function latestReport(config) {
             const fileStat = await lstat(candidate);
             if (!fileStat.isFile())
                 continue;
+            if (fileStat.size > maxReportBytes)
+                continue;
             const text = await readFile(candidate, 'utf8');
-            JSON.parse(text);
+            const value = JSON.parse(text);
+            if (!isAnalysisReport(value))
+                continue;
             return text.endsWith('\n') ? text : `${text}\n`;
         }
         catch {
@@ -44,6 +50,13 @@ async function latestReport(config) {
     }
     return undefined;
 }
+function isAnalysisReport(value) {
+    if (value === null || typeof value !== 'object')
+        return false;
+    const report = value;
+    const legacy = report.evidenceSchemaVersion === undefined && report.evidenceMode === 'resolved';
+    return report.schemaVersion === 1 && (report.evidenceSchemaVersion === 2 || legacy) && Array.isArray(report.diagnostics) && (report.evidenceMode === 'static' || report.evidenceMode === 'composed' || report.evidenceMode === 'runtime-observed' || report.evidenceMode === 'mixed' || legacy) && typeof report.generatedAt === 'string' && (report.runtimeObserved === undefined || typeof report.runtimeObserved === 'boolean');
+}
 function route(config) {
     return {
         kind: 'exact',

package/dist/reports/location.js

@@ -0,0 +1,9 @@
+import { resolve } from 'node:path';
+/**
+ * Relative to the DSH host process working directory. This directory is owned
+ * by the doctor plugin and is deliberately separate from a scanned profile.
+ */
+export const defaultReportDirectory = '.dsh-composition-doctor/reports';
+export function resolveReportDirectory(reportDir = defaultReportDirectory) {
+    return resolve(reportDir);
+}

package/dist/reports/markdown.js

@@ -1,7 +1,7 @@
 function formatEvidence(item) {
     const subject = item.subject === undefined ? '' : ` — ${item.subject}`;
     const packageLabel = item.packageName === undefined ? '' : ` (${item.packageName}${item.version === undefined ? '' : `@${item.version}`})`;
-    return `- \`${item.source}\`${subject}${packageLabel}: ${item.detail}`;
+    return `- [${item.evidenceKind}] \`${item.source}\`${subject}${packageLabel}: ${item.detail}`;
 }
 function formatDiagnostic(item) {
     const evidence = item.evidence.length === 0 ? '- No concrete source evidence was supplied.' : item.evidence.map(formatEvidence).join('\n');
@@ -10,5 +10,6 @@ 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');
-    return `# DSH Composition Doctor Report\n\nSchema: ${report.schemaVersion}\n\nProfile: \`${report.profileDir}\`\n\nGenerated: ${report.generatedAt}\n\nSummary: ${summary}\n\n${body}\n`;
+    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`;
 }