# 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` is written alongside the analyzer and executed via `deno run --cached-only --allow-read --allow-env --quiet trace-shim.ts` with `STELLA_DENO_ENTRYPOINT` set to the target module.
   - Registers listeners:
     - `Deno.permissions.request/query/revoke` wrappers to capture permission uses and maintain a granted-permission snapshot (normalized to fs/net/env/ffi/process/worker).
     - Hooks `Deno[Deno.internal].moduleLoader.load` when available to observe module loads (static/dynamic/npm) before execution.
     - Wraps `WebAssembly.instantiate` / `instantiateStreaming` to record wasm loads.
     - Wraps `Deno.dlopen` to record FFI permission use.
   - Uses a synchronous SHA-256 implementation (no WebCrypto) to hash normalized module paths for determinism/offline safety.

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/worker runs `deno run --cached-only --allow-read --allow-env --quiet trace-shim.ts` with `STELLA_DENO_ENTRYPOINT=<entry>` (absolute or cwd-relative) and optional `STELLA_DENO_BINARY` override.
   - Respects `DENO_DIR` if present for npm cache resolution; still offline (`--cached-only`).

4) **Output**
   - After user code exits, shim writes buffered events as NDJSON sorted by timestamp then type to `<root>/deno-runtime.ndjson`.
   - Analyzer ingests the NDJSON, hashes content, stores payload in AnalysisStore under `ScanAnalysisKeys.DenoRuntimePayload` (legacy alias `"deno.runtime"` kept for backward compatibility), and emits policy signals keyed `surface.lang.deno.*`.

5) **Determinism & safety**
   - Timestamps: `Date.now()` captured and converted to ISO-8601 UTC; events sorted by ts then type.
   - Paths: resolved to analyzer-relative form, forward-slash normalized, hashed with built-in synchronous SHA-256 (lowercase hex); remote origins normalized to protocol//host/path.
   - No module source or env values persisted; only paths + hashes; npm resolutions recorded as cache hits only.

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