@tryinget/runtime-trace-insights 0.1.0

package/LICENSE

@@ -0,0 +1,78 @@
+MIT License (with OpenAI/Anthropic/xAI/PRC Frontier Labs Rider)
+
+Copyright (c) contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+ADDITIONAL RIDER / RESTRICTION (OpenAI / Anthropic / xAI / PRC Frontier Labs):
+
+This rider is part of the "conditions" of this License. In the event of any
+conflict between this rider and any other portion of this License, this rider
+controls.
+
+"Restricted Parties" means OpenAI, L.L.C.; Anthropic, PBC; xAI Corp.; and the
+following PRC frontier AI labs and related entities: Baidu (including ERNIE-
+related entities), Alibaba and Alibaba Cloud (including Qwen-related entities),
+Tencent (including Hunyuan-related entities), ByteDance (including Doubao/Seed-
+related entities), DeepSeek, Zhipu AI, Moonshot AI, MiniMax, 01.AI
+(Lingyiwanwu), and iFlyTek. "Restricted Parties" also includes any of their
+respective Affiliates and any person or entity acting directly or indirectly
+on behalf of, for the benefit of, or under the direction of any of the
+foregoing (including any officer, director, employee, contractor, agent,
+consultant, service provider, or representative).
+
+Notwithstanding any other provision of this License, no rights are granted to
+any Restricted Party. Any purported license, sublicense, assignment, transfer,
+or other permission to any Restricted Party is null and void absent the
+express prior written permission of the copyright holders.
+
+You may not provide, disclose, distribute, sublicense, sell, lease, lend,
+host, make available, or otherwise permit access to the Software or any
+derivative work of the Software (as defined in applicable copyright law)
+(collectively, "Derivative Works") to or for any Restricted Party.
+
+For purposes of this rider, "use" includes, without limitation: copying,
+modifying, merging, publishing, distributing, sublicensing, selling,
+transferring, making available, hosting, deploying, executing, benchmarking,
+testing, analyzing, indexing, or incorporating the Software or any Derivative
+Works into any dataset, training corpus, evaluation harness, or pipeline for
+machine learning or other automated systems.
+
+This rider applies to the Software and all Derivative Works. As a condition of
+use, you agree that this rider is a precondition to exercising any rights
+under this License, and you agree that any distribution of the Software or any
+Derivative Works must include this rider provision unmodified.
+
+Any breach of this rider automatically and immediately terminates the
+permissions granted by this License. Upon termination, you must immediately
+cease all use and distribution of the Software and any Derivative Works and
+destroy all copies under your control.
+
+You agree that a breach of this rider would cause irreparable harm and that
+the copyright holders may seek injunctive or other equitable relief to enforce
+this rider, in addition to any other remedies available at law. To the maximum
+extent permitted by applicable law, the prevailing party in any action to
+enforce this rider shall be entitled to recover reasonable attorneys' fees and
+costs.
+
+For purposes of this rider, "Affiliate" means any entity that directly or
+indirectly controls, is controlled by, or is under common control with the
+specified party. "Control" means ownership of more than 50% of the voting
+securities or other ownership interest, or the power to direct management or
+policies by contract or otherwise.
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,155 @@
+---
+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:
+
+```bash
+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:
+
+```bash
+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:
+
+```bash
+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`.
+
+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:
+
+```text
+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 a pinned, vendored `npm pack` tarball of this repo: `vendor/runtime-trace-insights-<version>-<sha7>.tgz`, with the full commit in `vendor/runtime-trace-insights.commit`. `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/` reaches dep-diet only after dep-diet re-vendors. Push it here, then in dep-diet run `scripts/vendor-runtime-trace-insights.sh <40-char-sha>` followed by `npm install --save file:vendor/<new tarball>`. Ping the dep-diet session or leave a dep-diet AK task. Until then, the pinned-vs-checkout scenario in `tests/features/depdiet_record_parity.feature` is skipped and names the pinned commit. While `src/` still matches the pin, it checks that dep-diet's vendored tarball records exactly what this checkout records.
+
+To try an unreleased checkout in dep-diet without re-vendoring, override the module:
+
+```bash
+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
+
+```bash
+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)
+- `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)
+
+## 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.

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@tryinget/runtime-trace-insights",
+  "version": "0.1.0",
+  "description": "Runtime-record flow and runtime-trace-bundle producer for dependency evidence; ships the dep-diet runtime-record adapter.",
+  "license": "SEE LICENSE IN LICENSE",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tryingET/runtime-trace-insights.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "exports": {
+    ".": "./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"
+  },
+  "scripts": {
+    "lint": "node scripts/lint.mjs",
+    "runtime-trace-bundle": "node scripts/runtime_trace_bundle.mjs",
+    "test": "node scripts/run_record_runtime_tests.mjs",
+    "test:record-runtime": "node scripts/run_record_runtime_tests.mjs",
+    "loop-doctor": "bash -lc 'echo \"loop-doctor: runtime-trace-insights diagnostics\"; node --version || true; npm --version || true; git status --short -- . || true; exit 0'",
+    "loop-verify-fast": "npm test",
+    "loop-impact-plan": "bash -lc 'changed=$( { git diff --name-only -- .; git ls-files --others --exclude-standard .; } | grep -v \"^$\" | sort -u ); echo \"loop-impact-plan: changed files\"; if [ -n \"$changed\" ]; then printf \"%s\\n\" \"$changed\"; else echo \"(none)\"; fi; if printf \"%s\\n\" \"$changed\" | grep -Eq \"^(package(-lock)?\\.json$|src/|scripts/|tests/|fixtures/)\"; then echo \"impact=wide\"; echo \"next=npm run loop-impact-wide\"; echo \"reason=runtime package, script, fixture, or test surface changed; use the full package gate\"; else echo \"impact=normal\"; echo \"next=npm run loop-impact-run\"; echo \"reason=docs/policy or localized non-runtime surface; use the normal package gate\"; fi'",
+    "loop-impact-run": "npm run lint && npm test",
+    "loop-impact-wide": "bash -lc 'echo \"loop-impact-wide: explicit wide validation accepted; reason=${LOOP_WIDE_REASON:-not-provided}\"; npm run lint && npm test'",
+    "loop-landing-check": "npm run lint && npm test",
+    "prepublishOnly": "npm run lint && npm test"
+  }
+}

package/src/.gitkeep

@@ -0,0 +1 @@
+

package/src/index.mjs

@@ -0,0 +1,3 @@
+export * from "./runtime_record/index.mjs";
+export * from "./runtime_trace_bundle/index.mjs";
+export { runtimeRecordAdapter as default } from "./runtime_record/depdiet_runtime_record_adapter.mjs";

package/src/runtime_record/depdiet_runtime_record_adapter.mjs

@@ -0,0 +1,80 @@
+import {
+  runRuntimeRecordFlow,
+  RUNTIME_RECORD_RESULT_SCHEMA_VERSION,
+} from "./runtime_record_flow.mjs";
+
+export const DEPDIET_RUNTIME_RECORD_ADAPTER_ID = "runtime-trace-insights.runtimeRecord.v1";
+export const RUNTIME_RECORD_ADAPTER_CONTRACT_VERSION = "depdiet.runtime.record.adapter.v1";
+
+function asNonEmptyString(value) {
+  if (typeof value !== "string") {
+    return null;
+  }
+
+  const normalized = value.trim();
+  return normalized.length > 0 ? normalized : null;
+}
+
+function createAdapterMetadata({ id, name }) {
+  return {
+    id: asNonEmptyString(id) ?? DEPDIET_RUNTIME_RECORD_ADAPTER_ID,
+    name: asNonEmptyString(name) ?? "runtime-trace-insights",
+    contractVersion: RUNTIME_RECORD_ADAPTER_CONTRACT_VERSION,
+    contract_version: RUNTIME_RECORD_ADAPTER_CONTRACT_VERSION,
+  };
+}
+
+function normalizeRuntimeRecordResult(result, adapterMetadata) {
+  const normalizedResult = result && typeof result === "object"
+    ? result
+    : {
+      ok: false,
+      diagnostics: [
+        {
+          code: "runtimeRecord.adapterInvalidResult",
+          level: "error",
+          source: "runtimeTraceInsightsAdapter",
+          message: "Runtime record flow returned a non-object result.",
+        },
+      ],
+    };
+
+  const schemaVersion = asNonEmptyString(normalizedResult.schema_version)
+    ?? asNonEmptyString(normalizedResult.schemaVersion)
+    ?? RUNTIME_RECORD_RESULT_SCHEMA_VERSION;
+
+  return {
+    ...normalizedResult,
+    schemaVersion,
+    schema_version: schemaVersion,
+    adapter: {
+      ...(normalizedResult.adapter && typeof normalizedResult.adapter === "object"
+        ? normalizedResult.adapter
+        : {}),
+      ...adapterMetadata,
+    },
+  };
+}
+
+export function createDepdietRuntimeRecordAdapter(options = {}) {
+  const adapterMetadata = createAdapterMetadata({
+    id: options.id,
+    name: options.name,
+  });
+
+  const runner = typeof options.runner === "function"
+    ? options.runner
+    : runRuntimeRecordFlow;
+
+  return {
+    ...adapterMetadata,
+    run(runtimeRecordOptions = {}) {
+      const result = runner(runtimeRecordOptions);
+      return normalizeRuntimeRecordResult(result, adapterMetadata);
+    },
+  };
+}
+
+export const runtimeRecordAdapter = createDepdietRuntimeRecordAdapter();
+
+export default runtimeRecordAdapter;

package/src/runtime_record/index.mjs

@@ -0,0 +1,18 @@
+export {
+  runRuntimeRecordFlow,
+  RUNTIME_RECORD_INTERNALS,
+  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,
+} from "./runtime_record_flow.mjs";
+
+export {
+  DEPDIET_RUNTIME_RECORD_ADAPTER_ID,
+  RUNTIME_RECORD_ADAPTER_CONTRACT_VERSION,
+  createDepdietRuntimeRecordAdapter,
+  runtimeRecordAdapter,
+} from "./depdiet_runtime_record_adapter.mjs";