omnius 1.0.633 → 1.0.636

package/docs/DISCOVERY.json

@@ -4414,22 +4414,949 @@
         "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": "Managed inference contract: {session_id,file,asset_digest?,channel?,sample_rate_hz?,timeout_ms?}. It accepts only a retained mono PCM16/16 kHz WAV greater than 0 and at most 6 seconds. The persistent worker is limited to one active job plus one queued job; cancellation terminates it before clearing both. 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, downloads, or starts an unready worker.",
+          "responses": {
+            "200": {
+              "description": "Typed managed diarization spans."
+            },
+            "400": {
+              "description": "Invalid retained live window or request."
+            },
+            "403": {
+              "description": "Run scope required."
+            },
+            "503": {
+              "description": "Managed live diarization worker not provisioned or warm."
+            }
+          }
+        }
+      },
+      "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. Cancellation terminates the worker and clears its one active plus one queued request.",
+          "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. 200 requires a persistent worker that has proved it loaded the operator-verified local .nemo snapshot with the validated Orin CUDA Python runtime; otherwise this returns typed 503. 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": "Verified local snapshot and warm managed live worker."
+            },
+            "503": {
+              "description": "Snapshot/runtime/worker is unprovisioned or unready; body describes the exact model 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": "Verify and activate a local live-diarization runtime",
+      "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": "Verify and activate a local live-diarization runtime",
+          "tags": [
+            "Audio"
+          ],
+          "description": "Admin-only. Body requires absolute snapshot_path and an absolute python_path (or OMNIUS_DIAR_LIVE_PYTHON). The manifest must be omnius.audio-diarization-model-snapshot.v1 for nvidia/diar_streaming_sortformer_4spk-v2 with a full immutable 40- or 64-hex revision, relative artifact path, and sha256:<digest>. Setup streams those exact local bytes, validates the supplied Python imports plus Jetson Orin CUDA:0 CC 8.7, and warms the persistent worker. It never downloads NeMo, CUDA, model weights, or dependencies; exact runtime prerequisites are rejected rather than guessed.",
+          "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."
+                    },
+                    "python_path": {
+                      "type": "string",
+                      "description": "Absolute pre-provisioned Python with NeMo and Jetson CUDA imports."
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "responses": {
+            "200": {
+              "description": "Snapshot, runtime imports, and worker all verified/warm."
+            },
+            "400": {
+              "description": "Snapshot, Python runtime, immutable manifest/digest validation, or worker warmup 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": "Managed offline/dream contract: {file,observation_ids,episode_id?,timeout_ms?}. file is a retained local asset and may be longer than the live six-second window. The supplied IDs refer to role-isolated AudioObservation records. The pyannote worker returns only OfflineReconciliationProposal records: a proposed diarization_cluster_id, review requirement, and durable_identity:forbidden. Inference never installs, downloads, or starts an unready worker.",
+          "responses": {
+            "200": {
+              "description": "Typed review-required reconciliation proposals and spans."
+            },
+            "400": {
+              "description": "Invalid retained asset or observation IDs."
+            },
+            "403": {
+              "description": "Run scope required."
+            },
+            "503": {
+              "description": "Managed reconciliation worker not provisioned or warm."
+            }
+          }
+        }
+      },
+      "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. The persistent worker is limited to one active job plus one queued job; cancellation terminates it before clearing both.",
+          "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. 200 requires a persistent worker that proved it loaded the operator-supplied offline local snapshot. Community-1 snapshots must carry a deterministic files checksum map for every regular pipeline/model/config file; readiness checks that complete manifest metadata without rehashing. Reconciliation makes only reviewable cluster proposals, never durable identity claims.",
+          "responses": {
+            "200": {
+              "description": "Verified complete local Community-1 snapshot and warm managed worker."
+            },
+            "503": {
+              "description": "Snapshot/runtime/worker is unprovisioned or unready; body describes the exact model 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": "Verify and activate a local reconciliation runtime",
+      "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": "Verify and activate a local reconciliation runtime",
+          "tags": [
+            "Audio"
+          ],
+          "description": "Admin-only. Body requires absolute snapshot_path and an absolute python_path (or OMNIUS_DIAR_RECONCILE_PYTHON), plus pyannote_terms_accepted=true to attest the operator already accepted Community-1's gated terms. Omnius does not accept or persist a token: the snapshot must already be local. The manifest must pin a full immutable 40- or 64-hex revision, the primary artifact digest, and a complete files object mapping every regular pipeline/model/config file to sha256:<digest>. Setup streams/verifies those bytes, validates local pyannote imports, and warms the offline CPU worker. It never downloads pyannote, weights, or dependencies.",
+          "requestBody": {
+            "required": true,
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "required": [
+                    "snapshot_path",
+                    "pyannote_terms_accepted"
+                  ],
+                  "properties": {
+                    "snapshot_path": {
+                      "type": "string"
+                    },
+                    "manifest_path": {
+                      "type": "string"
+                    },
+                    "python_path": {
+                      "type": "string",
+                      "description": "Absolute pre-provisioned Python with pyannote.audio."
+                    },
+                    "pyannote_terms_accepted": {
+                      "type": "boolean",
+                      "enum": [
+                        true
+                      ]
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "responses": {
+            "200": {
+              "description": "Complete snapshot, runtime imports, and worker all verified/warm."
+            },
+            "400": {
+              "description": "Terms attestation, snapshot tree, Python runtime, immutable manifest validation, or worker warmup 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",
+      "title": "/v1/audio/embed",
+      "summary": "Create a managed role-typed audio embedding",
+      "aliases": [
+        "/v1/audio/embed"
+      ],
+      "keywords": [
+        "rest",
+        "openapi",
+        "POST",
+        "Audio",
+        "v1",
+        "audio",
+        "embed"
+      ],
+      "maturity": "stable",
+      "layer": "interface",
+      "audiences": [
+        "integrator",
+        "service-agent",
+        "coding-agent"
+      ],
+      "interfaces": [
+        {
+          "type": "rest",
+          "target": "POST /v1/audio/embed"
+        },
+        {
+          "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": "Create a managed role-typed audio embedding",
+          "tags": [
+            "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. A runtime that is not ready returns HTTP 503 with its role-specific code: audio_classifier_not_ready, speaker_embedding_not_ready, or audio_semantic_embedding_not_ready. Speaker busy and timeout remain typed direct-tool result codes. The generic /v1/tools/audio_analyze/call route retains HTTP 200 for all tool failures. Semantic local-memory admission pressure is likewise an adapter HTTP 503 with code audio_semantic_memory_pressure.",
+          "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: audio_classifier_not_ready, speaker_embedding_not_ready, or audio_semantic_embedding_not_ready. Semantic memory admission uses audio_semantic_memory_pressure."
+            }
+          }
+        }
+      },
+      "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"
+        "/v1/audio/embed/setup"
       ],
       "keywords": [
         "rest",
         "openapi",
         "POST",
-        "Voice",
+        "Audio",
         "v1",
         "audio",
-        "embed"
+        "embed",
+        "setup"
       ],
       "maturity": "stable",
       "layer": "interface",
@@ -4441,7 +5368,7 @@
       "interfaces": [
         {
           "type": "rest",
-          "target": "POST /v1/audio/embed"
+          "target": "POST /v1/audio/embed/setup"
         },
         {
           "type": "openapi",
@@ -4464,20 +5391,66 @@
         "POST"
       ],
       "tags": [
-        "Voice"
+        "Audio"
       ],
       "operations": {
         "post": {
-          "summary": "Create an audio embedding for uploaded or referenced audio",
+          "summary": "Provision and activate one role-typed audio embedding runtime",
           "tags": [
-            "Voice"
+            "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, then installs only the checksummed CPython 3.10/aarch64 Torchaudio 2.2.0 wheel into ~/.omnius/runtimes/audio/speaker/venv with --no-deps/--no-index. It retains --system-site-packages and links the selected OMNIUS_AUDIO_PYTHON JetPack Torch 2.2/CUDA 12.2 provider without writing to it; setup proves the Torch/Torchaudio ABI and CPU kaldi.fbank before readiness. An operator may replace that wheel only by supplying both OMNIUS_SPEAKER_TORCHAUDIO_WHEEL and OMNIUS_SPEAKER_TORCHAUDIO_WHEEL_SHA256. 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."
             }
           }
         }
@@ -6377,7 +7350,7 @@
       "id": "api.v1-config-model-check",
       "kind": "api",
       "title": "/v1/config/model/check",
-      "summary": "Probe configured model readiness",
+      "summary": "Run a bounded real-generation cognition readiness probe",
       "aliases": [
         "/v1/config/model/check"
       ],
@@ -6428,16 +7401,59 @@
       ],
       "operations": {
         "post": {
-          "summary": "Probe configured model readiness",
+          "summary": "Run a bounded real-generation cognition readiness probe",
           "tags": [
             "Config"
           ],
+          "description": "Sends a short non-streaming generation to the configured or requested model and succeeds only when non-empty visible text is returned. Defaults: 10,000ms and 8 tokens; timeout_ms is bounded to 1,000–30,000ms and max_tokens to 1–32. This is deliberately independent of the general 120-second backend timeout.",
+          "requestBody": {
+            "required": false,
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "model": {
+                      "type": "string"
+                    },
+                    "prompt": {
+                      "type": "string",
+                      "maxLength": 280
+                    },
+                    "max_tokens": {
+                      "type": "integer",
+                      "minimum": 1,
+                      "maximum": 32,
+                      "default": 8
+                    },
+                    "timeout_ms": {
+                      "type": "integer",
+                      "minimum": 1000,
+                      "maximum": 30000,
+                      "default": 10000
+                    },
+                    "timeout_s": {
+                      "type": "number",
+                      "deprecated": true,
+                      "description": "Compatibility alias, bounded to the same 1–30 second range."
+                    }
+                  }
+                }
+              }
+            }
+          },
           "responses": {
             "200": {
-              "description": "Model produced non-empty text"
+              "description": "Model produced non-empty visible text"
+            },
+            "400": {
+              "description": "Invalid bounded probe input"
             },
             "502": {
-              "description": "Model probe failed"
+              "description": "Provider error, invalid response, or empty visible response"
+            },
+            "504": {
+              "description": "Typed model_check_timeout"
             }
           }
         }
@@ -10266,11 +11282,271 @@
             "Memory"
           ],
           "responses": {
-            "200": {
-              "description": "Maintenance job result"
+            "200": {
+              "description": "Maintenance job result"
+            },
+            "400": {
+              "description": "Invalid job request"
+            }
+          }
+        }
+      },
+      "source_of_truth": [
+        "GET /openapi.json",
+        "packages/cli/src/api/openapi.ts"
+      ]
+    },
+    {
+      "id": "api.v1-memory-search",
+      "kind": "api",
+      "title": "/v1/memory/search",
+      "summary": "Search memory stores (PT-04)",
+      "aliases": [
+        "/v1/memory/search"
+      ],
+      "keywords": [
+        "rest",
+        "openapi",
+        "POST",
+        "Memory",
+        "v1",
+        "memory",
+        "search"
+      ],
+      "maturity": "stable",
+      "layer": "interface",
+      "audiences": [
+        "integrator",
+        "service-agent",
+        "coding-agent"
+      ],
+      "interfaces": [
+        {
+          "type": "rest",
+          "target": "POST /v1/memory/search"
+        },
+        {
+          "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"
+      ],
+      "operations": {
+        "post": {
+          "summary": "Search memory stores (PT-04)",
+          "tags": [
+            "Memory"
+          ],
+          "requestBody": {
+            "required": true,
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "required": [
+                    "query"
+                  ],
+                  "properties": {
+                    "query": {
+                      "type": "string"
+                    },
+                    "limit": {
+                      "type": "integer"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "responses": {
+            "200": {
+              "description": "Search results"
+            }
+          }
+        }
+      },
+      "source_of_truth": [
+        "GET /openapi.json",
+        "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": "Invalid job request"
+              "description": "Consent, observation role, or exact vector-space contract invalid."
+            },
+            "403": {
+              "description": "Admin scope required."
             }
           }
         }
@@ -10281,21 +11557,23 @@
       ]
     },
     {
-      "id": "api.v1-memory-search",
+      "id": "api.v1-memory-speaker-identities-match",
       "kind": "api",
-      "title": "/v1/memory/search",
-      "summary": "Search memory stores (PT-04)",
+      "title": "/v1/memory/speaker-identities/match",
+      "summary": "Query durable speaker candidates in one exact vector space",
       "aliases": [
-        "/v1/memory/search"
+        "/v1/memory/speaker-identities/match"
       ],
       "keywords": [
         "rest",
         "openapi",
         "POST",
         "Memory",
+        "Audio",
         "v1",
         "memory",
-        "search"
+        "speaker-identities",
+        "match"
       ],
       "maturity": "stable",
       "layer": "interface",
@@ -10307,7 +11585,7 @@
       "interfaces": [
         {
           "type": "rest",
-          "target": "POST /v1/memory/search"
+          "target": "POST /v1/memory/speaker-identities/match"
         },
         {
           "type": "openapi",
@@ -10330,14 +11608,17 @@
         "POST"
       ],
       "tags": [
-        "Memory"
+        "Memory",
+        "Audio"
       ],
       "operations": {
         "post": {
-          "summary": "Search memory stores (PT-04)",
+          "summary": "Query durable speaker candidates in one exact vector space",
           "tags": [
-            "Memory"
+            "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": {
@@ -10345,14 +11626,69 @@
                 "schema": {
                   "type": "object",
                   "required": [
-                    "query"
+                    "scope_id",
+                    "vector",
+                    "dimensions",
+                    "space"
                   ],
                   "properties": {
-                    "query": {
+                    "scope_id": {
                       "type": "string"
                     },
-                    "limit": {
-                      "type": "integer"
+                    "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
+                        }
+                      }
                     }
                   }
                 }
@@ -10361,7 +11697,13 @@
           },
           "responses": {
             "200": {
-              "description": "Search results"
+              "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."
             }
           }
         }
@@ -15288,7 +16630,7 @@
       "id": "api.v1-vision-embed",
       "kind": "api",
       "title": "/v1/vision/embed",
-      "summary": "Create a vision embedding for uploaded or referenced media",
+      "summary": "Create an offline-only OpenCLIP image embedding",
       "aliases": [
         "/v1/vision/embed"
       ],
@@ -15338,16 +16680,201 @@
       ],
       "operations": {
         "post": {
-          "summary": "Create a vision embedding for uploaded or referenced media",
+          "summary": "Create an offline-only OpenCLIP image embedding",
           "tags": [
             "Vision"
           ],
+          "description": "Uses only the verified OpenCLIP ViT-B-32/laion2b_s34b_b79k runtime. Inference never installs dependencies or downloads model artifacts; it checks the setup artifact digest and denies worker network access. Provides path or bytesBase64.",
+          "requestBody": {
+            "required": true,
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "path": {
+                      "type": "string"
+                    },
+                    "bytesBase64": {
+                      "type": "string",
+                      "description": "Base64-encoded image bytes"
+                    }
+                  }
+                }
+              }
+            }
+          },
           "responses": {
             "200": {
-              "description": "Vision embedding result"
+              "description": "512-dimensional L2-normalized embedding with model digest"
             },
             "400": {
               "description": "Invalid media input"
+            },
+            "502": {
+              "description": "Typed vision_embedding_failed"
+            },
+            "503": {
+              "description": "Typed vision_runtime_not_ready or Jetson memory admission failure"
+            },
+            "504": {
+              "description": "Typed vision_embedding_timeout"
+            }
+          }
+        }
+      },
+      "source_of_truth": [
+        "GET /openapi.json",
+        "packages/cli/src/api/openapi.ts"
+      ]
+    },
+    {
+      "id": "api.v1-vision-embed-readiness",
+      "kind": "api",
+      "title": "/v1/vision/embed/readiness",
+      "summary": "Read OpenCLIP vision embedding readiness",
+      "aliases": [
+        "/v1/vision/embed/readiness"
+      ],
+      "keywords": [
+        "rest",
+        "openapi",
+        "GET",
+        "Vision",
+        "v1",
+        "vision",
+        "embed",
+        "readiness"
+      ],
+      "maturity": "stable",
+      "layer": "interface",
+      "audiences": [
+        "integrator",
+        "service-agent",
+        "coding-agent"
+      ],
+      "interfaces": [
+        {
+          "type": "rest",
+          "target": "GET /v1/vision/embed/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": [
+        "Vision"
+      ],
+      "operations": {
+        "get": {
+          "summary": "Read OpenCLIP vision embedding readiness",
+          "tags": [
+            "Vision"
+          ],
+          "description": "Non-mutating status for the isolated ~/.omnius/runtimes/vision/open-clip runtime. It never imports Python, installs dependencies, downloads weights, or loads a model. Returns 503 until the checksum-manifested CUDA runtime and model artifacts are ready.",
+          "responses": {
+            "200": {
+              "description": "Verified OpenCLIP runtime is ready"
+            },
+            "503": {
+              "description": "Not ready; includes setup_in_progress, lastError, and Jetson memory admission"
+            }
+          }
+        }
+      },
+      "source_of_truth": [
+        "GET /openapi.json",
+        "packages/cli/src/api/openapi.ts"
+      ]
+    },
+    {
+      "id": "api.v1-vision-embed-setup",
+      "kind": "api",
+      "title": "/v1/vision/embed/setup",
+      "summary": "Explicitly set up the isolated OpenCLIP vision runtime",
+      "aliases": [
+        "/v1/vision/embed/setup"
+      ],
+      "keywords": [
+        "rest",
+        "openapi",
+        "POST",
+        "Vision",
+        "v1",
+        "vision",
+        "embed",
+        "setup"
+      ],
+      "maturity": "stable",
+      "layer": "interface",
+      "audiences": [
+        "integrator",
+        "service-agent",
+        "coding-agent"
+      ],
+      "interfaces": [
+        {
+          "type": "rest",
+          "target": "POST /v1/vision/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": [
+        "Vision"
+      ],
+      "operations": {
+        "post": {
+          "summary": "Explicitly set up the isolated OpenCLIP vision runtime",
+          "tags": [
+            "Vision"
+          ],
+          "description": "Admin-only single-flight setup. It creates a --system-site-packages venv, requires pre-existing CUDA Torch, installs only pinned non-Torch packages with --no-deps, and fetches/verifies the OpenCLIP checkpoint. It never resolves Torch or torchvision from generic PyPI. torchvision must be inherited from the JetPack vendor stack or supplied as a checksum-pinned local wheel via OMNIUS_VISION_TORCHVISION_WHEEL and OMNIUS_VISION_TORCHVISION_WHEEL_SHA256. Poll readiness for completion or failure; the setup request never makes an embedding inference request provision dependencies.",
+          "responses": {
+            "200": {
+              "description": "Already ready"
+            },
+            "202": {
+              "description": "Single-flight setup accepted; poll readiness"
+            },
+            "403": {
+              "description": "Admin scope required"
+            },
+            "500": {
+              "description": "Setup could not be started"
             }
           }
         }
@@ -29108,7 +30635,7 @@
       "id": "guide.rest-endpoints-voice-vision",
       "kind": "guide",
       "title": "Voice, Audio, Vision, And Voicechat",
-      "summary": "First poll GET /v1/ocr/readiness?language=eng. On Jetson, a privileged or interactive npm installation/bootstrap provisions tesseract-ocr, python3-venv, an import-verified system OpenCV provider (including NVIDIA libopencv-python), python3-numpy, python3-pil, and python3-reportlab. Daemon startup then creates (or repairs) ~/.omnius/runtimes/vision/ocr-advanc",
+      "summary": "POST /v1/vision/embed uses an isolated, CUDA-enabled OpenCLIP ViT-B-32 / laion2bs34bb79k backend and returns a 512-dimensional, L2-normalized image vector plus the verified artifact digest. It does not make descriptive claims or invoke an LLM.",
       "keywords": [
         "rest",
         "endpoints",