data-persistence-executor

name	data-persistence-executor
description	Domain guidance for implementing data and persistence phases. Loaded when phase category is DATA.

Data/Persistence Implementation Guidance

Default stance

Be conservative: validate aggressively, fail safely, never use destructive shortcuts.

File I/O discipline

• Always set explicit encoding for text files (encoding='utf-8').
• Normalize/resolve paths via one helper; never hardcode absolute paths.
• Use atomic writes for important artifacts (temp file → fsync if needed → rename).
• Handle missing files/dirs explicitly (create with clear policy or fail with clear error).
• Close file handles deterministically (context managers).

Serialization safety

• Implement explicit encoders/decoders for datetime/Decimal/bytes.
• Use envelopes: schema_version + payload + metadata.
• On parse failure: quarantine and surface structured error — do not guess.

Migrations

• Never run reset/downgrade-to-base as "verification."
• Add "destructive detected → stop" guardrails.
• Prefer deterministic schema diff + lint tools over hand-written migration SQL.

Required tests

• Constraint tests (unique/FK/not-null/check violations rejected).
• Round-trip: serialize → deserialize → equal for representative + edge inputs.
• Backward compat: old payload versions still load correctly.
• Cache: invalidation correctness + bounded size + stale detection.