summary: "Runtime-trace-insights README for runtime-record flow, runtime trace bundles, and dep-diet adapter usage." read_when:

• "Onboarding to runtime-trace-insights."
• "Changing runtime-record flows, runtime trace bundle production, adapter exports, or downstream integration docs." type: "reference"

runtime-trace-insights

Extracted runtime-record flow and external adapter module for dep-diet.

Current scope

• Runtime record flow implementation (runRuntimeRecordFlow)
• Runtime trace bundle production from an observed command (runtime_trace_bundle.mjs record)
• depdiet-compatible external adapter (runtimeRecordAdapter)
• Shared runtime-record diagnostic contract vectors
• Contract-focused tests for runtime trace artifacts and adapter behavior

Contract and identifiers

• Adapter ID: runtime-trace-insights.runtimeRecord.v1
• Adapter contract version: depdiet.runtime.record.adapter.v1
• Runtime record result schema: depdiet.runtime.record.result.v1
• Runtime trace bundle schema: runtime-trace-insights.runtime-trace-bundle.v1
• Shared vectors/fixture files:
  • fixtures/runtime_record_contract/v1/adapter_diagnostics_vectors.v1.json
  • fixtures/runtime_trace_bundle/v1/dependency-corridor-runtime-bundle.json
  • fixtures/runtime_trace_bundle/v1/fixture-manifest.json
  • fixtures/runtime_reobservation/v1/gardener-dependency-analysis.json (real Gardener output for the dependency-update re-observation fixture)

Compatibility policy for this extraction track is additive-first for v1 contracts.

Package exports

From package.json:

• . → src/index.mjs
• ./runtime-record → src/runtime_record/index.mjs
• ./runtime-trace-bundle → src/runtime_trace_bundle/index.mjs
• ./adapter/depdiet-runtime-record → src/runtime_record/depdiet_runtime_record_adapter.mjs

src/index.mjs also exports the depdiet adapter as default.

Produce a runtime trace bundle

Use runtime_trace_bundle.mjs record when a downstream consumer such as dep-diet needs a runtime-trace-insights.runtime-trace-bundle.v1 file from a real observed command:

node scripts/runtime_trace_bundle.mjs record <project-path> \
  --observed-package <name[@version]> \
  --out out/runtime-trace-insights/runtime-trace-bundle.json \
  -- <observed-command...>

Example for a TypeScript toolchain command:

node scripts/runtime_trace_bundle.mjs record /path/to/designmd-foundry \
  --observed-package @typescript/native-preview \
  --out /tmp/designmd-depintel-pilot/runtime/designmd-foundry-runtime-bundle.json \
  -- npm run typecheck

The observed package declaration is command-level evidence context, not removal authority. Use the narrowest representative command and do not treat one runtime command as full production coverage. The emitted bundle and each observed package entry carry machine-readable non-authority metadata (removalAuthority: false, riskAuthority: false, visualizationAuthority: false) so downstream tools do not have to infer this boundary from prose.

For dependency replacement candidates, bind comparable before/after observations to dep-diet / dep-surgeon references without granting replacement safety authority:

node scripts/runtime_trace_bundle.mjs record <project-path> \
  --observed-package <name[@version]> \
  --observation-phase before \
  --replacement-plan-ref <depsurgeon-plan-ref> \
  --comparison-key <stable-pair-key> \
  --out out/runtime-trace-insights/before.json \
  -- <observed-command...>

node scripts/runtime_trace_bundle.mjs record <project-path> \
  --observed-package <name[@version]> \
  --observation-phase after \
  --replacement-plan-ref <depsurgeon-plan-ref> \
  --replacement-result-ref <depsurgeon-result-ref> \
  --comparison-key <stable-pair-key> \
  --out out/runtime-trace-insights/after.json \
  -- <observed-command...>

Declared packages resolve to the exact version they run at. Resolution walks up from the project like Node resolution: at each level, package-lock.json first, then the installed node_modules/<name>/package.json, so workspace members resolve hoisted dependencies. After that comes an exact package.json specifier. With --package-autodiscovery, what the command actually loaded replaces declarations for the same package; a declared version that was not loaded is dropped with runtimeTraceBundle.declaredVersionNotObserved. A manifest range such as ^1.0.0 is never used as the version; without a lock or install the version is unknown and the bundle carries runtimeTraceBundle.observedPackageVersionRange.

For Python commands, pass --package-autodiscovery python (or node,python). The bundle then lists the installed distributions the command imported, as PEP 503-named pypi:<name>@<version> ids, without the project's own distribution. The bare flag and true keep meaning Node only. Details and limits are in "Producer command" in docs/project/runtime-trace-bundle-contract.md.

This adds replacementObservation.schemaVersion = runtime-trace-insights.replacement-reobservation.v1 and keeps exhaustive coverage, replacement safety, merge, release, exploitability, disclosure, and trust-certification authority false.

Re-observe a dependency update

To get before/after runtime evidence for a dependency update (new pin of the same package) into dep-diet depmodels, follow the recipe in docs/project/runtime-trace-bundle-contract.md ("Dependency update re-observation recipe"). In short: old pin in the main checkout, update in a git worktree, and the same command recorded for each from an evidence directory outside the checkout (record <checkout> ...), with --package-autodiscovery and one --comparison-key. Recording from inside the checkout writes artifacts there and emits the warning runtimeTraceBundle.artifactsInsideObservedProject; then depdiet analyze <checkout> --gardener-output ... --runtime-bundle ... --out-depmodel ... per phase. tests/runtime_reobservation_update_e2e.test.mjs runs the whole path, including dep-diet when its sibling checkout exists. Set RTI_DEPDIET_CLI=<path>/scripts/depdiet.mjs to run that leg against another dep-diet checkout. It needs dep-diet with #5887/#5888 (origin 48d4eb6 or later): a single bundle counted once, and the new transitive dep-b confirmed statically by the lockfile.

Dep-viz consumption boundary

The runtime trace bundle is consumable by dep-viz as runtime evidence for static/runtime overlays, but not as dep-viz's primary report model. The intended product path is:

runtime-trace-insights runtime bundle
  -> dep-diet evidence fusion / depmodel enrichment
  -> dep-viz depmodel rendering and overlay explanation

fixtures/runtime_trace_bundle/v1/fixture-manifest.json documents the corridor expectations for dep-viz contract tests: zod is a runtime observation that can become static/runtime-confirmed after fusion, debug is a runtime-only observation after fusion, and static-only packages such as chalk/lodash stay out of the raw runtime bundle.

Use from dep-diet

This repo is dep-diet's only runtime-record implementation. dep-diet retired its embedded copy (dep-diet AK #5902, with no fallback) and depends on the published package at an exact version under an npm alias: "runtime-trace-insights": "npm:@tryinget/runtime-trace-insights@<x.y.z>" (dep-diet AK #6038), locked with the registry sha512. depdiet record loads runtime-trace-insights/adapter/depdiet-runtime-record by default and gets from this repo the runtime trace bundle (out/depdiet/runtime/runtime-trace-bundle.json), the dep-viz runtime overlay handoff (out/depdiet/runtime/depviz-runtime-overlay-handoff.json), and the artifacts, summary and runtimeRecord.* diagnostics of dep-diet's record contract. A healthy run reports adapter.id: runtime-trace-insights.runtimeRecord.v1 with runtimeRecord.externalAdapterLoaded and runtimeRecord.adapterSelectionExternal.

The package exports and the adapter module are compatibility-relevant API. See "Package and adapter API compatibility" in docs/project/runtime-trace-bundle-contract.md, and docs/decisions/2026-09-23-runtime-record-single-owner.md.

Shipping a change to dep-diet. A change under src/ or the export map reaches dep-diet only after a release and a bump. Release it here (see "Release"), then in dep-diet run npm install --save-exact runtime-trace-insights@npm:@tryinget/runtime-trace-insights@<x.y.z>. Ping the dep-diet session or leave a dep-diet AK task. tests/features/depdiet_record_parity.feature reads dep-diet's package-lock.json pin and its installed node_modules/runtime-trace-insights. While their src/ and export map equal this checkout's, it checks that dep-diet's pinned release records exactly what this checkout records. Once this checkout moves past the pin, it skips and names the differing files and the bump command. It also skips, asking for npm ci, when dep-diet has not installed the locked version. It fails when it cannot recognize dep-diet's pin at all (tests/features/depdiet_pin_resolution.feature).

To try an unreleased checkout in dep-diet without a release, override the module:

DEPDIET_RUNTIME_RECORD_ADAPTER_MODULE=$HOME/ai-society/softwareco/owned/runtime-trace-insights/src/runtime_record/depdiet_runtime_record_adapter.mjs \
DEPDIET_APPMAP_AVAILABLE=true \
node $HOME/ai-society/softwareco/owned/dep-diet/scripts/depdiet.mjs record <project-path> -- <observed-command...>

Equivalent dep-diet CLI flags: --runtime-record-adapter-module <module>, --runtime-record-adapter-export <name>, --runtime-record-adapter-id <id>. Env overrides: DEPDIET_RUNTIME_RECORD_ADAPTER_EXPORT, DEPDIET_RUNTIME_RECORD_ADAPTER_ID.

Local validation

npm install
npm run lint
npm run test:record-runtime

The runtime-record test suite covers:

• tests/runtime_record_flow.test.mjs
• tests/depdiet_runtime_record_adapter.test.mjs
• tests/runtime_record_contract_vectors.test.mjs
• tests/runtime_trace_bundle_command.test.mjs
• tests/runtime_trace_bundle_contract.test.mjs
• tests/runtime_reobservation_update_e2e.test.mjs
• tests/observed_checkout_placement.feature.test.mjs (executes tests/features/observed_checkout_placement.feature)
• tests/declared_package_version_resolution.feature.test.mjs (executes tests/features/declared_package_version_resolution.feature)
• tests/depdiet_record_parity.feature.test.mjs (executes tests/features/depdiet_record_parity.feature; the differential scenario needs the ../dep-diet sibling with its dependencies installed)
• tests/depdiet_pin_resolution.feature.test.mjs (executes tests/features/depdiet_pin_resolution.feature: how the differential scenario reads dep-diet's npm pin, against fake dep-diet trees)
• tests/packaged_adapter.feature.test.mjs (executes tests/features/packaged_adapter.feature: packs and installs the tarball, then checks the adapter through the export map)
• tests/package_autodiscovery_portability.feature.test.mjs (executes tests/features/package_autodiscovery_portability.feature: the autodiscovery loader goes into NODE_OPTIONS as a file: URL, so Windows paths work; this repo has no Windows CI, and dep-diet's windows-latest CI covers real Windows)
• tests/python_package_autodiscovery.feature.test.mjs (executes tests/features/python_package_autodiscovery.feature on a real venv made with python3 -m venv --without-pip; needs python3 on PATH, or RTI_PYTHON)
• tests/release_version.feature.test.mjs (executes tests/features/release_version.feature: package.json, the newest released CHANGELOG heading and the annotated v<version> tag agree; needs the tags, so git fetch --tags in a fresh clone)

Release

The published package is @tryinget/runtime-trace-insights on npm. package.json's version, the newest released CHANGELOG heading (## [x.y.z] - YYYY-MM-DD) and the annotated tag vx.y.z name the same release, and the tag message records the published artifact's integrity: sha512-.... tests/features/release_version.feature enforces this. Build the tarball once and publish that exact file:

1. Move the [Unreleased] entries under ## [x.y.z] - YYYY-MM-DD, set version in package.json, and commit.
2. From that clean commit, npm pack and compute its integrity: echo "sha512-$(openssl dgst -sha512 -binary tryinget-runtime-trace-insights-x.y.z.tgz | base64 -w0)".
3. git tag -a vx.y.z with the tarball URL, shasum: and integrity: lines in the message, then run npm run lint && npm test (the release feature fails until the tag exists).
4. npm publish tryinget-runtime-trace-insights-x.y.z.tgz. Publishing a tarball skips prepublishOnly, which is why step 3 runs the gate. Check that npm view @tryinget/[email protected] dist.integrity equals the tag's integrity.
5. git push origin main vx.y.z, then bump dep-diet (see "Use from dep-diet").

v0.1.0 tags 8fb57f5, whose npm pack reproduces the registry tarball byte for byte (verified 2026-09-30, AK #6290).

Cross-repo alignment checks

tests/runtime_record_contract_vectors.test.mjs verifies the local vectors fixture and, when available, equality with dep-diet’s canonical copy:

• ../dep-diet/fixtures/runtime_record_contract/v1/adapter_diagnostics_vectors.v1.json

Keep these vectors synchronized when changing runtime-record diagnostics semantics.