馃搵 Pre-flight Checks
馃攳 Problem Description
Local chunk sync has no single recovery contract for incomplete history. A manifest can reference chunks that are unavailable on the current machine, while existing chunks can contain partial session, prompt, observation, relation, or tombstone history.
The current behavior mixes several decisions: when missing history should be treated as unknown, when local SQLite should re-export idempotently, when import should defer a dependency, when corruption must fail loudly, and how long histories should be scanned without unbounded work. PR #780 experimented with several of these policies while solving #615, but #894 delivered only the scoped observation-watermark fix. The remaining lifecycle policy needs its own design before implementation.
馃挕 Proposed Solution
Define one explicit recovery contract for local and cloud sync:
- distinguish unavailable history from corrupt readable history;
- keep local SQLite as the source of truth and never silently drop data;
- specify when to re-export idempotently, rebuild derived history, defer dependencies, or stop;
- align dependency ordering and terminal lifecycle states across local and cloud import;
- define bounded behavior for full-history scans;
- cover missing, corrupt, partial, tombstoned, and dependency-stalled histories with deterministic push and pull tests.
Implementation should be split into focused work units only after the contract is approved.
馃摝 Affected Area
Sync (multi-instance)
馃攧 Alternatives Considered
Continuing the global timestamp-only watermark can silently miss identities. Porting the accumulated PR #780 logic would mix multiple roots and unresolved policies. A destructive full reset would discard useful delivery state and violate local-first expectations.
馃搸 Additional Context
PR #780 was closed after PR #894 resolved issue #615. Related but non-equivalent issues include #595 (explicit full re-sync after project migration), #649 (orphan relation import stalls), and #849 (dead-row retention). This tracker owns only the incomplete-history recovery contract.
馃搵 Pre-flight Checks
status:approvedbefore a PR can be opened馃攳 Problem Description
Local chunk sync has no single recovery contract for incomplete history. A manifest can reference chunks that are unavailable on the current machine, while existing chunks can contain partial session, prompt, observation, relation, or tombstone history.
The current behavior mixes several decisions: when missing history should be treated as unknown, when local SQLite should re-export idempotently, when import should defer a dependency, when corruption must fail loudly, and how long histories should be scanned without unbounded work. PR #780 experimented with several of these policies while solving #615, but #894 delivered only the scoped observation-watermark fix. The remaining lifecycle policy needs its own design before implementation.
馃挕 Proposed Solution
Define one explicit recovery contract for local and cloud sync:
Implementation should be split into focused work units only after the contract is approved.
馃摝 Affected Area
Sync (multi-instance)
馃攧 Alternatives Considered
Continuing the global timestamp-only watermark can silently miss identities. Porting the accumulated PR #780 logic would mix multiple roots and unresolved policies. A destructive full reset would discard useful delivery state and violate local-first expectations.
馃搸 Additional Context
PR #780 was closed after PR #894 resolved issue #615. Related but non-equivalent issues include #595 (explicit full re-sync after project migration), #649 (orphan relation import stalls), and #849 (dead-row retention). This tracker owns only the incomplete-history recovery contract.