Another way

web/packages/new/photos/services/ml/face.ts

@@ -36,34 +36,37 @@ export const faceIndexingVersion = 1;
 /**
  * The faces in a file (and an embedding for each of them).
  *
- * This interface describes the format of remote face related data (aka "face
- * index") for a file. See {@link LocalFaceIndex} for the subset of the fields
- * that we also persist locally.
+ * This interface describes the format of face related data (aka "face index")
+ * for a file. This is the common subset that is present in both the fields that
+ * are persisted on remote ({@link RemoteFaceIndex}) and locally
+ * ({@link LocalFaceIndex}).
  *
- * - Local face detections and embeddings (collectively called as the face
- *   index) are generated by the current client when uploading a file, or when
- *   noticing a file which doesn't yet have a face index. They are then uploaded
- *   (E2EE) to remote, and the relevant bits also saved locally in the ML DB for
+ * - Face detections and embeddings (collectively called as the face index) are
+ *   generated by the current client when uploading a file, or when noticing a
+ *   file which doesn't yet have a face index. They are then uploaded (E2EE) to
+ *   remote, and the relevant bits also saved locally in the ML DB for
  *   subsequent lookup or clustering.
  *
- * - Remote embeddings are fetched by subsequent clients to avoid them having to
- *   reindex (indexing faces is a costly operation, esp. for mobile clients).
+ * - This face index is then fetched by subsequent clients to avoid them having
+ *   to reindex (indexing faces is a costly operation, esp. for mobile clients).
  *
  * In both these scenarios (whether generated locally or fetched from remote),
- * we end up with an face index described by this {@link RemoteFaceIndex}
- * interface. We slightly prune this when saving it to the local DB, and code
- * that runs locally only has access to the {@link LocalFaceIndex}.
- *
- * It has a top level envelope with information about the file (in particular
- * the primary key {@link fileID}), an inner envelope {@link faceEmbedding} with
- * metadata about the indexing, and an .
- *
- * The word embedding is used to refer two things: The last one (faceEmbedding >
- * faces > embedding) is the "actual" embedding, but sometimes we colloquially
- * refer to the inner envelope (the "faceEmbedding") also an embedding since a
- * file can have other types of embedding (envelopes), e.g. a "clipEmbedding".
+ * we end up with an some data described by this {@link FaceIndex} interface. We
+ * modify it slightly, adding envelopes, when saving them locally or uploading
+ * them to remote - those variations are described by the {@link LocalFaceIndex}
+ * and {@link RemoteFaceIndex} types respectively.
  */
-export interface RemoteFaceIndex {
+export interface FaceIndex {
+    /**
+     * The list of faces (and their embeddings) detected in the file.
+     *
+     * Each of the items is a {@link Face}, containing the result of a face
+     * detection, and an embedding for that detected face.
+     */
+    faces: Face[];
+}
+
+export type RemoteFaceIndex = FaceIndex & {
     /**
      * An integral version number of the indexing algorithm / pipeline.
      *
@@ -76,20 +79,9 @@ export interface RemoteFaceIndex {
      * The UA for the client which generated this embedding.
      */
     client: string;
-    /**
-     * The list of faces (and their embeddings) detected in the file.
-     *
-     * Each of the items is a {@link Face}, containing the result of a face
-     * detection, and an embedding for that detected face.
-     */
-    faces: Face[];
-}
+};
 
-/**
- * A pruned version of {@link RemoteFaceIndex} with data and shape that are
- * suitable for local persistence and usage.
- */
-export type LocalFaceIndex = Omit<RemoteFaceIndex, "version" | "client"> & {
+export type LocalFaceIndex = FaceIndex & {
     /**
      * The ID of the {@link EnteFile} whose index this is.
      *