Um mirror read-heavy do Linear, com UI própria sobre um contrato RPC único

Quem escreve no workspace é um time de agentes. O dono precisa ler o que eles fizeram, com uma view model própria, em tempo real. Três fatos da API do Linear impedem fazer isso direto na UI:

• Rate limit por usuário. API key: 2.500 req/h e 3.000.000 pontos/h. OAuth: 5.000 req/h e 2.000.000 pontos/h. Teto de 10.000 pontos por query. Cada tela aberta consumindo a API direto multiplica o gasto.
• Sem realtime público. Subscriptions GraphQL existem no schema, mas não são documentadas nem suportadas. O único canal push é webhook.
• Quatro entidades sem webhook. Organization, Team, WorkflowState e ProjectMilestone só mudam por polling. Colunas de board dependem de WorkflowState.

Sem um mirror, cada tela reimplementa paginação, rate limiting, filtro e controle de staleness. Com o mirror, isso vive num lugar só.

Dois deployables e um wrapper. Processo único no ingest: PubSub em memória, rate limiter com layerStoreMemory, Persistence.layerSql. Sem escala horizontal nesta fase.

Fatia core: 11 entidades. Organization, Team, User, WorkflowState, IssueLabel, Project, ProjectMilestone, Cycle, Issue, Comment, Attachment. Uma tabela por entidade via Model.Class.

Mirror híbrido. Colunas tipadas para o que é consultado ou filtrado, mais uma coluna raw JSONB com o payload inteiro. Três camadas declaradas separadamente: row schema, connection schemas, derived fields (computados no servidor, nunca coluna).

Multi-tenant desde o início. organization_id em toda tabela, payload e reactivity key. Verifica assinatura primeiro, discrimina tenant depois.

Dois tiers mais um adaptativo. Tier frequente para as quatro entidades sem webhook. Tier de segurança para issues. O intervalo adapta por Query.rateLimitStatus.

Cursor defensivo: updatedAt gte com ≥ 60 s de overlap, orderBy: updatedAt explícito, includeArchived: true explícito, dedupe por id no sink, lastSync gravado na mesma transação do batch em sync_state. Schedule: Schedule.spaced(...).pipe(Schedule.jittered).

Subscriptions GraphQL: uma sonda registrada (S-08). Poll é a base.

Dois buckets RateLimiter por token: req/h e pts/h. tokens = complexidade estimada. delay = máximo dos dois. Seed único no cold start por rateLimitStatus; re-seed em qualquer RATELIMITED (HTTP 400 com errors[].extensions.code). X-Complexity da última resposta estima a próxima chamada. Sem adaptiveConsume.

Envelope do Linear: ler errors[] primeiro, porque há sucesso parcial sob HTTP 200. Retryable: network, internal, lock timeout, ratelimited. Não retryable: invalid input, user error, feature not accessible, forbidden, usage limit exceeded. graphql error = drift de schema, alerta.

Sem SSE, sem HttpApi. Um RpcGroup é o único wire entre UI e ingest. Sub-grupo por fatia de domínio, arquivo próprio, RpcGroup.merge na raiz, middleware aplicado depois do merge. Um teste afirma o tamanho do grupo mesclado, porque merge sobrescreve tag duplicada sem erro e .middleware() só cobre os RPCs já adicionados.

Um stream: true por superfície viva. Snapshot RPC só onde a UI precisa de leitura pontual. stream: true força errorSchema = Schema.Never, então stream e snapshot nunca compartilham declaração de erro.

Erros. Um Schema.TaggedError por modo de falha, junto de quem levanta. Uniões por sub-grupo derivadas. Três buckets explícitos: error tipado, defect tipado, die.

Transporte. WebSocket com supportsAck: true como default. HTTP ndjson como fallback registrado. RpcSerialization.layerNdjson nos dois lados, nunca layerJson em stream. Presets nomeados exportados pelo pacote: socket, http-ndjson, in-process.

Parâmetros congelados do servidor. concurrency: 16, streamBufferSize: 64, highWaterMark: 4 MiB. Mount por layerProtocolSocket + layer({ concurrency }). Recalibrar depois do bootstrap.

SPA em todo lugar. Sem SSR. TanStack Start com React 19 e @effect/atom-react. React 19 é obrigatório: o binding declara peer react >=19 <20.

Stack de UI: shadcn/ui + Radix, Tailwind v4, @tanstack/react-virtual@3.14.10 para a lista de 10k linhas, TanStack Form v1 1.33.5 com Schema.toStandardSchemaV1. Filtros numa DSL própria, traduzida para SQL local e codificada para IssueFilter quando vai ao Linear.

Scaffold determinístico: npx gitpick TanStack/router/tree/main/examples/react/start-basic apps/web. create @tanstack/start não existe.

Tauri 2.11.5 como shell puro. A webview abre o RpcClient direto contra o ingest público. Sem sidecar, sem réplica local, zero #[tauri::command]. O contrato RPC é o único IPC.

Build: tanstackStart({ spa: { enabled: true, prerender: { outputPath: '/index.html' } } }), frontendDist no output do cliente, devUrl no dev server. Seleção de modo por TAURI_ENV_PLATFORM no vite.config.ts, não por isTauri().

apps/desktop/SECURITY-CONTRACT.md congelado antes do dispatch: origens da webview por plataforma (tauri://localhost no macOS, http://tauri.localhost no Windows), string de connect-src (mínimo ipc: http://ipc.localhost wss://<ingest> https://<ingest>), capabilities, allowlist de CORS no servidor. CSP restritiva desde o primeiro ticket.

CI só macos-latest aarch64 no primeiro ticket. Assinado e notarizado. Updater por latest.json estático. Versão única do app derivada de tag git, compartilhada com a imagem do ingest.

OAuth actor=user com PKCE para tudo que é user-facing. O usuário vê só o que o Linear deixa. actor=app (client credentials) confinado a reconciliação e write-through.

Access token vive 24 h. Refresh tem 30 min de graça. O token store faz replay dentro da janela e nunca trata refresh falho como logout. O desktop completa o fluxo sem client secret no binário.

Times privados fora: só allPublicTeams: true. CustomView ignorado, o app tem sua própria view model.

Gate é só unit: sete jobs offline. Nada no gate toca a API real do Linear.

Fora do gate: e2e, tauri-e2e, integration-linear (um job serializado contra workspace Free), bundle-compare (só em PR).

Doubles: mock/* via Layer.mock; faker com graphql-faker sobre o SDL pinado; sig com signWebhook(payload, secret); rpc-test com RpcTest.makeClient + AtomRpc.Service({ makeEffect }); pg-test com PGlite/SQLite pelo mesmo SqlClient.

Um bom teste exercita um contrato pelo lado de fora: uma tag RPC, uma interface de serviço, um webhook assinado, uma tabela pelo SqlClient. Nunca afirma sobre wiring interno de Layer.

Observabilidade: OTLP server-side, traces e métricas, propagação de span ligada, sem export do browser. Sete métricas: webhook_received_total{event}, webhook_ack_duration_ms, webhook_signature_invalid_total, rpc_inflight, rpc_duration_ms{tag}, reconcile_lag_seconds, store_write_duration_ms.

Quem constrói são agentes executores, um por unidade, em paralelo. Para isso, todo ticket depende só de contratos congelados. Não existe roadmap temporal. A ordem abaixo é ordem de dependência.

Arestas sequenciais só onde um dado real flui: MIGRATION ← SCHEMA (lista de colunas), REPO ← SCHEMA (tipagem). A aresta REPO → WEBHOOK/RECONCILE foi removida por decisão do dono: o gate usa mock/{Entity}Store. Cross-track: I-07 ← I-06, W-05 ← W-16, W-09 ← I-20, W-14 ← W-03, T-06 ← T-05, Q-06 ← C-01.

Cada brief nomeia o arquivo de referência no clone da Effect que o executor deve ler. ai-docs cobre sql, http-server, testing e schedule, mas não cobre rpc, httpapi nem reactivity. Para esses, a referência são os testes e fixtures do repo. Sem isso, o agente inventa a API. Foi o que produziu 11 símbolos errados nos relatórios web anteriores.

Docs só dos clones locais em lib-docs-raw/, na tag ou commit pinado: effect @ 9642776, router @ ebf13ed, effect-atom @ 60bcae0, tauri @ tauri-v2.11.5.