restructure diarization prep for langid/vad

.claude/skills/porting-1-intake/SKILL.md

@@ -55,6 +55,12 @@ field semantics.
 
 2. **Architecture pattern.** One of `encoder-transducer`, `encoder-decoder`, `audio-llm`, `encoder-ctc`. The script's `config.architecture_candidates` is a heuristic starting point. If it doesn't fit, propose a new pattern and have the user accept it based on your research of the architecture.
 
+   **Role.** ASR (the product is a transcript) or DIARIZE (the product is
+   who spoke when; see `docs/roles.md`). A DIARIZE port implements
+   `DiarizeOps` (`src/transcribe-diarize.h`) instead of the ASR hooks, sets
+   `"role": "diarize"` in its catalog record, and is accepted on DER
+   (`scripts/diar/`), not WER.
+
 3. **Acceptance dataset.** Default: LibriSpeech test-clean. Capture any
    publisher-reported score in `upstream_benchmarks` when available for
    context, but downstream gates use the measured Oracle reference

.claude/skills/porting-7-wer/SKILL.md

@@ -42,7 +42,7 @@ WER progress:
 
 ### Step 1: Acceptance manifest (execute or ask-point)
 
-Read the acceptance dataset and metric from `upstream_benchmarks[0].{dataset, metric}`. Slugify: lowercase, spaces → hyphens. `"LibriSpeech test-clean"` → `librispeech-test-clean`. Resolve to `$MANIFEST`; every later step uses `$MANIFEST`, never a reconstructed path. Confirm `metric` is `wer` or `cer`; anything else is out of scope. Do not use any publisher-reported score for pass/fail; the measured Oracle reference score is the gate target.
+Read the acceptance dataset and metric from `upstream_benchmarks[0].{dataset, metric}`. Slugify: lowercase, spaces → hyphens. `"LibriSpeech test-clean"` → `librispeech-test-clean`. Resolve to `$MANIFEST`; every later step uses `$MANIFEST`, never a reconstructed path. Confirm `metric` is `wer` or `cer` (`der` for a DIARIZE-role model: score with `scripts/diar/` instead; anything else is out of scope). Do not use any publisher-reported score for pass/fail; the measured Oracle reference score is the gate target.
 
 If the intake's dataset is not covered by `scripts/wer/ingest.py`, extend
 that script before running this step.

.github/actions/fetch-canary/action.yml

@@ -6,7 +6,8 @@ description: >
   secret): the model tests then skip, exactly as before this action existed.
   Always fetches ALL CI canaries (whisper-tiny + moonshine-streaming ~95 MB,
   Canary+SenseVoice text-control canaries ~290 MB, plus the two parakeet 0.6b
-  family-extension canaries — cache-aware + buffered — at Q4_K_M ~0.95 GB)
+  family-extension canaries — cache-aware + buffered — at Q4_K_M ~0.95 GB,
+  plus the Sortformer DIARIZE canary at Q8_0 ~140 MB)
   under one cache key — a per-consumer subset would let one job save the shared
   key with only its subset in it, and every other consumer would re-download
   forever (exact-key hits are never re-saved), which is also why the key carries
@@ -35,7 +36,7 @@ runs:
       uses: actions/cache@v5
       with:
         path: canary
-        key: canary-models-v3
+        key: canary-models-v4
     - name: Fetch canary models (cache miss only)
       if: inputs.hf-token != ''
       shell: bash
@@ -67,6 +68,12 @@ runs:
           uvx --from huggingface_hub hf download \
             handy-computer/parakeet-unified-en-0.6b-gguf \
             parakeet-unified-en-0.6b-Q4_K_M.gguf --local-dir canary
+        # Sortformer DIARIZE canary (Q8_0, ~140 MB) for the binding diarize
+        # tests.
+        [ -f canary/diar_streaming_sortformer_4spk-v2.1-Q8_0.gguf ] || \
+          uvx --from huggingface_hub hf download \
+            handy-computer/diar_streaming_sortformer_4spk-v2.1-gguf \
+            diar_streaming_sortformer_4spk-v2.1-Q8_0.gguf --local-dir canary
         # GITHUB_WORKSPACE (not bash's $PWD) so Windows exports a path
         # Python can open rather than an MSYS one.
         prefix='${{ inputs.model-path-prefix }}'
@@ -77,3 +84,4 @@ runs:
         echo "TRANSCRIBE_SMOKE_ITN_MODEL=$prefix/canary/SenseVoiceSmall-Q4_K_M.gguf" >> "$GITHUB_ENV"
         echo "TRANSCRIBE_SMOKE_PARAKEET_STREAM_MODEL=$prefix/canary/nemotron-speech-streaming-en-0.6b-Q4_K_M.gguf" >> "$GITHUB_ENV"
         echo "TRANSCRIBE_SMOKE_PARAKEET_BUFFERED_MODEL=$prefix/canary/parakeet-unified-en-0.6b-Q4_K_M.gguf" >> "$GITHUB_ENV"
+        echo "TRANSCRIBE_SMOKE_SORTFORMER_MODEL=$prefix/canary/diar_streaming_sortformer_4spk-v2.1-Q8_0.gguf" >> "$GITHUB_ENV"

AGENTS.md

@@ -44,7 +44,7 @@ scripts/ci/clang-format.sh --check    # verify, no changes
 No C++ exception may escape a public entry point.
 
 - A new public entry point must either route through an `api_guard_*`
-  wrapper (`src/transcribe.cpp`) or be nothrow by construction. Device and
+  wrapper (`src/transcribe-api-guard.h`) or be nothrow by construction. Device and
   registry queries are not pure reads; guard them.
 - Entry points with ownership out-params enforce "non-OK => `*out == NULL`,
   nothing leaked" in their forwarders on every error return.

README.md

@@ -33,7 +33,7 @@ C/C++ speech-to-text inference library. Runs diverse STT model families via [GGU
 
 **Speaker diarization models** (no transcription; verified by DER/JER rather than WER):
 
-<!-- catalog:family-index transcribe=false -->
+<!-- catalog:family-index role=diarize -->
 | Family | Variants | Available capabilities | Docs |
 | --- | --- | --- | --- |
 | Streaming Sortformer Diarizer 4spk v2.1 | `diar_streaming_sortformer_4spk-v2.1` | diarize, streaming | [docs/models/diar_streaming_sortformer_4spk-v2.1.md](docs/models/diar_streaming_sortformer_4spk-v2.1.md) |

bindings/python/README.md

@@ -70,6 +70,24 @@ Long transcriptions can be cancelled from another thread with
 `session.cancel()` — the run raises `Aborted` with the partial transcript on
 `exc.partial_result` (same for `OutputTruncated`).
 
+### Diarization
+
+Models whose `model.roles` include `Role.DIARIZE` (Sortformer) answer "who
+spoke when" through a diarize session. `run()` returns `SpeakerSegment`
+rows (`speaker_id` in `1..model.diarize_info.max_speakers`), grouped by
+speaker. Locking, `Busy`, `cancel()` and `close()` work as on `Session`. A
+model without the role raises `UnsupportedRole`, as `model.session()` and
+`model.capabilities` do on a model without `Role.ASR` (Sortformer serves only
+`Role.DIARIZE`).
+
+```python
+with model.diarize_session() as diarizer:
+    turns = diarizer.run(pcm, family=transcribe_cpp.SortformerDiarizeOptions(
+        preset="very_high_latency"))
+    for turn in turns:
+        print(turn.speaker_id, turn.t0_ms, turn.t1_ms)
+```
+
 ## Backends
 
 `Model(backend=...)` applies a backend policy (`"auto"` uses the best
@@ -120,9 +138,10 @@ TRANSCRIBE_LIBRARY=../../build-shared/src/libtranscribe.dylib \
 
 ## Notes
 
-- One run/stream at a time per `Model` in 0.x: sessions share the model's
-  compute backend, so serialize runs across sessions (or load one model per
-  worker). See the `Model` docstring.
+- One compute call at a time per `Model`: the binding serializes calls across
+  all sessions of a model with a model-wide lock (load one model per worker
+  for parallelism). While a stream is active, other runs and stream begins on
+  that model raise `transcribe_cpp.Busy`. See the `Model` docstring.
 - Import package: `transcribe_cpp`
 - Distribution: `transcribe-cpp`
 - License: MIT