git.stella-ops.org/docs/modules/scanner/design/deno-runtime-shim.md

Deno Runtime Trace Shim (draft v0.1)

This document specifies how the Deno analyzer will generate deno-runtime.ndjson traces offline for tasks DENO-26-009/010/011.

Objectives

• Capture module loads, permission uses, npm resolutions, and wasm loads during harnessed execution.
• Operate offline, deterministic ordering, and path redaction via relative paths + SHA256.
• Emit NDJSON per deno-runtime-signals.md and store to deno-runtime.ndjson at analyzer root.

Approach

1. Shim loader

   • Entry file trace-shim.ts injected ahead of user entrypoint (via --import-map or --unstable-preload-module).
   • Registers listeners:
     • Deno.permissions.query/deny/permit wrappers to observe grants.
     • globalThis.__originalImport = WebAssembly.instantiateStreaming to observe wasm loads (fallback to buffer) and record importer URL.
     • Wraps dynamic import by monkeypatching import via globalThis.__dynamicImport using createDynamicImportProxy helper (supported in Deno 1.42+).
   • Hooks Deno[Deno.internal].moduleLoader.load (where available) to observe resolved specifier and cache hit/miss reason; fallback to performance.resourceTimingBuffer not used.

2. Event buffering

   • Collects events in-memory; each event includes UTC timestamp and relative path (computed against analyzer root) plus path_sha256.
   • Origin normalization: for remote specifiers, strip query/fragment; record registry host/version if npm.

3. Execution

   • Analyzer runs deno run --allow-read --allow-env --no-lock --no-npm --quiet --import-map trace-import-map.json trace-shim.ts <user-entry>.
   • Optional: respect DENO_DIR from workspace normalization; no network fetch allowed (set --cached-only).

4. Output

   • After user code exits, shim writes buffered events as NDJSON sorted by timestamp then type to <root>/deno-runtime.ndjson.
   • Also prints SHA256 to stdout for diagnostics; Analyzer reads file and stores payload in AnalysisStore + signals.

5. Determinism & safety

   • Timestamps: Date.now() captured and converted to ISO-8601 UTC.
   • Paths: use analyzer root + path.relative + forward slashes; hash with SHA256(lowercase hex).
   • No module source or env values persisted; only paths + hashes.

Validation plan

• Add fixtures: simple import graph, dynamic import, wasm load, npm: chalk (cached), permission use via Deno.permissions.request.
• Golden NDJSON and hash comparison in tests; ensure stable ordering.

Open items

• Confirm --unstable-preload-module availability on target Deno version; fallback to import-map injection if unavailable.
• Verify WASM load interception across WebAssembly.instantiate vs instantiateStreaming.
• Ensure --cached-only works with npm cache; otherwise fallback to static npm graph without runtime fetch.