@proulr/bff-core 0.1.12 → 0.1.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proulr/bff-core",
-  "version": "0.1.12",
+  "version": "0.1.15",
   "type": "module",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
@@ -33,8 +33,8 @@
   },
   "dependencies": {
     "@hono/node-server": "^1.19.6",
-    "@proulr/rosetta": "^0.1.70",
-    "@proulr/sdui-contract": "^0.1.17",
+    "@proulr/rosetta": "^0.1.80",
+    "@proulr/sdui-contract": "^0.1.21",
     "@supabase/supabase-js": "^2.107.0",
     "dotenv": "^16.6.1",
     "hono": "^4.10.6",

package/src/index.integration.test.ts

@@ -1,4 +1,5 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { gunzipSync } from 'node:zlib';
 
 type ServeCallback = (info: { address: string; family: string; port: number }) => void;
 
@@ -14,28 +15,49 @@ vi.mock('@hono/node-server', () => ({
 
 import { createSduiBff } from './index';
 
+/** Contador de builders por screenId — prova reuso de cache e escopo do purge. */
+const buildCounts: Record<string, number> = {};
+
 function createTestApp(overrides?: {
   metricsEnv?: string;
+  ttlEnv?: string;
   actions?: Parameters<typeof createSduiBff>[0]['actions'];
 }) {
   if (overrides?.metricsEnv !== undefined) {
     vi.stubEnv('BFF_METRICS', overrides.metricsEnv);
   }
+  if (overrides?.ttlEnv !== undefined) {
+    vi.stubEnv('BFF_SCREEN_CACHE_TTL_MS', overrides.ttlEnv);
+  }
+  Object.keys(buildCounts).forEach((key) => delete buildCounts[key]);
   return createSduiBff({
     name: 'Integration BFF',
     port: 9999,
     bffId: 'integration-bff',
     screens: {
-      'demo.home': async (ctx) => ({
-        schema_version: 1,
-        screen_id: 'demo.home',
-        blocks: [],
-        data: {
-          auth_token: ctx.authToken ?? null,
-          locale: ctx.query?.locale ?? null,
-        },
-        meta: { bff: 'integration-bff' },
-      }),
+      'demo.home': async (ctx) => {
+        buildCounts['demo.home'] = (buildCounts['demo.home'] ?? 0) + 1;
+        return {
+          schema_version: 1,
+          screen_id: 'demo.home',
+          blocks: [],
+          data: {
+            auth_token: ctx.authToken ?? null,
+            locale: ctx.query?.locale ?? null,
+          },
+          meta: { bff: 'integration-bff' },
+        };
+      },
+      // Acima do threshold (1 KB) do hono/compress — corpo pequeno é servido identity.
+      'demo.big': async () => {
+        buildCounts['demo.big'] = (buildCounts['demo.big'] ?? 0) + 1;
+        return {
+          schema_version: 1,
+          screen_id: 'demo.big',
+          blocks: [],
+          data: { filler: 'proulr-'.repeat(400) },
+        };
+      },
     },
     actions: overrides?.actions ?? {
       ping: async (_ctx, body) => ({ echo: body }),
@@ -68,7 +90,7 @@ describe('createSduiBff HTTP integration', () => {
       ok: true,
       bff: 'integration-bff',
       name: 'Integration BFF',
-      screens: ['demo.home'],
+      screens: ['demo.home', 'demo.big'],
       metrics_enabled: true,
     });
   });
@@ -84,6 +106,116 @@ describe('createSduiBff HTTP integration', () => {
     expect(body.data).toMatchObject({ auth_token: 'tok-abc', locale: 'pt-BR' });
   });
 
+  it('reuses the cached wire within the default TTL and answers 304 on If-None-Match', async () => {
+    const { app } = createTestApp();
+
+    const first = await app.request('/v1/screens/demo.home', {
+      headers: { Authorization: 'Bearer tok-reuse' },
+    });
+    const etag = first.headers.get('ETag');
+    expect(etag).toMatch(/^W\/"/);
+    expect(buildCounts['demo.home']).toBe(1);
+
+    const second = await app.request('/v1/screens/demo.home', {
+      headers: { Authorization: 'Bearer tok-reuse' },
+    });
+    expect(second.status).toBe(200);
+    expect(buildCounts['demo.home']).toBe(1);
+    await expect(second.json()).resolves.toMatchObject({ screen_id: 'demo.home' });
+
+    const conditional = await app.request('/v1/screens/demo.home', {
+      headers: { Authorization: 'Bearer tok-reuse', 'If-None-Match': etag ?? '' },
+    });
+    expect(conditional.status).toBe(304);
+    expect(conditional.headers.get('ETag')).toBe(etag);
+    await expect(conditional.text()).resolves.toBe('');
+    expect(buildCounts['demo.home']).toBe(1);
+  });
+
+  it('does not reuse the cache when BFF_SCREEN_CACHE_TTL_MS=0', async () => {
+    const { app } = createTestApp({ ttlEnv: '0' });
+
+    await app.request('/v1/screens/demo.home', { headers: { Authorization: 'Bearer tok-0' } });
+    await app.request('/v1/screens/demo.home', { headers: { Authorization: 'Bearer tok-0' } });
+    expect(buildCounts['demo.home']).toBe(2);
+  });
+
+  it('compresses a screen above the threshold and marks it as varying by encoding', async () => {
+    const { app } = createTestApp();
+    const response = await app.request('/v1/screens/demo.big', {
+      headers: { 'Accept-Encoding': 'gzip' },
+    });
+
+    expect(response.status).toBe(200);
+    expect(response.headers.get('Content-Encoding')).toBe('gzip');
+    expect(response.headers.get('Vary')).toContain('Accept-Encoding');
+
+    const bytes = new Uint8Array(await response.arrayBuffer());
+    const json = JSON.parse(gunzipSync(bytes).toString('utf8')) as {
+      screen_id: string;
+      data: { filler: string };
+    };
+    expect(json.screen_id).toBe('demo.big');
+    expect(json.data.filler).toHaveLength('proulr-'.repeat(400).length);
+  });
+
+  it('leaves an identity response uncompressed when the client accepts nothing', async () => {
+    const { app } = createTestApp();
+    const response = await app.request('/v1/screens/demo.big');
+    expect(response.headers.get('Content-Encoding')).toBeNull();
+    await expect(response.json()).resolves.toMatchObject({ screen_id: 'demo.big' });
+  });
+
+  it('purges only the declared screen and the author, not the whole park', async () => {
+    const actionHandler = vi.fn(async () => ({
+      ok: true,
+      invalidated_screen_ids: ['demo.big'],
+    }));
+    const { app } = createTestApp({ actions: { 'social.like': actionHandler } });
+
+    // autor (tok-author) e outra pessoa (tok-other) com as duas telas em cache
+    for (const token of ['tok-author', 'tok-other']) {
+      for (const screenId of ['demo.home', 'demo.big']) {
+        await app.request(`/v1/screens/${screenId}`, {
+          headers: { Authorization: `Bearer ${token}` },
+        });
+      }
+    }
+    expect(buildCounts).toEqual({ 'demo.home': 2, 'demo.big': 2 });
+
+    await app.request('/v1/actions/social.like', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', Authorization: 'Bearer tok-author' },
+      body: JSON.stringify({ post_id: 'p1' }),
+    });
+
+    // demo.big caiu para todo o parque; demo.home só para o autor.
+    await app.request('/v1/screens/demo.big', { headers: { Authorization: 'Bearer tok-other' } });
+    expect(buildCounts['demo.big']).toBe(3);
+
+    await app.request('/v1/screens/demo.home', { headers: { Authorization: 'Bearer tok-other' } });
+    expect(buildCounts['demo.home']).toBe(2);
+
+    await app.request('/v1/screens/demo.home', { headers: { Authorization: 'Bearer tok-author' } });
+    expect(buildCounts['demo.home']).toBe(3);
+  });
+
+  it('does not echo the reserved invalidated_screen_ids key in the action response', async () => {
+    const { app } = createTestApp({
+      actions: {
+        'social.like': async () => ({ ok: true, likes: 3, invalidated_screen_ids: ['demo.home'] }),
+      },
+    });
+    const response = await app.request('/v1/actions/social.like', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: '{}',
+    });
+    const body = await response.json();
+    expect(body).toMatchObject({ ok: true, action_id: 'social.like', likes: 3 });
+    expect(body).not.toHaveProperty('invalidated_screen_ids');
+  });
+
   it('ignores non-Bearer Authorization header', async () => {
     const { app } = createTestApp();
     const response = await app.request('/v1/screens/demo.home', {

package/src/index.ts

@@ -1,11 +1,18 @@
 import { randomUUID } from 'node:crypto';
 import { serve } from '@hono/node-server';
 import { Hono } from 'hono';
+import { compress } from 'hono/compress';
 import { cors } from 'hono/cors';
 import type { SduiScreenBuilder, SduiScreenBuilderContext } from '@proulr/sdui-contract';
 import { createBffMetrics, isBffMetricsEnabled } from './bff-metrics';
 import { ScreenResponseCache, buildScreenCacheKey } from './screen-response-cache';
 
+/**
+ * Handler de action. O retorno é mesclado no JSON de resposta, com uma chave
+ * reservada: `invalidated_screen_ids?: string[]` lista as telas cujo cache o BFF
+ * sabe alterado por esta escrita (ex.: `feed.social` num like). A chave nunca é
+ * devolvida ao cliente.
+ */
 export type SduiActionHandler = (
   ctx: SduiScreenBuilderContext,
   body: Record<string, unknown>,
@@ -41,15 +48,32 @@ function resolveScreenId(path: string): string {
   return 'other';
 }
 
+/**
+ * Freshness default em vez de 0: com TTL zerado o cache só faz coalescing de
+ * in-flight, então cada revalidação do app reconstrói o wire no builder. 5 s é o
+ * orçamento em que um like/mensagem atrasa sem o usuário perceber e o round-trip
+ * condicional (304) deixa de custar CPU. `BFF_SCREEN_CACHE_TTL_MS=0` continua
+ * desligando o cache para quem precisar de leitura fortemente consistente.
+ */
+const DEFAULT_SCREEN_CACHE_TTL_MS = 5000;
+
+function resolveScreenCacheTtlMs(): number {
+  const configured = Number(process.env.BFF_SCREEN_CACHE_TTL_MS);
+  return Number.isFinite(configured) && configured >= 0
+    ? configured
+    : DEFAULT_SCREEN_CACHE_TTL_MS;
+}
+
 export function createSduiBff(options: CreateSduiBffOptions) {
   const app = new Hono();
   const metricsEnabled = isBffMetricsEnabled();
   const metrics = metricsEnabled ? createBffMetrics(options.bffId) : null;
-  const screenCache = new ScreenResponseCache(
-    Number(process.env.BFF_SCREEN_CACHE_TTL_MS ?? 0) || 0,
-  );
+  const screenCache = new ScreenResponseCache(resolveScreenCacheTtlMs());
 
   app.use('*', cors());
+  // O túnel cloudflared vai na porta do BFF sem Caddy no caminho, então a
+  // compressão tem que nascer aqui — é o único salto que cruza a internet.
+  app.use('*', compress());
 
   app.use('*', async (c, next) => {
     const requestId = randomUUID();
@@ -116,16 +140,22 @@ export function createSduiBff(options: CreateSduiBffOptions) {
       cacheKey,
       async () => builder(buildContext({}, query, authToken)),
       c.req.header('If-None-Match'),
+      { screenId, authToken },
     );
 
+    // O body é sempre identity aqui; hono/compress escolhe o encoding depois. Sem
+    // Vary, qualquer borda compartilhada serviria gzip para quem pediu identity.
+    const vary = { Vary: 'Accept-Encoding' };
+
     if (hit.notModified) {
-      return c.newResponse(null, 304, { ETag: hit.entry.etag });
+      return c.newResponse(null, 304, { ETag: hit.entry.etag, ...vary });
     }
 
     return c.body(hit.entry.body, 200, {
       'Content-Type': 'application/json; charset=utf-8',
       ETag: hit.entry.etag,
       'Cache-Control': 'private, no-cache',
+      ...vary,
     });
   });
 
@@ -146,8 +176,16 @@ export function createSduiBff(options: CreateSduiBffOptions) {
     try {
       const authToken = readAuthToken(c.req.header('Authorization'));
       const result = await handler(buildContext({}, {}, authToken), body);
-      screenCache.purgeAll();
-      return c.json({ ok: true, action_id: actionId, ...result });
+      // `invalidated_screen_ids` é a tela que o BFF dono sabe ter mudado. Sem
+      // lista, só o token do autor é purgado — `purgeAll()` derrubava o cache de
+      // todas as telas de todo o parque a cada like.
+      const { invalidated_screen_ids: invalidatedScreenIds, ...payload } = result;
+      const screens = Array.isArray(invalidatedScreenIds)
+        ? invalidatedScreenIds.filter((screenId): screenId is string => typeof screenId === 'string')
+        : [];
+      screenCache.invalidateScreens(screens);
+      screenCache.invalidateToken(authToken);
+      return c.json({ ok: true, action_id: actionId, ...payload });
     } catch (error) {
       console.warn(`[${options.bffId}] action ${actionId} failed`, error);
       return c.json(
@@ -178,8 +216,11 @@ export {
   ScreenResponseCache,
   buildScreenCacheKey,
   computeScreenEtag,
+  computeScreenRevision,
   type ScreenCacheEntry,
   type ScreenCacheHit,
+  type ScreenCacheKeyInput,
+  type ScreenCacheScopeInput,
 } from './screen-response-cache';
 export {
   buildNativeAdInsertionSeed,

package/src/screen-response-cache.test.ts

@@ -3,8 +3,13 @@ import {
   ScreenResponseCache,
   buildScreenCacheKey,
   computeScreenEtag,
+  computeScreenRevision,
 } from './screen-response-cache';
 
+function parseBody(body: string): Record<string, unknown> {
+  return JSON.parse(body) as Record<string, unknown>;
+}
+
 describe('buildScreenCacheKey', () => {
   it('is stable regardless of query insertion order', () => {
     const a = buildScreenCacheKey({
@@ -63,8 +68,41 @@ describe('ScreenResponseCache', () => {
 
     const [h1, h2] = await Promise.all([p1, p2]);
     expect(calls).toBe(1);
-    expect(h1.entry.body).toBe('{"ok":true}');
-    expect(h2.entry.body).toBe('{"ok":true}');
+    expect(h1.entry.body).toContain('"ok":true');
+    expect(h2.entry.body).toBe(h1.entry.body);
+  });
+
+  it('stamps meta.rev with the same digest as the weak ETag', async () => {
+    const cache = new ScreenResponseCache(5_000);
+    const wire = { schema_version: 1, screen_id: 'feed.social', blocks: [] };
+    const hit = await cache.get('k', async () => wire);
+
+    const rev = (parseBody(hit.entry.body).meta as { rev: string }).rev;
+    expect(hit.entry.etag).toBe(`W/"${rev}"`);
+    // O digest é do wire antes da injeção — o corpo final não é a fonte do rev.
+    expect(rev).toBe(computeScreenRevision(JSON.stringify(wire)));
+  });
+
+  it('keeps the rev stable for identical content and rotates it when the wire changes', async () => {
+    const cache = new ScreenResponseCache(0);
+    let n = 0;
+    const build = async () => ({ screen_id: 'feed.social', n: ++n });
+
+    const first = await cache.get('k', build);
+    const second = await cache.get('k', build);
+    const firstRev = (parseBody(first.entry.body).meta as { rev: string }).rev;
+    const secondRev = (parseBody(second.entry.body).meta as { rev: string }).rev;
+    expect(secondRev).not.toBe(firstRev);
+
+    const twin = await cache.get('k2', async () => ({ screen_id: 'feed.social', n: 2 }));
+    expect((parseBody(twin.entry.body).meta as { rev: string }).rev).toBe(secondRev);
+  });
+
+  it('leaves a non-object payload untouched', async () => {
+    const cache = new ScreenResponseCache(5_000);
+    const hit = await cache.get('k', async () => 'plain');
+    expect(hit.entry.body).toBe('"plain"');
+    expect(hit.entry.etag).toBe(computeScreenEtag('"plain"'));
   });
 
   it('rebuilds after completion when ttl is 0', async () => {
@@ -75,7 +113,7 @@ describe('ScreenResponseCache', () => {
     await cache.get('k', build);
     const second = await cache.get('k', build);
     expect(calls).toBe(2);
-    expect(second.entry.body).toBe('{"n":2}');
+    expect(parseBody(second.entry.body).n).toBe(2);
   });
 
   it('serves fresh entries within ttl and flags matching etag as not modified', async () => {
@@ -121,6 +159,78 @@ describe('ScreenResponseCache', () => {
     expect(calls).toBe(2);
   });
 
+  it('invalidateToken drops only that user entries', async () => {
+    let calls = 0;
+    const build = async () => ({ n: ++calls });
+    const cache = new ScreenResponseCache(5_000);
+
+    const authorKey = buildScreenCacheKey({ screenId: 'feed.social', query: {}, authToken: 'A' });
+    const otherKey = buildScreenCacheKey({ screenId: 'feed.social', query: {}, authToken: 'B' });
+    await cache.get(authorKey, build, null, { screenId: 'feed.social', authToken: 'A' });
+    await cache.get(otherKey, build, null, { screenId: 'feed.social', authToken: 'B' });
+    expect(calls).toBe(2);
+
+    cache.invalidateToken('A');
+
+    // O autor reconstrói; a entrada do outro usuário continua no cache.
+    await cache.get(authorKey, build, null, { screenId: 'feed.social', authToken: 'A' });
+    expect(calls).toBe(3);
+    await cache.get(otherKey, build, null, { screenId: 'feed.social', authToken: 'B' });
+    expect(calls).toBe(3);
+  });
+
+  it('invalidateToken also clears the anonymous scope', async () => {
+    let calls = 0;
+    const build = async () => ({ n: ++calls });
+    const cache = new ScreenResponseCache(5_000);
+    const key = buildScreenCacheKey({ screenId: 'vibes.home', query: {} });
+
+    await cache.get(key, build, null, { screenId: 'vibes.home' });
+    cache.invalidateToken(undefined);
+    await cache.get(key, build, null, { screenId: 'vibes.home' });
+    expect(calls).toBe(2);
+  });
+
+  it('invalidateScreens drops the screen for every token and ignores an empty list', async () => {
+    let calls = 0;
+    const build = async () => ({ n: ++calls });
+    const cache = new ScreenResponseCache(5_000);
+    const keyA = buildScreenCacheKey({ screenId: 'feed.social', query: {}, authToken: 'A' });
+    const keyB = buildScreenCacheKey({ screenId: 'feed.social', query: {}, authToken: 'B' });
+    const otherKey = buildScreenCacheKey({ screenId: 'chat.inbox', query: {}, authToken: 'A' });
+
+    await cache.get(keyA, build, null, { screenId: 'feed.social', authToken: 'A' });
+    await cache.get(keyB, build, null, { screenId: 'feed.social', authToken: 'B' });
+    await cache.get(otherKey, build, null, { screenId: 'chat.inbox', authToken: 'A' });
+    expect(calls).toBe(3);
+
+    cache.invalidateScreens([]);
+    await cache.get(keyA, build, null, { screenId: 'feed.social', authToken: 'A' });
+    expect(calls).toBe(3);
+
+    cache.invalidateScreens(['feed.social']);
+    await cache.get(keyA, build, null, { screenId: 'feed.social', authToken: 'A' });
+    await cache.get(keyB, build, null, { screenId: 'feed.social', authToken: 'B' });
+    expect(calls).toBe(5);
+    await cache.get(otherKey, build, null, { screenId: 'chat.inbox', authToken: 'A' });
+    expect(calls).toBe(5);
+  });
+
+  it('forgotten scopes evicted with their entries do not break invalidation', async () => {
+    let calls = 0;
+    const build = async () => ({ n: ++calls });
+    const cache = new ScreenResponseCache(5_000, 2);
+
+    await cache.get('a', build, null, { screenId: 'feed.social', authToken: 'A' });
+    await cache.get('b', build, null, { screenId: 'chat.inbox', authToken: 'B' });
+    await cache.get('c', build, null, { screenId: 'vibes.home', authToken: 'C' });
+
+    expect(() => {
+      cache.invalidateScreens(['feed.social']);
+      cache.invalidateToken('A');
+    }).not.toThrow();
+  });
+
   it('does not cache failures', async () => {
     let calls = 0;
     const build = async () => {
@@ -133,7 +243,7 @@ describe('ScreenResponseCache', () => {
     await expect(cache.get('k', build)).rejects.toThrow('boom');
     const ok = await cache.get('k', build);
     expect(calls).toBe(2);
-    expect(ok.entry.body).toBe('{"ok":true}');
+    expect(parseBody(ok.entry.body).ok).toBe(true);
   });
 
   it('evicts the oldest entries beyond the limit', async () => {

package/src/screen-response-cache.ts

@@ -18,6 +18,24 @@ export type ScreenCacheHit = {
   notModified: boolean;
 };
 
+/**
+ * Domínio de uma entrada, lembrado junto dela para permitir purge sem reconstruir
+ * a chave. O token nunca fica retido cru — só o escopo derivado dele.
+ */
+type ScreenCacheScope = {
+  screenId: string;
+  tokenScope: string;
+};
+
+export type ScreenCacheScopeInput = {
+  screenId: string;
+  authToken?: string;
+};
+
+function hashTokenScope(authToken?: string): string {
+  return createHash('sha256').update(authToken ?? 'anon').digest('base64url');
+}
+
 export function buildScreenCacheKey(input: ScreenCacheKeyInput): string {
   const queryPart = Object.keys(input.query)
     .sort()
@@ -33,18 +51,44 @@ export function buildScreenCacheKey(input: ScreenCacheKeyInput): string {
 }
 
 export function computeScreenEtag(body: string): string {
-  return `W/"${createHash('sha256').update(body).digest('base64url').slice(0, 32)}"`;
+  return `W/"${computeScreenRevision(body)}"`;
+}
+
+/**
+ * Digest do wire que vira duas coisas do mesmo valor: o ETag fraco da resposta e
+ * `meta.rev` dentro do corpo. O app precisa do segundo porque o wire persistido
+ * em AsyncStorage não carrega header HTTP — sem `rev` ele só saberia se mudou
+ * baixando o corpo inteiro.
+ */
+export function computeScreenRevision(body: string): string {
+  return createHash('sha256').update(body).digest('base64url').slice(0, 32);
+}
+
+/**
+ * O digest é do wire **sem** `meta.rev`, senão ele dependeria de si mesmo. Por
+ * isso o hash é feito sobre a serialização original e a chave é injetada depois;
+ * o corpo em cache e o ETag apontam para o mesmo digest.
+ */
+function withRevision(screen: unknown, rev: string): unknown {
+  if (!screen || typeof screen !== 'object' || Array.isArray(screen)) return screen;
+  const meta = (screen as { meta?: unknown }).meta;
+  const metaObject = meta && typeof meta === 'object' && !Array.isArray(meta)
+    ? (meta as Record<string, unknown>)
+    : {};
+  return { ...screen, meta: { ...metaObject, rev } };
 }
 
 /**
  * Dedupes identical in-flight screen builds (the mount/focus revalidation storm
- * fires the same GET 3-4x concurrently). `ttlMs > 0` additionally serves
- * completed results while fresh; keep it low (default 0) so direct client-side
- * writes stay near-real-time.
+ * fires the same GET 3-4x concurrently) and, with `ttlMs > 0`, serves completed
+ * results while fresh. Freshness is bounded by TTL and by the targeted purges
+ * (`invalidateScreens` / `invalidateToken`), never by dropping the whole park's
+ * cache on every write — an action used to invalidate every screen for everyone.
  */
 export class ScreenResponseCache {
   private entries = new Map<string, ScreenCacheEntry>();
   private pending = new Map<string, Promise<ScreenCacheEntry>>();
+  private scopes = new Map<string, ScreenCacheScope>();
 
   constructor(
     private readonly ttlMs: number,
@@ -56,6 +100,7 @@ export class ScreenResponseCache {
     key: string,
     build: () => Promise<unknown>,
     ifNoneMatch?: string | null,
+    scope?: ScreenCacheScopeInput,
   ): Promise<ScreenCacheHit> {
     const fresh = this.entries.get(key);
     if (fresh && fresh.freshUntil > this.now()) {
@@ -71,7 +116,7 @@ export class ScreenResponseCache {
       }));
     }
 
-    const promise = this.buildEntry(key, build);
+    const promise = this.buildEntry(key, build, scope);
     this.pending.set(key, promise);
     return promise.then((entry) => ({
       entry,
@@ -80,23 +125,56 @@ export class ScreenResponseCache {
     }));
   }
 
+  /** Purge de uma tela em todos os queries/tokens — o que uma action declara ter mudado. */
+  invalidateScreens(screenIds: readonly string[]): void {
+    if (screenIds.length === 0) return;
+    const wanted = new Set(screenIds);
+    this.dropWhere((scope) => wanted.has(scope.screenId));
+  }
+
+  /**
+   * Purge do autor da action: quem escreve nunca relê o próprio estado atrasado,
+   * e as telas dos outros usuários continuam pagando só o TTL.
+   */
+  invalidateToken(authToken?: string): void {
+    const tokenScope = hashTokenScope(authToken);
+    this.dropWhere((scope) => scope.tokenScope === tokenScope);
+  }
+
   purgeAll(): void {
     this.entries.clear();
+    this.scopes.clear();
+  }
+
+  private dropWhere(predicate: (scope: ScreenCacheScope) => boolean): void {
+    for (const [key, scope] of this.scopes) {
+      if (!predicate(scope)) continue;
+      this.entries.delete(key);
+      this.scopes.delete(key);
+    }
   }
 
   private async buildEntry(
     key: string,
     build: () => Promise<unknown>,
+    scope?: ScreenCacheScopeInput,
   ): Promise<ScreenCacheEntry> {
     try {
       const screen = await build();
-      const body = JSON.stringify(screen);
+      const rev = computeScreenRevision(JSON.stringify(screen));
+      const body = JSON.stringify(withRevision(screen, rev));
       const entry: ScreenCacheEntry = {
         body,
-        etag: computeScreenEtag(body),
+        etag: `W/"${rev}"`,
         freshUntil: this.now() + this.ttlMs,
       };
       this.entries.set(key, entry);
+      if (scope) {
+        this.scopes.set(key, {
+          screenId: scope.screenId,
+          tokenScope: hashTokenScope(scope.authToken),
+        });
+      }
       this.evictOverflow();
       return entry;
     } finally {
@@ -109,6 +187,7 @@ export class ScreenResponseCache {
       const oldest = this.entries.keys().next().value;
       if (oldest === undefined) break;
       this.entries.delete(oldest);
+      this.scopes.delete(oldest);
     }
   }
 }