overengineeringstudio / overengineeringstudio/effect-utils
notion-datasource-sync: finish public SQLite contract hardening
Nobody has claimed this yet.
- Dominant language
- TypeScript
- Stars
- 82
- Forks
- 2
- Avg merge
- 1d 8h
- Merged PRs (30d)
- 121
Description
Parent epic: #698
Problem
The public <database-id>.sqlite contract is close for the current supported surface, but remaining lifecycle and conflict semantics still need a single focused tracker.
Current Evidence
- Required SQLite objects/triggers and tamper guards are validated.
- Public
rows,changes,sync_status, and private_nds_*behavior have contract tests. - Row create, archive/restore, title/description metadata, and external URL file attach subsets are represented.
- Closed folded context: #705, #706, #710, #712.
Scope
- Ensure status projection stays aligned with
_nds_outboxand the current sync-state schema. - Keep protected VRS docs aligned with the database-ID SQLite file contract.
- Preserve local restore ergonomics after data-only archive and query-membership gaps.
- Define retirement/retention for resolved conflicts and terminal CDC history.
- Implement or explicitly keep fail-closed choose-local/manual conflict writes with verified post-write hashes.
- Make public/private rebuild and migration behavior explicit for users.
Repro / Proof Instructions
- Create or adopt a disposable data-source replica into
<workspace>/<database-id>.sqlite. - Exercise public
rowschanges for supported scalar edits, row create, archive, restore, metadata, and external URL file attach. - Exercise unsupported direct writes to
changes,conflicts,schema,schema_properties, debug views, and_nds_*. - Create a conflict, resolve it through the supported public/CLI path, and verify public pending state, terminal history, and audit retention.
- Rebuild projections from private sync state and verify public tables remain deterministic.
Acceptance Criteria
- Public tables/views expose only supported write paths; unsupported writes fail before visible local mutation.
sync_statusdistinguishes clean, pending, conflicted, unsupported, and degraded/incomplete states without treating unsupported hydration as dirty local work.- Conflict resolution retires active work while preserving bounded auditability.
- Docs/VRS explain the public contract without requiring readers to inspect closed folded issues.
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the public .sqlite contract, its public/private tables, _nds_outbox, and the current sync-state schema; follow the repro steps to exercise supported and unsupported writes. Done means the acceptance criteria hold for status projection, conflict retirement and audit retention, deterministic rebuilds, and the documented VRS contract.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- sqlite, typescript
- Domain
- backend-api-design, databases, documentation
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100