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