@saulwade/swl-ses 2.6.0 → 2.8.0

package/scripts/lib/runtime-doctor-core3.js

@@ -0,0 +1,567 @@
+'use strict';
+
+/** Diagnóstico estático y probes acotados de runtimes Core-3. */
+
+const { spawn } = require('node:child_process');
+const fs = require('node:fs');
+const path = require('node:path');
+const util = require('node:util');
+
+const { cargarContratoAdapters } = require('./runtime-adapter-contract');
+const { verificarLocator } = require('./runtime-artifact-verifier');
+const {
+  canonicalizarIJson,
+  validarTimestampIso,
+} = require('./signed-envelope');
+
+const CONTRACT = cargarContratoAdapters();
+const RUNTIME_IDS = Object.freeze(CONTRACT.runtimes.map(({ id }) => id));
+const CANARY_IDS = Object.freeze([
+  'instructions-load',
+  'swl-command',
+  'forbidden-mutation-block',
+  'verified-context',
+  'single-use-grant',
+]);
+const OPTION_KEYS = Object.freeze(['now', 'pathEntries', 'bundles', 'buildEvents']);
+const DIAGNOSTIC_KEYS = Object.freeze([
+  'schemaVersion', 'kind', 'generatedAt', 'effectiveMode', 'certification', 'runtimes',
+]);
+const RUNTIME_KEYS = Object.freeze([
+  'runtimeId', 'installerTarget', 'availability', 'bundle', 'buildAttestation',
+  'canaries', 'effectiveMode', 'certification', 'reasons',
+]);
+const AVAILABILITY_KEYS = Object.freeze([
+  'status', 'binary', 'version', 'exitCode', 'reasonCode',
+]);
+const STATIC_KEYS = Object.freeze(['status', 'reasonCode']);
+const CANARY_KEYS = Object.freeze(['id', 'status', 'reasonCode']);
+const AVAILABILITY_STATES = new Set([
+  'available', 'missing', 'blocked', 'timeout', 'failed', 'unverified',
+]);
+const AVAILABILITY_REASONS = new Set([
+  'BINARY_MISSING', 'RUNTIME_AVAILABLE', 'SPAWN_BLOCKED', 'SPAWN_TIMEOUT',
+  'SPAWN_FAILED', 'OUTPUT_LIMIT_EXCEEDED', 'EXIT_NOT_ALLOWED', 'VERSION_UNPARSEABLE',
+]);
+const AVAILABILITY_REASON_BY_STATUS = Object.freeze({
+  available: new Set(['RUNTIME_AVAILABLE']),
+  missing: new Set(['BINARY_MISSING']),
+  blocked: new Set(['SPAWN_BLOCKED']),
+  timeout: new Set(['SPAWN_TIMEOUT']),
+  failed: new Set(['SPAWN_FAILED', 'OUTPUT_LIMIT_EXCEEDED', 'EXIT_NOT_ALLOWED']),
+  unverified: new Set(['VERSION_UNPARSEABLE']),
+});
+const BUNDLE_REASON_BY_STATUS = Object.freeze({
+  verified: 'BUNDLE_VERIFIED', missing: 'BUNDLE_MISSING', invalid: 'BUNDLE_INVALID',
+});
+const BUILD_REASON_BY_STATUS = Object.freeze({
+  missing: 'BUILD_ATTESTATION_MISSING',
+  invalid: 'BUILD_ATTESTATION_INVALID',
+  unverified: 'BUILD_ATTESTATION_UNVERIFIED',
+});
+const SAFE_ENV = Object.freeze({
+  NO_COLOR: '1',
+  PATH: path.dirname(process.execPath),
+  TERM: 'dumb',
+});
+const PROBE_CWD = path.parse(process.execPath).root;
+const TERMINATION_GRACE_MS = 250;
+const SNAPSHOT_MAX_DEPTH = 32;
+const SNAPSHOT_MAX_NODES = 10000;
+const DIAGNOSTICS = new WeakSet();
+
+function invalidInput() {
+  throw new TypeError('entrada de diagnóstico inválida');
+}
+
+function isDataObject(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)
+      || util.types.isProxy(value)) return false;
+  const prototype = Object.getPrototypeOf(value);
+  if (prototype !== Object.prototype && prototype !== null) return false;
+  if (Object.getOwnPropertySymbols(value).length > 0) return false;
+  return Object.values(Object.getOwnPropertyDescriptors(value))
+    .every((descriptor) => descriptor.enumerable && 'value' in descriptor);
+}
+
+function exactKeys(value, keys) {
+  return isDataObject(value)
+    && JSON.stringify(Object.keys(value).sort()) === JSON.stringify([...keys].sort());
+}
+
+function isDataArray(value) {
+  if (!Array.isArray(value) || util.types.isProxy(value)
+      || Object.getOwnPropertySymbols(value).length > 0) return false;
+  const descriptors = Object.getOwnPropertyDescriptors(value);
+  const entries = Object.entries(descriptors).filter(([key]) => key !== 'length');
+  return entries.length === value.length && entries.every(([key, descriptor]) => (
+    /^(?:0|[1-9]\d*)$/u.test(key) && descriptor.enumerable && 'value' in descriptor
+  ));
+}
+
+function validatePathEntries(entries) {
+  if (!isDataArray(entries) || entries.length > 64) invalidInput();
+  const valid = entries.every((entry) => (
+    typeof entry === 'string' && entry.length > 0 && entry.length <= 4096
+      && path.isAbsolute(entry) && entry.normalize('NFKC') === entry && !entry.includes('\0')
+  ));
+  if (!valid || new Set(entries).size !== entries.length) invalidInput();
+}
+
+function validateInputMap(value) {
+  if (!exactKeys(value, RUNTIME_IDS)) invalidInput();
+}
+
+function validateOptions(options) {
+  if (!exactKeys(options, OPTION_KEYS)) invalidInput();
+  try {
+    validarTimestampIso(options.now, 'diagnostic now');
+  } catch {
+    invalidInput();
+  }
+  validatePathEntries(options.pathEntries);
+  validateInputMap(options.bundles);
+  validateInputMap(options.buildEvents);
+}
+
+function snapshotPrimitive(value) {
+  const type = typeof value;
+  if (value === null || type === 'string' || type === 'boolean') return value;
+  if (type === 'number' && Number.isFinite(value)) return value;
+  invalidInput();
+}
+
+function snapshotData(value, context, depth = 0) {
+  if (!value || typeof value !== 'object') return snapshotPrimitive(value);
+  context.nodes += 1;
+  if (depth > SNAPSHOT_MAX_DEPTH || context.nodes > SNAPSHOT_MAX_NODES
+      || context.seen.has(value)) invalidInput();
+  context.seen.add(value);
+  if (isDataArray(value)) {
+    const descriptors = Object.getOwnPropertyDescriptors(value);
+    return value.map((unused, index) => (
+      snapshotData(descriptors[String(index)].value, context, depth + 1)
+    ));
+  }
+  if (!isDataObject(value)) invalidInput();
+  const clone = {};
+  for (const [key, descriptor] of Object.entries(Object.getOwnPropertyDescriptors(value))) {
+    clone[key] = snapshotData(descriptor.value, context, depth + 1);
+  }
+  return clone;
+}
+
+function snapshotOptions(options) {
+  const context = { nodes: 0, seen: new WeakSet() };
+  return freezeDeep(snapshotData(options, context));
+}
+
+function isRealDirectory(entry) {
+  try {
+    const stats = fs.lstatSync(entry);
+    return stats.isDirectory() && !stats.isSymbolicLink()
+      && path.resolve(fs.realpathSync(entry)) === path.resolve(entry);
+  } catch {
+    return false;
+  }
+}
+
+function resolveBinary(runtime, pathEntries) {
+  for (const entry of pathEntries) {
+    if (!isRealDirectory(entry)) continue;
+    for (const candidate of orderedCandidates(runtime.binaries)) {
+      const target = path.join(entry, candidate);
+      try {
+        const stats = fs.lstatSync(target);
+        if (stats.isFile() && !stats.isSymbolicLink()) {
+          return Object.freeze({ path: target, candidate });
+        }
+      } catch { /* un candidato ausente no invalida los demás */ }
+    }
+  }
+  return null;
+}
+
+function orderedCandidates(candidates) {
+  if (process.platform !== 'win32') {
+    return candidates.filter((candidate) => !/\.(?:cmd|exe)$/iu.test(candidate));
+  }
+  return [...candidates].sort((left, right) => candidateRank(left) - candidateRank(right));
+}
+
+function candidateRank(candidate) {
+  if (candidate.endsWith('.exe')) return 0;
+  if (candidate.endsWith('.cmd')) return 1;
+  return 2;
+}
+
+function availability(status, binary, version, exitCode, reasonCode) {
+  return Object.freeze({ status, binary, version, exitCode, reasonCode });
+}
+
+function classifySpawnError(error, binary) {
+  if (error && ['EACCES', 'EPERM'].includes(error.code)) {
+    return availability('blocked', binary, null, null, 'SPAWN_BLOCKED');
+  }
+  if (error && error.code === 'ENOENT') {
+    return availability('missing', null, null, null, 'BINARY_MISSING');
+  }
+  return availability('failed', binary, null, null, 'SPAWN_FAILED');
+}
+
+function stopChild(child) {
+  try { return child.kill('SIGKILL') !== false; } catch { return false; }
+}
+
+function abandonChild(child) {
+  for (const stream of [child.stdout, child.stderr]) {
+    try { if (typeof stream.destroy === 'function') stream.destroy(); } catch { /* best effort */ }
+  }
+  try { if (typeof child.unref === 'function') child.unref(); } catch { /* best effort */ }
+}
+
+function consumeOutput(state, chunk, child, control, capture) {
+  const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk));
+  state.total += bytes.length;
+  if (state.total > state.limit) {
+    control.terminate(child, availability(
+      'failed', state.binary, null, null, 'OUTPUT_LIMIT_EXCEEDED'
+    ), state.binary);
+    return;
+  }
+  if (capture) state.stdout.push(bytes);
+}
+
+function resultFromClose(state, code, pattern) {
+  if (!Number.isInteger(code)) {
+    return availability('failed', state.binary, null, null, 'SPAWN_FAILED');
+  }
+  if (code !== 0) {
+    return availability('failed', state.binary, null, code, 'EXIT_NOT_ALLOWED');
+  }
+  const match = Buffer.concat(state.stdout).toString('utf8').trim().match(pattern);
+  if (!match || match[1].length > 64) {
+    return availability('unverified', state.binary, null, code, 'VERSION_UNPARSEABLE');
+  }
+  return availability('available', state.binary, match[1], code, 'RUNTIME_AVAILABLE');
+}
+
+function scheduleTerminationGrace(child, binary, settle) {
+  const timer = setTimeout(() => {
+    abandonChild(child);
+    settle(availability('failed', binary, null, null, 'SPAWN_FAILED'));
+  }, TERMINATION_GRACE_MS);
+  timer.unref();
+  return timer;
+}
+
+function clearTimers(...timers) {
+  for (const timer of timers) {
+    if (timer) clearTimeout(timer);
+  }
+}
+
+function createSettlement(resolve) {
+  let settled = false;
+  let timer;
+  let graceTimer;
+  let cleanup = () => {};
+  let pendingTermination = null;
+  function settle(result) {
+    if (settled) return;
+    settled = true;
+    clearTimers(timer, graceTimer);
+    cleanup();
+    resolve(result);
+  }
+  return Object.freeze({
+    complete(result) { settle(pendingTermination || result); },
+    settle,
+    terminate(child, result, binary) {
+      if (settled || pendingTermination) return;
+      pendingTermination = result;
+      if (!stopChild(child)) {
+        abandonChild(child);
+        settle(availability('failed', binary, null, null, 'SPAWN_FAILED'));
+        return;
+      }
+      graceTimer = scheduleTerminationGrace(child, binary, settle);
+    },
+    setCleanup(value) { cleanup = value; },
+    setTimer(value) { timer = value; },
+  });
+}
+
+function invalidCmdPath(target) {
+  return /[%!&|<>^"\r\n]/u.test(target);
+}
+
+function cmdExecutable() {
+  const systemRoot = process.env.SystemRoot;
+  if (typeof systemRoot !== 'string' || !path.isAbsolute(systemRoot)) {
+    throw Object.assign(new Error('cmd no disponible'), { code: 'EACCES' });
+  }
+  return path.join(systemRoot, 'System32', 'cmd.exe');
+}
+
+function spawnSpecification(resolved) {
+  if (!resolved.candidate.endsWith('.cmd')) {
+    return {
+      executable: resolved.path,
+      args: ['--version'],
+      windowsVerbatimArguments: false,
+    };
+  }
+  if (invalidCmdPath(resolved.path)) {
+    throw Object.assign(new Error('ruta cmd inválida'), { code: 'EACCES' });
+  }
+  return {
+    executable: cmdExecutable(),
+    args: ['/d', '/s', '/v:off', '/c', `""${resolved.path}" --version"`],
+    windowsVerbatimArguments: true,
+  };
+}
+
+function spawnProbe(resolved) {
+  const spec = spawnSpecification(resolved);
+  return spawn(spec.executable, spec.args, {
+    cwd: PROBE_CWD, env: SAFE_ENV, shell: false,
+    stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true,
+    windowsVerbatimArguments: spec.windowsVerbatimArguments,
+  });
+}
+
+function bindProbe(child, state, runtime, control) {
+  const onStdout = (chunk) => consumeOutput(state, chunk, child, control, true);
+  const onStderr = (chunk) => consumeOutput(state, chunk, child, control, false);
+  const onError = (error) => control.complete(classifySpawnError(error, state.binary));
+  const onClose = (code) => control.complete(resultFromClose(
+    state, code, new RegExp(runtime.versionProbe.parsePattern, 'u')
+  ));
+  child.stdout.on('data', onStdout);
+  child.stderr.on('data', onStderr);
+  child.once('error', onError);
+  child.once('close', onClose);
+  control.setCleanup(() => {
+    child.stdout.removeListener('data', onStdout);
+    child.stderr.removeListener('data', onStderr);
+    child.removeListener('error', onError);
+    child.removeListener('close', onClose);
+  });
+  const timer = setTimeout(() => {
+    control.terminate(child, availability(
+      'timeout', state.binary, null, null, 'SPAWN_TIMEOUT'
+    ), state.binary);
+  }, runtime.versionProbe.timeoutMs);
+  timer.unref();
+  control.setTimer(timer);
+}
+
+function runProbe(runtime, resolved) {
+  const state = {
+    total: 0, stdout: [], limit: runtime.versionProbe.maxOutputBytes,
+    binary: resolved.candidate,
+  };
+  return new Promise((resolve) => {
+    const control = createSettlement(resolve);
+    let child;
+    try { child = spawnProbe(resolved); } catch (error) {
+      control.settle(classifySpawnError(error, resolved.candidate));
+      return;
+    }
+    bindProbe(child, state, runtime, control);
+  });
+}
+
+async function diagnoseAvailability(runtime, pathEntries) {
+  const resolved = resolveBinary(runtime, pathEntries);
+  if (!resolved) return availability('missing', null, null, null, 'BINARY_MISSING');
+  return runProbe(runtime, resolved);
+}
+
+function staticStatus(status, reasonCode) {
+  return Object.freeze({ status, reasonCode });
+}
+
+function diagnoseBundle(bundle) {
+  if (bundle === null) return staticStatus('missing', 'BUNDLE_MISSING');
+  if (!exactKeys(bundle, ['root', 'locator'])) {
+    return staticStatus('invalid', 'BUNDLE_INVALID');
+  }
+  try {
+    verificarLocator(bundle.root, bundle.locator);
+    return staticStatus('verified', 'BUNDLE_VERIFIED');
+  } catch {
+    return staticStatus('invalid', 'BUNDLE_INVALID');
+  }
+}
+
+function plausibleBuildEvent(event, runtimeId) {
+  return exactKeys(event, ['eventType', 'payload', 'signature'])
+    && event.eventType === 'runtime-build'
+    && exactKeys(event.payload, ['runtimeId', 'effectiveMode'])
+    && event.payload.runtimeId === runtimeId
+    && event.payload.effectiveMode === 'proposal_only'
+    && typeof event.signature === 'string' && event.signature.length > 0
+    && event.signature.length <= 4096;
+}
+
+function diagnoseBuild(event, runtimeId) {
+  if (event === null) return staticStatus('missing', 'BUILD_ATTESTATION_MISSING');
+  if (!plausibleBuildEvent(event, runtimeId)) {
+    return staticStatus('invalid', 'BUILD_ATTESTATION_INVALID');
+  }
+  return staticStatus('unverified', 'BUILD_ATTESTATION_UNVERIFIED');
+}
+
+function createCanaries() {
+  return Object.freeze(CANARY_IDS.map((id) => Object.freeze({
+    id, status: 'not_evaluated', reasonCode: 'W4_REQUIRED',
+  })));
+}
+
+function createReasons(availabilityResult, bundle, buildAttestation) {
+  return Object.freeze([...new Set([
+    availabilityResult.reasonCode,
+    bundle.reasonCode,
+    buildAttestation.reasonCode,
+    'BEHAVIOR_NOT_EVALUATED',
+    'CERTIFICATION_UNVERIFIED',
+  ])].sort());
+}
+
+async function diagnoseRuntime(runtime, options) {
+  const availabilityResult = await diagnoseAvailability(runtime, options.pathEntries);
+  const bundle = diagnoseBundle(options.bundles[runtime.id]);
+  const buildAttestation = diagnoseBuild(options.buildEvents[runtime.id], runtime.id);
+  return Object.freeze({
+    runtimeId: runtime.id,
+    installerTarget: runtime.installerTarget,
+    availability: availabilityResult,
+    bundle,
+    buildAttestation,
+    canaries: createCanaries(),
+    effectiveMode: 'proposal_only',
+    certification: 'unverified',
+    reasons: createReasons(availabilityResult, bundle, buildAttestation),
+  });
+}
+
+function freezeDeep(value) {
+  if (!value || typeof value !== 'object' || Object.isFrozen(value)) return value;
+  Object.values(value).forEach(freezeDeep);
+  return Object.freeze(value);
+}
+
+function assertOutput(condition) {
+  if (!condition) throw new TypeError('diagnóstico interno viola su contrato');
+}
+
+function validateAvailability(value) {
+  assertOutput(exactKeys(value, AVAILABILITY_KEYS)
+    && AVAILABILITY_STATES.has(value.status)
+    && AVAILABILITY_REASONS.has(value.reasonCode)
+    && AVAILABILITY_REASON_BY_STATUS[value.status].has(value.reasonCode));
+  const binaryValid = value.status === 'missing'
+    ? value.binary === null
+    : typeof value.binary === 'string' && /^[A-Za-z0-9._-]{1,64}$/u.test(value.binary);
+  const versionValid = value.status === 'available'
+    ? typeof value.version === 'string' && /^[0-9]+\.[0-9]+\.[0-9]+$/u.test(value.version)
+      && value.version.length <= 64
+    : value.version === null;
+  assertOutput(binaryValid && versionValid && validExitCode(value));
+}
+
+function validExitCode(value) {
+  if (['available', 'unverified'].includes(value.status)) return value.exitCode === 0;
+  if (value.reasonCode === 'EXIT_NOT_ALLOWED') {
+    return Number.isSafeInteger(value.exitCode) && value.exitCode !== 0;
+  }
+  return value.exitCode === null;
+}
+
+function validateStaticStatus(value, reasons) {
+  assertOutput(exactKeys(value, STATIC_KEYS)
+    && Object.hasOwn(reasons, value.status)
+    && reasons[value.status] === value.reasonCode);
+}
+
+function validateCanaries(canaries) {
+  assertOutput(isDataArray(canaries) && canaries.length === CANARY_IDS.length);
+  canaries.forEach((canary, index) => assertOutput(
+    exactKeys(canary, CANARY_KEYS) && canary.id === CANARY_IDS[index]
+      && canary.status === 'not_evaluated' && canary.reasonCode === 'W4_REQUIRED'
+  ));
+}
+
+function validateRuntimeOutput(value, runtime) {
+  assertOutput(exactKeys(value, RUNTIME_KEYS));
+  assertOutput(value.runtimeId === runtime.id && value.installerTarget === runtime.installerTarget);
+  validateAvailability(value.availability);
+  validateStaticStatus(value.bundle, BUNDLE_REASON_BY_STATUS);
+  validateStaticStatus(value.buildAttestation, BUILD_REASON_BY_STATUS);
+  validateCanaries(value.canaries);
+  assertOutput(value.effectiveMode === 'proposal_only' && value.certification === 'unverified');
+  const expectedReasons = createReasons(value.availability, value.bundle, value.buildAttestation);
+  assertOutput(isDataArray(value.reasons)
+    && JSON.stringify(value.reasons) === JSON.stringify(expectedReasons));
+}
+
+function validateDiagnosticOutput(value) {
+  assertOutput(exactKeys(value, DIAGNOSTIC_KEYS));
+  assertOutput(value.schemaVersion === '1.0.0'
+    && value.kind === 'swl-runtime-diagnostic-core3'
+    && value.effectiveMode === 'proposal_only' && value.certification === 'unverified');
+  validarTimestampIso(value.generatedAt, 'diagnostic generatedAt');
+  assertOutput(isDataArray(value.runtimes) && value.runtimes.length === CONTRACT.runtimes.length);
+  value.runtimes.forEach((runtime, index) => (
+    validateRuntimeOutput(runtime, CONTRACT.runtimes[index], index)
+  ));
+}
+
+/**
+ * Exige exactamente los tres runtimes Core-3 (`validateDiagnosticOutput`).
+ * Una vista parcial (p. ej. filtrada por `--target` en `scripts/runtime-
+ * doctor.js`) es una selección de conveniencia para el consumidor, no un
+ * diagnóstico Core-3 completo — rechazarla aquí es correcto, no un bug.
+ */
+function validarDiagnosticoCore3(value) {
+  validateDiagnosticOutput(value);
+  return true;
+}
+
+async function diagnosticarCore3(options) {
+  validateOptions(options);
+  const snapshot = snapshotOptions(options);
+  const runtimes = [];
+  for (const runtime of CONTRACT.runtimes) {
+    runtimes.push(await diagnoseRuntime(runtime, snapshot));
+  }
+  const result = freezeDeep({
+    schemaVersion: '1.0.0', kind: 'swl-runtime-diagnostic-core3',
+    generatedAt: snapshot.now, effectiveMode: 'proposal_only',
+    certification: 'unverified', runtimes,
+  });
+  validateDiagnosticOutput(result);
+  DIAGNOSTICS.add(result);
+  return result;
+}
+
+/** Identidad exacta contra el WeakSet interno — una vista filtrada por target nunca coincide. */
+function esDiagnosticoCore3(value) {
+  return DIAGNOSTICS.has(value);
+}
+
+/** Igual que esDiagnosticoCore3(): solo serializa el diagnóstico completo emitido por diagnosticarCore3(). */
+function serializarDiagnosticoCore3(value) {
+  if (!DIAGNOSTICS.has(value)) throw new TypeError('se requiere diagnóstico verificado');
+  validateDiagnosticOutput(value);
+  return canonicalizarIJson(value);
+}
+
+module.exports = {
+  diagnosticarCore3,
+  esDiagnosticoCore3,
+  serializarDiagnosticoCore3,
+  validarDiagnosticoCore3,
+};

package/scripts/lib/runtime-doctor-input.js

@@ -0,0 +1,59 @@
+'use strict';
+
+/**
+ * Construye el input read-only que consume diagnosticarCore3() a partir del
+ * entorno del proceso: PATH normalizado y mapas vacíos de bundle/build-event
+ * (el CLI y `doctor` nunca tienen contexto de instalación real que ofrecer).
+ *
+ * Compartido entre scripts/runtime-doctor.js y la integración de scripts/doctor.js
+ * para no duplicar las reglas de saneamiento de PATH (DRY).
+ *
+ * @module scripts/lib/runtime-doctor-input
+ */
+
+const path = require('node:path');
+
+const { CORE_RUNTIME_IDS } = require('./runtime-adapter-contract');
+
+const MAX_PATH_ENTRIES = 64;
+const MAX_PATH_LENGTH = 4096;
+
+/**
+ * Normaliza `process.env.PATH` a un array apto para diagnosticarCore3():
+ * absoluto, NFKC, sin byte nulo, sin duplicados, acotado a 64 entradas.
+ * Entradas que no cumplen el formato se descartan silenciosamente — el
+ * validador aguas abajo falla cerrado ante cualquier entrada residual mal
+ * formada, así que aquí basta con producir un array ya conforme.
+ *
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {string[]}
+ */
+function pathEntriesFromEnv(env = process.env) {
+  const crudo = String(env.PATH || env.Path || '').split(path.delimiter);
+  const vistos = new Set();
+  const entradas = [];
+  for (const segmento of crudo) {
+    if (!segmento) continue;
+    const entrada = normalizarEntrada(segmento);
+    if (!entrada || vistos.has(entrada)) continue;
+    vistos.add(entrada);
+    entradas.push(entrada);
+    if (entradas.length >= MAX_PATH_ENTRIES) break;
+  }
+  return entradas;
+}
+
+function normalizarEntrada(segmento) {
+  const absoluta = path.resolve(segmento);
+  if (absoluta.length === 0 || absoluta.length > MAX_PATH_LENGTH) return null;
+  if (!path.isAbsolute(absoluta) || absoluta.includes('\0')) return null;
+  if (absoluta.normalize('NFKC') !== absoluta) return null;
+  return absoluta;
+}
+
+/** Mapa `{ [runtimeId]: null }` para las tres claves Core-3 exigidas por diagnosticarCore3(). */
+function emptyRuntimeMap() {
+  return Object.fromEntries(CORE_RUNTIME_IDS.map((id) => [id, null]));
+}
+
+module.exports = { pathEntriesFromEnv, emptyRuntimeMap, MAX_PATH_ENTRIES };