TenantAtlas/specs/167-derived-state-memoization/research.md

Research: Request-Scoped Derived State and Resolver Memoization

Decision 1: Use a dedicated request-scoped in-memory store bound through the Laravel container

• Decision: Introduce one dedicated request-scoped derived-state store with request-local lifecycle semantics instead of static arrays or persistent cache stores.
• Rationale: The feature needs explicit reuse within one HTTP or Livewire request and explicit isolation across requests. A request-local container binding makes that boundary visible and testable while avoiding new persistence and avoiding cross-request staleness.
• Alternatives considered:
  • Static caches inside presenters or resources: rejected because they hide scope boundaries, duplicate behavior across families, and make invalidation inconsistent.
  • Cache::remember() or Redis-backed caching: rejected because the spec explicitly excludes cross-request caching and because stale semantic reuse would become much harder to reason about.

Decision 2: Key derivations by family, record identity, variant, and scope-sensitive context

• Decision: Define one deterministic key contract that includes the derived-state family, stable record identity, variant or surface mode, and any workspace, tenant, or visibility-sensitive context required to produce the correct result.
• Rationale: Existing repeated work happens because the same deterministic question is asked multiple times. Correct reuse therefore depends on a stable definition of “same question.” Model-object identity alone is insufficient because the same record can appear through different model instances or under different scopes.
• Alternatives considered:
  • Model ID only: rejected because it cannot distinguish list vs detail variants or capability-sensitive outputs.
  • spl_object_hash() only: rejected because it prevents convergence across separate model instances representing the same record.

Decision 3: Integrate through the existing family entry points, not by adding a new presentation framework

• Decision: Route reuse through ArtifactTruthPresenter, OperationUxPresenter, and RelatedNavigationResolver entry points instead of creating a generic presenter base class, a universal decorator, or a new UI taxonomy layer.
• Rationale: The business semantics already live in these families. The feature's goal is to reduce repeated deterministic work beneath them, not to redesign how operator meaning is modeled.
• Alternatives considered:
  • New cross-domain presentation framework: rejected because it would layer new semantics on top of already-correct families and violate the spec's narrow foundation intent.
  • Surface-only fixes per page: rejected because the same repeated-cost pattern already spans multiple domains and would continue to reappear elsewhere.

Decision 4: Converge existing hidden caches into the shared contract and keep negative results reusable

• Decision: Standardize existing local request-like caches, such as the finding primary related-entry cache, behind the shared contract and allow deterministic negative results like “no related entry” or “no next action” to be reused within one request.
• Rationale: The repo already contains evidence that request-local reuse is useful, but it is unevenly applied. Converging on one contract avoids parallel caching patterns and still prevents repeated work when the correct result is the absence of a link or action.
• Alternatives considered:
  • Leave existing local caches untouched and optimize only the worst pages: rejected because it would preserve multiple hidden patterns and make future adoption harder.
  • Cache only positive results: rejected because deterministic negative results can also drive repeated work and should be equally reusable when scope-stable.

Decision 5: Treat mutation freshness as an explicit family rule

• Decision: Covered mutating flows must explicitly invalidate or bypass request-local reuse after business state changes within the same request.
• Rationale: The spec requires “no stale within request ambiguity.” A clear family-level freshness rule is safer than assuming the existing code path order will always avoid stale derived values.
• Alternatives considered:
  • Cache for the full request without exceptions: rejected because post-action state could become stale and misleading.
  • Disable reuse on every Livewire action: rejected because many actions still have deterministic pre- and post-action read phases where request-local reuse remains valuable.

Decision 6: Test derivation-count behavior directly instead of proxying everything through query-count assertions

• Decision: Validate the feature with focused unit and feature tests that prove one full derivation per request for representative covered families, plus explicit scope-safety and mutation-path tests.
• Rationale: The repeated-cost problem is not just SQL chatter. It is repeated presenter and resolver work across closures and page fragments. Query-count assertions alone would miss important non-query work and would not prove freshness rules.
• Alternatives considered:
  • Measure only query counts: rejected because the problem is broader than SQL and includes repeated in-memory translation and navigation assembly.
  • Rely on manual profiling only: rejected because this feature needs regression protection against future local cache drift.