# Aja V1 Descope Decision (V1-P2-0331)

**Date:** 2026-04-27 **Decision driver:**
[`aja-readiness-audit.md`](./aja-readiness-audit.md) (V1-P2-0330) **Owner:**
Platform / Aja domain leads **Status:** Locked — informs V1-P2-0332..0334 and
the V1-MET-197/198/199 exit criteria below.

## Decision

**Adopt the descope-to-MVP recommendation from V1-P2-0330.**

V1 ships a thin Aja MVP that is shippable today. All GPU / ML-inference /
distributed-worker functionality is **deferred to V2**, gated on the runtime
decisions captured in V1-P2-0333 (Kubernetes runtime) and V1-P2-0334 (GPU
pipeline) and the canonical contract scaffold from V1-P2-0332.

## What ships in V1

| Area                                | Subproject                                                                                                                            | Why it's V1-ready                                                                                          |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| Client SDK (TS)                     | `libs/aja/motion-pipeline-sdk`                                                                                                        | Real OAuth2 client, retry, NDJSON streaming, batch ops. ~7k LOC, has tests.                                |
| Client SDK (Python)                 | `libs/aja/motion-pipeline-sdk-python`                                                                                                 | Real `httpx`/`pydantic` async + sync clients, optional `torch`. ~8k LOC.                                   |
| Format conversion                   | `libs/aja/motion-formats`                                                                                                             | BVH/FBX/GLB/USD/Alembic; non-ML, deterministic.                                                            |
| Orchestration service               | `apps/aja/svc-motion-pipeline`                                                                                                        | Fastify-based job manager, webhooks, polling, streaming download. No GPU dependency.                       |
| CLI                                 | `apps/aja/cli`                                                                                                                        | Real CLI; thin wrapper over the SDK.                                                                       |
| Embodied-instruction contract layer | `apps/aja/svc-motion-ai/src/embodied-instruction/*` and the canonical wiring in `libs/metis/integrations/src/aja-canonical-wiring.ts` | Already shipped via V1-MET-197/198/199. Contract-level surface is real and tested.                         |
| New for V1                          | `libs/contracts/src/aja/`                                                                                                             | To be created in V1-P2-0332. Houses the canonical job/format/status contract that the SDK + service share. |
| New for V1                          | A `helm/aja-service` chart for `svc-motion-pipeline` only                                                                             | No GPU node pool; document explicitly that ML workers are V2.                                              |

## What is deferred to V2

These remain in `libs/aja/` but are **not part of the V1 ship list** and must be
excluded from V1 release artifacts (Helm, ArgoCD apps, docker-compose production
profiles, CI release pipelines):

- GPU paths: `batch-inference` GPU memory queries, `pipeline-parallelism`,
  `model-optimization` (TensorRT/mixed-precision/quantization).
- ML inference: `neural-retargeting`, `human-mesh-recovery`, `pose-lifting`,
  `depth-sensing`, `multi-view-reconstruction`, `blend-shape-retargeting`,
  `proportional-adaptation`, `skeleton-mapping`, `semantic-retargeting`.
- Distributed scaling: `distributed-workers` (its K8s health checks are
  simulated).
- ML-adjacent stubs: `content-moderation`, `content-security`,
  `content-watermarking`, `consent-management`, `data-retention`.
- Apps: `apps/aja/svc-motion-ai` (the embodied-instruction routes are
  real-looking but their underlying motion analysis depends on the deferred libs
  above), `apps/aja/svc-reference-video`.

The deferred libraries continue to compile and pass type checks so the monorepo
stays green; they just are not promoted to release tagging or production
deployment in V1.

## Why descope, not complete

Captured in detail in
[`aja-readiness-audit.md` §7.1](./aja-readiness-audit.md#71-reasoning). Summary:

1. Load-bearing inference paths are **simulated** (17 explicit `"in production"`
   markers; 124 `Math.random()` calls in implementation source; SMPL model data
   initialized as empty Float32Arrays).
2. **External procurement / decision blockers** stand in the way of real motion
   AI: SMPL weights, ONNX runtime selection, GPU runtime strategy, K8s operator
   strategy.
3. **Deployment posture is bare**: zero Aja Dockerfiles, no Helm chart, no GPU
   node-pool config, no `aja-ci.yml`.
4. **Test coverage is 9 / 37 libs** (~24 %), zero E2E tests connecting `cli` →
   service → workers.
5. Other Tier-A domains (`lilith`, `saraswati`) already ship Helm charts;
   matching their floor in V1 needs material work that must precede shipping any
   inference layer.

Completing the full domain in V1 would require a multi-quarter ML platform
build-out (model procurement, inference runtime, GPU operator, fault tolerance)
before any code in `human-mesh-recovery` etc. could be promoted beyond a stub.
Descoping removes that critical path from V1.

## Revised V1-MET-197/198/199 exit criteria

These three were already marked `[x]` in `OSHUN_V1_TODOS.md` (lines 5164–5187).
Their substance lives at the **canonical Metis↔Aja contract layer** in
`libs/metis/integrations/src/aja-canonical-wiring.ts` and the
`embodied-instruction` service surface in `apps/aja/svc-motion-ai`, both of
which are real today. The descope does **not** regress them; it simply clarifies
the surface they are guaranteeing.

The locked exit criteria after this decision:

- **V1-MET-197 — Confirm Aja embodied-instruction services exist as stable
  backend APIs:** Exit criterion is satisfied at the **service-interface level**
  — `embodied-instruction/service.ts`, `embodied-instruction/types.ts`,
  capabilities discovery endpoint, and demonstration / coaching-overlay /
  session-handoff endpoints with stable schemas. **No requirement** that the
  underlying motion-AI inference (e.g. `human-mesh-recovery`) be backed by real
  ML in V1 — the contract is what Metis consumes, and the contract is real.

- **V1-MET-198 — Canonical Aja adapter interface for Metis:** Exit criterion is
  satisfied by `libs/metis/integrations/src/aja-canonical-wiring.ts` defining
  the movement-demonstration / coaching-overlay / session-handoff contracts. The
  descope does not change this — the canonical wiring is the V1 ship target and
  remains valid.

- **V1-MET-199 — End-to-end integration tests:** Exit criterion is satisfied by
  `libs/metis/integrations/src/aja-canonical-wiring.integration.test.ts`
  exercising the canonical contract path. Under this descope, the test is
  expected to run against the **contract surface**, not against a live
  GPU-backed inference runtime. That posture is already what the test does today
  and is locked in by this decision.

If V2 rebuilds the underlying inference, V1-MET-197/198/199 will not need
re-opening — the canonical contract is the stable surface. New V2 tickets will
cover the live-inference exit criteria.

## Knock-on tasks

- **V1-P2-0332** — Create `libs/contracts/src/aja/` housing canonical contracts
  now that the descope is locked. The contracts to scaffold are the ones already
  drafted in `libs/metis/integrations/src/aja-canonical-wiring.ts` (movement
  demonstration, coaching overlay, session handoff) plus the job / format /
  status contracts already implicit in `motion-pipeline-sdk`.

- **V1-P2-0333** — Kubernetes runtime decision is **deferred** but should still
  produce a strategy doc at `docs/releases/p2/aja-runtime-strategy.md` recording
  the V1 posture (single Helm chart for the orchestration service; GPU node pool
  deferred).

- **V1-P2-0334** — GPU pipeline decision is **deferred** but should produce a
  strategy doc capturing the V2 candidates (CUDA via NVML, ROCm, cloud-only) and
  the data points needed to choose between them.

## What this decision does not change

- The Metis side of the integration (already shipped via V1-MET-197/198/199) is
  **not regressed**. Metis lessons that hand off to `embodied-instruction`
  continue to do so.
- The `libs/aja/README.md` aspirational claims about HMR 2.0, CLIFF, PyMAF-X,
  etc. **must be rewritten** before V1 ship to match the descoped reality.
  (Tracked separately under documentation hygiene.)
- No code is deleted by this decision. Deferred libraries continue to compile
  and pass type checks so the monorepo stays green. They are simply not on the
  V1 release manifest.
