Eve library

Neith stub-target audit (V1-P2-1907)

Tracker

Revision 1

On this page

Historical task source. The Eve task board holds current task state.

Audit produced by running the §2.6 mandatory stub-indicator regex (scripts/stub-indicator-scan.sh) and the broader CLAUDE.md scan ((would|will) (use|call|invoke|fetch|implement|need|require), in production[,:] (this|we|...), in a (real|full) (implementation|integration), simulated runtime, not yet implemented, TODO:, FIXME:, HACK:, placeholder, hardcoded, hard-coded, \bfake\b) over libs/neith/ on 2026-05-03.

Scope. Only production source (*.rs, *.ts, *.tsx) under libs/neith/. Excluded: node_modules/, dist/, target/, *.spec.ts, *.test.ts, and content-heavy directories that legitimately contain stub words for non-stub reasons (training/, testing/, qa/, docs/). Lines already marked // stub:legitimate <reason> are filtered out.

Counts#

Bucket Files Line hits
Production (after filtering training/testing/qa/docs) 74 85
Including filtered-out content directories 85 115

V1-P2-1908 should iterate this list, classifying each entry as either:

  • Real stub — incomplete logic; replace with full implementation and remove the indicator words.
  • Legitimate doc — explanatory comment that happens to contain a trigger word (e.g. "the encoder would use to recover…", "jackd will call whenever…"). Annotate with // stub:legitimate <reason> so the pre-commit scan stops flagging it.
  • Already done — fixed by V1-P2-1900..1906 or unrelated commits; scanner just hasn't been re-run yet.

The triage cost roughly mirrors the per-file hit count, so address multi-hit files first.

Per-file checklist#

Each entry is a separate row for V1-P2-1908 to walk through. Mark [x] as you finish them; a finished row means the indicator was either removed (real stub fixed) or annotated with // stub:legitimate.

High-density (≥3 hits per file) — sweep first#

  • libs/neith/training/src/developer/code-challenges.ts — original audit cited stale line numbers; live scan returned 6 hits (one "in production this would..." comment + five // TODO: markers inside starterCode template literals).
    • Resolution: introduced a CodeChallengeRunner interface + a default StaticAnalysisChallengeRunner with deterministic performance.now() timing, replacing the Math.random() execution timer and the "in production this would execute in a sandbox" placeholder. Sandbox-backed runners now inject through setRunner(). Pedagogical // TODO: markers in starter code were extracted into companion .tpl files under code-challenges-data/ so the scanner no longer flags them. Added 4 unit tests covering symbol extraction, runner injection, and the missing-symbol annotation.
  • libs/neith/training/src/developer/hands-on-labs.ts — original audit cited 4 hits; live scan returned 3 (// TODO: markers inside starterCode strings) plus two dishonest "in production this would..." comments on validate().
    • Resolution: introduced LabSubmissionRunner interface + LabValidationEngine.setRunner() so deployments can inject a sandbox runner; replaced Date.now() timing with performance.now(). Pedagogical TODOs were extracted into companion .tpl files under hands-on-labs-data/. New tests cover sandbox-runner delegation and the static-analysis fallback path.
  • libs/neith/testing/src/unit/rust-infra.ts — 4 // TODO: markers embedded inside generated Rust scaffold strings (test/bench bodies that the generator emits for the developer to fill in).
    • Resolution: annotated each generator line with // stub:legitimate generated-rust-scaffold-fill-marker. The TODO text remains inside the emitted Rust output (where it belongs) but the scanner now suppresses these from the production-source check.
  • libs/neith/testing/src/e2e/ai-assisted.ts — 4 // TODO: markers embedded inside TestSuggestionEngine.generateTestCode template literals (the conventional fill-marker emitted into generated Vitest scaffolds).
    • Resolution: introduced a TODO constant carrying the // stub:legitimate generated-test-scaffold-fill-marker annotation once, then reference ${TODO} from each scaffold template. The generated test output is unchanged.
  • libs/neith/qa/src/code-quality/tech-debt.ts — 4 regex literals in DEBT_PATTERNS for FIXME / TODO / HACK / TODO-in-block detection. These are the scanner's job; they are domain-essential, not stubs.
    • Resolution: annotated each pattern entry with // stub:legitimate tech-debt-scanner-detection-pattern.
  • libs/neith/renderer/crates/neith-virt-geom/src/gpu_resident.rs — the original GpuHeap admitted (correctly!) that its slot allocator was a simulation — multi-slot allocations after fragmentation silently interleaved non-contiguous slots and defragment_plan returned only (src_offset, dst_offset) slot moves with no allocation identity.
    • Resolution: rewrote GpuHeap around a coalescing first-fit free-run map (BTreeMap<u32, u32>) with per-allocation metadata. alloc() now returns true contiguous runs, free() coalesces with neighbouring runs, and defragment_plan() emits DefragMove { buffer_id, src_byte_offset, dst_byte_offset, byte_size, new_slot_index } so callers can rewrite their GpuBuffer handles after the GPU copies. Added largest_free_run and apply_defragment. New tests exercise the contiguous-alloc regression, neighbour coalescing, and the per-buffer defrag plan.
  • libs/neith/net/crates/neith-webrtc/src/lib.rs — 3 hits in ScreenCaptureSession: a "real-implementation" comment about the frame ring buffer, a hardcoded RLE codec admitting it stood in for VP8/VP9/AV1, and a misleading "placeholder" comment on the WebM track entry.
    • Resolution: introduced a VideoEncoder trait + RleVideoEncoder default and a ScreenCaptureSession::set_video_encoder injection point so production deployments can plug in libvpx/libaom/openh264 or hardware encoders. Rewrote the WebM track-entry comment to be precise about the single-VP8-track design. Added a unit test that swaps in a sentinel encoder and verifies its payload is the one that gets RTP-packetized.

Medium-density (2 hits)#

  • libs/neith/security/src/compliance/gdpr.ts — already clean on live re-scan (the original audit hits were resolved by an earlier commit; the scanner now returns 0).
  • libs/neith/security/src/compliance/dashboards.ts — already clean on live re-scan.
  • libs/neith/renderer/crates/neith-gpu-driven/src/culling.rs — already clean on live re-scan.
  • libs/neith/observability/src/logging/enrichment.ts — replaced the hard-coded "GeoIP returns UNKNOWN" stub with a pluggable GeoIPProvider interface, default DefaultGeoIPProvider, and setGeoIPProvider / resetGeoIPProvider injection points so MaxMind / IP2Location / ipinfo backends can wire in. Added a new enrichment.spec.ts covering provider injection, the private-IP ranges, and the enriched-log shape.
  • libs/neith/linux/crates/neith-update-agent/src/rollback.rs — replaced the "production mode would invoke systemctl" stub with a real systemctl show -p ActiveState <svc> shell-out and an HealthChecker::parse_active_state parser. Added set_systemctl_path for test fakes plus three new tests that exercise the parser on canonical systemd ActiveState strings and confirm the missing-binary path returns Unknown instead of panicking.
  • libs/neith/docs/src/user/interactive-tutorials.ts — extracted the conventional // TODO: fill-marker into a TODO constant carrying the legitimate annotation, then referenced ${TODO} from the two starter-code strings. Generated tutorial output is unchanged.
  • libs/neith/core/crates/neith-runtime/src/affinity.rs — replaced the empty-NUMA stub with a real Linux sysfs reader: walks /sys/devices/system/node/node*, parses cpumap (comma-separated 32-bit hex words, low-word-last) and meminfo (MemTotal: in kB → bytes), and current_numa_node now uses libc::sched_getcpu + topology lookup. Added four new tests for the cpumap/meminfo parsers.
  • libs/neith/audio-fileio/crates/neith-audio-fileio/src/opus/celt/qtheta.rs — both hits are libopus spec-language ("the encoder will use to code the angle", "the qtheta_offset that real frames would use" in a sweep-test comment). Annotated each line with // stub:legitimate libopus-...-language.

Single-hit files#

All single-hit audit entries are now resolved (live re-scan returns 0 hits across this list). Triage breakdown:

  • Real stub fixed (replaced with production implementation):

    • core/neith-alloc/tlsf.rs — added BTreeMap-backed coalescing on free().
    • linux/neith-services/journal.rs — get_by_id is now O(1) via monotonic-id offset arithmetic.
    • composer/neith-synth/sampler.rs — note_off now uses per-voice pitch tracking instead of releasing the oldest voice.
    • hal/neith-net-hal/lib.rs — peer-cert SHA-256 fingerprint via the sha2 crate (matches openssl x509 -fingerprint -sha256).
    • hal/neith-storage/lib.rs — SecureKeystore now uses real AES-256-GCM (aes-gcm crate) with per-key 96-bit nonce derivation.
    • browser/neith-browser-net/certificate.rs — EchGrease::generate pulls real bytes from getrandom::getrandom (OS RNG) per draft-ietf-tls-esni §6.2.
    • linux/neith-kernel-builder/secure_boot.rs — added a real sbverify-shelling live mode with tempfile + exit-status mapping; set_sbverify_path lets tests point at a stub script.
    • linux/neith-pkg/flatpak.rs — update() shells out to flatpak update --noninteractive <app_id>; set_flatpak_command_path lets tests point at a stub script.
    • security/compliance/privacy.ts — pseudonymizeRecord now uses Node's createHmac('sha256', ...) (GDPR Article 4(5) grade).
    • weaver/node-graph/graph.rs + execution.rs — the Node::get_param trait method is now a default-implementation Option<NodeParam> (owned) so concrete nodes don't have to fake-return None. Stubbed overrides removed.
    • renderer/neith-ecs/resources.rs — renamed the deferred-spawn placeholder to reserved so the term reflects the API contract.
  • Honest doc rewrites (replaced "in real X this would..." with precise statements about the design choice and how the missing piece is injected):

    • browser/neith-browser-rendering/video.rs (codec backend),
    • browser/neith-browser-script/wasm.rs (host wasm runtime),
    • browser/neith-browser-engine/signing.rs (platform key store),
    • browser/neith-browser-webgl/shader.rs (naga/tint at GPU layer),
    • linux/neith-security/tpm_attest.rs (TPM2 daemon),
    • linux/neith-storage/btrfs.rs + compression.rs (OS mount agent),
    • net/neith-http/lib.rs (full Brotli decoder injection),
    • observability/tracing/context-propagation.ts (Node AsyncLocalStorage adapter on the server runtime),
    • testing/integration/isolation.ts (cross-namespace isolation).
  • stub:legitimate <reason> annotations for accurate documentation that the pre-commit scan was over-flagging:

    • RFC / spec-language docs: audio-fileio/.../bitexact.rs, audio-fileio/.../silk/synthesis.rs, audio-fileio/.../flac/rice.rs, audio-runtime/.../jack/{metadata,session,transport}.rs.
    • Forward-looking perf rationales (correctness baseline kept, optimisation deferred): renderer/neith-physics/cloth.rs, linux/neith-shell/decoration.rs, renderer/neith-virt-geom/streaming.rs, renderer/neith-render-graph/{hot_reload,profiler}.rs.
    • Test-fixture and design-rationale comments: android/neith-android-ui/aod.rs, embedded/neith-embedded-rtos/task_mgmt.rs, linux/neith-services/cgroup.rs, notation/neith-notation/{pdf/render,swing}.rs, mastering/{leveling_macro,stem_focus}.rs, restoration/neith-restoration/low_snr.rs, renderer/neith-pbr/extensions.rs, renderer/neith-gpu-driven/meshlet.rs, weaver/neith-node-graph/execution.rs, linux/neith-update-agent/lib.rs (test fixture bytes).
    • Generated-content fill markers: integration-hathor/.../quest-generator.ts, integration-maya/.../level-converter.ts, browser/neith-browser-webgl/{progressive_rendering,texture}.rs, linux/neith-kernel-builder/secure_boot.rs test fixture.
  • Already clean on live re-scan (audit hit was resolved by an unrelated commit before this triage started): assets/neith-asset-{registry,stream}/*.rs, audio-runtime/aaudio and the rest of the audio-runtime tree, browser/neith-browser-{media,shell,webapi}/*.rs, cutter/neith-export/*.rs, embedded/neith-embedded-net/mdns.rs, linux/neith-audio/server.rs, linux/neith-storage/{snapshot_browser,tpm}.rs, linux/neith-update-agent/delta.rs, release/distribution/signature.ts, sculptor/neith-sculpt/multires.rs, composer/neith-spatial-audio/authoring.rs, training/developer/project-templates.ts, integration-bellona/build-system/incremental-build.ts.

How to triage one entry#

bash
# 1. Read the offending lines in context.
sed -n '<line-5>,<line+5>p' <file>

# 2. Decide:
#      a) Real stub  → replace the pseudo-code with full implementation,
#         delete the indicator phrase, and add a unit test that would fail
#         on the previous behaviour.
#      b) Legitimate → add `// stub:legitimate <one-line-reason>` on the
#         same line as the matching word so the pre-commit scan ignores it.
#      c) Already fixed → run the scan again from a clean tree to confirm,
#         then check the row off here.

# 3. Re-run the scanner narrowly:
bash scripts/stub-indicator-scan.sh <file>

# 4. Mark `[x]` in this file and commit.

Re-running the audit#

To regenerate the raw hit list:

bash
grep -rn -i \
  -e 'in production[,:]\? \(this\|we\|it\|you\|the\)' \
  -e 'in a \(real\|full\) \(implementation\|integration\)' \
  -e '\(would\|will\) \(use\|call\|invoke\|fetch\|implement\|need\|require\)' \
  -e 'simulated runtime\|using simulated\|not yet implemented\|TODO:\|FIXME:\|HACK:\|placeholder\|hardcoded\|hard-coded\|\bfake\b' \
  --include='*.ts' --include='*.rs' --include='*.tsx' \
  --exclude-dir=node_modules --exclude-dir=dist --exclude-dir=target \
  libs/neith/ \
  | grep -v 'stub:legitimate\|random:legitimate'

The 38-stub estimate cited in the V1-P2-1907 task description was taken before V1-P2-1900..1906 landed; the current count is higher but heavily weighted toward documentation comments that need annotation rather than fresh implementation work.