@tryinget/runtime-trace-insights 0.1.0

package/src/runtime_trace_bundle/index.mjs

@@ -0,0 +1,8 @@
+export {
+  DEFAULT_RUNTIME_TRACE_BUNDLE_PATH,
+  RUNTIME_TRACE_BUNDLE_NON_AUTHORITY_NOTE,
+  RUNTIME_TRACE_BUNDLE_SCHEMA_VERSION,
+  RUNTIME_TRACE_REOBSERVATION_NON_AUTHORITY_NOTE,
+  RUNTIME_TRACE_REOBSERVATION_SCHEMA_VERSION,
+  runRuntimeTraceBundleFlow,
+} from "./runtime_trace_bundle_flow.mjs";

package/src/runtime_trace_bundle/runtime_trace_bundle_builder.mjs

@@ -0,0 +1,679 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const RUNTIME_TRACE_BUNDLE_SCHEMA_VERSION = "runtime-trace-insights.runtime-trace-bundle.v1";
+export const RUNTIME_TRACE_REOBSERVATION_SCHEMA_VERSION = "runtime-trace-insights.replacement-reobservation.v1";
+export const RUNTIME_TRACE_BUNDLE_NON_AUTHORITY_NOTE = "Runtime observation is command-level evidence, not dependency removal, risk, vulnerability policy, or visualization authority.";
+export const RUNTIME_TRACE_REOBSERVATION_NON_AUTHORITY_NOTE = "Replacement re-observation is before/after command-level evidence for candidate validation; it is not exhaustive coverage, replacement safety, merge, release, exploitability, disclosure, or trust 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 normalizePathSlashes(value) {
+  return String(value).replaceAll("\\", "/");
+}
+
+function toRelativePath(basePath, targetPath) {
+  const relative = path.relative(basePath, targetPath);
+  return normalizePathSlashes(relative.length > 0 ? relative : ".");
+}
+
+function createDiagnostic({ code, level = "warning", message, source = "runtimeTraceBundle", details }) {
+  const diagnostic = { code, level, source, message };
+  if (details !== undefined) {
+    diagnostic.details = details;
+  }
+  return diagnostic;
+}
+
+function capitalize(value) {
+  return `${value.charAt(0).toUpperCase()}${value.slice(1)}`;
+}
+
+// Who emits the bundle decides its diagnostic namespace and a few conventions. The bundle command
+// (runtime_trace_bundle.mjs record) is this repo's own surface. The record profile reproduces
+// dep-diet's `depdiet record` contract so dep-diet can load this repo as its runtime-record adapter
+// without loss (AK #5892).
+export const RUNTIME_TRACE_BUNDLE_PROFILES = Object.freeze({
+  bundleCommand: Object.freeze({
+    diagnosticCode: (name) => `runtimeTraceBundle.${name}`,
+    diagnosticSource: "runtimeTraceBundle",
+    readPackageJson: "always",
+    warnWhenNoPackagesDeclared: true,
+    warnOnArtifactPlacement: true,
+    emittedBy: null,
+    moduleId: ({ projectPathAbsolute }) => `js:${path.basename(projectPathAbsolute)}`,
+    referenceTool: "runtime-trace-insights",
+  }),
+  depdietRecord: Object.freeze({
+    diagnosticCode: (name) => `runtimeRecord.runtimeBundle${capitalize(name)}`,
+    diagnosticSource: "runtimeRecord",
+    readPackageJson: "when-declared",
+    warnWhenNoPackagesDeclared: false,
+    warnOnArtifactPlacement: false,
+    emittedBy: "dep-diet",
+    moduleId: ({ projectPathInput }) => `js:${normalizePathSlashes(projectPathInput)}`,
+    referenceTool: "dep-diet",
+  }),
+});
+
+function profileDiagnostic(context, { name, level = "warning", message, details }) {
+  return createDiagnostic({
+    code: context.profile.diagnosticCode(name),
+    level,
+    message,
+    source: context.profile.diagnosticSource,
+    details,
+  });
+}
+
+export function normalizeDiagnosticList(entries, source) {
+  return asArray(entries)
+    .filter((entry) => isPlainObject(entry))
+    .map((entry) => ({
+      ...entry,
+      ...(asNonEmptyString(entry.level) ? {} : { level: "warning" }),
+      ...(asNonEmptyString(entry.source) ? {} : { source }),
+    }));
+}
+
+function parsePackageSpecifier(value) {
+  const token = asNonEmptyString(value);
+  if (!token) {
+    return null;
+  }
+
+  const atIndex = token.lastIndexOf("@");
+  if (atIndex > 0) {
+    return {
+      name: token.slice(0, atIndex),
+      version: token.slice(atIndex + 1) || null,
+    };
+  }
+
+  return {
+    name: token,
+    version: null,
+  };
+}
+
+function readPackageJson(projectPathAbsolute, context) {
+  const packageJsonPath = path.join(projectPathAbsolute, "package.json");
+
+  if (!fs.existsSync(packageJsonPath)) {
+    context.diagnostics.push(profileDiagnostic(context, {
+      name: "packageJsonMissing",
+      message: "Could not resolve package versions because package.json was not found.",
+      details: { packageJsonPath },
+    }));
+    return null;
+  }
+
+  try {
+    return JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
+  } catch (error) {
+    context.diagnostics.push(profileDiagnostic(context, {
+      name: "packageJsonReadFailed",
+      message: "Could not parse package.json while resolving observed package versions.",
+      details: {
+        packageJsonPath,
+        error: error instanceof Error ? error.message : String(error),
+      },
+    }));
+    return null;
+  }
+}
+
+function isExactVersionSpecifier(value) {
+  const normalized = asNonEmptyString(value);
+  return Boolean(normalized && /^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/u.test(normalized));
+}
+
+function readJsonFile(filePath) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function ancestorDirectories(startAbsolute) {
+  const directories = [];
+  let current = path.resolve(startAbsolute);
+  for (;;) {
+    directories.push(current);
+    const parent = path.dirname(current);
+    if (parent === current) {
+      return directories;
+    }
+    current = parent;
+  }
+}
+
+// A package-lock.json at `directory` records a workspace member's own nested install as
+// "<member>/node_modules/<name>" and a hoisted install as "node_modules/<name>".
+function readPackageLockVersion(directory, projectPathAbsolute, packageName) {
+  const lockPath = path.join(directory, "package-lock.json");
+  if (!fs.existsSync(lockPath)) {
+    return null;
+  }
+
+  const lockPackages = readJsonFile(lockPath)?.packages;
+  const memberPath = normalizePathSlashes(path.relative(directory, projectPathAbsolute));
+  const lockKeys = [
+    ...(memberPath ? [`${memberPath}/node_modules/${packageName}`] : []),
+    `node_modules/${packageName}`,
+  ];
+  for (const lockKey of lockKeys) {
+    const version = asNonEmptyString(lockPackages?.[lockKey]?.version);
+    if (version) {
+      return {
+        version,
+        sourcePath: `${toRelativePath(projectPathAbsolute, lockPath)}#packages.${lockKey}.version`,
+      };
+    }
+  }
+  return null;
+}
+
+function readInstalledPackageVersion(directory, projectPathAbsolute, packageName) {
+  const packageJsonPath = path.join(directory, "node_modules", packageName, "package.json");
+  const version = asNonEmptyString(readJsonFile(packageJsonPath)?.version);
+  return version
+    ? { version, sourcePath: `${toRelativePath(projectPathAbsolute, packageJsonPath)}#version` }
+    : null;
+}
+
+// Walks from the project upward the way Node resolution does, so the nearest install wins and a
+// distant ancestor lockfile (for example one in $HOME) never overrides it. At each level the
+// lockfile is checked before the installed package.json.
+function resolveInstalledPackageVersion(projectPathAbsolute, packageName) {
+  for (const directory of ancestorDirectories(projectPathAbsolute)) {
+    const resolved = readPackageLockVersion(directory, projectPathAbsolute, packageName)
+      ?? readInstalledPackageVersion(directory, projectPathAbsolute, packageName);
+    if (resolved) {
+      return resolved;
+    }
+  }
+  return null;
+}
+
+// Resolves the exact version a declared package runs at. A manifest range such as
+// "^1.0.0" is never returned as a version: it cannot distinguish a before/after update.
+function resolvePackageVersion({ packageJson, projectPathAbsolute, packageName }) {
+  const locked = resolveInstalledPackageVersion(projectPathAbsolute, packageName);
+  if (locked) {
+    return { ...locked, rawSpecifier: null };
+  }
+
+  for (const sectionName of ["dependencies", "devDependencies", "optionalDependencies", "peerDependencies"]) {
+    const section = packageJson?.[sectionName];
+    if (!isPlainObject(section)) {
+      continue;
+    }
+
+    const specifier = asNonEmptyString(section[packageName]);
+    if (specifier) {
+      return {
+        version: isExactVersionSpecifier(specifier) ? specifier : null,
+        rawSpecifier: specifier,
+        sourcePath: `package.json#${sectionName}.${packageName}`,
+      };
+    }
+  }
+
+  return {
+    version: null,
+    rawSpecifier: null,
+    sourcePath: "package.json",
+  };
+}
+
+function normalizeReplacementObservation(options) {
+  const phase = asNonEmptyString(options.observationPhase ?? options.reobservationPhase ?? options.phase);
+  const planRef = asNonEmptyString(options.replacementPlanRef ?? options.planRef);
+  const resultRef = asNonEmptyString(options.replacementResultRef ?? options.resultRef);
+  const candidateId = asNonEmptyString(options.replacementCandidateId ?? options.candidateId);
+  const intentRef = asNonEmptyString(options.replacementIntentRef ?? options.intentRef);
+
+  if (!phase && !planRef && !resultRef && !candidateId && !intentRef) {
+    return null;
+  }
+
+  const normalizedPhase = phase === "after" ? "after" : phase === "before" ? "before" : "unspecified";
+  return {
+    schemaVersion: RUNTIME_TRACE_REOBSERVATION_SCHEMA_VERSION,
+    phase: normalizedPhase,
+    ...(intentRef ? { intentRef } : {}),
+    ...(planRef ? { planRef } : {}),
+    ...(resultRef ? { resultRef } : {}),
+    ...(candidateId ? { candidateId } : {}),
+    comparisonKey: asNonEmptyString(options.comparisonKey)
+      ?? ([intentRef, planRef, candidateId].filter(Boolean).join("::") || null),
+    requiredPairing: normalizedPhase === "before"
+      ? "Record a matching after observation with the same comparisonKey after a candidate replacement is produced."
+      : normalizedPhase === "after"
+        ? "Compare against the matching before observation with the same comparisonKey; do not treat this command as exhaustive coverage."
+        : "Pair before and after observations with the same comparisonKey for candidate validation.",
+    authority: {
+      exhaustiveCoverageAuthority: false,
+      replacementSafetyAuthority: false,
+      mergeAuthority: false,
+      releaseAuthority: false,
+      exploitabilityAuthority: false,
+      disclosureAuthority: false,
+      trustCertificationAuthority: false,
+      note: RUNTIME_TRACE_REOBSERVATION_NON_AUTHORITY_NOTE,
+    },
+  };
+}
+
+function normalizeObservedPackage(entry, context) {
+  const diagnostics = context.diagnostics;
+  const raw = isPlainObject(entry)
+    ? entry
+    : { specifier: entry };
+
+  const parsed = parsePackageSpecifier(raw.name ?? raw.packageName ?? raw.specifier ?? raw.package);
+  if (!parsed?.name) {
+    diagnostics.push(profileDiagnostic(context, {
+      name: "observedPackageSkipped",
+      message: "Skipped observed package because its name was missing.",
+      details: { entry },
+    }));
+    return null;
+  }
+
+  const ecosystem = asNonEmptyString(raw.ecosystem) ?? asNonEmptyString(context.ecosystem) ?? "npm";
+  const resolved = resolvePackageVersion({
+    packageJson: context.packageJson,
+    projectPathAbsolute: context.projectPathAbsolute,
+    packageName: parsed.name,
+  });
+  const version = asNonEmptyString(raw.version) ?? parsed.version ?? resolved.version ?? "unknown";
+  const packageId = asNonEmptyString(raw.packageId) ?? `${ecosystem}:${parsed.name}@${version}`;
+  const moduleId = asNonEmptyString(raw.moduleId) ?? asNonEmptyString(context.moduleId) ?? context.profile.moduleId(context);
+  const sourcePath = asNonEmptyString(raw.sourcePath) ?? resolved.sourcePath;
+
+  if (!resolved.version && !parsed.version && !raw.version) {
+    diagnostics.push(profileDiagnostic(context, {
+      name: resolved.rawSpecifier ? "observedPackageVersionRange" : "observedPackageVersionUnknown",
+      message: resolved.rawSpecifier
+        ? `Observed package ${JSON.stringify(parsed.name)} used non-exact manifest specifier ${JSON.stringify(resolved.rawSpecifier)} without a lockfile or installed version; using \"unknown\".`
+        : `Observed package ${JSON.stringify(parsed.name)} did not have a resolvable version; using \"unknown\".`,
+      details: {
+        packageName: parsed.name,
+        rawSpecifier: resolved.rawSpecifier ?? null,
+      },
+    }));
+  }
+
+  return {
+    name: parsed.name,
+    ecosystem,
+    packageId,
+    version,
+    moduleId,
+    observed: raw.observed === false ? false : true,
+    evidence: {
+      kind: asNonEmptyString(raw.evidenceKind) ?? asNonEmptyString(context.evidenceKind) ?? "runtime-command-observation",
+      sourcePath,
+      commandLine: context.commandLine,
+      ...(context.replacementObservation
+        ? {
+            replacementObservationPhase: context.replacementObservation.phase,
+            replacementObservationComparisonKey: context.replacementObservation.comparisonKey,
+          }
+        : {}),
+    },
+    authority: {
+      removalAuthority: false,
+      riskAuthority: false,
+      visualizationAuthority: false,
+      note: RUNTIME_TRACE_BUNDLE_NON_AUTHORITY_NOTE,
+    },
+  };
+}
+
+function observedPackageInputs(options) {
+  const inputs = [];
+  for (const candidate of [options.observedPackage, options.observedPackages, options.packageName, options.packages]) {
+    if (Array.isArray(candidate)) {
+      inputs.push(...candidate);
+    } else if (typeof candidate === "string") {
+      inputs.push(...candidate.split(","));
+    }
+  }
+  return inputs
+    .map((entry) => (isPlainObject(entry) ? entry : asNonEmptyString(entry)))
+    .filter(Boolean);
+}
+
+function normalizeObservedPackages(inputs, context) {
+  if (inputs.length === 0 && context.packageAutodiscoveryRequested !== true && context.profile.warnWhenNoPackagesDeclared) {
+    context.diagnostics.push(profileDiagnostic(context, {
+      name: "noObservedPackagesDeclared",
+      message: "Runtime trace bundle was produced without explicit observed package declarations.",
+    }));
+  }
+
+  const packages = inputs
+    .map((entry) => normalizeObservedPackage(entry, context))
+    .filter(Boolean);
+
+  packages.sort((left, right) => left.packageId.localeCompare(right.packageId));
+  return packages;
+}
+
+function eventPathFromAutodiscoveryEvent(event) {
+  const url = asNonEmptyString(event?.url);
+  if (url?.startsWith("file:")) {
+    try {
+      return fileURLToPath(url);
+    } catch {
+      return null;
+    }
+  }
+
+  return asNonEmptyString(event?.resolvedPath);
+}
+
+function resolveNodeModulePackageFromPath(absolutePath) {
+  const normalized = normalizePathSlashes(path.resolve(absolutePath));
+  const marker = "/node_modules/";
+  const markerIndex = normalized.lastIndexOf(marker);
+  if (markerIndex < 0) {
+    return null;
+  }
+
+  const prefix = normalized.slice(0, markerIndex + marker.length - 1);
+  const remainder = normalized.slice(markerIndex + marker.length);
+  const segments = remainder.split("/").filter(Boolean);
+  if (segments.length === 0) {
+    return null;
+  }
+
+  const name = segments[0].startsWith("@")
+    ? (segments.length >= 2 ? `${segments[0]}/${segments[1]}` : null)
+    : segments[0];
+
+  if (!name) {
+    return null;
+  }
+
+  const packageRoot = path.join(prefix, name);
+  return {
+    name,
+    packageRoot,
+    relativePathInPackage: normalizePathSlashes(path.relative(packageRoot, absolutePath)),
+  };
+}
+
+function readPackageVersionFromPackageRoot(packageRoot) {
+  try {
+    const packageJsonPath = path.join(packageRoot, "package.json");
+    const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
+    return asNonEmptyString(packageJson.version);
+  } catch {
+    return null;
+  }
+}
+
+function normalizeAutodiscoveredPackages(packageAutodiscovery, context) {
+  const events = asArray(packageAutodiscovery?.events);
+  if (events.length === 0) {
+    if (packageAutodiscovery?.enabled === true) {
+      context.diagnostics.push(profileDiagnostic(context, {
+        name: "packageAutodiscoveryNoEvents",
+        message: "Package autodiscovery was enabled but emitted no loader/preload events.",
+      }));
+    }
+    return [];
+  }
+
+  const byPackageId = new Map();
+
+  for (const event of events) {
+    const eventPath = eventPathFromAutodiscoveryEvent(event);
+    if (!eventPath) {
+      continue;
+    }
+
+    const resolved = resolveNodeModulePackageFromPath(eventPath);
+    if (!resolved) {
+      continue;
+    }
+
+    const packageJsonResolution = resolvePackageVersion({
+      packageJson: context.packageJson,
+      projectPathAbsolute: context.projectPathAbsolute,
+      packageName: resolved.name,
+    });
+    const version = readPackageVersionFromPackageRoot(resolved.packageRoot)
+      ?? packageJsonResolution.version
+      ?? "unknown";
+    const ecosystem = asNonEmptyString(context.ecosystem) ?? "npm";
+    const packageId = `${ecosystem}:${resolved.name}@${version}`;
+    const moduleId = asNonEmptyString(context.moduleId) ?? `js:${path.basename(context.projectPathAbsolute)}`;
+
+    if (!byPackageId.has(packageId)) {
+      byPackageId.set(packageId, {
+        name: resolved.name,
+        ecosystem,
+        packageId,
+        version,
+        moduleId,
+        observed: true,
+        evidence: {
+          kind: "runtime-package-autodiscovery",
+          sourcePath: normalizePathSlashes(path.relative(context.projectPathAbsolute, path.join(resolved.packageRoot, "package.json"))),
+          commandLine: context.commandLine,
+          discovery: {
+            eventKinds: [],
+            sampleResolvedPaths: [],
+          },
+        },
+        authority: {
+          removalAuthority: false,
+          riskAuthority: false,
+          visualizationAuthority: false,
+          note: RUNTIME_TRACE_BUNDLE_NON_AUTHORITY_NOTE,
+        },
+      });
+    }
+
+    const observed = byPackageId.get(packageId);
+    if (!observed.evidence.discovery.eventKinds.includes(event.kind)) {
+      observed.evidence.discovery.eventKinds.push(event.kind);
+    }
+    const relativeEventPath = normalizePathSlashes(path.relative(context.projectPathAbsolute, eventPath));
+    if (observed.evidence.discovery.sampleResolvedPaths.length < 5
+      && !observed.evidence.discovery.sampleResolvedPaths.includes(relativeEventPath)) {
+      observed.evidence.discovery.sampleResolvedPaths.push(relativeEventPath);
+    }
+  }
+
+  return [...byPackageId.values()]
+    .sort((left, right) => left.packageId.localeCompare(right.packageId));
+}
+
+// Autodiscovery records what the command actually loaded, so it outranks declarations for the
+// same package. A declared entry for an autodiscovered package survives only through the
+// autodiscovered entry; keeping a declared "unknown" or a version that was never loaded would
+// give dep-diet a phantom package row.
+function mergeObservedPackageEvidence({ declared, autodiscovered, context }) {
+  const diagnostics = context.diagnostics;
+  const unresolvedDeclaredVersionCodes = new Set(
+    ["observedPackageVersionRange", "observedPackageVersionUnknown"].map((name) => context.profile.diagnosticCode(name)),
+  );
+  const observedVersionsByName = new Map();
+  for (const entry of autodiscovered) {
+    const key = `${entry.ecosystem}:${entry.name}`;
+    observedVersionsByName.set(key, [...(observedVersionsByName.get(key) ?? []), entry.version]);
+  }
+
+  const keptDeclared = [];
+  for (const entry of declared) {
+    const observedVersions = observedVersionsByName.get(`${entry.ecosystem}:${entry.name}`);
+    if (!observedVersions) {
+      keptDeclared.push(entry);
+      continue;
+    }
+
+    if (entry.version === "unknown") {
+      for (let index = diagnostics.length - 1; index >= 0; index -= 1) {
+        const diagnostic = diagnostics[index];
+        if (unresolvedDeclaredVersionCodes.has(diagnostic.code) && diagnostic.details?.packageName === entry.name) {
+          diagnostics.splice(index, 1);
+        }
+      }
+    } else if (!observedVersions.includes(entry.version)) {
+      diagnostics.push(profileDiagnostic(context, {
+        name: "declaredVersionNotObserved",
+        message: `Declared observed package ${JSON.stringify(entry.name)} at ${JSON.stringify(entry.version)} was not loaded by the command; package autodiscovery observed ${observedVersions.map((version) => JSON.stringify(version)).join(", ")}. The declared version was dropped.`,
+        details: {
+          packageName: entry.name,
+          declaredVersion: entry.version,
+          observedVersions: [...observedVersions].sort(),
+        },
+      }));
+    }
+  }
+
+  const byPackageId = new Map();
+  for (const entry of [...keptDeclared, ...autodiscovered]) {
+    byPackageId.set(entry.packageId, entry);
+  }
+
+  return [...byPackageId.values()]
+    .sort((left, right) => left.packageId.localeCompare(right.packageId));
+}
+
+function isInsideDirectory(directoryAbsolute, targetAbsolute) {
+  const relative = path.relative(directoryAbsolute, targetAbsolute);
+  return relative.length > 0 && !relative.startsWith("..") && !path.isAbsolute(relative);
+}
+
+// Artifact paths resolve against the caller's cwd while the command runs in the project, so a
+// caller standing inside the project writes the recorder's files into the observed checkout.
+// See docs/decisions/2026-09-23-observed-checkout-artifact-placement-greats.md.
+function createArtifactPlacementDiagnostic(context, { runDirectoryAbsolute, runtimeTraceManifestAbsolutePath, bundleAbsolutePath }) {
+  const projectPathAbsolute = context.projectPathAbsolute;
+  const artifacts = [
+    { artifact: "runDirectory", absolutePath: runDirectoryAbsolute },
+    { artifact: "runtimeTraceManifest", absolutePath: runtimeTraceManifestAbsolutePath },
+    { artifact: "bundle", absolutePath: bundleAbsolutePath },
+  ];
+
+  const insideObservedProject = artifacts
+    .filter((entry) => entry.absolutePath && isInsideDirectory(projectPathAbsolute, entry.absolutePath))
+    .map((entry) => ({ artifact: entry.artifact, path: toRelativePath(projectPathAbsolute, entry.absolutePath) }));
+
+  if (insideObservedProject.length === 0) {
+    return null;
+  }
+
+  return profileDiagnostic(context, {
+    name: "artifactsInsideObservedProject",
+    message: "Recorder artifacts were written inside the observed project; a later static scan of the project can read them (including package autodiscovery loader modules) as project source. Record from a directory outside the project, or pass --artifact-directory, --runtime-trace-manifest, and --out outside it.",
+    details: { insideObservedProject },
+  });
+}
+
+/**
+ * Builds a runtime-trace-insights.runtime-trace-bundle.v1 object from one recorded command.
+ * Diagnostics are appended to `diagnostics` (shared with the caller); the bundle carries a
+ * normalized snapshot of them.
+ */
+export function buildRuntimeTraceBundle({
+  profile = RUNTIME_TRACE_BUNDLE_PROFILES.bundleCommand,
+  diagnostics,
+  options = {},
+  generatedAt,
+  runId,
+  bundleId,
+  projectPathInput,
+  projectPathAbsolute,
+  observedCommand,
+  commandLine,
+  exitCode,
+  durationMs,
+  packageAutodiscovery,
+  artifactPaths = {},
+  references = [],
+}) {
+  const inputs = observedPackageInputs(options);
+  const context = {
+    profile,
+    diagnostics,
+    projectPathInput,
+    projectPathAbsolute,
+    moduleId: options.moduleId,
+    ecosystem: options.ecosystem,
+    evidenceKind: options.evidenceKind,
+    commandLine,
+    replacementObservation: normalizeReplacementObservation(options),
+    packageAutodiscoveryRequested: packageAutodiscovery?.enabled === true,
+    packageJson: null,
+  };
+  if (profile.readPackageJson === "always" || inputs.length > 0) {
+    context.packageJson = readPackageJson(projectPathAbsolute, context);
+  }
+
+  const observedPackages = mergeObservedPackageEvidence({
+    declared: normalizeObservedPackages(inputs, context),
+    autodiscovered: normalizeAutodiscoveredPackages(packageAutodiscovery, context),
+    context,
+  });
+
+  if (profile.warnOnArtifactPlacement) {
+    const placementDiagnostic = createArtifactPlacementDiagnostic(context, artifactPaths);
+    if (placementDiagnostic) {
+      diagnostics.push(placementDiagnostic);
+    }
+  }
+
+  return {
+    schemaVersion: RUNTIME_TRACE_BUNDLE_SCHEMA_VERSION,
+    schema_version: RUNTIME_TRACE_BUNDLE_SCHEMA_VERSION,
+    bundleId: asNonEmptyString(bundleId) ?? `${runId}-runtime-trace-bundle`,
+    producer: "runtime-trace-insights",
+    ...(profile.emittedBy ? { emittedBy: profile.emittedBy } : {}),
+    runId,
+    generatedAt,
+    command: {
+      projectPath: projectPathInput,
+      observedCommand,
+      commandLine,
+      exitCode,
+      durationMs,
+    },
+    authority: {
+      removalAuthority: false,
+      riskAuthority: false,
+      visualizationAuthority: false,
+      note: RUNTIME_TRACE_BUNDLE_NON_AUTHORITY_NOTE,
+    },
+    ...(context.replacementObservation ? { replacementObservation: context.replacementObservation } : {}),
+    observedPackages,
+    diagnostics: normalizeDiagnosticList(diagnostics, profile.diagnosticSource),
+    references: references
+      .filter((reference) => asNonEmptyString(reference?.path))
+      .map((reference) => ({ kind: reference.kind, path: reference.path, tool: profile.referenceTool })),
+  };
+}