Skip to content
Python
37.5 KB
Raw Blame
import { randomUUID } from "node:crypto";
import {
  appendFileSync,
  chmodSync,
  constants,
  lstatSync,
  mkdirSync,
  renameSync,
  rmSync,
  statSync,
} from "node:fs";
import {
  appendFile,
  chmod,
  link,
  lstat,
  mkdir,
  open,
  readdir,
  rename,
  rm,
  stat,
  statfs,
  writeFile,
} from "node:fs/promises";
import os from "node:os";
import path from "node:path";
import { strToU8, zipSync } from "fflate";

export const DIAGNOSTIC_SCHEMA_VERSION = 1 as const;
export const DIAGNOSTIC_MAX_FILE_BYTES = 4 * 1024 * 1024;
export const DIAGNOSTIC_MAX_TOTAL_BYTES = 128 * 1024 * 1024;
export const DIAGNOSTIC_MAX_AGE_MS = 14 * 24 * 60 * 60 * 1000;

export type DiagnosticLevel = "debug" | "info" | "warn" | "error";
export type DiagnosticService =
  | "runtime"
  | "core"
  | "host-bridge"
  | "desktop"
  | "cli";

export interface DiagnosticEventV1 {
  schema_version: 1;
  timestamp: string;
  level: DiagnosticLevel;
  service: DiagnosticService;
  component: string;
  event: string;
  outcome: string;
  session_id: string;
  trace_id?: string;
  incident_id?: string;
  instance_id?: string;
  operation_id?: string;
  request_id?: string;
  job_id?: string;
  task_id?: string;
  /** Package identity, so a four-level chain can be attributed to a build.
   *  Optional: an ad-hoc source run has no package and must not invent one. */
  build_id?: string;
  package_id?: string;
  round?: string;
  duration_ms?: number;
  state_before?: string;
  state_after?: string;
  error_code?: string;
  error_type?: string;
  safe_stack?: string[];
  details?: Record<string, string | number | boolean | null>;
}

export interface DiagnosticInput
  extends Omit<
    DiagnosticEventV1,
    "schema_version" | "timestamp" | "service" | "session_id"
  > {
  timestamp?: string;
}

export interface DiagnosticLoggerOptions {
  dataDir: string;
  service: DiagnosticService;
  sessionId?: string;
  now?: () => Date;
  maxFileBytes?: number;
}

export interface DiagnosticSink {
  log(input: DiagnosticInput): Promise<void>;
}

const NAME =
  /^diagnostic-(runtime|core|host-bridge|desktop|cli)\.jsonl(?:\.\d+)?$/;
const CODE_FRAME =
  /^(?:(?:apps|packages|scripts)\/(?:[A-Za-z0-9_-]+\/)*[A-Za-z0-9_.-]+:\d+:\d+|one_memory\/(?:[A-Za-z0-9_-]+\/)*[A-Za-z0-9_.-]+:\d+:[A-Za-z_][A-Za-z0-9_]*|[A-Za-z0-9_][A-Za-z0-9_.-]*\.py:\d+:[A-Za-z_][A-Za-z0-9_]*)$/;
const THREAD_STACK = /^thread\|(.+)$/;
const SHORT_CREDENTIAL_TOKEN =
  /(^|[^A-Za-z0-9])([A-Za-z0-9]{24,47})(?:[_-])?(?=$|[^A-Za-z0-9])/g;
const IDENTIFIER = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,255}$/;
const EVENT_NAME = /^[a-z][a-z0-9]*(?:[._-][a-z0-9]+){0,15}$/;
const DETAIL_KEY = /^[A-Za-z][A-Za-z0-9_.-]{0,63}$/;
const DANGEROUS_DETAIL_KEYS = new Set([
  "__proto__",
  "prototype",
  "constructor",
]);
const MAX_DETAIL_KEYS = 32;
const EXPORT_SECRET_MARKER =
  /(?:^|[._:-])(?:authorization|credential|password|prompt|query|secret|token)(?:$|[._:-])/i;
const EXPORTED_STRING_DETAIL_KEYS = new Set([
  "action",
  "method",
  "mode",
  "phase",
  "platform",
  "reason",
  "source_id",
  "status",
  "version",
  "parent_session_id",
  "runtime_state",
  "core_state",
  "broker_state",
  "instance_id",
  "operation_kind",
  "file_kind",
  "last_probe",
  "signal",
]);
const EXPORTED_NUMBER_DETAIL_KEYS = new Set([
  "attempt",
  "count",
  "status_code",
  "result_count",
  "invalid_lines",
  "open_file_count",
  "memory_bytes",
  "thread_count",
  "database_error_count",
  "file_count",
  "sqlite_file_count",
  "byte_file_count",
  "total_bytes",
  "copied_bytes",
  "bytes_per_second",
  "stored_count",
  "revised_count",
  "skipped_count",
  "error_count",
  "restart_streak",
  "pending_count",
  "prepared_count",
  "queue_depth",
  "in_flight_count",
  "call_count",
  "created_count",
  "updated_count",
  "superseded_count",
  "deleted_count",
  "attempts",
  "delay_ms",
  "budget_ms",
  "port",
  "exit_code",
]);
const EXPORTED_BOOLEAN_DETAIL_KEYS = new Set(["spawned", "truncated"]);
const EVENT_KEYS = new Set([
  "schema_version",
  "timestamp",
  "level",
  "service",
  "component",
  "event",
  "outcome",
  "session_id",
  "trace_id",
  "incident_id",
  "instance_id",
  "operation_id",
  "request_id",
  "job_id",
  "task_id",
  "build_id",
  "package_id",
  "round",
  "duration_ms",
  "state_before",
  "state_after",
  "error_code",
  "error_type",
  "safe_stack",
  "details",
]);

/** Package identity from the environment the shared spawn point populates.
 *
 * Only fields that are actually present are returned, so a source run writes no
 * identity rather than a fabricated one.
 */
function buildIdentityFromEnvironment(
  environment: NodeJS.ProcessEnv = process.env,
): Pick<DiagnosticEventV1, "build_id" | "package_id" | "round"> {
  const identity: Pick<DiagnosticEventV1, "build_id" | "package_id" | "round"> =
    {};
  const buildId = environment.ONE_MEMORY_BUILD_ID?.trim();
  const packageId = environment.ONE_MEMORY_PACKAGE_ID?.trim();
  const round = environment.ONE_MEMORY_ROUND?.trim();
  if (buildId) identity.build_id = buildId;
  if (packageId) identity.package_id = packageId;
  if (round) identity.round = round;
  return identity;
}

export class DiagnosticLogger {
  readonly sessionId: string;
  private readonly options: DiagnosticLoggerOptions;
  private tail: Promise<void> = Promise.resolve();

  constructor(options: DiagnosticLoggerOptions) {
    this.options = options;
    this.sessionId = canonicalUuid(options.sessionId) ?? randomUUID();
  }

  log(input: DiagnosticInput): Promise<void> {
    let event: DiagnosticEventV1;
    try {
      event = diagnosticEvent({
        // A package build stamps its identity into the environment at the shared
        // spawn point; copy it onto every event so one chain can be attributed to
        // one package. A source run leaves them unset and writes nothing.
        ...buildIdentityFromEnvironment(),
        ...input,
        service: this.options.service,
        session_id: this.sessionId,
        timestamp:
          input.timestamp ??
          (this.options.now ?? (() => new Date()))().toISOString(),
      });
    } catch {
      // Diagnostics are observational. A malformed event must be dropped rather
      // than turn a logging mistake into a product outage. The pure validator
      // stays strict so tests and export paths can still reject unsafe records.
      return this.tail;
    }
    this.tail = this.tail.then(() => this.write(event)).catch(() => undefined);
    return this.tail;
  }

  async markIncident(input: {
    component: string;
    traceId?: string;
    instanceId?: string;
    status?: string;
  }): Promise<{ incident_id: string; session_id: string; timestamp: string }> {
    const incidentId = randomUUID();
    const timestamp = (this.options.now ?? (() => new Date()))().toISOString();
    await this.log({
      timestamp,
      level: "info",
      component: input.component,
      event: "incident.marked",
      outcome: "recorded",
      incident_id: incidentId,
      ...(input.traceId ? { trace_id: input.traceId } : {}),
      ...(input.instanceId ? { instance_id: input.instanceId } : {}),
      details: { status: input.status ?? "unknown" },
    });
    return { incident_id: incidentId, session_id: this.sessionId, timestamp };
  }

  private async write(event: DiagnosticEventV1): Promise<void> {
    const directory = await ensureDiagnosticDirectory(this.options.dataDir);
    await pruneDiagnosticLogs(
      this.options.dataDir,
      new Date(event.timestamp).getTime(),
    );
    const target = path.join(
      directory,
      `diagnostic-${this.options.service}.jsonl`,
    );
    const line = `${JSON.stringify(event)}\n`;
    const current = await stat(target).catch(() => null);
    if (
      current &&
      current.size + Buffer.byteLength(line) >
        (this.options.maxFileBytes ?? DIAGNOSTIC_MAX_FILE_BYTES)
    ) {
      await rotate(target);
    }
    await appendFile(target, line, { encoding: "utf8", mode: 0o600 });
    await chmod(target, 0o600);
  }
}

/** Persist one fatal startup event before Electron can terminate the process. */
export function writeDiagnosticEventSync(
  options: DiagnosticLoggerOptions,
  input: DiagnosticInput,
): void {
  try {
    const event = diagnosticEvent({
      ...buildIdentityFromEnvironment(),
      ...input,
      service: options.service,
      session_id: canonicalUuid(options.sessionId) ?? randomUUID(),
      timestamp:
        input.timestamp ?? (options.now ?? (() => new Date()))().toISOString(),
    });
    const directory = diagnosticDirectory(options.dataDir);
    mkdirSync(directory, { recursive: true, mode: 0o700 });
    const directoryInfo = lstatSync(directory);
    if (!directoryInfo.isDirectory() || directoryInfo.isSymbolicLink())
      fail("diagnostic_directory_unsafe");
    chmodSync(directory, 0o700);
    const target = path.join(directory, `diagnostic-${options.service}.jsonl`);
    const line = `${JSON.stringify(event)}\n`;
    let current: ReturnType<typeof statSync> | null = null;
    try {
      current = statSync(target);
    } catch (error) {
      if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
    }
    if (
      current &&
      current.size + Buffer.byteLength(line) >
        (options.maxFileBytes ?? DIAGNOSTIC_MAX_FILE_BYTES)
    ) {
      rotateSync(target);
    }
    appendFileSync(target, line, { encoding: "utf8", mode: 0o600 });
    chmodSync(target, 0o600);
  } catch {
    // A synchronous fatal-path diagnostic must never replace the business error.
  }
}

export function diagnosticEvent(
  value: Omit<DiagnosticEventV1, "schema_version">,
): DiagnosticEventV1 {
  for (const key of Object.keys(value)) {
    if (!EVENT_KEYS.has(key)) fail("diagnostic_field_invalid");
  }
  if (typeof value.timestamp !== "string") fail("diagnostic_timestamp_invalid");
  const timestamp = new Date(value.timestamp);
  if (Number.isNaN(timestamp.getTime())) fail("diagnostic_timestamp_invalid");
  if (
    typeof value.component !== "string" ||
    typeof value.event !== "string" ||
    !EVENT_NAME.test(value.component) ||
    !EVENT_NAME.test(value.event)
  )
    fail("diagnostic_event_invalid");
  if (!(["debug", "info", "warn", "error"] as const).includes(value.level))
    fail("diagnostic_level_invalid");
  if (
    !(["runtime", "core", "host-bridge", "desktop", "cli"] as const).includes(
      value.service,
    )
  )
    fail("diagnostic_service_invalid");
  if (typeof value.outcome !== "string" || !IDENTIFIER.test(value.outcome))
    fail("diagnostic_outcome_invalid");
  if (typeof value.session_id !== "string" || !canonicalUuid(value.session_id))
    fail("diagnostic_session_invalid");
  for (const key of [
    "trace_id",
    "incident_id",
    "instance_id",
    "operation_id",
    "request_id",
    "job_id",
    "task_id",
    "build_id",
    "package_id",
    "round",
  ] as const) {
    const item = value[key];
    if (
      item !== undefined &&
      (typeof item !== "string" || !IDENTIFIER.test(item))
    )
      fail("diagnostic_identifier_invalid");
  }
  for (const key of [
    "state_before",
    "state_after",
    "error_code",
    "error_type",
  ] as const) {
    const item = value[key];
    if (
      item !== undefined &&
      (typeof item !== "string" || !IDENTIFIER.test(item))
    )
      fail("diagnostic_text_field_invalid");
  }
  if (
    value.duration_ms !== undefined &&
    (!Number.isSafeInteger(value.duration_ms) || value.duration_ms < 0)
  )
    fail("diagnostic_duration_invalid");
  const details = sanitizeDetails(value.details);
  const stack =
    value.safe_stack === undefined ? undefined : safeStack(value.safe_stack);
  const { details: _details, safe_stack: _safeStack, ...event } = value;
  return Object.freeze({
    schema_version: DIAGNOSTIC_SCHEMA_VERSION,
    ...event,
    timestamp: timestamp.toISOString(),
    ...(details ? { details } : {}),
    ...(stack ? { safe_stack: stack } : {}),
  });
}

export async function readDiagnosticEvents(
  dataDir: string,
  filter: {
    since?: Date;
    sessionId?: string;
    traceId?: string;
    incidentId?: string;
    operationId?: string;
    requestId?: string;
    jobId?: string;
    taskId?: string;
    component?: string;
    event?: string;
    errorsOnly?: boolean;
    tail?: number;
  } = {},
): Promise<{
  events: DiagnosticEventV1[];
  invalid_lines: number;
  unrecognized_lines: number;
}> {
  const files = await diagnosticLogFiles(dataDir);
  let events: DiagnosticEventV1[] = [];
  // Only a line that is not JSON at all is damage. A whole JSON line this
  // reader does not accept (an older build's record, another schema) is left
  // out and counted apart, so an upgrade does not read as a broken log.
  let invalidLines = 0;
  let unrecognizedLines = 0;
  for (const file of files) {
    const content = await readRegularFileNoFollow(
      file,
      "diagnostic_file_unsafe",
    );
    for (const line of content.split("\n")) {
      if (!line) continue;
      let value: unknown;
      try {
        value = JSON.parse(line);
      } catch {
        invalidLines += 1;
        continue;
      }
      try {
        events.push(parseDiagnosticEvent(value));
      } catch {
        unrecognizedLines += 1;
      }
    }
  }
  events.sort((a, b) => compareDiagnosticTimestamps(a.timestamp, b.timestamp));
  if (filter.incidentId) {
    const marker = events.find(
      (item) => item.incident_id === filter.incidentId,
    );
    if (!marker) events = [];
    else {
      const markedAt = new Date(marker.timestamp).getTime();
      events = events.filter(
        (item) =>
          (item.session_id === marker.session_id ||
            (marker.instance_id !== undefined &&
              item.instance_id === marker.instance_id)) &&
          new Date(item.timestamp).getTime() >= markedAt - 15 * 60_000 &&
          new Date(item.timestamp).getTime() <= markedAt + 5 * 60_000,
      );
    }
  }
  events = events.filter((item) => {
    if (filter.since && new Date(item.timestamp) < filter.since) return false;
    if (filter.sessionId && item.session_id !== filter.sessionId) return false;
    if (filter.traceId && item.trace_id !== filter.traceId) return false;
    if (filter.operationId && item.operation_id !== filter.operationId)
      return false;
    if (filter.requestId && item.request_id !== filter.requestId) return false;
    if (filter.jobId && item.job_id !== filter.jobId) return false;
    if (filter.taskId && item.task_id !== filter.taskId) return false;
    if (filter.component && item.component !== filter.component) return false;
    if (filter.event && item.event !== filter.event) return false;
    return !(filter.errorsOnly && item.level !== "error");
  });
  const tail = Math.min(Math.max(filter.tail ?? 200, 1), 5_000);
  return {
    events: events.slice(-tail),
    invalid_lines: invalidLines,
    unrecognized_lines: unrecognizedLines,
  };
}

export async function exportDiagnosticBundle(options: {
  dataDir: string;
  target: string;
  productVersion: string;
  status?: Record<string, string | number | boolean | null>;
}): Promise<{ event_count: number; invalid_lines: number }> {
  const result = await readDiagnosticEvents(options.dataDir, { tail: 5_000 });
  if (result.invalid_lines > 0) fail("diagnostic_export_invalid_lines");
  const events = result.events.map(projectDiagnosticEventForSafeOutput);
  const payload = {
    schema_version: 1,
    exported_at: new Date().toISOString(),
    product_version: exportProductVersion(options.productVersion),
    platform: process.platform,
    arch: process.arch,
    status: projectExportDetails(options.status),
    event_count: events.length,
    invalid_lines: 0,
    events,
  };
  const directory = path.dirname(options.target);
  await mkdir(directory, { recursive: true });
  const temporary = path.join(
    directory,
    `.one-memory-diagnostics-${randomUUID()}.tmp`,
  );
  try {
    await appendFile(temporary, `${JSON.stringify(payload, null, 2)}\n`, {
      encoding: "utf8",
      mode: 0o600,
      flag: "wx",
    });
    await chmod(temporary, 0o600);
    await publishTemporaryFile(temporary, options.target);
  } catch (error) {
    await rm(temporary, { force: true }).catch(() => undefined);
    throw error;
  }
  return {
    event_count: result.events.length,
    invalid_lines: result.invalid_lines,
  };
}

export interface DiagnosticMarker {
  timestamp: string;
  description: string;
}

const MARKER_FILE = "problem-markers.jsonl";
const MARKER_DESCRIPTION = "user_marked_incident";

export async function recordDiagnosticMarker(
  dataDir: string,
  marker: DiagnosticMarker,
  home = os.homedir(),
): Promise<void> {
  const safe = validateDiagnosticMarker(marker, home);
  const directory = await ensureDiagnosticDirectory(dataDir);
  const target = path.join(directory, MARKER_FILE);
  await refuseUnsafeExistingFile(target, "diagnostic_marker_file_unsafe");
  const handle = await open(
    target,
    constants.O_WRONLY |
      constants.O_CREAT |
      constants.O_APPEND |
      (constants.O_NOFOLLOW ?? 0),
    0o600,
  );
  try {
    const info = await handle.stat();
    if (!info.isFile()) fail("diagnostic_marker_file_unsafe");
    await handle.appendFile(`${JSON.stringify(safe)}\n`, "utf8");
    await handle.chmod(0o600);
  } finally {
    await handle.close();
  }
}

async function readDiagnosticMarkers(
  dataDir: string,
  home: string,
): Promise<DiagnosticMarker[]> {
  const target = path.join(diagnosticDirectory(dataDir), MARKER_FILE);
  let raw: string;
  try {
    raw = await readRegularFileNoFollow(
      target,
      "diagnostic_marker_file_unsafe",
    );
  } catch (error) {
    if ((error as NodeJS.ErrnoException).code === "ENOENT") return [];
    throw error;
  }
  const markers: DiagnosticMarker[] = [];
  for (const line of raw.split("\n")) {
    if (!line) continue;
    let value: unknown;
    try {
      value = JSON.parse(line);
    } catch {
      fail("diagnostic_marker_invalid");
    }
    markers.push(validateDiagnosticMarker(value, home));
  }
  return markers.slice(-50);
}

export function diagnosticZipFilename(build: string, now = new Date()): string {
  const two = (value: number) => String(value).padStart(2, "0");
  const stamp = `${now.getFullYear()}${two(now.getMonth() + 1)}${two(now.getDate())}-${two(now.getHours())}${two(now.getMinutes())}`;
  const safeBuild = build.trim().replace(/[^0-9A-Za-z._-]+/g, "-") || "unknown";
  return `MemHub-日志-${safeBuild}-${stamp}.zip`;
}

export async function exportDiagnosticZip(options: {
  dataDir: string;
  target: string;
  productVersion: string;
  commit?: string;
  coreSha256?: string;
  home?: string;
  crashReportsDir?: string;
  now?: Date;
  markers?: DiagnosticMarker[];
  summary?: Record<string, unknown>;
}): Promise<{ filename: string; file_count: number }> {
  const now = options.now ?? new Date();
  const home = options.home ?? os.homedir();
  const cutoff = new Date(now.getTime() - 7 * 24 * 60 * 60 * 1000);
  const result = await readDiagnosticEvents(options.dataDir, {
    since: cutoff,
    tail: 5_000,
  });
  if (result.invalid_lines > 0) fail("diagnostic_export_invalid_lines");
  const events = result.events.map(projectDiagnosticEventForSafeOutput);
  const markers = options.markers
    ? options.markers
        .map((marker) => validateDiagnosticMarker(marker, home))
        .slice(-50)
    : await readDiagnosticMarkers(options.dataDir, home);
  const disk = await statfs(options.dataDir).catch(() => null);
  const background = projectSummaryBackground(options.summary);
  const summary = {
    schema_version: 1,
    exported_at: now.toISOString(),
    build: exportProductVersion(options.productVersion),
    commit: options.commit ? exportCommit(options.commit) : null,
    core_sha256: options.coreSha256 ? exportSha256(options.coreSha256) : null,
    system: {
      macos_version: process.platform === "darwin" ? os.release() : null,
      platform: process.platform,
      arch: process.arch,
      chip: os.cpus()[0]?.model ?? "unknown",
      memory_bytes: os.totalmem(),
      free_disk_bytes: disk ? disk.bavail * disk.bsize : null,
    },
    problem_markers: markers,
    ...(background ? { background } : {}),
  };
  const eventLines = events.map((event) => JSON.stringify(event)).join("\n");
  const archive: Record<string, Uint8Array> = {
    "diagnostics/events.jsonl": strToU8(
      eventLines.length > 0 ? `${eventLines}\n` : "",
    ),
    "summary.json": strToU8(`${JSON.stringify(summary, null, 2)}\n`),
    "README.txt": strToU8(
      [
        "MemHub diagnostics",
        "",
        "包含:最近 7 天通过安全白名单重新投影的诊断事件,以及不含正文的状态摘要。",
        "不包含:原始日志、崩溃报告、对话原文、记忆内容、API Key、token 或宿主凭证。",
        ...(markers.length
          ? [
              "",
              "问题时间点:",
              ...markers.map(
                (marker) => `${marker.timestamp}  ${marker.description}`,
              ),
            ]
          : []),
        "",
      ].join("\n"),
    ),
  };
  const directory = path.dirname(options.target);
  await mkdir(directory, { recursive: true });
  const temporary = path.join(directory, `.memhub-logs-${randomUUID()}.tmp`);
  try {
    await writeFile(temporary, zipSync(archive, { level: 6 }), {
      mode: 0o600,
      flag: "wx",
    });
    await chmod(temporary, 0o600);
    await publishTemporaryFile(temporary, options.target);
  } catch (error) {
    await rm(temporary, { force: true }).catch(() => undefined);
    throw error;
  }
  return {
    filename: path.basename(options.target),
    file_count: Object.keys(archive).length,
  };
}

async function publishTemporaryFile(
  temporary: string,
  target: string,
): Promise<void> {
  // A hard link publishes the already-permissioned inode atomically and refuses
  // to overwrite an existing target. That avoids both stale-file confusion and
  // the rename-then-chmod window where a later failure leaves a false success.
  await link(temporary, target);
  await rm(temporary, { force: true }).catch(() => undefined);
}

export function projectDiagnosticEventForSafeOutput(
  event: DiagnosticEventV1,
): DiagnosticEventV1 {
  const details = projectExportDetails(event.details);
  const stack = projectSafeStack(event.safe_stack);
  const optional: Partial<DiagnosticEventV1> = {};
  for (const key of [
    "trace_id",
    "incident_id",
    "instance_id",
    "operation_id",
    "request_id",
    "job_id",
    "task_id",
    "build_id",
    "package_id",
    "round",
    "state_before",
    "state_after",
    "error_code",
    "error_type",
  ] as const) {
    const value = event[key];
    if (value !== undefined && isExportIdentifier(value)) optional[key] = value;
  }
  return {
    schema_version: DIAGNOSTIC_SCHEMA_VERSION,
    timestamp: event.timestamp,
    level: event.level,
    service: event.service,
    component: isExportIdentifier(event.component)
      ? event.component
      : "diagnostic.redacted",
    event: isExportIdentifier(event.event)
      ? event.event
      : "diagnostic.redacted",
    outcome: isExportIdentifier(event.outcome) ? event.outcome : "redacted",
    session_id: event.session_id,
    ...optional,
    ...(event.duration_ms === undefined ||
    !Number.isSafeInteger(event.duration_ms)
      ? {}
      : { duration_ms: event.duration_ms }),
    ...(stack === undefined ? {} : { safe_stack: stack }),
    ...(details === undefined ? {} : { details }),
  };
}

function projectExportDetails(
  value: Record<string, unknown> | undefined,
): Record<string, string | number | boolean | null> | undefined {
  if (!value || typeof value !== "object" || Array.isArray(value))
    return undefined;
  const result: Record<string, string | number | boolean | null> = {};
  for (const [key, item] of Object.entries(value)) {
    if (
      EXPORTED_STRING_DETAIL_KEYS.has(key) &&
      typeof item === "string" &&
      isExportIdentifier(item)
    ) {
      result[key] = item;
    } else if (
      EXPORTED_NUMBER_DETAIL_KEYS.has(key) &&
      typeof item === "number" &&
      isJsonSafeNumber(item)
    ) {
      result[key] = item;
    } else if (
      EXPORTED_BOOLEAN_DETAIL_KEYS.has(key) &&
      typeof item === "boolean"
    ) {
      result[key] = item;
    }
  }
  return Object.keys(result).length > 0 ? result : undefined;
}

function validateDiagnosticMarker(
  value: unknown,
  _home: string,
): DiagnosticMarker {
  if (!value || typeof value !== "object" || Array.isArray(value))
    fail("diagnostic_marker_invalid");
  const marker = value as Record<string, unknown>;
  const keys = Object.keys(marker);
  if (
    keys.length !== 2 ||
    !keys.includes("timestamp") ||
    !keys.includes("description") ||
    typeof marker.timestamp !== "string" ||
    typeof marker.description !== "string"
  )
    fail("diagnostic_marker_invalid");
  const timestamp = new Date(marker.timestamp);
  if (Number.isNaN(timestamp.getTime())) fail("diagnostic_marker_invalid");
  return {
    timestamp: timestamp.toISOString(),
    description: redactString(MARKER_DESCRIPTION, _home),
  };
}

function projectSummaryBackground(
  summary: Record<string, unknown> | undefined,
): Record<string, string> | undefined {
  if (!summary || typeof summary !== "object" || Array.isArray(summary))
    return undefined;
  const candidate = summary.background;
  if (!candidate || typeof candidate !== "object" || Array.isArray(candidate))
    return undefined;
  const source = candidate as Record<string, unknown>;
  const background: Record<string, string> = {};
  for (const key of [
    "status",
    "runtime_state",
    "core_state",
    "broker_state",
    "instance_id",
  ]) {
    const value = source[key];
    if (typeof value === "string" && isExportIdentifier(value))
      background[key] = value;
  }
  return Object.keys(background).length > 0 ? background : undefined;
}

function redactString(value: string, home: string): string {
  const withoutHome = (home ? value.split(home).join("~") : value)
    .replace(/\/Users\/[^/\s"']+/g, "~")
    .replace(/\b[A-Za-z]:\\Users\\[^\\\s"']+/g, "~");
  return withoutHome
    .replace(/\bBearer\s+[^\s"']+/gi, "Bearer [redacted]")
    .replace(/\b(?:sk|omhg|ghp|github_pat)_[A-Za-z0-9._-]+\b/gi, "[redacted]")
    .replace(/\bsk-[A-Za-z0-9._-]+\b/gi, "[redacted]")
    .replace(/\bxox[baprs]-[A-Za-z0-9-]+\b/gi, "[redacted]")
    .replace(/\b(?:AKIA|ASIA)[A-Z0-9]{16}\b/g, "[redacted]")
    .replace(/\bAKID[A-Za-z0-9]{12,}\b/g, "[redacted]")
    .replace(/\bAIza[A-Za-z0-9_-]{20,}\b/g, "[redacted]")
    .replace(/\bGOCSPX-[A-Za-z0-9_-]+\b/g, "[redacted]")
    .replace(SHORT_CREDENTIAL_TOKEN, (match, prefix: string, token: string) =>
      isConservativeShortCredential(token) ? `${prefix}[redacted]` : match,
    )
    .replace(
      /\b[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b/g,
      "[redacted]",
    )
    .replace(
      /\b(?=[A-Za-z0-9._-]{48,}\b)(?=[A-Za-z0-9._-]*[A-Za-z])(?=[A-Za-z0-9._-]*\d)[A-Za-z0-9._-]+\b/g,
      "[redacted]",
    )
    .replace(
      /\b(api[_-]?key|authorization|credential|password|secret|token)\s*[:=]\s*[^\s,;"']+/gi,
      "$1=[redacted]",
    );
}

async function refuseUnsafeExistingFile(
  target: string,
  code: string,
): Promise<void> {
  try {
    const info = await lstat(target);
    if (!info.isFile() || info.isSymbolicLink()) fail(code);
  } catch (error) {
    if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
  }
}

async function readRegularFileNoFollow(
  target: string,
  code: string,
): Promise<string> {
  await refuseUnsafeExistingFile(target, code);
  const handle = await open(
    target,
    constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0),
  );
  try {
    const info = await handle.stat();
    if (!info.isFile()) fail(code);
    return await handle.readFile("utf8");
  } finally {
    await handle.close();
  }
}

export async function diagnosticLogFiles(dataDir: string): Promise<string[]> {
  const directory = diagnosticDirectory(dataDir);
  let directoryInfo: Awaited<ReturnType<typeof lstat>>;
  try {
    directoryInfo = await lstat(directory);
  } catch (error) {
    if ((error as NodeJS.ErrnoException).code === "ENOENT") return [];
    throw error;
  }
  if (!directoryInfo.isDirectory() || directoryInfo.isSymbolicLink())
    fail("diagnostic_directory_unsafe");
  const entries = await readdir(directory, { withFileTypes: true });
  const files: Array<{ path: string; mtime: number }> = [];
  for (const entry of entries) {
    if (!entry.isFile() || entry.isSymbolicLink() || !NAME.test(entry.name))
      continue;
    const target = path.join(directory, entry.name);
    const info = await lstat(target);
    if (!info.isFile() || info.isSymbolicLink()) continue;
    files.push({ path: target, mtime: info.mtimeMs });
  }
  return files.sort((a, b) => a.mtime - b.mtime).map((item) => item.path);
}

export async function pruneDiagnosticLogs(
  dataDir: string,
  now = Date.now(),
  maxTotalBytes = DIAGNOSTIC_MAX_TOTAL_BYTES,
): Promise<void> {
  const files = await diagnosticLogFiles(dataDir);
  const retained: Array<{ path: string; size: number; mtime: number }> = [];
  for (const file of files) {
    const info = await stat(file);
    if (now - info.mtimeMs > DIAGNOSTIC_MAX_AGE_MS)
      await rm(file, { force: true });
    else retained.push({ path: file, size: info.size, mtime: info.mtimeMs });
  }
  let total = retained.reduce((sum, item) => sum + item.size, 0);
  for (const item of retained.sort((a, b) => a.mtime - b.mtime)) {
    if (total <= maxTotalBytes) break;
    await rm(item.path, { force: true });
    total -= item.size;
  }
}

export function diagnosticError(error: unknown): {
  error_type: string;
  safe_stack?: string[];
} {
  if (!(error instanceof Error)) return { error_type: "UnknownError" };
  const stack = (error.stack ?? "")
    .split("\n")
    .flatMap((line) => {
      const match = line.match(
        /((?:apps|packages|scripts)\/[A-Za-z0-9_./-]+:\d+:\d+)/,
      );
      return match?.[1] ? [match[1]] : [];
    })
    .slice(0, 16);
  return {
    error_type: cleanErrorType(error.name),
    ...(stack.length ? { safe_stack: stack } : {}),
  };
}

function diagnosticDirectory(dataDir: string): string {
  if (!path.isAbsolute(dataDir) || /[\0\r\n]/.test(dataDir))
    fail("diagnostic_data_directory_invalid");
  return path.join(dataDir, "logs");
}

async function ensureDiagnosticDirectory(dataDir: string): Promise<string> {
  const directory = diagnosticDirectory(dataDir);
  await mkdir(directory, { recursive: true, mode: 0o700 });
  const info = await lstat(directory);
  if (!info.isDirectory() || info.isSymbolicLink())
    fail("diagnostic_directory_unsafe");
  await chmod(directory, 0o700);
  return directory;
}

async function rotate(target: string): Promise<void> {
  await rm(`${target}.3`, { force: true });
  for (let index = 2; index >= 1; index -= 1) {
    await rename(`${target}.${index}`, `${target}.${index + 1}`).catch(
      (error: NodeJS.ErrnoException) => {
        if (error.code !== "ENOENT") throw error;
      },
    );
  }
  await rename(target, `${target}.1`).catch((error: NodeJS.ErrnoException) => {
    if (error.code !== "ENOENT") throw error;
  });
}

function rotateSync(target: string): void {
  rmSync(`${target}.3`, { force: true });
  for (let index = 2; index >= 1; index -= 1) {
    try {
      renameSync(`${target}.${index}`, `${target}.${index + 1}`);
    } catch (error) {
      if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
    }
  }
  try {
    renameSync(target, `${target}.1`);
  } catch (error) {
    if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
  }
}

function parseDiagnosticEvent(value: unknown): DiagnosticEventV1 {
  if (!value || typeof value !== "object" || Array.isArray(value))
    fail("diagnostic_record_invalid");
  const item = value as Record<string, unknown>;
  if (item.schema_version !== 1) fail("diagnostic_record_invalid");
  const validated = diagnosticEvent(
    item as unknown as Omit<DiagnosticEventV1, "schema_version">,
  );
  // Core emits RFC 3339 timestamps with microseconds while JS writers emit
  // milliseconds. `diagnosticEvent()` canonicalizes through `Date` and would
  // otherwise truncate the extra digits, making events within one millisecond
  // sort in file-discovery order rather than chronological order.
  if (
    typeof item.timestamp !== "string" ||
    !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,9})?(?:Z|[+-]\d{2}:\d{2})$/.test(
      item.timestamp,
    )
  )
    fail("diagnostic_timestamp_invalid");
  return Object.freeze({ ...validated, timestamp: item.timestamp });
}

function compareDiagnosticTimestamps(left: string, right: string): number {
  const key = (value: string): bigint => {
    const milliseconds = Date.parse(value);
    if (!Number.isFinite(milliseconds)) fail("diagnostic_timestamp_invalid");
    const fraction = /\.(\d+)(?:Z|[+-]\d{2}:\d{2})$/.exec(value)?.[1] ?? "";
    const nanoseconds = BigInt(`${fraction}000000000`.slice(0, 9));
    return (
      BigInt(Math.floor(milliseconds / 1000)) * 1_000_000_000n + nanoseconds
    );
  };
  const leftKey = key(left);
  const rightKey = key(right);
  return leftKey < rightKey ? -1 : leftKey > rightKey ? 1 : 0;
}

function containsCredentialMaterial(value: string): boolean {
  return (
    /(?:^|[^A-Za-z0-9])(?:sk-|sk_|omhg_|ghp_|github_pat_)[A-Za-z0-9._-]+/i.test(
      value,
    ) ||
    /(?:^|[^A-Za-z0-9])xox[baprs]-[A-Za-z0-9-]+/i.test(value) ||
    /(?:^|[^A-Za-z0-9])(?:AKIA|ASIA)[A-Z0-9]{16}(?![A-Za-z0-9])/.test(value) ||
    /(?:^|[^A-Za-z0-9])AKID[A-Za-z0-9]{12,}/i.test(value) ||
    /(?:^|[^A-Za-z0-9])AIza[A-Za-z0-9_-]{20,}/.test(value) ||
    /(?:^|[^A-Za-z0-9])GOCSPX-[A-Za-z0-9_-]+/.test(value) ||
    hasConservativeShortCredential(value) ||
    /\b[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b/.test(
      value,
    ) ||
    /\b(?=[A-Za-z0-9._-]{48,}\b)(?=[A-Za-z0-9._-]*[A-Za-z])(?=[A-Za-z0-9._-]*\d)[A-Za-z0-9._-]+\b/.test(
      value,
    )
  );
}

function hasConservativeShortCredential(value: string): boolean {
  for (const match of value.matchAll(SHORT_CREDENTIAL_TOKEN)) {
    if (match[2] && isConservativeShortCredential(match[2])) return true;
  }
  return false;
}

function isConservativeShortCredential(value: string): boolean {
  return (
    /[A-Z]/.test(value) &&
    /[a-z]/.test(value) &&
    /\d/.test(value) &&
    !/^[A-Fa-f0-9]+$/.test(value)
  );
}

function looksLikeCredential(value: string): boolean {
  return containsCredentialMaterial(value);
}

function isExportIdentifier(value: string): boolean {
  return (
    IDENTIFIER.test(value) &&
    !EXPORT_SECRET_MARKER.test(value) &&
    !looksLikeCredential(value)
  );
}

function isJsonSafeNumber(value: number): boolean {
  return (
    Number.isFinite(value) &&
    (!Number.isInteger(value) || Number.isSafeInteger(value))
  );
}

function sanitizeDetails(
  value: Record<string, unknown> | undefined,
): Record<string, string | number | boolean | null> | undefined {
  if (value === undefined) return undefined;
  if (!value || typeof value !== "object" || Array.isArray(value))
    fail("diagnostic_details_invalid");
  const prototype = Object.getPrototypeOf(value);
  if (prototype !== Object.prototype && prototype !== null)
    fail("diagnostic_detail_key_invalid");
  const keys = Reflect.ownKeys(value);
  if (keys.length > MAX_DETAIL_KEYS) fail("diagnostic_detail_count_invalid");
  if (keys.some((key) => typeof key !== "string"))
    fail("diagnostic_detail_key_invalid");
  const result: Record<string, string | number | boolean | null> = {};
  for (const [key, item] of Object.entries(value)) {
    if (!DETAIL_KEY.test(key) || DANGEROUS_DETAIL_KEYS.has(key))
      fail("diagnostic_detail_key_invalid");
    if (item === null || typeof item === "boolean") result[key] = item;
    else if (typeof item === "number" && isJsonSafeNumber(item))
      result[key] = item;
    else if (typeof item === "string") result[key] = cleanText(item, 256);
    else fail("diagnostic_detail_value_invalid");
  }
  return Object.keys(result).length ? result : undefined;
}

function projectSafeStack(value: string[] | undefined): string[] | undefined {
  if (!Array.isArray(value)) return undefined;
  const result = value
    .filter((line) => typeof line === "string" && isSafeStackLine(line))
    .slice(0, 16);
  return result.length > 0 ? result : undefined;
}

function safeStack(value: string[]): string[] {
  if (!Array.isArray(value) || value.length > 16)
    fail("diagnostic_stack_invalid");
  return value.map((line) => {
    if (typeof line !== "string" || !isSafeStackLine(line))
      fail("diagnostic_stack_invalid");
    return line;
  });
}

function isSafeStackLine(value: string): boolean {
  if (
    value.length < 1 ||
    value.length > 256 ||
    /[\0\r\n]/.test(value) ||
    containsCredentialMaterial(value)
  )
    return false;
  if (CODE_FRAME.test(value)) return true;
  const aggregate = THREAD_STACK.exec(value)?.[1];
  return (
    aggregate?.split(" > ").every((frame) => CODE_FRAME.test(frame)) === true
  );
}

function exportProductVersion(value: string): string {
  const cleaned = cleanText(value, 128);
  if (!isExportIdentifier(cleaned)) fail("diagnostic_product_version_invalid");
  return cleaned;
}

function exportCommit(value: string): string {
  const cleaned = cleanText(value, 64);
  if (!/^[0-9a-f]{7,64}$/i.test(cleaned)) fail("diagnostic_commit_invalid");
  return cleaned;
}

function exportSha256(value: string): string {
  const cleaned = cleanText(value, 64);
  if (!/^[0-9a-f]{64}$/i.test(cleaned)) fail("diagnostic_sha256_invalid");
  return cleaned;
}

function cleanText(value: string, maximum: number): string {
  if (!value || value.length > maximum || /[\0\r\n]/.test(value))
    fail("diagnostic_text_invalid");
  return value;
}

function cleanErrorType(value: string): string {
  return IDENTIFIER.test(value) ? value : "Error";
}

function canonicalUuid(value: string | undefined): string | null {
  if (!value) return null;
  return /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/.test(
    value,
  )
    ? value
    : null;
}

function fail(code: string): never {
  throw new Error(code);
}