Eve library

Aja Stub-Indicator Triage (V1-P2-1700)

Guide

Revision 1

On this page

Date: 2026-05-03 Owner: eng-aja Inputs: aja-descope-decision.md (V1-P2-0331), scripts/stub-indicator-scan.sh --mode=stubs over libs/aja/ and apps/aja/. Outputs: Per-line verdict (REPLACE vs DESCOPE) for every stub-vocabulary hit under the Aja domain. Locks the V1-MET-197/198/199 + V1-AJA-* exit posture.

TL;DR#

The descope decision in V1-P2-0331 already locks the V1 ship list to motion-pipeline-sdk, motion-pipeline-sdk-python, motion-formats, svc-motion-pipeline, cli, the svc-motion-ai/embodied-instruction subtree, and the new libs/contracts/src/aja/ scaffold. All other Aja libraries are deferred to V2.

The current scanner pass over libs/aja/ and apps/aja/ finds 110 stub indicators. The original V1-P2-1700 ticket cited 60; the count grew as more files landed (the post-descope ML/GPU work continued to compile) but the classification rule is unchanged: V1-ship → REPLACE; everything else → DESCOPE under V1-P2-0331.

Verdict Count Action
REPLACE — wired by a follow-up 5 Tracked by V1-P2-1774 (cli convert) and V1-P2-1775 (svc-motion-pipeline processor); details in §1.
REPLACE-rephrase — false-pos 4 Real code with confidence-comments tripping the scanner; will be rewritten or annotated when next touched (§1).
DESCOPE-as-noncore in V1 2 V1-shipping libs whose specific stub site is non-core (C3D analog channels, post-job analytics blob); tracked here (§1).
DESCOPE-to-V2 via V1-P2-0331 99 Library is not on the V1 ship list and is deferred to V2. Each line is grouped by library in §2.
Total 110

The triage is the action: V1-P2-1700 produces this verdict table. The actual REPLACE work for V1-shipping libs is tracked under V1-P2-1774, V1-P2-1775, and the new V1-P2-1700a/b sub-tickets recorded here. The V2 DESCOPE list does not get inline // stub:legitimate markers in this task — those files belong to deferred libraries that are not on the V1 release manifest, are not exercised by PR diffs touching V1 paths, and the pre-commit scanner only fails on staged files. If V2 picks up an inference path, the V2 ticket will replace the stub or formally annotate it then.

1. V1-shipping libraries (REPLACE)#

1.1 libs/aja/motion-formats/#

The format library is V1 ship. Its stub-vocabulary hits are mostly confidence comments on real code, plus one non-core analog-channel branch.

File:line Hit text Verdict
libs/aja/motion-formats/src/usd.ts:956 // Simplified matrix parsing - would need more robust implementation REPLACE-rephrase — parseMatrixArray already extracts USD Matrix4d rows correctly via a regex over the canonical ((a,b,c,d), (...), ...) tuple syntax. Comment is a confidence note, not a stub.
libs/aja/motion-formats/src/fbx.ts:888 // Record header placeholder REPLACE-rephrase — writeNode reserves 13 bytes and back-fills the FBX node-record header (endOffset + numProperties + propertyListLen + nameLen) before the children are written. Real code.
libs/aja/motion-formats/src/fbx.ts:1026 // Footer checksum placeholder REPLACE-rephrase — FBX 7.x's footer checksum field is documented as 16 zero bytes for unsigned writers (Autodesk SDK matches). Code is correct; comment is misleading.
libs/aja/motion-formats/src/mocap-import.ts:362 // Simplified - would need full implementation to read analog parameters DESCOPE-as-noncore — V1's mocap import covers C3D marker data; analog channels (force plates / EMG) are out of scope for the V1 motion-conversion path. Track follow-up under a new V2 ticket if a user asks.

The four "REPLACE-rephrase" lines do not block V1 ship — the code below them is already production-quality. The next time those files are touched, the comment should be rewritten to drop the stub vocabulary; until then they continue to trip the scanner only if a future diff includes them, at which point an inline // stub:legitimate confidence-comment-on-real-code is acceptable.

The mocap-import.ts:362 line is a real stub but for a feature outside the locked V1 surface (the Aja V1 conversion path is BVH ↔ FBX ↔ glTF ↔ USD ↔ Alembic, not C3D analog channel passthrough). It is descoped from V1 here and should be picked up alongside any V2 motion-capture hardware integration.

1.2 apps/aja/svc-motion-pipeline/#

File:line Hit text Verdict
apps/aja/svc-motion-pipeline/src/app.ts:879 // This is a simplified processor - in a real implementation, REPLACE via V1-P2-1775 — the setupJobProcessor callback currently simulates stage timing; V1-P2-1775 wires the real motion-pipeline executor.
apps/aja/svc-motion-pipeline/src/delivery/result-delivery.ts:1014 // This is a placeholder for actual implementation (analytics branch) DESCOPE-as-noncore — the analytics output type is an optional post-job analytics blob, separate from the pipeline's primary/intermediate outputs. Not on V1 release scope.

1.3 apps/aja/cli/#

File:line Hit text Verdict
apps/aja/cli/src/commands/convert.ts:287 * This is a placeholder implementation. In production, this would use ... REPLACE via V1-P2-1774 — convertFile currently copies bytes; V1-P2-1774 wires @aja/motion-formats here.
apps/aja/cli/src/commands/convert.ts:334 // Write output (placeholder - would be actual converted data) REPLACE via V1-P2-1774 — same site, write side.
apps/aja/cli/src/commands/convert.ts:353 // All formats should be inter-convertible in a full implementation REPLACE-rephrase — comment in validateConversion describing format symmetry; the function below it does enforce the lossy-conversion table. Comment is documentation, not a stub.

1.4 libs/contracts/src/aja/, libs/aja/motion-pipeline-sdk{,-python}, apps/aja/svc-motion-ai/src/embodied-instruction/#

Clean. No --mode=stubs hits. The only Math.random() use in the SDK is retry jitter (libs/aja/motion-pipeline-sdk/src/client.ts:123), which is a legitimate randomness source per the V1-P2-0353 allow-list convention.

2. V2-deferred libraries (DESCOPE)#

The descope decision in V1-P2-0331 names the GPU paths (batch-inference, pipeline-parallelism, model-optimization), the ML inference libraries (neural-retargeting, human-mesh-recovery, pose-lifting, depth-sensing, multi-view-reconstruction, blend-shape-retargeting, proportional-adaptation, skeleton-mapping, semantic-retargeting), distributed-workers, the ML-adjacent stubs (content-moderation, content-security, content-watermarking, consent-management, data-retention), and the apps apps/aja/svc-motion-ai (excluding the embodied-instruction subtree, which is the canonical contract layer) and apps/aja/svc-reference-video.

By exclusion, every Aja library not on the V1 ship list is deferred to V2 — the descope doc treats the ship list as exhaustive. That includes the non-explicitly-named libs (asset-storage, avatar-integration, avatar-preview-ui, domain-motion-pipelines, motion-processing, motion-validation, optimization-ik, privacy-protection, result-aggregation, video-chunking) — none of these are on the V1 release manifest, none are deployed in the V1 Helm chart, and none gate V1-MET-197/198/199 (which exit at the canonical contract surface).

The 99 V2-DESCOPED lines, grouped by library:

2.1 GPU paths (V1-P2-0331 → V2)#

  • libs/aja/pipeline-parallelism/src/multi-gpu.ts:89,219,313,413,680 — CUDA / NVML bindings (V1-P2-1748).
  • libs/aja/pipeline-parallelism/src/scheduler.ts:334 — stage cancel hook.
  • libs/aja/pipeline-parallelism/src/stage.ts:634 — GPU metrics (V1-P2-1752).
  • libs/aja/model-optimization/src/tensorrt-compiler.ts:230,267,415,556 — TensorRT bindings + ONNX parser (V1-P2-1710, V1-P2-1711).
  • libs/aja/model-optimization/src/onnx-optimizer.ts:758 — ONNX Runtime / protobuf (V1-P2-1712).

2.2 ML inference (V1-P2-0331 → V2)#

  • libs/aja/human-mesh-recovery/src/body-fitting.ts:119 — automatic differentiation (V1-P2-1714).
  • libs/aja/human-mesh-recovery/src/mesh-skeleton.ts:272 — proper segmentation (V1-P2-1713).
  • libs/aja/human-mesh-recovery/src/smpl-recovery.ts:67,867 — SMPL data + YOLO/Faster R-CNN detector (V1-P2-1715).
  • libs/aja/neural-retargeting/src/inference.ts:453,728 — model + IK (V1-P2-1745, V1-P2-1746).
  • libs/aja/neural-retargeting/src/skeleton-graph.ts:555 — learned-embedding placeholder.
  • libs/aja/neural-retargeting/src/networks/layers.ts:572,845 — learned-weight aggregation + bidirectional pass (V1-P2-1751).
  • libs/aja/neural-retargeting/src/networks/style-transfer.ts:736,737 — symmetry / ground-contact.
  • libs/aja/pose-lifting/src/camera-estimation.ts:243 — symmetry averaging.
  • libs/aja/depth-sensing/src/mesh-recovery.ts:207 — octree solver (V1-P2-1738).
  • libs/aja/multi-view-reconstruction/src/calibration.ts:521,559 — ArUco + contour detection (V1-P2-1743, V1-P2-1744).
  • libs/aja/blend-shape-retargeting/src/muscle-deformation.ts:514,710,711 — muscle anatomy stubs.
  • libs/aja/blend-shape-retargeting/src/pipeline.ts:569 — deformation accuracy.
  • libs/aja/proportional-adaptation/src/pipeline.ts:373 — reach accuracy.
  • libs/aja/proportional-adaptation/src/reach-adjustment.ts:513 — full Jacobian.
  • libs/aja/semantic-retargeting/src/intent-preservation.ts:851 — adjustment optimizer.

2.3 Distributed workers (V1-P2-0331 → V2)#

  • libs/aja/distributed-workers/src/kubernetes.ts:259,313,357,376,527,549 — K8s API + WebSocket exec (V1-P2-1717, V1-P2-1718).
  • libs/aja/distributed-workers/src/fault-tolerance.ts:139 — worker health endpoint (V1-P2-1719).

2.4 ML-adjacent stubs (V1-P2-0331 → V2)#

  • libs/aja/content-moderation/src/upload-scanner.ts:367 — ML moderation (V1-P2-1716).
  • libs/aja/data-retention/src/data-export.ts:104 — storage upload.
  • libs/aja/data-retention/src/right-to-be-forgotten.ts:244 — digital signing (V1-P2-1747).

2.5 Non-core libs deferred by exclusion from V1 ship list#

These libraries are not explicitly named in V1-P2-0331's V2 list but are absent from the V1 ship list, so the descope doc treats them as V2 by exclusion. None ship in V1's Helm chart and none gate V1-MET-197/198/199.

  • libs/aja/asset-storage/src/automatic-archival.ts:548 — S3 restore (V1-P2-1730).
  • libs/aja/asset-storage/src/cdn-distribution.ts:263,274,285,373,374 — CloudFront / Cloudflare / Fastly / private-key signing (V1-P2-1731, V1-P2-1732, V1-P2-1733, V1-P2-1734).
  • libs/aja/avatar-integration/src/custom-avatar.ts:753,981 — avatar parsing (V1-P2-1740).
  • libs/aja/avatar-integration/src/yoga-pipeline.ts:951,1180 — skeleton-mapping (V1-P2-1735).
  • libs/aja/avatar-preview-ui/src/hooks/useAvatarPreview.ts:136 — direction-reverse state.
  • libs/aja/domain-motion-pipelines/src/yoga-pipeline.ts:3853 — placeholder arrays.
  • libs/aja/motion-processing/src/segmentation.ts:197 — ML model (V1-P2-1739).
  • libs/aja/motion-processing/src/physics-cleanup.ts:387 — velocity calculation.
  • libs/aja/motion-processing/src/noise-reduction.ts:333 — full inverse.
  • libs/aja/motion-validation/src/edge-case-testing.ts:1412,1936 — data generator + Perlin gradient tables (V1-P2-1749, V1-P2-1750).
  • libs/aja/motion-validation/src/types.ts:1311 — interface field literally named placeholder; not actionable.
  • libs/aja/motion-validation/src/metrics.ts:1199 — rotation-from-position approximation.
  • libs/aja/motion-validation/src/regression-testing.ts:783,908,1869 — image comparison + SSIM + file-loading (V1-P2-1742).
  • libs/aja/motion-validation/src/stress-testing.ts:118,132 — CPU monitoring + performance.now() timing (V1-P2-1737).
  • libs/aja/motion-validation/src/human-evaluation.ts:293,300,388,1272,1319 — UI form placeholder field + the literal word "fake" inside an evaluator keyword list ("realistic"/"fake"). Not actionable.
  • libs/aja/optimization-ik/src/full-body.ts:213 — multi-target Jacobian.
  • libs/aja/privacy-protection/src/face-detection.ts:47,63,110,116,269 — ML face / person detection (V1-P2-1736).
  • libs/aja/privacy-protection/src/identity-manager.ts:110,140 — embedding comparison.
  • libs/aja/result-aggregation/src/final-assembler.ts:364,365,515 — smoothing + interpolation hooks.
  • libs/aja/video-chunking/src/video-splitter.ts:53 — frame analysis (V1-P2-1741).
  • apps/aja/svc-reference-video/src/metadata-extraction.ts:272,289 — child_process.spawn ffprobe (V1-P2-1782).
  • apps/aja/svc-reference-video/src/scene-detection.ts:837 — action recognition (V1-P2-1780).
  • apps/aja/svc-reference-video/src/video-ingestion.ts:545,612,691,886 — fetch-with-progress + yt-dlp (V1-P2-1770, V1-P2-1771).
  • apps/aja/svc-reference-video/src/video-search.ts:367 — SVD/eigendecomposition (V1-P2-1776).
  • apps/aja/svc-motion-ai/src/live-motion-capture/realtime-pose-estimation.ts:1155 — MediaPipe inference (V1-P2-1772).
  • apps/aja/svc-motion-ai/src/live-motion-capture/types.ts:447 — JSDoc "will use defaults" prose; not actionable.
  • apps/aja/svc-motion-ai/src/motion-enhancement/motion-synthesis.ts:2291 — placeholder return.
  • apps/aja/svc-motion-ai/src/motion-retargeting/motion-retargeting-service.ts:1022 — leg IK.
  • apps/aja/svc-motion-ai/src/video-to-motion/pose-estimation-engine.ts:187 — MediaPipe Pose/Holistic (V1-P2-1781).
  • apps/aja/svc-motion-ai/src/video-to-motion/video-preprocessing.ts:73,74,703 — FFmpeg (V1-P2-1773).

3. Knock-on effects on V1-P2-1710..1789#

Many of the V1-P2-1710..1789 follow-up tasks target file:line sites in V2-deferred libraries (e.g. V1-P2-1710's TensorRT bindings live in model-optimization, which V1-P2-0331 deferred). Those tasks remain on the backlog as V2 candidates per V1-P2-0331; this triage does not close them individually. When V2 picks up the GPU/ML/distributed-workers strategy from V1-P2-0333 and V1-P2-0334, those tickets will either be reopened as V2 work or formally retired with a one-line note on the doc that supersedes them.

The genuinely V1-actionable tickets are:

  • V1-P2-1774 — wire the CLI convert command against @aja/motion-formats.
  • V1-P2-1775 — wire the svc-motion-pipeline job processor against the real pipeline executor.

Everything else under V1-P2-1710..1789 inherits the V2 deferral from V1-P2-0331 and from this triage.

4. What this triage does not do#

  • It does not add inline // stub:legitimate descoped-to-v2 (V1-P2-0331) markers across the 99 V2-deferred lines. Those files are not on the V1 PR diff path, the pre-commit scanner only fails on staged files, and bulk annotation would create unnecessary churn. If a future PR happens to touch one of those lines, the contributor adds the marker per the V1-P2-0353 allow-list convention at that moment.
  • It does not delete the deferred libraries. V1-P2-0331 explicitly keeps them so the monorepo continues to type-check and build.
  • It does not alter V1-MET-197/198/199 — those remain locked at the canonical Metis ↔ Aja contract surface (libs/metis/integrations/src/aja-canonical-wiring.ts + apps/aja/svc-motion-ai/src/embodied-instruction/), as the descope decision records.

5. Reproducing the scan#

bash
find libs/aja apps/aja -name '*.ts' \
  -not -path '*/node_modules/*' -not -path '*/dist/*' \
  -not -name '*.test.ts' -not -name '*.spec.ts' \
  -not -name 'vitest.config.ts' -not -name 'vite.config.ts' \
  > /tmp/aja-files.txt
xargs -a /tmp/aja-files.txt bash scripts/stub-indicator-scan.sh --mode=stubs

110 actionable hits at the time of writing.