@dzhechkov/harness-core 0.8.32 → 0.8.33

package/src/packed-install-smoke.ts

@@ -0,0 +1,273 @@
+/**
+ * Packed-install smoke — feature `publish-sibling-drift-gate`, ADR-001 (Decision 2).
+ *
+ * `dz release`'s existing smoke gate boots a package's bin straight from the WORKSPACE — its
+ * sibling `workspace:*` deps resolve via pnpm's workspace links, never through a real install.
+ * That makes the whole class of "published tarball missing an export" incidents invisible by
+ * construction (Alternative Б1, rejected). This module plans and judges the alternative
+ * (Б2, accepted): pack every package in the batch, `npm install` the resulting tarballs together
+ * into a CLEAN directory — siblings OUTSIDE the batch resolve from the registry, exactly like a
+ * fresh user's install — then boot every bin with `--version` and require exit 0 AND non-empty
+ * stdout (the "publisher output is not a receipt" lesson: a bin that boots but prints nothing has
+ * not proven it works).
+ *
+ * Pure by construction (NFR-2): `planPackedInstallSmoke` only builds command STRINGS from
+ * injected package/bin facts and paths — it never spawns anything. `judgePackedInstallSmoke`
+ * only classifies injected execution records. The CLI (`cmdPublish`, `cmdRelease`) is the single
+ * executor, sharing this same plan/judge pair so both doors apply the identical rule.
+ *
+ * @packageDocumentation
+ */
+
+import { join } from 'node:path';
+
+export type PackedInstallStepKind = 'pack' | 'install' | 'bin-exists' | 'bin-version';
+
+/** One concrete step — data, not action (mirrors release.ts's GateStep idiom). */
+export interface PackedInstallStep {
+  readonly id: string;
+  readonly kind: PackedInstallStepKind;
+  readonly cmd: string;
+  readonly cwd: string;
+  readonly timeoutMs: number;
+  /** Present for 'pack' and 'bin-version' steps. */
+  readonly pkg?: string;
+  /** Present for 'bin-version' steps only. */
+  readonly binName?: string;
+}
+
+export interface PackedInstallPackageSpec {
+  readonly name: string;
+  /** Absolute source directory to `npm pack`. */
+  readonly dir: string;
+  readonly version: string;
+}
+
+export interface PackedInstallBinSpec {
+  readonly pkg: string;
+  readonly binName: string;
+  /** Path to the executable relative to the package's OWN directory (as it ships), e.g. "dist/bin.js". */
+  readonly relPath: string;
+}
+
+export interface PlanPackedInstallSmokeOptions {
+  /** Every package to pack — the full batch, since a bin-less sibling can still be a dependency. */
+  readonly packages: readonly PackedInstallPackageSpec[];
+  /** Bins to boot after install (typically the subset of `packages` that declare one). */
+  readonly bins: readonly PackedInstallBinSpec[];
+  /** Directory `npm pack --pack-destination` writes tarballs into. */
+  readonly packDir: string;
+  /** Fresh, empty directory `npm install` runs in — outside-batch siblings resolve from the registry here. */
+  readonly installDir: string;
+  readonly packTimeoutMs?: number;
+  readonly installTimeoutMs?: number;
+  readonly versionTimeoutMs?: number;
+  /**
+   * AM-1 (feature publish-sibling-drift-gate): the caller (`publishPackages`'s `packedTransport`)
+   * already packed each artifact ONCE, post-bump — a SECOND, different `npm pack` here would smoke
+   * bytes other than the ones about to be published, reintroducing the exact defect this amendment
+   * closes. `true` skips planning any 'pack' step; `tarballs` is still populated with the SAME
+   * deterministic `packedTarballName(name, version)` path under `packDir` — the caller is
+   * responsible for having written the tarball there already (`packages[].dir` is unused in this
+   * mode and may be any string).
+   */
+  readonly skipPack?: boolean;
+}
+
+export interface PackedInstallPlan {
+  readonly steps: readonly PackedInstallStep[];
+  /** Absolute tarball paths the install step references, in package order. */
+  readonly tarballs: readonly string[];
+}
+
+const DEFAULT_PACK_TIMEOUT_MS = 60_000;
+const DEFAULT_INSTALL_TIMEOUT_MS = 180_000;
+const DEFAULT_VERSION_TIMEOUT_MS = 30_000;
+
+/** Mirror npm's own tarball naming: `@scope/name@1.2.3` -> `scope-name-1.2.3.tgz`. */
+export function packedTarballName(name: string, version: string): string {
+  return `${name.replace(/^@/, '').replace(/\//g, '-')}-${version}.tgz`;
+}
+
+export function planPackedInstallSmoke(opts: PlanPackedInstallSmokeOptions): PackedInstallPlan {
+  const packTimeoutMs = opts.packTimeoutMs ?? DEFAULT_PACK_TIMEOUT_MS;
+  const installTimeoutMs = opts.installTimeoutMs ?? DEFAULT_INSTALL_TIMEOUT_MS;
+  const versionTimeoutMs = opts.versionTimeoutMs ?? DEFAULT_VERSION_TIMEOUT_MS;
+
+  const steps: PackedInstallStep[] = [];
+  const tarballs: string[] = [];
+
+  for (const pkg of opts.packages) {
+    const tgz = join(opts.packDir, packedTarballName(pkg.name, pkg.version));
+    tarballs.push(tgz);
+    if (opts.skipPack === true) continue; // AM-1: already packed by the caller — see skipPack's doc
+    steps.push({
+      id: `pack:${pkg.name}`,
+      kind: 'pack',
+      cmd: `npm pack ${JSON.stringify(pkg.dir)} --pack-destination ${JSON.stringify(opts.packDir)}`,
+      cwd: pkg.dir,
+      timeoutMs: packTimeoutMs,
+      pkg: pkg.name,
+    });
+  }
+
+  if (tarballs.length > 0) {
+    steps.push({
+      id: 'install',
+      kind: 'install',
+      cmd: `npm install ${tarballs.map((t) => JSON.stringify(t)).join(' ')} --no-audit --no-fund`,
+      cwd: opts.installDir,
+      timeoutMs: installTimeoutMs,
+    });
+  }
+
+  for (const bin of opts.bins) {
+    const absBinPath = join(opts.installDir, 'node_modules', bin.pkg, bin.relPath);
+    // AM-8: a manifest can declare a `bin` whose target file does not exist (never built, moved,
+    // typo'd) — the OLD `cli.ts` bin-collection step silently DROPPED such a bin before this
+    // amendment, which read as "n/a: nothing to smoke" (or even skipped the whole gate when it
+    // was the batch's only bin). `test -f` is a dedicated, portable existence probe RUN AFTER THE
+    // REAL INSTALL — pass/fail here is judged into a specific, honest message
+    // ("declared bin missing after packed install") instead of being folded into whatever
+    // `node <bin> --version` happens to print for a missing file (a generic MODULE_NOT_FOUND).
+    steps.push({
+      id: `bin-exists:${bin.pkg}:${bin.binName}`,
+      kind: 'bin-exists',
+      cmd: `test -f ${JSON.stringify(absBinPath)}`,
+      cwd: opts.installDir,
+      timeoutMs: versionTimeoutMs,
+      pkg: bin.pkg,
+      binName: bin.binName,
+    });
+    steps.push({
+      id: `bin:${bin.pkg}:${bin.binName}`,
+      kind: 'bin-version',
+      cmd: `node ${JSON.stringify(absBinPath)} --version`,
+      cwd: opts.installDir,
+      timeoutMs: versionTimeoutMs,
+      pkg: bin.pkg,
+      binName: bin.binName,
+    });
+  }
+
+  return { steps, tarballs };
+}
+
+export interface PackedInstallExecution {
+  readonly stepId: string;
+  readonly exitCode: number;
+  readonly stdout: string;
+  readonly stderr: string;
+  readonly timedOut?: boolean;
+}
+
+export interface PackedInstallBinVerdict {
+  readonly pkg: string;
+  readonly binName: string;
+  readonly ok: boolean;
+  readonly stdout: string;
+  /** First 3 non-empty lines of stderr (falling back to stdout), present only when !ok. */
+  readonly detail?: string;
+}
+
+export interface PackedInstallVerdict {
+  readonly ok: boolean;
+  readonly packOk: boolean;
+  readonly installOk: boolean;
+  /** First failure's detail, from whichever of pack/install failed first. */
+  readonly failureDetail?: string;
+  readonly bins: readonly PackedInstallBinVerdict[];
+}
+
+/**
+ * First 3 lines (FR-3), EXCEPT when they are pure source context. MEASURED 2026-09-13 reproducing
+ * the exact incident this gate targets — a bin whose `import` names a missing export — Node
+ * prints the location, the offending source line and a caret BEFORE the actual
+ * `SyntaxError: … does not provide an export named …` message (identically for a plain uncaught
+ * `throw`: file:line / code / `^` / blank / `Error: …`). A literal first-3-lines slice therefore
+ * shows three lines of code and caret marks and never the reason — useless for the incident it
+ * exists to surface. When stderr contains a line that LOOKS like an error header
+ * (`SomethingError: …` or bare `Error: …`), the snippet starts there instead.
+ */
+function firstLines(text: string, n: number): string {
+  const lines = text.split(/\r?\n/).map((l) => l.trim()).filter((l) => l.length > 0);
+  if (lines.length === 0) return '(no output)';
+  const errorHeaderAt = lines.findIndex((l) => /^[A-Za-z][A-Za-z0-9_]*Error:|^Error\b/.test(l));
+  const start = errorHeaderAt >= 0 ? errorHeaderAt : 0;
+  return lines.slice(start, start + n).join(' | ');
+}
+
+const NO_EXECUTION_RECORD = '(no execution record — under-executed plan)';
+
+function stepOk(exec: PackedInstallExecution | undefined): boolean {
+  return exec !== undefined && exec.timedOut !== true && exec.exitCode === 0;
+}
+
+function stepDetail(exec: PackedInstallExecution | undefined): string {
+  if (exec === undefined) return NO_EXECUTION_RECORD;
+  if (exec.timedOut === true) return 'timed out';
+  return firstLines(exec.stderr || exec.stdout, 3);
+}
+
+/**
+ * Classify a plan's executions. `plan` may be the `{ steps }` half of {@link PackedInstallPlan}.
+ * A missing execution for a planned step is a FAILURE (an under-executed plan cannot pass) —
+ * never treated as "nothing to judge, so it passed".
+ */
+export function judgePackedInstallSmoke(
+  plan: { readonly steps: readonly PackedInstallStep[] },
+  executions: readonly PackedInstallExecution[],
+): PackedInstallVerdict {
+  const byId = new Map(executions.map((e) => [e.stepId, e]));
+
+  let packOk = true;
+  let failureDetail: string | undefined;
+  for (const step of plan.steps.filter((s) => s.kind === 'pack')) {
+    const exec = byId.get(step.id);
+    if (!stepOk(exec)) {
+      packOk = false;
+      failureDetail ??= stepDetail(exec);
+    }
+  }
+
+  let installOk = true;
+  const installStep = plan.steps.find((s) => s.kind === 'install');
+  if (installStep !== undefined) {
+    const exec = byId.get(installStep.id);
+    if (!stepOk(exec)) {
+      installOk = false;
+      failureDetail ??= stepDetail(exec);
+    }
+  }
+
+  const bins: PackedInstallBinVerdict[] = plan.steps
+    .filter((s) => s.kind === 'bin-version')
+    .map((step) => {
+      const exec = byId.get(step.id);
+      if (!packOk || !installOk) {
+        // Pack/install already failed for the whole batch — the generic pack/install detail is
+        // more informative than a bin-specific message about a step that never had a chance to run.
+        return { pkg: step.pkg!, binName: step.binName!, ok: false, stdout: '', detail: stepDetail(exec) };
+      }
+      // AM-8: a declared bin missing from the REAL post-install tree is its own failure class —
+      // checked and reported BEFORE the generic stdout rule below, whose message ("empty stdout")
+      // would otherwise misdescribe a file that was never there to boot at all.
+      const existsStep = plan.steps.find((s) => s.kind === 'bin-exists' && s.pkg === step.pkg && s.binName === step.binName);
+      if (existsStep !== undefined && !stepOk(byId.get(existsStep.id))) {
+        return { pkg: step.pkg!, binName: step.binName!, ok: false, stdout: '', detail: 'declared bin missing after packed install' };
+      }
+      // FR-3 / lesson "publisher output is not a receipt": exit 0 alone is not enough — the
+      // version output must be non-empty, or a bin that silently no-ops would read as healthy.
+      const ok = stepOk(exec) && (exec?.stdout ?? '').trim() !== '';
+      return {
+        pkg: step.pkg!,
+        binName: step.binName!,
+        ok,
+        stdout: exec?.stdout ?? '',
+        ...(ok ? {} : { detail: exec !== undefined && stepOk(exec) ? '(exit 0 but empty stdout)' : stepDetail(exec) }),
+      };
+    });
+
+  const ok = packOk && installOk && bins.every((b) => b.ok);
+  return { ok, packOk, installOk, ...(failureDetail !== undefined ? { failureDetail } : {}), bins };
+}

package/src/publish-sibling-drift.ts

@@ -0,0 +1,293 @@
+/**
+ * Sibling-drift gate — feature `publish-sibling-drift-gate`, ADR-001 (Decision 1).
+ *
+ * `rewriteWorkspaceSpecs` (publish.ts) pins a sibling `workspace:^`/`workspace:~`/`workspace:*`
+ * dependency to the EXACT version currently on disk. That version may be published on the
+ * registry carrying an OLDER build than the workspace — the sibling changed without a version
+ * bump. The pinned range then resolves at install time to a package that does not match the
+ * workspace's current behavior, and a fresh `npm install` reproduces whatever regressed.
+ *
+ * Detection (ADR-001, Decision 1, alternative А3 — accepted): hash every file under the
+ * published tarball's `dist/**` plus its `package.json` (with `version`/`gitHead`/`_*` fields
+ * stripped, since those legitimately differ between the registry copy and the workspace copy),
+ * and compare against the same hash of the workspace copy. Any difference is drift. A published
+ * `dist/index.js` missing an export the workspace's `dist/index.js` declares is surfaced as a
+ * SECOND, more readable signal (`missingExports`) — the exact shape of the 2026-09-13 incident
+ * ("does not provide an export named …") — but the hash comparison is the load-bearing check:
+ * it also catches behavior changes that keep every export name intact.
+ *
+ * Network access is NOT this module's concern (NFR-2: pure, no network, fixture-testable):
+ * `fetchPublished` is injected. The CLI implementation packs the sibling from the registry via
+ * `npm pack <name>@<version>` into a temp dir; tests inject a local directory. A fetch that
+ * returns `null` (offline, 404, timeout) is reported as `'unavailable'` — never silently treated
+ * as `'same'` (the "a gate that infers a pass from silence breaks on the next failure path"
+ * lesson): the caller decides whether `'unavailable'` blocks or is overridden.
+ *
+ * @packageDocumentation
+ */
+
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { join, relative } from 'node:path';
+
+export type SiblingDriftStatus = 'same' | 'drift' | 'unavailable';
+
+export interface SiblingDriftResult {
+  readonly name: string;
+  readonly version: string;
+  readonly status: SiblingDriftStatus;
+  /** Relative paths (dist/** or package.json) whose hash differs, or is present on only one side. */
+  readonly changedFiles: readonly string[];
+  /** Export names the workspace's dist/index.js declares that the published one lacks (А2, secondary signal). */
+  readonly missingExports: readonly string[];
+  /** Present only when status === 'unavailable'. */
+  readonly reason?: string;
+}
+
+export interface FetchedPublished {
+  /** Directory holding the extracted published tarball (contains dist/, package.json). */
+  readonly dir: string;
+}
+
+/** Fetch the published build of `name@version`. `null` = unavailable (network/404/timeout). */
+export type FetchPublished = (name: string, version: string) => FetchedPublished | null;
+
+export interface DetectSiblingDriftOptions {
+  readonly dependencies: Record<string, string> | undefined;
+  /** pnpm rewrites `workspace:` in peerDependencies too (mirrors findUnpublishedWorkspaceFloors). */
+  readonly peerDependencies?: Record<string, string> | undefined;
+  /** AM-3: ships and pins exactly like `dependencies` — checked the same way. */
+  readonly optionalDependencies?: Record<string, string> | undefined;
+  /** name -> version on DISK, for every package in the workspace. */
+  readonly workspaceVersions: ReadonlyMap<string, string>;
+  /** name -> absolute package dir on disk, for every package in the workspace. */
+  readonly workspaceDirs: ReadonlyMap<string, string>;
+  /** Names being published in THIS batch — they publish fresh, so drift cannot be measured against them. */
+  readonly batch: ReadonlySet<string>;
+  readonly fetchPublished: FetchPublished;
+}
+
+function listFilesRecursive(root: string, dir: string): string[] {
+  if (!existsSync(dir)) return [];
+  const out: string[] = [];
+  for (const entry of readdirSync(dir).sort()) {
+    const abs = join(dir, entry);
+    const st = statSync(abs);
+    if (st.isDirectory()) out.push(...listFilesRecursive(root, abs));
+    else out.push(relative(root, abs));
+  }
+  return out;
+}
+
+function sha256(data: string | Buffer): string {
+  return createHash('sha256').update(data).digest('hex');
+}
+
+/**
+ * package.json PARSED and validated. `null` (never `undefined`) means "this side cannot be built
+ * at all" — AM-3: a missing or unparseable manifest on EITHER side must surface as `unavailable`,
+ * never as an empty/omitted comparison field that a hash-mismatch loop could silently read as
+ * "nothing differs here".
+ */
+function readManifest(dir: string): Record<string, unknown> | null {
+  const p = join(dir, 'package.json');
+  if (!existsSync(p)) return null;
+  try {
+    const raw = JSON.parse(readFileSync(p, 'utf-8'));
+    return raw !== null && typeof raw === 'object' && !Array.isArray(raw) ? (raw as Record<string, unknown>) : null;
+  } catch {
+    return null;
+  }
+}
+
+/** package.json normalized for comparison: strip fields that legitimately differ (version, gitHead, npm-internal `_*`). */
+function normalizedPackageJsonText(raw: Record<string, unknown>): string {
+  // Lead edit after the live dry-run on the hub (2026-09-13 10:40): the packer strips
+  // `scripts.prepublishOnly`, drops devDependencies/publishConfig and rewrites `workspace:` specs to
+  // pinned versions — every freshly published sibling read as "1 file drifted". Compare only what
+  // shapes the SHIPPED behavior: entry points, bins, files, engines, and dependency NAMES (values
+  // are the workspace-floor preflight's business, not this gate's).
+  //
+  // AM-4: `imports`/`browser`/`sideEffects`/`man` added — each one changes what a consumer actually
+  // resolves or ships, exactly like `main`/`exports`/`bin` already did; omitting them was a real gap
+  // the round-1 review named (finding 4), not a stylistic nicety.
+  const SHIPPING_FIELDS = [
+    'name', 'type', 'main', 'module', 'types', 'exports', 'imports', 'browser', 'sideEffects', 'man',
+    'bin', 'files', 'engines', 'os', 'cpu',
+  ];
+  const DEP_TABLES = ['dependencies', 'peerDependencies', 'optionalDependencies'];
+  const kept: Record<string, unknown> = {};
+  for (const key of SHIPPING_FIELDS) if (key in raw) kept[key] = raw[key];
+  for (const key of DEP_TABLES) {
+    const table = raw[key];
+    if (table !== null && typeof table === 'object') kept[key] = Object.keys(table as Record<string, unknown>).sort();
+  }
+  return JSON.stringify(kept);
+}
+
+/** Every relative path (from `dir`) that a `bin` field in a parsed manifest resolves to. */
+function binPaths(raw: Record<string, unknown>): string[] {
+  const bin = raw['bin'];
+  if (typeof bin === 'string') return [bin.replace(/^\.\//, '')];
+  if (bin !== null && typeof bin === 'object' && !Array.isArray(bin)) {
+    return Object.values(bin as Record<string, unknown>)
+      .filter((v): v is string => typeof v === 'string')
+      .map((v) => v.replace(/^\.\//, ''));
+  }
+  return [];
+}
+
+/**
+ * AM-4: the round-1 gate hashed only `dist/**` — a changed bin script, template, or other
+ * top-level asset that ships (declared in `package.json#files`, or the `bin` target itself) was
+ * invisible to the drift check even though npm ships it byte-for-byte. This is a documented,
+ * honest APPROXIMATION of "the whole tarball inventory" (the literal ADR wording), not a full
+ * re-implementation of npm's pack-time file-inclusion rules (`.npmignore`, default excludes,
+ * nested `.gitignore`): it walks `dist/**` (unconditional — the common case) plus every path
+ * named in `files` (directories walked recursively, files hashed directly) plus every resolved
+ * `bin` target, deduplicated. A package with no `files` field declared keeps exactly the
+ * pre-amendment `dist/**`-only scope, named here rather than silently pretended-away.
+ */
+function shippedInventoryDirs(dir: string, raw: Record<string, unknown>): string[] {
+  const rels = new Set<string>(['dist']);
+  const files = raw['files'];
+  if (Array.isArray(files)) {
+    for (const entry of files) {
+      if (typeof entry === 'string' && entry.trim() !== '') rels.add(entry.replace(/^\.\//, '').replace(/\/+$/, ''));
+    }
+  }
+  for (const bin of binPaths(raw)) rels.add(bin);
+  return [...rels].filter((rel) => existsSync(join(dir, rel)));
+}
+
+/** Hash the shipped inventory (AM-4) plus the normalized package.json, keyed by a stable relative path. */
+function hashTree(dir: string, manifest: Record<string, unknown>): Map<string, string> {
+  const map = new Map<string, string>();
+  for (const rel of shippedInventoryDirs(dir, manifest)) {
+    const abs = join(dir, rel);
+    if (statSync(abs).isDirectory()) {
+      for (const sub of listFilesRecursive(abs, abs)) map.set(join(rel, sub), sha256(readFileSync(join(abs, sub))));
+    } else {
+      map.set(rel, sha256(readFileSync(abs)));
+    }
+  }
+  map.set('package.json', sha256(normalizedPackageJsonText(manifest)));
+  return map;
+}
+
+function extractExportNames(source: string): Set<string> {
+  const names = new Set<string>();
+  for (const m of source.matchAll(/export\s+(?:const|function|class|async\s+function)\s+([A-Za-z0-9_$]+)/g)) {
+    names.add(m[1]!);
+  }
+  for (const m of source.matchAll(/export\s*\{([^}]*)\}/g)) {
+    for (const part of m[1]!.split(',')) {
+      const name = part.trim().split(/\s+as\s+/).pop()?.trim();
+      if (name) names.add(name);
+    }
+  }
+  return names;
+}
+
+/** А2 (ADR-001, rejected as the sole signal, kept as a readable second signal). */
+function missingExportNames(publishedDir: string, workspaceDir: string): string[] {
+  const pubIndex = join(publishedDir, 'dist', 'index.js');
+  const wsIndex = join(workspaceDir, 'dist', 'index.js');
+  if (!existsSync(pubIndex) || !existsSync(wsIndex)) return [];
+  const pubExports = extractExportNames(readFileSync(pubIndex, 'utf-8'));
+  const wsExports = extractExportNames(readFileSync(wsIndex, 'utf-8'));
+  return [...wsExports].filter((n) => !pubExports.has(n)).sort();
+}
+
+/**
+ * For every `workspace:`-declared dependency of a package that is NOT part of `batch` (i.e. will
+ * be pinned to whatever is already on the registry, not published fresh in this run), compare the
+ * build that will be pinned against the workspace copy. Pure: all IO (fetch, fs) is either
+ * injected or scoped to reading local dist/package.json files — no network call is made here.
+ */
+export function detectSiblingDrift(opts: DetectSiblingDriftOptions): SiblingDriftResult[] {
+  const results: SiblingDriftResult[] = [];
+  const seen = new Set<string>();
+  // AM-3: `optionalDependencies` ships and pins EXACTLY like `dependencies`/`peerDependencies` —
+  // checking only the first two let a stale optional sibling through untouched (round-1 finding 3).
+  const entries = [
+    ...Object.entries(opts.dependencies ?? {}),
+    ...Object.entries(opts.peerDependencies ?? {}),
+    ...Object.entries(opts.optionalDependencies ?? {}),
+  ];
+  for (const [dep, spec] of entries) {
+    if (!String(spec).startsWith('workspace:')) continue;
+    if (seen.has(dep)) continue;
+    seen.add(dep);
+    if (opts.batch.has(dep)) continue; // publishes fresh in this batch — nothing stale to drift from
+    const version = opts.workspaceVersions.get(dep);
+    const workspaceDir = opts.workspaceDirs.get(dep);
+    // AM-3: a `workspace:`-spec'd dependency this caller does not recognize used to be silently
+    // SKIPPED — an input this gate cannot build is a HARD gate that cannot say "same", never a
+    // quiet pass-through (round-1 finding 3: pnpm would die packing it anyway; die here, named).
+    if (version === undefined || workspaceDir === undefined) {
+      results.push({
+        name: dep,
+        version: version ?? '(not in workspace)',
+        status: 'unavailable',
+        changedFiles: [],
+        missingExports: [],
+        reason: `${dep} is declared workspace:-protocol but is not a known workspace package`,
+      });
+      continue;
+    }
+
+    const fetched = opts.fetchPublished(dep, version);
+    if (fetched === null) {
+      results.push({
+        name: dep,
+        version,
+        status: 'unavailable',
+        changedFiles: [],
+        missingExports: [],
+        reason: `could not fetch ${dep}@${version} from the registry (network unavailable or the version was not found)`,
+      });
+      continue;
+    }
+
+    // AM-3: a missing/unparseable package.json on EITHER side must not silently drop out of the
+    // comparison (the old `hashTree` simply omitted the key, which — with an empty/matching
+    // `dist/**` on both sides — could report `same` about an input that was never actually read).
+    const publishedManifest = readManifest(fetched.dir);
+    const workspaceManifest = readManifest(workspaceDir);
+    if (publishedManifest === null || workspaceManifest === null) {
+      const side = publishedManifest === null ? 'the published tarball' : 'the workspace copy';
+      results.push({
+        name: dep,
+        version,
+        status: 'unavailable',
+        changedFiles: [],
+        missingExports: [],
+        reason: `${dep}@${version}: package.json in ${side} is missing or not valid JSON — cannot compare`,
+      });
+      continue;
+    }
+
+    const publishedHashes = hashTree(fetched.dir, publishedManifest);
+    const workspaceHashes = hashTree(workspaceDir, workspaceManifest);
+    const allKeys = new Set<string>([...publishedHashes.keys(), ...workspaceHashes.keys()]);
+    const changed: string[] = [];
+    for (const key of allKeys) {
+      if (publishedHashes.get(key) !== workspaceHashes.get(key)) changed.push(key);
+    }
+    changed.sort();
+
+    if (changed.length === 0) {
+      results.push({ name: dep, version, status: 'same', changedFiles: [], missingExports: [] });
+    } else {
+      results.push({
+        name: dep,
+        version,
+        status: 'drift',
+        changedFiles: changed,
+        missingExports: missingExportNames(fetched.dir, workspaceDir),
+      });
+    }
+  }
+  return results;
+}