manual_slop/conductor/directives/nil_sentinel_pattern/v1.md

Use nil-sentinel dataclasses instead of None (zero-initialized frozen dataclass; safe to read fields)

1. Nil-Sentinel Dataclasses (replaces None)

When a function would "return None" in conventional Python, return a nil-sentinel dataclass instead. The sentinel has all default values (zero-initialized) and is safe to read from.

from dataclasses import dataclass, field

@dataclass(frozen=True)
class NilPath:
 exists: bool = False
 read_text: str = ""
 errors: list[ErrorInfo] = field(default_factory=list)

NIL_PATH = NilPath() # module-level singleton

Callers don't need if x is None: checks; they can call x.read_text and get "" on the nil path.

Convention: NIL_* (uppercase) is the module-level singleton. Nil* (PascalCase) is the class. Frozen dataclass prevents runtime mutation.