up

docs/modules/scanner/cli-node.md

@@ -0,0 +1,18 @@
+# Scanner CLI: Node Analyzer Plug-in
+
+## Commands (to be exposed under `stella node`)
+- `stella node inspect <path>` — run language analyzer against a directory or bundle and emit JSON (AOC compliant).
+- `stella node resolve <specifier> --root <path>` — run the resolver (CJS+ESM) with condition set auto-detected.
+- `stella node runtime-ingest <evidence.ndjson>` — convert runtime evidence NDJSON into language records (stdout JSON).
+
+## Packaging expectations
+- Plug-in manifest: `plugins/scanner/node/manifest.json` (schemaVersion 1.0, id `stellaops.analyzer.lang.node`, version `0.1.0`, capabilities: language-analyzer · node · npm · pnpm · pnp · runtime-optional).
+- Payload: `StellaOps.Scanner.Analyzers.Lang.Node.dll` plus runtime hooks under `plugins/scanner/node/runtime-hooks/` (CJS require hook and ESM loader).
+- Restart-time activation: Scanner services must restart to load new plug-in; manifest declares `requiresRestart=true`.
+
+## Offline Kit
+- Include plug-in binaries + manifest + hooks + CLI shim in Offline Kit bundle.
+- Document CLI usage with no network dependency; registries are never contacted.
+
+## Determinism
+- Resolver, observation, and runtime ingestion outputs are deterministic (sorted keys, hashed loader IDs, scrubbed paths).

docs/modules/scanner/runtime-evidence.md

@@ -0,0 +1,33 @@
+# Scanner Runtime Evidence (Node)
+
+## Purpose
+Optional, air-gap-friendly runtime capture for Node workloads to enrich dependency graphs with observed imports/loads. Produces append-only NDJSON that the Node analyzer ingests as `node:runtime-*` records.
+
+## Capture hooks
+- **CJS**: `runtime-hooks/runtime-require-hook.js`
+  - Usage: `SCANNER_NODE_RUNTIME_OUT=<out.ndjson> SCANNER_NODE_ROOT=<root> node -r ./runtime-require-hook.js app.js`
+- **ESM**: `runtime-hooks/runtime-esm-loader.mjs`
+  - Usage: `SCANNER_NODE_RUNTIME_OUT=<out.ndjson> SCANNER_NODE_ROOT=<root> node --experimental-loader=./runtime-esm-loader.mjs app.mjs`
+
+## Output format (NDJSON)
+Each line is a JSON object:
+- `type`: `edge` | `component`
+- `from` / `to`: module specifiers (scrubbed relative to `SCANNER_NODE_ROOT` when possible)
+- `reason`: e.g., `runtime-import`, `runtime-require`, `runtime-load`
+- `loaderId`: arbitrary string; hashed to SHA-256 during ingestion
+- `path`: component path for `component` records
+
+## Ingestion rules
+- File name defaults to `node-runtime-evidence.ndjson` in the scan root; override with `SCANNER_NODE_RUNTIME_EVIDENCE`.
+- Paths are scrubbed relative to the analyzer `rootPath`; absolute paths outside root remain absolute.
+- Loader IDs are SHA-256 hashed before storage (`loaderId.sha256`).
+- Evidence is tagged as `node:runtime-edge` or `node:runtime-component` with derived evidence from the reason/locators.
+
+## Determinism & safety
+- Append-only writes; no network access.
+- Stable hashing, stable ordering during ingestion (sorted by `componentKey`).
+- Path scrubbing prevents leakage of host-specific prefixes when root-relative.
+
+## When to use
+- Debugging dynamic imports/require resolutions.
+- Environments with heavy plugin loading where static analysis is insufficient.

docs/modules/zastava/operations/runtime.md

@@ -123,12 +123,18 @@ It aligns with `Sprint 12 – Runtime Guardrails` and assumes components consume
   - Extract Prometheus rules into offline monitoring cluster (`/etc/prometheus/rules.d`).
   - Import Grafana dashboard via `grafana-cli --config ...`.
 
-## 6. Observability assets
-
+## 6. Observability assets
+
 - Prometheus alert rules: `docs/modules/zastava/operations/runtime-prometheus-rules.yaml`.
 - Grafana dashboard JSON: `docs/modules/zastava/operations/runtime-grafana-dashboard.json`.
-- Add both to the monitoring repo (`ops/monitoring/zastava`) and reference them in
-  the Offline Kit manifest.
+- Add both to the monitoring repo (`ops/monitoring/zastava`) and reference them in
+  the Offline Kit manifest.
+
+### 6.1 Surface manifest troubleshooting
+- Metrics: `zastava_surface_manifest_failures_total{reason=not_found|fetch_error}` increments when Observer cannot resolve cached `cas://` pointers or digests; correlate with Scanner cache health.
+- Evidence: Observer appends `runtime.surface.manifest{resolved|not_found|fetch_error}` plus `runtime.surface.manifestUri`/`manifestDigest` and up to five artifact metadata keys per manifest; view via drift diagnostics or runtime posture evidence.
+- Checklist: ensure `Surface:Manifest:RootDirectory` points to the Scanner cache mount, tenant matches `ZASTAVA_SURFACE_TENANT`, and `cas://` URIs from drift/entrytrace events exist on disk (`<root>/manifests/<hh>/<tt>/<digest>.json`).
+- Offline: if missing, sync the manifests directory from Offline Kit bundle into the Observer node cache and rerun the drift check. Avoid network fetches.
 
 ## 7. Build-id correlation & symbol retrieval