refactor: tighten the public API surface to tier-1 facades

README.md

@@ -94,6 +94,27 @@ ser --train --profile accurate-research
 Profile selection during predict is strict: use an artifact trained for the same profile/backend.
 When running from a source checkout without activating an environment, prefix commands with `uv run`.
 
+## Python API
+`ser.api` is the sole supported Python entry point. Everything else — including
+modules under public-looking paths that are not exported from `ser`, `ser.api`,
+`ser.domain`, `ser.config`, or `ser.utils` — is implementation detail and may
+change without notice.
+
+Minimal inference example:
+
+```python
+import ser.api
+
+execution = ser.api.infer("sample.wav", profile="fast")
+for segment in execution.emotions:
+    print(segment.emotion, segment.start_seconds, segment.end_seconds)
+```
+
+Stability promise: symbols exported from `ser.api` (see `ser.api.__all__`),
+the domain types re-exported from `ser`/`ser.domain`, the trimmed `ser.config`
+surface, and the helpers in `ser.utils` follow semantic versioning from `1.0.0`
+onward. Anything not exported there carries no compatibility guarantee.
+
 ## Boundary Checks (Contributors)
 If your change touches `ser/api.py`, `ser/_internal/api/*`, or `ser/__main__.py`, run:
 

boundary_policy.toml

@@ -44,22 +44,6 @@ reason = "Public representation adapter requiring internal runtime/config suppor
 path = "ser/runtime/accurate_inference.py"
 reason = "Accurate profile wrapper over internal runtime owners."
 
-[[public_internal_import]]
-path = "ser/runtime/accurate_process_timeout.py"
-reason = "Accurate timeout wrapper over internal runtime owners."
-
-[[public_internal_import]]
-path = "ser/runtime/accurate_retry_operation.py"
-reason = "Accurate retry wrapper over internal runtime owners."
-
-[[public_internal_import]]
-path = "ser/runtime/accurate_worker_lifecycle.py"
-reason = "Accurate worker lifecycle wrapper over internal runtime owners."
-
-[[public_internal_import]]
-path = "ser/runtime/accurate_worker_operation.py"
-reason = "Accurate worker operation wrapper over internal runtime owners."
-
 [[public_internal_import]]
 path = "ser/runtime/fast_inference.py"
 reason = "Fast profile wrapper over internal runtime owner modules."
@@ -68,18 +52,6 @@ reason = "Fast profile wrapper over internal runtime owner modules."
 path = "ser/runtime/medium_inference.py"
 reason = "Medium profile wrapper over internal runtime owners."
 
-[[public_internal_import]]
-path = "ser/runtime/medium_process_timeout.py"
-reason = "Medium timeout wrapper over internal runtime owners."
-
-[[public_internal_import]]
-path = "ser/runtime/medium_worker_lifecycle.py"
-reason = "Medium worker lifecycle wrapper over internal runtime owners."
-
-[[public_internal_import]]
-path = "ser/runtime/medium_worker_operation.py"
-reason = "Medium worker operation wrapper over internal runtime owners."
-
 [[public_internal_import]]
 path = "ser/runtime/pipeline.py"
 reason = "Public runtime orchestration surface over internal workflow owners."

docs/architecture-diagram.md

@@ -32,35 +32,35 @@ _internal/api/runtime.py
 runtime/pipeline.py
         |
         +--> runtime/registry.py
-        +--> runtime/backend_hooks.py
+        +--> _internal/runtime/backend_hooks.py
         +--> _internal/runtime/environment_plan.py
         +--> _internal/runtime/process_env.py
         |
         +--> fast_inference.py
         +--> medium_inference.py
-        |      +--> medium_execution_context.py
-        |      +--> medium_execution_flow.py
+        |      +--> _internal/runtime/medium_execution_context.py
+        |      +--> _internal/runtime/medium_execution_flow.py
         |      +--> medium_execution.py
-        |      +--> medium_worker_operation.py
-        |      +--> medium_worker_lifecycle.py
-        |      +--> medium_runtime_support.py
+        |      +--> _internal/runtime/medium_worker_operation.py
+        |      +--> _internal/runtime/medium_worker_lifecycle.py
+        |      +--> _internal/runtime/medium_runtime_support.py
         |
         +--> accurate_inference.py
-               +--> accurate_execution_flow.py
+               +--> _internal/runtime/accurate_execution_flow.py
                +--> accurate_execution.py
-               +--> accurate_operation_setup.py
-               +--> accurate_worker_operation.py
-               +--> accurate_worker_lifecycle.py
-               +--> accurate_runtime_support.py
+               +--> _internal/runtime/accurate_operation_setup.py
+               +--> _internal/runtime/accurate_worker_operation.py
+               +--> _internal/runtime/accurate_worker_lifecycle.py
+               +--> _internal/runtime/accurate_runtime_support.py
 ```
 
 Shared runtime primitives:
 
 ```text
 _internal/runtime/worker_lifecycle.py
 _internal/runtime/retry_scaffold.py
-runtime/policy.py
-runtime/retry_primitives.py
+_internal/runtime/policy.py
+_internal/runtime/retry_primitives.py
 ```
 
 ## Level 3: transcription execution

docs/codebase-architecture.md

@@ -110,10 +110,10 @@ It coordinates:
 
 Supporting runtime ownership is split between:
 
-- backend hook construction: [`ser/runtime/backend_hooks.py`](../ser/runtime/backend_hooks.py)
+- backend hook construction: [`ser/_internal/runtime/backend_hooks.py`](../ser/_internal/runtime/backend_hooks.py)
 - capability resolution: [`ser/runtime/registry.py`](../ser/runtime/registry.py)
-- retry policy: [`ser/runtime/policy.py`](../ser/runtime/policy.py)
-- shared retry/error primitives: [`ser/runtime/retry_primitives.py`](../ser/runtime/retry_primitives.py)
+- retry policy: [`ser/_internal/runtime/policy.py`](../ser/_internal/runtime/policy.py)
+- shared retry/error primitives: [`ser/_internal/runtime/retry_primitives.py`](../ser/_internal/runtime/retry_primitives.py)
 - process env planning: [`ser/_internal/runtime/environment_plan.py`](../ser/_internal/runtime/environment_plan.py)
 - scoped env application: [`ser/_internal/runtime/process_env.py`](../ser/_internal/runtime/process_env.py)
 
@@ -130,10 +130,10 @@ longer monolithic runtime modules. They now delegate heavily into owner modules:
 
 - public-boundary orchestration: [`ser/_internal/runtime/accurate_public_boundary.py`](../ser/_internal/runtime/accurate_public_boundary.py), [`ser/_internal/runtime/medium_public_boundary.py`](../ser/_internal/runtime/medium_public_boundary.py)
 - execution: [`ser/runtime/medium_execution.py`](../ser/runtime/medium_execution.py), [`ser/runtime/accurate_execution.py`](../ser/runtime/accurate_execution.py)
-- setup/context: [`ser/runtime/medium_execution_context.py`](../ser/runtime/medium_execution_context.py), [`ser/runtime/accurate_operation_setup.py`](../ser/runtime/accurate_operation_setup.py)
-- retry/execution flow: [`ser/runtime/medium_execution_flow.py`](../ser/runtime/medium_execution_flow.py), [`ser/runtime/accurate_execution_flow.py`](../ser/runtime/accurate_execution_flow.py)
-- worker lifecycle: [`ser/runtime/medium_worker_lifecycle.py`](../ser/runtime/medium_worker_lifecycle.py), [`ser/runtime/accurate_worker_lifecycle.py`](../ser/runtime/accurate_worker_lifecycle.py)
-- runtime support: [`ser/runtime/medium_runtime_support.py`](../ser/runtime/medium_runtime_support.py), [`ser/runtime/accurate_runtime_support.py`](../ser/runtime/accurate_runtime_support.py)
+- setup/context: [`ser/_internal/runtime/medium_execution_context.py`](../ser/_internal/runtime/medium_execution_context.py), [`ser/_internal/runtime/accurate_operation_setup.py`](../ser/_internal/runtime/accurate_operation_setup.py)
+- retry/execution flow: [`ser/_internal/runtime/medium_execution_flow.py`](../ser/_internal/runtime/medium_execution_flow.py), [`ser/_internal/runtime/accurate_execution_flow.py`](../ser/_internal/runtime/accurate_execution_flow.py)
+- worker lifecycle: [`ser/_internal/runtime/medium_worker_lifecycle.py`](../ser/_internal/runtime/medium_worker_lifecycle.py), [`ser/_internal/runtime/accurate_worker_lifecycle.py`](../ser/_internal/runtime/accurate_worker_lifecycle.py)
+- runtime support: [`ser/_internal/runtime/medium_runtime_support.py`](../ser/_internal/runtime/medium_runtime_support.py), [`ser/_internal/runtime/accurate_runtime_support.py`](../ser/_internal/runtime/accurate_runtime_support.py)
 
 Underneath those, shared internal worker primitives provide the real reusable
 mechanics:

docs/refactor-hotspot-checks.md

@@ -27,22 +27,22 @@ only as a maintenance heuristic and architecture-reference aid.
 - `ser/runtime/quality_gate_evaluation.py`
 - `ser/runtime/quality_gate_reporting.py`
 - `ser/runtime/quality_gate_cli.py`
-- `ser/runtime/medium_execution_context.py`
-- `ser/runtime/medium_execution_flow.py`
-- `ser/runtime/medium_process_operation.py`
-- `ser/runtime/medium_retry_operation.py`
-- `ser/runtime/retry_primitives.py`
-- `ser/runtime/medium_runtime_support.py`
-- `ser/runtime/medium_worker_lifecycle.py`
-- `ser/runtime/medium_worker_operation.py`
+- `ser/_internal/runtime/medium_execution_context.py`
+- `ser/_internal/runtime/medium_execution_flow.py`
+- `ser/_internal/runtime/medium_process_operation.py`
+- `ser/_internal/runtime/medium_retry_operation.py`
+- `ser/_internal/runtime/retry_primitives.py`
+- `ser/_internal/runtime/medium_runtime_support.py`
+- `ser/_internal/runtime/medium_worker_lifecycle.py`
+- `ser/_internal/runtime/medium_worker_operation.py`
 - `ser/runtime/medium_inference.py`
 - `ser/runtime/medium_execution.py`
 - `ser/runtime/accurate_execution.py`
-- `ser/runtime/accurate_execution_flow.py`
-- `ser/runtime/accurate_operation_setup.py`
-- `ser/runtime/accurate_runtime_support.py`
-- `ser/runtime/accurate_worker_lifecycle.py`
-- `ser/runtime/accurate_worker_operation.py`
+- `ser/_internal/runtime/accurate_execution_flow.py`
+- `ser/_internal/runtime/accurate_operation_setup.py`
+- `ser/_internal/runtime/accurate_runtime_support.py`
+- `ser/_internal/runtime/accurate_worker_lifecycle.py`
+- `ser/_internal/runtime/accurate_worker_operation.py`
 - `ser/runtime/accurate_inference.py`
 - `ser/transcript/transcript_extractor.py`
 

docs/subsystem-dependency-map.md

@@ -43,7 +43,7 @@ Shared primitives, schemas, utils, external libraries
 ### Primary nodes
 
 - `runtime/pipeline.py`
-- `runtime/backend_hooks.py`
+- `_internal/runtime/backend_hooks.py`
 - `runtime/registry.py`
 - `runtime/*_inference.py`
 - `_internal/runtime/accurate_public_boundary.py`
@@ -210,7 +210,7 @@ Obsolete references:
 ## Cross-cutting shared primitives
 
 - Config schema and bootstrap: `_internal/config/*`
-- Runtime worker lifecycle and retries: `_internal/runtime/*`, `runtime/policy.py`, `runtime/retry_primitives.py`
+- Runtime worker lifecycle and retries: `_internal/runtime/*`, `_internal/runtime/policy.py`, `_internal/runtime/retry_primitives.py`
 - Domain contracts: `domain.py`, `runtime/contracts.py`, `runtime/schema.py`
 - Logging and timing: `utils/logger.py`, `runtime/phase_timing.py`
 

ser/_internal/api/diagnostics.py

@@ -85,7 +85,7 @@ def run_startup_preflight(
     include_transcription_checks: bool,
 ) -> DiagnosticReport:
     """Runs one startup preflight diagnostics check suite."""
-    from ser.diagnostics.service import run_startup_preflight as _run_startup_preflight
+    from ser.diagnostics.service import _run_startup_preflight
 
     return _run_startup_preflight(
         settings=settings,

ser/_internal/api/runtime.py

@@ -242,7 +242,7 @@ def load_profile(
     settings: AppConfig,
 ) -> None:
     """Validates profile availability and dependency capability for execution."""
-    from ser.runtime.backend_hooks import build_backend_hooks
+    from ser._internal.runtime.backend_hooks import build_backend_hooks
     from ser.runtime.registry import (
         ensure_profile_supported,
         resolve_runtime_capability,

ser/runtime/accurate_execution_flow.py → ser/_internal/runtime/accurate_execution_flow.py

@@ -7,12 +7,12 @@
 from functools import partial
 from typing import TypeVar
 
-from ser.config import AppConfig
-from ser.runtime.accurate_worker_operation import (
+from ser._internal.runtime.accurate_worker_operation import (
     AccurateRetryOperationState,
     PreparedAccurateOperation,
 )
-from ser.runtime.accurate_worker_operation import _PayloadLike as _AccuratePayloadLike
+from ser._internal.runtime.accurate_worker_operation import _PayloadLike as _AccuratePayloadLike
+from ser.config import AppConfig
 
 _PayloadT = TypeVar("_PayloadT", bound=_AccuratePayloadLike)
 _LoadedModelT = TypeVar("_LoadedModelT")

ser/runtime/accurate_operation_setup.py → ser/_internal/runtime/accurate_operation_setup.py

@@ -7,9 +7,9 @@
 
 from numpy.typing import NDArray
 
+from ser._internal.runtime import accurate_worker_operation as accurate_worker_operation_helpers
+from ser._internal.runtime.accurate_worker_operation import PreparedAccurateOperation
 from ser.config import AppConfig, ProfileRuntimeConfig
-from ser.runtime import accurate_worker_operation as accurate_worker_operation_helpers
-from ser.runtime.accurate_worker_operation import PreparedAccurateOperation
 
 _LoadedModelT = TypeVar("_LoadedModelT")
 _BackendT = TypeVar("_BackendT")

ser/_internal/runtime/accurate_public_boundary.py

@@ -14,9 +14,65 @@
 import numpy as np
 from numpy.typing import NDArray
 
+from ser._internal.runtime.accurate_backend_runtime import (
+    build_backend_for_profile as _build_backend_for_profile_impl,
+)
+from ser._internal.runtime.accurate_backend_runtime import (
+    runtime_config_for_profile as _runtime_config_for_profile_impl,
+)
+from ser._internal.runtime.accurate_execution_flow import (
+    execute_accurate_inference_with_retry as _execute_accurate_inference_with_retry_impl,
+)
+from ser._internal.runtime.accurate_execution_flow import (
+    run_accurate_retryable_operation as _run_accurate_retryable_operation_impl,
+)
+from ser._internal.runtime.accurate_operation_setup import _PayloadLike as _AccuratePayloadLike
+from ser._internal.runtime.accurate_operation_setup import _RequestLike as _AccurateRequestLike
+from ser._internal.runtime.accurate_operation_setup import (
+    prepare_in_process_operation as _prepare_in_process_operation_orchestration,
+)
+from ser._internal.runtime.accurate_operation_setup import (
+    prepare_process_operation as _prepare_process_operation_orchestration,
+)
+from ser._internal.runtime.accurate_operation_setup import (
+    run_process_operation as _run_process_operation_orchestration,
+)
+from ser._internal.runtime.accurate_retry_operation import (
+    run_accurate_inference_with_retry_policy as _run_accurate_retry_policy_impl,
+)
+from ser._internal.runtime.accurate_runtime_support import (
+    build_cpu_settings_snapshot as _build_cpu_settings_snapshot_impl,
+)
+from ser._internal.runtime.accurate_runtime_support import (
+    build_process_settings_snapshot as _build_process_settings_snapshot_impl,
+)
+from ser._internal.runtime.accurate_runtime_support import (
+    encode_accurate_sequence as _encode_accurate_sequence_impl,
+)
+from ser._internal.runtime.accurate_runtime_support import (
+    prepare_accurate_backend_runtime as _prepare_accurate_backend_runtime_support_impl,
+)
+from ser._internal.runtime.accurate_worker_operation import (
+    AccurateRetryOperationState,
+    PreparedAccurateOperation,
+    build_transient_failure_handler,
+)
+from ser._internal.runtime.accurate_worker_operation import (
+    finalize_in_process_setup as _finalize_in_process_setup_impl,
+)
+from ser._internal.runtime.accurate_worker_operation import (
+    prepare_retry_state as _prepare_retry_state_impl,
+)
+from ser._internal.runtime.accurate_worker_operation import (
+    run_inference_operation as _run_inference_operation_impl,
+)
+from ser._internal.runtime.policy import run_with_retry_policy
 from ser._internal.runtime.process_timeout import (
     run_with_process_timeout as _run_with_process_timeout_impl,
 )
+from ser._internal.runtime.retry_primitives import (
+    jittered_retry_delay_seconds as _jittered_retry_delay_seconds_impl,
+)
 from ser._internal.runtime.single_flight import SingleFlightRegistry
 from ser._internal.runtime.worker_bindings import (
     is_setup_complete_message as _is_setup_complete_message_binding,
@@ -56,81 +112,27 @@
 from ser.repr import Emotion2VecBackend, FeatureBackend, WhisperBackend
 from ser.repr.runtime_policy import resolve_feature_runtime_policy
 from ser.runtime import mps_oom as mps_oom_helpers
-from ser.runtime.accurate_backend_runtime import (
-    build_backend_for_profile as _build_backend_for_profile_impl,
-)
-from ser.runtime.accurate_backend_runtime import (
-    runtime_config_for_profile as _runtime_config_for_profile_impl,
-)
 from ser.runtime.accurate_execution import LoadedModelLike as _AccurateLoadedModelLike
 from ser.runtime.accurate_execution import (
     run_accurate_inference_once as _run_accurate_inference_once_impl,
 )
-from ser.runtime.accurate_execution_flow import (
-    execute_accurate_inference_with_retry as _execute_accurate_inference_with_retry_impl,
-)
-from ser.runtime.accurate_execution_flow import (
-    run_accurate_retryable_operation as _run_accurate_retryable_operation_impl,
-)
 from ser.runtime.accurate_model_contract import (
     ArtifactMetadataCarrier,
 )
 from ser.runtime.accurate_model_contract import (
     validate_accurate_loaded_model_runtime_contract as _validate_accurate_loaded_model_runtime_contract_impl,
 )
-from ser.runtime.accurate_operation_setup import _PayloadLike as _AccuratePayloadLike
-from ser.runtime.accurate_operation_setup import _RequestLike as _AccurateRequestLike
-from ser.runtime.accurate_operation_setup import (
-    prepare_in_process_operation as _prepare_in_process_operation_orchestration,
-)
-from ser.runtime.accurate_operation_setup import (
-    prepare_process_operation as _prepare_process_operation_orchestration,
-)
-from ser.runtime.accurate_operation_setup import (
-    run_process_operation as _run_process_operation_orchestration,
-)
 from ser.runtime.accurate_prediction import (
     confidence_and_probabilities as _confidence_and_probabilities_impl,
 )
 from ser.runtime.accurate_prediction import predict_labels as _predict_labels_impl
-from ser.runtime.accurate_retry_operation import (
-    run_accurate_inference_with_retry_policy as _run_accurate_retry_policy_impl,
-)
-from ser.runtime.accurate_runtime_support import (
-    build_cpu_settings_snapshot as _build_cpu_settings_snapshot_impl,
-)
-from ser.runtime.accurate_runtime_support import (
-    build_process_settings_snapshot as _build_process_settings_snapshot_impl,
-)
-from ser.runtime.accurate_runtime_support import (
-    encode_accurate_sequence as _encode_accurate_sequence_impl,
-)
-from ser.runtime.accurate_runtime_support import (
-    prepare_accurate_backend_runtime as _prepare_accurate_backend_runtime_support_impl,
-)
-from ser.runtime.accurate_worker_operation import (
-    AccurateRetryOperationState,
-    PreparedAccurateOperation,
-    build_transient_failure_handler,
-)
-from ser.runtime.accurate_worker_operation import (
-    finalize_in_process_setup as _finalize_in_process_setup_impl,
-)
-from ser.runtime.accurate_worker_operation import prepare_retry_state as _prepare_retry_state_impl
-from ser.runtime.accurate_worker_operation import (
-    run_inference_operation as _run_inference_operation_impl,
-)
 from ser.runtime.contracts import InferenceRequest
 from ser.runtime.phase_contract import PHASE_EMOTION_INFERENCE, PHASE_EMOTION_SETUP
 from ser.runtime.phase_timing import (
     log_phase_completed,
     log_phase_failed,
     log_phase_started,
 )
-from ser.runtime.policy import run_with_retry_policy
-from ser.runtime.retry_primitives import (
-    jittered_retry_delay_seconds as _jittered_retry_delay_seconds_impl,
-)
 from ser.runtime.schema import InferenceResult
 from ser.utils.audio_utils import read_audio_file