# 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.