livedesk 0.1.593 → 0.1.595

package/diagnostics/livedesk-transport-physical-core.mjs

@@ -1,702 +1,702 @@
-import { createHash } from 'node:crypto';
-import { isIP } from 'node:net';
-
-const REQUIRED_PHASES = Object.freeze([
-  'direct',
-  'p2p',
-  'relay',
-  'recover-direct'
-]);
-
-const MAX_PHASE_LATENCY_MS = 15_000;
-const MAX_AGENT_QUEUE_DEPTH = 8;
-const MAX_AGENT_QUEUE_DROPPED_DELTA = 8;
-const MAX_HUB_INGRESS_DROPPED_DELTA = 8;
-const MAX_UDP_INCOMPLETE_DELTA = 2;
-const MAX_HUB_ADDRESS_OBSERVATION_SKEW_MS = 60_000;
-
-const SECRET_KEYS = new Set([
-  'authorization',
-  'bearer',
-  'token',
-  'secret',
-  'password',
-  'apikey',
-  'pairtoken'
-]);
-const SAFE_NETWORK_KEYS = new Set([
-  'clientaddresshash',
-  'hubaddresshash',
-  'clientaddresspublic',
-  'hubaddresspublic',
-  'hubaddressobservedat',
-  'endpointauthenticated',
-  'differentpublicegress',
-  'evidence',
-  'observedat',
-  'rendezvousport',
-  'udpready'
-]);
-const IDENTIFIER_KEYS = new Set([
-  'leaseid',
-  'deviceid',
-  'selecteddeviceid',
-  'streamid',
-  'streamcommandid',
-  'commandid',
-  'sessionid',
-  'requestid',
-  'connectionid',
-  'hubconnectionid',
-  'inputeventid',
-  'clientid',
-  'ownerid'
-]);
-const FILESYSTEM_KEYS = new Set([
-  'cwd',
-  'directory',
-  'dirname',
-  'executablepath',
-  'filepath',
-  'filename',
-  'homedir',
-  'packagepath',
-  'path',
-  'reportpath'
-]);
-const SECRET_TEXT = /\b(?:authorization|bearer|token|secret|password|api[-_ ]?key|pair[-_ ]?token)(?:\s+|\s*[:=]\s*)\S+/i;
-const FILESYSTEM_TEXT = /(?:^|\s)(?:[a-z]:[\\/]|\\\\[^\\\s]+\\|\/(?:applications|etc|home|opt|private|run|srv|tmp|users|usr|var|volumes)\/)\S*/i;
-const IPV4_TEXT = /(^|[^\d])(?:\d{1,3}\.){3}\d{1,3}(?::\d{1,5})?($|[^\d])/;
-const IPV6_CANDIDATE_TEXT = /\[[0-9a-f:.%]+\](?::\d{1,5})?|[0-9a-f:%]*:[0-9a-f:.%:]*/gi;
-const URL_TEXT = /\b[a-z][a-z0-9+.-]*:\/\/[^\s]+/i;
-const HOST_TEXT = /\b(?:localhost|(?:[a-z0-9-]+\.)+[a-z]{2,63})(?::\d{1,5})?\b/i;
-const UUID_TEXT = /\b[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\b/i;
-const SAFE_PLATFORMS = new Set([
-  'aix',
-  'android',
-  'darwin',
-  'freebsd',
-  'linux',
-  'macos',
-  'openbsd',
-  'sunos',
-  'win32',
-  'windows'
-]);
-const SAFE_ARCHITECTURES = new Set([
-  'arm',
-  'arm64',
-  'ia32',
-  'loong64',
-  'mips',
-  'mipsel',
-  'ppc',
-  'ppc64',
-  'riscv64',
-  's390',
-  's390x',
-  'x64'
-]);
-const SAFE_RUNTIME_STATES = new Set([
-  'booting',
-  'connecting',
-  'error',
-  'resolving-role',
-  'running',
-  'starting',
-  'stopping',
-  'switching',
-  'updating',
-  'waiting-auth'
-]);
-const SAFE_RUNTIME_ROLES = new Set(['client', 'hub']);
-const SAFE_VERSION = /^(?:v)?\d+(?:\.\d+){1,3}(?:[-+][0-9a-z][0-9a-z.-]{0,47})?$/i;
-
-function normalizedKey(key) {
-  return String(key || '').replace(/[-_]/g, '').toLowerCase();
-}
-
-function isIdentifierKey(key) {
-  return IDENTIFIER_KEYS.has(normalizedKey(key));
-}
-
-function isSecretKey(key) {
-  const normalized = normalizedKey(key);
-  return SECRET_KEYS.has(normalized)
-    || normalized.endsWith('token')
-    || normalized.endsWith('secret')
-    || normalized.endsWith('password')
-    || normalized.endsWith('apikey');
-}
-
-function isRawFilesystemKey(key) {
-  return FILESYSTEM_KEYS.has(normalizedKey(key));
-}
-
-function isRawNetworkKey(key) {
-  const rawKey = String(key || '');
-  const normalized = normalizedKey(key);
-  if (SAFE_NETWORK_KEYS.has(normalized) || normalized.endsWith('hash')) return false;
-  return normalized === 'address'
-    || normalized.endsWith('address')
-    || normalized === 'endpoint'
-    || normalized.endsWith('endpoint')
-    || normalized === 'host'
-    || normalized.endsWith('host')
-    || normalized === 'port'
-    || /(?:^|[-_])port$/i.test(rawKey)
-    || /[A-Z]Port$/.test(rawKey)
-    || normalized === 'url'
-    || normalized.endsWith('url')
-    || normalized === 'uri'
-    || normalized.endsWith('uri')
-    || normalized === 'origin'
-    || normalized.endsWith('origin');
-}
-
-function containsIpv6Text(value) {
-  const candidates = String(value || '').match(IPV6_CANDIDATE_TEXT) || [];
-  return candidates.some(candidate => {
-    const bracketed = candidate.match(/^\[([^\]]+)\](?::\d{1,5})?$/);
-    const address = String(bracketed?.[1] || candidate)
-      .replace(/%[a-z0-9_.-]+$/i, '')
-      .replace(/[.,;]+$/g, '');
-    return isIP(address) === 6;
-  });
-}
-
-function containsRawNetworkText(value) {
-  const text = String(value || '');
-  return IPV4_TEXT.test(text)
-    || containsIpv6Text(text)
-    || URL_TEXT.test(text)
-    || HOST_TEXT.test(text);
-}
-
-function identifierMarker(value) {
-  if (value === null || value === undefined || String(value) === '') return '';
-  return '[redacted-id]';
-}
-
-function normalizedEnum(value, allowed) {
-  const normalized = String(value || '').trim().toLowerCase();
-  return allowed.has(normalized) ? normalized : 'unknown';
-}
-
-function normalizedVersion(value) {
-  const normalized = String(value || '').trim();
-  if (normalized === 'dev') return 'dev';
-  return SAFE_VERSION.test(normalized) && isIP(normalized.replace(/^v/i, '')) === 0
-    ? normalized
-    : 'unknown';
-}
-
-function normalizedPackageName(value, fallback = '') {
-  const normalized = String(value || '').trim().toLowerCase();
-  if (normalized === 'livedesk' || /^@livedesk\/[a-z0-9-]{1,48}$/.test(normalized)) {
-    return normalized;
-  }
-  return fallback;
-}
-
-function normalizedBoolean(value) {
-  return typeof value === 'boolean' ? value : null;
-}
-
-function isAllowedStructuredScalar(key, value) {
-  const normalized = normalizedKey(key);
-  const text = String(value || '');
-  if (normalized === 'schema') {
-    return /^livedesk\.transport-physical\.v\d+$/.test(text);
-  }
-  if (normalized.endsWith('hash')) {
-    return /^sha256:[0-9a-f]{20,64}$/.test(text);
-  }
-  if ([
-    'agentversion',
-    'appversion',
-    'managerversion',
-    'nodeversion',
-    'packageversion',
-    'productversion'
-  ].includes(normalized)) {
-    return text === 'unknown'
-      || text === 'dev'
-      || normalizedVersion(text) === text;
-  }
-  return false;
-}
-
-function stableFingerprint(value) {
-  const normalized = String(value || '').trim();
-  if (!normalized) return '';
-  return `sha256:${createHash('sha256').update(normalized).digest('hex').slice(0, 20)}`;
-}
-
-function runtimeFingerprint(value = {}) {
-  const explicit = String(value.runtimeId || value.sessionId || '').trim();
-  if (explicit) return stableFingerprint(explicit);
-  const pid = Number(value.runtimePid ?? value.pid);
-  const startedAt = String(value.startedAt || value.connectedAt || '').trim();
-  if (!Number.isSafeInteger(pid) || pid <= 0 || !startedAt) return '';
-  return stableFingerprint(`${pid}:${startedAt}`);
-}
-
-function normalizedRendezvousEndpoint(value = {}) {
-  let rawHost = String(value.host || value.rendezvousHost || '').trim();
-  let rawPort = Number(value.port ?? value.rendezvousPort);
-  if (rawHost) {
-    try {
-      const parsed = new URL(rawHost.includes('://') ? rawHost : `udp://${rawHost}`);
-      rawHost = parsed.hostname.replace(/^\[|\]$/g, '').toLowerCase().replace(/\.$/, '');
-      if ((!Number.isSafeInteger(rawPort) || rawPort < 1 || rawPort > 65_535)
-        && parsed.port) {
-        rawPort = Number(parsed.port);
-      }
-    } catch {
-      rawHost = '';
-    }
-  }
-  const rendezvousPort = Number.isSafeInteger(rawPort) && rawPort >= 1 && rawPort <= 65_535
-    ? rawPort
-    : null;
-  return {
-    endpointKind: 'udp-rendezvous',
-    configured: !!rawHost && rendezvousPort !== null,
-    hostHash: stableFingerprint(rawHost),
-    rendezvousPort
-  };
-}
-
-export function buildTransportPhysicalProvenance(input = {}) {
-  const liveDeskPackage = input.liveDeskPackage || {};
-  const runner = input.runner || {};
-  const hubRuntime = input.hubRuntime || {};
-  const hubRemote = input.hubRemote || {};
-  const client = input.client || {};
-  const udp = input.rendezvous || hubRemote.udp || {};
-  const hubVersion = normalizedVersion(hubRuntime.appVersion);
-  const managerVersion = normalizedVersion(hubRemote.managerVersion);
-  return {
-    livedesk: {
-      packageName: 'livedesk',
-      packageVersion: normalizedVersion(liveDeskPackage.version)
-    },
-    runner: {
-      nodeVersion: normalizedVersion(runner.nodeVersion),
-      platform: normalizedEnum(runner.platform, SAFE_PLATFORMS),
-      arch: normalizedEnum(runner.arch, SAFE_ARCHITECTURES)
-    },
-    hub: {
-      packageName: normalizedPackageName(hubRemote.managerPackage, '@livedesk/hub'),
-      appVersion: hubVersion !== 'unknown' ? hubVersion : managerVersion,
-      managerVersion,
-      role: normalizedEnum(hubRuntime.role || hubRemote.runtimeRole, SAFE_RUNTIME_ROLES),
-      state: normalizedEnum(hubRuntime.state, SAFE_RUNTIME_STATES),
-      runtimeStarted: normalizedBoolean(hubRuntime.runtimeStarted),
-      runtimeIdentityHash: runtimeFingerprint(hubRuntime)
-    },
-    client: {
-      productVersion: normalizedVersion(client.productVersion),
-      agentVersion: normalizedVersion(client.agentVersion),
-      platform: normalizedEnum(client.platform, SAFE_PLATFORMS),
-      arch: normalizedEnum(client.arch, SAFE_ARCHITECTURES),
-      runtimeIdentityHash: runtimeFingerprint(client)
-    },
-    rendezvous: {
-      ...normalizedRendezvousEndpoint(udp),
-      enabled: normalizedBoolean(udp.enabled),
-      started: normalizedBoolean(udp.started)
-    }
-  };
-}
-
-export function genericTransportPhysicalError(value, fallback = 'transport-diagnostic-error') {
-  const text = String(value instanceof Error ? value.message : value || '').trim();
-  if (!text
-    || containsRawNetworkText(text)
-    || SECRET_TEXT.test(text)
-    || UUID_TEXT.test(text)) return fallback;
-  if (!/^[a-z0-9][a-z0-9 _.,:;()[\]/'"+=-]{0,239}$/i.test(text)) return fallback;
-  return text;
-}
-
-export function redactTransportPhysicalReport(value, key = '') {
-  if (isSecretKey(key)) return '[redacted]';
-  if (isIdentifierKey(key)) return identifierMarker(value);
-  if (isRawFilesystemKey(key)) return '[redacted-path]';
-  if (isRawNetworkKey(key)) return '[redacted-network]';
-  if (Array.isArray(value)) {
-    return value.map(item => redactTransportPhysicalReport(item));
-  }
-  if (value && typeof value === 'object') {
-    return Object.fromEntries(Object.entries(value)
-      .filter(([childKey]) => !isSecretKey(childKey))
-      .map(([childKey, childValue]) => [
-        childKey,
-        redactTransportPhysicalReport(childValue, childKey)
-      ]));
-  }
-  if (typeof value === 'string'
-    && !isAllowedStructuredScalar(key, value)
-    && (containsRawNetworkText(value)
-      || FILESYSTEM_TEXT.test(value)
-      || SECRET_TEXT.test(value)
-      || UUID_TEXT.test(value))) {
-    return /error|reason|detail|summary/i.test(key)
-      ? '[redacted-sensitive-error]'
-      : '[redacted-sensitive]';
-  }
-  return value;
-}
-
-export function findTransportPhysicalReportLeaks(value, path = '$', leaks = []) {
-  if (Array.isArray(value)) {
-    value.forEach((item, index) => findTransportPhysicalReportLeaks(item, `${path}[${index}]`, leaks));
-    return leaks;
-  }
-  if (value && typeof value === 'object') {
-    for (const [key, child] of Object.entries(value)) {
-      if (isSecretKey(key)
-        || (isRawFilesystemKey(key) && child !== '[redacted-path]')
-        || (isRawNetworkKey(key) && child !== '[redacted-network]')) {
-        leaks.push(`${path}.${key}`);
-      }
-      if (isIdentifierKey(key)
-        && child !== ''
-        && child !== '[redacted-id]') {
-        leaks.push(`${path}.${key}`);
-      }
-      findTransportPhysicalReportLeaks(child, `${path}.${key}`, leaks);
-    }
-    return leaks;
-  }
-  if (typeof value === 'string'
-    && !isAllowedStructuredScalar(path.split('.').at(-1)?.replace(/\[\d+\]$/, ''), value)
-    && (containsRawNetworkText(value)
-      || FILESYSTEM_TEXT.test(value)
-      || SECRET_TEXT.test(value)
-      || UUID_TEXT.test(value))) {
-    leaks.push(path);
-  }
-  return leaks;
-}
-
-function optionalFinite(value) {
-  if (value === null || value === undefined || value === '') return null;
-  const parsed = Number(value);
-  return Number.isFinite(parsed) ? parsed : null;
-}
-
-function phaseFrame(snapshot, phase) {
-  return Array.isArray(snapshot?.frames)
-    ? snapshot.frames.find(frame => frame?.phase === phase && frame?.accepted === true)
-    : null;
-}
-
-function expectedPathForPhase(phase) {
-  if (phase === 'p2p') return 'p2p';
-  if (phase === 'relay') return 'relay';
-  return 'direct';
-}
-
-export function hubObservedTransport(frame) {
-  const transport = String(frame?.transport || '').trim().toLowerCase();
-  if (transport === 'udp-p2p') return { path: 'p2p', label: 'udp-p2p' };
-  if (transport === 'relay-binary') return { path: 'relay', label: 'relay-binary' };
-  if (transport === 'binary' || transport === 'tcp-binary') {
-    return { path: 'direct', label: 'direct-tcp' };
-  }
-  if (transport === 'ws-binary') return { path: 'direct', label: 'direct-ws' };
-  return { path: '', label: 'unknown' };
-}
-
-export function isTransportPhysicalPhaseEvidence(frame, phase) {
-  const expectedPath = expectedPathForPhase(phase);
-  const observed = hubObservedTransport(frame);
-  const phaseLatencyMs = optionalFinite(frame?.phaseLatencyMs);
-  return frame?.accepted === true
-    && frame?.phase === phase
-    && frame?.actualPath === expectedPath
-    && observed.path === expectedPath
-    && frame?.isKeyFrame === true
-    && frame?.annexB === true
-    && frame?.hasIdr === true
-    && frame?.hasSps === true
-    && frame?.hasPps === true
-    && frame?.nalOrderValid === true
-    && optionalFinite(frame?.byteLength) > 0
-    && phaseLatencyMs !== null
-    && phaseLatencyMs >= 0
-    && phaseLatencyMs <= MAX_PHASE_LATENCY_MS;
-}
-
-function cumulativeDelta(values) {
-  if (!Array.isArray(values) || values.length < 2) {
-    return { valid: false, delta: null };
-  }
-  const normalized = values.map(optionalFinite);
-  const valid = normalized.every(value => value !== null && value >= 0)
-    && normalized.every((value, index) => index === 0 || value >= normalized[index - 1]);
-  return {
-    valid,
-    delta: valid ? normalized.at(-1) - normalized[0] : null
-  };
-}
-
-function scopedCounterDelta(baselines, samples) {
-  const scopes = new Map();
-  for (const baseline of baselines || []) {
-    const scope = String(baseline?.scope || '');
-    const value = optionalFinite(baseline?.value);
-    if (!scope || value === null || value < 0 || scopes.has(scope)) {
-      return { valid: false, delta: null };
-    }
-    scopes.set(scope, { initial: value, last: value });
-  }
-  let total = 0;
-  for (const sample of samples || []) {
-    const scope = String(sample?.scope || '');
-    const value = optionalFinite(sample?.value);
-    if (!scope || value === null || value < 0) {
-      return { valid: false, delta: null };
-    }
-    const state = scopes.get(scope) || { initial: 0, last: 0 };
-    if (value < state.last) {
-      return { valid: false, delta: null };
-    }
-    state.last = value;
-    scopes.set(scope, state);
-  }
-  for (const state of scopes.values()) {
-    total += state.last - state.initial;
-  }
-  return { valid: true, delta: total };
-}
-
-function timestampWithin(value, reference, maximumSkewMs) {
-  const observedAt = Date.parse(String(value || ''));
-  const referenceAt = Date.parse(String(reference || ''));
-  return Number.isFinite(observedAt)
-    && Number.isFinite(referenceAt)
-    && Math.abs(observedAt - referenceAt) <= maximumSkewMs;
-}
-
-export function classifyTransportPhysicalSnapshot(snapshot) {
-  const checks = [];
-  const add = (id, ok, detail) => checks.push({ id, ok: ok === true, detail });
-  const owner = snapshot?.owner || {};
-
-  add(
-    'same-current-owner',
-    !!owner.streamId
-      && !!owner.streamCommandId
-      && Number(owner.captureGeneration || 0) > 0
-      && Number(owner.monitorIndex) >= 0,
-    'One immutable stream, command, generation, and monitor must own the complete run.');
-
-  const observedFrames = REQUIRED_PHASES.map(phase => phaseFrame(snapshot, phase));
-  for (let index = 0; index < REQUIRED_PHASES.length; index += 1) {
-    const phase = REQUIRED_PHASES[index];
-    const frame = observedFrames[index];
-    const expectedPath = expectedPathForPhase(phase);
-    const observed = hubObservedTransport(frame);
-    add(
-      `received-h264-${phase}`,
-      !!frame
-        && frame.actualPath === expectedPath
-        && frame.isKeyFrame === true
-        && frame.annexB === true
-        && frame.hasIdr === true
-        && frame.hasSps === true
-        && frame.hasPps === true
-        && frame.nalOrderValid === true
-        && optionalFinite(frame.byteLength) > 0,
-      `A received Annex-B H.264 SPS -> PPS -> IDR access unit must prove ${phase}.`);
-    add(
-      `hub-observed-transport-${phase}`,
-      !!frame && observed.path === expectedPath,
-      `Hub ingress must observe ${phase} as ${observed.label}.`);
-    const phaseLatencyMs = optionalFinite(frame?.phaseLatencyMs);
-    add(
-      `phase-latency-${phase}`,
-      phaseLatencyMs !== null
-        && phaseLatencyMs >= 0
-        && phaseLatencyMs <= MAX_PHASE_LATENCY_MS,
-      `${phaseLatencyMs === null ? 'unknown' : Math.round(phaseLatencyMs)}ms/15000ms`);
-  }
-
-  const receivedTimes = observedFrames.map(frame => Date.parse(frame?.receivedAt || ''));
-  add(
-    'ordered-path-transition',
-    observedFrames.every(Boolean)
-      && receivedTimes.every(Number.isFinite)
-      && receivedTimes.every((time, index) => index === 0 || time > receivedTimes[index - 1]),
-    'Frames must arrive in strict Direct, UDP P2P, encrypted relay, Direct order.');
-
-  const frameSequences = observedFrames.map(frame => optionalFinite(frame?.frameSeq));
-  add(
-    'strict-frame-sequence',
-    frameSequences.every(value => Number.isSafeInteger(value) && value > 0)
-      && frameSequences.every((value, index) => index === 0 || value > frameSequences[index - 1]),
-    frameSequences.map(value => value ?? '?').join(' -> '));
-
-  const switchCounts = observedFrames.map(frame => optionalFinite(frame?.switchCount));
-  add(
-    'transport-switch-count',
-    switchCounts.every(value => Number.isSafeInteger(value) && value >= 0)
-      && switchCounts.every((value, index) => index === 0 || value > switchCounts[index - 1]),
-    switchCounts.map(value => value ?? '?').join(' -> '));
-
-  const network = snapshot?.network || {};
-  add(
-    'distinct-public-ipv4-egress',
-    network.evidence === 'authenticated-udp-endpoint-rendezvous-observed'
-      && network.endpointAuthenticated === true
-      && network.clientAddressPublic === true
-      && network.hubAddressPublic === true
-      && network.differentPublicEgress === true
-      && network.hubEndpointSource === 'trusted-rendezvous-observation',
-    'Authenticated UDP and trusted-rendezvous-observed distinct public IPv4 egress values are required; this does not prove distinct NAT devices.');
-  add(
-    'fresh-hub-public-ipv4-observation',
-    timestampWithin(
-      network.hubAddressObservedAt,
-      snapshot?.startedAt,
-      MAX_HUB_ADDRESS_OBSERVATION_SKEW_MS),
-    'The Hub public IPv4 value must be freshly observed within 60 seconds of diagnostic start.');
-  add(
-    'fresh-client-udp-observation',
-    timestampWithin(
-      network.observedAt,
-      snapshot?.startedAt,
-      MAX_HUB_ADDRESS_OBSERVATION_SKEW_MS),
-    'The authenticated Client UDP endpoint must be observed within 60 seconds of diagnostic start.');
-
-  const cleanup = Array.isArray(snapshot?.cleanup) ? snapshot.cleanup : [];
-  add(
-    'lease-cleaned',
-    snapshot?.state === 'completed'
-      && cleanup.some(entry => entry?.state === 'agent-released'),
-    'The exact-owner diagnostic lease must be released by the Agent.');
-
-  const baseline = snapshot?.baseline || {};
-  const agentTelemetryAvailable = baseline.agentQueueTelemetryAvailable === true
-    && optionalFinite(baseline.agentQueueDropped) !== null
-    && observedFrames.every(frame =>
-      frame?.agentQueueTelemetryAvailable === true
-      && optionalFinite(frame.agentQueueDepth) !== null
-      && optionalFinite(frame.agentQueueDropped) !== null);
-  const hubTelemetryAvailable = baseline.hubIngressTelemetryAvailable === true
-    && optionalFinite(baseline.hubIngressDropped) !== null
-    && !!baseline.hubIngressCounterEpochHash
-    && !!baseline.udpCounterEpochHash
-    && observedFrames.every(frame =>
-      frame?.hubIngressTelemetryAvailable === true
-      && optionalFinite(frame.hubIngressDropped) !== null
-      && !!frame.hubIngressCounterEpochHash);
-  const p2pFrame = observedFrames[REQUIRED_PHASES.indexOf('p2p')];
-  const udpTelemetryAvailable = baseline.udpTelemetryAvailable === true
-    && optionalFinite(baseline.udpIncompleteFrames) !== null
-    && p2pFrame?.udpTelemetryAvailable === true
-    && optionalFinite(p2pFrame?.udpIncompleteFrames) !== null
-    && p2pFrame?.hubIngressCounterEpochHash === baseline.udpCounterEpochHash;
-  add(
-    'agent-queue-telemetry',
-    agentTelemetryAvailable,
-    agentTelemetryAvailable ? 'baseline and all four phases' : 'unknown or incomplete');
-  add(
-    'hub-ingress-telemetry',
-    hubTelemetryAvailable,
-    hubTelemetryAvailable ? 'baseline and all four phases' : 'unknown or incomplete');
-  add(
-    'udp-reassembly-telemetry',
-    udpTelemetryAvailable,
-    udpTelemetryAvailable ? 'baseline and P2P phase' : 'unknown or incomplete');
-
-  const agentDropped = cumulativeDelta([
-    baseline.agentQueueDropped,
-    ...observedFrames.map(frame => frame?.agentQueueDropped)
-  ]);
-  const hubDropped = scopedCounterDelta([
-    {
-      scope: baseline.hubIngressCounterEpochHash,
-      value: baseline.hubIngressDropped
-    },
-    {
-      scope: baseline.udpCounterEpochHash,
-      value: baseline.udpIncompleteFrames
-    }
-  ], observedFrames.map(frame => ({
-    scope: frame?.hubIngressCounterEpochHash,
-    value: frame?.hubIngressDropped
-  })));
-  const udpIncomplete = cumulativeDelta([
-    baseline.udpIncompleteFrames,
-    p2pFrame?.udpIncompleteFrames
-  ]);
-  const maxAgentQueueDepth = agentTelemetryAvailable
-    ? Math.max(...observedFrames.map(frame => Number(frame.agentQueueDepth)))
-    : null;
-  const boundedQueues = agentTelemetryAvailable
-    && hubTelemetryAvailable
-    && udpTelemetryAvailable
-    && agentDropped.valid
-    && hubDropped.valid
-    && udpIncomplete.valid
-    && maxAgentQueueDepth <= MAX_AGENT_QUEUE_DEPTH
-    && agentDropped.delta <= MAX_AGENT_QUEUE_DROPPED_DELTA
-    && hubDropped.delta <= MAX_HUB_INGRESS_DROPPED_DELTA
-    && udpIncomplete.delta <= MAX_UDP_INCOMPLETE_DELTA;
-  add(
-    'bounded-frame-queues',
-    boundedQueues,
-    `queueDepth=${maxAgentQueueDepth ?? 'unknown'}, `
-      + `agentDroppedDelta=${agentDropped.delta ?? 'unknown'}, `
-      + `hubDroppedDelta=${hubDropped.delta ?? 'unknown'}, `
-      + `udpIncompleteDelta=${udpIncomplete.delta ?? 'unknown'}`);
-
-  const failed = checks.filter(check => !check.ok);
-  const phaseLatencies = observedFrames.map(frame => optionalFinite(frame?.phaseLatencyMs));
-  return {
-    status: failed.length === 0 ? 'passed' : 'blocked',
-    summary: failed.length === 0
-      ? 'Direct, UDP P2P, encrypted relay, and Direct recovery were proven by independent received H.264 access units.'
-      : `Physical transport proof is incomplete (${failed.map(check => check.id).join(', ')}).`,
-    checks,
-    metrics: {
-      maxPhaseLatencyMs: phaseLatencies.every(value => value !== null)
-        ? Math.max(...phaseLatencies)
-        : null,
-      maxAgentQueueDepth,
-      agentQueueDroppedDelta: agentDropped.delta,
-      hubIngressDroppedDelta: hubDropped.delta,
-      udpIncompleteFramesDelta: udpIncomplete.delta,
-      observedTransports: observedFrames.map(frame => hubObservedTransport(frame).label)
-    }
-  };
-}
-
-export function buildTransportPhysicalReport(snapshot, context = {}) {
-  const classified = classifyTransportPhysicalSnapshot(snapshot);
-  const report = redactTransportPhysicalReport({
-    schema: 'livedesk.transport-physical.v2',
-    generatedAt: new Date().toISOString(),
-    hubUrl: context.hubUrl,
-    selectedDeviceId: context.deviceId,
-    provenance: buildTransportPhysicalProvenance(context.provenance),
-    result: classified,
-    transport: snapshot
-  });
-  const leaks = findTransportPhysicalReportLeaks(report);
-  if (leaks.length > 0) {
-    throw new Error(`transport-physical-report-redaction-failed:${leaks.join(',')}`);
-  }
-  return report;
-}
-
-export {
-  MAX_HUB_ADDRESS_OBSERVATION_SKEW_MS,
-  MAX_PHASE_LATENCY_MS,
-  REQUIRED_PHASES
-};
+import { createHash } from 'node:crypto';
+import { isIP } from 'node:net';
+
+const REQUIRED_PHASES = Object.freeze([
+  'direct',
+  'p2p',
+  'relay',
+  'recover-direct'
+]);
+
+const MAX_PHASE_LATENCY_MS = 15_000;
+const MAX_AGENT_QUEUE_DEPTH = 8;
+const MAX_AGENT_QUEUE_DROPPED_DELTA = 8;
+const MAX_HUB_INGRESS_DROPPED_DELTA = 8;
+const MAX_UDP_INCOMPLETE_DELTA = 2;
+const MAX_HUB_ADDRESS_OBSERVATION_SKEW_MS = 60_000;
+
+const SECRET_KEYS = new Set([
+  'authorization',
+  'bearer',
+  'token',
+  'secret',
+  'password',
+  'apikey',
+  'pairtoken'
+]);
+const SAFE_NETWORK_KEYS = new Set([
+  'clientaddresshash',
+  'hubaddresshash',
+  'clientaddresspublic',
+  'hubaddresspublic',
+  'hubaddressobservedat',
+  'endpointauthenticated',
+  'differentpublicegress',
+  'evidence',
+  'observedat',
+  'rendezvousport',
+  'udpready'
+]);
+const IDENTIFIER_KEYS = new Set([
+  'leaseid',
+  'deviceid',
+  'selecteddeviceid',
+  'streamid',
+  'streamcommandid',
+  'commandid',
+  'sessionid',
+  'requestid',
+  'connectionid',
+  'hubconnectionid',
+  'inputeventid',
+  'clientid',
+  'ownerid'
+]);
+const FILESYSTEM_KEYS = new Set([
+  'cwd',
+  'directory',
+  'dirname',
+  'executablepath',
+  'filepath',
+  'filename',
+  'homedir',
+  'packagepath',
+  'path',
+  'reportpath'
+]);
+const SECRET_TEXT = /\b(?:authorization|bearer|token|secret|password|api[-_ ]?key|pair[-_ ]?token)(?:\s+|\s*[:=]\s*)\S+/i;
+const FILESYSTEM_TEXT = /(?:^|\s)(?:[a-z]:[\\/]|\\\\[^\\\s]+\\|\/(?:applications|etc|home|opt|private|run|srv|tmp|users|usr|var|volumes)\/)\S*/i;
+const IPV4_TEXT = /(^|[^\d])(?:\d{1,3}\.){3}\d{1,3}(?::\d{1,5})?($|[^\d])/;
+const IPV6_CANDIDATE_TEXT = /\[[0-9a-f:.%]+\](?::\d{1,5})?|[0-9a-f:%]*:[0-9a-f:.%:]*/gi;
+const URL_TEXT = /\b[a-z][a-z0-9+.-]*:\/\/[^\s]+/i;
+const HOST_TEXT = /\b(?:localhost|(?:[a-z0-9-]+\.)+[a-z]{2,63})(?::\d{1,5})?\b/i;
+const UUID_TEXT = /\b[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\b/i;
+const SAFE_PLATFORMS = new Set([
+  'aix',
+  'android',
+  'darwin',
+  'freebsd',
+  'linux',
+  'macos',
+  'openbsd',
+  'sunos',
+  'win32',
+  'windows'
+]);
+const SAFE_ARCHITECTURES = new Set([
+  'arm',
+  'arm64',
+  'ia32',
+  'loong64',
+  'mips',
+  'mipsel',
+  'ppc',
+  'ppc64',
+  'riscv64',
+  's390',
+  's390x',
+  'x64'
+]);
+const SAFE_RUNTIME_STATES = new Set([
+  'booting',
+  'connecting',
+  'error',
+  'resolving-role',
+  'running',
+  'starting',
+  'stopping',
+  'switching',
+  'updating',
+  'waiting-auth'
+]);
+const SAFE_RUNTIME_ROLES = new Set(['client', 'hub']);
+const SAFE_VERSION = /^(?:v)?\d+(?:\.\d+){1,3}(?:[-+][0-9a-z][0-9a-z.-]{0,47})?$/i;
+
+function normalizedKey(key) {
+  return String(key || '').replace(/[-_]/g, '').toLowerCase();
+}
+
+function isIdentifierKey(key) {
+  return IDENTIFIER_KEYS.has(normalizedKey(key));
+}
+
+function isSecretKey(key) {
+  const normalized = normalizedKey(key);
+  return SECRET_KEYS.has(normalized)
+    || normalized.endsWith('token')
+    || normalized.endsWith('secret')
+    || normalized.endsWith('password')
+    || normalized.endsWith('apikey');
+}
+
+function isRawFilesystemKey(key) {
+  return FILESYSTEM_KEYS.has(normalizedKey(key));
+}
+
+function isRawNetworkKey(key) {
+  const rawKey = String(key || '');
+  const normalized = normalizedKey(key);
+  if (SAFE_NETWORK_KEYS.has(normalized) || normalized.endsWith('hash')) return false;
+  return normalized === 'address'
+    || normalized.endsWith('address')
+    || normalized === 'endpoint'
+    || normalized.endsWith('endpoint')
+    || normalized === 'host'
+    || normalized.endsWith('host')
+    || normalized === 'port'
+    || /(?:^|[-_])port$/i.test(rawKey)
+    || /[A-Z]Port$/.test(rawKey)
+    || normalized === 'url'
+    || normalized.endsWith('url')
+    || normalized === 'uri'
+    || normalized.endsWith('uri')
+    || normalized === 'origin'
+    || normalized.endsWith('origin');
+}
+
+function containsIpv6Text(value) {
+  const candidates = String(value || '').match(IPV6_CANDIDATE_TEXT) || [];
+  return candidates.some(candidate => {
+    const bracketed = candidate.match(/^\[([^\]]+)\](?::\d{1,5})?$/);
+    const address = String(bracketed?.[1] || candidate)
+      .replace(/%[a-z0-9_.-]+$/i, '')
+      .replace(/[.,;]+$/g, '');
+    return isIP(address) === 6;
+  });
+}
+
+function containsRawNetworkText(value) {
+  const text = String(value || '');
+  return IPV4_TEXT.test(text)
+    || containsIpv6Text(text)
+    || URL_TEXT.test(text)
+    || HOST_TEXT.test(text);
+}
+
+function identifierMarker(value) {
+  if (value === null || value === undefined || String(value) === '') return '';
+  return '[redacted-id]';
+}
+
+function normalizedEnum(value, allowed) {
+  const normalized = String(value || '').trim().toLowerCase();
+  return allowed.has(normalized) ? normalized : 'unknown';
+}
+
+function normalizedVersion(value) {
+  const normalized = String(value || '').trim();
+  if (normalized === 'dev') return 'dev';
+  return SAFE_VERSION.test(normalized) && isIP(normalized.replace(/^v/i, '')) === 0
+    ? normalized
+    : 'unknown';
+}
+
+function normalizedPackageName(value, fallback = '') {
+  const normalized = String(value || '').trim().toLowerCase();
+  if (normalized === 'livedesk' || /^@livedesk\/[a-z0-9-]{1,48}$/.test(normalized)) {
+    return normalized;
+  }
+  return fallback;
+}
+
+function normalizedBoolean(value) {
+  return typeof value === 'boolean' ? value : null;
+}
+
+function isAllowedStructuredScalar(key, value) {
+  const normalized = normalizedKey(key);
+  const text = String(value || '');
+  if (normalized === 'schema') {
+    return /^livedesk\.transport-physical\.v\d+$/.test(text);
+  }
+  if (normalized.endsWith('hash')) {
+    return /^sha256:[0-9a-f]{20,64}$/.test(text);
+  }
+  if ([
+    'agentversion',
+    'appversion',
+    'managerversion',
+    'nodeversion',
+    'packageversion',
+    'productversion'
+  ].includes(normalized)) {
+    return text === 'unknown'
+      || text === 'dev'
+      || normalizedVersion(text) === text;
+  }
+  return false;
+}
+
+function stableFingerprint(value) {
+  const normalized = String(value || '').trim();
+  if (!normalized) return '';
+  return `sha256:${createHash('sha256').update(normalized).digest('hex').slice(0, 20)}`;
+}
+
+function runtimeFingerprint(value = {}) {
+  const explicit = String(value.runtimeId || value.sessionId || '').trim();
+  if (explicit) return stableFingerprint(explicit);
+  const pid = Number(value.runtimePid ?? value.pid);
+  const startedAt = String(value.startedAt || value.connectedAt || '').trim();
+  if (!Number.isSafeInteger(pid) || pid <= 0 || !startedAt) return '';
+  return stableFingerprint(`${pid}:${startedAt}`);
+}
+
+function normalizedRendezvousEndpoint(value = {}) {
+  let rawHost = String(value.host || value.rendezvousHost || '').trim();
+  let rawPort = Number(value.port ?? value.rendezvousPort);
+  if (rawHost) {
+    try {
+      const parsed = new URL(rawHost.includes('://') ? rawHost : `udp://${rawHost}`);
+      rawHost = parsed.hostname.replace(/^\[|\]$/g, '').toLowerCase().replace(/\.$/, '');
+      if ((!Number.isSafeInteger(rawPort) || rawPort < 1 || rawPort > 65_535)
+        && parsed.port) {
+        rawPort = Number(parsed.port);
+      }
+    } catch {
+      rawHost = '';
+    }
+  }
+  const rendezvousPort = Number.isSafeInteger(rawPort) && rawPort >= 1 && rawPort <= 65_535
+    ? rawPort
+    : null;
+  return {
+    endpointKind: 'udp-rendezvous',
+    configured: !!rawHost && rendezvousPort !== null,
+    hostHash: stableFingerprint(rawHost),
+    rendezvousPort
+  };
+}
+
+export function buildTransportPhysicalProvenance(input = {}) {
+  const liveDeskPackage = input.liveDeskPackage || {};
+  const runner = input.runner || {};
+  const hubRuntime = input.hubRuntime || {};
+  const hubRemote = input.hubRemote || {};
+  const client = input.client || {};
+  const udp = input.rendezvous || hubRemote.udp || {};
+  const hubVersion = normalizedVersion(hubRuntime.appVersion);
+  const managerVersion = normalizedVersion(hubRemote.managerVersion);
+  return {
+    livedesk: {
+      packageName: 'livedesk',
+      packageVersion: normalizedVersion(liveDeskPackage.version)
+    },
+    runner: {
+      nodeVersion: normalizedVersion(runner.nodeVersion),
+      platform: normalizedEnum(runner.platform, SAFE_PLATFORMS),
+      arch: normalizedEnum(runner.arch, SAFE_ARCHITECTURES)
+    },
+    hub: {
+      packageName: normalizedPackageName(hubRemote.managerPackage, '@livedesk/hub'),
+      appVersion: hubVersion !== 'unknown' ? hubVersion : managerVersion,
+      managerVersion,
+      role: normalizedEnum(hubRuntime.role || hubRemote.runtimeRole, SAFE_RUNTIME_ROLES),
+      state: normalizedEnum(hubRuntime.state, SAFE_RUNTIME_STATES),
+      runtimeStarted: normalizedBoolean(hubRuntime.runtimeStarted),
+      runtimeIdentityHash: runtimeFingerprint(hubRuntime)
+    },
+    client: {
+      productVersion: normalizedVersion(client.productVersion),
+      agentVersion: normalizedVersion(client.agentVersion),
+      platform: normalizedEnum(client.platform, SAFE_PLATFORMS),
+      arch: normalizedEnum(client.arch, SAFE_ARCHITECTURES),
+      runtimeIdentityHash: runtimeFingerprint(client)
+    },
+    rendezvous: {
+      ...normalizedRendezvousEndpoint(udp),
+      enabled: normalizedBoolean(udp.enabled),
+      started: normalizedBoolean(udp.started)
+    }
+  };
+}
+
+export function genericTransportPhysicalError(value, fallback = 'transport-diagnostic-error') {
+  const text = String(value instanceof Error ? value.message : value || '').trim();
+  if (!text
+    || containsRawNetworkText(text)
+    || SECRET_TEXT.test(text)
+    || UUID_TEXT.test(text)) return fallback;
+  if (!/^[a-z0-9][a-z0-9 _.,:;()[\]/'"+=-]{0,239}$/i.test(text)) return fallback;
+  return text;
+}
+
+export function redactTransportPhysicalReport(value, key = '') {
+  if (isSecretKey(key)) return '[redacted]';
+  if (isIdentifierKey(key)) return identifierMarker(value);
+  if (isRawFilesystemKey(key)) return '[redacted-path]';
+  if (isRawNetworkKey(key)) return '[redacted-network]';
+  if (Array.isArray(value)) {
+    return value.map(item => redactTransportPhysicalReport(item));
+  }
+  if (value && typeof value === 'object') {
+    return Object.fromEntries(Object.entries(value)
+      .filter(([childKey]) => !isSecretKey(childKey))
+      .map(([childKey, childValue]) => [
+        childKey,
+        redactTransportPhysicalReport(childValue, childKey)
+      ]));
+  }
+  if (typeof value === 'string'
+    && !isAllowedStructuredScalar(key, value)
+    && (containsRawNetworkText(value)
+      || FILESYSTEM_TEXT.test(value)
+      || SECRET_TEXT.test(value)
+      || UUID_TEXT.test(value))) {
+    return /error|reason|detail|summary/i.test(key)
+      ? '[redacted-sensitive-error]'
+      : '[redacted-sensitive]';
+  }
+  return value;
+}
+
+export function findTransportPhysicalReportLeaks(value, path = '$', leaks = []) {
+  if (Array.isArray(value)) {
+    value.forEach((item, index) => findTransportPhysicalReportLeaks(item, `${path}[${index}]`, leaks));
+    return leaks;
+  }
+  if (value && typeof value === 'object') {
+    for (const [key, child] of Object.entries(value)) {
+      if (isSecretKey(key)
+        || (isRawFilesystemKey(key) && child !== '[redacted-path]')
+        || (isRawNetworkKey(key) && child !== '[redacted-network]')) {
+        leaks.push(`${path}.${key}`);
+      }
+      if (isIdentifierKey(key)
+        && child !== ''
+        && child !== '[redacted-id]') {
+        leaks.push(`${path}.${key}`);
+      }
+      findTransportPhysicalReportLeaks(child, `${path}.${key}`, leaks);
+    }
+    return leaks;
+  }
+  if (typeof value === 'string'
+    && !isAllowedStructuredScalar(path.split('.').at(-1)?.replace(/\[\d+\]$/, ''), value)
+    && (containsRawNetworkText(value)
+      || FILESYSTEM_TEXT.test(value)
+      || SECRET_TEXT.test(value)
+      || UUID_TEXT.test(value))) {
+    leaks.push(path);
+  }
+  return leaks;
+}
+
+function optionalFinite(value) {
+  if (value === null || value === undefined || value === '') return null;
+  const parsed = Number(value);
+  return Number.isFinite(parsed) ? parsed : null;
+}
+
+function phaseFrame(snapshot, phase) {
+  return Array.isArray(snapshot?.frames)
+    ? snapshot.frames.find(frame => frame?.phase === phase && frame?.accepted === true)
+    : null;
+}
+
+function expectedPathForPhase(phase) {
+  if (phase === 'p2p') return 'p2p';
+  if (phase === 'relay') return 'relay';
+  return 'direct';
+}
+
+export function hubObservedTransport(frame) {
+  const transport = String(frame?.transport || '').trim().toLowerCase();
+  if (transport === 'udp-p2p') return { path: 'p2p', label: 'udp-p2p' };
+  if (transport === 'relay-binary') return { path: 'relay', label: 'relay-binary' };
+  if (transport === 'binary' || transport === 'tcp-binary') {
+    return { path: 'direct', label: 'direct-tcp' };
+  }
+  if (transport === 'ws-binary') return { path: 'direct', label: 'direct-ws' };
+  return { path: '', label: 'unknown' };
+}
+
+export function isTransportPhysicalPhaseEvidence(frame, phase) {
+  const expectedPath = expectedPathForPhase(phase);
+  const observed = hubObservedTransport(frame);
+  const phaseLatencyMs = optionalFinite(frame?.phaseLatencyMs);
+  return frame?.accepted === true
+    && frame?.phase === phase
+    && frame?.actualPath === expectedPath
+    && observed.path === expectedPath
+    && frame?.isKeyFrame === true
+    && frame?.annexB === true
+    && frame?.hasIdr === true
+    && frame?.hasSps === true
+    && frame?.hasPps === true
+    && frame?.nalOrderValid === true
+    && optionalFinite(frame?.byteLength) > 0
+    && phaseLatencyMs !== null
+    && phaseLatencyMs >= 0
+    && phaseLatencyMs <= MAX_PHASE_LATENCY_MS;
+}
+
+function cumulativeDelta(values) {
+  if (!Array.isArray(values) || values.length < 2) {
+    return { valid: false, delta: null };
+  }
+  const normalized = values.map(optionalFinite);
+  const valid = normalized.every(value => value !== null && value >= 0)
+    && normalized.every((value, index) => index === 0 || value >= normalized[index - 1]);
+  return {
+    valid,
+    delta: valid ? normalized.at(-1) - normalized[0] : null
+  };
+}
+
+function scopedCounterDelta(baselines, samples) {
+  const scopes = new Map();
+  for (const baseline of baselines || []) {
+    const scope = String(baseline?.scope || '');
+    const value = optionalFinite(baseline?.value);
+    if (!scope || value === null || value < 0 || scopes.has(scope)) {
+      return { valid: false, delta: null };
+    }
+    scopes.set(scope, { initial: value, last: value });
+  }
+  let total = 0;
+  for (const sample of samples || []) {
+    const scope = String(sample?.scope || '');
+    const value = optionalFinite(sample?.value);
+    if (!scope || value === null || value < 0) {
+      return { valid: false, delta: null };
+    }
+    const state = scopes.get(scope) || { initial: 0, last: 0 };
+    if (value < state.last) {
+      return { valid: false, delta: null };
+    }
+    state.last = value;
+    scopes.set(scope, state);
+  }
+  for (const state of scopes.values()) {
+    total += state.last - state.initial;
+  }
+  return { valid: true, delta: total };
+}
+
+function timestampWithin(value, reference, maximumSkewMs) {
+  const observedAt = Date.parse(String(value || ''));
+  const referenceAt = Date.parse(String(reference || ''));
+  return Number.isFinite(observedAt)
+    && Number.isFinite(referenceAt)
+    && Math.abs(observedAt - referenceAt) <= maximumSkewMs;
+}
+
+export function classifyTransportPhysicalSnapshot(snapshot) {
+  const checks = [];
+  const add = (id, ok, detail) => checks.push({ id, ok: ok === true, detail });
+  const owner = snapshot?.owner || {};
+
+  add(
+    'same-current-owner',
+    !!owner.streamId
+      && !!owner.streamCommandId
+      && Number(owner.captureGeneration || 0) > 0
+      && Number(owner.monitorIndex) >= 0,
+    'One immutable stream, command, generation, and monitor must own the complete run.');
+
+  const observedFrames = REQUIRED_PHASES.map(phase => phaseFrame(snapshot, phase));
+  for (let index = 0; index < REQUIRED_PHASES.length; index += 1) {
+    const phase = REQUIRED_PHASES[index];
+    const frame = observedFrames[index];
+    const expectedPath = expectedPathForPhase(phase);
+    const observed = hubObservedTransport(frame);
+    add(
+      `received-h264-${phase}`,
+      !!frame
+        && frame.actualPath === expectedPath
+        && frame.isKeyFrame === true
+        && frame.annexB === true
+        && frame.hasIdr === true
+        && frame.hasSps === true
+        && frame.hasPps === true
+        && frame.nalOrderValid === true
+        && optionalFinite(frame.byteLength) > 0,
+      `A received Annex-B H.264 SPS -> PPS -> IDR access unit must prove ${phase}.`);
+    add(
+      `hub-observed-transport-${phase}`,
+      !!frame && observed.path === expectedPath,
+      `Hub ingress must observe ${phase} as ${observed.label}.`);
+    const phaseLatencyMs = optionalFinite(frame?.phaseLatencyMs);
+    add(
+      `phase-latency-${phase}`,
+      phaseLatencyMs !== null
+        && phaseLatencyMs >= 0
+        && phaseLatencyMs <= MAX_PHASE_LATENCY_MS,
+      `${phaseLatencyMs === null ? 'unknown' : Math.round(phaseLatencyMs)}ms/15000ms`);
+  }
+
+  const receivedTimes = observedFrames.map(frame => Date.parse(frame?.receivedAt || ''));
+  add(
+    'ordered-path-transition',
+    observedFrames.every(Boolean)
+      && receivedTimes.every(Number.isFinite)
+      && receivedTimes.every((time, index) => index === 0 || time > receivedTimes[index - 1]),
+    'Frames must arrive in strict Direct, UDP P2P, encrypted relay, Direct order.');
+
+  const frameSequences = observedFrames.map(frame => optionalFinite(frame?.frameSeq));
+  add(
+    'strict-frame-sequence',
+    frameSequences.every(value => Number.isSafeInteger(value) && value > 0)
+      && frameSequences.every((value, index) => index === 0 || value > frameSequences[index - 1]),
+    frameSequences.map(value => value ?? '?').join(' -> '));
+
+  const switchCounts = observedFrames.map(frame => optionalFinite(frame?.switchCount));
+  add(
+    'transport-switch-count',
+    switchCounts.every(value => Number.isSafeInteger(value) && value >= 0)
+      && switchCounts.every((value, index) => index === 0 || value > switchCounts[index - 1]),
+    switchCounts.map(value => value ?? '?').join(' -> '));
+
+  const network = snapshot?.network || {};
+  add(
+    'distinct-public-ipv4-egress',
+    network.evidence === 'authenticated-udp-endpoint-rendezvous-observed'
+      && network.endpointAuthenticated === true
+      && network.clientAddressPublic === true
+      && network.hubAddressPublic === true
+      && network.differentPublicEgress === true
+      && network.hubEndpointSource === 'trusted-rendezvous-observation',
+    'Authenticated UDP and trusted-rendezvous-observed distinct public IPv4 egress values are required; this does not prove distinct NAT devices.');
+  add(
+    'fresh-hub-public-ipv4-observation',
+    timestampWithin(
+      network.hubAddressObservedAt,
+      snapshot?.startedAt,
+      MAX_HUB_ADDRESS_OBSERVATION_SKEW_MS),
+    'The Hub public IPv4 value must be freshly observed within 60 seconds of diagnostic start.');
+  add(
+    'fresh-client-udp-observation',
+    timestampWithin(
+      network.observedAt,
+      snapshot?.startedAt,
+      MAX_HUB_ADDRESS_OBSERVATION_SKEW_MS),
+    'The authenticated Client UDP endpoint must be observed within 60 seconds of diagnostic start.');
+
+  const cleanup = Array.isArray(snapshot?.cleanup) ? snapshot.cleanup : [];
+  add(
+    'lease-cleaned',
+    snapshot?.state === 'completed'
+      && cleanup.some(entry => entry?.state === 'agent-released'),
+    'The exact-owner diagnostic lease must be released by the Agent.');
+
+  const baseline = snapshot?.baseline || {};
+  const agentTelemetryAvailable = baseline.agentQueueTelemetryAvailable === true
+    && optionalFinite(baseline.agentQueueDropped) !== null
+    && observedFrames.every(frame =>
+      frame?.agentQueueTelemetryAvailable === true
+      && optionalFinite(frame.agentQueueDepth) !== null
+      && optionalFinite(frame.agentQueueDropped) !== null);
+  const hubTelemetryAvailable = baseline.hubIngressTelemetryAvailable === true
+    && optionalFinite(baseline.hubIngressDropped) !== null
+    && !!baseline.hubIngressCounterEpochHash
+    && !!baseline.udpCounterEpochHash
+    && observedFrames.every(frame =>
+      frame?.hubIngressTelemetryAvailable === true
+      && optionalFinite(frame.hubIngressDropped) !== null
+      && !!frame.hubIngressCounterEpochHash);
+  const p2pFrame = observedFrames[REQUIRED_PHASES.indexOf('p2p')];
+  const udpTelemetryAvailable = baseline.udpTelemetryAvailable === true
+    && optionalFinite(baseline.udpIncompleteFrames) !== null
+    && p2pFrame?.udpTelemetryAvailable === true
+    && optionalFinite(p2pFrame?.udpIncompleteFrames) !== null
+    && p2pFrame?.hubIngressCounterEpochHash === baseline.udpCounterEpochHash;
+  add(
+    'agent-queue-telemetry',
+    agentTelemetryAvailable,
+    agentTelemetryAvailable ? 'baseline and all four phases' : 'unknown or incomplete');
+  add(
+    'hub-ingress-telemetry',
+    hubTelemetryAvailable,
+    hubTelemetryAvailable ? 'baseline and all four phases' : 'unknown or incomplete');
+  add(
+    'udp-reassembly-telemetry',
+    udpTelemetryAvailable,
+    udpTelemetryAvailable ? 'baseline and P2P phase' : 'unknown or incomplete');
+
+  const agentDropped = cumulativeDelta([
+    baseline.agentQueueDropped,
+    ...observedFrames.map(frame => frame?.agentQueueDropped)
+  ]);
+  const hubDropped = scopedCounterDelta([
+    {
+      scope: baseline.hubIngressCounterEpochHash,
+      value: baseline.hubIngressDropped
+    },
+    {
+      scope: baseline.udpCounterEpochHash,
+      value: baseline.udpIncompleteFrames
+    }
+  ], observedFrames.map(frame => ({
+    scope: frame?.hubIngressCounterEpochHash,
+    value: frame?.hubIngressDropped
+  })));
+  const udpIncomplete = cumulativeDelta([
+    baseline.udpIncompleteFrames,
+    p2pFrame?.udpIncompleteFrames
+  ]);
+  const maxAgentQueueDepth = agentTelemetryAvailable
+    ? Math.max(...observedFrames.map(frame => Number(frame.agentQueueDepth)))
+    : null;
+  const boundedQueues = agentTelemetryAvailable
+    && hubTelemetryAvailable
+    && udpTelemetryAvailable
+    && agentDropped.valid
+    && hubDropped.valid
+    && udpIncomplete.valid
+    && maxAgentQueueDepth <= MAX_AGENT_QUEUE_DEPTH
+    && agentDropped.delta <= MAX_AGENT_QUEUE_DROPPED_DELTA
+    && hubDropped.delta <= MAX_HUB_INGRESS_DROPPED_DELTA
+    && udpIncomplete.delta <= MAX_UDP_INCOMPLETE_DELTA;
+  add(
+    'bounded-frame-queues',
+    boundedQueues,
+    `queueDepth=${maxAgentQueueDepth ?? 'unknown'}, `
+      + `agentDroppedDelta=${agentDropped.delta ?? 'unknown'}, `
+      + `hubDroppedDelta=${hubDropped.delta ?? 'unknown'}, `
+      + `udpIncompleteDelta=${udpIncomplete.delta ?? 'unknown'}`);
+
+  const failed = checks.filter(check => !check.ok);
+  const phaseLatencies = observedFrames.map(frame => optionalFinite(frame?.phaseLatencyMs));
+  return {
+    status: failed.length === 0 ? 'passed' : 'blocked',
+    summary: failed.length === 0
+      ? 'Direct, UDP P2P, encrypted relay, and Direct recovery were proven by independent received H.264 access units.'
+      : `Physical transport proof is incomplete (${failed.map(check => check.id).join(', ')}).`,
+    checks,
+    metrics: {
+      maxPhaseLatencyMs: phaseLatencies.every(value => value !== null)
+        ? Math.max(...phaseLatencies)
+        : null,
+      maxAgentQueueDepth,
+      agentQueueDroppedDelta: agentDropped.delta,
+      hubIngressDroppedDelta: hubDropped.delta,
+      udpIncompleteFramesDelta: udpIncomplete.delta,
+      observedTransports: observedFrames.map(frame => hubObservedTransport(frame).label)
+    }
+  };
+}
+
+export function buildTransportPhysicalReport(snapshot, context = {}) {
+  const classified = classifyTransportPhysicalSnapshot(snapshot);
+  const report = redactTransportPhysicalReport({
+    schema: 'livedesk.transport-physical.v2',
+    generatedAt: new Date().toISOString(),
+    hubUrl: context.hubUrl,
+    selectedDeviceId: context.deviceId,
+    provenance: buildTransportPhysicalProvenance(context.provenance),
+    result: classified,
+    transport: snapshot
+  });
+  const leaks = findTransportPhysicalReportLeaks(report);
+  if (leaks.length > 0) {
+    throw new Error(`transport-physical-report-redaction-failed:${leaks.join(',')}`);
+  }
+  return report;
+}
+
+export {
+  MAX_HUB_ADDRESS_OBSERVATION_SKEW_MS,
+  MAX_PHASE_LATENCY_MS,
+  REQUIRED_PHASES
+};