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

# Feature Specification: Request-Scoped Derived State and Resolver Memoization

**Feature Branch**: `167-derived-state-memoization`  
**Created**: 2026-03-28  
**Status**: Draft  
**Input**: User description: "Request-scoped derived state and resolver memoization foundation"

## Spec Scope Fields *(mandatory)*

- **Scope**: workspace + tenant + canonical-view
- **Primary Routes**:
  - Workspace-scoped baseline snapshot list and detail surfaces
  - Tenant-scoped evidence snapshot list and detail surfaces
  - Workspace-scoped evidence overview and review register surfaces
  - Tenant-scoped tenant review and review-pack list and detail surfaces
  - Workspace-scoped operation run list and tenantless operation-run detail surfaces
  - Existing detail and list surfaces that build related-context entries through the shared navigation resolver, especially baseline snapshot, policy version, and finding inspection surfaces
- **Data Ownership**:
  - Workspace-owned records affected: baseline snapshots, operation runs, workspace-scoped review register rows, and related workspace-scoped records whose operator-facing state is repeatedly derived during one request
  - Tenant-owned records affected: evidence snapshots, tenant reviews, review packs, and tenant-owned records that contribute related navigation entries or operator guidance on covered surfaces
  - This feature does not change ownership boundaries and does not introduce any new persisted artifact; it only changes how already-owned truth is reused inside one request
- **RBAC**:
  - Existing workspace membership, tenant entitlement, and capability checks remain unchanged across all covered surfaces
  - Non-members and out-of-scope users remain deny-as-not-found
  - In-scope users missing required capability remain forbidden
  - Request-local reuse must never cross workspace, tenant, request, or authorization boundaries

For canonical-view specs, the spec MUST define:

- **Default filter behavior when tenant-context is active**: Canonical evidence, review, and operation-run surfaces continue to open in the currently active tenant context or existing prefiltered scope when entered from tenant context. Request-local reuse must respect that existing scope instead of broadening a derivation to workspace-wide results.
- **Explicit entitlement checks preventing cross-tenant leakage**: Any memoized derived state used on canonical views must remain isolated to the current request and must include scope-sensitive inputs whenever the output depends on tenant context, workspace context, visibility rules, or capability-sensitive presentation. A derived label, next action, or related entry computed for one tenant or one entitlement context must never be reused for another.

## Operator Surface Contract *(mandatory when operator-facing surfaces are changed)*

| Surface | Primary Persona | Surface Type | Primary Operator Question | Default-visible Information | Diagnostics-only Information | Status Dimensions Used | Mutation Scope | Primary Actions | Dangerous Actions |
|---|---|---|---|---|---|---|---|---|---|
| Baseline snapshot list and detail | Workspace governance operator | List/detail | Is this snapshot trustworthy, and where should I go next? | Existing artifact-truth label, explanation, status badges, related context, next action | Raw payloads, low-level counters, internal reason fragments | artifact truth, freshness, readiness, operator actionability | Existing actions only | View snapshot, inspect related context, open related run | Existing destructive actions unchanged |
| Evidence snapshot list/detail and evidence overview | Tenant or workspace governance operator | List/detail/overview | What evidence exists, how complete is it, and what should I inspect? | Existing truth badges, completeness explanation, next action, related navigation | Raw evidence payloads, internal detail fragments | artifact truth, completeness, freshness, actionability | Existing actions only | View snapshot, open related review or run | Existing destructive actions unchanged |
| Tenant review list/detail and review register | Tenant or workspace review operator | List/detail/register | Is this review ready, and what is blocking it if not? | Existing primary label, publication-readiness state, next action, related navigation | Raw section payloads, internal readiness details | artifact truth, publication readiness, actionability | Existing actions only | View review, open related pack or run | Existing destructive actions unchanged |
| Review-pack list/detail | Tenant review operator | List/detail | Is this pack usable, and what is its source context? | Existing primary truth state, operator explanation, related navigation | Internal generation details, raw export payloads | artifact truth, readiness, actionability | Existing actions only | View pack, open source review | Existing destructive actions unchanged |
| Operation run list/detail and related-context surfaces | Governance or operations operator | List/detail | What happened, what does it mean, and where should I navigate? | Existing surface guidance, operator explanation, related entries, existing run metadata | Raw context JSON, low-level execution fields | execution outcome, artifact truth where relevant, actionability | Existing actions only | View run, retry where already allowed, open related record | Existing dangerous rerun or mutation actions unchanged |

## Proportionality Review *(mandatory when structural complexity is introduced)*

- **New source of truth?**: No. The feature reuses existing artifact truth, operation UX, and related-navigation truth.
- **New persisted entity/table/artifact?**: No. All reuse remains request-local and in-memory only.
- **New abstraction?**: Yes. A single request-scoped derived-state contract is introduced so deterministic presenter and resolver outputs can be reused explicitly within one request.
- **New enum/state/reason family?**: No. This feature must not introduce a new semantic family.
- **New cross-domain UI framework/taxonomy?**: No. The feature is a runtime reuse contract, not a new interpretation or badge framework.
- **Current operator problem**: Governance-heavy list, detail, and widget surfaces repeatedly recompute the same truth, guidance, and related-navigation state, making each additional closure or surface fragment more expensive than it should be and increasing the risk that related values diverge in timing or freshness.
- **Existing structure is insufficient because**: Current presenters and resolvers are semantically correct but are called independently from badge, description, tooltip, visibility, URL, detail-entry, and widget closures without one explicit request-local reuse boundary.
- **Narrowest correct implementation**: A request-scoped deterministic reuse contract for explicitly covered presenter and resolver families is the smallest viable fix. It addresses the repeated-cost shape without adding persistence, without introducing cross-request caching, and without redefining business semantics.
- **Ownership cost**: The feature adds key-discipline rules, adoption work on covered surfaces, freshness testing for mutation flows, and ongoing review discipline so new heavy closures do not bypass the shared contract.
- **Alternative intentionally rejected**: Page-local static caches, ad hoc helper memoization, cross-request cache stores, and broad query redesign were rejected because they either hide scope boundaries, create stale-state ambiguity, or solve a different layer of the problem.
- **Release truth**: Current-release truth. The affected hotspots already exist on shipped artifact, review, navigation, and operation surfaces.

## User Scenarios & Testing *(mandatory)*

### User Story 1 - Reuse One Derived Truth Per Record (Priority: P1)

As an operator viewing governance-heavy lists and detail surfaces, I want repeated labels, explanations, icons, colors, next actions, and related links for the same record to come from one request-local derivation, so that the page remains responsive and internally consistent.

**Why this priority**: This is the immediate product-cost problem. The same row or detail page currently asks for the same deterministic answer multiple times through separate UI closures.

**Independent Test**: Can be fully tested by instrumenting a covered surface where the same presenter or resolver output is read multiple times for one record and proving that the full derivation occurs once per request while all visible values stay unchanged.

**Acceptance Scenarios**:

1. **Given** a covered list row renders a primary label, badge color, badge icon, description, and next action from the same artifact-truth state, **When** the row is built within one request, **Then** the underlying full truth derivation occurs once and the visible outputs remain identical to the current semantics.
2. **Given** a covered detail page renders related-context entries and operator explanation from the same underlying record, **When** the page is built within one request, **Then** repeated reads reuse the same request-local derived state instead of recomputing it separately.

---

### User Story 2 - Reuse Derived State Across Surface Fragments In One Request (Priority: P1)

As an operator using pages that combine tables, summary sections, and related-context fragments, I want the same deterministic truth to be reused across those fragments, so that multi-part pages do not multiply the same derivation cost.

**Why this priority**: The repeated-cost shape is not limited to one table cell. It also appears when one request renders widgets, detail sections, and navigation context for the same records.

**Independent Test**: Can be fully tested by instrumenting a covered page where the same record contributes to more than one surface fragment during one request and proving that the derivation is reused while the page still renders the same operator-facing meaning.

**Acceptance Scenarios**:

1. **Given** a canonical or workspace surface renders a table plus a supporting detail or related-context fragment for the same record set, **When** the request completes, **Then** the shared presenter or resolver family computes each deterministic record-scope result once.
2. **Given** a covered page uses both a presenter-backed explanation and a resolver-backed related link for the same record in multiple places, **When** the page renders, **Then** each covered family reuses its own request-local result instead of repeating full derivation work per consumer.

---

### User Story 3 - Preserve Freshness In Mutation Flows (Priority: P2)

As an operator triggering an action that changes a record's visible truth, guidance, or related navigation, I want any post-action state shown within the same request to be freshly determined when needed, so that the interface never reuses stale pre-mutation derived state.

**Why this priority**: Request-local reuse is only safe if mutation flows define where reuse stops and fresh determination must resume.

**Independent Test**: Can be fully tested by executing a covered mutating action that changes operator-visible truth or related navigation in the same request and proving that the post-action state is not taken from the stale pre-action derivation.

**Acceptance Scenarios**:

1. **Given** a covered action changes the business state used by a presenter or resolver, **When** the action finishes within the same request, **Then** any post-action truth or navigation shown to the operator is freshly determined according to the explicit freshness rule.
2. **Given** a covered derivation is intentionally non-deterministic or capability-sensitive, **When** the request path cannot safely reuse a prior result, **Then** the feature bypasses memoization or uses a distinct key rather than returning a stale or cross-scope result.

### Edge Cases

- The same underlying record is referenced through more than one model instance during one request; identity-based keying must still converge when the business inputs are the same.
- Two derivation variants for the same record require different outputs, such as list-surface primary state versus detail-surface related entries; the key contract must keep those variants separate.
- A covered path returns a stable negative result such as no related entry or no next action; that absence must be reusable within the request instead of triggering repeated resolver work.
- A derivation depends on capability, visibility, or current-scope context; memoization must include those inputs or explicitly opt out.
- A mutating action changes the state used by a covered derivation inside the same request; the pre-mutation result must not be reused after the state change.
- Canonical views entered from tenant context must not reuse derived state outside the active tenant or workspace scope.

## Requirements *(mandatory)*

**Constitution alignment (required):** This feature introduces no new Microsoft Graph call path, no new persistence, and no new long-running operation family. It hardens the request-time read path for existing presenter and resolver outputs. Existing business truth, existing safety gates, existing audit semantics, and existing operation observability remain unchanged. If a covered mutating action needs fresh post-action truth, the implementation must define that freshness path explicitly rather than relying on accidental stale reuse.

**Constitution alignment (PROP-001 / ABSTR-001 / PERSIST-001 / STATE-001 / BLOAT-001):** The feature introduces one new abstraction and no new persistence or state family. The abstraction is justified because repeated deterministic derivation is already a current-release cross-surface cost problem and existing local call-site discipline is insufficient. The feature follows the default bias by deriving before persisting, keeping reuse request-local, and avoiding a broader cache platform.

**Constitution alignment (OPS-UX):** This feature does not create a new `OperationRun` family and does not change the three-surface feedback contract. If operation-run list or detail surfaces adopt request-local guidance reuse, `OperationRun.status` and `OperationRun.outcome` remain service-owned and all existing notification behavior stays unchanged.

**Constitution alignment (RBAC-UX):** This feature does not change the authorization model, but it must not become an accidental authorization layer. Non-members and wrong-scope users remain `404`. In-scope users lacking capability remain `403`. Any derived state that depends on visibility or capability context must include that context in its reuse boundary or bypass reuse. At least one positive and one negative scope-safety regression test must prove that request-local reuse cannot leak unauthorized tenant or workspace state.

**Constitution alignment (OPS-EX-AUTH-001):** Not applicable. No authentication handshake behavior is changed.

**Constitution alignment (BADGE-001):** This feature must not introduce new page-local badge mappings. If covered surfaces reuse the same derived truth for multiple badge properties, they must continue to consume centralized badge semantics with unchanged visible meaning.

**Constitution alignment (UI-FIL-001):** Covered admin and operator surfaces continue to use existing Filament tables, infolists, widgets, and shared UI primitives. The feature should consolidate how existing derived values are obtained, not introduce custom replacement markup or a new local status language.

**Constitution alignment (UI-NAMING-001):** This feature does not introduce new operator-facing action vocabulary. Existing labels, helper copy, next-action text, run titles, and related-link labels must remain semantically unchanged unless an existing covered surface is already inconsistent and the change is explicitly called out by a follow-up spec.

**Constitution alignment (OPSURF-001):** This feature materially affects operator-facing surfaces but must not change what those surfaces primarily communicate. Default-visible information, diagnostic hierarchy, mutation scope messaging, and inspect affordances stay the same. The change is that repeated deterministic state is obtained once per request and reused consistently.

**Constitution alignment (UI-SEM-001 / LAYER-001 / TEST-TRUTH-001):** The feature must not create a second semantic layer above artifact truth, operation UX, or related navigation. It reuses existing layers and adds one request-local reuse boundary beneath them. Tests must focus on business-visible consistency, scope safety, and freshness consequences rather than treating memoization as a goal by itself.

**Constitution alignment (Filament Action Surfaces):** Covered Filament Resources and Pages keep their current action inventories and inspect affordances. The Action Surface Contract remains satisfied because this feature changes derivation reuse behind existing actions rather than introducing new mutation behavior. No new exemptions are needed.

**Constitution alignment (UX-001 — Layout & Information Architecture):** No new Filament layout pattern is introduced. Existing view-page, list-page, widget, and summary structures remain intact. Any row-safe or page-safe consumption helper introduced by implementation must preserve current table filters, sortability, inspection flow, empty states, and detail-section hierarchy.

### Functional Requirements

- **FR-167-001**: The system MUST provide one explicit request-scoped contract for deterministic derived presentation and navigation state used repeatedly within one HTTP or Livewire request.
- **FR-167-002**: The contract MUST be isolated per request and MUST NOT persist derived state across requests.
- **FR-167-003**: The contract MUST use deterministic keys that can distinguish at minimum derivation family, record type, record identity, surface variant or mode, and any scope-sensitive input that changes the result.
- **FR-167-004**: The contract MUST support an explicit opt-out or distinct-key path for derivations that are non-deterministic, mutation-sensitive, or capability-sensitive.
- **FR-167-005**: The first implementation slice MUST route the covered `ArtifactTruthPresenter::for*()` paths through the request-scoped contract for baseline snapshots, evidence snapshots, tenant reviews, review packs, and operation runs.
- **FR-167-006**: The first implementation slice MUST route covered `OperationUxPresenter` surface-guidance and operator-explanation paths through the same request-scoped contract.
- **FR-167-007**: The first implementation slice MUST route covered `RelatedNavigationResolver` primary-entry, detail-entry, and header-entry paths through the same request-scoped contract where repeated resolution currently occurs.
- **FR-167-008**: The first implementation slice MUST cover at least one list surface, one detail surface, and one widget or canonical surface across the three target families.
- **FR-167-009**: Covered surfaces MUST be able to read the same deterministic derived value from multiple UI consumers in one request without triggering a second full derivation.
- **FR-167-010**: Covered list surfaces MUST define a row-safe consumption pattern so label, description, tooltip, icon, color, URL, and visibility consumers can share one derived-state result per row when they rely on the same family and scope.
- **FR-167-011**: Covered detail surfaces MUST define an equivalent page-safe or section-safe consumption pattern when the same deterministic result is read more than once during one request.
- **FR-167-012**: The contract MUST support stable reuse of negative results such as no related entry, no next action, or no operator explanation when those results are deterministic for the current scope.
- **FR-167-013**: Request-local reuse MUST NOT change operator-visible semantics, labels, readiness states, navigation destinations, or next-action text on covered surfaces.
- **FR-167-014**: Request-local reuse MUST NOT cross workspace boundaries, tenant boundaries, request boundaries, or authorization contexts.
- **FR-167-015**: If a derived result depends on capability or visibility context, that context MUST be part of the reuse boundary or the derivation MUST bypass request-local reuse.
- **FR-167-016**: Covered mutating action flows MUST define an explicit freshness rule so post-mutation truth, guidance, or navigation is recomputed when the underlying business state changes within the same request.
- **FR-167-017**: The feature MUST forbid new ad hoc page-local static caches for covered families once the shared contract exists, unless an explicit, bounded exemption is documented.
- **FR-167-018**: The feature MUST include focused regression coverage proving one full derivation per request for representative `ArtifactTruthPresenter`, `OperationUxPresenter`, and `RelatedNavigationResolver` paths.
- **FR-167-019**: The feature MUST include focused regression coverage proving that request-local reuse cannot leak derived state across tenant, workspace, or entitlement boundaries.
- **FR-167-020**: The feature MUST include at least one mutation-path regression proving that covered post-action state is freshly determined when business truth changes within the same request.
- **FR-167-021**: The feature MUST provide a documented adoption path and an automated guardrail for future presenter and resolver families so new heavy derived-state surfaces do not bypass the contract by default.
- **FR-167-022**: The feature MUST explicitly exclude cross-request caching, persistent cache stores, new persisted summaries, and business-semantic changes to artifact truth, operation guidance, or related navigation.

## UI Action Matrix *(mandatory when Filament is changed)*

| Surface | Location | Header Actions | Inspect Affordance (List/Table) | Row Actions (max 2 visible) | Bulk Actions (grouped) | Empty-State CTA(s) | View Header Actions | Create/Edit Save+Cancel | Audit log? | Notes / Exemptions |
|---|---|---|---|---|---|---|---|---|---|---|
| Baseline snapshots | `app/Filament/Resources/BaselineSnapshotResource.php` and related view page | Existing actions unchanged | Existing clickable inspection remains primary | Existing row actions unchanged | Existing bulk actions unchanged | Existing empty state unchanged | Existing view actions unchanged | N/A | Existing audit model unchanged | This spec changes only how truth and related context are reused during one request |
| Evidence snapshots and evidence overview | `app/Filament/Resources/EvidenceSnapshotResource.php` and `app/Filament/Pages/Monitoring/EvidenceOverview.php` | Existing actions unchanged | Existing clickable inspection remains primary | Existing row actions unchanged | Existing bulk actions unchanged | Existing empty states unchanged | Existing view actions unchanged | N/A | Existing audit model unchanged | No action inventory change; only repeated truth derivation is consolidated |
| Tenant reviews and review register | `app/Filament/Resources/TenantReviewResource.php` and `app/Filament/Pages/Reviews/ReviewRegister.php` | Existing actions unchanged | Existing clickable inspection remains primary | Existing row actions unchanged | Existing bulk actions unchanged | Existing empty states unchanged | Existing view actions unchanged | N/A | Existing audit model unchanged | Review truth, readiness, and next-action reads should reuse one request-local result per record |
| Review packs | `app/Filament/Resources/ReviewPackResource.php` | Existing actions unchanged | Existing clickable inspection remains primary | Existing row actions unchanged | Existing bulk actions unchanged | Existing empty states unchanged | Existing view actions unchanged | N/A | Existing audit model unchanged | No new actions, semantics, or audit events are added |
| Operation runs and related-context pages | `app/Filament/Resources/OperationRunResource.php`, `app/Filament/Pages/Operations/TenantlessOperationRunViewer.php`, and covered related-context pages using `RelatedNavigationResolver` | Existing actions unchanged | Existing inspection patterns unchanged | Existing retry or navigation actions unchanged | Existing bulk actions unchanged | Existing empty states unchanged | Existing detail actions unchanged | N/A | Existing audit model unchanged | The purpose is request-local reuse of guidance and related navigation, not action redesign |

### Key Entities *(include if feature involves data)*

- **Request-Scoped Derived State Contract**: The explicit per-request reuse boundary for deterministic presenter and resolver outputs.
- **Derived State Key**: The stable identifier that combines derivation family, record identity, variant, and any scope-sensitive inputs needed to return the correct result.
- **Row-Safe Surface State**: The once-derived per-record state reused by multiple list-row consumers in one request.
- **Freshness Boundary**: The point at which a mutating action must recompute truth instead of reusing a previously derived result from the same request.
- **Derived State Family**: One covered presenter or resolver family, such as artifact truth, operation UX guidance, or related navigation.

## Success Criteria *(mandatory)*

### Measurable Outcomes

- **SC-167-001**: On the first implementation slice, 100% of covered repeated-read examples derive a deterministic record-scope result at most once per request for the covered family.
- **SC-167-002**: At least three currently affected surface families adopt the same request-scoped contract without changing the operator-visible meaning of their labels, explanations, or related destinations.
- **SC-167-003**: In focused regression coverage, 100% of covered rows and detail pages keep badge properties, descriptions, next-action text, and related-navigation outputs internally consistent when those values depend on the same derived-state family.
- **SC-167-004**: In mutation-path regression coverage, 100% of covered post-action flows show fresh post-mutation truth or navigation when the underlying business state changes inside the request.
- **SC-167-005**: In focused scope-safety regression coverage, 100% of covered canonical and tenant-context examples prevent derived-state reuse across unauthorized workspace, tenant, or entitlement boundaries.
- **SC-167-006**: The first implementation slice ships without introducing any new persisted cache, any new business-semantic state family, or any visible operator-language regression on the covered surfaces.
- **SC-167-007**: An automated derived-state adoption guard fails with actionable output when a covered consumer introduces an ad hoc local cache, bypasses the supported access patterns, or adopts the shared store without explicit scope and freshness declaration.

## Assumptions

- Existing `ArtifactTruthPresenter`, `OperationUxPresenter`, and `RelatedNavigationResolver` outputs are already semantically correct for the covered first slice; the problem is repeated request-time computation, not incorrect business meaning.
- Request scope is defined by one HTTP or Livewire request and is sufficiently narrow to avoid cross-request staleness while still removing repeated deterministic work.
- Some surfaces already contain local request-like caches, and the long-term direction is to converge those local caches into one explicit contract instead of allowing multiple hidden patterns to coexist.
- The first implementation slice should reuse existing presenter and resolver families rather than replacing them with a broader semantic or caching platform.

## Dependencies

- Spec 131 - Cross-Resource Navigation
- Spec 144 - Canonical Operation Viewer Context Decoupling
- Spec 156 - Operator Outcome Taxonomy and Cross-Domain State Separation
- Spec 157 - Operator Reason Code Translation and Humanization Contract
- Spec 158 - Governance Artifact Truthful Outcomes and Fidelity Semantics
- Existing baseline snapshot, evidence snapshot, tenant review, review-pack, review register, evidence overview, and operation-run surfaces already in the admin panel

## Non-Goals

- Introducing cross-request caching, Redis, or any persistent cache store
- Redesigning the underlying database query layer or treating this spec as a general query-optimization initiative
- Changing the business semantics of artifact truth, operation guidance, or related navigation
- Replacing existing presenter or resolver families with a new taxonomy or UI framework
- Performing the tenant-governance aggregate consolidation tracked by the adjacent aggregate candidate
- Performing the workspace access-context hardening tracked by the adjacent workspace-context candidate

## Final Direction

This spec establishes one explicit request-scoped reuse contract for deterministic derived state that is already being asked for repeatedly across artifact, review, navigation, and operation surfaces. It is intentionally narrow: no new persistence, no new meaning system, and no speculative cache platform. The first slice should prove that Artifact Truth, Operation UX, and Related Navigation can share one request-local boundary, that mutating flows keep their freshness guarantees, and that future heavy surfaces have a clear adoption path instead of inventing one more local cache.