@tryinget/runtime-trace-insights 0.1.0

package/src/runtime_record/runtime_record_flow.mjs

@@ -0,0 +1,1577 @@
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { pathToFileURL } from "node:url";
+
+import {
+  RUNTIME_TRACE_BUNDLE_PROFILES,
+  RUNTIME_TRACE_BUNDLE_SCHEMA_VERSION,
+  buildRuntimeTraceBundle,
+} from "../runtime_trace_bundle/runtime_trace_bundle_builder.mjs";
+
+const DEFAULT_RECORD_ARTIFACT_DIR = "out/depdiet/record";
+const DEFAULT_RUNTIME_TRACE_MANIFEST_PATH = "out/depdiet/runtime/trace-samples.manifest.json";
+const DEFAULT_RUNTIME_TRACE_MANIFEST_RETENTION_COUNT = 30;
+const RUNTIME_TRACE_SCHEMA_VERSION = "depdiet.runtime.trace.v1";
+const RUNTIME_TRACE_MANIFEST_SCHEMA_VERSION = "depdiet.runtime.trace.manifest.v1";
+const APPMAP_SETUP_GUIDANCE_SCHEMA_VERSION = "depdiet.appmap.guidance.v1";
+const RUNTIME_RECORD_RESULT_SCHEMA_VERSION = "depdiet.runtime.record.result.v1";
+// dep-diet `record` artifacts; paths and schema are dep-diet's read contract (see dep-diet
+// src/runtime_record/runtime_record_flow.mjs, whose embedded copy this flow replaces, AK #5892).
+const DEFAULT_RECORD_RUNTIME_TRACE_BUNDLE_PATH = "out/depdiet/runtime/runtime-trace-bundle.json";
+const DEFAULT_DEPVIZ_RUNTIME_HANDOFF_PATH = "out/depdiet/runtime/depviz-runtime-overlay-handoff.json";
+const DEPVIZ_RUNTIME_HANDOFF_SCHEMA_VERSION = "depdiet.depviz.runtime-overlay-handoff.v1";
+const DEPVIZ_RUNTIME_HANDOFF_NON_AUTHORITY_NOTE = "Dep-viz handoff is import guidance for runtime overlays; depmodel production remains dep-diet evidence fusion and visualization semantics remain dep-viz authority.";
+
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function asArray(value) {
+  return Array.isArray(value) ? value : [];
+}
+
+function asNonEmptyString(value) {
+  if (typeof value !== "string") {
+    return null;
+  }
+
+  const normalized = value.trim();
+  return normalized.length > 0 ? normalized : null;
+}
+
+function parseOptionalBoolean(value) {
+  if (typeof value === "boolean") {
+    return value;
+  }
+
+  if (typeof value !== "string") {
+    return null;
+  }
+
+  const normalized = value.trim().toLowerCase();
+
+  if (normalized === "true") {
+    return true;
+  }
+
+  if (normalized === "false") {
+    return false;
+  }
+
+  return null;
+}
+
+function normalizePathSlashes(value) {
+  return String(value).replaceAll("\\", "/");
+}
+
+function toRelativePath(basePath, targetPath) {
+  const relative = path.relative(basePath, targetPath);
+  return normalizePathSlashes(relative.length > 0 ? relative : ".");
+}
+
+function sanitizeSegment(value, {
+  fallback = "record-run",
+  maxLength = 80,
+} = {}) {
+  const base = asNonEmptyString(value) ?? fallback;
+
+  const normalized = String(base)
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]+/gu, "-")
+    .replace(/-+/gu, "-")
+    .replace(/^-|-$/gu, "")
+    .slice(0, maxLength);
+
+  if (normalized.length > 0) {
+    return normalized;
+  }
+
+  return fallback;
+}
+
+function createDiagnostic({
+  code,
+  level = "warning",
+  message,
+  path: diagnosticPath,
+  source,
+  details,
+}) {
+  const diagnostic = {
+    code,
+    level,
+    message,
+  };
+
+  const normalizedPath = asNonEmptyString(diagnosticPath);
+  if (normalizedPath) {
+    diagnostic.path = normalizedPath;
+  }
+
+  const normalizedSource = asNonEmptyString(source);
+  if (normalizedSource) {
+    diagnostic.source = normalizedSource;
+  }
+
+  if (details !== undefined) {
+    diagnostic.details = details;
+  }
+
+  return diagnostic;
+}
+
+function normalizeDiagnosticList(entries, source) {
+  return asArray(entries)
+    .filter((entry) => isPlainObject(entry))
+    .map((entry) => ({
+      ...entry,
+      ...(asNonEmptyString(entry.level) ? {} : { level: "warning" }),
+      ...(asNonEmptyString(entry.source) ? {} : (asNonEmptyString(source) ? { source } : {})),
+    }));
+}
+
+function hasErrorDiagnostic(entries) {
+  return asArray(entries)
+    .some((entry) => String(entry?.level ?? "").toLowerCase() === "error");
+}
+
+function resolveProjectPathInput(options = {}) {
+  return asNonEmptyString(options.projectPath)
+    ?? asNonEmptyString(options.path)
+    ?? null;
+}
+
+function normalizeCommandToken(value) {
+  if (typeof value === "number") {
+    return String(value);
+  }
+
+  return asNonEmptyString(value);
+}
+
+function resolveObservedCommand(options = {}) {
+  const candidates = [];
+
+  if (Array.isArray(options.observedCommand)) {
+    candidates.push(options.observedCommand);
+  }
+
+  if (Array.isArray(options.command)) {
+    candidates.push(options.command);
+  }
+
+  if (Array.isArray(options.commandArgs)) {
+    candidates.push(options.commandArgs);
+  }
+
+  if (Array.isArray(options.argv)) {
+    candidates.push(options.argv);
+  }
+
+  if (Array.isArray(options.args)) {
+    candidates.push(options.args);
+  }
+
+  for (const candidate of candidates) {
+    const tokens = candidate
+      .map((entry) => normalizeCommandToken(entry))
+      .filter(Boolean);
+
+    if (tokens.length > 0) {
+      return tokens;
+    }
+  }
+
+  const commandString = asNonEmptyString(options.commandString)
+    ?? asNonEmptyString(options.cmd)
+    ?? null;
+
+  if (commandString) {
+    return commandString.split(/\s+/u).filter(Boolean);
+  }
+
+  return [];
+}
+
+function toCommandLineString(tokens = []) {
+  return asArray(tokens)
+    .map((token) => {
+      if (!/[\s"'`$]/u.test(token)) {
+        return token;
+      }
+
+      return JSON.stringify(token);
+    })
+    .join(" ");
+}
+
+function isExistingDirectory(targetPath) {
+  try {
+    return fs.existsSync(targetPath) && fs.statSync(targetPath).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+function resolveAppMapAvailabilityOverride(options = {}) {
+  const directCandidates = [
+    options.appMapAvailable,
+    options.appmapAvailable,
+    options.appMapAvailability,
+  ];
+
+  for (const candidate of directCandidates) {
+    const parsed = parseOptionalBoolean(candidate);
+    if (parsed !== null) {
+      return {
+        available: parsed,
+        source: "option",
+      };
+    }
+  }
+
+  const explicitEnv = isPlainObject(options.env)
+    ? options.env
+    : process.env;
+
+  const envParsed = parseOptionalBoolean(
+    explicitEnv.DEPDIET_APPMAP_AVAILABLE,
+  );
+
+  if (envParsed !== null) {
+    return {
+      available: envParsed,
+      source: "env:DEPDIET_APPMAP_AVAILABLE",
+    };
+  }
+
+  return null;
+}
+
+function appMapBinaryCandidates(projectPathAbsolute) {
+  const base = path.join(projectPathAbsolute, "node_modules", ".bin");
+
+  return [
+    path.join(base, "appmap"),
+    path.join(base, "appmap-node"),
+    path.join(base, "appmap-python"),
+    path.join(base, "appmap.cmd"),
+    path.join(base, "appmap-node.cmd"),
+    path.join(base, "appmap-python.cmd"),
+  ];
+}
+
+function detectAppMapPackage(projectPathAbsolute, diagnostics, probes) {
+  const packageJsonAbsolute = path.join(projectPathAbsolute, "package.json");
+
+  if (!fs.existsSync(packageJsonAbsolute)) {
+    probes.push({
+      probe: "package-json",
+      status: "missing",
+      path: packageJsonAbsolute,
+    });
+
+    return false;
+  }
+
+  let packageJson;
+
+  try {
+    packageJson = JSON.parse(fs.readFileSync(packageJsonAbsolute, "utf8"));
+  } catch (error) {
+    diagnostics.push(createDiagnostic({
+      code: "runtimeRecord.appMap.packageJsonParseFailed",
+      level: "warning",
+      source: "runtimeRecord",
+      message: "Failed to parse package.json while probing AppMap availability.",
+      path: "/appMap/probe/packageJson",
+      details: {
+        packageJsonPath: packageJsonAbsolute,
+        error: error instanceof Error ? error.message : String(error),
+      },
+    }));
+
+    probes.push({
+      probe: "package-json",
+      status: "parse-failed",
+      path: packageJsonAbsolute,
+    });
+
+    return false;
+  }
+
+  const dependencySections = [
+    packageJson.dependencies,
+    packageJson.devDependencies,
+    packageJson.optionalDependencies,
+    packageJson.peerDependencies,
+  ]
+    .filter((entry) => isPlainObject(entry));
+
+  const dependencyNames = dependencySections
+    .flatMap((section) => Object.keys(section));
+
+  const appMapDependency = dependencyNames
+    .find((name) => /(^@appland\/appmap$|(^|[-_/])appmap($|[-_/]))/iu.test(String(name)));
+
+  probes.push({
+    probe: "package-json",
+    status: appMapDependency ? "found" : "not-found",
+    path: packageJsonAbsolute,
+    dependencyName: appMapDependency ?? null,
+  });
+
+  return Boolean(appMapDependency);
+}
+
+function probeAppMapAvailability({
+  projectPathAbsolute,
+  options,
+}) {
+  const diagnostics = [];
+  const probes = [];
+
+  const override = resolveAppMapAvailabilityOverride(options);
+  if (override) {
+    probes.push({
+      probe: "override",
+      status: override.available ? "forced-available" : "forced-missing",
+      source: override.source,
+    });
+
+    return {
+      available: override.available,
+      reason: override.available
+        ? "appmap-availability-forced-true"
+        : "appmap-availability-forced-false",
+      probes,
+      diagnostics,
+    };
+  }
+
+  let binaryDetected = false;
+
+  for (const candidatePath of appMapBinaryCandidates(projectPathAbsolute)) {
+    const exists = fs.existsSync(candidatePath);
+
+    probes.push({
+      probe: "local-binary",
+      status: exists ? "found" : "not-found",
+      path: candidatePath,
+    });
+
+    if (exists) {
+      binaryDetected = true;
+      break;
+    }
+  }
+
+  const packageDetected = detectAppMapPackage(projectPathAbsolute, diagnostics, probes);
+
+  if (binaryDetected || packageDetected) {
+    return {
+      available: true,
+      reason: binaryDetected
+        ? "local-appmap-binary-detected"
+        : "appmap-dependency-detected",
+      probes,
+      diagnostics,
+    };
+  }
+
+  return {
+    available: false,
+    reason: "appmap-not-detected",
+    probes,
+    diagnostics,
+  };
+}
+
+function executeObservedCommand({
+  commandTokens,
+  cwd,
+  env,
+}) {
+  const [command, ...args] = commandTokens;
+
+  const startedAt = new Date().toISOString();
+  const started = Date.now();
+
+  const result = spawnSync(command, args, {
+    cwd,
+    shell: false,
+    encoding: "utf8",
+    env: env ?? process.env,
+  });
+
+  const completedAt = new Date().toISOString();
+  const durationMs = Math.max(0, Date.now() - started);
+
+  const errorMessage = result.error ? result.error.message : null;
+  const exitCode = Number.isInteger(result.status) ? result.status : null;
+  const signal = asNonEmptyString(result.signal) ?? null;
+
+  return {
+    ok: !errorMessage && exitCode === 0,
+    command,
+    args,
+    commandLine: toCommandLineString(commandTokens),
+    cwd,
+    exitCode,
+    signal,
+    stdout: String(result.stdout ?? ""),
+    stderr: String(result.stderr ?? ""),
+    errorMessage,
+    startedAt,
+    completedAt,
+    durationMs,
+  };
+}
+
+function optionEnabled(value) {
+  if (value === true) {
+    return true;
+  }
+
+  if (typeof value !== "string") {
+    return false;
+  }
+
+  return ["1", "true", "yes", "on", "auto"].includes(value.trim().toLowerCase());
+}
+
+function nodeOptionsPathToken(value) {
+  const normalized = String(value);
+  if (!/[\s"']/u.test(normalized)) {
+    return normalized;
+  }
+
+  return JSON.stringify(normalized);
+}
+
+function appendNodeOption(existing, option) {
+  const current = asNonEmptyString(existing);
+  return current ? `${current} ${option}` : option;
+}
+
+function createPackageAutodiscoveryInstrumentation({ artifactDirectoryAbsolute, diagnostics }) {
+  const logAbsolutePath = path.join(artifactDirectoryAbsolute, "package-autodiscovery.jsonl");
+  const loaderAbsolutePath = path.join(artifactDirectoryAbsolute, "package-autodiscovery-loader.mjs");
+  const preloadAbsolutePath = path.join(artifactDirectoryAbsolute, "package-autodiscovery-preload.cjs");
+
+  const loaderSource = String.raw`import fs from "node:fs";
+
+const logPath = process.env.RUNTIME_TRACE_PACKAGE_AUTODISCOVERY_LOG;
+
+function emit(event) {
+  if (!logPath) return;
+  try {
+    fs.appendFileSync(logPath, JSON.stringify({ ...event, pid: process.pid, observedAt: new Date().toISOString() }) + "\n", "utf8");
+  } catch {
+    // Runtime observation must not alter target command behavior.
+  }
+}
+
+export async function resolve(specifier, context, nextResolve) {
+  const result = await nextResolve(specifier, context);
+  emit({ kind: "esm-resolve", specifier, parentURL: context.parentURL ?? null, url: result.url ?? null });
+  return result;
+}
+`;
+
+  const preloadSource = String.raw`const fs = require("node:fs");
+const Module = require("node:module");
+const logPath = process.env.RUNTIME_TRACE_PACKAGE_AUTODISCOVERY_LOG;
+const originalLoad = Module._load;
+const originalResolveFilename = Module._resolveFilename;
+
+function emit(event) {
+  if (!logPath) return;
+  try {
+    fs.appendFileSync(logPath, JSON.stringify({ ...event, pid: process.pid, observedAt: new Date().toISOString() }) + "\n", "utf8");
+  } catch {
+    // Runtime observation must not alter target command behavior.
+  }
+}
+
+Module._load = function runtimeTraceAutodiscoveryLoad(request, parent, isMain) {
+  let resolved = null;
+  try {
+    resolved = originalResolveFilename.call(this, request, parent, isMain);
+  } catch {
+    resolved = null;
+  }
+
+  const loaded = originalLoad.apply(this, arguments);
+  emit({ kind: "cjs-load", specifier: request, parentFilename: parent?.filename ?? null, resolvedPath: typeof resolved === "string" ? resolved : null });
+  return loaded;
+};
+`;
+
+  try {
+    fs.writeFileSync(loaderAbsolutePath, loaderSource, "utf8");
+    fs.writeFileSync(preloadAbsolutePath, preloadSource, "utf8");
+    fs.writeFileSync(logAbsolutePath, "", "utf8");
+  } catch (error) {
+    diagnostics.push(createDiagnostic({
+      code: "runtimeRecord.packageAutodiscoverySetupFailed",
+      level: "warning",
+      source: "runtimeRecord",
+      message: "Failed to create package autodiscovery instrumentation; command will run without package autodiscovery.",
+      details: {
+        artifactDirectoryAbsolute,
+        error: error instanceof Error ? error.message : String(error),
+      },
+    }));
+
+    return {
+      enabled: false,
+      reason: "setup-failed",
+      logAbsolutePath,
+      loaderAbsolutePath,
+      preloadAbsolutePath,
+      env: process.env,
+      events: [],
+      diagnostics,
+    };
+  }
+
+  const env = { ...process.env };
+  env.RUNTIME_TRACE_PACKAGE_AUTODISCOVERY_LOG = logAbsolutePath;
+  // ESM loaders take URLs: a bare Windows path (C:\\...) is read as a "c:" URL scheme and rejected.
+  env.NODE_OPTIONS = appendNodeOption(env.NODE_OPTIONS, `--experimental-loader=${nodeOptionsPathToken(pathToFileURL(loaderAbsolutePath).href)}`);
+  env.NODE_OPTIONS = appendNodeOption(env.NODE_OPTIONS, `--require=${nodeOptionsPathToken(preloadAbsolutePath)}`);
+
+  return {
+    enabled: true,
+    reason: "node-options-loader-and-preload",
+    logAbsolutePath,
+    loaderAbsolutePath,
+    preloadAbsolutePath,
+    env,
+    events: [],
+    diagnostics: [],
+  };
+}
+
+function readPackageAutodiscoveryEvents({ logAbsolutePath, diagnostics }) {
+  if (!asNonEmptyString(logAbsolutePath) || !fs.existsSync(logAbsolutePath)) {
+    return [];
+  }
+
+  const events = [];
+  const lines = fs.readFileSync(logAbsolutePath, "utf8")
+    .split(/\r?\n/u)
+    .filter(Boolean);
+
+  for (const line of lines) {
+    try {
+      const parsed = JSON.parse(line);
+      if (isPlainObject(parsed)) {
+        events.push(parsed);
+      }
+    } catch (error) {
+      diagnostics.push(createDiagnostic({
+        code: "runtimeRecord.packageAutodiscoveryEventParseFailed",
+        level: "warning",
+        source: "runtimeRecord",
+        message: "Skipped malformed package autodiscovery event.",
+        details: {
+          error: error instanceof Error ? error.message : String(error),
+        },
+      }));
+    }
+  }
+
+  return events;
+}
+
+function createDepvizRuntimeHandoffArtifact({
+  generatedAt,
+  runId,
+  projectPathInput,
+  observedCommand,
+  execution,
+  diagnostics,
+  runtimeTracePath,
+  runtimeTraceBundlePath,
+  setupGuidancePath,
+  runtimeBundle,
+}) {
+  const normalizedDiagnostics = normalizeDiagnosticList(diagnostics, "runtimeRecord");
+  const overlayImportPermitted = execution.ok && !hasErrorDiagnostic(normalizedDiagnostics);
+
+  return {
+    schemaVersion: DEPVIZ_RUNTIME_HANDOFF_SCHEMA_VERSION,
+    schema_version: DEPVIZ_RUNTIME_HANDOFF_SCHEMA_VERSION,
+    generatedAt,
+    producer: "dep-diet",
+    targetConsumers: ["dep-viz", "dep-diet"],
+    runId,
+    command: {
+      name: "record",
+      projectPath: projectPathInput,
+      observedCommand,
+      commandLine: execution.commandLine,
+      exitCode: execution.exitCode,
+      durationMs: execution.durationMs,
+    },
+    runtimeEvidence: {
+      bundleSchemaVersion: RUNTIME_TRACE_BUNDLE_SCHEMA_VERSION,
+      bundlePath: runtimeTraceBundlePath,
+      bundleId: runtimeBundle.bundleId,
+      observedPackageCount: runtimeBundle.observedPackages.length,
+      diagnosticsPermitOverlayImport: overlayImportPermitted,
+      limitations: [
+        "Runtime observation is command-level evidence only.",
+        "Static/runtime classifications must be produced by dep-diet depmodel fusion before visualization.",
+        "Dep-viz owns rendering and overlay semantics; this handoff does not grant visualization authority.",
+      ],
+    },
+    depmodelHandoff: {
+      preferredConsumerInput: "depmodel.v1",
+      producerCommand: [
+        "depdiet",
+        "analyze",
+        projectPathInput,
+        "--gardener-output",
+        "<gardener-output.json>",
+        "--runtime-bundle",
+        runtimeTraceBundlePath,
+        "--out-depmodel",
+        "<depmodel.v1.json>",
+      ],
+      note: "Pair this runtime bundle with static evidence to emit depmodel.v1 before dep-viz rendering.",
+    },
+    artifacts: {
+      runtimeTrace: runtimeTracePath,
+      runtimeTraceBundle: runtimeTraceBundlePath,
+      setupGuidance: setupGuidancePath,
+    },
+    authority: {
+      removalAuthority: false,
+      riskAuthority: false,
+      visualizationAuthority: false,
+      note: DEPVIZ_RUNTIME_HANDOFF_NON_AUTHORITY_NOTE,
+    },
+    diagnostics: normalizedDiagnostics,
+  };
+}
+
+// Emits dep-diet's `record` artifacts: the runtime trace bundle and the dep-viz runtime overlay handoff.
+function emitRecordHandoffArtifacts({
+  cwd,
+  options,
+  diagnostics,
+  generatedAt,
+  runId,
+  projectPathInput,
+  projectPathAbsolute,
+  observedCommand,
+  execution,
+  packageAutodiscovery,
+  runtimeTracePath,
+  setupGuidancePath,
+}) {
+  const runtimeTraceBundleAbsolutePath = path.resolve(
+    cwd,
+    asNonEmptyString(options.runtimeTraceBundlePath) ?? DEFAULT_RECORD_RUNTIME_TRACE_BUNDLE_PATH,
+  );
+  const runtimeTraceBundlePath = toRelativePath(cwd, runtimeTraceBundleAbsolutePath);
+  const runtimeTraceBundle = buildRuntimeTraceBundle({
+    profile: RUNTIME_TRACE_BUNDLE_PROFILES.depdietRecord,
+    diagnostics,
+    options,
+    generatedAt,
+    runId,
+    bundleId: options.runtimeTraceBundleId,
+    projectPathInput,
+    projectPathAbsolute,
+    observedCommand,
+    commandLine: execution.commandLine,
+    exitCode: execution.exitCode,
+    durationMs: execution.durationMs,
+    packageAutodiscovery,
+    references: [
+      { kind: "runtime-trace", path: runtimeTracePath },
+      { kind: "setup-guidance", path: setupGuidancePath },
+    ],
+  });
+
+  const runtimeTraceBundleWriteOk = writeArtifact(
+    runtimeTraceBundleAbsolutePath,
+    `${JSON.stringify(runtimeTraceBundle, null, 2)}\n`,
+    diagnostics,
+    {
+      code: "runtimeRecord.runtimeTraceBundleWriteFailed",
+      message: "Failed to write dep-viz runtime trace bundle handoff input.",
+      details: {
+        artifact: "runtime-trace-bundle.json",
+      },
+    },
+  );
+
+  const depvizHandoffAbsolutePath = path.resolve(
+    cwd,
+    asNonEmptyString(options.depvizHandoffPath) ?? DEFAULT_DEPVIZ_RUNTIME_HANDOFF_PATH,
+  );
+  const depvizHandoffPath = toRelativePath(cwd, depvizHandoffAbsolutePath);
+  const depvizHandoff = createDepvizRuntimeHandoffArtifact({
+    generatedAt,
+    runId,
+    projectPathInput,
+    observedCommand,
+    execution,
+    diagnostics,
+    runtimeTracePath,
+    runtimeTraceBundlePath,
+    setupGuidancePath,
+    runtimeBundle: runtimeTraceBundle,
+  });
+
+  const depvizHandoffWriteOk = writeArtifact(
+    depvizHandoffAbsolutePath,
+    `${JSON.stringify(depvizHandoff, null, 2)}\n`,
+    diagnostics,
+    {
+      code: "runtimeRecord.depvizHandoffWriteFailed",
+      message: "Failed to write dep-viz runtime overlay handoff artifact.",
+      details: {
+        artifact: "depviz-runtime-overlay-handoff.json",
+      },
+    },
+  );
+
+  return {
+    artifacts: {
+      runtimeTraceBundle: runtimeTraceBundleWriteOk
+        ? {
+          path: runtimeTraceBundlePath,
+          absolutePath: runtimeTraceBundleAbsolutePath,
+          schemaVersion: RUNTIME_TRACE_BUNDLE_SCHEMA_VERSION,
+          schema_version: RUNTIME_TRACE_BUNDLE_SCHEMA_VERSION,
+        }
+        : null,
+      depvizHandoff: depvizHandoffWriteOk
+        ? {
+          path: depvizHandoffPath,
+          absolutePath: depvizHandoffAbsolutePath,
+          schemaVersion: DEPVIZ_RUNTIME_HANDOFF_SCHEMA_VERSION,
+          schema_version: DEPVIZ_RUNTIME_HANDOFF_SCHEMA_VERSION,
+        }
+        : null,
+    },
+    summary: {
+      runtimeTraceBundleEmitted: runtimeTraceBundleWriteOk,
+      depvizHandoffEmitted: depvizHandoffWriteOk,
+      observedPackageCount: runtimeTraceBundle.observedPackages.length,
+    },
+  };
+}
+
+function writeArtifact(absolutePath, content, diagnostics, {
+  code,
+  message,
+  details = {},
+} = {}) {
+  try {
+    fs.writeFileSync(absolutePath, content, "utf8");
+    return true;
+  } catch (error) {
+    diagnostics.push(createDiagnostic({
+      code: code ?? "runtimeRecord.artifactWriteFailed",
+      level: "error",
+      source: "runtimeRecord",
+      message: message ?? "Failed to write runtime record artifact.",
+      path: "/artifacts",
+      details: {
+        artifactPath: absolutePath,
+        error: error instanceof Error ? error.message : String(error),
+        ...details,
+      },
+    }));
+
+    return false;
+  }
+}
+
+function normalizePositiveInteger(value, fallback) {
+  const numeric = Number(value);
+
+  if (!Number.isInteger(numeric) || numeric <= 0) {
+    return fallback;
+  }
+
+  return numeric;
+}
+
+function normalizeRuntimeTraceManifestEntry(rawEntry) {
+  if (!isPlainObject(rawEntry)) {
+    return null;
+  }
+
+  const runId = asNonEmptyString(rawEntry.runId);
+  const tracePath = asNonEmptyString(rawEntry.tracePath)
+    ?? asNonEmptyString(rawEntry.runtimeTracePath)
+    ?? null;
+
+  if (!runId || !tracePath) {
+    return null;
+  }
+
+  return {
+    runId,
+    generatedAt: asNonEmptyString(rawEntry.generatedAt),
+    tracePath,
+    commandLine: asNonEmptyString(rawEntry.commandLine),
+    projectPath: asNonEmptyString(rawEntry.projectPath),
+    appMapAvailable: typeof rawEntry.appMapAvailable === "boolean" ? rawEntry.appMapAvailable : null,
+    commandExitCode: Number.isFinite(rawEntry.commandExitCode)
+      ? Number(rawEntry.commandExitCode)
+      : null,
+    commandDurationMs: Number.isFinite(rawEntry.commandDurationMs)
+      ? Number(rawEntry.commandDurationMs)
+      : null,
+  };
+}
+
+function parseExistingRuntimeTraceManifestEntries(manifestAbsolutePath, diagnostics = []) {
+  if (!fs.existsSync(manifestAbsolutePath)) {
+    return [];
+  }
+
+  let parsed;
+
+  try {
+    parsed = JSON.parse(fs.readFileSync(manifestAbsolutePath, "utf8"));
+  } catch (error) {
+    diagnostics.push(createDiagnostic({
+      code: "runtimeRecord.traceManifestReadFailed",
+      level: "warning",
+      source: "runtimeRecord",
+      message: "Could not parse existing runtime trace manifest. A new manifest will be written.",
+      path: "/artifacts/runtimeTraceManifest",
+      details: {
+        manifestAbsolutePath,
+        error: error instanceof Error ? error.message : String(error),
+      },
+    }));
+
+    return [];
+  }
+
+  return asArray(parsed.entries)
+    .map((entry) => normalizeRuntimeTraceManifestEntry(entry))
+    .filter(Boolean);
+}
+
+function deduplicateRuntimeTraceManifestEntries(entries = []) {
+  const deduplicated = [];
+  const seen = new Set();
+
+  for (const entry of entries) {
+    const normalized = normalizeRuntimeTraceManifestEntry(entry);
+
+    if (!normalized) {
+      continue;
+    }
+
+    const key = `${normalized.runId}::${normalized.tracePath}`;
+
+    if (seen.has(key)) {
+      continue;
+    }
+
+    seen.add(key);
+    deduplicated.push(normalized);
+  }
+
+  return deduplicated;
+}
+
+function writeRuntimeTraceManifest(options = {}) {
+  const cwd = path.resolve(options.cwd ?? process.cwd());
+  const diagnostics = [];
+
+  const manifestAbsolutePath = path.resolve(
+    cwd,
+    asNonEmptyString(options.manifestPath) ?? DEFAULT_RUNTIME_TRACE_MANIFEST_PATH,
+  );
+
+  const manifestDirectoryAbsolute = path.dirname(manifestAbsolutePath);
+
+  try {
+    fs.mkdirSync(manifestDirectoryAbsolute, {
+      recursive: true,
+    });
+  } catch (error) {
+    diagnostics.push(createDiagnostic({
+      code: "runtimeRecord.traceManifestDirectoryCreateFailed",
+      level: "warning",
+      source: "runtimeRecord",
+      message: "Failed to create runtime trace manifest directory.",
+      path: "/artifacts/runtimeTraceManifest",
+      details: {
+        manifestDirectoryAbsolute,
+        error: error instanceof Error ? error.message : String(error),
+      },
+    }));
+
+    return {
+      ok: false,
+      artifact: null,
+      entryCount: 0,
+      droppedEntryCount: 0,
+      diagnostics,
+    };
+  }
+
+  const retentionCount = normalizePositiveInteger(
+    options.retentionCount,
+    DEFAULT_RUNTIME_TRACE_MANIFEST_RETENTION_COUNT,
+  );
+
+  const existingEntries = parseExistingRuntimeTraceManifestEntries(manifestAbsolutePath, diagnostics);
+
+  const nextEntry = normalizeRuntimeTraceManifestEntry({
+    runId: options.runId,
+    generatedAt: options.generatedAt,
+    tracePath: options.runtimeTracePath,
+    commandLine: options.commandLine,
+    projectPath: options.projectPath,
+    appMapAvailable: options.appMapAvailable,
+    commandExitCode: options.commandExitCode,
+    commandDurationMs: options.commandDurationMs,
+  });
+
+  if (!nextEntry) {
+    diagnostics.push(createDiagnostic({
+      code: "runtimeRecord.traceManifestMissingEntry",
+      level: "warning",
+      source: "runtimeRecord",
+      message: "Runtime trace manifest entry could not be created because runId or runtime trace path is missing.",
+      path: "/artifacts/runtimeTraceManifest/entries",
+    }));
+
+    return {
+      ok: false,
+      artifact: null,
+      entryCount: existingEntries.length,
+      droppedEntryCount: 0,
+      diagnostics,
+    };
+  }
+
+  const deduplicated = deduplicateRuntimeTraceManifestEntries([
+    nextEntry,
+    ...existingEntries,
+  ]);
+
+  const droppedEntryCount = Math.max(0, deduplicated.length - retentionCount);
+  const retainedEntries = deduplicated.slice(0, retentionCount);
+
+  const manifestRecord = {
+    schemaVersion: RUNTIME_TRACE_MANIFEST_SCHEMA_VERSION,
+    schema_version: RUNTIME_TRACE_MANIFEST_SCHEMA_VERSION,
+    generatedAt: new Date().toISOString(),
+    retention: {
+      retentionCount,
+      entryCount: retainedEntries.length,
+      droppedEntryCount,
+    },
+    entries: retainedEntries,
+  };
+
+  try {
+    fs.writeFileSync(
+      manifestAbsolutePath,
+      `${JSON.stringify(manifestRecord, null, 2)}\n`,
+      "utf8",
+    );
+  } catch (error) {
+    diagnostics.push(createDiagnostic({
+      code: "runtimeRecord.traceManifestWriteFailed",
+      level: "warning",
+      source: "runtimeRecord",
+      message: "Failed to write runtime trace manifest.",
+      path: "/artifacts/runtimeTraceManifest",
+      details: {
+        manifestAbsolutePath,
+        error: error instanceof Error ? error.message : String(error),
+      },
+    }));
+
+    return {
+      ok: false,
+      artifact: null,
+      entryCount: retainedEntries.length,
+      droppedEntryCount,
+      diagnostics,
+    };
+  }
+
+  return {
+    ok: true,
+    artifact: {
+      path: toRelativePath(cwd, manifestAbsolutePath),
+      absolutePath: manifestAbsolutePath,
+      schemaVersion: RUNTIME_TRACE_MANIFEST_SCHEMA_VERSION,
+      schema_version: RUNTIME_TRACE_MANIFEST_SCHEMA_VERSION,
+      retentionCount,
+      entryCount: retainedEntries.length,
+    },
+    entryCount: retainedEntries.length,
+    droppedEntryCount,
+    diagnostics,
+  };
+}
+
+function createAppMapRerunCommand({
+  projectPathInput,
+  observedCommand,
+}) {
+  const rerunTokens = [
+    "depdiet",
+    "record",
+    projectPathInput,
+    "--",
+    ...(
+      asArray(observedCommand)
+        .map((token) => normalizeCommandToken(token))
+        .filter(Boolean)
+    ),
+  ];
+
+  if (rerunTokens.length === 4) {
+    rerunTokens.push("<command...>");
+  }
+
+  return toCommandLineString(rerunTokens);
+}
+
+function createAppMapGuidanceInstructions({
+  projectPathInput,
+  observedCommand,
+}) {
+  const rerunCommand = createAppMapRerunCommand({
+    projectPathInput,
+    observedCommand,
+  });
+
+  return [
+    "AppMap tooling was not detected for this project, so only raw command tracing was captured.",
+    "Node.js setup: npm install --save-dev @appland/appmap",
+    "Node.js verify: npx appmap-node --help",
+    "Python setup: pip install appmap",
+    "Python verify: python -m appmap --help",
+    `Re-run recording once AppMap is installed: ${rerunCommand}`,
+    "Detection override for CI/tests: DEPDIET_APPMAP_AVAILABLE=true|false",
+  ];
+}
+
+function renderAppMapGuidanceMarkdown({
+  generatedAt,
+  projectPathInput,
+  appMap,
+  instructions,
+}) {
+  return [
+    "# AppMap setup guidance",
+    "",
+    `Generated at: ${generatedAt}`,
+    `Project path: ${projectPathInput}`,
+    `Probe reason: ${appMap.reason}`,
+    "",
+    "AppMap runtime capture was unavailable for this run.",
+    "",
+    "## Recommended steps",
+    ...instructions.map((entry) => `- ${entry}`),
+    "",
+    "## Probe details",
+    "",
+    ...appMap.probes.map((probe) => `- ${JSON.stringify(probe)}`),
+    "",
+  ].join("\n");
+}
+
+function createFailureResult({
+  cwd,
+  generatedAt,
+  projectPath,
+  observedCommand,
+  diagnostics,
+  code,
+  message,
+}) {
+  return {
+    schemaVersion: RUNTIME_RECORD_RESULT_SCHEMA_VERSION,
+    schema_version: RUNTIME_RECORD_RESULT_SCHEMA_VERSION,
+    ok: false,
+    cwd,
+    generatedAt,
+    command: {
+      name: "record",
+      projectPath,
+      observedCommand,
+    },
+    diagnostics: [
+      createDiagnostic({
+        code,
+        level: "error",
+        source: "runtimeRecord",
+        message,
+      }),
+      ...normalizeDiagnosticList(diagnostics, "runtimeRecord"),
+    ],
+    artifacts: {
+      runDirectory: null,
+      runtimeTrace: null,
+      runtimeTraceManifest: null,
+      setupGuidance: null,
+    },
+    trace: null,
+    appMap: null,
+    guidance: null,
+    commandsRun: [],
+  };
+}
+
+export function runRuntimeRecordFlow(options = {}) {
+  const cwd = path.resolve(options.cwd ?? process.cwd());
+  const generatedAt = asNonEmptyString(options.traceTimestamp) ?? new Date().toISOString();
+
+  const projectPathInput = resolveProjectPathInput(options);
+  const observedCommand = resolveObservedCommand(options);
+
+  if (!projectPathInput) {
+    return createFailureResult({
+      cwd,
+      generatedAt,
+      projectPath: null,
+      observedCommand,
+      diagnostics: [],
+      code: "runtimeRecord.missingProjectPath",
+      message: "Record command requires a target project path.",
+    });
+  }
+
+  if (observedCommand.length === 0) {
+    return createFailureResult({
+      cwd,
+      generatedAt,
+      projectPath: projectPathInput,
+      observedCommand,
+      diagnostics: [],
+      code: "runtimeRecord.missingObservedCommand",
+      message: "Record command requires an observed command after '--'.",
+    });
+  }
+
+  const projectPathAbsolute = path.resolve(cwd, projectPathInput);
+
+  if (!isExistingDirectory(projectPathAbsolute)) {
+    return createFailureResult({
+      cwd,
+      generatedAt,
+      projectPath: projectPathInput,
+      observedCommand,
+      diagnostics: [],
+      code: "runtimeRecord.projectPathNotFound",
+      message: "Record command requires an existing project directory.",
+    });
+  }
+
+  const runId = sanitizeSegment(
+    options.runId ?? `record-${Date.now()}`,
+    {
+      fallback: `record-${Date.now()}`,
+    },
+  );
+
+  const diagnostics = [];
+
+  const artifactDirectoryAbsolute = path.resolve(
+    cwd,
+    asNonEmptyString(options.artifactDirectory) ?? DEFAULT_RECORD_ARTIFACT_DIR,
+    runId,
+  );
+
+  try {
+    fs.mkdirSync(artifactDirectoryAbsolute, { recursive: true });
+  } catch (error) {
+    return createFailureResult({
+      cwd,
+      generatedAt,
+      projectPath: projectPathInput,
+      observedCommand,
+      diagnostics: [createDiagnostic({
+        code: "runtimeRecord.artifactDirectoryCreateFailed",
+        level: "error",
+        source: "runtimeRecord",
+        message: "Failed to create runtime record artifact directory.",
+        details: {
+          artifactDirectory: artifactDirectoryAbsolute,
+          error: error instanceof Error ? error.message : String(error),
+        },
+      })],
+      code: "runtimeRecord.artifactDirectoryCreateFailed",
+      message: "Record command aborted because artifact directory creation failed.",
+    });
+  }
+
+  const appMap = probeAppMapAvailability({
+    projectPathAbsolute,
+    options,
+  });
+
+  diagnostics.push(...normalizeDiagnosticList(appMap.diagnostics, "runtimeRecord"));
+
+  if (!appMap.available) {
+    diagnostics.push(createDiagnostic({
+      code: "runtimeRecord.appMapUnavailable",
+      level: "warning",
+      source: "runtimeRecord",
+      message: "AppMap tooling was not detected. Runtime trace was captured without AppMap instrumentation, and setup guidance was generated.",
+      path: "/appMap",
+      details: {
+        reason: appMap.reason,
+      },
+    }));
+  }
+
+  const packageAutodiscovery = optionEnabled(
+    options.packageAutodiscovery
+      ?? options.packageAutoDiscovery
+      ?? options.autodiscoverPackages
+      ?? options["package-autodiscovery"],
+  )
+    ? createPackageAutodiscoveryInstrumentation({
+      artifactDirectoryAbsolute,
+      diagnostics,
+    })
+    : {
+      enabled: false,
+      reason: "not-requested",
+      logAbsolutePath: null,
+      loaderAbsolutePath: null,
+      preloadAbsolutePath: null,
+      env: process.env,
+      events: [],
+      diagnostics: [],
+    };
+
+  diagnostics.push(...normalizeDiagnosticList(packageAutodiscovery.diagnostics, "runtimeRecord"));
+
+  const execution = executeObservedCommand({
+    commandTokens: observedCommand,
+    cwd: projectPathAbsolute,
+    env: packageAutodiscovery.env,
+  });
+
+  packageAutodiscovery.events = packageAutodiscovery.enabled
+    ? readPackageAutodiscoveryEvents({
+      logAbsolutePath: packageAutodiscovery.logAbsolutePath,
+      diagnostics,
+    })
+    : [];
+
+  if (execution.errorMessage) {
+    diagnostics.push(createDiagnostic({
+      code: "runtimeRecord.commandExecutionSpawnError",
+      level: "error",
+      source: "runtimeRecord",
+      message: "Observed command failed to start.",
+      path: "/trace/command",
+      details: {
+        command: execution.commandLine,
+        error: execution.errorMessage,
+      },
+    }));
+  } else if (execution.exitCode !== 0) {
+    diagnostics.push(createDiagnostic({
+      code: "runtimeRecord.commandExecutionNonZeroExit",
+      level: "warning",
+      source: "runtimeRecord",
+      message: "Observed command exited with a non-zero status.",
+      path: "/trace/command",
+      details: {
+        command: execution.commandLine,
+        exitCode: execution.exitCode,
+      },
+    }));
+  }
+
+  const runtimeTraceRecord = {
+    schemaVersion: RUNTIME_TRACE_SCHEMA_VERSION,
+    schema_version: RUNTIME_TRACE_SCHEMA_VERSION,
+    generatedAt,
+    runId,
+    command: {
+      name: "record",
+      projectPath: projectPathInput,
+      observedCommand,
+    },
+    appMap: {
+      available: appMap.available,
+      reason: appMap.reason,
+      probes: appMap.probes,
+    },
+    execution: {
+      ok: execution.ok,
+      command: execution.command,
+      args: execution.args,
+      commandLine: execution.commandLine,
+      cwd: toRelativePath(cwd, execution.cwd),
+      exitCode: execution.exitCode,
+      signal: execution.signal,
+      stdout: execution.stdout,
+      stderr: execution.errorMessage
+        ? `${execution.stderr}${execution.stderr ? "\n" : ""}${execution.errorMessage}`
+        : execution.stderr,
+      startedAt: execution.startedAt,
+      completedAt: execution.completedAt,
+      durationMs: execution.durationMs,
+    },
+    packageAutodiscovery: {
+      enabled: packageAutodiscovery.enabled,
+      reason: packageAutodiscovery.reason,
+      eventCount: packageAutodiscovery.events.length,
+      events: packageAutodiscovery.events,
+    },
+    diagnostics: normalizeDiagnosticList(diagnostics, "runtimeRecord"),
+  };
+
+  const runtimeTraceAbsolutePath = path.join(
+    artifactDirectoryAbsolute,
+    "runtime-trace.json",
+  );
+
+  const runtimeTraceWriteOk = writeArtifact(
+    runtimeTraceAbsolutePath,
+    `${JSON.stringify(runtimeTraceRecord, null, 2)}\n`,
+    diagnostics,
+    {
+      code: "runtimeRecord.runtimeTraceWriteFailed",
+      message: "Failed to write runtime trace artifact.",
+      details: {
+        artifact: "runtime-trace.json",
+      },
+    },
+  );
+
+  let setupGuidanceAbsolutePath = null;
+  let setupGuidance = null;
+
+  if (!appMap.available) {
+    const rerunCommand = createAppMapRerunCommand({
+      projectPathInput,
+      observedCommand,
+    });
+
+    const instructions = createAppMapGuidanceInstructions({
+      projectPathInput,
+      observedCommand,
+    });
+
+    setupGuidance = {
+      schemaVersion: APPMAP_SETUP_GUIDANCE_SCHEMA_VERSION,
+      schema_version: APPMAP_SETUP_GUIDANCE_SCHEMA_VERSION,
+      generatedAt,
+      runId,
+      reason: appMap.reason,
+      rerunCommand,
+      instructions,
+    };
+
+    setupGuidanceAbsolutePath = path.join(
+      artifactDirectoryAbsolute,
+      "appmap-setup-guidance.md",
+    );
+
+    const markdown = renderAppMapGuidanceMarkdown({
+      generatedAt,
+      projectPathInput,
+      appMap,
+      instructions,
+    });
+
+    writeArtifact(
+      setupGuidanceAbsolutePath,
+      `${markdown.endsWith("\n") ? markdown : `${markdown}\n`}`,
+      diagnostics,
+      {
+        code: "runtimeRecord.setupGuidanceWriteFailed",
+        message: "Failed to write AppMap setup guidance artifact.",
+        details: {
+          artifact: "appmap-setup-guidance.md",
+        },
+      },
+    );
+  }
+
+  const runtimeTraceManifest = runtimeTraceWriteOk
+    ? writeRuntimeTraceManifest({
+      cwd,
+      runId,
+      generatedAt,
+      projectPath: projectPathInput,
+      runtimeTracePath: toRelativePath(cwd, runtimeTraceAbsolutePath),
+      commandLine: execution.commandLine,
+      appMapAvailable: appMap.available,
+      commandExitCode: execution.exitCode,
+      commandDurationMs: execution.durationMs,
+      manifestPath: asNonEmptyString(options.runtimeTraceManifestPath),
+      retentionCount: options.runtimeTraceManifestRetentionCount,
+    })
+    : {
+      ok: false,
+      artifact: null,
+      entryCount: 0,
+      droppedEntryCount: 0,
+      diagnostics: [createDiagnostic({
+        code: "runtimeRecord.traceManifestSkipped",
+        level: "warning",
+        source: "runtimeRecord",
+        message: "Runtime trace manifest update was skipped because runtime trace artifact emission failed.",
+        path: "/artifacts/runtimeTraceManifest",
+      })],
+    };
+
+  diagnostics.push(...normalizeDiagnosticList(runtimeTraceManifest.diagnostics, "runtimeRecord"));
+
+  const recordHandoff = options.emitRecordHandoffArtifacts === false
+    ? null
+    : emitRecordHandoffArtifacts({
+      cwd,
+      options,
+      diagnostics,
+      generatedAt,
+      runId,
+      projectPathInput,
+      projectPathAbsolute,
+      observedCommand,
+      execution,
+      packageAutodiscovery,
+      runtimeTracePath: runtimeTraceWriteOk ? toRelativePath(cwd, runtimeTraceAbsolutePath) : null,
+      setupGuidancePath: setupGuidanceAbsolutePath ? toRelativePath(cwd, setupGuidanceAbsolutePath) : null,
+    });
+
+  const normalizedDiagnostics = normalizeDiagnosticList(diagnostics, "runtimeRecord");
+
+  const ok = (
+    execution.ok
+    && !hasErrorDiagnostic(normalizedDiagnostics)
+  );
+
+  return {
+    schemaVersion: RUNTIME_RECORD_RESULT_SCHEMA_VERSION,
+    schema_version: RUNTIME_RECORD_RESULT_SCHEMA_VERSION,
+    ok,
+    cwd,
+    generatedAt,
+    runId,
+    command: {
+      name: "record",
+      projectPath: projectPathInput,
+      observedCommand,
+    },
+    appMap: {
+      available: appMap.available,
+      reason: appMap.reason,
+      probes: appMap.probes,
+    },
+    trace: {
+      ok: execution.ok,
+      commandLine: execution.commandLine,
+      cwd: toRelativePath(cwd, execution.cwd),
+      exitCode: execution.exitCode,
+      signal: execution.signal,
+      stdout: execution.stdout,
+      stderr: execution.errorMessage
+        ? `${execution.stderr}${execution.stderr ? "\n" : ""}${execution.errorMessage}`
+        : execution.stderr,
+      startedAt: execution.startedAt,
+      completedAt: execution.completedAt,
+      durationMs: execution.durationMs,
+      packageAutodiscovery: {
+        enabled: packageAutodiscovery.enabled,
+        reason: packageAutodiscovery.reason,
+        eventCount: packageAutodiscovery.events.length,
+        events: packageAutodiscovery.events,
+      },
+    },
+    guidance: setupGuidance,
+    artifacts: {
+      runDirectory: toRelativePath(cwd, artifactDirectoryAbsolute),
+      runtimeTrace: {
+        path: toRelativePath(cwd, runtimeTraceAbsolutePath),
+        absolutePath: runtimeTraceAbsolutePath,
+        schemaVersion: RUNTIME_TRACE_SCHEMA_VERSION,
+        schema_version: RUNTIME_TRACE_SCHEMA_VERSION,
+      },
+      runtimeTraceManifest: runtimeTraceManifest.artifact,
+      setupGuidance: setupGuidanceAbsolutePath
+        ? {
+          path: toRelativePath(cwd, setupGuidanceAbsolutePath),
+          absolutePath: setupGuidanceAbsolutePath,
+          schemaVersion: APPMAP_SETUP_GUIDANCE_SCHEMA_VERSION,
+          schema_version: APPMAP_SETUP_GUIDANCE_SCHEMA_VERSION,
+        }
+        : null,
+      packageAutodiscovery: packageAutodiscovery.enabled
+        ? {
+          logPath: toRelativePath(cwd, packageAutodiscovery.logAbsolutePath),
+          logAbsolutePath: packageAutodiscovery.logAbsolutePath,
+          loaderPath: toRelativePath(cwd, packageAutodiscovery.loaderAbsolutePath),
+          preloadPath: toRelativePath(cwd, packageAutodiscovery.preloadAbsolutePath),
+          eventCount: packageAutodiscovery.events.length,
+        }
+        : null,
+      ...(recordHandoff ? recordHandoff.artifacts : {}),
+    },
+    summary: {
+      appMapAvailable: appMap.available,
+      setupGuidanceEmitted: Boolean(setupGuidanceAbsolutePath),
+      observedCommandSucceeded: execution.ok,
+      commandExitCode: execution.exitCode,
+      commandDurationMs: execution.durationMs,
+      runtimeTraceManifestUpdated: runtimeTraceManifest.ok,
+      runtimeTraceManifestEntryCount: runtimeTraceManifest.entryCount,
+      runtimeTraceManifestDroppedEntryCount: runtimeTraceManifest.droppedEntryCount,
+      ...(recordHandoff ? recordHandoff.summary : {}),
+    },
+    diagnostics: normalizedDiagnostics,
+    commandsRun: [execution.commandLine],
+  };
+}
+
+export const RUNTIME_RECORD_INTERNALS = Object.freeze({
+  resolveProjectPathInput,
+  resolveObservedCommand,
+  sanitizeSegment,
+  probeAppMapAvailability,
+  executeObservedCommand,
+  createAppMapRerunCommand,
+  createAppMapGuidanceInstructions,
+  renderAppMapGuidanceMarkdown,
+  writeRuntimeTraceManifest,
+  DEFAULT_RECORD_ARTIFACT_DIR,
+  DEFAULT_RUNTIME_TRACE_MANIFEST_PATH,
+  DEFAULT_RUNTIME_TRACE_MANIFEST_RETENTION_COUNT,
+  RUNTIME_TRACE_SCHEMA_VERSION,
+  RUNTIME_TRACE_MANIFEST_SCHEMA_VERSION,
+  APPMAP_SETUP_GUIDANCE_SCHEMA_VERSION,
+  RUNTIME_RECORD_RESULT_SCHEMA_VERSION,
+});
+
+export {
+  DEFAULT_RECORD_ARTIFACT_DIR,
+  DEFAULT_RUNTIME_TRACE_MANIFEST_PATH,
+  DEFAULT_RUNTIME_TRACE_MANIFEST_RETENTION_COUNT,
+  RUNTIME_TRACE_SCHEMA_VERSION,
+  RUNTIME_TRACE_MANIFEST_SCHEMA_VERSION,
+  APPMAP_SETUP_GUIDANCE_SCHEMA_VERSION,
+  RUNTIME_RECORD_RESULT_SCHEMA_VERSION,
+};