manual_slop/conductor/directives/boundary_layer_exception/v1.md

dict[str, Any], Any, Optional[T] returns are allowed only at the literal wire boundary (TOML/JSON parse)

17.7 The one exception: the boundary layer

The ONLY place these patterns are allowed is at the literal wire boundary — the function that calls tomllib.load(), json.loads(), or a vendor SDK's response parser. The boundary is 2-3 functions per file. Every consumer IMMEDIATELY converts to a typed dataclass via from_dict().

17.8 Enforcement

• scripts/audit_weak_types.py --strict — flags dict[str, Any], Any, anonymous tuple returns
• scripts/audit_optional_in_3_files.py --strict — flags Optional[T] return types in the baseline 4 files (src/mcp_client.py, src/ai_client.py, src/rag_engine.py, plus one more). An all-src/*.py successor (audit_optional_returns.py) is referenced in older planning docs but is NOT yet built — the live script today is audit_optional_in_3_files.py.

---

The one exception (the boundary layer) — from data_oriented_design.md §8.5:

at the literal wire boundary (TOML parsing, JSON parsing, vendor SDK response parsing), the data is open-ended for the 100ns between parsing and from_dict() conversion. At that boundary:

• The function that calls tomllib.load() or json.loads() may return Metadata (the typed fat struct — see §8.6).
• Every consumer of that function IMMEDIATELY calls SomeTypedDataclass.from_dict(metadata) and uses the typed result.
• The boundary is 2-3 functions per file (one per wire entry point).

No other code uses Metadata or dict[str, Any] or Any. This is enforced by scripts/audit_weak_types.py --strict (existing) + the boundary-layer audit (planned in conductor/tracks/cruft_elimination_20260627/spec.md).

8.6 The Boundary Layer (the wire schema)

The codebase has ONE typed fat struct at the boundary: Metadata in src/type_aliases.py. It is @dataclass(frozen=True, slots=True) with explicit fields covering the TOML/JSON wire schema (paths, project, discussion, role, content, ts, source_tier, model, depends_on, document, script, args, etc.). It is used in exactly 2 places:

---

1. Use Metadata ONLY at the wire boundary (TOML/JSON parse) — from type_aliases.md

UPDATED 2026-06-25 (the C11/Odin/Jai-in-Python mandate). Metadata is the typed fat struct at the wire boundary. It is @dataclass(frozen=True, slots=True) with explicit fields covering the TOML/JSON wire schema (paths, project, discussion, role, content, ts, source_tier, model, depends_on, document, script, args, etc.).

# CORRECT — at the literal wire boundary:
def _parse_toml_config(raw: str) -> Metadata:
 return Metadata.from_dict(tomllib.loads(raw))

# CORRECT — consumer at the boundary, converts immediately:
def _load_project_context(raw_toml: Metadata) -> ProjectContext:
 return ProjectContext.from_dict(raw_toml)

# WRONG — using Metadata as a lazy-typing escape hatch:
def process_event(self, event: Metadata) -> None:
 if hasattr(event, 'tool_calls'):
  ...   # ← BAD: this is the laziest possible typing

Metadata is NOT TypeAlias = dict[str, Any]. It is a typed fat struct. The boundary is 2-3 functions per file. Every consumer IMMEDIATELY converts to a componentized dataclass via from_dict().

Anti-pattern (banned): Metadata: TypeAlias = dict[str, Any] (the lazy-typing escape hatch). LLMs default to this because it's idiomatic Python. This codebase does NOT do idiomatic Python. See data_oriented_design.md §8.5.