git.stella-ops.org/docs/modules/scanner/design/analyzer-prep-0132.md

# Scanner Analyzer Prep · Sprint 0132

This note captures the unblockers promised in PREP tasks for Sprint 0132. Each subsection gives the artifact location, assumption set, and the handoff needed by downstream implementation tasks.

## SCANNER-ANALYZERS-LANG-11-003 (runtime fusion)
- **Objective:** Define the runtime evidence ingest contract to merge AssemblyLoad/Resolving/PInvoke signals with static edges from 11-002.
- **Inputs required:**
  - Static edge export format from 11-002 (AssemblyRef/ModuleRef/PInvoke with reason codes).
  - Event listener tap points: `AssemblyLoadContext.Resolving`, `AssemblyLoad`, `NativeLibrary.SetDllImportResolver`, `DynamicDependency` attributes, and optional ETW provider `Microsoft-Windows-DotNETRuntime` (keyword 0x8, task AssemblyLoad).
- **Runtime evidence envelope (AOC-aligned):**
  ```json
  {
    "runtime_observation_id": "uuid",
    "assembly_name": "System.Text.Json",
    "kind": "assembly-load|p-invoke|dynamic-dependency",
    "source": "Resolving|AssemblyLoad|NativeLibrary|ETW",
    "details": {
      "requested_name": "System.Text.Json",
      "resolved_path": "<normalized absolute path>",
      "assembly_version": "8.0.0.0",
      "culture": "neutral",
      "package_purl": "pkg:nuget/system.text.json@8.0.0",
      "confidence": 0.72,
      "reason_code": "runtime-resolve"
    },
    "timestamp_utc": "2025-11-20T00:00:00Z"
  }
  ```
- **Merge rules for downstream 11-003 implementation:**
  - De-dup edges by (assembly_name, resolved_path, kind).
  - Prefer static edge confidence when present; runtime adds `confidence_bonus = +0.1` but never exceeds 1.0.
  - Keep provenance: `edge.provenance = { "static": bool, "runtime": bool }`.
- **Publication:** This doc section is the frozen location for the runtime ingest contract; downstream tasks should reference this path.

## SCANNER-ANALYZERS-LANG-11-004 (observation export → writer/SBOM)
- **Objective:** Define the observation payload emitted to Scanner writer and SBOM entrypoint tagging.
- **Export envelope (AOC-compliant):**
  ```json
  {
    "entrypoints": [
      {
        "label": "app",
        "rids": ["win-x64","linux-x64"],
        "tfms": ["net8.0","net8.0-windows"],
        "command": "dotnet ./bin/app.dll",
        "sources": ["src/App/Program.cs"],
        "rank": 1
      }
    ],
    "dependency_edges": [
      {
        "from": "app",
        "to": "pkg:nuget/system.text.json@8.0.0",
        "reason_code": "assembly-ref",
        "confidence": 0.86,
        "provenance": {"static": true, "runtime": false}
      }
    ],
    "environment_profiles": {
      "tfm": "net8.0",
      "rid": "linux-x64",
      "host_policy": "portable",
      "features": ["singlefile:false","trimmed:false","nativeaot:false"]
    }
  }
  ```
- **Writer handoff:**
  - Serialize as deterministic JSON (sorted keys) to the Scanner writer contract `writer/observations/lang/dotnet`.
  - Attach `sbom_entrypoint_tags` derived from entrypoint labels to feed SBOM Service tagging.
- **Publication:** Payload shape and field meanings fixed here for Sprint 0132 downstream work.

## SCANNER-ANALYZERS-LANG-11-005 (fixtures & benchmarks)
- **Objective:** Provide fixture plan so QA can start without waiting on further design.
- **Fixture matrix:**
  - Framework-dependent: `net8.0`, `net9.0-preview` sample apps (console + web minimal API).
  - Self-contained: `linux-x64` trimmed vs non-trimmed.
  - Single-file: `win-x64` single-file publish, include native hosting bundle.
  - NativeAOT: `linux-x64` HelloWorld + P/Invoke stub.
  - Multi-RID: RID graph `linux-x64`, `linux-arm64`, `win-x64` with RID fallback expectations.
- **Locations:** place fixtures under `src/Scanner/__Tests/Fixtures/DotNet/11-005/*`; store expected observation JSON in `__Tests/Fixtures/DotNet/11-005/expected/*.json` with sorted keys.
- **Bench envelopes:**
  - Target <150 ms p95 per project scan on dev laptop, <25 MB heap delta; capture via BenchmarkDotNet and report to `__Benchmarks/11-005.md`.
- **Determinism:** lock timestamps to `1970-01-01T00:00:00Z` in serialized outputs; stable ordering by (entrypoint label, dependency to PURL, reason_code).

## SCANNER-ANALYZERS-NATIVE-20-002 (ELF declared-dependency writer contract)
- **Objective:** Unblock writer schema so native analyzer can emit DT_NEEDED/DT_RPATH/DT_RUNPATH data.
- **Edge record (per ELF binary):**
  ```json
  {
    "image": "libssl.so.3",
    "build_id": "cafef00d",
    "rpath": ["$ORIGIN/lib","/usr/lib"],
    "runpath": ["$ORIGIN","/opt/openssl"],
    "needed": [
      {"name": "libcrypto.so.3", "slot": 0, "version": "OPENSSL_3.0", "reason_code": "elf-dtneeded"},
      {"name": "libpthread.so.0", "slot": 1, "version": null, "reason_code": "elf-dtneeded"}
    ],
    "interpreter": "/lib64/ld-linux-x86-64.so.2",
    "origin": "virtual-fs",
    "confidence": 0.82
  }
  ```
- **Writer path:** `writer/observations/native/elf-declared-deps` (append-only NDJSON; sorted by image name then slot).
- **Redaction:** no host absolute paths; resolve `$ORIGIN` using virtual image root only.
- **Publication:** schema above is the agreed baseline for downstream tasks; time-boxed to Sprint 0132.

## SCANNER-ANALYZERS-NODE-22-001 (isolated runner / scoped build graph)
- **Objective:** Provide a deterministic way to run Node analyzer tests without fanning out the whole solution.
- **Approach:**
  - Add target solution filter: `src/Scanner/StellaOps.Scanner.Analyzers.Lang.Node.slnf` including only Node projects + shared test utilities.
  - Introduce `Directory.Build.props` override for `Lang.Node` tests to disable cross-solution restore (`DisableTransitiveProjectReferences=true`).
  - Test command for CI + local: `dotnet test src/Scanner/StellaOps.Scanner.Analyzers.Lang.Node.Tests/StellaOps.Scanner.Analyzers.Lang.Node.Tests.csproj /p:DisableTransitiveProjectReferences=true --no-restore --logger:"console;verbosity=minimal"`.
  - Cache seeds: copy pnpm/Yarn fixtures into `obj/fixtures-cache` during test init; deterministic zip timestamps set to `1980-01-01`.
- **Publication:** This runbook unblocks execution while broader solution build contention is resolved; downstream tasks should adopt this invocation until Sprint 131 completes.

---
**Owners:** Scanner EPDR Guild (DotNet), SBOM Service Guild, Native Analyzer Guild, Node Analyzer Guild.  
**Status:** All PREP artifacts published 2025-11-20.