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

**Date:** 2026-05-03 **Owner:** eng-aja **Inputs:**
[`aja-descope-decision.md`](./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.
