feat(service): protocol ports, validated runtime seeds and typed runtime hook (V8 S1)

[marlon-costa-dc]

Summary

Slice S1 of plan V8 (epic flext-4jtcb, bead flext-4jtcb.1; ADR-019 proposed in flext-sh/flext#274). It makes the service contract's dependency ports real in the kernel and deletes the dead runtime paths.

• Ports. t.Port[P] = Annotated[P, SkipJsonSchema()]. A service field name: t.Port[p.X] = m.Field(exclude=True, ...) is validated by isinstance on construction and on assignment, and never enters the JSON Schema. FlextService.__pydantic_on_complete__ rejects a port type that is not a plain Protocol class (subscripted generic, concrete class) with c.ERR_SERVICE_PORT_TYPE; Pydantic itself rejects a Protocol that is not runtime-checkable.
• Runtime. m.ServiceRuntime collaborators and m.RuntimeBootstrapOptions are validated ports. The x seeds runtime_settings and initial_context drop SkipValidation for t.Port[p.X | None]; settings_type and settings_overrides leave the schema, so model_json_schema() of any service works and lists only data.
• Hook. u.resolve_runtime_options is a typed match over an options model or a component: the base's runtime_bootstrap_options is read through p.RuntimeBootstrapProvider (not declared on x, so no @override sweep), instance seeds win, any other source raises TypeError. No getattr overlay, no attribute probes, no model_copy(update=).
• Builder. u.build_service_runtime uses the container's context and command bus; a dispatcher that cannot be resolved raises with its cause instead of becoming None.
• Deleted, with zero uses in the fleet (validation workspace grep): the RuntimeBootstrapOptions fields services, factories, resources, container_overrides, wire_*, subproject and registry; ServiceRuntime.registry (which removes the registry↔runtime cycle); FlextRegistry.configure_runtime, create(runtime=) and the dead _create_initial_runtime; build_registry(runtime=); service_settings_type; _normalize_runtime_override_mapping; resolve_wire_targets; p.CloneableRuntime; the orphan tests/unit/_golden_public_api.json.
• Failures. r.unwrap() and .value raise from the carried exception; __exit__ is typed.
• Docs. docs/guides/service-patterns.md is rewritten for the contract. The stale dependency_injector_prompt.md and improvements/dependency-injection-audit.md are deleted, and overview.md and dependency-injection-advanced.md are aligned.
• Projections. Regenerated by make gen and locks written by make upg with the current flext-infra.

Validation

• Runtime through the public API: a port service accepts a real adapter and rejects a non-conforming value on construction and assignment; the schema lists only data; the hook sets the settings class and a seed overrides it; unwrap() carries __cause__; the registry builds without recursion.
• Lane gates on 4f367dc0c, run with env -u VIRTUAL_ENV -u UV_PROJECT_ENVIRONMENT:
  • make gen exit 0 twice. make gen on the committed candidate leaves git status --porcelain --untracked-files=all empty (fixed point).
  • make fix and make fmt exit 0.
  • make check: lint, pyrefly, pyright, mypy (252 s), markdown, security, smells, loc-cap, layout, tier-whitelist, index-declarations, canonical-alias, direnv and deferred-self-reference all at 0. The only red is silent-failure 2 (below).
  • make test-full exit 0: the incremental phase is a testmon cache hit (0 changed files), then 2709 passed with warnings as errors, including the 17 new port and bootstrap tests.
• Base red not caused by this PR: silent-failure 2 in _utilities/_beartype/_helpers_parts/helpers_part_01.py:33,93 (ImportError and NameError branches returning a sentinel). The same findings are in the fleet baseline at c47ea7d79. Their owner is lane flext-edcqq, whose uncommitted refactor (owner-aware alias resolution with new modules) is the fix; it is not portable as a hunk. The three unwrap_or(sentinel) test findings from the same baseline are fixed here by porting that lane's hunks byte-identically.
• Fleet non-breakage runs in the V8 validation workspace before this leaves draft.

🤖 Generated with Claude Code

---

Summary by cubic

Implements slice S1 of the V8 service plan: dependency ports are now real in the kernel, the runtime hook is typed, and dead runtime paths and the registry↔runtime cycle are removed.

New Features

• t.Port[P] validates a service dependency with isinstance on construction and assignment and never leaks it into the JSON Schema; non-Protocol or subscripted port types are rejected at class creation.
• m.RuntimeBootstrapOptions and m.ServiceRuntime collaborators are validated ports; runtime_settings and initial_context seeds drop SkipValidation.
• u.resolve_runtime_options is a typed match where instance seeds win and unknown sources raise TypeError.
• u.build_service_runtime builds from the container's context and command bus; unresolvable dispatchers raise with their cause.
• Result.unwrap() and Result.value raise with the carried exception as __cause__.

Refactors

• PEP 695 alias evaluation is now owner-aware and source-backed (_beartype.type_aliases + module_source): a TYPE_CHECKING-only alias becomes a typed m.DeferredAlias, enforcement Report exposes report.complete for deferral-safe inspection, lazy_alias_suffixes propagates import failures, and facade lookup runs only for loaded packages so enforcement never imports packages as a side effect — clearing the two silent-failure findings in helpers_part_01.py.
• Removed all runtime fields and methods with zero fleet uses: services, factories, resources, container_overrides, wire_*, subproject, registry; plus ServiceRuntime.registry, configure_runtime, create(runtime=), build_registry(runtime=), service_settings_type, resolve_wire_targets, and p.CloneableRuntime.
• Rewrote service-patterns.md for the ADR-019 contract; deleted the stale DI prompt and audit docs and aligned overview/advanced guides.
• Toolchain is frozen via committed mise.version and mise.lock; make upg resolves and locks at flext-infra 8c0c20eca and the rope 1.14.0+dc.2 fork, the projected Makefile drops .WAIT so GNU Make 4.3 runs make setup, workspace members resolve the workspace runtime, and CI passes the token only through BuildKit secrets.

^{Written for commit ebbe6f0. Summary will update on new commits.}

[sonarqubecloud]

Quality Gate passed

Issues
6 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud