PRD compliance matrix
Mapping workspace PRDs and RFCs to implementation status across packages and apps.
This page tracks how Melon-db implementation compares to the product requirements in .cursor/rules/ (prd-1 through prd-4, db-core, db-query, db-prisma, package-roles, file-layout). prd-4 describes a future sliding-window retention subsystem — not part of v1 core. For shipped phase history see Roadmap.
Legend: Done · Partial · Deferred (intentional v1 limit) · Gap (not scheduled / needs decision)
| Bucket | Examples |
|---|
| Done | Core engine, SQLite, sync, codemods, hasMany includes, Q.on / relationFilters, observeQuery precision, walkthroughs |
| Partial | Mango/Prisma surfaces, testkit helpers, devtools (Plan/params), playground-web, hook/schema typing |
| Deferred | SQL SELECT JOIN shaping, full schema codemods, background sync |
| Gap | getChangedCollections, sliding window (prd-4), Supabase/REST backends, npm alpha / open-source release |
| Requirement | Status | Notes |
|---|
Schema + createMelonSchema | Done | Generic schema preserves collection keys |
| AST + prepare/validate/plan | Done | |
StorageAdapter contract | Done | |
createDatabase, collections, CRUD, observe | Done | |
| In-memory adapter | Done | In core; re-exported from testkit |
Serialized write queue | Done | |
belongsTo includes (engine) | Done | loadIncludes |
hasMany includes (engine) | Done | Post-fetch batch load; global limit on child query |
relationFilters / Q.on filters | Done | SQLite IN subquery; in-memory applyRelationFilters |
| Sync APIs on DB | Done | Beyond minimal db-core |
collection.query(builder => …) | Done | Via @melon-db/db-query bridge |
observeQuery on in-memory | Partial | Engine ChangeEmitter fallback |
getChangedCollections | Gap | Not on any adapter; outbox used for sync |
| Read blocked during write | Gap | Writes serialized; reads do not wait on queue |
| Requirement | Status | Notes |
|---|
| AST → SQL | Done | |
| Node / Bun / Expo / RN | Done | |
| Transactions | Done | |
observeQuery + triggers | Done | Phase 27–29; Phase 33 cross-collection relationFilters + field-aware invalidation |
| Benchmarks | Done | |
| iOS/Android JSI + TurboModule | Done | |
| SQL joins / partial select | Deferred | capabilities.joins: false; includes via post-fetch |
getChangedCollections | Gap | |
Unified createSqliteAdapter({ jsi }) | Partial | JSI via createJsiSqliteAdapter export |
| Requirement | Status | Notes |
|---|
QueryBuilder + createQueryFactory | Done | |
byId / byForeignKey | Done | |
resolveCollectionQuery | Done | Builder → AST for collections |
findMany / findFirst / count + builder | Done | Same CollectionQueryInput as query() |
| Schema-driven inference | Partial | Factory accepts schema; no field inference yet |
Builder .not() | Done | Mirrors and / or nesting |
| Hook/schema typing without assertions | Partial | resolveCollectionQuery overloads; collection keys via generics |
| Requirement | Status | Notes |
|---|
createMangoCompiler | Done | |
| Core Mango operators | Done | |
mode: one / count | Done | MangoQuery.mode |
normalizeMangoQuery | Done | MangoNormalizer |
$contains, null checks | Partial | Limited operator map |
| Operator matrix doc | Partial | See package README |
| Requirement | Status | Notes |
|---|
| Provider + core hooks | Done | |
useMangoQuery, useFindMany, useFindFirst | Done | |
useFindMany + fluent builder | Done | useFluentQuery helper |
useRecord | Done | Primary-key observe + useRecordState |
| Hook loading/error state | Done | useQueryState, useFindManyState, useFluentQueryState, useRecordState |
| Sync hooks in this package | Partial | Convenience; package-roles boundary drift |
| Hook/schema typing without assertions | Partial | isPreparedQuery guards; UseQueryOptions select generic |
| Requirement | Status | Notes |
|---|
| Prisma schema import | Done | importPrismaSchema on ./node |
compilePrismaQuery + client | Done | |
select / include in compiler | Done | belongsTo includes only |
CLI melon-prisma | Done | package.json bin |
observeMany on client | Partial | Codegen re-exports hooks |
emitZod | Gap | |
| Package | Status | Main gap |
|---|
| devtools | Partial | Plan + SQL params in UI; Retention tab stub (prd-4) |
| testkit | Partial | No Jest helpers / fake clock |
| codemods | Done | migrate-schema spike; Q.on → relationFilters when schema passed to translator |
| Requirement | Status | Notes |
|---|
| Pull/push, checkpoint, retry, conflicts | Done | |
| Postgres reference backend | Done | |
merging sync state | Deferred | See Phase 29+ decisions |
| Persistent multi-job queue | Deferred | |
| Supabase / REST recipes | Gap | |
| Sliding window / local prune (prd-4) | Gap | Builds on pull/push + outbox; not a sync-server replacement |
| React hooks | N/A | In @melon-db/db-react |
Future retention subsystem from prd-4.mdc — org-aware download windows, safe local pruning, and diagnostics. Not scheduled for v1.
| Requirement | Status | Notes |
|---|
| Window definition model (per org / entity) | Gap | Server-sourced config via app API |
| Effective window computation | Gap | Pure-function policy engine |
| Record eligibility (in-window / protected / prune-eligible) | Gap | Protect unsynced + relational deps |
| Prune planner + executor | Gap | Post-sync + pressure modes |
sync_window_state + local_prune_ledger tables | Gap | Phase 1 in prd-4 |
| Pressure modes (normal / low-storage / emergency) | Gap | |
| Background maintenance (NetInfo, background fetch) | Gap | Opportunistic + resume |
| Retention observability (devtools / support UI) | Gap | Devtools Retention tab stub only |
| Devtools integration | Partial | Placeholder tab; full UI with Phase 31+ |
Package home (TBD): @melon-db/sync extension or @melon-db/sync-retention — sync packages must not depend on query-layer packages per package-roles.
| Feature | playground-rn | playground-rn-dev | playground-web | docs | playground-node |
|---|
| SQLite / storage | Expo | Native JSI | In-memory | In-memory live UI | Node SQLite |
| CRUD + reactive | Yes | Yes | Yes | Yes | Yes |
| Delete in UI | Partial | Yes | Yes | Yes | — |
| Mango / Prisma / relations demos | — | Demos screen | Fluent query | Docs + walkthrough | — |
| Devtools panel | — | Yes | Yes | Toggle in playground | — |
| Benchmarks | No | Dev screen | — | Static JSON | Node benches |
| Sync + backend demos | Client only | Client | — | Sync playground | HTTP + Postgres scripts |
Pre-GA work required before publishing @melon-db/* to npm and opening the GitHub repository. Phase 34 implements the release engineering and adoption plumbing; a couple items remain manual (npm org creation + flipping GitHub public).
| Requirement | Status | Notes |
|---|
| GitHub: private → public | Gap | Manual: flip visibility, enable branch protection + secret scanning |
| Community files | Done | Root LICENSE, CONTRIBUTING.md, CODE_OF_CONDUCT.md, SECURITY.md, templates |
| Secret / history hygiene | Done | .gitignore tightened for local artifacts; manual scan recommended before public |
npm org @melon-db | Gap | Manual: create org, invite maintainers, enforce 2FA |
| Per-package publish metadata | Done | files, exports, publishConfig.access: public, license, repository, aligned versions |
| Monorepo publish workflow | Done | release.yml + tooling/release/publish.ts (topological order, --tag alpha) |
| Alpha versioning policy | Done | Lockstep 0.1.0-alpha.0 + alpha dist-tag |
| npm provenance / trusted publish | Partial | Workflow supports token publish; switch to OIDC when npm org is configured |
| Dependency & supply-chain security | Done | Release workflow runs bun audit and smoke from packed tarballs |
| Security disclosure process | Done | SECURITY.md |
| Release notes & changelog | Done | Root CHANGELOG.md; use GitHub Releases for tags |
| Install docs for consumers | Done | Getting started includes npm/Bun install |
| Support / SLA for alpha | Done | Alpha support policy + issue templates |
-
Legal & repo hygiene (before public GitHub)
- Choose and add a LICENSE.
- Add
CONTRIBUTING.md, CODE_OF_CONDUCT.md, and SECURITY.md.
- Enable branch protection, required status checks, and secret scanning / Dependabot.
- Confirm no credentials in git history,
.env examples, or CI logs.
-
npm organization & package prep
- Create npm org
@melon-db; add maintainers with 2FA.
- For each publishable package under
packages/*: verify name, version, description, repository, license, files / exports, and "publishConfig": { "access": "public" }.
- Run
bun run build and smoke tests from packed tarballs (npm pack / bun pm pack) — not only workspace links.
-
Alpha release
- Publish with dist-tag
alpha (e.g. @melon-db/db@0.1.0-alpha.0).
- Tag monorepo release in GitHub; attach release notes listing packages and known limitations (v1 limitations).
- Update Getting started and package pages with non-workspace install instructions.
-
Security hardening (ongoing)
- CI: audit on PR + before publish.
- Document supported React Native / Expo versions and native setup boundaries.
- Review third-party native dependencies and pin where necessary.
-
Path to GA (post-alpha)
- Stable
1.0.0 criteria aligned with prd-1 Milestone 5 (API freeze, migration docs, benchmark publication).
- Promote dist-tag from
alpha → latest only after acceptance criteria met.
Package home: release automation likely lives in root CI + tooling/ scripts; individual packages stay publishable units per package-roles.
Product decisions recorded here (not blockers for phases 0–28):
| Item | Decision | Rationale |
|---|
getChangedCollections | Defer | Sync uses outbox + getLocalChanges; adapter hook when sync needs incremental adapter scans |
SQL SELECT JOIN / partial select | Defer | Includes remain post-fetch; see ADR-011 |
Per-parent nested take on includes | Defer | Global child limit only in v1 |
Sync merging state | Defer | Apply path is synchronous; add when merge UI needs distinct phase |
@melon-db/db-react → @melon-db/sync dep | Accept | DX for useSync; split only if publishing react without sync |
playground-web | Partial | In-memory Vite app; full web SQLite adapter still deferred |
| Read-during-write blocking | Defer | Serialized writes sufficient for v1; revisit if readers observe torn state |
| Sliding window subsystem (prd-4) | Defer | Phase 31+; policy foundation before prune executor |
| Alpha / open-source release | Next (Phase 34) | Public GitHub + npm @melon-db alpha; see Alpha release and open source |
| File | Focus |
|---|
prd-1.mdc | Product vision, sync, RN, hooks, GA checklist, open source / npm alpha |
prd-2.mdc | AST-first multi-surface queries |
prd-3.mdc | TypeScript interface contracts |
prd-4.mdc | Future sliding-window retention, prune ledger, org-aware scope |
db-core.mdc | @melon-db/db + @melon-db/db-sqlite |
db-query.mdc | Fluent builder + React |
db-prisma.mdc | Prisma layer |
package-roles.mdc | Per-package milestones |
