From 7c7dab3898e8a48413473fca22d8105ee2e685a4 Mon Sep 17 00:00:00 2001 From: jarvis Date: Tue, 18 Aug 2026 05:56:58 +0000 Subject: [PATCH] feat(ri-050): RI-5-001 typed freshness states and stale-safe Mission Control surfaces (#1275) (#1300) --- .../freshness/freshness-notices.tsx | 110 ++++++ apps/web/src/lib/freshness/model.spec.ts | 324 +++++++++++++++ apps/web/src/lib/freshness/model.ts | 261 ++++++++++++ .../src/lib/freshness/snapshot-cache.spec.ts | 197 ++++++++++ apps/web/src/lib/freshness/snapshot-cache.ts | 154 ++++++++ .../freshness/use-fresh-collection.spec.tsx | 372 ++++++++++++++++++ .../src/lib/freshness/use-fresh-collection.ts | 281 +++++++++++++ apps/web/src/lib/freshness/validators.spec.ts | 103 +++++ apps/web/src/lib/freshness/validators.ts | 135 +++++++ .../web/src/spa/pages/project-detail.spec.tsx | 198 ++++++++-- apps/web/src/spa/pages/project-detail.tsx | 293 +++++++++----- apps/web/src/spa/pages/projects.spec.tsx | 72 +++- apps/web/src/spa/pages/projects.tsx | 66 ++-- apps/web/src/spa/pages/tasks.spec.tsx | 88 ++++- apps/web/src/spa/pages/tasks.tsx | 59 ++- 15 files changed, 2525 insertions(+), 188 deletions(-) create mode 100644 apps/web/src/components/freshness/freshness-notices.tsx create mode 100644 apps/web/src/lib/freshness/model.spec.ts create mode 100644 apps/web/src/lib/freshness/model.ts create mode 100644 apps/web/src/lib/freshness/snapshot-cache.spec.ts create mode 100644 apps/web/src/lib/freshness/snapshot-cache.ts create mode 100644 apps/web/src/lib/freshness/use-fresh-collection.spec.tsx create mode 100644 apps/web/src/lib/freshness/use-fresh-collection.ts create mode 100644 apps/web/src/lib/freshness/validators.spec.ts create mode 100644 apps/web/src/lib/freshness/validators.ts diff --git a/apps/web/src/components/freshness/freshness-notices.tsx b/apps/web/src/components/freshness/freshness-notices.tsx new file mode 100644 index 00000000..eac24868 --- /dev/null +++ b/apps/web/src/components/freshness/freshness-notices.tsx @@ -0,0 +1,110 @@ +'use client'; + +import type { ReactElement } from 'react'; +import { formatAge, type FreshnessLabel } from '@/lib/freshness/model'; + +/** + * Rendering rules for non-current freshness states (RI-5-001). + * + * - `unavailable` renders an explicit failure panel — never an empty + * healthy collection. + * - `stale` may render last-known data, but only under a visible label + * carrying source identity, snapshot version, and age. + * - `partial` renders the verified parts plus an explicit list of what is + * missing. + */ + +interface RetryableNoticeProps { + readonly onRetry?: () => void; + readonly retryLabel?: string; +} + +function RetryButton({ onRetry, retryLabel }: RetryableNoticeProps): ReactElement | null { + if (!onRetry) return null; + return ( + + ); +} + +export interface UnavailableDataNoticeProps extends RetryableNoticeProps { + /** What is unavailable, e.g. "Tasks". */ + readonly title: string; + /** Optional underlying failure detail (network message, invalidation reason). */ + readonly detail?: string | null; +} + +/** Explicit `unavailable` state. Never renders as an empty healthy collection. */ +export function UnavailableDataNotice({ + title, + detail, + onRetry, + retryLabel, +}: UnavailableDataNoticeProps): ReactElement { + return ( +
+

{title} are unavailable

+

+ This is not an empty result — the data could not be verified from the gateway. + {detail ? ` ${detail}` : ''} +

+ +
+ ); +} + +export interface StaleDataNoticeProps extends RetryableNoticeProps { + /** Provenance of the last-known snapshot being displayed. */ + readonly label: FreshnessLabel; +} + +/** + * Situational-awareness banner for `stale` data: last-known data may render, + * but visibly labeled with source identity, snapshot version, and age. + */ +export function StaleDataNotice({ + label, + onRetry, + retryLabel, +}: StaleDataNoticeProps): ReactElement { + return ( +
+

Showing last-known data — it may be out of date

+

+ Source {label.source} · snapshot v{label.version} · fetched{' '} + {formatAge(label.fetchedAt, Date.now())}. Verdicts derived from this data are unknown and + changes are disabled until it is revalidated. +

+ +
+ ); +} + +export interface PartialDataNoticeProps extends RetryableNoticeProps { + /** Display names of the sections whose collections are unavailable. */ + readonly missing: readonly string[]; +} + +/** `partial` surface banner: verified parts render, missing parts are explicit. */ +export function PartialDataNotice({ + missing, + onRetry, + retryLabel, +}: PartialDataNoticeProps): ReactElement { + return ( +
+

Some data could not be loaded

+

+ {missing.join(', ')} {missing.length === 1 ? 'is' : 'are'} unavailable — sections below show + an explicit unavailable state instead of an empty list. Derived verdicts remain unknown + until every collection is revalidated. +

+ +
+ ); +} diff --git a/apps/web/src/lib/freshness/model.spec.ts b/apps/web/src/lib/freshness/model.spec.ts new file mode 100644 index 00000000..9ccf361c --- /dev/null +++ b/apps/web/src/lib/freshness/model.spec.ts @@ -0,0 +1,324 @@ +import { describe, expect, it } from 'vitest'; +import type { Task } from '@/lib/types'; +import { + acceptSnapshot, + assertMutable, + canMutate, + combineFreshness, + computeDigest, + computeFreshness, + DEFAULT_FRESHNESS_POLICY, + formatAge, + type FreshSnapshot, + invalidationReasonLabels, + StaleMutationError, + UNKNOWN_VERDICT, + verdictValue, +} from './model'; +import { validateProjectCollection, validateTaskCollection } from './validators'; + +const NOW = 1_800_000_000_000; + +const policy = { ...DEFAULT_FRESHNESS_POLICY, staleAfterMs: 60_000 }; + +const taskPayload: Task[] = [ + { + id: 'task-1', + title: 'T1', + description: null, + status: 'not-started', + priority: 'high', + projectId: 'project-1', + missionId: null, + assignee: null, + tags: null, + dueDate: null, + metadata: null, + createdAt: '2026-08-01T00:00:00.000Z', + updatedAt: '2026-08-01T00:00:00.000Z', + }, +]; + +function acceptedTaskSnapshot( + overrides: Partial> = {}, +): FreshSnapshot { + const result = acceptSnapshot({ + value: taskPayload, + validate: validateTaskCollection, + previous: null, + policy, + source: 'gateway:/api/tasks', + now: NOW, + }); + if (result.outcome !== 'accepted') { + throw new Error(`fixture setup failed: ${result.reason}`); + } + return { ...result.snapshot, ...overrides }; +} + +describe('computeFreshness', () => { + it('treats a missing snapshot as unavailable, never as an empty healthy collection', () => { + expect(computeFreshness({ snapshot: null, policy, now: NOW })).toBe('unavailable'); + }); + + it('returns current for a fresh verified snapshot regardless of data emptiness', () => { + const empty = acceptSnapshot({ + value: [], + validate: validateTaskCollection, + previous: null, + policy, + source: 'gateway:/api/tasks', + now: NOW, + }); + if (empty.outcome !== 'accepted') throw new Error('expected acceptance'); + expect(computeFreshness({ snapshot: empty.snapshot, policy, now: NOW })).toBe('current'); + }); + + it('degrades to stale once the snapshot ages past staleAfterMs', () => { + const snapshot = acceptedTaskSnapshot(); + expect(computeFreshness({ snapshot, policy, now: NOW + 60_001 })).toBe('stale'); + expect(computeFreshness({ snapshot, policy, now: NOW + 59_999 })).toBe('current'); + }); + + it('degrades to stale when the latest revalidation failed', () => { + const snapshot = acceptedTaskSnapshot(); + expect(computeFreshness({ snapshot, policy, now: NOW, degraded: true })).toBe('stale'); + }); +}); + +describe('mutation guard', () => { + it('permits mutations only on current data', () => { + expect(canMutate('current')).toBe(true); + for (const state of ['stale', 'partial', 'unknown', 'unavailable'] as const) { + expect(canMutate(state)).toBe(false); + } + }); + + it('refuses mutations on non-current data via assertMutable', () => { + expect(() => assertMutable('current')).not.toThrow(); + for (const state of ['stale', 'partial', 'unknown', 'unavailable'] as const) { + let thrown: unknown; + try { + assertMutable(state); + } catch (caught) { + thrown = caught; + } + expect(thrown).toBeInstanceOf(StaleMutationError); + expect(thrown).toBeInstanceOf(Error); + if (thrown instanceof StaleMutationError) { + expect(thrown.name).toBe('StaleMutationError'); + expect(thrown.freshness).toBe(state); + expect(thrown.message).toContain(state); + expect(thrown.message).toContain('revalidat'); + } + } + }); +}); + +describe('acceptSnapshot', () => { + it('accepts a valid payload with provenance', () => { + const result = acceptSnapshot({ + value: taskPayload, + validate: validateTaskCollection, + previous: null, + policy, + source: 'gateway:/api/tasks', + now: NOW, + }); + expect(result.outcome).toBe('accepted'); + if (result.outcome !== 'accepted') return; + expect(result.snapshot.source).toBe('gateway:/api/tasks'); + expect(result.snapshot.version).toBe(1); + expect(result.snapshot.fetchedAt).toBe(NOW); + expect(result.snapshot.data).toEqual(taskPayload); + }); + + it('invalidates a schema-mismatched payload instead of rendering it', () => { + const result = acceptSnapshot({ + value: { not: 'an array' }, + validate: validateTaskCollection, + previous: acceptedTaskSnapshot(), + policy, + source: 'gateway:/api/tasks', + now: NOW, + }); + expect(result).toEqual({ outcome: 'invalidated', reason: 'schema-mismatch' }); + expect(invalidationReasonLabels['schema-mismatch']).toContain('schema'); + }); + + it('invalidates cross-workspace payloads', () => { + const userOne = acceptSnapshot({ + value: [ + { + id: 'p1', + name: 'P1', + description: null, + status: 'active', + userId: 'user-1', + metadata: null, + createdAt: '2026-08-01T00:00:00.000Z', + updatedAt: '2026-08-01T00:00:00.000Z', + }, + ], + validate: validateProjectCollection, + previous: null, + policy, + source: 'gateway:/api/projects', + now: NOW, + }); + if (userOne.outcome !== 'accepted') throw new Error('expected acceptance'); + + const switched = acceptSnapshot({ + value: [ + { + id: 'p9', + name: 'P9', + description: null, + status: 'active', + userId: 'user-2', + metadata: null, + createdAt: '2026-08-01T00:00:00.000Z', + updatedAt: '2026-08-01T00:00:00.000Z', + }, + ], + validate: validateProjectCollection, + previous: userOne.snapshot, + policy, + source: 'gateway:/api/projects', + now: NOW, + }); + expect(switched).toEqual({ outcome: 'invalidated', reason: 'cross-workspace' }); + }); + + it('keeps the previous workspace for collections with no intrinsic identity', () => { + const userOne = acceptSnapshot({ + value: [ + { + id: 'p1', + name: 'P1', + description: null, + status: 'active', + userId: 'user-1', + metadata: null, + createdAt: '2026-08-01T00:00:00.000Z', + updatedAt: '2026-08-01T00:00:00.000Z', + }, + ], + validate: validateProjectCollection, + previous: null, + policy, + source: 'gateway:/api/projects', + now: NOW, + }); + if (userOne.outcome !== 'accepted') throw new Error('expected acceptance'); + + // Empty list after the user deleted every project: no identity to check, + // so the verified scope is retained and the empty state stays healthy. + const emptied = acceptSnapshot({ + value: [], + validate: validateProjectCollection, + previous: userOne.snapshot, + policy, + source: 'gateway:/api/projects', + now: NOW, + }); + expect(emptied.outcome).toBe('accepted'); + if (emptied.outcome === 'accepted') { + expect(emptied.snapshot.data).toEqual([]); + expect(emptied.snapshot.workspace).toBe('user-1'); + } + }); + + it('invalidates version regressions', () => { + const previous = acceptedTaskSnapshot({ version: 7 }); + const regressed = acceptSnapshot({ + value: taskPayload, + validate: validateTaskCollection, + previous, + policy, + source: 'gateway:/api/tasks', + now: NOW, + incomingVersion: 3, + }); + expect(regressed).toEqual({ outcome: 'invalidated', reason: 'version-regression' }); + + const newerSchema = acceptedTaskSnapshot({ schemaVersion: 4 }); + const downgradedClient = acceptSnapshot({ + value: taskPayload, + validate: validateTaskCollection, + previous: newerSchema, + policy: { ...policy, schemaVersion: 2 }, + source: 'gateway:/api/tasks', + now: NOW, + }); + expect(downgradedClient).toEqual({ outcome: 'invalidated', reason: 'version-regression' }); + }); + + it('increments the version monotonically across accepted snapshots', () => { + const first = acceptedTaskSnapshot(); + const second = acceptSnapshot({ + value: taskPayload, + validate: validateTaskCollection, + previous: first, + policy, + source: 'gateway:/api/tasks', + now: NOW, + }); + expect(second.outcome).toBe('accepted'); + if (second.outcome === 'accepted') { + expect(second.snapshot.version).toBe(first.version + 1); + } + }); +}); + +describe('combineFreshness', () => { + it('gates the surface on the primary collection', () => { + expect(combineFreshness('unavailable', ['current'])).toBe('unavailable'); + expect(combineFreshness('unknown', ['current'])).toBe('unknown'); + expect(combineFreshness('current', [])).toBe('current'); + }); + + it('degrades to partial when a secondary is unavailable', () => { + expect(combineFreshness('current', ['current', 'unavailable'])).toBe('partial'); + }); + + it('degrades to unknown while a secondary is still loading', () => { + expect(combineFreshness('current', ['unknown'])).toBe('unknown'); + }); + + it('degrades to stale when any collection is stale', () => { + expect(combineFreshness('current', ['stale'])).toBe('stale'); + expect(combineFreshness('stale', ['current'])).toBe('stale'); + }); + + it('propagates partial secondaries', () => { + expect(combineFreshness('current', ['partial'])).toBe('partial'); + }); +}); + +describe('computeDigest', () => { + it('is stable across key order and changes with data', () => { + const a = computeDigest({ x: 1, y: [1, 2] }); + const b = computeDigest({ y: [1, 2], x: 1 }); + expect(a).toBe(b); + expect(computeDigest({ x: 1, y: [1, 3] })).not.toBe(a); + }); +}); + +describe('verdictValue', () => { + it('returns the value only for verified inputs', () => { + expect(verdictValue(true, '5')).toBe('5'); + expect(verdictValue(false, '5')).toBe(UNKNOWN_VERDICT); + expect(verdictValue(false, '5')).not.toBe('5'); + }); +}); + +describe('formatAge', () => { + it('labels age in human terms', () => { + expect(formatAge(NOW, NOW)).toBe('just now'); + expect(formatAge(NOW, NOW + 15_000)).toBe('under a minute ago'); + expect(formatAge(NOW, NOW + 120_000)).toBe('2m ago'); + expect(formatAge(NOW, NOW + 3 * 3_600_000)).toBe('3h ago'); + expect(formatAge(NOW, NOW + 2 * 86_400_000)).toBe('2d ago'); + }); +}); diff --git a/apps/web/src/lib/freshness/model.ts b/apps/web/src/lib/freshness/model.ts new file mode 100644 index 00000000..a83090f3 --- /dev/null +++ b/apps/web/src/lib/freshness/model.ts @@ -0,0 +1,261 @@ +/** + * Typed freshness model for gateway-fetched collections (RI-5-001). + * + * A failed or stale fetch must never be indistinguishable from an empty + * healthy collection. Every fetched surface carries an explicit freshness + * state, a verified snapshot identity (source, workspace, version, age), and + * a mutation guard that refuses state-changing operations unless the data is + * verified current. + */ + +/** Freshness states for fetched data. Never inferred from emptiness. */ +export type FreshnessState = 'current' | 'stale' | 'partial' | 'unknown' | 'unavailable'; + +/** + * Reasons a snapshot is invalidated. An invalidated snapshot is treated as + * unavailable and is never rendered as current. + */ +export type InvalidationReason = + | 'cache-corruption' + | 'cross-workspace' + | 'schema-mismatch' + | 'version-regression'; + +/** Human-readable labels for invalidation reasons (UI + error messages). */ +export const invalidationReasonLabels: Record = { + 'cache-corruption': 'cached snapshot failed integrity checks', + 'cross-workspace': 'data belongs to a different workspace', + 'schema-mismatch': 'response did not match the expected schema', + 'version-regression': 'snapshot version regressed below the accepted version', +}; + +/** A verified snapshot of fetched data with full provenance. */ +export interface FreshSnapshot { + readonly data: T; + /** Source identity of the fetch, e.g. `gateway:/api/tasks`. */ + readonly source: string; + /** Workspace scope the data belongs to. */ + readonly workspace: string; + /** Monotonic snapshot sequence number for this surface. */ + readonly version: number; + /** Schema version of the validator that accepted this snapshot. */ + readonly schemaVersion: number; + /** Epoch ms at which the data was verified. */ + readonly fetchedAt: number; + /** Integrity digest of `data`, used to detect cache corruption. */ + readonly digest: string; +} + +/** Provenance label rendered next to last-known data. */ +export interface FreshnessLabel { + readonly source: string; + readonly version: number; + readonly fetchedAt: number; +} + +/** Policy governing freshness for a surface. */ +export interface FreshnessPolicy { + /** Active workspace scope. Snapshots from other scopes are invalidated. */ + readonly workspace: string; + /** Schema version of the current validator. */ + readonly schemaVersion: number; + /** Age after which a verified snapshot degrades from current to stale. */ + readonly staleAfterMs: number; +} + +export const DEFAULT_FRESHNESS_POLICY: FreshnessPolicy = { + workspace: 'default', + schemaVersion: 1, + staleAfterMs: 60_000, +}; + +/** Payload returned by a successful schema validation. */ +export interface FreshPayload { + readonly data: T; + /** + * Workspace identity extracted from the payload itself when the collection + * carries one (e.g. a uniform `userId` on projects). `null` when the + * collection has no intrinsic workspace identity. + */ + readonly workspace: string | null; +} + +/** Error thrown when a mutation is attempted on non-current data. */ +export class StaleMutationError extends Error { + readonly freshness: FreshnessState; + + constructor(freshness: FreshnessState) { + super(`Refused mutation on ${freshness} data: revalidation is required before mutating.`); + this.name = 'StaleMutationError'; + this.freshness = freshness; + } +} + +/** Stable JSON digest used for snapshot integrity checks. */ +export function computeDigest(value: unknown): string { + // FNV-1a 32-bit over the stable JSON serialization. This is an integrity + // check against corruption, not a cryptographic guarantee. + let hash = 0x811c9dc5; + for (const byte of stableStringify(value)) { + hash ^= byte.charCodeAt(0); + hash = Math.imul(hash, 0x01000193) >>> 0; + } + return hash.toString(16).padStart(8, '0'); +} + +function stableStringify(value: unknown): string { + return serialize(value); +} + +function serialize(value: unknown): string { + if (value === null || typeof value !== 'object') return JSON.stringify(value) ?? 'null'; + if (Array.isArray(value)) return `[${value.map(serialize).join(',')}]`; + const entries = Object.entries(value as Record) + .filter(([, item]) => item !== undefined) + .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0)) + .map(([key, item]) => `${JSON.stringify(key)}:${serialize(item)}`); + return `{${entries.join(',')}}`; +} + +export type AcceptSnapshotResult = + | { readonly outcome: 'accepted'; readonly snapshot: FreshSnapshot } + | { readonly outcome: 'invalidated'; readonly reason: InvalidationReason }; + +export interface AcceptSnapshotOptions { + /** Raw fetched value (untrusted JSON). */ + readonly value: unknown; + /** Schema validator; returns `null` when the value does not match. */ + readonly validate: (value: unknown) => FreshPayload | null; + /** Previously accepted snapshot for this surface, if any. */ + readonly previous: FreshSnapshot | null; + readonly policy: FreshnessPolicy; + readonly source: string; + /** + * Version carried by the incoming payload when the transport exposes one. + * Must not regress below the accepted snapshot's version. + */ + readonly incomingVersion?: number; + readonly now: number; +} + +/** + * Validate and accept a fetched value as a snapshot, or invalidate it. + * + * Invalidation rules (each treated as unavailable, never rendered current): + * - schema mismatch: the payload fails validation + * - cross-workspace: the payload's workspace differs from the verified one + * - version regression: payload/schema version is below the accepted one + */ +export function acceptSnapshot(options: AcceptSnapshotOptions): AcceptSnapshotResult { + const payload = options.validate(options.value); + if (payload === null) { + return { outcome: 'invalidated', reason: 'schema-mismatch' }; + } + + // Workspace identity: the payload's own scope wins; a collection with no + // intrinsic identity (e.g. an empty list after every project was deleted) + // keeps the previously verified scope rather than resetting to the policy + // default, so a legitimately empty response is not mistaken for a scope + // change. + const workspace = payload.workspace ?? options.previous?.workspace ?? options.policy.workspace; + if (options.previous !== null && options.previous.workspace !== workspace) { + return { outcome: 'invalidated', reason: 'cross-workspace' }; + } + if (options.previous !== null && options.policy.schemaVersion < options.previous.schemaVersion) { + return { outcome: 'invalidated', reason: 'version-regression' }; + } + if ( + options.incomingVersion !== undefined && + options.previous !== null && + options.incomingVersion < options.previous.version + ) { + return { outcome: 'invalidated', reason: 'version-regression' }; + } + + const snapshot: FreshSnapshot = { + data: payload.data, + source: options.source, + workspace, + version: options.incomingVersion ?? (options.previous?.version ?? 0) + 1, + schemaVersion: options.policy.schemaVersion, + fetchedAt: options.now, + digest: computeDigest(payload.data), + }; + return { outcome: 'accepted', snapshot }; +} + +export interface ComputeFreshnessOptions { + readonly snapshot: FreshSnapshot | null; + readonly policy: FreshnessPolicy; + readonly now: number; + /** + * True when the snapshot cannot be trusted as current regardless of age: + * the latest revalidation failed, or the snapshot was restored from cache + * and has not been verified by a fetch in this session. + */ + readonly degraded?: boolean; +} + +/** + * Compute the freshness state of a snapshot. A missing snapshot is + * `unavailable` (never "empty and healthy"); a degraded or aged snapshot is + * `stale` (situational awareness only). + */ +export function computeFreshness(options: ComputeFreshnessOptions): FreshnessState { + const { snapshot, policy, now, degraded = false } = options; + if (snapshot === null) return 'unavailable'; + if (degraded) return 'stale'; + if (now - snapshot.fetchedAt > policy.staleAfterMs) return 'stale'; + return 'current'; +} + +/** Only verified-current data may back a state-changing action. */ +export function canMutate(state: FreshnessState): boolean { + return state === 'current'; +} + +/** Defense in depth: reject the mutation call itself on non-current data. */ +export function assertMutable(state: FreshnessState): void { + if (!canMutate(state)) { + throw new StaleMutationError(state); + } +} + +/** + * Combine freshness across a multi-collection surface (primary + secondaries). + * The primary collection gates the surface: unknown while it loads, + * unavailable when it fails. Missing secondaries degrade the surface to + * `partial`; aged collections degrade it to `stale`. + */ +export function combineFreshness( + primary: FreshnessState, + secondaries: readonly FreshnessState[], +): FreshnessState { + if (primary === 'unavailable') return 'unavailable'; + if (primary === 'unknown') return 'unknown'; + if (secondaries.includes('unavailable')) return 'partial'; + if (secondaries.includes('unknown')) return 'unknown'; + if (secondaries.includes('stale') || primary === 'stale') return 'stale'; + if (secondaries.includes('partial')) return 'partial'; + return 'current'; +} + +/** Render-safe age label for snapshot provenance. */ +export function formatAge(fetchedAt: number, now: number): string { + const ageMs = Math.max(0, now - fetchedAt); + if (ageMs < 10_000) return 'just now'; + const minutes = Math.floor(ageMs / 60_000); + if (minutes < 1) return 'under a minute ago'; + if (minutes < 60) return `${minutes}m ago`; + const hours = Math.floor(minutes / 60); + if (hours < 24) return `${hours}h ago`; + const days = Math.floor(hours / 24); + return `${days}d ago`; +} + +/** Derived verdict placeholder for non-current inputs — never a green value. */ +export const UNKNOWN_VERDICT = '?'; + +export function verdictValue(verified: boolean, value: string): string { + return verified ? value : UNKNOWN_VERDICT; +} diff --git a/apps/web/src/lib/freshness/snapshot-cache.spec.ts b/apps/web/src/lib/freshness/snapshot-cache.spec.ts new file mode 100644 index 00000000..551905b2 --- /dev/null +++ b/apps/web/src/lib/freshness/snapshot-cache.spec.ts @@ -0,0 +1,197 @@ +import { afterEach, beforeEach, describe, expect, it } from 'vitest'; +import { acceptSnapshot, DEFAULT_FRESHNESS_POLICY } from './model'; +import { clearSnapshotCache, readSnapshotCache, writeSnapshotCache } from './snapshot-cache'; +import { validateProjectCollection, validateTaskCollection } from './validators'; +import { projectFixtures, taskFixtures } from '@/spa/pages/page-fixtures'; +import type { Project, Task } from '@/lib/types'; + +const KEY = 'test:tasks'; +const NOW = 1_800_000_000_000; +const policy = { ...DEFAULT_FRESHNESS_POLICY, staleAfterMs: 60_000 }; + +function storedTaskSnapshot() { + const result = acceptSnapshot({ + value: taskFixtures, + validate: validateTaskCollection, + previous: null, + policy, + source: 'gateway:/api/tasks', + now: NOW, + }); + if (result.outcome !== 'accepted') throw new Error('fixture setup failed'); + return result.snapshot; +} + +function storedProjectSnapshot() { + const result = acceptSnapshot({ + value: projectFixtures, + validate: validateProjectCollection, + previous: null, + policy, + source: 'gateway:/api/projects', + now: NOW, + }); + if (result.outcome !== 'accepted') throw new Error('fixture setup failed'); + return result.snapshot; +} + +function readTasks() { + return readSnapshotCache({ + key: KEY, + workspace: policy.workspace, + policy, + validate: validateTaskCollection, + }); +} + +/** Write an arbitrary value directly at the raw cache slot. */ +function writeRaw(key: string, value: unknown): void { + sessionStorage.setItem(`mosaic:freshness:v1:${key}`, JSON.stringify(value)); +} + +/** Parse and re-write the stored entry (for tampering with internals). */ +function tamperStored(key: string, mutate: (stored: T) => void): void { + const parsed = JSON.parse(sessionStorage.getItem(`mosaic:freshness:v1:${key}`) ?? '{}') as T; + mutate(parsed); + writeRaw(key, parsed); +} + +beforeEach(() => { + sessionStorage.clear(); +}); + +afterEach(() => { + sessionStorage.clear(); +}); + +describe('readSnapshotCache', () => { + it('misses when nothing is stored', () => { + expect(readTasks()).toEqual({ outcome: 'miss' }); + }); + + it('hits for a well-formed entry and preserves provenance', () => { + const snapshot = storedTaskSnapshot(); + writeSnapshotCache(KEY, snapshot); + + const result = readTasks(); + expect(result.outcome).toBe('hit'); + if (result.outcome === 'hit') { + expect(result.snapshot.data).toEqual(taskFixtures); + expect(result.snapshot.source).toBe('gateway:/api/tasks'); + expect(result.snapshot.version).toBe(snapshot.version); + expect(result.snapshot.fetchedAt).toBe(snapshot.fetchedAt); + expect(result.snapshot.workspace).toBe(snapshot.workspace); + } + }); + + it('invalidates unparsable entries as cache corruption', () => { + sessionStorage.setItem(`mosaic:freshness:v1:${KEY}`, '{not json'); + expect(readTasks()).toEqual({ outcome: 'invalidated', reason: 'cache-corruption' }); + }); + + it('invalidates structurally wrong entries as cache corruption', () => { + const malformed: unknown[] = [ + 'nested but not a snapshot', + { data: taskFixtures }, // missing provenance fields + { + data: taskFixtures, + source: 1, + workspace: 'w', + version: 1, + schemaVersion: 1, + fetchedAt: 1, + digest: 'x', + }, + null, + 17, + ]; + for (const entry of malformed) { + writeRaw(KEY, entry); + expect(readTasks()).toEqual({ outcome: 'invalidated', reason: 'cache-corruption' }); + } + }); + + it('invalidates digest mismatches as cache corruption (tampered data)', () => { + writeSnapshotCache(KEY, storedTaskSnapshot()); + tamperStored<{ data: Task[] }>(KEY, (stored) => { + stored.data = [...stored.data, { ...stored.data[0]!, id: 'injected-task' }]; + }); + expect(readTasks()).toEqual({ outcome: 'invalidated', reason: 'cache-corruption' }); + }); + + it('invalidates entries scoped to another workspace', () => { + const snapshot = storedTaskSnapshot(); + writeSnapshotCache(KEY, { ...snapshot, workspace: 'someone-else' }); + expect(readTasks()).toEqual({ outcome: 'invalidated', reason: 'cross-workspace' }); + }); + + it('invalidates entries written by a newer schema as a version regression', () => { + const snapshot = storedTaskSnapshot(); + writeSnapshotCache(KEY, { ...snapshot, schemaVersion: policy.schemaVersion + 1 }); + expect(readTasks()).toEqual({ outcome: 'invalidated', reason: 'version-regression' }); + }); + + it('invalidates entries whose data no longer validates (schema mismatch)', () => { + writeSnapshotCache(KEY, storedTaskSnapshot()); + tamperStored<{ data: unknown }>(KEY, (stored) => { + stored.data = { malformed: true }; + }); + expect(readTasks()).toEqual({ outcome: 'invalidated', reason: 'schema-mismatch' }); + }); + + it('never reports a corrupted raw entry as a hit (negative control)', () => { + for (const raw of ['{oops', 'null', '"string"', '[]', '12']) { + sessionStorage.setItem(`mosaic:freshness:v1:${KEY}`, raw); + const result = readTasks(); + expect(result.outcome).not.toBe('hit'); + expect(result.outcome).toBe('invalidated'); + } + }); + + it('scopes project collections by their workspace identity', () => { + const snapshot = storedProjectSnapshot(); + writeSnapshotCache('test:projects', snapshot); + + const sameScope = readSnapshotCache({ + key: 'test:projects', + workspace: 'user-1', + policy, + validate: validateProjectCollection, + }); + expect(sameScope.outcome).toBe('hit'); + + const foreignScope = readSnapshotCache({ + key: 'test:projects', + workspace: 'user-2', + policy, + validate: validateProjectCollection, + }); + expect(foreignScope).toEqual({ outcome: 'invalidated', reason: 'cross-workspace' }); + }); +}); + +describe('writeSnapshotCache round-trip', () => { + it('round-trips an accepted project snapshot', () => { + const snapshot = storedProjectSnapshot(); + writeSnapshotCache('test:projects', snapshot); + const result = readSnapshotCache({ + key: 'test:projects', + workspace: snapshot.workspace, + policy, + validate: validateProjectCollection, + }); + expect(result.outcome).toBe('hit'); + if (result.outcome === 'hit') { + expect(result.snapshot.data).toEqual(projectFixtures as Project[]); + } + }); +}); + +describe('clearSnapshotCache', () => { + it('drops the entry so the next read misses', () => { + writeSnapshotCache(KEY, storedTaskSnapshot()); + expect(readTasks().outcome).toBe('hit'); + clearSnapshotCache(KEY); + expect(readTasks()).toEqual({ outcome: 'miss' }); + }); +}); diff --git a/apps/web/src/lib/freshness/snapshot-cache.ts b/apps/web/src/lib/freshness/snapshot-cache.ts new file mode 100644 index 00000000..63dbd756 --- /dev/null +++ b/apps/web/src/lib/freshness/snapshot-cache.ts @@ -0,0 +1,154 @@ +import { + computeDigest, + type FreshPayload, + type FreshSnapshot, + type FreshnessPolicy, + type InvalidationReason, +} from './model'; + +/** + * Session-scoped last-known snapshot cache (RI-5-001). + * + * Restored snapshots are situational awareness only: they surface as `stale` + * until a fetch re-verifies them. A cache entry that is corrupted, belongs to + * another workspace, was written by a newer schema, or no longer validates is + * invalidated (treated as unavailable, never rendered as current). + */ + +const CACHE_PREFIX = 'mosaic:freshness:v1'; + +interface StoredSnapshot { + data: unknown; + source: string; + workspace: string; + version: number; + schemaVersion: number; + fetchedAt: number; + digest: string; +} + +export type SnapshotCacheRead = + | { readonly outcome: 'hit'; readonly snapshot: FreshSnapshot } + | { readonly outcome: 'miss' } + | { readonly outcome: 'invalidated'; readonly reason: InvalidationReason }; + +export interface ReadSnapshotCacheOptions { + readonly key: string; + readonly workspace: string; + readonly policy: FreshnessPolicy; + readonly validate: (value: unknown) => FreshPayload | null; +} + +function cacheKey(key: string): string { + return `${CACHE_PREFIX}:${key}`; +} + +function isStoredSnapshot(value: unknown): value is StoredSnapshot { + if (typeof value !== 'object' || value === null) return false; + const candidate = value as Record; + return ( + typeof candidate['data'] === 'object' && + candidate['data'] !== null && + typeof candidate['source'] === 'string' && + typeof candidate['workspace'] === 'string' && + typeof candidate['version'] === 'number' && + typeof candidate['schemaVersion'] === 'number' && + typeof candidate['fetchedAt'] === 'number' && + typeof candidate['digest'] === 'string' + ); +} + +function getStorage(): Storage | null { + try { + return globalThis.sessionStorage ?? null; + } catch { + return null; + } +} + +/** + * Restore a cached snapshot under the active workspace scope. Every failure + * mode maps to an explicit invalidation reason or a miss — never to data + * that renders as current. + */ +export function readSnapshotCache(options: ReadSnapshotCacheOptions): SnapshotCacheRead { + const storage = getStorage(); + if (storage === null) return { outcome: 'miss' }; + + let raw: string | null; + try { + raw = storage.getItem(cacheKey(options.key)); + } catch { + return { outcome: 'miss' }; + } + if (raw === null) return { outcome: 'miss' }; + + let parsed: unknown; + try { + parsed = JSON.parse(raw); + } catch { + return { outcome: 'invalidated', reason: 'cache-corruption' }; + } + if (!isStoredSnapshot(parsed)) { + return { outcome: 'invalidated', reason: 'cache-corruption' }; + } + if (parsed.workspace !== options.workspace) { + return { outcome: 'invalidated', reason: 'cross-workspace' }; + } + if (parsed.schemaVersion > options.policy.schemaVersion) { + // Written by a newer build than the running client: version regression. + return { outcome: 'invalidated', reason: 'version-regression' }; + } + + const payload = options.validate(parsed.data); + if (payload === null) { + return { outcome: 'invalidated', reason: 'schema-mismatch' }; + } + if (computeDigest(payload.data) !== parsed.digest) { + return { outcome: 'invalidated', reason: 'cache-corruption' }; + } + + return { + outcome: 'hit', + snapshot: { + data: payload.data, + source: parsed.source, + workspace: parsed.workspace, + version: parsed.version, + schemaVersion: parsed.schemaVersion, + fetchedAt: parsed.fetchedAt, + digest: parsed.digest, + }, + }; +} + +/** Persist a verified snapshot. Failures are non-fatal (cache is best-effort). */ +export function writeSnapshotCache(key: string, snapshot: FreshSnapshot): void { + const storage = getStorage(); + if (storage === null) return; + const stored: StoredSnapshot = { + data: snapshot.data, + source: snapshot.source, + workspace: snapshot.workspace, + version: snapshot.version, + schemaVersion: snapshot.schemaVersion, + fetchedAt: snapshot.fetchedAt, + digest: snapshot.digest, + }; + try { + storage.setItem(cacheKey(key), JSON.stringify(stored)); + } catch { + // Quota or serialization failures simply skip caching. + } +} + +/** Drop a cached snapshot (used when a surface invalidates its cache entry). */ +export function clearSnapshotCache(key: string): void { + const storage = getStorage(); + if (storage === null) return; + try { + storage.removeItem(cacheKey(key)); + } catch { + // Ignorable: a wedged storage entry is detected as corruption on read. + } +} diff --git a/apps/web/src/lib/freshness/use-fresh-collection.spec.tsx b/apps/web/src/lib/freshness/use-fresh-collection.spec.tsx new file mode 100644 index 00000000..bd218c94 --- /dev/null +++ b/apps/web/src/lib/freshness/use-fresh-collection.spec.tsx @@ -0,0 +1,372 @@ +import { act } from 'react'; +import { createRoot, type Root } from 'react-dom/client'; +import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from 'vitest'; +import type { Task } from '@/lib/types'; +import { acceptSnapshot, StaleMutationError, DEFAULT_FRESHNESS_POLICY } from './model'; +import type { FreshnessFailure } from './use-fresh-collection'; +import { + describeFailure, + useFreshCollection, + type FreshCollection, + type UseFreshCollectionOptions, +} from './use-fresh-collection'; +import { validateProjectCollection, validateTaskCollection } from './validators'; +import { projectFixtures, taskFixtures } from '@/spa/pages/page-fixtures'; + +/** + * Failure-matrix coverage for the freshness seam (RI-5-001): network failure, + * auth failure, malformed response, cache corruption, stale age, schema + * mismatch, cross-workspace, recovery, and stale-action rejection — with + * negative controls proving no case yields current data or an enabled + * mutation. + */ + +const NOW = 1_800_000_000_000; + +interface Deferred { + promise: Promise; + resolve: (value: T) => void; + reject: (reason?: unknown) => void; +} + +function createDeferred(): Deferred { + let resolve!: (value: T) => void; + let reject!: (reason?: unknown) => void; + const promise = new Promise((res, rej) => { + resolve = res; + reject = rej; + }); + return { promise, resolve, reject }; +} + +let root: Root | null = null; +let container: HTMLDivElement; +let latest: FreshCollection | null = null; + +function Probe({ + options, +}: { + options: UseFreshCollectionOptions; +}): React.ReactElement | null { + latest = useFreshCollection(options); + return null; +} + +beforeAll(() => { + Object.defineProperty(globalThis, 'IS_REACT_ACT_ENVIRONMENT', { + configurable: true, + value: true, + }); +}); + +beforeEach(() => { + sessionStorage.clear(); +}); + +afterEach(async () => { + await act(async () => { + root?.unmount(); + }); + document.body.replaceChildren(); + root = null; + latest = null; + sessionStorage.clear(); + vi.restoreAllMocks(); +}); + +async function renderCollection( + options: UseFreshCollectionOptions, +): Promise> { + container = document.createElement('div'); + document.body.append(container); + root = createRoot(container); + await act(async () => { + root?.render(); + }); + if (latest === null) throw new Error('hook did not run'); + return latest; +} + +function taskOptions( + overrides: Partial> = {}, +): UseFreshCollectionOptions { + return { + source: 'gateway:/api/tasks', + fetcher: () => Promise.resolve(taskFixtures), + validate: validateTaskCollection, + cacheKey: 'tasks', + clock: () => NOW, + ...overrides, + }; +} + +function authError(statusCode: number): Error & { statusCode: number } { + return Object.assign(new Error(`Request failed with ${statusCode}`), { statusCode }); +} + +function seedCache(key: string): number { + const result = acceptSnapshot({ + value: taskFixtures, + validate: validateTaskCollection, + previous: null, + policy: DEFAULT_FRESHNESS_POLICY, + source: 'gateway:/api/tasks', + now: NOW, + }); + if (result.outcome !== 'accepted') throw new Error('fixture setup failed'); + sessionStorage.setItem(`mosaic:freshness:v1:${key}`, JSON.stringify({ ...result.snapshot })); + return result.snapshot.version; +} + +describe('useFreshCollection failure matrix', () => { + it('is unknown (not empty) while the first validation is in flight', async () => { + const deferred = createDeferred(); + const collection = await renderCollection(taskOptions({ fetcher: () => deferred.promise })); + + expect(collection.freshness).toBe('unknown'); + expect(collection.validating).toBe(true); + expect(collection.data).toBeNull(); + expect(collection.canMutate).toBe(false); + + await act(async () => { + deferred.resolve(taskFixtures); + await deferred.promise; + }); + }); + + it('becomes current with provenance after a verified fetch', async () => { + const collection = await renderCollection(taskOptions()); + + expect(collection.freshness).toBe('current'); + expect(collection.data).toEqual(taskFixtures); + expect(collection.snapshot?.source).toBe('gateway:/api/tasks'); + expect(collection.snapshot?.version).toBe(1); + expect(collection.failure).toBeNull(); + expect(collection.canMutate).toBe(true); + // Verified snapshot is persisted for last-known restore. + expect(sessionStorage.getItem('mosaic:freshness:v1:tasks')).toBeTruthy(); + }); + + it('treats a network failure as unavailable — never an empty healthy collection', async () => { + const collection = await renderCollection( + taskOptions({ fetcher: () => Promise.reject(new Error('network down')) }), + ); + + expect(collection.freshness).toBe('unavailable'); + expect(collection.data).toBeNull(); + expect(collection.failure).toEqual({ kind: 'fetch', message: 'network down' }); + expect(collection.canMutate).toBe(false); + expect(describeFailure(collection.failure)).toBe('network down'); + }); + + it('treats an auth failure as unavailable and drops the last-known snapshot', async () => { + let call = 0; + const collection = await renderCollection( + taskOptions({ + fetcher: () => { + call += 1; + return call === 1 ? Promise.resolve(taskFixtures) : Promise.reject(authError(401)); + }, + }), + ); + expect(collection.freshness).toBe('current'); + + await act(async () => { + await collection.revalidate(); + }); + + expect(latest?.freshness).toBe('unavailable'); + expect(latest?.data).toBeNull(); + expect(latest?.failure?.kind).toBe('fetch'); + // The previous user's data must not linger in the session cache. + expect(sessionStorage.getItem('mosaic:freshness:v1:tasks')).toBeNull(); + }); + + it('invalidates a malformed response as a schema mismatch', async () => { + const collection = await renderCollection( + taskOptions({ fetcher: () => Promise.resolve({ malformed: true }) }), + ); + + expect(collection.freshness).toBe('unavailable'); + expect(collection.data).toBeNull(); + expect(collection.failure).toEqual({ kind: 'invalidated', reason: 'schema-mismatch' }); + expect(collection.canMutate).toBe(false); + }); + + it('keeps the previous snapshot as labeled stale when a later payload mismatches', async () => { + let call = 0; + const collection = await renderCollection( + taskOptions({ + fetcher: () => { + call += 1; + return call === 1 ? Promise.resolve(taskFixtures) : Promise.resolve('garbage'); + }, + }), + ); + expect(collection.freshness).toBe('current'); + + await act(async () => { + await collection.revalidate(); + }); + + expect(latest?.freshness).toBe('stale'); + expect(latest?.data).toEqual(taskFixtures); + expect(latest?.failure).toEqual({ kind: 'invalidated', reason: 'schema-mismatch' }); + expect(latest?.canMutate).toBe(false); + }); + + it('drops the snapshot when the workspace changes under it (cross-workspace)', async () => { + let call = 0; + const collection = await renderCollection( + taskOptions({ + fetcher: () => { + call += 1; + return Promise.resolve( + call === 1 ? projectFixtures : [{ ...projectFixtures[0], userId: 'user-2' }], + ); + }, + validate: validateProjectCollection as unknown as (value: unknown) => { + data: Task[]; + workspace: string | null; + }, + source: 'gateway:/api/projects', + }), + ); + expect(collection.freshness).toBe('current'); + + await act(async () => { + await collection.revalidate(); + }); + + expect(latest?.freshness).toBe('unavailable'); + expect(latest?.data).toBeNull(); + expect(latest?.failure).toEqual({ kind: 'invalidated', reason: 'cross-workspace' }); + }); + + it('ages from current to stale and refuses mutations on stale data', async () => { + let fakeNow = NOW; + const collection = await renderCollection( + taskOptions({ + clock: () => fakeNow, + policy: { staleAfterMs: 40 }, + tickMs: 10, + }), + ); + expect(collection.freshness).toBe('current'); + + // Age the snapshot past the policy and let the tick recompute. + fakeNow = NOW + 60; + await act(async () => { + await new Promise((resolve) => setTimeout(resolve, 25)); + }); + + expect(latest?.freshness).toBe('stale'); + expect(latest?.data).toEqual(taskFixtures); + expect(latest?.canMutate).toBe(false); + + const operation = vi.fn(async () => 'result'); + await expect(latest?.mutate(operation)).rejects.toBeInstanceOf(StaleMutationError); + expect(operation).not.toHaveBeenCalled(); + }); + + it('recovers to current after a successful revalidation', async () => { + let call = 0; + const collection = await renderCollection( + taskOptions({ + fetcher: () => { + call += 1; + return call === 1 + ? Promise.reject(new Error('first attempt failed')) + : Promise.resolve(taskFixtures); + }, + }), + ); + expect(collection.freshness).toBe('unavailable'); + + await act(async () => { + await collection.revalidate(); + }); + + expect(latest?.freshness).toBe('current'); + expect(latest?.failure).toBeNull(); + + const operation = vi.fn(async (data: Task[]) => data.length); + await expect(latest?.mutate(operation)).resolves.toBe(taskFixtures.length); + expect(operation).toHaveBeenCalledOnce(); + }); + + it('restores a cached snapshot as unverified stale data, then verifies it', async () => { + const seededVersion = seedCache('tasks'); + const deferred = createDeferred(); + const collection = await renderCollection(taskOptions({ fetcher: () => deferred.promise })); + + // Restored data is situational awareness only: labeled stale, never + // current, and mutations are refused before verification. + expect(collection.freshness).toBe('stale'); + expect(collection.data).toEqual(taskFixtures); + expect(collection.canMutate).toBe(false); + await expect(collection.mutate(vi.fn())).rejects.toBeInstanceOf(StaleMutationError); + + await act(async () => { + deferred.resolve(taskFixtures); + await deferred.promise; + }); + + expect(latest?.freshness).toBe('current'); + expect(latest?.snapshot?.version).toBe(seededVersion + 1); + }); + + it('never promotes corrupted cache data to current (cache corruption)', async () => { + sessionStorage.setItem('mosaic:freshness:v1:tasks', '{"data":'); + const collection = await renderCollection( + taskOptions({ fetcher: () => Promise.reject(new Error('still down')) }), + ); + + expect(collection.freshness).toBe('unavailable'); + expect(collection.data).toBeNull(); + expect(collection.canMutate).toBe(false); + // The corrupted entry is dropped so it cannot come back. + expect(sessionStorage.getItem('mosaic:freshness:v1:tasks')).toBeNull(); + }); + + it('refuses mutations while unknown or unavailable — the call itself, not just the button', async () => { + const deferred = createDeferred(); + const unknown = await renderCollection(taskOptions({ fetcher: () => deferred.promise })); + const operation = vi.fn(async () => 'result'); + await expect(unknown.mutate(operation)).rejects.toBeInstanceOf(StaleMutationError); + expect(operation).not.toHaveBeenCalled(); + await act(async () => { + deferred.reject(new Error('failed')); + await deferred.promise.catch(() => undefined); + }); + + const unavailable = latest!; + await expect(unavailable.mutate(operation)).rejects.toBeInstanceOf(StaleMutationError); + expect(operation).not.toHaveBeenCalled(); + expect(unavailable.canMutate).toBe(false); + }); + + it('degrades to stale with last-known data when a revalidation fails after success', async () => { + let call = 0; + const collection = await renderCollection( + taskOptions({ + fetcher: () => { + call += 1; + return call === 1 + ? Promise.resolve(taskFixtures) + : Promise.reject(new Error('connection lost')); + }, + }), + ); + expect(collection.freshness).toBe('current'); + + await act(async () => { + await collection.revalidate(); + }); + + expect(latest?.freshness).toBe('stale'); + expect(latest?.data).toEqual(taskFixtures); + const failure: FreshnessFailure | null = latest?.failure ?? null; + expect(failure).toEqual({ kind: 'fetch', message: 'connection lost' }); + }); +}); diff --git a/apps/web/src/lib/freshness/use-fresh-collection.ts b/apps/web/src/lib/freshness/use-fresh-collection.ts new file mode 100644 index 00000000..4819c07e --- /dev/null +++ b/apps/web/src/lib/freshness/use-fresh-collection.ts @@ -0,0 +1,281 @@ +import { useCallback, useEffect, useMemo, useRef, useState } from 'react'; +import { + acceptSnapshot, + assertMutable, + computeFreshness, + DEFAULT_FRESHNESS_POLICY, + invalidationReasonLabels, + type FreshPayload, + type FreshSnapshot, + type FreshnessPolicy, + type FreshnessState, + type InvalidationReason, + StaleMutationError, +} from './model'; +import { clearSnapshotCache, readSnapshotCache, writeSnapshotCache } from './snapshot-cache'; + +/** + * Freshness-aware collection fetch hook (RI-5-001). + * + * One hook owns one gateway collection end to end: fetch, schema validation, + * snapshot acceptance with provenance, session-scoped last-known caching, + * aging, and the mutation guard. Pages consume `freshness` and never infer + * health from emptiness. + */ + +/** Why the latest validation did not produce a current snapshot. */ +export type FreshnessFailure = + | { readonly kind: 'fetch'; readonly message: string } + | { readonly kind: 'invalidated'; readonly reason: InvalidationReason }; + +export interface UseFreshCollectionOptions { + /** Source identity for provenance labels, e.g. `gateway:/api/tasks`. */ + readonly source: string; + /** Performs the unvalidated fetch. The hook owns abort and verification. */ + readonly fetcher: (signal: AbortSignal) => Promise; + /** + * Runtime schema validator. Returning `null` invalidates the payload + * (`schema-mismatch`) instead of letting malformed JSON flow into render. + */ + readonly validate: (value: unknown) => FreshPayload | null; + /** Overrides of the default freshness policy. */ + readonly policy?: Partial; + /** + * Session cache key for last-known snapshots. `null`/omitted disables + * restore. Restored snapshots are unverified: they render only as + * labeled `stale` data until a fetch re-verifies them. + */ + readonly cacheKey?: string | null; + /** Injectable clock for deterministic age transitions in tests. */ + readonly clock?: () => number; + /** Aging tick interval override (default derived from `staleAfterMs`). */ + readonly tickMs?: number; + /** When false, no fetch runs (surfaces stay `unavailable`/`unknown`). */ + readonly enabled?: boolean; +} + +export interface FreshCollection { + /** Last verified (or restored-unverified) snapshot, or `null`. */ + readonly snapshot: FreshSnapshot | null; + /** Snapshot data or `null` — never a fabricated empty collection. */ + readonly data: T | null; + readonly freshness: FreshnessState; + /** True while a validation request is in flight. */ + readonly validating: boolean; + /** Outcome of the latest failed validation, `null` when healthy. */ + readonly failure: FreshnessFailure | null; + /** False unless freshness is `current`; drives disabled UI affordances. */ + readonly canMutate: boolean; + /** Re-run the fetch and re-verify. Always allowed (it is a read). */ + readonly revalidate: () => Promise; + /** + * Run a state-changing operation against verified-current data only. + * Rejects with `StaleMutationError` on any other state — the guard fires + * even if a disabled button was bypassed (defense in depth). + */ + readonly mutate: (operation: (data: T) => Promise) => Promise; +} + +const defaultClock = (): number => Date.now(); + +function resolveTickMs(policy: FreshnessPolicy, override?: number): number { + if (override !== undefined && override > 0) return override; + return Math.min(5_000, Math.max(250, Math.floor(policy.staleAfterMs / 4))); +} + +function isAuthFailure(caught: unknown): boolean { + return ( + typeof caught === 'object' && + caught !== null && + 'statusCode' in caught && + ((caught as { statusCode?: unknown }).statusCode === 401 || + (caught as { statusCode?: unknown }).statusCode === 403) + ); +} + +function fetchFailureMessage(caught: unknown): string { + if (caught instanceof Error && caught.message.trim().length > 0) return caught.message; + return 'The request failed.'; +} + +/** Human-readable summary of a failure for unavailable/stale notices. */ +export function describeFailure(failure: FreshnessFailure | null): string | null { + if (failure === null) return null; + if (failure.kind === 'fetch') return failure.message; + return `The snapshot was invalidated: ${invalidationReasonLabels[failure.reason]}.`; +} + +export function useFreshCollection(options: UseFreshCollectionOptions): FreshCollection { + const optionsRef = useRef(options); + optionsRef.current = options; + + const policy = useMemo( + () => ({ ...DEFAULT_FRESHNESS_POLICY, ...options.policy }), + [options.policy], + ); + const policyRef = useRef(policy); + policyRef.current = policy; + + const clockRef = useRef(options.clock ?? defaultClock); + clockRef.current = options.clock ?? defaultClock; + + const [snapshot, setSnapshot] = useState | null>(null); + const [failure, setFailure] = useState(null); + const [unverified, setUnverified] = useState(false); + const [validating, setValidating] = useState(options.enabled !== false); + const [now, setNow] = useState(() => (options.clock ?? defaultClock)()); + + const snapshotRef = useRef(snapshot); + snapshotRef.current = snapshot; + const failureRef = useRef(failure); + failureRef.current = failure; + const unverifiedRef = useRef(unverified); + unverifiedRef.current = unverified; + + const runRef = useRef(0); + const abortRef = useRef(null); + + const revalidate = useCallback(async (): Promise => { + const current = optionsRef.current; + if (current.enabled === false) { + setValidating(false); + return; + } + + const runId = ++runRef.current; + abortRef.current?.abort(); + const controller = new AbortController(); + abortRef.current = controller; + setValidating(true); + + let value: unknown; + try { + value = await current.fetcher(controller.signal); + } catch (caught) { + if (runRef.current !== runId || controller.signal.aborted) return; + if (isAuthFailure(caught)) { + // An unauthenticated viewer must not keep (or be served) the + // previous user's last-known data. + setSnapshot(null); + setUnverified(false); + if (current.cacheKey) clearSnapshotCache(current.cacheKey); + } + setFailure({ kind: 'fetch', message: fetchFailureMessage(caught) }); + setValidating(false); + return; + } + + if (runRef.current !== runId) return; + + const result = acceptSnapshot({ + value, + validate: current.validate, + previous: snapshotRef.current, + policy: policyRef.current, + source: current.source, + now: clockRef.current(), + }); + + if (result.outcome === 'accepted') { + setSnapshot(result.snapshot); + setUnverified(false); + setFailure(null); + if (current.cacheKey) writeSnapshotCache(current.cacheKey, result.snapshot); + } else { + if (result.reason === 'cross-workspace') { + // Data verified for a different workspace must not linger as + // last-known situational awareness either. + setSnapshot(null); + setUnverified(false); + } + if (current.cacheKey) clearSnapshotCache(current.cacheKey); + setFailure({ kind: 'invalidated', reason: result.reason }); + } + setValidating(false); + }, []); + + // Restore the last-known snapshot (unverified) and run the first fetch. + useEffect(() => { + if (optionsRef.current.enabled === false) { + setValidating(false); + return; + } + + const cacheKey = optionsRef.current.cacheKey; + if (cacheKey) { + const restored = readSnapshotCache({ + key: cacheKey, + workspace: policyRef.current.workspace, + policy: policyRef.current, + validate: optionsRef.current.validate, + }); + if (restored.outcome === 'hit') { + setSnapshot(restored.snapshot); + setUnverified(true); + } else if (restored.outcome === 'invalidated') { + // A corrupted/foreign/regressed entry is dropped immediately; it must + // never surface as data. The fetch decides the visible state. + clearSnapshotCache(cacheKey); + } + } + + void revalidate(); + + return () => { + abortRef.current?.abort(); + }; + // Mount-once by design: `revalidate` is stable and reads live options + // through refs, so it never needs to re-run when options change. + // Route-param pages remount this hook via an identity `key` instead. + }, [revalidate]); + + // Aging tick: recomputes freshness as the snapshot ages past the policy. + useEffect(() => { + const interval = setInterval( + () => { + setNow(clockRef.current()); + }, + resolveTickMs(policyRef.current, optionsRef.current.tickMs), + ); + return () => clearInterval(interval); + }, []); + + const freshness = useMemo(() => { + if (snapshot === null) return validating ? 'unknown' : 'unavailable'; + return computeFreshness({ + snapshot, + policy, + now, + degraded: failure !== null || unverified, + }); + // `now` from state covers age; refs inside computeFreshness are pure. + }, [snapshot, validating, failure, unverified, now, policy]); + + const canMutate = freshness === 'current'; + + const mutate = useCallback(async (operation: (data: T) => Promise): Promise => { + const currentSnapshot = snapshotRef.current; + // No verified snapshot at all: with nothing verified there is nothing + // current to mutate, regardless of the recorded failure. + if (currentSnapshot === null) throw new StaleMutationError('unavailable'); + const state = computeFreshness({ + snapshot: currentSnapshot, + policy: policyRef.current, + now: clockRef.current(), + degraded: failureRef.current !== null || unverifiedRef.current, + }); + assertMutable(state); + return operation(currentSnapshot.data); + }, []); + + return { + snapshot, + data: snapshot === null ? null : snapshot.data, + freshness, + validating, + failure, + canMutate, + revalidate, + mutate, + }; +} diff --git a/apps/web/src/lib/freshness/validators.spec.ts b/apps/web/src/lib/freshness/validators.spec.ts new file mode 100644 index 00000000..7f6d3ec2 --- /dev/null +++ b/apps/web/src/lib/freshness/validators.spec.ts @@ -0,0 +1,103 @@ +import { describe, expect, it } from 'vitest'; +import type { Mission, Project, Task } from '@/lib/types'; +import { + validateMissionCollection, + validateProjectCollection, + validateProjectEntity, + validateTaskCollection, +} from './validators'; +import { missionFixtures, projectFixtures, taskFixtures } from '@/spa/pages/page-fixtures'; + +describe('validateTaskCollection', () => { + it('accepts a well-formed task collection', () => { + expect(validateTaskCollection(taskFixtures)).toEqual({ + data: taskFixtures, + workspace: null, + }); + }); + + it('accepts an empty collection (a healthy empty state is a valid payload)', () => { + expect(validateTaskCollection([])).toEqual({ data: [], workspace: null }); + }); + + it.each([ + ['not an array', { items: [] }], + ['item is not an object', ['nope']], + ['missing id', [{ ...(taskFixtures[0] as Task), id: undefined }]], + ['missing title', [{ ...(taskFixtures[0] as Task), title: undefined }]], + ['unknown status enum', [{ ...(taskFixtures[0] as Task), status: 'finished' }]], + ['unknown priority enum', [{ ...(taskFixtures[0] as Task), priority: 'urgent' }]], + ['tags of the wrong type', [{ ...(taskFixtures[0] as Task), tags: 'spa' }]], + ['metadata of the wrong type', [{ ...(taskFixtures[0] as Task), metadata: 'notes' }]], + ['createdAt of the wrong type', [{ ...(taskFixtures[0] as Task), createdAt: 1234 }]], + ['null sneaks past a required string', [{ ...(taskFixtures[0] as Task), title: null }]], + ])('rejects a malformed payload: %s', (_label, value) => { + expect(validateTaskCollection(value)).toBeNull(); + }); +}); + +describe('validateMissionCollection', () => { + it('accepts a well-formed mission collection', () => { + expect(validateMissionCollection(missionFixtures)).toEqual({ + data: missionFixtures, + workspace: null, + }); + }); + + it.each([ + ['not an array', null], + ['item missing name', [{ ...(missionFixtures[0] as Mission), name: 42 }]], + ['unknown status enum', [{ ...(missionFixtures[0] as Mission), status: 'canceled' }]], + ['projectId of the wrong type', [{ ...(missionFixtures[0] as Mission), projectId: 7 }]], + ])('rejects a malformed payload: %s', (_label, value) => { + expect(validateMissionCollection(value)).toBeNull(); + }); +}); + +describe('validateProjectCollection', () => { + it('accepts a uniform workspace-scoped collection and reports its workspace', () => { + expect(validateProjectCollection(projectFixtures)).toEqual({ + data: projectFixtures, + workspace: 'user-1', + }); + }); + + it('accepts an empty collection with no workspace identity', () => { + expect(validateProjectCollection([])).toEqual({ data: [], workspace: null }); + }); + + it.each([ + ['not an array', 42], + ['item missing userId', [{ ...(projectFixtures[0] as Project), userId: undefined }]], + ['unknown status enum', [{ ...(projectFixtures[0] as Project), status: 'live' }]], + ['description of the wrong type', [{ ...(projectFixtures[0] as Project), description: 1 }]], + ])('rejects a malformed payload: %s', (_label, value) => { + expect(validateProjectCollection(value)).toBeNull(); + }); + + it('rejects a collection mixing workspace identities (cross-workspace leak)', () => { + const mixed = [ + projectFixtures[0] as Project, + { ...(projectFixtures[1] as Project), userId: 'user-2' }, + ]; + expect(validateProjectCollection(mixed)).toBeNull(); + }); +}); + +describe('validateProjectEntity', () => { + it('accepts a well-formed project and reports its workspace', () => { + expect(validateProjectEntity(projectFixtures[0])).toEqual({ + data: projectFixtures[0], + workspace: 'user-1', + }); + }); + + it.each([ + ['not an object', 'project-1'], + ['null', null], + ['array', [projectFixtures[0]]], + ['missing userId', [{ ...(projectFixtures[0] as Project), userId: null }]], + ])('rejects a malformed entity: %s', (_label, value) => { + expect(validateProjectEntity(value)).toBeNull(); + }); +}); diff --git a/apps/web/src/lib/freshness/validators.ts b/apps/web/src/lib/freshness/validators.ts new file mode 100644 index 00000000..6c51c8a1 --- /dev/null +++ b/apps/web/src/lib/freshness/validators.ts @@ -0,0 +1,135 @@ +import type { Mission, Project, Task, MissionStatus, TaskPriority, TaskStatus } from '@/lib/types'; +import type { FreshPayload } from './model'; + +/** + * Runtime schema validators for gateway collections (RI-5-001). + * + * `api()` returns untrusted JSON cast to `T`; these validators are the + * seam where a malformed response becomes an explicit schema mismatch + * instead of flowing into the render path as if it were healthy data. + */ + +const taskStatuses: readonly TaskStatus[] = [ + 'not-started', + 'in-progress', + 'blocked', + 'done', + 'cancelled', +]; +const taskPriorities: readonly TaskPriority[] = ['critical', 'high', 'medium', 'low']; +const missionStatuses: readonly MissionStatus[] = [ + 'planning', + 'active', + 'paused', + 'completed', + 'failed', +]; +const projectStatuses: readonly Project['status'][] = ['active', 'paused', 'completed', 'archived']; + +function isRecord(value: unknown): value is Record { + return typeof value === 'object' && value !== null && !Array.isArray(value); +} + +function isString(value: unknown): value is string { + return typeof value === 'string'; +} + +function isNullableString(value: unknown): value is string | null { + return value === null || typeof value === 'string'; +} + +function isOneOf(value: unknown, allowed: readonly T[]): value is T { + return typeof value === 'string' && (allowed as readonly string[]).includes(value); +} + +function isNullableRecord(value: unknown): value is Record | null { + return value === null || isRecord(value); +} + +function isNullableStringArray(value: unknown): value is string[] | null { + if (value === null) return true; + if (!Array.isArray(value)) return false; + return value.every((item) => typeof item === 'string'); +} + +function isIsoLike(value: unknown): value is string { + return typeof value === 'string' && value.length > 0; +} + +function isTask(value: unknown): value is Task { + if (!isRecord(value)) return false; + return ( + isString(value['id']) && + isString(value['title']) && + isOneOf(value['status'], taskStatuses) && + isOneOf(value['priority'], taskPriorities) && + isNullableString(value['projectId']) && + isNullableString(value['missionId']) && + isNullableString(value['assignee']) && + isNullableStringArray(value['tags']) && + isNullableRecord(value['metadata']) && + isNullableString(value['dueDate']) && + isIsoLike(value['createdAt']) && + isIsoLike(value['updatedAt']) + ); +} + +/** Tasks carry no workspace identity; scope falls back to the policy. */ +export function validateTaskCollection(value: unknown): FreshPayload | null { + if (!Array.isArray(value) || !value.every(isTask)) return null; + return { data: value as Task[], workspace: null }; +} + +function isMission(value: unknown): value is Mission { + if (!isRecord(value)) return false; + return ( + isString(value['id']) && + isString(value['name']) && + isOneOf(value['status'], missionStatuses) && + isNullableString(value['projectId']) && + isNullableString(value['description']) && + isNullableRecord(value['metadata']) && + isIsoLike(value['createdAt']) && + isIsoLike(value['updatedAt']) + ); +} + +/** Missions carry no workspace identity; scope falls back to the policy. */ +export function validateMissionCollection(value: unknown): FreshPayload | null { + if (!Array.isArray(value) || !value.every(isMission)) return null; + return { data: value as Mission[], workspace: null }; +} + +function isProject(value: unknown): value is Project { + if (!isRecord(value)) return false; + return ( + isString(value['id']) && + isString(value['name']) && + isOneOf(value['status'], projectStatuses) && + isString(value['userId']) && + isNullableString(value['description']) && + isNullableRecord(value['metadata']) && + isIsoLike(value['createdAt']) && + isIsoLike(value['updatedAt']) + ); +} + +/** + * Projects are workspace-scoped: every item must carry the same `userId`. + * A collection mixing identities (cross-workspace leak) is a schema + * mismatch; the uniform `userId` becomes the snapshot workspace. + */ +export function validateProjectCollection(value: unknown): FreshPayload | null { + if (!Array.isArray(value) || !value.every(isProject)) return null; + const projects = value as Project[]; + const workspaces = new Set(projects.map((project) => project.userId)); + if (workspaces.size > 1) return null; + return { data: projects, workspace: projects.length > 0 ? projects[0]!.userId : null }; +} + +/** Single project entity (project detail primary collection). */ +export function validateProjectEntity(value: unknown): FreshPayload | null { + if (!isProject(value)) return null; + const project = value as Project; + return { data: project, workspace: project.userId }; +} diff --git a/apps/web/src/spa/pages/project-detail.spec.tsx b/apps/web/src/spa/pages/project-detail.spec.tsx index ffb7b795..22f0b695 100644 --- a/apps/web/src/spa/pages/project-detail.spec.tsx +++ b/apps/web/src/spa/pages/project-detail.spec.tsx @@ -35,6 +35,7 @@ afterEach(async () => { document.body.replaceChildren(); root = null; apiMock.mockReset(); + sessionStorage.clear(); }); async function renderProjectDetailPage(): Promise> { @@ -64,21 +65,49 @@ function clickButtonByText(text: string): void { button.dispatchEvent(new MouseEvent('click', { bubbles: true })); } +async function flushAct(): Promise { + await act(async () => { + await Promise.resolve(); + }); +} + +interface Deferred { + promise: Promise; + resolve: (value: T) => void; +} + +function createDeferred(): Deferred { + let resolve!: (value: T) => void; + const promise = new Promise((res) => { + resolve = res; + }); + return { promise, resolve }; +} + +const projectOneTasks = taskFixtures.filter((task) => task.projectId === 'project-1'); + +function mockHealthyLoad(): void { + apiMock + .mockResolvedValueOnce(projectFixtures[0]) + .mockResolvedValueOnce(missionFixtures) + .mockResolvedValueOnce(projectOneTasks); +} + describe('ProjectDetailPage', () => { it('loads the project, tasks, missions, and optional PRD content for the active project', async () => { - apiMock - .mockResolvedValueOnce(projectFixtures[0]) - .mockResolvedValueOnce(missionFixtures) - .mockResolvedValueOnce(taskFixtures.filter((task) => task.projectId === 'project-1')); + mockHealthyLoad(); await renderProjectDetailPage(); - expect(apiMock.mock.calls).toEqual([ - ['/api/projects/project-1'], - ['/api/missions'], - ['/api/tasks?projectId=project-1'], + expect(apiMock.mock.calls.map((call) => call[0])).toEqual([ + '/api/projects/project-1', + '/api/missions', + '/api/tasks?projectId=project-1', ]); + expect(container.querySelector('[data-freshness]')?.getAttribute('data-freshness')).toBe( + 'current', + ); expect(container.textContent).toContain('Mosaic Stack'); expect(container.textContent).toContain('Route /projects/:id'); expect(container.textContent).toContain('Tasks'); @@ -101,10 +130,7 @@ describe('ProjectDetailPage', () => { }); it('opens and closes the existing read-only task modal from the tasks tab', async () => { - apiMock - .mockResolvedValueOnce(projectFixtures[0]) - .mockResolvedValueOnce(missionFixtures) - .mockResolvedValueOnce(taskFixtures.filter((task) => task.projectId === 'project-1')); + mockHealthyLoad(); await renderProjectDetailPage(); @@ -134,35 +160,153 @@ describe('ProjectDetailPage', () => { expect(container.querySelector('[role="dialog"]')).toBeNull(); }); - it('renders the project with an empty missions tab when the missions request fails', async () => { - apiMock - .mockResolvedValueOnce(projectFixtures[0]) - .mockRejectedValueOnce(new Error('Missions request failed')) - .mockResolvedValueOnce(taskFixtures.filter((task) => task.projectId === 'project-1')); + it('shows verified completion verdicts when the task collection is current', async () => { + mockHealthyLoad(); await renderProjectDetailPage(); - expect(container.textContent).toContain('Mosaic Stack'); - expect(container.querySelector('[role="alert"]')).toBeNull(); - - await act(async () => { - clickButtonByText('Missions (0)'); - }); - - expect(container.textContent).toContain('No missions for this project'); + const doneCard = [...container.querySelectorAll('div')].find( + (candidate) => candidate.textContent === 'Done1', + ); + expect(doneCard).toBeTruthy(); + const inProgressCard = [...container.querySelectorAll('div')].find( + (candidate) => candidate.textContent === 'In Progress1', + ); + expect(inProgressCard).toBeTruthy(); }); - it('renders a visible alert when the project request fails and lets the user navigate back', async () => { + it('renders an explicit unavailable missions tab when the missions request fails (partial, not empty)', async () => { + apiMock + .mockResolvedValueOnce(projectFixtures[0]) + .mockRejectedValueOnce(new Error('Missions request failed')) + .mockResolvedValueOnce(projectOneTasks); + + await renderProjectDetailPage(); + + // Secondary failure degrades the surface to partial; the project itself + // still renders. + expect(container.querySelector('[data-freshness]')?.getAttribute('data-freshness')).toBe( + 'partial', + ); + expect(container.textContent).toContain('Mosaic Stack'); + const partial = container.querySelector('[role="status"]'); + expect(partial?.textContent).toContain('Missions'); + expect(partial?.textContent).toContain('unavailable'); + + await act(async () => { + clickButtonByText('Missions (?)'); + }); + + const alert = container.querySelector('[role="alert"]'); + expect(alert?.textContent).toContain('Missions request failed'); + // Negative control: a failed fetch must not look like an empty list. + expect(container.textContent).not.toContain('No missions for this project'); + }); + + it('marks derived verdicts unknown when the tasks collection is unavailable', async () => { + apiMock + .mockResolvedValueOnce(projectFixtures[0]) + .mockResolvedValueOnce(missionFixtures) + .mockRejectedValueOnce(new Error('Tasks request failed')); + + await renderProjectDetailPage(); + + expect(container.querySelector('[data-freshness]')?.getAttribute('data-freshness')).toBe( + 'partial', + ); + + // Completion verdicts become unknown ('?') — never green counts. + for (const label of ['Done', 'In Progress', 'Blocked', 'Tasks']) { + const unknownCard = [...container.querySelectorAll('div')].find( + (candidate) => candidate.textContent === `${label}?`, + ); + expect(unknownCard, `expected ${label} card to render ?`).toBeTruthy(); + } + // Negative control: no green "Done 1" verdict anywhere. + expect( + [...container.querySelectorAll('div')].some((candidate) => candidate.textContent === 'Done1'), + ).toBe(false); + + await act(async () => { + clickButtonByText('Tasks (?)'); + }); + + const alert = container.querySelector('[role="alert"]'); + expect(alert?.textContent).toContain('Tasks request failed'); + // Negative control: no healthy empty task list from a failed fetch. + expect(container.textContent).not.toContain('No tasks found'); + expect(container.querySelector('table')).toBeNull(); + }); + + it('recovers a partial surface to current after revalidation', async () => { + apiMock + .mockResolvedValueOnce(projectFixtures[0]) + .mockResolvedValueOnce(missionFixtures) + .mockRejectedValueOnce(new Error('Tasks request failed')) + .mockResolvedValueOnce(projectFixtures[0]) + .mockResolvedValueOnce(missionFixtures) + .mockResolvedValueOnce(projectOneTasks); + + await renderProjectDetailPage(); + expect(container.querySelector('[data-freshness]')?.getAttribute('data-freshness')).toBe( + 'partial', + ); + + await act(async () => { + clickButtonByText('Revalidate'); + }); + await flushAct(); + + expect(container.querySelector('[data-freshness]')?.getAttribute('data-freshness')).toBe( + 'current', + ); + expect( + [...container.querySelectorAll('div')].some((candidate) => candidate.textContent === 'Done1'), + ).toBe(true); + }); + + it("never shows one project's data on another project's route after navigation", async () => { + mockHealthyLoad(); + + const router = await renderProjectDetailPage(); + expect(container.textContent).toContain('Mosaic Stack'); + + const deferred = createDeferred<(typeof projectFixtures)[number]>(); + apiMock + .mockResolvedValueOnce(deferred.promise) + .mockResolvedValueOnce([]) + .mockResolvedValueOnce([]); + + await act(async () => { + await router.navigate('/projects/project-2'); + }); + + // While project-2 loads, nothing from project-1 may render on its route. + expect(container.textContent).toContain('Loading project...'); + expect(container.textContent).not.toContain('Mosaic Stack'); + expect(container.textContent).not.toContain('Route /projects/:id'); + + await act(async () => { + deferred.resolve(projectFixtures[1]!); + await deferred.promise; + }); + + expect(container.textContent).toContain('Agent Runtime'); + expect(apiMock.mock.calls[3]?.[0]).toBe('/api/projects/project-2'); + }); + + it('renders a visible unavailable state when the project request fails and lets the user navigate back', async () => { apiMock .mockRejectedValueOnce(new Error('Project request failed')) .mockResolvedValueOnce(missionFixtures) - .mockResolvedValueOnce(taskFixtures.filter((task) => task.projectId === 'project-1')); + .mockResolvedValueOnce(projectOneTasks); const router = await renderProjectDetailPage(); const alert = container.querySelector('[role="alert"]'); expect(alert).toBeTruthy(); expect(alert?.textContent).toContain('Project request failed'); + expect(alert?.textContent).toContain('not an empty result'); expect(container.textContent).not.toContain('Mosaic Stack'); await act(async () => { diff --git a/apps/web/src/spa/pages/project-detail.tsx b/apps/web/src/spa/pages/project-detail.tsx index 20253b5e..c0907ad6 100644 --- a/apps/web/src/spa/pages/project-detail.tsx +++ b/apps/web/src/spa/pages/project-detail.tsx @@ -1,14 +1,30 @@ -import { useEffect, useState, type ReactElement } from 'react'; +import { useState, type ReactElement } from 'react'; import { useNavigate, useParams } from 'react-router-dom'; import { MissionTimeline } from '@/components/projects/mission-timeline'; import { PrdViewer } from '@/components/projects/prd-viewer'; import { TaskDetailModal } from '@/components/tasks/task-detail-modal'; import { TaskListView } from '@/components/tasks/task-list-view'; import { TaskStatusSummary } from '@/components/tasks/task-status-summary'; +import { + PartialDataNotice, + StaleDataNotice, + UnavailableDataNotice, +} from '@/components/freshness/freshness-notices'; import { api } from '@/lib/api'; import { cn } from '@/lib/cn'; import type { Mission, Project, Task, TaskStatus } from '@/lib/types'; -import { getErrorMessage } from './page-errors'; +import { + combineFreshness, + UNKNOWN_VERDICT, + verdictValue, + type FreshSnapshot, +} from '@/lib/freshness/model'; +import { describeFailure, useFreshCollection } from '@/lib/freshness/use-fresh-collection'; +import { + validateMissionCollection, + validateProjectEntity, + validateTaskCollection, +} from '@/lib/freshness/validators'; type Tab = 'overview' | 'tasks' | 'missions' | 'prd'; @@ -51,73 +67,62 @@ function TabButton({ id, label, activeTab, onClick }: TabButtonProps): ReactElem ); } +/** Remounts per project id so no state from one project renders for another. */ export function ProjectDetailPage(): ReactElement { const { id = '' } = useParams(); + return ; +} + +function ProjectDetail({ id }: { id: string }): ReactElement { const navigate = useNavigate(); - const [project, setProject] = useState(null); - const [missions, setMissions] = useState([]); - const [tasks, setTasks] = useState([]); - const [loading, setLoading] = useState(true); - const [error, setError] = useState(null); + const enabled = id.length > 0; + + // Primary collection gates the surface; missions and tasks are secondaries + // whose failures degrade the surface to `partial` instead of rendering + // empty healthy lists. + const project = useFreshCollection({ + source: `gateway:/api/projects/${id}`, + fetcher: (signal) => api(`/api/projects/${id}`, { signal }), + validate: validateProjectEntity, + // No last-known restore: the entity carries workspace identity that + // cannot be scope-checked before display (see ProjectsPage note). + enabled, + }); + const missions = useFreshCollection({ + source: 'gateway:/api/missions', + fetcher: (signal) => api('/api/missions', { signal }), + validate: validateMissionCollection, + cacheKey: enabled ? 'missions' : null, + enabled, + }); + const tasks = useFreshCollection({ + source: `gateway:/api/tasks?projectId=${id}`, + fetcher: (signal) => api(`/api/tasks?projectId=${id}`, { signal }), + validate: validateTaskCollection, + cacheKey: enabled ? `project-tasks:${id}` : null, + enabled, + }); + const [activeTab, setActiveTab] = useState('overview'); const [taskFilter, setTaskFilter] = useState('all'); const [selectedTask, setSelectedTask] = useState(null); - useEffect(() => { - if (!id) { - setError('Project id is missing.'); - setLoading(false); - return; - } + const surface = combineFreshness(project.freshness, [missions.freshness, tasks.freshness]); + const tasksVerified = tasks.freshness === 'current'; + const projectMissions = missions.data?.filter((mission) => mission.projectId === id) ?? null; - let cancelled = false; - setLoading(true); - setError(null); + const retryAll = (): void => { + void Promise.all([project.revalidate(), missions.revalidate(), tasks.revalidate()]); + }; - void Promise.all([ - api('/api/projects/' + id), - api('/api/missions').catch(() => [] as Mission[]), - api('/api/tasks?projectId=' + id).catch(() => [] as Task[]), - ]) - .then(([loadedProject, allMissions, loadedTasks]) => { - if (cancelled) return; - setProject(loadedProject); - setMissions(allMissions.filter((mission) => mission.projectId === id)); - setTasks(loadedTasks); - }) - .catch((caught: unknown) => { - if (cancelled) return; - setError(getErrorMessage(caught, 'Failed to load project.')); - }) - .finally(() => { - if (cancelled) return; - setLoading(false); - }); - - return () => { - cancelled = true; - }; - }, [id]); - - if (loading) { - return ( -
-
-

Project

-
-

Loading project...

-
- ); - } - - if (error || !project) { + if (!enabled) { return (

Project

- {error ?? 'Project not found.'} + Project id is missing.
+ ); + } + + if (project.freshness === 'unavailable' || project.data === null) { + return ( +
+
+

Project

+
+ + +
+ ); + } + + const projectTasks = tasks.data ?? null; const filteredTasks = - taskFilter === 'all' ? tasks : tasks.filter((task) => task.status === taskFilter); - const prdContent = getPrdContent(project); + projectTasks === null + ? [] + : taskFilter === 'all' + ? projectTasks + : projectTasks.filter((task) => task.status === taskFilter); + + // Derived completion verdicts: unknown (never green) unless the task + // collection is verified current. + const doneCount = projectTasks?.filter((task) => task.status === 'done').length ?? 0; + const inProgressCount = projectTasks?.filter((task) => task.status === 'in-progress').length ?? 0; + const blockedCount = projectTasks?.filter((task) => task.status === 'blocked').length ?? 0; + + const prdContent = getPrdContent(project.data); const tabs: Array<{ id: Tab; label: string }> = [ { id: 'overview', label: 'Overview' }, - { id: 'tasks', label: `Tasks (${tasks.length})` }, - { id: 'missions', label: `Missions (${missions.length})` }, + { + id: 'tasks', + label: `Tasks (${projectTasks === null ? UNKNOWN_VERDICT : projectTasks.length})`, + }, + { + id: 'missions', + label: `Missions (${projectMissions === null ? UNKNOWN_VERDICT : projectMissions.length})`, + }, ...(prdContent ? [{ id: 'prd' as const, label: 'PRD' }] : []), ]; + const staleSnapshot: FreshSnapshot | null = + project.freshness === 'stale' + ? project.snapshot + : missions.freshness === 'stale' + ? missions.snapshot + : tasks.freshness === 'stale' + ? tasks.snapshot + : null; + const missingSections: string[] = []; + if (missions.freshness === 'unavailable') missingSections.push('Missions'); + if (tasks.freshness === 'unavailable') missingSections.push('Tasks'); + return ( -
+
-

{project.name}

+

{project.data.name}

- {project.status} + {project.data.status}
- {project.description ? ( -

{project.description}

+ {project.data.description ? ( +

{project.data.description}

) : null}

- Created {new Date(project.createdAt).toLocaleDateString()} · Updated{' '} - {new Date(project.updatedAt).toLocaleDateString()} + Created {new Date(project.data.createdAt).toLocaleDateString()} · Updated{' '} + {new Date(project.data.updatedAt).toLocaleDateString()}

+ {staleSnapshot !== null ? ( +
+ +
+ ) : null} + + {missingSections.length > 0 ? ( +
+ +
+ ) : null} +
- + task.status === 'done').length)} - valueClass="text-success" + value={verdictValue(tasksVerified, String(doneCount))} + valueClass={tasksVerified ? 'text-success' : undefined} /> task.status === 'in-progress').length)} - valueClass="text-blue-400" + value={verdictValue(tasksVerified, String(inProgressCount))} + valueClass={tasksVerified ? 'text-blue-400' : undefined} /> task.status === 'blocked').length)} - valueClass={tasks.some((task) => task.status === 'blocked') ? 'text-error' : undefined} + value={verdictValue(tasksVerified, String(blockedCount))} + valueClass={tasksVerified && blockedCount > 0 ? 'text-error' : undefined} />
@@ -211,23 +294,43 @@ export function ProjectDetailPage(): ReactElement {
{activeTab === 'overview' ? ( - + ) : null} {activeTab === 'tasks' ? (
-
- -
- + ) : ( + <> +
+ +
+ + + )}
) : null} - {activeTab === 'missions' ? : null} + {activeTab === 'missions' ? ( + projectMissions === null ? ( + + ) : ( + + ) + ) : null} {activeTab === 'prd' && prdContent ? (
@@ -248,18 +351,26 @@ function OverviewTab({ tasks, }: { project: Project; - missions: Mission[]; - tasks: Task[]; + missions: Mission[] | null; + tasks: Task[] | null; }): ReactElement { - const recentTasks = [...tasks] - .sort((left, right) => new Date(right.updatedAt).getTime() - new Date(left.updatedAt).getTime()) - .slice(0, 5); + const recentTasks = + tasks === null + ? null + : [...tasks] + .sort( + (left, right) => + new Date(right.updatedAt).getTime() - new Date(left.updatedAt).getTime(), + ) + .slice(0, 5); return (

Recent Tasks

- {recentTasks.length === 0 ? ( + {recentTasks === null ? ( + + ) : recentTasks.length === 0 ? (

No tasks yet

@@ -287,7 +398,9 @@ function OverviewTab({

Missions

- {missions.length === 0 ? ( + {missions === null ? ( + + ) : missions.length === 0 ? (

No missions yet

diff --git a/apps/web/src/spa/pages/projects.spec.tsx b/apps/web/src/spa/pages/projects.spec.tsx index e030fc22..a682293b 100644 --- a/apps/web/src/spa/pages/projects.spec.tsx +++ b/apps/web/src/spa/pages/projects.spec.tsx @@ -51,6 +51,7 @@ afterEach(async () => { document.body.replaceChildren(); root = null; apiMock.mockReset(); + sessionStorage.clear(); }); async function renderProjectsPage(): Promise> { @@ -71,6 +72,22 @@ async function renderProjectsPage(): Promise + candidate.textContent?.includes(text), + ); + if (!button) { + throw new Error(`Button containing "${text}" not found`); + } + button.dispatchEvent(new MouseEvent('click', { bubbles: true })); +} + +async function flushAct(): Promise { + await act(async () => { + await Promise.resolve(); + }); +} + describe('ProjectsPage', () => { it('shows a visible loading state while the project request is in flight', async () => { const deferred = createDeferred(); @@ -91,7 +108,7 @@ describe('ProjectsPage', () => { const router = await renderProjectsPage(); - expect(apiMock).toHaveBeenCalledWith('/api/projects'); + expect(apiMock.mock.calls[0]?.[0]).toBe('/api/projects'); expect(container.textContent).toContain('Mosaic Stack'); expect(container.textContent).toContain('Agent Runtime'); @@ -108,7 +125,7 @@ describe('ProjectsPage', () => { expect(container.textContent).toContain('Project detail target'); }); - it('renders the empty state when the API returns no projects', async () => { + it('renders the empty state only for a verified empty collection', async () => { apiMock.mockResolvedValueOnce([]); await renderProjectsPage(); @@ -117,9 +134,12 @@ describe('ProjectsPage', () => { expect(container.textContent).toContain( 'Projects will appear here when created via the gateway API', ); + expect(container.querySelector('[data-freshness]')?.getAttribute('data-freshness')).toBe( + 'current', + ); }); - it('renders a visible alert when the projects request fails', async () => { + it('renders a failed fetch as an explicit unavailable state, never an empty collection', async () => { apiMock.mockRejectedValueOnce(new Error('Projects are unavailable')); await renderProjectsPage(); @@ -127,5 +147,51 @@ describe('ProjectsPage', () => { const alert = container.querySelector('[role="alert"]'); expect(alert).toBeTruthy(); expect(alert?.textContent).toContain('Projects are unavailable'); + expect(alert?.textContent).toContain('not an empty result'); + + // Negative controls: no healthy empty state and no project cards render + // from a failed fetch. + expect(container.textContent).not.toContain('No projects yet'); + expect(container.textContent).not.toContain('Mosaic Stack'); + expect(container.querySelector('[data-freshness]')?.getAttribute('data-freshness')).toBe( + 'unavailable', + ); + }); + + it('renders an auth failure as unavailable and recovers after retry', async () => { + apiMock + .mockRejectedValueOnce(Object.assign(new Error('Unauthorized'), { statusCode: 401 })) + .mockResolvedValueOnce(projectFixtures); + + await renderProjectsPage(); + + const alert = container.querySelector('[role="alert"]'); + expect(alert?.textContent).toContain('Unauthorized'); + expect(container.textContent).not.toContain('No projects yet'); + + await act(async () => { + clickButtonByText('Retry'); + }); + await flushAct(); + + expect(container.querySelector('[role="alert"]')).toBeNull(); + expect(container.textContent).toContain('Mosaic Stack'); + expect(container.querySelector('[data-freshness]')?.getAttribute('data-freshness')).toBe( + 'current', + ); + }); + + it('renders a schema-mismatched response as unavailable, never as data', async () => { + apiMock.mockResolvedValueOnce({ results: projectFixtures }); + + await renderProjectsPage(); + + const alert = container.querySelector('[role="alert"]'); + expect(alert?.textContent).toContain('not an empty result'); + expect(container.textContent).not.toContain('Mosaic Stack'); + expect(container.textContent).not.toContain('No projects yet'); + expect(container.querySelector('[data-freshness]')?.getAttribute('data-freshness')).toBe( + 'unavailable', + ); }); }); diff --git a/apps/web/src/spa/pages/projects.tsx b/apps/web/src/spa/pages/projects.tsx index 5ab7a746..df0a6e80 100644 --- a/apps/web/src/spa/pages/projects.tsx +++ b/apps/web/src/spa/pages/projects.tsx @@ -1,53 +1,51 @@ -import { useEffect, useState, type ReactElement } from 'react'; +import { type ReactElement } from 'react'; import { useNavigate } from 'react-router-dom'; import { ProjectCard } from '@/components/projects/project-card'; +import { StaleDataNotice, UnavailableDataNotice } from '@/components/freshness/freshness-notices'; import { api } from '@/lib/api'; import type { Project } from '@/lib/types'; -import { getErrorMessage } from './page-errors'; +import { useFreshCollection, describeFailure } from '@/lib/freshness/use-fresh-collection'; +import { validateProjectCollection } from '@/lib/freshness/validators'; export function ProjectsPage(): ReactElement { const navigate = useNavigate(); - const [projects, setProjects] = useState([]); - const [loading, setLoading] = useState(true); - const [error, setError] = useState(null); - - useEffect(() => { - let cancelled = false; - - void api('/api/projects') - .then((response) => { - if (cancelled) return; - setProjects(response); - }) - .catch((caught: unknown) => { - if (cancelled) return; - setError(getErrorMessage(caught, 'Failed to load projects.')); - }) - .finally(() => { - if (cancelled) return; - setLoading(false); - }); - - return () => { - cancelled = true; - }; - }, []); + const projects = useFreshCollection({ + source: 'gateway:/api/projects', + fetcher: (signal) => api('/api/projects', { signal }), + validate: validateProjectCollection, + // Projects carry workspace identity (userId) that is only knowable from + // the payload itself, so a restored entry cannot be scope-checked before + // display. Conservative choice: no last-known restore for this surface; + // cross-workspace switching is still invalidated at verification time. + }); + const retry = (): void => { + void projects.revalidate(); + }; return ( -
+

Projects

- {error ? ( -
- {error} + {projects.freshness === 'stale' && projects.snapshot ? ( +
+
) : null} - {loading ? ( + {projects.freshness === 'unknown' ? (

Loading projects...

- ) : projects.length === 0 ? ( + ) : projects.freshness === 'unavailable' ? ( + + ) : projects.data !== null && projects.data.length === 0 ? (

No projects yet

@@ -56,7 +54,7 @@ export function ProjectsPage(): ReactElement {

) : (
- {projects.map((project) => ( + {(projects.data ?? []).map((project) => ( ({ apiMock: vi.fn(), @@ -48,6 +51,7 @@ afterEach(async () => { document.body.replaceChildren(); root = null; apiMock.mockReset(); + sessionStorage.clear(); }); async function renderTasksPage(): Promise { @@ -72,6 +76,13 @@ function clickButtonByText(text: string): void { button.dispatchEvent(new MouseEvent('click', { bubbles: true })); } +/** Flush pending promise callbacks inside the act environment. */ +async function flushAct(): Promise { + await act(async () => { + await Promise.resolve(); + }); +} + describe('TasksPage', () => { it('shows a visible loading state before the tasks request settles', async () => { const deferred = createDeferred(); @@ -132,7 +143,7 @@ describe('TasksPage', () => { expect(container.textContent).toContain('Wire list and kanban modal interactions'); }); - it('renders a visible alert when the tasks request fails', async () => { + it('renders a failed fetch as an explicit unavailable state, never an empty healthy board', async () => { apiMock.mockRejectedValueOnce(new Error('Tasks request failed')); await renderTasksPage(); @@ -140,5 +151,80 @@ describe('TasksPage', () => { const alert = container.querySelector('[role="alert"]'); expect(alert).toBeTruthy(); expect(alert?.textContent).toContain('Tasks request failed'); + expect(alert?.textContent).toContain('not an empty result'); + + // Negative controls: no board, no healthy empty-state markers, and the + // surface is marked unavailable rather than current. + expect(container.textContent).not.toContain('Not Started'); + expect(container.textContent).not.toContain('No tasks'); + expect(container.querySelector('[data-freshness]')?.getAttribute('data-freshness')).toBe( + 'unavailable', + ); + }); + + it('recovers to a current board after retrying a failed fetch', async () => { + apiMock + .mockRejectedValueOnce(new Error('Tasks request failed')) + .mockResolvedValueOnce(taskFixtures); + + await renderTasksPage(); + expect(container.querySelector('[role="alert"]')).toBeTruthy(); + + await act(async () => { + clickButtonByText('Retry'); + }); + await flushAct(); + + expect(container.querySelector('[role="alert"]')).toBeNull(); + expect(container.textContent).toContain('Not Started'); + expect(container.querySelector('[data-freshness]')?.getAttribute('data-freshness')).toBe( + 'current', + ); + }); + + it('labels restored last-known data as stale with source, version, and age until verified', async () => { + // Seed a last-known snapshot fetched five minutes ago; the page must + // render it only under an explicit staleness label while the fetch is + // still in flight. + const restored = acceptSnapshot({ + value: taskFixtures, + validate: validateTaskCollection, + previous: null, + policy: DEFAULT_FRESHNESS_POLICY, + source: 'gateway:/api/tasks', + now: Date.now() - 5 * 60_000, + }); + if (restored.outcome !== 'accepted') throw new Error('fixture setup failed'); + writeSnapshotCache('tasks', restored.snapshot); + + const deferred = createDeferred(); + apiMock.mockReturnValueOnce(deferred.promise); + + await renderTasksPage(); + + expect(container.querySelector('[data-freshness]')?.getAttribute('data-freshness')).toBe( + 'stale', + ); + const banner = container.querySelector('[role="status"]'); + expect(banner?.textContent).toContain('last-known'); + expect(banner?.textContent).toContain('may be out of date'); + expect(banner?.textContent).toContain('gateway:/api/tasks'); + expect(banner?.textContent).toContain('snapshot v1'); + expect(banner?.textContent).toContain('5m ago'); + + // Last-known data still renders as situational awareness under the label. + expect(container.textContent).toContain('Route /tasks'); + expect(container.textContent).not.toContain('Loading tasks...'); + + // Verification lands: the banner clears and the surface becomes current. + await act(async () => { + deferred.resolve(taskFixtures); + await deferred.promise; + }); + + expect(container.querySelector('[role="status"]')).toBeNull(); + expect(container.querySelector('[data-freshness]')?.getAttribute('data-freshness')).toBe( + 'current', + ); }); }); diff --git a/apps/web/src/spa/pages/tasks.tsx b/apps/web/src/spa/pages/tasks.tsx index b388ba95..ab5b0bb2 100644 --- a/apps/web/src/spa/pages/tasks.tsx +++ b/apps/web/src/spa/pages/tasks.tsx @@ -1,45 +1,32 @@ -import { useEffect, useState, type ReactElement } from 'react'; +import { useState, type ReactElement } from 'react'; import { KanbanBoard } from '@/components/tasks/kanban-board'; import { TaskDetailModal } from '@/components/tasks/task-detail-modal'; import { TaskListView } from '@/components/tasks/task-list-view'; +import { StaleDataNotice, UnavailableDataNotice } from '@/components/freshness/freshness-notices'; import { api } from '@/lib/api'; import { cn } from '@/lib/cn'; import type { Task } from '@/lib/types'; -import { getErrorMessage } from './page-errors'; +import { useFreshCollection, describeFailure } from '@/lib/freshness/use-fresh-collection'; +import { validateTaskCollection } from '@/lib/freshness/validators'; type ViewMode = 'list' | 'kanban'; export function TasksPage(): ReactElement { - const [tasks, setTasks] = useState([]); + const tasks = useFreshCollection({ + source: 'gateway:/api/tasks', + fetcher: (signal) => api('/api/tasks', { signal }), + validate: validateTaskCollection, + cacheKey: 'tasks', + }); const [view, setView] = useState('kanban'); - const [loading, setLoading] = useState(true); - const [error, setError] = useState(null); const [selectedTask, setSelectedTask] = useState(null); - useEffect(() => { - let cancelled = false; - - void api('/api/tasks') - .then((response) => { - if (cancelled) return; - setTasks(response); - }) - .catch((caught: unknown) => { - if (cancelled) return; - setError(getErrorMessage(caught, 'Failed to load tasks.')); - }) - .finally(() => { - if (cancelled) return; - setLoading(false); - }); - - return () => { - cancelled = true; - }; - }, []); + const retry = (): void => { + void tasks.revalidate(); + }; return ( -
+

Tasks

@@ -70,18 +57,24 @@ export function TasksPage(): ReactElement {
- {error ? ( -
- {error} + {tasks.freshness === 'stale' && tasks.snapshot ? ( +
+
) : null} - {loading ? ( + {tasks.freshness === 'unknown' ? (

Loading tasks...

+ ) : tasks.freshness === 'unavailable' ? ( + ) : view === 'kanban' ? ( - + ) : ( - + )} {selectedTask ? (