Hacktoberfest 2026: as issues que os mantenedores marcaram para outubro, abertas e boas para iniciantes. Ver issues do Hacktoberfest

Design safe offline subset reuse and remaining managed-cache recovery contracts

Aberta
  • Algo errado?
#2,102 0 comentários 1 reação 0 responsáveis Ver no GitHub

Mantenedores costumam responder em até 1 dia

Ninguém assumiu esta issue ainda.

Avaliação

Dificuldade
5/5
Tempo estimado
Mais de uma semana
Facilidade para iniciantes
5/100
Tipo de issue
Funcionalidade
Clareza
Precisa de esclarecimento
Status de atividade
Ativa
Stack de tecnologia
electron, typescript
Domínio
data-engineering

Direção de pesquisa

This is a multi-part design issue, not a starting task: the work spans Electric snapshot cursors, the persisted cache wrapper, SQLite durability and legacy storage. Read the linked PR #2069 and issue #2056 first to see the boundary text they establish. Done means a separate, reviewed design per item with its oracle and test coverage, not a single patch.

Escrita pelo modelo de indexação a partir do texto da issue.

Descrição

Problem

PR #2069 makes an invalid on-demand cache safe: it rotates the persisted cache generation and reacquires active subsets. This prevents stale rows from entering a new run, but it does not make a partial Electric cache an authoritative offline snapshot. A later cold start can need the network again. The PR also deliberately leaves several provider, upgrade, and settlement boundaries explicit. Track those product improvements together so each can get a separate design and implementation PR without weakening the safety law.

Work to design and implement

  1. Certify reusable Electric subsets. Define durable evidence for which predicate/window a source snapshot covers, whether it is exhausted, and which deletes or invalidations have been applied. Specify how overlapping subsets combine, how resume metadata ties to that evidence, and when evidence is revoked. On an offline cold start, publish only rows justified by still-valid coverage. Preserve the current rule that an uncertified partial cache rotates and fetches demanded subsets. Include warm and expired peer runs, empty snapshots, deletes, changed shape identity, and overlapping demands.
  2. Harden provider-controlled recovery hooks. PR #2069 now lets a custom on-demand source omit restartAfterScopedRecovery: the persistence wrapper retires its old callbacks, cleans up that source session, rotates the cache, and reenters sync. Its controlled oracle and a real SQLite expiry test cover that path. For providers that implement their own hook, define and test when they retire callbacks, settle or reject outstanding demands, start new acquisitions, and fence late results after rotation. Include multi-tab and native-host receiving histories.
  3. Choose a cross-version policy for legacy storage. The first new-format generation uses a different physical ID, so an older tab can still write to legacy tables. Specify the supported mixed-version window and the evidence that makes legacy storage safe to reclaim. Test an old writer racing an upgrade and a later cleanup, including process/tab crashes. Do not infer safety from a schema-version bump alone.
  4. Resolve publication versus durability after claim expiry. A claim can expire after core publishes a source row but before SQLite accepts its durable write; the receipt then rejects and the Collection fails terminally. Decide whether that fail-stop result is the contract or whether durability-first publication or a defined rollback/reload is required. If recovery is promised, specify caller settlement and public-row observations, then prove the chosen boundary with a real SQLite schedule.
  5. Enable parallel Electric snapshots only with independent cursor authority. The installed SDK currently shares a mutable snapshot cursor, so serialization is required for correctness. Design separate cursor/session ownership or change the SDK protocol before allowing concurrent snapshots. Test stalled and overlapping requests, cancellation, and late responses against the installed SDK.
  6. Reduce recovery code weight. Review the claim, wrapper, and provider recovery states against their oracle laws, remove redundant branches and helpers where a simpler existing boundary can carry the same guarantee, and keep review-evidence artifacts only where they remain useful to maintainers. Measure production and test/documentation diffs separately. Preserve the retirement, lease, and durable-authority witnesses when simplifying.

Completion criteria

  • Record the chosen laws and vocabulary in the cache design, glossary, and user-facing Electric documentation. Distinguish product promises from bounded test evidence.
  • For each changed law, extend the primary independent oracle and a receiving test at the provider/SQLite or host boundary. Include a hostile wrong-design control and state remaining unproved schedules in docs/contributing/oracle-coverage.md.
  • Preserve eager and progressive Collection behavior and the warm peer's valid rows. No stale row may be published or written under a retired claim.
  • Update the PR #2069 boundary text when a follow-up actually lands; this issue does not imply those behaviors already exist.

Related: #2056 and PR #2069.

Linguagem predominante
TypeScript
Estrelas
4k
Forks
277
Merge médio
17h 40min
PRs com merge (30d)
223

Preparar o ambiente

Primeiros passos

  1. Leia a issue inteira e depois o guia de contribuição do projeto.
  2. Comente na issue dizendo que vai assumir — evita que duas pessoas façam o mesmo trabalho.
  3. Faça um fork do repositório e trabalhe em uma branch.
  4. Abra um pull request que referencie o número da issue.

Mais de TanStack/db

Todas as issues de TanStack/db

Issues semelhantes

Mais issues de TypeScript

Receba novas issues na sua caixa de entrada

Um resumo curto de issues do GitHub para quem está começando.