dsh-composition-doctor 0.1.3 → 0.2.1

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

@@ -0,0 +1,150 @@
+import { lstat, readFile, readdir } from 'node:fs/promises';
+import { delimiter, join, resolve } from 'node:path';
+import { stat } from 'node:fs/promises';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { tmpdir } from 'node:os';
+import { downloadNpmArtifact, fileDigest, readNpmCacheMetadata, tarManifest } from './npm-artifact.js';
+const execFileAsync = promisify(execFile);
+async function readableFile(path) {
+    try {
+        return (await stat(path)).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+async function readableDirectory(path) {
+    try {
+        return (await stat(path)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+async function respondsToVersion(path) {
+    try {
+        const shim = process.platform === 'win32' && /\.(?:cmd|bat)$/i.test(path);
+        const executable = shim ? (process.env.ComSpec ?? 'cmd.exe') : path;
+        const args = shim ? ['/d', '/s', '/c', `call "${path}" --version`] : ['--version'];
+        await execFileAsync(executable, args, { windowsHide: true, timeout: 5_000, maxBuffer: 128 * 1024 });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function explicitPackage(path, targetDsh) {
+    if (await readableFile(path)) {
+        if (/\.(?:tgz|tar|tar\.gz)$/i.test(path)) {
+            try {
+                const bytes = await readFile(path);
+                const manifest = tarManifest(bytes);
+                const digest = await fileDigest(path);
+                const resolvedVersion = typeof manifest.version === 'string' ? manifest.version : undefined;
+                return { kind: 'dsh-tarball', path, detail: resolvedVersion === targetDsh ? `Using explicit local DSH ${targetDsh} tarball.` : `Using local DSH tarball candidate ${resolvedVersion ?? 'unknown'}; target ${targetDsh} is not verified.`, targetVersionVerified: resolvedVersion === targetDsh, source: 'explicit-local', requestedVersion: targetDsh, resolvedVersion, manifest, ...digest };
+            }
+            catch {
+                return { kind: 'unavailable', detail: `Explicit DSH tarball could not be inspected: ${path}`, targetVersionVerified: false, source: 'unavailable', requestedVersion: targetDsh };
+            }
+        }
+        return { kind: 'unavailable', detail: `Explicit DSH package path is a file but not a supported local tarball: ${path}`, targetVersionVerified: false, source: 'unavailable', requestedVersion: targetDsh };
+    }
+    if (!(await readableDirectory(path)))
+        return { kind: 'unavailable', detail: `Explicit DSH package path is not readable: ${path}`, targetVersionVerified: false, source: 'unavailable', requestedVersion: targetDsh };
+    try {
+        const manifest = JSON.parse(await readFile(join(path, 'package.json'), 'utf8'));
+        const version = typeof manifest.version === 'string' ? manifest.version : undefined;
+        const hasBin = typeof manifest.bin === 'string' || (manifest.bin !== null && typeof manifest.bin === 'object');
+        const digest = await fileDigest(join(path, 'package.json'));
+        if (!hasBin)
+            return { kind: 'unavailable', detail: `Local DSH package has no public bin entry: ${path}`, targetVersionVerified: false, source: 'unavailable', requestedVersion: targetDsh, resolvedVersion: version, manifest, ...digest };
+        return { kind: 'dsh-package', path, detail: version === targetDsh ? `Using local DSH package ${targetDsh}.` : `Using local DSH package candidate ${version ?? 'unknown'}; target ${targetDsh} is not verified.`, targetVersionVerified: version === targetDsh, source: 'explicit-local', requestedVersion: targetDsh, resolvedVersion: version, manifest, ...digest };
+    }
+    catch {
+        return { kind: 'unavailable', detail: `Local DSH package has no readable package.json: ${path}`, targetVersionVerified: false, source: 'unavailable', requestedVersion: targetDsh };
+    }
+}
+async function cachedTarball(targetDsh, cacheDir, source) {
+    try {
+        const names = await readdir(cacheDir);
+        const path = names.map((name) => resolve(cacheDir, name)).find((candidate) => candidate.endsWith('.tgz') && candidate.includes(targetDsh));
+        if (path === undefined)
+            return undefined;
+        if (!(await lstat(path)).isFile())
+            return undefined;
+        const bytes = await readFile(path);
+        const manifest = tarManifest(bytes);
+        const resolvedVersion = typeof manifest.version === 'string' ? manifest.version : undefined;
+        const digest = await fileDigest(path);
+        if (source === 'doctor-cache') {
+            const metadata = await readNpmCacheMetadata(path);
+            if (metadata === undefined || metadata.resolvedVersion !== resolvedVersion || metadata.sha512 !== digest.sha512 || metadata.integrity !== digest.integrity)
+                return undefined;
+        }
+        const label = source === 'doctor-cache' ? 'Doctor cache' : 'package-manager cache/store';
+        return { kind: 'dsh-tarball', path, detail: resolvedVersion === targetDsh ? `Using ${label} artifact for DSH ${targetDsh}.` : `${label} contains DSH ${resolvedVersion ?? 'unknown'}, not requested ${targetDsh}.`, targetVersionVerified: resolvedVersion === targetDsh, source, requestedVersion: targetDsh, resolvedVersion, manifest, ...digest };
+    }
+    catch {
+        return undefined;
+    }
+}
+async function installedDsh() {
+    const pathValue = process.env.PATH ?? '';
+    for (const directory of pathValue.split(delimiter).filter(Boolean)) {
+        const candidates = process.platform === 'win32' ? [join(directory, 'dsh.cmd'), join(directory, 'dsh.exe'), join(directory, 'dsh')] : [join(directory, 'dsh')];
+        for (const candidate of candidates)
+            if (await readableFile(candidate) && await respondsToVersion(candidate)) {
+                try {
+                    const shim = process.platform === 'win32' && /\.(?:cmd|bat)$/i.test(candidate);
+                    const executable = shim ? (process.env.ComSpec ?? 'cmd.exe') : candidate;
+                    const args = shim ? ['/d', '/s', '/c', `call "${candidate}" --version`] : ['--version'];
+                    const result = await execFileAsync(executable, args, { windowsHide: true, timeout: 5_000, maxBuffer: 128 * 1024 });
+                    return { path: candidate, version: `${result.stdout}\n${result.stderr}`.trim() };
+                }
+                catch {
+                    return { path: candidate };
+                }
+            }
+    }
+    return undefined;
+}
+/** Offline-first target artifact discovery. No registry, Git, cache install, or lifecycle is performed. */
+export async function resolveDshArtifact(options) {
+    if (options.dshBin !== undefined) {
+        if (await readableFile(options.dshBin))
+            return { kind: 'dsh-bin', path: options.dshBin, detail: `Using explicit local DSH binary candidate for ${options.targetDsh}; release version is not verified until --version is checked.`, targetVersionVerified: false, source: 'explicit-local', requestedVersion: options.targetDsh, ...(await fileDigest(options.dshBin)) };
+        return { kind: 'unavailable', detail: `Explicit DSH binary path is not readable: ${options.dshBin}`, targetVersionVerified: false, source: 'unavailable', requestedVersion: options.targetDsh };
+    }
+    if (options.dshPackage !== undefined)
+        return explicitPackage(options.dshPackage, options.targetDsh);
+    const installed = await installedDsh();
+    if (installed !== undefined)
+        return { kind: 'dsh-bin', path: installed.path, detail: `Using installed local dsh candidate for ${options.targetDsh}; release version is not verified.`, targetVersionVerified: installed.version?.includes(options.targetDsh) === true, source: 'installed', requestedVersion: options.targetDsh, resolvedVersion: installed.version, ...(await fileDigest(installed.path)) };
+    for (const directory of options.packageManagerCacheDirs ?? []) {
+        const cached = await cachedTarball(options.targetDsh, directory, 'package-manager-cache');
+        if (cached !== undefined && cached.targetVersionVerified)
+            return cached;
+    }
+    if (options.cacheDir !== undefined) {
+        const cached = await cachedTarball(options.targetDsh, options.cacheDir, 'doctor-cache');
+        if (cached !== undefined && cached.targetVersionVerified)
+            return cached;
+    }
+    if (options.online) {
+        try {
+            const downloaded = await downloadNpmArtifact(`@deepseek-ai/dsh@${options.targetDsh}`, options.cacheDir ?? join(tmpdir(), 'dsh-composition-doctor-cache'));
+            return { kind: 'dsh-tarball', path: downloaded.path, detail: `Downloaded official DSH ${downloaded.resolvedVersion} artifact from npm registry into Doctor-owned cache.`, targetVersionVerified: downloaded.resolvedVersion === options.targetDsh, source: downloaded.source, requestedVersion: options.targetDsh, resolvedVersion: downloaded.resolvedVersion, manifest: downloaded.manifest, sha512: downloaded.sha512, integrity: downloaded.integrity };
+        }
+        catch (error) {
+            return { kind: 'unavailable', detail: `Official npm artifact download failed for DSH ${options.targetDsh}: ${error instanceof Error ? error.message : String(error)}`, targetVersionVerified: false, source: 'unavailable', requestedVersion: options.targetDsh };
+        }
+    }
+    return {
+        kind: 'unavailable',
+        detail: `Target DSH ${options.targetDsh} artifact unavailable offline; no permitted local package-manager cache/store or Doctor cache contained the exact release.`,
+        targetVersionVerified: false,
+        source: 'unavailable',
+        requestedVersion: options.targetDsh
+    };
+}

package/dist/core/preflight/candidate-artifact-resolver.js

@@ -0,0 +1,61 @@
+import { lstat, readFile, readdir } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { tmpdir } from 'node:os';
+import { downloadNpmArtifact, fileDigest, tarManifest } from './npm-artifact.js';
+function candidateParts(candidate) {
+    const at = candidate.lastIndexOf('@');
+    return { name: candidate.slice(0, at), version: candidate.slice(at + 1) };
+}
+function packagePath(profileDir, name) {
+    return resolve(profileDir, 'node_modules', ...name.split('/'), 'package.json');
+}
+/** Reads only an already-installed candidate manifest; it never invokes a package manager. */
+export async function resolveCandidateArtifact(profileDir, candidate, online, cacheDir, packageManagerCacheDirs) {
+    const { name, version } = candidateParts(candidate);
+    const packageJsonPath = packagePath(profileDir, name);
+    try {
+        const manifest = JSON.parse(await readFile(packageJsonPath, 'utf8'));
+        const installedVersion = typeof manifest.version === 'string' ? manifest.version : 'unknown';
+        if (installedVersion !== version)
+            return { status: 'unavailable', candidate, detail: `Local candidate manifest version ${installedVersion} does not match requested ${version}.` };
+        const scripts = manifest.scripts ?? {};
+        const lifecycleScripts = ['preinstall', 'install', 'postinstall', 'prepare'].filter((key) => typeof scripts[key] === 'string');
+        return { status: 'resolved', candidate, detail: 'Inspected an existing local candidate manifest; no install or lifecycle was executed.', artifact: { name, requestedVersion: version, installedVersion, packageJsonPath, lifecycleScripts, source: 'profile-node_modules', manifest } };
+    }
+    catch {
+        for (const directory of packageManagerCacheDirs ?? []) {
+            try {
+                const nameInFilename = name.replaceAll('/', '-');
+                const filename = (await readdir(directory)).find((entry) => entry.endsWith('.tgz') && entry.includes(nameInFilename) && entry.includes(version));
+                if (filename === undefined)
+                    continue;
+                const tarballPath = resolve(directory, filename);
+                if (!(await lstat(tarballPath)).isFile())
+                    continue;
+                const manifest = tarManifest(await readFile(tarballPath));
+                if (manifest.name !== name || manifest.version !== version)
+                    continue;
+                const scripts = manifest.scripts !== null && typeof manifest.scripts === 'object' ? manifest.scripts : {};
+                const lifecycleScripts = ['preinstall', 'install', 'postinstall', 'prepare'].filter((key) => typeof scripts[key] === 'string');
+                const digest = await fileDigest(tarballPath);
+                return { status: 'resolved', candidate, detail: 'Inspected an exact package-manager cache/store tarball; no install or lifecycle was executed.', artifact: { name, requestedVersion: version, installedVersion: version, packageJsonPath: tarballPath, lifecycleScripts, source: 'package-manager-cache', manifest, integrity: digest.integrity, sha512: digest.sha512 } };
+            }
+            catch {
+                // An unreadable cache entry is not evidence of an unavailable release.
+            }
+        }
+        if (!online)
+            return { status: 'unavailable', candidate, detail: `${candidate} is not available as an exact local profile node_modules artifact offline.` };
+        try {
+            const downloaded = await downloadNpmArtifact(candidate, cacheDir ?? resolve(tmpdir(), 'dsh-composition-doctor-cache'));
+            if (downloaded.resolvedVersion !== version)
+                return { status: 'unavailable', candidate, detail: `npm resolved ${downloaded.resolvedVersion}, not requested ${version}; the downloaded artifact was not accepted.` };
+            const scripts = downloaded.manifest.scripts !== null && typeof downloaded.manifest.scripts === 'object' ? downloaded.manifest.scripts : {};
+            const lifecycleScripts = ['preinstall', 'install', 'postinstall', 'prepare'].filter((key) => typeof scripts[key] === 'string');
+            return { status: 'resolved', candidate, detail: `Downloaded and inspected the exact npm artifact into Doctor-owned cache; no install or lifecycle was executed.`, artifact: { name, requestedVersion: version, installedVersion: downloaded.resolvedVersion, packageJsonPath: downloaded.path, lifecycleScripts, source: 'npm-registry', manifest: downloaded.manifest, integrity: downloaded.integrity, sha512: downloaded.sha512, registry: downloaded.registry } };
+        }
+        catch (error) {
+            return { status: 'unavailable', candidate, detail: `Candidate npm artifact download failed for ${candidate}: ${error instanceof Error ? error.message : String(error)}` };
+        }
+    }
+}

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

@@ -0,0 +1,132 @@
+import { createHash, randomBytes } from 'node:crypto';
+import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { basename, resolve } from 'node:path';
+import { gunzipSync } from 'node:zlib';
+function text(bytes) {
+    return new TextDecoder().decode(bytes).replace(/\0+$/g, '');
+}
+export function tarManifest(bytes) {
+    // npm publishes gzip-compressed tar archives (.tgz). Keep accepting a
+    // plain tar too because explicit local fixtures are useful in unit tests.
+    const archive = bytes[0] === 0x1f && bytes[1] === 0x8b ? gunzipSync(bytes) : bytes;
+    let manifest;
+    for (let offset = 0; offset + 512 <= archive.length;) {
+        const name = text(archive.slice(offset, offset + 100));
+        if (name.length === 0)
+            break;
+        const normalizedName = name.replaceAll('\\', '/');
+        const pathParts = normalizedName.split('/');
+        const type = archive[offset + 156];
+        if (normalizedName.startsWith('/') || /^[A-Za-z]:\//.test(normalizedName) || name.includes('\\') || pathParts.includes('..')) {
+            throw new Error(`npm tarball contains an unsafe path: ${name}`);
+        }
+        if (type === 49 || type === 50)
+            throw new Error(`npm tarball contains a link entry: ${name}`);
+        const sizeText = text(archive.slice(offset + 124, offset + 136)).trim();
+        const size = Number.parseInt(sizeText || '0', 8);
+        if (!Number.isSafeInteger(size) || size < 0)
+            throw new Error(`npm tarball contains an invalid entry size: ${name}`);
+        const dataStart = offset + 512;
+        if (dataStart + size > archive.length)
+            throw new Error(`npm tarball entry is truncated: ${name}`);
+        if (normalizedName === 'package/package.json')
+            manifest = JSON.parse(text(archive.slice(dataStart, dataStart + size)));
+        offset = dataStart + Math.ceil(size / 512) * 512;
+    }
+    if (manifest === undefined)
+        throw new Error('npm tarball has no package/package.json');
+    return manifest;
+}
+function digest(bytes) {
+    const hash = createHash('sha512').update(bytes);
+    const base64 = hash.digest('base64');
+    const sha512 = createHash('sha512').update(bytes).digest('hex');
+    return { sha512, integrity: `sha512-${base64}` };
+}
+function exactPackageSpec(requestedSpec) {
+    const separator = requestedSpec.lastIndexOf('@');
+    if (separator <= 0 || separator === requestedSpec.length - 1)
+        throw new Error(`Only exact npm package specs are supported: ${requestedSpec}`);
+    return { name: requestedSpec.slice(0, separator), version: requestedSpec.slice(separator + 1) };
+}
+function metadataPath(path) {
+    return `${path}.metadata.json`;
+}
+async function atomicWrite(path, bytes) {
+    const temporaryPath = `${path}.${randomBytes(12).toString('hex')}.partial`;
+    try {
+        await writeFile(temporaryPath, bytes, { flag: 'wx' });
+        await rename(temporaryPath, path);
+    }
+    finally {
+        await rm(temporaryPath, { force: true }).catch(() => undefined);
+    }
+}
+export async function readNpmCacheMetadata(path) {
+    try {
+        const value = JSON.parse(await readFile(metadataPath(path), 'utf8'));
+        if (value === null || typeof value !== 'object')
+            return undefined;
+        const metadata = value;
+        if (typeof metadata.requestedSpec !== 'string' || typeof metadata.resolvedVersion !== 'string' || metadata.registry !== 'https://registry.npmjs.org' || typeof metadata.sha512 !== 'string' || typeof metadata.integrity !== 'string')
+            return undefined;
+        return metadata;
+    }
+    catch {
+        return undefined;
+    }
+}
+async function registryJson(url) {
+    const response = await fetch(url, { headers: { accept: 'application/json' } });
+    if (!response.ok)
+        throw new Error(`npm registry returned HTTP ${response.status} for ${url}`);
+    const value = await response.json();
+    if (value === null || typeof value !== 'object')
+        throw new Error(`npm registry returned invalid JSON for ${url}`);
+    return value;
+}
+/** Downloads one exact npm package tarball into Doctor-owned cache storage without install or lifecycle execution. */
+export async function downloadNpmArtifact(requestedSpec, cacheDir) {
+    const directory = resolve(cacheDir);
+    await mkdir(directory, { recursive: true });
+    const { name, version } = exactPackageSpec(requestedSpec);
+    const metadataUrl = `https://registry.npmjs.org/${encodeURIComponent(name)}`;
+    const packageMetadata = await registryJson(metadataUrl);
+    const versions = packageMetadata.versions;
+    const versionMetadata = versions !== null && typeof versions === 'object'
+        ? versions[version]
+        : undefined;
+    if (versionMetadata === null || typeof versionMetadata !== 'object')
+        throw new Error(`npm registry has no exact version ${version} for ${name}`);
+    const metadata = versionMetadata;
+    const dist = metadata.dist;
+    if (dist === undefined)
+        throw new Error(`npm registry metadata has no dist information for ${requestedSpec}`);
+    const tarballUrl = dist?.tarball;
+    if (typeof tarballUrl !== 'string')
+        throw new Error(`npm registry metadata has no tarball URL for ${requestedSpec}`);
+    const response = await fetch(tarballUrl, { headers: { accept: 'application/octet-stream' } });
+    if (!response.ok)
+        throw new Error(`npm registry returned HTTP ${response.status} for ${tarballUrl}`);
+    const bytes = new Uint8Array(await response.arrayBuffer());
+    const filename = basename(new URL(tarballUrl).pathname) || `${name.replaceAll('/', '-')}-${version}.tgz`;
+    const path = resolve(directory, filename);
+    const manifest = tarManifest(bytes);
+    const resolvedVersion = typeof manifest.version === 'string' ? manifest.version : undefined;
+    if (resolvedVersion === undefined)
+        throw new Error(`npm tarball has no resolved version for ${requestedSpec}`);
+    if (manifest.name !== name || resolvedVersion !== version)
+        throw new Error(`npm tarball manifest does not match exact request ${requestedSpec}`);
+    const computed = digest(bytes);
+    if (typeof dist.integrity === 'string' && dist.integrity !== computed.integrity)
+        throw new Error(`npm registry integrity mismatch for ${requestedSpec}`);
+    const integrity = typeof dist.integrity === 'string' ? dist.integrity : computed.integrity;
+    const cacheMetadata = { requestedSpec, resolvedVersion, registry: 'https://registry.npmjs.org', sha512: computed.sha512, integrity };
+    await atomicWrite(metadataPath(path), Buffer.from(`${JSON.stringify(cacheMetadata)}\n`, 'utf8'));
+    await atomicWrite(path, bytes);
+    return { path, requestedSpec, resolvedVersion, manifest, source: 'npm-registry', registry: 'https://registry.npmjs.org', ...computed, integrity };
+}
+export async function fileDigest(path) {
+    const bytes = await readFile(path);
+    return digest(bytes);
+}

package/dist/core/preflight/package-manager.js

@@ -0,0 +1,4 @@
+/** Describes the only package-manager policy accepted by the preflight runner. */
+export function packageManagerPolicy(online, allowBuild) {
+    return { online, allowBuild, lifecycleScripts: allowBuild ? ['preinstall', 'install', 'postinstall', 'prepare'] : [] };
+}

package/dist/core/preflight/package-resolution.js

@@ -0,0 +1,66 @@
+import { satisfies } from 'semver';
+function evidence(source, subject, detail, severity) {
+    return { source, subject, detail, evidenceKind: 'static', ...(severity === undefined ? {} : { severity }) };
+}
+function rangeCheck(range, actual, subject, source, label, evidenceItems, checks) {
+    if (typeof range !== 'string')
+        return;
+    if (actual === undefined) {
+        checks[label] = 'unknown';
+        evidenceItems.push(evidence(source, subject, `${label} requires ${range}, but the selected runtime fact is unavailable.`, 'warning'));
+        return;
+    }
+    try {
+        const matches = satisfies(actual, range, { includePrerelease: true });
+        checks[label] = matches ? 'pass' : 'fail';
+        evidenceItems.push(evidence(source, subject, `${label} requires ${range}; observed ${actual}.`, matches ? undefined : 'warning'));
+    }
+    catch {
+        checks[label] = 'unknown';
+        evidenceItems.push(evidence(source, subject, `${label} declares an unsupported range ${range}.`, 'warning'));
+    }
+}
+function listConstraint(value, actual, source, subject, label, evidenceItems, checks) {
+    if (value === undefined)
+        return;
+    const values = Array.isArray(value) ? value.filter((item) => typeof item === 'string') : typeof value === 'string' ? [value] : [];
+    if (values.length === 0) {
+        checks[label] = 'unknown';
+        evidenceItems.push(evidence(source, subject, `${label} constraint could not be interpreted.`, 'warning'));
+        return;
+    }
+    const excluded = values.some((item) => item.startsWith('!') && item.slice(1) === actual);
+    const positive = values.filter((item) => !item.startsWith('!'));
+    const matches = !excluded && (positive.length === 0 || positive.includes(actual));
+    checks[label] = matches ? 'pass' : 'fail';
+    evidenceItems.push(evidence(source, subject, `${label} declares ${values.join(', ')}; observed ${actual}.`, matches ? undefined : 'warning'));
+}
+export function evaluatePackageResolution(input) {
+    const evidenceItems = [];
+    const checks = {};
+    const manifest = input.manifest;
+    if (manifest === undefined || input.resolvedVersion === undefined) {
+        return { packageName: input.packageName, requestedVersion: input.requestedVersion, resolvedVersion: input.resolvedVersion, status: 'unavailable', source: input.source, integrity: input.integrity, sha512: input.sha512, checks: { artifact: 'unknown' }, evidence: [evidence(input.source, input.packageName, 'Package metadata was not available for resolution.', 'warning')] };
+    }
+    checks.version = input.resolvedVersion === input.requestedVersion ? 'pass' : 'fail';
+    evidenceItems.push(evidence(input.source, input.packageName, `Requested ${input.requestedVersion}; resolved ${input.resolvedVersion}.`, checks.version === 'pass' ? undefined : 'error'));
+    const peers = manifest.peerDependencies !== null && typeof manifest.peerDependencies === 'object' ? manifest.peerDependencies : {};
+    rangeCheck(peers['@deepseek-ai/dsh'], input.runtime.dsh, input.packageName, input.source, 'DSH peer', evidenceItems, checks);
+    rangeCheck(peers['@deepseek-ai/cordis'], input.runtime.cordis, input.packageName, input.source, 'Cordis peer', evidenceItems, checks);
+    const engines = manifest.engines !== null && typeof manifest.engines === 'object' ? manifest.engines : {};
+    rangeCheck(engines.node, input.runtime.node, input.packageName, input.source, 'Node engine', evidenceItems, checks);
+    listConstraint(manifest.os, input.runtime.platform ?? process.platform, input.source, input.packageName, 'OS', evidenceItems, checks);
+    listConstraint(manifest.cpu, process.arch, input.source, input.packageName, 'CPU', evidenceItems, checks);
+    const repository = manifest.repository;
+    const gitRef = typeof manifest.gitHead === 'string' ? manifest.gitHead : undefined;
+    if (input.integrity !== undefined || gitRef !== undefined || repository !== undefined) {
+        evidenceItems.push(evidence(input.source, input.packageName, `Package provenance: ${input.integrity === undefined ? 'no registry integrity' : input.integrity}${gitRef === undefined ? '' : `; git ref ${gitRef}`}.`));
+    }
+    else {
+        checks.provenance = 'unknown';
+        evidenceItems.push(evidence(input.source, input.packageName, 'No registry integrity or fixed Git ref was supplied with this local artifact.', 'warning'));
+    }
+    const values = Object.values(checks);
+    const status = values.includes('fail') ? 'incompatible' : values.includes('unknown') ? 'unknown' : 'compatible';
+    return { packageName: input.packageName, requestedVersion: input.requestedVersion, resolvedVersion: input.resolvedVersion, status, source: input.source, integrity: input.integrity, sha512: input.sha512, checks, evidence: evidenceItems };
+}

package/dist/core/preflight/rehearsal-profile.js

@@ -0,0 +1,6 @@
+import { mkdir } from 'node:fs/promises';
+/** Creates only the directory boundary; callers must copy allow-listed files through AST redaction. */
+export async function createRehearsalDirectory(directory) {
+    await mkdir(directory, { recursive: true });
+    return directory;
+}

package/dist/core/preflight/smoke.js

@@ -0,0 +1 @@
+export const runtimeNotRun = { outcome: 'not-run', detail: 'Third-party runtime execution requires an explicit supported isolation backend; a temporary directory is not a security sandbox.' };

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) {
@@ -40,7 +43,7 @@ function safeMetadataText(relativePath, text) {
             return `${JSON.stringify(redact(JSON.parse(text)), null, 2)}\n`;
         }
         if (yamlFiles.has(relativePath)) {
-            return stringify(redact(parse(text)));
+            return redactYamlPreservingTags(text);
         }
     }
     catch {
@@ -114,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;
@@ -122,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 });
@@ -135,27 +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.`));
+        const candidateResolutions = [];
         for (const candidate of candidates) {
             evidenceItems.push(evidence(profileDir, 'candidate-accepted', `${candidate} was accepted as an exact package@version reference.`));
-            evidenceItems.push(evidence(profileDir, 'candidate-metadata-inspected', `${candidate} was injected into the isolated package metadata and included in static manifest analysis.`));
+            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 requested, but this adapter performs no network operation.' : 'Offline mode enforced; no network operation was attempted.'));
-        if (options.online)
-            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, 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';
@@ -206,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,13 +53,19 @@ export async function readProfile({ profileDir }) {
             throw error;
         }
     }
+    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: ['nested plugin manifests and bundle metadata', 'environment files and values', 'private keys, tokens, sessions, and workspace source files']
+            unscannedSurfaces: ['non-declared nested plugin manifests and non-selected package metadata', 'environment files and values', 'private keys, tokens, sessions, and workspace source files']
         }
     };
 }