@softize/opus 12.4.0 → 12.5.1

package/CHANGELOG.md

@@ -7,6 +7,29 @@ Depois de qualquer bump, rode os gates (`typecheck` · `test` · `opus check` ·
 `opus copy --check` · `base copy check` · `manifest:check`) — eles apontam o que a
 mudança cobra do seu código.
 
+## 12.5.1 — 2026-08-24
+
+`Dock` passa a fazer o roving tabindex que uma `toolbar` promete: a barra tem um único ponto de
+entrada no Tab, e as setas andam entre as ações a partir dele. Antes as setas eram um caminho a
+mais e a barra continuava cobrando um Tab por ícone, que é justamente o que o padrão evita.
+
+A mudança é interna ao componente e não altera a API.
+
+## 12.5.0 — 2026-08-24
+
+Cache vira porta do protocolo. `CacheAdapter` chega aos handlers como `ctx.cache`, com a superfície
+mínima que um handler usa — `get`, `set`, `delete` — e cresce por reincidência, como a do storage.
+O **miss é o `null`**: quem observa a execução distingue acerto de ausência pelo retorno, sem o
+adapter reportar métrica por fora, e erro de infraestrutura continua sendo exceção — cache
+indisponível não deve virar "não estava em cache".
+
+`cache/memory` é o driver de processo, para desenvolvimento e para quem roda numa instância só.
+Expira preguiçosamente (a entrada vencida some quando alguém a procura, sem timer permanente),
+tem teto de entradas para não crescer sem limite dentro de um servidor de longa duração, e expõe
+`sweep()` e `size()` para quem quiser forçar a limpeza ou observar o tamanho.
+
+Nada é obrigatório: sem adapter montado, `ctx.cache` é `null` e o handler decide o que fazer.
+
 ## 12.4.0 — 2026-08-24
 
 Superfícies de trabalho — canvas, editor, preview — ganham os dois lugares que faltavam. `Dock`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softize/opus",
-  "version": "12.4.0",
+  "version": "12.5.1",
   "description": "End-to-end action protocol for TypeScript. Single package with subpath exports (core + adapters).",
   "license": "MIT",
   "type": "module",
@@ -122,6 +122,14 @@
     "./storage": "./src/storage/index.ts",
     "./storage/fs": "./src/storage/drivers/fs.ts",
     "./storage/s3": "./src/storage/drivers/s3.ts",
+    "./cache": {
+      "types": "./src/cache/index.ts",
+      "default": "./src/cache/index.ts"
+    },
+    "./cache/memory": {
+      "types": "./src/cache/drivers/memory.ts",
+      "default": "./src/cache/drivers/memory.ts"
+    },
     "./ai": "./src/ai/index.ts",
     "./ai/anthropic": "./src/ai/drivers/anthropic.ts",
     "./mcp": "./src/mcp/index.ts",

package/src/cache/drivers/memory.ts

@@ -0,0 +1,82 @@
+/**
+ * Driver de cache em memória do processo.
+ *
+ * Serve desenvolvimento e o caso de um único processo. Não compartilha nada entre
+ * instâncias — quem precisa disso usa um driver distribuído, e a troca é só a montagem.
+ *
+ * A expiração é preguiçosa: a entrada vencida some quando alguém a procura. Sem varredura
+ * de fundo, um cache de processo não justifica um timer permanente; `sweep()` existe para
+ * quem quiser forçar a limpeza.
+ */
+import type { CacheAdapter, CacheSetOptions } from '../../core/index.ts'
+
+interface Entry {
+  value: unknown
+  /** Epoch em milissegundos; `null` = não expira. */
+  expiresAt: number | null
+}
+
+export interface MemoryCacheOptions {
+  /** Expiração padrão quando a chamada não passa `ttlSeconds`. Ausente = não expira. */
+  defaultTtlSeconds?: number
+  /** Teto de entradas. Passando dele, a mais antiga sai — um cache de processo não deve
+   *  crescer sem limite dentro de um servidor de longa duração. */
+  maxEntries?: number
+}
+
+export interface MemoryCache extends CacheAdapter {
+  /** Remove as entradas vencidas agora. */
+  sweep(): number
+  /** Quantas entradas o cache guarda neste momento. */
+  size(): number
+}
+
+export function memoryCache(options: MemoryCacheOptions = {}): MemoryCache {
+  const entries = new Map<string, Entry>()
+  const maxEntries = options.maxEntries ?? 10_000
+
+  const expired = (entry: Entry, now: number): boolean => entry.expiresAt !== null && entry.expiresAt <= now
+
+  return {
+    name: 'memory',
+    kind: 'cache',
+    get<T>(key: string): Promise<T | null> {
+      const entry = entries.get(key)
+      if (entry === undefined) return Promise.resolve(null)
+      if (expired(entry, Date.now())) {
+        entries.delete(key)
+        return Promise.resolve(null)
+      }
+      return Promise.resolve(entry.value as T)
+    },
+    set<T>(key: string, value: T, opts: CacheSetOptions = {}): Promise<void> {
+      const ttl = opts.ttlSeconds ?? options.defaultTtlSeconds
+      // Reinserir move a chave para o fim da ordem do Map, que é o que faz o descarte
+      // abaixo tirar a MAIS ANTIGA, e não a que acabou de ser escrita.
+      entries.delete(key)
+      entries.set(key, { value, expiresAt: ttl === undefined ? null : Date.now() + ttl * 1000 })
+      if (entries.size > maxEntries) {
+        const oldest = entries.keys().next()
+        if (!oldest.done) entries.delete(oldest.value)
+      }
+      return Promise.resolve()
+    },
+    delete(key: string): Promise<void> {
+      entries.delete(key)
+      return Promise.resolve()
+    },
+    sweep(): number {
+      const now = Date.now()
+      let removed = 0
+      for (const [key, entry] of entries) {
+        if (expired(entry, now)) {
+          entries.delete(key)
+          removed += 1
+        }
+      }
+      return removed
+    },
+    size: () => entries.size,
+    healthCheck: () => Promise.resolve({ ok: true as const, details: { entries: entries.size } }),
+  }
+}

package/src/cache/index.ts

@@ -0,0 +1,15 @@
+/**
+ * @softize/opus/cache — helpers compartilhados dos drivers de cache.
+ *
+ * EXPERIMENTAL. O contrato (`CacheAdapter`) vive no core; o driver de memória fica em
+ * `cache/memory`. A superfície é a mínima que um handler usa — guardar, ler, remover — e
+ * cresce por reincidência, não por especulação.
+ */
+
+export type { CacheAdapter, CacheSetOptions } from '../core/index.ts'
+
+/** Monta uma chave estável a partir de partes. Evita a concatenação à mão que produz
+ *  chaves parecidas e colidentes entre domínios. */
+export function cacheKey(...parts: (string | number)[]): string {
+  return parts.map((part) => String(part)).join(':')
+}

package/src/core/index.ts

@@ -99,6 +99,8 @@ export type {
   SchedulerAdapter,
   ClientAdapter,
   StorageAdapter,
+  CacheAdapter,
+  CacheSetOptions,
   StoragePutOptions,
   StorageObject,
   AiAdapter,

package/src/core/runtime.ts

@@ -61,6 +61,7 @@ import type {
   SchedulerAdapter,
   ServerAdapter,
   StorageAdapter,
+  CacheAdapter,
   AiAdapter,
   AiRunOptions,
   BoundAiRunOptions,
@@ -97,6 +98,8 @@ export interface RuntimeSetup {
   client?: ClientAdapter
   /** EXPERIMENTAL — storage de objetos (arquivos); chega nos handlers via `ctx.storage`. */
   storage?: StorageAdapter
+  /** EXPERIMENTAL — cache de leitura; chega nos handlers via `ctx.cache`. */
+  cache?: CacheAdapter
   /** EXPERIMENTAL — IA generativa (complete/extract); chega nos handlers via `ctx.ai`. */
   ai?: AiAdapter
 
@@ -243,6 +246,7 @@ export class Runtime {
   private readonly scheduler: SchedulerAdapter | undefined
   private readonly client: ClientAdapter | undefined
   private readonly storage: StorageAdapter | undefined
+  private readonly cache: CacheAdapter | undefined
   private readonly ai: AiAdapter | undefined
   /** Cache das tools derivadas das actions `ai:enabled` (registry é estático pós-start). */
   private aiToolsCache: AiTool[] | null = null
@@ -293,6 +297,7 @@ export class Runtime {
     this.scheduler = setup.scheduler
     this.client = setup.client
     this.storage = setup.storage
+    this.cache = setup.cache
     this.ai = setup.ai
   }
 
@@ -764,6 +769,7 @@ export class Runtime {
     if (this.scheduler !== undefined) yield this.scheduler
     if (this.client !== undefined) yield this.client
     if (this.storage !== undefined) yield this.storage
+    if (this.cache !== undefined) yield this.cache
     if (this.ai !== undefined) yield this.ai
   }
 
@@ -860,6 +866,7 @@ export class Runtime {
       log,
       emit: this.buildEmit(action, actionId, base, trace),
       storage: this.storage ?? null,
+      cache: this.cache ?? null,
       ai: this.bindAi({ ...base, ...(trace !== undefined ? { trace } : {}) }),
       provenance,
       ...(trace !== undefined ? { trace } : {}),
@@ -1192,6 +1199,7 @@ export class Runtime {
       log: reactionLog,
       emit: noopEmit,
       storage: this.storage ?? null,
+      cache: this.cache ?? null,
       // Reação = contexto de sistema; o agente só alcança actions públicas (can nega por
       // padrão — nada de LLM disparado por evento chamando action gated sem gate explícito).
       ai: this.bindAi({

package/src/core/types.ts

@@ -277,6 +277,7 @@ export interface ActionContext {
   log: Logger
   emit: EmitFn
   storage: StorageAdapter | null
+  cache: CacheAdapter | null
   ai: BoundAi | null
   provenance: Provenance
   trace?: TraceContext
@@ -294,6 +295,7 @@ export interface ReactionContext {
   log: Logger
   emit: EmitFn
   storage: StorageAdapter | null
+  cache: CacheAdapter | null
   ai: BoundAi | null
   provenance: Provenance
   trace?: TraceContext
@@ -941,6 +943,7 @@ export type AdapterKind =
   | 'scheduler'
   | 'client'
   | 'storage'
+  | 'cache'
   | 'ai'
   | 'ui'
   | 'schema'
@@ -1167,6 +1170,28 @@ export interface StorageAdapter extends Adapter {
   url(key: string, opts?: { expiresInSeconds?: number }): Promise<string>
 }
 
+/**
+ * EXPERIMENTAL — cache de leitura. A superfície é a mínima que um handler usa e cresce
+ * por reincidência, como a do storage.
+ *
+ * O MISS é o `null`: quem observa a execução distingue acerto de ausência pelo retorno,
+ * sem o adapter precisar reportar métrica por fora. Erro de infraestrutura é outra coisa
+ * e continua sendo exceção — cache indisponível não deve virar "não estava em cache".
+ */
+export interface CacheAdapter extends Adapter {
+  kind: 'cache'
+  /** Valor guardado, ou `null` quando a chave não está presente (ou expirou). */
+  get<T>(key: string): Promise<T | null>
+  /** Guarda o valor. Sem `ttlSeconds`, a expiração é a que o driver definir. */
+  set<T>(key: string, value: T, opts?: CacheSetOptions): Promise<void>
+  /** Remove. Idempotente: remover o que não existe não é erro. */
+  delete(key: string): Promise<void>
+}
+
+export interface CacheSetOptions {
+  ttlSeconds?: number
+}
+
 /** Opções por chamada do `AiAdapter` — tudo tem default do driver. */
 export interface AiCompleteOptions {
   /** System prompt da chamada. */

package/src/testing/index.ts

@@ -43,6 +43,7 @@ import type {
   Paginated,
   Schema,
   StorageAdapter,
+  CacheAdapter,
   StorageObject,
   StoragePutOptions,
   User,
@@ -72,6 +73,7 @@ export interface TestContextOptions {
   can?: ActionContext['can']
   db?: unknown
   storage?: StorageAdapter | null
+  cache?: CacheAdapter | null
   ai?: AiAdapter | null
   meta?: Record<string, unknown>
   trace?: TraceContext
@@ -133,6 +135,7 @@ export function testContext(options: TestContextOptions = {}): TestContext {
       return Promise.resolve()
     },
     storage: options.storage ?? null,
+    cache: options.cache ?? null,
     ai: options.ai ? toBoundAi(options.ai) : null,
     provenance: { kind: 'system', source: 'test' },
     ...(options.trace !== undefined ? { trace: options.trace } : {}),

package/src/ui/components/patterns/dock.tsx

@@ -36,6 +36,18 @@ export interface DockProps {
 export function Dock({ position = 'bottom', label, className, children }: DockProps): React.ReactElement {
   const ref = React.useRef<HTMLDivElement>(null)
 
+  // Roving tabindex: uma toolbar tem UM ponto de entrada no Tab; dentro dela, as setas andam.
+  // Sem isto as setas seriam um caminho a mais, e a barra continuaria cobrando um Tab por ícone.
+  const roving = React.useCallback((focado?: HTMLElement) => {
+    const items = Array.from(ref.current?.querySelectorAll<HTMLButtonElement>('button') ?? [])
+    const entrada = items.find((item) => item === focado) ?? items.find((item) => !item.disabled)
+    for (const item of items) item.tabIndex = item === entrada ? 0 : -1
+  }, [])
+
+  React.useEffect(() => {
+    roving()
+  })
+
   // Navegação de toolbar: as setas andam entre as ações, e Home/End vão às pontas. Sem isso
   // uma barra com dez ícones cobra dez Tabs de quem navega por teclado.
   const onKeyDown = (event: React.KeyboardEvent<HTMLDivElement>): void => {
@@ -54,7 +66,10 @@ export function Dock({ position = 'bottom', label, className, children }: DockPr
           : event.key === 'ArrowRight'
             ? (current + 1) % items.length
             : (current - 1 + items.length) % items.length
-    items[next]?.focus()
+    const alvo = items[next]
+    if (alvo === undefined) return
+    roving(alvo)
+    alvo.focus()
   }
 
   return (
@@ -65,6 +80,7 @@ export function Dock({ position = 'bottom', label, className, children }: DockPr
       aria-label={label}
       aria-orientation="horizontal"
       onKeyDown={onKeyDown}
+      onFocus={(event) => roving(event.target as HTMLElement)}
       className={cn(
         'absolute z-10 flex max-w-[calc(100%-1.5rem)] flex-row items-center gap-1.5 overflow-x-auto',
         'rounded-2xl border border-border bg-background/95 p-1.5 shadow-lg backdrop-blur',