create-windy 0.5.2 → 0.6.0

package/template/apps/server/src/system/system-resource-monitoring.ts

@@ -100,16 +100,27 @@ interface CommandResult {
   timedOut?: boolean;
 }
 
+interface KillableProcess {
+  readonly exitCode: number | null;
+  readonly exited: Promise<number>;
+  kill(signal?: number): void;
+}
+
 export type NvidiaSmiRunner = (args: string[]) => Promise<CommandResult>;
 
 export function createGpuMonitorProbe(
   run: NvidiaSmiRunner = runNvidiaSmi,
 ): GpuMonitorProbe {
   return async () => {
-    const deviceResult = await run([
-      "--query-gpu=index,uuid,name,utilization.gpu,memory.used,memory.total,temperature.gpu",
-      "--format=csv,noheader,nounits",
-    ]);
+    let deviceResult: CommandResult;
+    try {
+      deviceResult = await run([
+        "--query-gpu=index,uuid,name,utilization.gpu,memory.used,memory.total,temperature.gpu",
+        "--format=csv,noheader,nounits",
+      ]);
+    } catch {
+      return unavailableGpuSnapshot();
+    }
     if (deviceResult.missing) {
       return {
         status: "not-detected",
@@ -138,10 +149,15 @@ export function createGpuMonitorProbe(
         message: "nvidia-smi 未返回可用的 NVIDIA GPU。",
       };
     }
-    const processResult = await run([
-      "--query-compute-apps=gpu_uuid,pid,process_name,used_gpu_memory",
-      "--format=csv,noheader,nounits",
-    ]);
+    let processResult: CommandResult;
+    try {
+      processResult = await run([
+        "--query-compute-apps=gpu_uuid,pid,process_name,used_gpu_memory",
+        "--format=csv,noheader,nounits",
+      ]);
+    } catch {
+      processResult = { exitCode: null, stdout: "" };
+    }
     if (processResult.exitCode === 0) {
       attachGpuProcesses(devices, processResult.stdout);
     }
@@ -157,6 +173,15 @@ export function createGpuMonitorProbe(
   };
 }
 
+function unavailableGpuSnapshot(): GpuMonitorSnapshot {
+  return {
+    status: "unavailable",
+    provider: "NVIDIA",
+    devices: [],
+    message: "nvidia-smi 查询失败，无法读取 GPU 指标。",
+  };
+}
+
 function systemCpuSample(): CpuSample {
   const cores = cpus();
   const totals = cores.reduce(
@@ -203,8 +228,7 @@ async function runNvidiaSmi(args: string[]): Promise<CommandResult> {
   ]);
   if (timeout) clearTimeout(timeout);
   if (result.timedOut) {
-    child.kill();
-    await child.exited;
+    await terminateTimedOutProcess(child);
     return { exitCode: null, stdout: "", timedOut: true };
   }
   return {
@@ -213,6 +237,32 @@ async function runNvidiaSmi(args: string[]): Promise<CommandResult> {
   };
 }
 
+export async function terminateTimedOutProcess(
+  child: KillableProcess,
+  delay: (milliseconds: number) => Promise<unknown> = Bun.sleep,
+  graceMilliseconds = 250,
+): Promise<void> {
+  try {
+    child.kill();
+  } catch {
+    // Optional telemetry must still return when the soft termination fails.
+  }
+  await Promise.race([
+    child.exited.then(
+      () => undefined,
+      () => undefined,
+    ),
+    delay(graceMilliseconds).then(() => undefined),
+  ]);
+  if (child.exitCode === null) {
+    try {
+      child.kill(9);
+    } catch {
+      // The caller has already observed a timeout; never rethrow kill errors.
+    }
+  }
+}
+
 function parseGpuDevices(output: string): GpuDeviceSnapshot[] {
   return output
     .split(/\r?\n/)

package/template/apps/server/src/work-order/routes.test.ts

@@ -145,6 +145,7 @@ async function createFixture(options: FixtureOptions = {}) {
     invoke(method: string, path: string, params = {}, body?: unknown) {
       return app.invoke(method, path, {
         guardContext,
+        request: new Request("http://localhost/api/work-orders"),
         params,
         query: {},
         body,

package/template/apps/speech-server/src/southwind_speech_server/adapter.py

@@ -8,10 +8,12 @@ from pathlib import Path
 
 import httpx
 
+from .bounded_json import read_bounded_json
 from .config import SpeechRuntimeConfig
 from .contracts import JsonValue, StartSpeechRunRequest
 from .errors import SafeSpeechError
 from .normalizer import AudioNormalizer, NormalizationError
+from .output_artifact import SpeechOutputArtifactClient
 from .output_validation import canonicalize_output
 
 SUPPORTED_MEDIA_TYPES = frozenset(
@@ -37,13 +39,12 @@ class SpeechAdapter:
     ) -> None:
         self.config = config
         self.normalizer = normalizer or AudioNormalizer()
+        self.output_artifacts = SpeechOutputArtifactClient(config)
 
-    @property
-    def available(self) -> bool:
-        return self.config.adapter_url is not None and self.normalizer.available
-
-    async def execute(self, request: StartSpeechRunRequest) -> JsonValue:
-        if not self.config.adapter_url:
+    async def execute(
+        self, request: StartSpeechRunRequest, output_grant: str | None = None
+    ) -> JsonValue:
+        if request.effective_variant != "normalize" and not self.config.adapter_url:
             raise SafeSpeechError(
                 "CAPABILITY_UNAVAILABLE",
                 "Speech Adapter 未配置",
@@ -67,12 +68,27 @@ class SpeechAdapter:
         source = await self._download(request)
         normalized = Path(f"{source}.wav")
         try:
+            output_limit: int | None = None
+            if request.effective_variant == "normalize":
+                sink = request.output_artifact_sink
+                if not sink or not output_grant:
+                    raise SafeSpeechError(
+                        "CAPABILITY_UNAVAILABLE",
+                        "normalize 需要 Host 分配 Output Artifact Sink",
+                        True,
+                    )
+                output_limit = min(
+                    sink.limits.max_artifact_bytes,
+                    sink.limits.max_total_bytes,
+                    self.config.max_output_artifact_bytes,
+                )
             try:
                 audio = await self.normalizer.normalize(
                     source,
                     normalized,
                     request.limits.max_media_duration_seconds,
                     request.limits.max_duration_seconds,
+                    output_limit,
                 )
             except NormalizationError as error:
                 raise SafeSpeechError(
@@ -80,6 +96,16 @@ class SpeechAdapter:
                     str(error),
                     error.code == "CAPABILITY_UNAVAILABLE",
                 ) from error
+            if request.effective_variant == "normalize":
+                assert request.output_artifact_sink and output_grant
+                artifact = await self.output_artifacts.publish(
+                    request.output_artifact_sink, output_grant, audio.path
+                )
+                return {
+                    "durationMs": audio.duration_ms,
+                    "normalizedFormat": "pcm_s16le/16000/mono",
+                    "artifacts": [artifact],
+                }
             return await self._invoke(request, audio.path, audio.duration_ms)
         finally:
             await remove(source)
@@ -141,6 +167,16 @@ class SpeechAdapter:
             )
         return path
 
+    async def accept_output_grant(
+        self, request: StartSpeechRunRequest, grant: str | None
+    ) -> None:
+        await self.output_artifacts.accept_grant(request, grant)
+
+    async def abort_open_output(
+        self, request: StartSpeechRunRequest, grant: str | None
+    ) -> None:
+        await self.output_artifacts.abort_open(request, grant)
+
     async def _invoke(
         self,
         request: StartSpeechRunRequest,
@@ -165,8 +201,9 @@ class SpeechAdapter:
                 )
             ) as client:
                 with path.open("rb") as source:
-                    response = await client.post(
-                        f"{adapter_url.rstrip('/')}/v1/speech/transcribe",
+                    async with client.stream(
+                        "POST",
+                        f"{adapter_url.rstrip('/')}/v1/speech/{request.effective_variant}",
                         headers=headers,
                         files={"file": ("source.wav", source, "audio/wav")},
                         data={
@@ -186,19 +223,19 @@ class SpeechAdapter:
                             ),
                             "limits": request.limits.model_dump_json(by_alias=True),
                         },
-                    )
-            response.raise_for_status()
-            if len(response.content) > request.limits.max_output_bytes:
-                raise SafeSpeechError(
-                    "BUDGET_EXCEEDED",
-                    "Speech 输出超过上限",
-                    False,
-                )
-            value: JsonValue = response.json()
+                    ) as response:
+                        value = await read_bounded_json(
+                            response,
+                            min(
+                                request.limits.max_output_bytes,
+                                self.config.max_inline_output_bytes,
+                            ),
+                        )
             return canonicalize_output(
                 value,
                 duration_ms,
                 request.limits.max_units,
+                request.effective_variant,
             )
         except SafeSpeechError:
             raise
@@ -235,6 +272,10 @@ def enforce_runtime_quotas(
 ) -> None:
     if request.source.byte_size > request.limits.max_input_bytes:
         raise SafeSpeechError("BUDGET_EXCEEDED", "Speech Artifact 超过输入上限", False)
+    if request.source.byte_size > config.max_input_artifact_bytes:
+        raise SafeSpeechError(
+            "BUDGET_EXCEEDED", "Speech Artifact 超过 Runtime 上限", False
+        )
     if request.limits.max_units > config.max_units:
         raise SafeSpeechError("BUDGET_EXCEEDED", "转写分段上限超过 Runtime 配置", False)
     if request.limits.max_media_duration_seconds > config.max_media_duration_seconds:

package/template/apps/speech-server/src/southwind_speech_server/app.py

@@ -13,7 +13,8 @@ from fastapi.responses import JSONResponse, Response, StreamingResponse
 from .adapter import SpeechAdapter
 from .config import SpeechRuntimeConfig
 from .contracts import ErrorResponse, StartRunResponse, StartSpeechRunRequest
-from .errors import SafeSpeechError
+from .errors import SafeSpeechError, safe_speech_status
+from .readiness import SpeechReadinessProbe
 from .service import SpeechRunService
 from .store import RunConflictError, SpeechRunStore
 
@@ -22,6 +23,7 @@ def create_app(config: SpeechRuntimeConfig) -> FastAPI:
     app = FastAPI(title="Southwind Speech Runtime", docs_url=None, redoc_url=None)
     store = SpeechRunStore(config.store_path)
     service = SpeechRunService(SpeechAdapter(config), store)
+    readiness = SpeechReadinessProbe(config)
 
     def authorize(authorization: str | None = Header(default=None)) -> None:
         provided = (authorization or "").removeprefix("Bearer ")
@@ -30,32 +32,33 @@ def create_app(config: SpeechRuntimeConfig) -> FastAPI:
 
     @app.get("/health/ready")
     async def ready(_: None = Depends(authorize)) -> JSONResponse:
-        if not service.adapter.available:
-            return JSONResponse(
-                {"status": "unavailable", "capabilities": []},
-                status_code=503,
-            )
+        inspection = await readiness.inspect()
         return JSONResponse(
-            {
-                "status": "ready",
-                "capabilities": list(config.capabilities),
-                "limits": {
-                    "maxUnits": config.max_units,
-                    "maxMediaDurationSeconds": config.max_media_duration_seconds,
-                },
-            }
+            inspection.snapshot, status_code=200 if inspection.ready else 503
         )
 
     @app.post("/api/speech/runs", status_code=202)
     async def start(
         request: StartSpeechRunRequest,
         idempotency_key: str = Header(alias="idempotency-key"),
+        output_artifact_grant: str | None = Header(
+            default=None, alias="x-ai-output-artifact-grant"
+        ),
         _: None = Depends(authorize),
     ) -> StartRunResponse:
         if not idempotency_key.strip() or len(idempotency_key) > 160:
             raise HTTPException(status_code=400, detail="INVALID_INPUT")
+        inspection = await readiness.inspect()
+        if not readiness.supports(inspection, request):
+            raise SafeSpeechError(
+                "CAPABILITY_UNAVAILABLE",
+                "Speech Runtime 当前没有匹配的原子 offer",
+                True,
+            )
         try:
-            record = await service.start(request, idempotency_key)
+            record = await service.start(
+                request, idempotency_key, output_artifact_grant
+            )
         except RunConflictError:
             raise HTTPException(status_code=409, detail="RUN_CONFLICT") from None
         return StartRunResponse(
@@ -155,8 +158,12 @@ def create_app(config: SpeechRuntimeConfig) -> FastAPI:
     async def safe_speech_error(
         _request: object, error: SafeSpeechError
     ) -> JSONResponse:
-        status = 403 if error.code == "FORBIDDEN" else 400
-        return safe_error(error.code, error.safe_message, status, error.retryable)
+        return safe_error(
+            error.code,
+            error.safe_message,
+            safe_speech_status(error),
+            error.retryable,
+        )
 
     return app
 

package/template/apps/speech-server/src/southwind_speech_server/bounded_json.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+import json
+from typing import cast
+
+import httpx
+
+from .contracts import JsonValue
+
+
+class BoundedJsonError(Exception):
+    pass
+
+
+async def read_bounded_json(
+    response: httpx.Response,
+    max_bytes: int,
+) -> JsonValue:
+    media_type = response.headers.get("content-type", "").split(";", 1)[0]
+    if (
+        response.status_code < 200
+        or response.status_code >= 300
+        or media_type.strip().lower() != "application/json"
+        or response.headers.get("content-encoding")
+    ):
+        raise BoundedJsonError
+    declared = response.headers.get("content-length")
+    if declared is not None and (not declared.isdigit() or int(declared) > max_bytes):
+        raise BoundedJsonError
+    body = bytearray()
+    async for chunk in response.aiter_bytes():
+        if len(chunk) > max_bytes - len(body):
+            raise BoundedJsonError
+        body.extend(chunk)
+    if declared is not None and int(declared) != len(body):
+        raise BoundedJsonError
+    try:
+        return cast(
+            JsonValue,
+            json.loads(
+                body.decode("utf-8"),
+                object_pairs_hook=unique_object,
+                parse_constant=reject_constant,
+            ),
+        )
+    except (UnicodeDecodeError, json.JSONDecodeError, ValueError, RecursionError):
+        raise BoundedJsonError from None
+
+
+def unique_object(pairs: list[tuple[str, JsonValue]]) -> dict[str, JsonValue]:
+    result: dict[str, JsonValue] = {}
+    for key, value in pairs:
+        if key in result:
+            raise ValueError("duplicate key")
+        result[key] = value
+    return result
+
+
+def reject_constant(_value: str) -> JsonValue:
+    raise ValueError("non-finite number")

package/template/apps/speech-server/src/southwind_speech_server/config.py

@@ -1,24 +1,52 @@
 from __future__ import annotations
 
 import ipaddress
+import re
 from dataclasses import dataclass
 from urllib.parse import urlparse
 
+_STABLE_KEY = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._:/-]{0,127}$")
+_DEPLOYMENT_IDENTITY = re.compile(
+    r"^windy-deployment-v1_[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-"
+    r"[89ab][a-f0-9]{3}-[a-f0-9]{12}$"
+)
+_DIGEST = re.compile(r"^sha256:[a-f0-9]{64}$")
+
 
 @dataclass(frozen=True)
 class SpeechRuntimeConfig:
     internal_token: str
     store_path: str
     artifact_url: str
+    output_artifact_url: str
     adapter_url: str | None
     adapter_token: str | None
     deployment_key: str | None
+    deployment_identity: str | None
+    release_digest: str | None
+    offers_digest: str | None
     capabilities: tuple[str, ...]
     max_units: int = 100_000
     max_media_duration_seconds: int = 24 * 60 * 60
+    max_input_artifact_bytes: int = 2 * 1024 * 1024 * 1024
+    max_inline_output_bytes: int = 64 * 1024 * 1024
+    max_output_artifact_bytes: int = 512 * 1024 * 1024
+    max_concurrent_runs: int = 1
+    max_queue_depth: int = 0
+    readiness_timeout_seconds: float = 5
+    readiness_ttl_seconds: int = 60
     connect_timeout_seconds: float = 5
     request_timeout_seconds: float = 3600
 
+    @property
+    def readiness_configured(self) -> bool:
+        return bool(
+            self.deployment_key
+            and self.deployment_identity
+            and self.release_digest
+            and self.offers_digest
+        )
+
     @classmethod
     def from_environment(cls, environment: dict[str, str]) -> SpeechRuntimeConfig:
         artifact_url = environment.get(
@@ -26,6 +54,11 @@ class SpeechRuntimeConfig:
             "http://server:9747/api/internal/ai/artifacts",
         ).strip()
         validate_intranet_url(artifact_url)
+        output_artifact_url = environment.get(
+            "SPEECH_OUTPUT_ARTIFACT_URL",
+            "http://server:9747/api/internal/ai/output-artifacts",
+        ).strip()
+        validate_intranet_url(output_artifact_url)
         adapter_url = environment.get("SPEECH_ADAPTER_URL", "").strip() or None
         if adapter_url:
             validate_intranet_url(adapter_url)
@@ -36,7 +69,7 @@ class SpeechRuntimeConfig:
                     for item in environment.get(
                         "SPEECH_ADAPTER_CAPABILITIES",
                         (
-                            "speech.transcribe.batch,speech.normalize,"
+                            "speech.transcribe.batch,speech.translate,"
                             "speech.vad,speech.timestamps"
                         ),
                     ).split(",")
@@ -44,15 +77,35 @@ class SpeechRuntimeConfig:
                 }
             )
         )
+        if any(not _STABLE_KEY.fullmatch(item) for item in capabilities):
+            raise ValueError("SPEECH_ADAPTER_CAPABILITIES 无效")
+        deployment_key = optional(environment, "SPEECH_DEPLOYMENT_KEY")
+        if deployment_key and not _STABLE_KEY.fullmatch(deployment_key):
+            raise ValueError("SPEECH_DEPLOYMENT_KEY 无效")
+        deployment_identity = optional(environment, "SPEECH_DEPLOYMENT_IDENTITY")
+        if deployment_identity and not _DEPLOYMENT_IDENTITY.fullmatch(
+            deployment_identity
+        ):
+            raise ValueError("SPEECH_DEPLOYMENT_IDENTITY 无效")
+        release_digest = optional(environment, "SPEECH_RELEASE_DIGEST")
+        if release_digest and not _DIGEST.fullmatch(release_digest):
+            raise ValueError("SPEECH_RELEASE_DIGEST 无效")
+        offers_digest = optional(environment, "SPEECH_OFFERS_DIGEST")
+        if offers_digest and not _DIGEST.fullmatch(offers_digest):
+            raise ValueError("SPEECH_OFFERS_DIGEST 无效")
         return cls(
             internal_token=required(environment, "SPEECH_SERVER_INTERNAL_TOKEN"),
             store_path=environment.get(
                 "SPEECH_RUN_STORE_PATH", "/app/data/speech/runs.sqlite3"
             ).strip(),
             artifact_url=artifact_url,
+            output_artifact_url=output_artifact_url,
             adapter_url=adapter_url,
             adapter_token=environment.get("SPEECH_ADAPTER_TOKEN", "").strip() or None,
-            deployment_key=environment.get("SPEECH_DEPLOYMENT_KEY", "").strip() or None,
+            deployment_key=deployment_key,
+            deployment_identity=deployment_identity,
+            release_digest=release_digest,
+            offers_digest=offers_digest,
             capabilities=capabilities,
             max_units=positive_int(environment, "SPEECH_MAX_UNITS", 100_000),
             max_media_duration_seconds=positive_int(
@@ -60,6 +113,25 @@ class SpeechRuntimeConfig:
                 "SPEECH_MAX_MEDIA_DURATION_SECONDS",
                 24 * 60 * 60,
             ),
+            max_input_artifact_bytes=positive_int(
+                environment, "SPEECH_MAX_INPUT_ARTIFACT_BYTES", 2 * 1024**3
+            ),
+            max_inline_output_bytes=positive_int(
+                environment, "SPEECH_MAX_INLINE_OUTPUT_BYTES", 64 * 1024**2
+            ),
+            max_output_artifact_bytes=positive_int(
+                environment, "SPEECH_MAX_OUTPUT_ARTIFACT_BYTES", 512 * 1024**2
+            ),
+            max_concurrent_runs=positive_int(
+                environment, "SPEECH_MAX_CONCURRENT_RUNS", 1
+            ),
+            max_queue_depth=non_negative_int(environment, "SPEECH_MAX_QUEUE_DEPTH", 0),
+            readiness_timeout_seconds=bounded_positive_float(
+                environment, "SPEECH_READINESS_TIMEOUT_SECONDS", 5, 30
+            ),
+            readiness_ttl_seconds=bounded_positive_int(
+                environment, "SPEECH_READINESS_TTL_SECONDS", 60, 300
+            ),
         )
 
 
@@ -70,6 +142,10 @@ def required(environment: dict[str, str], key: str) -> str:
     return value
 
 
+def optional(environment: dict[str, str], key: str) -> str | None:
+    return environment.get(key, "").strip() or None
+
+
 def positive_int(environment: dict[str, str], key: str, default: int) -> int:
     raw = environment.get(key, str(default)).strip()
     try:
@@ -81,6 +157,50 @@ def positive_int(environment: dict[str, str], key: str, default: int) -> int:
     return value
 
 
+def non_negative_int(environment: dict[str, str], key: str, default: int) -> int:
+    value = integer(environment, key, default)
+    if value < 0:
+        raise ValueError(f"{key} 必须是非负整数")
+    return value
+
+
+def integer(environment: dict[str, str], key: str, default: int) -> int:
+    raw = environment.get(key, str(default)).strip()
+    try:
+        return int(raw)
+    except ValueError:
+        raise ValueError(f"{key} 必须是整数") from None
+
+
+def positive_float(environment: dict[str, str], key: str, default: float) -> float:
+    raw = environment.get(key, str(default)).strip()
+    try:
+        value = float(raw)
+    except ValueError:
+        raise ValueError(f"{key} 必须是正数") from None
+    if value <= 0:
+        raise ValueError(f"{key} 必须是正数")
+    return value
+
+
+def bounded_positive_int(
+    environment: dict[str, str], key: str, default: int, maximum: int
+) -> int:
+    value = positive_int(environment, key, default)
+    if value > maximum:
+        raise ValueError(f"{key} 不能超过 {maximum}")
+    return value
+
+
+def bounded_positive_float(
+    environment: dict[str, str], key: str, default: float, maximum: float
+) -> float:
+    value = positive_float(environment, key, default)
+    if value > maximum:
+        raise ValueError(f"{key} 不能超过 {maximum:g}")
+    return value
+
+
 def validate_intranet_url(raw: str) -> None:
     parsed = urlparse(raw)
     if parsed.scheme not in {"http", "https"} or not parsed.hostname:

package/template/apps/speech-server/src/southwind_speech_server/contracts.py

@@ -38,6 +38,37 @@ class RuntimeLimits(CanonicalModel):
     max_media_duration_seconds: int = Field(ge=1, le=24 * 60 * 60)
 
 
+class OutputArtifactLimits(CanonicalModel):
+    max_artifact_bytes: int = Field(ge=1, le=512 * 1024 * 1024)
+    max_artifacts: Literal[1]
+    max_total_bytes: int = Field(ge=1, le=512 * 1024 * 1024)
+
+
+class OutputArtifactSink(CanonicalModel):
+    contract_version: Literal[1]
+    scope: str = Field(pattern=r"^outscope_[a-f0-9]{32}$")
+    output_kind: Literal["normalized-audio"]
+    deployment_identity: str = Field(
+        pattern=(
+            r"^windy-deployment-v1_[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-"
+            r"[89ab][a-f0-9]{3}-[a-f0-9]{12}$"
+        )
+    )
+    release_digest: str = Field(pattern=r"^sha256:[a-f0-9]{64}$")
+    offers_digest: str = Field(pattern=r"^sha256:[a-f0-9]{64}$")
+    policy_digest: str = Field(pattern=r"^[a-f0-9]{64}$")
+    grant_generation: int = Field(ge=1)
+    allowed_media_types: list[Literal["audio/wav"]] = Field(min_length=1, max_length=1)
+    expires_at: str = Field(min_length=24, max_length=32)
+    limits: OutputArtifactLimits
+
+    @model_validator(mode="after")
+    def validate_limits(self) -> Self:
+        if self.limits.max_artifact_bytes > self.limits.max_total_bytes:
+            raise ValueError("normalize Sink 单件上限超过总量上限")
+        return self
+
+
 class ProviderEgress(CanonicalModel):
     mode: Literal["forbidden", "configured-endpoint"]
     deployment_key: str | None = None
@@ -80,6 +111,13 @@ class ProviderDataPolicy(CanonicalModel):
 
 class StartSpeechRunRequest(CanonicalModel):
     kind: Literal["speech"]
+    run_id: str | None = Field(
+        default=None,
+        pattern=r"^speech_[a-f0-9]{64}$",
+    )
+    # Missing version remains the V1 transcribe wire contract.
+    contract_version: Literal[2] | None = None
+    variant: Literal["normalize", "transcribe", "translate"] | None = None
     operation_key: str = Field(min_length=1, max_length=160)
     options: JsonValue
     source: ArtifactInput
@@ -88,6 +126,26 @@ class StartSpeechRunRequest(CanonicalModel):
     limits: RuntimeLimits
     provider_egress: ProviderEgress
     provider_data_policy: ProviderDataPolicy | None = None
+    output_artifact_sink: OutputArtifactSink | None = None
+
+    @model_validator(mode="after")
+    def validate_contract(self) -> Self:
+        if self.contract_version is None and self.variant is None:
+            if self.run_id is not None or self.output_artifact_sink is not None:
+                raise ValueError("Speech V1 不接受 Output Artifact")
+            return self
+        if self.contract_version != 2 or self.variant is None:
+            raise ValueError("Speech V2 contractVersion 与 variant 必须同时指定")
+        if self.variant == "normalize":
+            if self.run_id is None or self.output_artifact_sink is None:
+                raise ValueError("normalize 缺少 Host Run 或 Output Artifact Sink")
+        elif self.run_id is not None or self.output_artifact_sink is not None:
+            raise ValueError("非 normalize 不能指定 Output Artifact")
+        return self
+
+    @property
+    def effective_variant(self) -> Literal["normalize", "transcribe", "translate"]:
+        return self.variant or "transcribe"
 
 
 class StartRunResponse(CanonicalModel):