dsh-composition-doctor 0.1.2 → 0.2.0

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

@@ -0,0 +1,93 @@
+import { mkdir, mkdtemp, rm, stat, writeFile } from 'node:fs/promises';
+import { execFile } from 'node:child_process';
+import { tmpdir } from 'node:os';
+import { extname, join } from 'node:path';
+import { promisify } from 'node:util';
+import { redactYamlPreservingTags, redact } from './redaction.js';
+import { parseDshDump } from './dsh-dump-parser.js';
+const execFileAsync = promisify(execFile);
+const yamlFiles = new Set(['cordis.yml', 'cordis.patch.yml']);
+function unavailable(reason) {
+    return {
+        id: 'runtime-composition-unavailable', severity: 'warning', title: 'Resolved composition is unavailable', evidence: [{ source: '<DSH provider>', detail: reason, evidenceKind: 'static' }],
+        explanation: 'The scan could not obtain final resolved rows from a public DSH dump-config provider, so it used bounded static evidence.',
+        remediation: 'Install a verified DSH CLI or pass a public provider in integration code; do not import private DSH loaders.'
+    };
+}
+function pathCandidates() {
+    const values = (process.env.PATH ?? '').split(process.platform === 'win32' ? ';' : ':').filter(Boolean);
+    return values.flatMap((directory) => process.platform === 'win32' ? [join(directory, 'dsh.cmd'), join(directory, 'dsh.exe'), join(directory, 'dsh')] : [join(directory, 'dsh')]);
+}
+async function findDsh() {
+    const explicit = process.env.DSH_DOCTOR_DSH_BIN;
+    const candidates = explicit === undefined ? pathCandidates() : [explicit];
+    for (const candidate of candidates) {
+        try {
+            if ((await stat(candidate)).isFile())
+                return candidate;
+        }
+        catch { /* executable lookup is best effort */ }
+    }
+    return undefined;
+}
+async function copyRehearsal(input, directory) {
+    for (const file of input.files) {
+        if (file.relativePath === 'package.json') {
+            await writeFile(join(directory, file.relativePath), `${JSON.stringify(redact(JSON.parse(file.text)), null, 2)}\n`, 'utf8');
+        }
+        else if (yamlFiles.has(file.relativePath)) {
+            await writeFile(join(directory, file.relativePath), redactYamlPreservingTags(file.text), 'utf8');
+        }
+    }
+}
+function runtimeUnknownDiagnostic(input) {
+    const tagged = input.files.find((file) => yamlFiles.has(file.relativePath) && /!<[^>]+>|!![A-Za-z0-9_/-]+/.test(file.text));
+    if (tagged === undefined)
+        return undefined;
+    return {
+        id: 'runtime-behavior-unverified', severity: 'warning', title: 'Runtime-dependent configuration remains unverified',
+        evidence: [{ source: tagged.relativePath, detail: 'A custom YAML tag or runtime expression was preserved for dump-config but was not executed.', evidenceKind: 'composed' }],
+        explanation: 'A composed configuration can be structurally resolved while runtime-dependent values remain unknown. dump-config is not a runtime observation.',
+        remediation: 'Keep runtime-observed claims separate unless a supported isolated runtime observation backend is explicitly available.'
+    };
+}
+export async function tryDshDump(input, options = {}) {
+    const dshBin = options.dshBin ?? await findDsh();
+    if (dshBin === undefined)
+        return undefined;
+    const directory = await mkdtemp(join(tmpdir(), 'dsh-doctor-dump-'));
+    try {
+        const home = join(directory, 'dsh-home');
+        const isolatedName = 'doctor-isolated';
+        const profile = join(home, 'profiles', isolatedName);
+        await mkdir(profile, { recursive: true });
+        await copyRehearsal(input, profile);
+        const env = { PATH: process.env.PATH, TEMP: process.env.TEMP, TMP: process.env.TMP, DSH_HOME: home };
+        const extension = extname(dshBin).toLowerCase();
+        const script = ['.js', '.mjs', '.cjs'].includes(extension);
+        const commandShim = process.platform === 'win32' && (extension === '.cmd' || extension === '.bat');
+        const executable = script ? process.execPath : commandShim ? (process.env.ComSpec ?? 'cmd.exe') : dshBin;
+        const args = script ? [dshBin, '--profile', isolatedName, '--dump-config'] : commandShim ? ['/d', '/s', '/c', `call "${dshBin}" --profile ${isolatedName} --dump-config`] : ['--profile', isolatedName, '--dump-config'];
+        try {
+            const result = await execFileAsync(executable, args, { cwd: directory, env, timeout: options.timeoutMs ?? 20_000, windowsHide: true, maxBuffer: 2 * 1024 * 1024 });
+            const parsed = parseDshDump(result.stdout, result.stderr);
+            const runtimeUnknown = runtimeUnknownDiagnostic(input);
+            return { rows: parsed.rows, diagnostics: runtimeUnknown === undefined ? parsed.diagnostics : [...parsed.diagnostics, runtimeUnknown] };
+        }
+        catch (error) {
+            const detail = error instanceof Error ? error.message : String(error);
+            // The caller must keep the static rows when the public command cannot
+            // execute.  A default provider failure is represented by the bounded
+            // static-fallback diagnostic in composition-adapter.
+            void detail;
+            return undefined;
+        }
+    }
+    catch (error) {
+        void error;
+        return undefined;
+    }
+    finally {
+        await rm(directory, { recursive: true, force: true });
+    }
+}

package/dist/core/package-provenance.js

@@ -0,0 +1,80 @@
+import { createRequire } from 'node:module';
+import { readFile, realpath, stat } from 'node:fs/promises';
+import { dirname, isAbsolute, relative, resolve } from 'node:path';
+function record(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value) ? value : undefined;
+}
+function string(value) {
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+function repositoryValue(value) {
+    if (typeof value === 'string')
+        return value;
+    const object = record(value);
+    return object === undefined ? undefined : string(object.url);
+}
+function gitRefFrom(repository, manifest) {
+    const explicit = string(manifest.gitHead);
+    if (explicit !== undefined)
+        return explicit;
+    const match = repository?.match(/#([0-9a-f]{7,40})$/i);
+    return match?.[1];
+}
+function packageJsonPath(profileDir, name) {
+    if (!/^(?:@[a-z0-9_.-]+\/)?[a-z0-9_.-]+$/i.test(name))
+        throw new Error(`Invalid bundle package name: ${name}`);
+    const require = createRequire(resolve(profileDir, 'package.json'));
+    return require.resolve(`${name}/package.json`);
+}
+function within(root, candidate) {
+    const relativePath = relative(root, candidate);
+    return relativePath === '' || (!relativePath.startsWith('..') && !isAbsolute(relativePath));
+}
+export async function inspectInstalledPackage(profileDir, name, requestedSpec) {
+    const profileRoot = await realpath(profileDir);
+    const source = packageJsonPath(profileDir, name);
+    const resolvedSource = await realpath(source);
+    if (!within(profileRoot, resolvedSource))
+        throw new Error(`Bundle package resolves outside the selected profile: ${name}`);
+    const manifest = JSON.parse(await readFile(resolvedSource, 'utf8'));
+    const dsh = record(manifest.dsh);
+    const bundle = record(dsh?.bundle);
+    const dist = record(manifest.dist);
+    const peers = record(manifest.peerDependencies);
+    const engines = record(manifest.engines);
+    const scripts = record(manifest.scripts);
+    const peerDsh = string(peers?.['@deepseek-ai/dsh']);
+    const peerCordis = string(peers?.['@deepseek-ai/cordis']) ?? string(peers?.cordis) ?? string(peers?.['@cordisjs/core']);
+    const engineNode = string(engines?.node);
+    const repository = repositoryValue(manifest.repository);
+    const fileStat = await stat(source);
+    const declaredPatch = string(bundle?.patch);
+    const patchPath = declaredPatch === undefined ? undefined : resolve(dirname(resolvedSource), declaredPatch);
+    if (patchPath !== undefined && !within(profileRoot, patchPath))
+        throw new Error(`Bundle patch resolves outside the selected profile: ${name}`);
+    const safePatch = patchPath === undefined ? undefined : await realpath(patchPath).then((resolvedPatch) => {
+        if (!within(profileRoot, resolvedPatch))
+            throw new Error(`Bundle patch resolves outside the selected profile: ${name}`);
+        return resolvedPatch;
+    }).catch((error) => {
+        if (error.code === 'ENOENT')
+            return patchPath;
+        throw error;
+    });
+    return {
+        name,
+        ...(requestedSpec === undefined ? {} : { requestedSpec }),
+        ...(string(manifest.version) === undefined ? {} : { installedVersion: string(manifest.version) }),
+        packageJsonSource: source,
+        ...(safePatch === undefined ? {} : { bundlePatch: safePatch }),
+        ...(repository === undefined ? {} : { repository }),
+        ...(gitRefFrom(repository, manifest) === undefined ? {} : { gitRef: gitRefFrom(repository, manifest) }),
+        ...(string(dist?.integrity) === undefined ? {} : { integrity: string(dist?.integrity) }),
+        modifiedAt: fileStat.mtime.toISOString(),
+        ...(Array.isArray(manifest.os) ? { platform: manifest.os.filter((item) => typeof item === 'string') } : {}),
+        ...(peerDsh === undefined ? {} : { peerDsh }),
+        ...(peerCordis === undefined ? {} : { peerCordis }),
+        ...(engineNode === undefined ? {} : { engineNode }),
+        ...(scripts === undefined ? {} : { lifecycleScripts: ['preinstall', 'install', 'postinstall', 'prepare'].filter((key) => typeof scripts[key] === 'string') })
+    };
+}

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.' };