Boundary Discipline

Place validation, type narrowing, and error handling at system boundaries. Trust internal code unconditionally. Business logic lives in pure functions. The shell is thin and mechanical.

Why: Scattered validation is noisy, redundant, and gives a false sense of safety. Keep logic out of framework wiring so it can be tested without the framework.

The pattern:

• At boundaries (CLI args, config files, external APIs, network protocols, serial and bus frames): validate, return errors, handle defensively.
• Inside the system: typed data, error propagation, no re-validation. Trust the types.
• Across the boundary. Expose domain concepts, not the boundary's private representation. Keep general-purpose mechanism inside and special-purpose policy at the edge.

Applications:

Validation and error handling:

• Validate config at parse time (the boundary), not inside business logic
• Parse raw data into domain types at the boundary (a dataclass or model built by one parse function)
• Keep transport, storage, framework, and wire types out of the public surface
• Skip None checks deep in call chains when the boundary already validated

Code organization:

• Business logic in pure functions with no framework dependencies
• Parse functions: pure transforms from raw bytes to typed state
• Prompt construction: structured state in, string out
• Scoring and assessment: pure transforms from state to results

Firmware: register access and peripheral I/O sit behind a HAL. Logic above it takes typed values, so it runs in host tests without the board.

The tests:

• "Is this data crossing a system boundary right now?" If not, validation is redundant.
• "Can this be a pure function that the shell just calls?" If yes, extract it.