omnius 1.0.633 → 1.0.634

package/docs/DISCOVERY.json

@@ -4414,11 +4414,673 @@
         "packages/cli/src/api/openapi.ts"
       ]
     },
+    {
+      "id": "api.v1-audio-diarization-live",
+      "kind": "api",
+      "title": "/v1/audio/diarization/live",
+      "summary": "Diarize live/session-local speaker turns",
+      "aliases": [
+        "/v1/audio/diarization/live"
+      ],
+      "keywords": [
+        "rest",
+        "openapi",
+        "POST",
+        "Audio",
+        "v1",
+        "audio",
+        "diarization",
+        "live"
+      ],
+      "maturity": "stable",
+      "layer": "interface",
+      "audiences": [
+        "integrator",
+        "service-agent",
+        "coding-agent"
+      ],
+      "interfaces": [
+        {
+          "type": "rest",
+          "target": "POST /v1/audio/diarization/live"
+        },
+        {
+          "type": "openapi",
+          "target": "/openapi.json"
+        }
+      ],
+      "references": [
+        {
+          "type": "source",
+          "target": "packages/cli/src/api/openapi.ts",
+          "relation": "openapi-source"
+        },
+        {
+          "type": "documentation",
+          "target": "docs/reference/rest-api.md",
+          "relation": "endpoint-inventory"
+        }
+      ],
+      "methods": [
+        "POST"
+      ],
+      "tags": [
+        "Audio"
+      ],
+      "operations": {
+        "post": {
+          "summary": "Diarize live/session-local speaker turns",
+          "tags": [
+            "Audio"
+          ],
+          "description": "Reserved managed-inference contract: {session_id,file,asset_digest?,channel?,sample_rate_hz?,timeout_ms?}. A future persistent worker is limited to one active job plus one queued job and cancellation terminates the worker before clearing both. This build returns typed HTTP 503 speaker_diarization_runtime_unavailable rather than running a generic transcription diarization fallback. When available, output is omnius.speaker-diarization.v1 SpeakerTurnSpan[] with start_ms/end_ms/channel, explicit overlap, and labels scoped only to session_id; spans may populate audio_observation.diarizationClusterId but cannot create durable identities. Inference never installs or downloads.",
+          "responses": {
+            "200": {
+              "description": "Reserved for a future successful managed diarization result; current builds never return this response."
+            },
+            "403": {
+              "description": "Run scope required."
+            },
+            "503": {
+              "description": "Managed live diarization worker not shipped or not proven ready."
+            }
+          }
+        }
+      },
+      "source_of_truth": [
+        "GET /openapi.json",
+        "packages/cli/src/api/openapi.ts"
+      ]
+    },
+    {
+      "id": "api.v1-audio-diarization-live-cancel",
+      "kind": "api",
+      "title": "/v1/audio/diarization/live/cancel",
+      "summary": "Cancel live diarization work",
+      "aliases": [
+        "/v1/audio/diarization/live/cancel"
+      ],
+      "keywords": [
+        "rest",
+        "openapi",
+        "POST",
+        "Audio",
+        "v1",
+        "audio",
+        "diarization",
+        "live",
+        "cancel"
+      ],
+      "maturity": "stable",
+      "layer": "interface",
+      "audiences": [
+        "integrator",
+        "service-agent",
+        "coding-agent"
+      ],
+      "interfaces": [
+        {
+          "type": "rest",
+          "target": "POST /v1/audio/diarization/live/cancel"
+        },
+        {
+          "type": "openapi",
+          "target": "/openapi.json"
+        }
+      ],
+      "references": [
+        {
+          "type": "source",
+          "target": "packages/cli/src/api/openapi.ts",
+          "relation": "openapi-source"
+        },
+        {
+          "type": "documentation",
+          "target": "docs/reference/rest-api.md",
+          "relation": "endpoint-inventory"
+        }
+      ],
+      "methods": [
+        "POST"
+      ],
+      "tags": [
+        "Audio"
+      ],
+      "operations": {
+        "post": {
+          "summary": "Cancel live diarization work",
+          "tags": [
+            "Audio"
+          ],
+          "description": "Run scope required. The persistent-worker cancellation contract terminates the worker and clears its one active plus one queued request. Current builds return cancelled:false because no worker has been started.",
+          "responses": {
+            "200": {
+              "description": "Cancellation state."
+            },
+            "403": {
+              "description": "Run scope required."
+            }
+          }
+        }
+      },
+      "source_of_truth": [
+        "GET /openapi.json",
+        "packages/cli/src/api/openapi.ts"
+      ]
+    },
+    {
+      "id": "api.v1-audio-diarization-live-readiness",
+      "kind": "api",
+      "title": "/v1/audio/diarization/live/readiness",
+      "summary": "Read managed live speaker-turn diarization readiness",
+      "aliases": [
+        "/v1/audio/diarization/live/readiness"
+      ],
+      "keywords": [
+        "rest",
+        "openapi",
+        "GET",
+        "Audio",
+        "v1",
+        "audio",
+        "diarization",
+        "live",
+        "readiness"
+      ],
+      "maturity": "stable",
+      "layer": "interface",
+      "audiences": [
+        "integrator",
+        "service-agent",
+        "coding-agent"
+      ],
+      "interfaces": [
+        {
+          "type": "rest",
+          "target": "GET /v1/audio/diarization/live/readiness"
+        },
+        {
+          "type": "openapi",
+          "target": "/openapi.json"
+        }
+      ],
+      "references": [
+        {
+          "type": "source",
+          "target": "packages/cli/src/api/openapi.ts",
+          "relation": "openapi-source"
+        },
+        {
+          "type": "documentation",
+          "target": "docs/reference/rest-api.md",
+          "relation": "endpoint-inventory"
+        }
+      ],
+      "methods": [
+        "GET"
+      ],
+      "tags": [
+        "Audio"
+      ],
+      "operations": {
+        "get": {
+          "summary": "Read managed live speaker-turn diarization readiness",
+          "tags": [
+            "Audio"
+          ],
+          "description": "Non-mutating readiness for NVIDIA diar_streaming_sortformer_4spk-v2. It never downloads, installs, creates environments, or loads a model. Current Omnius builds intentionally return 503 until a managed persistent worker proves it can load an operator-verified local snapshot. The output contract is typed speaker-turn spans with explicit overlap and session-local labels only; those labels are never durable identities.",
+          "responses": {
+            "200": {
+              "description": "Reserved for a future worker-proven ready state; current builds never return this response."
+            },
+            "503": {
+              "description": "No verified managed live diarization worker is available; body still describes the exact model, snapshot state, and span/observation contract."
+            }
+          }
+        }
+      },
+      "source_of_truth": [
+        "GET /openapi.json",
+        "packages/cli/src/api/openapi.ts"
+      ]
+    },
+    {
+      "id": "api.v1-audio-diarization-live-setup",
+      "kind": "api",
+      "title": "/v1/audio/diarization/live/setup",
+      "summary": "Register a verified local live-diarization snapshot",
+      "aliases": [
+        "/v1/audio/diarization/live/setup"
+      ],
+      "keywords": [
+        "rest",
+        "openapi",
+        "POST",
+        "Audio",
+        "v1",
+        "audio",
+        "diarization",
+        "live",
+        "setup"
+      ],
+      "maturity": "stable",
+      "layer": "interface",
+      "audiences": [
+        "integrator",
+        "service-agent",
+        "coding-agent"
+      ],
+      "interfaces": [
+        {
+          "type": "rest",
+          "target": "POST /v1/audio/diarization/live/setup"
+        },
+        {
+          "type": "openapi",
+          "target": "/openapi.json"
+        }
+      ],
+      "references": [
+        {
+          "type": "source",
+          "target": "packages/cli/src/api/openapi.ts",
+          "relation": "openapi-source"
+        },
+        {
+          "type": "documentation",
+          "target": "docs/reference/rest-api.md",
+          "relation": "endpoint-inventory"
+        }
+      ],
+      "methods": [
+        "POST"
+      ],
+      "tags": [
+        "Audio"
+      ],
+      "operations": {
+        "post": {
+          "summary": "Register a verified local live-diarization snapshot",
+          "tags": [
+            "Audio"
+          ],
+          "description": "Admin-only. Body requires absolute snapshot_path and optional absolute manifest_path. The manifest must be omnius.audio-diarization-model-snapshot.v1 for nvidia/diar_streaming_sortformer_4spk-v2 with an immutable revision, relative artifact path, and sha256:<digest>; setup verifies those exact local bytes and records a private binding. It never downloads NeMo, CUDA, model weights, or dependencies and returns 202 because inference remains disabled until a worker is shipped.",
+          "requestBody": {
+            "required": true,
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "required": [
+                    "snapshot_path"
+                  ],
+                  "properties": {
+                    "snapshot_path": {
+                      "type": "string",
+                      "description": "Absolute local directory containing the operator-provided snapshot."
+                    },
+                    "manifest_path": {
+                      "type": "string",
+                      "description": "Optional absolute manifest path; defaults to snapshot_path/omnius-model-manifest.json."
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "responses": {
+            "202": {
+              "description": "snapshot_registered=true means only the local artifact bytes were verified; the runtime remains unavailable."
+            },
+            "400": {
+              "description": "Snapshot path or immutable manifest/digest validation failed."
+            },
+            "403": {
+              "description": "Admin scope required."
+            }
+          }
+        }
+      },
+      "source_of_truth": [
+        "GET /openapi.json",
+        "packages/cli/src/api/openapi.ts"
+      ]
+    },
+    {
+      "id": "api.v1-audio-diarization-reconcile",
+      "kind": "api",
+      "title": "/v1/audio/diarization/reconcile",
+      "summary": "Reconcile offline/dream diarization observations",
+      "aliases": [
+        "/v1/audio/diarization/reconcile"
+      ],
+      "keywords": [
+        "rest",
+        "openapi",
+        "POST",
+        "Audio",
+        "v1",
+        "audio",
+        "diarization",
+        "reconcile"
+      ],
+      "maturity": "stable",
+      "layer": "interface",
+      "audiences": [
+        "integrator",
+        "service-agent",
+        "coding-agent"
+      ],
+      "interfaces": [
+        {
+          "type": "rest",
+          "target": "POST /v1/audio/diarization/reconcile"
+        },
+        {
+          "type": "openapi",
+          "target": "/openapi.json"
+        }
+      ],
+      "references": [
+        {
+          "type": "source",
+          "target": "packages/cli/src/api/openapi.ts",
+          "relation": "openapi-source"
+        },
+        {
+          "type": "documentation",
+          "target": "docs/reference/rest-api.md",
+          "relation": "endpoint-inventory"
+        }
+      ],
+      "methods": [
+        "POST"
+      ],
+      "tags": [
+        "Audio"
+      ],
+      "operations": {
+        "post": {
+          "summary": "Reconcile offline/dream diarization observations",
+          "tags": [
+            "Audio"
+          ],
+          "description": "Reserved managed-inference contract: {observation_ids,episode_id?,timeout_ms?}. The supplied IDs refer to role-isolated AudioObservation records. A future pyannote worker can return only OfflineReconciliationProposal records: a proposed diarization_cluster_id, review requirement, and durable_identity:forbidden. This build returns typed HTTP 503 speaker_diarization_runtime_unavailable rather than pretending that a model catalogue entry is live. Inference never installs or downloads.",
+          "responses": {
+            "200": {
+              "description": "Reserved for a future successful managed reconciliation result; current builds never return this response."
+            },
+            "403": {
+              "description": "Run scope required."
+            },
+            "503": {
+              "description": "Managed reconciliation worker not shipped or not proven ready."
+            }
+          }
+        }
+      },
+      "source_of_truth": [
+        "GET /openapi.json",
+        "packages/cli/src/api/openapi.ts"
+      ]
+    },
+    {
+      "id": "api.v1-audio-diarization-reconcile-cancel",
+      "kind": "api",
+      "title": "/v1/audio/diarization/reconcile/cancel",
+      "summary": "Cancel offline diarization reconciliation work",
+      "aliases": [
+        "/v1/audio/diarization/reconcile/cancel"
+      ],
+      "keywords": [
+        "rest",
+        "openapi",
+        "POST",
+        "Audio",
+        "v1",
+        "audio",
+        "diarization",
+        "reconcile",
+        "cancel"
+      ],
+      "maturity": "stable",
+      "layer": "interface",
+      "audiences": [
+        "integrator",
+        "service-agent",
+        "coding-agent"
+      ],
+      "interfaces": [
+        {
+          "type": "rest",
+          "target": "POST /v1/audio/diarization/reconcile/cancel"
+        },
+        {
+          "type": "openapi",
+          "target": "/openapi.json"
+        }
+      ],
+      "references": [
+        {
+          "type": "source",
+          "target": "packages/cli/src/api/openapi.ts",
+          "relation": "openapi-source"
+        },
+        {
+          "type": "documentation",
+          "target": "docs/reference/rest-api.md",
+          "relation": "endpoint-inventory"
+        }
+      ],
+      "methods": [
+        "POST"
+      ],
+      "tags": [
+        "Audio"
+      ],
+      "operations": {
+        "post": {
+          "summary": "Cancel offline diarization reconciliation work",
+          "tags": [
+            "Audio"
+          ],
+          "description": "Run scope required. A future persistent worker is limited to one active job plus one queued job; cancellation terminates the worker before clearing both. Current builds return cancelled:false because no worker has been started.",
+          "responses": {
+            "200": {
+              "description": "Cancellation state."
+            },
+            "403": {
+              "description": "Run scope required."
+            }
+          }
+        }
+      },
+      "source_of_truth": [
+        "GET /openapi.json",
+        "packages/cli/src/api/openapi.ts"
+      ]
+    },
+    {
+      "id": "api.v1-audio-diarization-reconcile-readiness",
+      "kind": "api",
+      "title": "/v1/audio/diarization/reconcile/readiness",
+      "summary": "Read offline/dream speaker-reconciliation readiness",
+      "aliases": [
+        "/v1/audio/diarization/reconcile/readiness"
+      ],
+      "keywords": [
+        "rest",
+        "openapi",
+        "GET",
+        "Audio",
+        "v1",
+        "audio",
+        "diarization",
+        "reconcile",
+        "readiness"
+      ],
+      "maturity": "stable",
+      "layer": "interface",
+      "audiences": [
+        "integrator",
+        "service-agent",
+        "coding-agent"
+      ],
+      "interfaces": [
+        {
+          "type": "rest",
+          "target": "GET /v1/audio/diarization/reconcile/readiness"
+        },
+        {
+          "type": "openapi",
+          "target": "/openapi.json"
+        }
+      ],
+      "references": [
+        {
+          "type": "source",
+          "target": "packages/cli/src/api/openapi.ts",
+          "relation": "openapi-source"
+        },
+        {
+          "type": "documentation",
+          "target": "docs/reference/rest-api.md",
+          "relation": "endpoint-inventory"
+        }
+      ],
+      "methods": [
+        "GET"
+      ],
+      "tags": [
+        "Audio"
+      ],
+      "operations": {
+        "get": {
+          "summary": "Read offline/dream speaker-reconciliation readiness",
+          "tags": [
+            "Audio"
+          ],
+          "description": "Non-mutating readiness for pyannote/speaker-diarization-community-1. It never downloads, installs, creates environments, or loads a model. Current Omnius builds intentionally return 503 until a managed persistent worker proves it can load an operator-verified local snapshot. Reconciliation may make only reviewable file/episode cluster proposals, never durable identity claims.",
+          "responses": {
+            "200": {
+              "description": "Reserved for a future worker-proven ready state; current builds never return this response."
+            },
+            "503": {
+              "description": "No verified managed reconciliation worker is available; body still describes the exact model, snapshot state, and proposal/observation contract."
+            }
+          }
+        }
+      },
+      "source_of_truth": [
+        "GET /openapi.json",
+        "packages/cli/src/api/openapi.ts"
+      ]
+    },
+    {
+      "id": "api.v1-audio-diarization-reconcile-setup",
+      "kind": "api",
+      "title": "/v1/audio/diarization/reconcile/setup",
+      "summary": "Register a verified local reconciliation snapshot",
+      "aliases": [
+        "/v1/audio/diarization/reconcile/setup"
+      ],
+      "keywords": [
+        "rest",
+        "openapi",
+        "POST",
+        "Audio",
+        "v1",
+        "audio",
+        "diarization",
+        "reconcile",
+        "setup"
+      ],
+      "maturity": "stable",
+      "layer": "interface",
+      "audiences": [
+        "integrator",
+        "service-agent",
+        "coding-agent"
+      ],
+      "interfaces": [
+        {
+          "type": "rest",
+          "target": "POST /v1/audio/diarization/reconcile/setup"
+        },
+        {
+          "type": "openapi",
+          "target": "/openapi.json"
+        }
+      ],
+      "references": [
+        {
+          "type": "source",
+          "target": "packages/cli/src/api/openapi.ts",
+          "relation": "openapi-source"
+        },
+        {
+          "type": "documentation",
+          "target": "docs/reference/rest-api.md",
+          "relation": "endpoint-inventory"
+        }
+      ],
+      "methods": [
+        "POST"
+      ],
+      "tags": [
+        "Audio"
+      ],
+      "operations": {
+        "post": {
+          "summary": "Register a verified local reconciliation snapshot",
+          "tags": [
+            "Audio"
+          ],
+          "description": "Admin-only. Body requires absolute snapshot_path and optional absolute manifest_path. The manifest must be omnius.audio-diarization-model-snapshot.v1 for pyannote/speaker-diarization-community-1 with an immutable revision, relative artifact path, and sha256:<digest>; setup verifies those exact local bytes and records a private binding. It never downloads pyannote, model weights, or dependencies and returns 202 because inference remains disabled until a worker is shipped.",
+          "requestBody": {
+            "required": true,
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "required": [
+                    "snapshot_path"
+                  ],
+                  "properties": {
+                    "snapshot_path": {
+                      "type": "string"
+                    },
+                    "manifest_path": {
+                      "type": "string"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "responses": {
+            "202": {
+              "description": "snapshot_registered=true means only the local artifact bytes were verified; the runtime remains unavailable."
+            },
+            "400": {
+              "description": "Snapshot path or immutable manifest/digest validation failed."
+            },
+            "403": {
+              "description": "Admin scope required."
+            }
+          }
+        }
+      },
+      "source_of_truth": [
+        "GET /openapi.json",
+        "packages/cli/src/api/openapi.ts"
+      ]
+    },
     {
       "id": "api.v1-audio-embed",
       "kind": "api",
       "title": "/v1/audio/embed",
-      "summary": "Create an audio embedding for uploaded or referenced audio",
+      "summary": "Create a managed role-typed audio embedding",
       "aliases": [
         "/v1/audio/embed"
       ],
@@ -4426,7 +5088,7 @@
         "rest",
         "openapi",
         "POST",
-        "Voice",
+        "Audio",
         "v1",
         "audio",
         "embed"
@@ -4464,20 +5126,310 @@
         "POST"
       ],
       "tags": [
-        "Voice"
+        "Audio"
       ],
       "operations": {
         "post": {
-          "summary": "Create an audio embedding for uploaded or referenced audio",
+          "summary": "Create a managed role-typed audio embedding",
           "tags": [
-            "Voice"
+            "Audio"
+          ],
+          "description": "Alias of POST /v1/tools/audio_analyze/call with args.action forced to embed. Canonical form: POST /v1/audio/embed?kind=acoustic|speaker|semantic with {args:{file|path,...},timeout_ms?,profile?,working_dir?}; body.kind and args.kind are compatibility aliases. Legacy top-level path/file is normalized into args. bytesBase64 is rejected because every managed runtime accepts a retained caller-supplied WAV path only. It preserves the exact direct-tool auth, profile, origin, output-cap, timeout, and cancellation contract. The route passes the requested role through exactly and never substitutes vector spaces. Poll /v1/audio/embed/health?kind=<role> first; inference never installs dependencies or downloads weights.",
+          "parameters": [
+            {
+              "name": "kind",
+              "in": "query",
+              "required": false,
+              "schema": {
+                "type": "string",
+                "enum": [
+                  "acoustic",
+                  "speaker",
+                  "semantic"
+                ]
+              },
+              "description": "Canonical location for the required role kind; body.kind is accepted for compatibility."
+            }
+          ],
+          "requestBody": {
+            "required": true,
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "kind": {
+                      "type": "string",
+                      "enum": [
+                        "acoustic",
+                        "speaker",
+                        "semantic"
+                      ]
+                    },
+                    "path": {
+                      "type": "string",
+                      "description": "Compatibility input; normalized into args.path."
+                    },
+                    "file": {
+                      "type": "string",
+                      "description": "Compatibility input; normalized into args.file."
+                    },
+                    "args": {
+                      "type": "object",
+                      "properties": {
+                        "file": {
+                          "type": "string"
+                        },
+                        "path": {
+                          "type": "string"
+                        }
+                      }
+                    },
+                    "timeout_ms": {
+                      "type": "integer",
+                      "minimum": 1000,
+                      "maximum": 120000
+                    },
+                    "max_output_chars": {
+                      "type": "integer"
+                    },
+                    "profile": {
+                      "type": "string"
+                    },
+                    "working_dir": {
+                      "type": "string",
+                      "description": "Admin scope only."
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "responses": {
+            "200": {
+              "description": "Direct audio_analyze result envelope; consume result.data for the role-typed embedding."
+            },
+            "400": {
+              "description": "Invalid body or embedding kind"
+            },
+            "403": {
+              "description": "Direct-tool scope/profile/origin policy denied the call"
+            },
+            "503": {
+              "description": "Requested role runtime is unavailable"
+            }
+          }
+        }
+      },
+      "source_of_truth": [
+        "GET /openapi.json",
+        "packages/cli/src/api/openapi.ts"
+      ]
+    },
+    {
+      "id": "api.v1-audio-embed-health",
+      "kind": "api",
+      "title": "/v1/audio/embed/health",
+      "summary": "Read role-typed audio embedding readiness",
+      "aliases": [
+        "/v1/audio/embed/health"
+      ],
+      "keywords": [
+        "rest",
+        "openapi",
+        "GET",
+        "Audio",
+        "v1",
+        "audio",
+        "embed",
+        "health"
+      ],
+      "maturity": "stable",
+      "layer": "interface",
+      "audiences": [
+        "integrator",
+        "service-agent",
+        "coding-agent"
+      ],
+      "interfaces": [
+        {
+          "type": "rest",
+          "target": "GET /v1/audio/embed/health"
+        },
+        {
+          "type": "openapi",
+          "target": "/openapi.json"
+        }
+      ],
+      "references": [
+        {
+          "type": "source",
+          "target": "packages/cli/src/api/openapi.ts",
+          "relation": "openapi-source"
+        },
+        {
+          "type": "documentation",
+          "target": "docs/reference/rest-api.md",
+          "relation": "endpoint-inventory"
+        }
+      ],
+      "methods": [
+        "GET"
+      ],
+      "tags": [
+        "Audio"
+      ],
+      "operations": {
+        "get": {
+          "summary": "Read role-typed audio embedding readiness",
+          "tags": [
+            "Audio"
+          ],
+          "description": "Requires kind=acoustic|speaker|semantic. Each kind dispatches only to its role-correct managed runtime: acoustic is Jetson TensorRT YAMNet (1024d), speaker is CPU-only WeSpeaker CAM++ (512d), and semantic is Jetson CUDA CLAP (512d). A 503 means that requested role is unprovisioned or its worker is unready; Omnius never substitutes another vector space. This endpoint is non-provisioning: it never installs dependencies, downloads weights, or runs embedding inference.",
+          "parameters": [
+            {
+              "name": "kind",
+              "in": "query",
+              "required": true,
+              "schema": {
+                "type": "string",
+                "enum": [
+                  "acoustic",
+                  "speaker",
+                  "semantic"
+                ]
+              }
+            }
+          ],
+          "responses": {
+            "200": {
+              "description": "The requested role-specific embedding runtime is warm and ready."
+            },
+            "400": {
+              "description": "kind is missing or invalid"
+            },
+            "503": {
+              "description": "The requested role runtime is unprovisioned or unready; response retains that role's exact vector-space metadata."
+            }
+          }
+        }
+      },
+      "source_of_truth": [
+        "GET /openapi.json",
+        "packages/cli/src/api/openapi.ts"
+      ]
+    },
+    {
+      "id": "api.v1-audio-embed-setup",
+      "kind": "api",
+      "title": "/v1/audio/embed/setup",
+      "summary": "Provision and activate one role-typed audio embedding runtime",
+      "aliases": [
+        "/v1/audio/embed/setup"
+      ],
+      "keywords": [
+        "rest",
+        "openapi",
+        "POST",
+        "Audio",
+        "v1",
+        "audio",
+        "embed",
+        "setup"
+      ],
+      "maturity": "stable",
+      "layer": "interface",
+      "audiences": [
+        "integrator",
+        "service-agent",
+        "coding-agent"
+      ],
+      "interfaces": [
+        {
+          "type": "rest",
+          "target": "POST /v1/audio/embed/setup"
+        },
+        {
+          "type": "openapi",
+          "target": "/openapi.json"
+        }
+      ],
+      "references": [
+        {
+          "type": "source",
+          "target": "packages/cli/src/api/openapi.ts",
+          "relation": "openapi-source"
+        },
+        {
+          "type": "documentation",
+          "target": "docs/reference/rest-api.md",
+          "relation": "endpoint-inventory"
+        }
+      ],
+      "methods": [
+        "POST"
+      ],
+      "tags": [
+        "Audio"
+      ],
+      "operations": {
+        "post": {
+          "summary": "Provision and activate one role-typed audio embedding runtime",
+          "tags": [
+            "Audio"
+          ],
+          "description": "Admin-only. Requires kind=acoustic|speaker|semantic in the query (canonical) or JSON body. acoustic reuses the pinned JetPack YAMNet/TensorRT setup; speaker installs the isolated CPU-only WeSpeaker CAM++ ONNX Runtime and pinned model; semantic installs the isolated JetPack CUDA CLAP dependencies and pinned model. This is the only REST operation allowed to provision. It activates and warms only the requested role worker; no role is substituted for another.",
+          "parameters": [
+            {
+              "name": "kind",
+              "in": "query",
+              "required": false,
+              "schema": {
+                "type": "string",
+                "enum": [
+                  "acoustic",
+                  "speaker",
+                  "semantic"
+                ]
+              },
+              "description": "Canonical required role selector; JSON body.kind is accepted for compatibility."
+            }
           ],
+          "requestBody": {
+            "required": false,
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "kind": {
+                      "type": "string",
+                      "enum": [
+                        "acoustic",
+                        "speaker",
+                        "semantic"
+                      ]
+                    }
+                  }
+                }
+              }
+            }
+          },
           "responses": {
             "200": {
-              "description": "Audio embedding result"
+              "description": "Requested role runtime provisioned and warm."
+            },
+            "202": {
+              "description": "Provisioning finished but requested role did not prove warm; poll its health URL."
             },
             "400": {
-              "description": "Invalid audio input"
+              "description": "kind is missing or invalid."
+            },
+            "403": {
+              "description": "Admin scope required."
+            },
+            "500": {
+              "description": "Role-specific setup/preflight failed."
             }
           }
         }
@@ -10371,6 +11323,332 @@
         "packages/cli/src/api/openapi.ts"
       ]
     },
+    {
+      "id": "api.v1-memory-speaker-identities-enroll",
+      "kind": "api",
+      "title": "/v1/memory/speaker-identities/enroll",
+      "summary": "Enroll an explicitly self-identified speaker exemplar",
+      "aliases": [
+        "/v1/memory/speaker-identities/enroll"
+      ],
+      "keywords": [
+        "rest",
+        "openapi",
+        "POST",
+        "Memory",
+        "Audio",
+        "v1",
+        "memory",
+        "speaker-identities",
+        "enroll"
+      ],
+      "maturity": "stable",
+      "layer": "interface",
+      "audiences": [
+        "integrator",
+        "service-agent",
+        "coding-agent"
+      ],
+      "interfaces": [
+        {
+          "type": "rest",
+          "target": "POST /v1/memory/speaker-identities/enroll"
+        },
+        {
+          "type": "openapi",
+          "target": "/openapi.json"
+        }
+      ],
+      "references": [
+        {
+          "type": "source",
+          "target": "packages/cli/src/api/openapi.ts",
+          "relation": "openapi-source"
+        },
+        {
+          "type": "documentation",
+          "target": "docs/reference/rest-api.md",
+          "relation": "endpoint-inventory"
+        }
+      ],
+      "methods": [
+        "POST"
+      ],
+      "tags": [
+        "Memory",
+        "Audio"
+      ],
+      "operations": {
+        "post": {
+          "summary": "Enroll an explicitly self-identified speaker exemplar",
+          "tags": [
+            "Memory",
+            "Audio"
+          ],
+          "description": "Admin-only durable biometric enrollment. Body requires {scope_id, identity, observation_id, consent:{basis:'explicit_self_identification', asserted_by,...}, space:{embedding_set_slug,model,model_revision,model_digest,dimensions,normalization:'l2'}}. observation_id must already hold exactly one role-isolated speaker_identity_embedding in that exact model/revision/digest/set/dimension. Sender metadata and diarization labels are never identity proof; this endpoint creates no voice_sample_of or other identity graph edges and never returns a centroid/vector.",
+          "requestBody": {
+            "required": true,
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "required": [
+                    "scope_id",
+                    "identity",
+                    "observation_id",
+                    "consent",
+                    "space"
+                  ],
+                  "properties": {
+                    "scope_id": {
+                      "type": "string"
+                    },
+                    "identity": {
+                      "type": "string"
+                    },
+                    "observation_id": {
+                      "type": "string"
+                    },
+                    "consent": {
+                      "type": "object",
+                      "required": [
+                        "basis",
+                        "asserted_by"
+                      ],
+                      "properties": {
+                        "basis": {
+                          "type": "string",
+                          "enum": [
+                            "explicit_self_identification"
+                          ]
+                        },
+                        "asserted_by": {
+                          "type": "string"
+                        },
+                        "asserted_at": {
+                          "type": "string",
+                          "format": "date-time"
+                        },
+                        "note": {
+                          "type": "string"
+                        }
+                      }
+                    },
+                    "space": {
+                      "type": "object",
+                      "required": [
+                        "embedding_set_slug",
+                        "model",
+                        "model_revision",
+                        "model_digest",
+                        "dimensions",
+                        "normalization"
+                      ],
+                      "properties": {
+                        "embedding_set_slug": {
+                          "type": "string"
+                        },
+                        "model": {
+                          "type": "string"
+                        },
+                        "model_revision": {
+                          "type": "string"
+                        },
+                        "model_digest": {
+                          "type": "string"
+                        },
+                        "dimensions": {
+                          "type": "integer",
+                          "minimum": 1
+                        },
+                        "normalization": {
+                          "type": "string",
+                          "enum": [
+                            "l2"
+                          ]
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "responses": {
+            "201": {
+              "description": "Consent-gated profile updated; only exemplar IDs and metadata are returned."
+            },
+            "400": {
+              "description": "Consent, observation role, or exact vector-space contract invalid."
+            },
+            "403": {
+              "description": "Admin scope required."
+            }
+          }
+        }
+      },
+      "source_of_truth": [
+        "GET /openapi.json",
+        "packages/cli/src/api/openapi.ts"
+      ]
+    },
+    {
+      "id": "api.v1-memory-speaker-identities-match",
+      "kind": "api",
+      "title": "/v1/memory/speaker-identities/match",
+      "summary": "Query durable speaker candidates in one exact vector space",
+      "aliases": [
+        "/v1/memory/speaker-identities/match"
+      ],
+      "keywords": [
+        "rest",
+        "openapi",
+        "POST",
+        "Memory",
+        "Audio",
+        "v1",
+        "memory",
+        "speaker-identities",
+        "match"
+      ],
+      "maturity": "stable",
+      "layer": "interface",
+      "audiences": [
+        "integrator",
+        "service-agent",
+        "coding-agent"
+      ],
+      "interfaces": [
+        {
+          "type": "rest",
+          "target": "POST /v1/memory/speaker-identities/match"
+        },
+        {
+          "type": "openapi",
+          "target": "/openapi.json"
+        }
+      ],
+      "references": [
+        {
+          "type": "source",
+          "target": "packages/cli/src/api/openapi.ts",
+          "relation": "openapi-source"
+        },
+        {
+          "type": "documentation",
+          "target": "docs/reference/rest-api.md",
+          "relation": "endpoint-inventory"
+        }
+      ],
+      "methods": [
+        "POST"
+      ],
+      "tags": [
+        "Memory",
+        "Audio"
+      ],
+      "operations": {
+        "post": {
+          "summary": "Query durable speaker candidates in one exact vector space",
+          "tags": [
+            "Memory",
+            "Audio"
+          ],
+          "description": "Admin-only exact-space biometric candidate query. Body requires {scope_id, vector, dimensions, space:{embedding_set_slug,model,model_revision,model_digest,normalization:'l2'}} and optional thresholds. It searches only consented speaker_identity_embedding centroids in the same scope and exact set/model/revision/digest/dimension—never generic memory vectors, acoustic vectors, semantic vectors, sender data, or diarization labels. Outcomes are provisional, ambiguous, or no_match and never assign a durable identity.",
+          "requestBody": {
+            "required": true,
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "required": [
+                    "scope_id",
+                    "vector",
+                    "dimensions",
+                    "space"
+                  ],
+                  "properties": {
+                    "scope_id": {
+                      "type": "string"
+                    },
+                    "vector": {
+                      "type": "array",
+                      "items": {
+                        "type": "number"
+                      }
+                    },
+                    "dimensions": {
+                      "type": "integer",
+                      "minimum": 1
+                    },
+                    "space": {
+                      "type": "object",
+                      "required": [
+                        "embedding_set_slug",
+                        "model",
+                        "model_revision",
+                        "model_digest",
+                        "normalization"
+                      ],
+                      "properties": {
+                        "embedding_set_slug": {
+                          "type": "string"
+                        },
+                        "model": {
+                          "type": "string"
+                        },
+                        "model_revision": {
+                          "type": "string"
+                        },
+                        "model_digest": {
+                          "type": "string"
+                        },
+                        "normalization": {
+                          "type": "string",
+                          "enum": [
+                            "l2"
+                          ]
+                        }
+                      }
+                    },
+                    "thresholds": {
+                      "type": "object",
+                      "properties": {
+                        "provisional": {
+                          "type": "number",
+                          "minimum": 0,
+                          "maximum": 1
+                        },
+                        "ambiguity_margin": {
+                          "type": "number",
+                          "minimum": 0,
+                          "maximum": 1
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "responses": {
+            "200": {
+              "description": "Typed provisional/ambiguous/no_match outcome with candidates but no stored vectors."
+            },
+            "400": {
+              "description": "Query vector or exact-space contract invalid."
+            },
+            "403": {
+              "description": "Admin scope required."
+            }
+          }
+        }
+      },
+      "source_of_truth": [
+        "GET /openapi.json",
+        "packages/cli/src/api/openapi.ts"
+      ]
+    },
     {
       "id": "api.v1-memory-write",
       "kind": "api",