feat(ri-050): RI-5-001 typed freshness states and stale-safe Mission Control surfaces (#1275) (#1300)

2026-08-18 05:56:58 +00:00
parent d92de53399
commit 7c7dab3898
15 changed files with 2525 additions and 188 deletions
@@ -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<InvalidationReason, string> = {
+  '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<T> {
+  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<T> {
+  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<string, unknown>)
+    .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<T> =
+  | { readonly outcome: 'accepted'; readonly snapshot: FreshSnapshot<T> }
+  | { readonly outcome: 'invalidated'; readonly reason: InvalidationReason };
+
+export interface AcceptSnapshotOptions<T> {
+  /** Raw fetched value (untrusted JSON). */
+  readonly value: unknown;
+  /** Schema validator; returns `null` when the value does not match. */
+  readonly validate: (value: unknown) => FreshPayload<T> | null;
+  /** Previously accepted snapshot for this surface, if any. */
+  readonly previous: FreshSnapshot<T> | 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<T>(options: AcceptSnapshotOptions<T>): AcceptSnapshotResult<T> {
+  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<T> = {
+    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<unknown> | 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;
+}