overengineeringstudio / overengineeringstudio/effect-utils

notion-datasource-sync: finish public SQLite contract hardening

Open
#716 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

area:notion origin:agent type:chore
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_outbox and 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

  1. Create or adopt a disposable data-source replica into <workspace>/<database-id>.sqlite.
  2. Exercise public rows changes for supported scalar edits, row create, archive, restore, metadata, and external URL file attach.
  3. Exercise unsupported direct writes to changes, conflicts, schema, schema_properties, debug views, and _nds_*.
  4. Create a conflict, resolve it through the supported public/CLI path, and verify public pending state, terminal history, and audit retention.
  5. 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_status distinguishes 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

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.