[DD-005] Affinity calculation: storage vs. computation strategy

DD Identifier

DD-005

Target version

v0.5.0

Context

DD-004 defines the Affinity concept and its properties. The mechanism for computing and maintaining Affinity relationships is intentionally left open pending benchmarking at scale.

Options considered

Option	Advantage	Risk
A — Explicit join table (stored)	Fast reads; simple queries	Write overhead; risk of stale data on attribute update
B — On-the-fly computation	Always fresh; no storage overhead	Potentially expensive on large trees
C — Signals / triggers (materialised on write)	Fresh on read; amortised write cost	Complex invalidation logic; Django signal pitfalls

Decision

⏳ Deferred to v0.5.0 — requires benchmarking on realistic dataset sizes before committing to an approach.

Constraints to honour when this decision is made

• Transitivity rules from DD-004 must be preserved exactly.
• Must remain performant for trees with thousands of nodes.
• Must not silently produce stale results.

Affected scopes

• api — public interface
• tests — pytest, coverage

References

• Depends on: #DD-004
• Resolves in: v0.5.0