Design decisions

pgxsinkit records significant, hard-to-reverse choices as Architecture Decision Records (ADRs). The canonical copies live in docs/adr/ in the repository; the list below is generated from them (bun run docs:adr) and verified on every docs build, so it stays complete as ADRs are added.

• ADR-0001 — Unified TypeScript release, versioning, and tooling standard (emergent / conform-ed / pgxsinkit)
• ADR-0002 — Single in-database write path; retire the strategy/backend/artifact seam
• ADR-0003 — Secured sync ingress: fail closed, one verified-claims adapter
• ADR-0004 — One registry interpreter: shared resolvers and a registry fingerprint
• ADR-0005 — Mutation convergence: mechanism primitives plus an opt-in driver
• ADR-0006 — Local schema evolution and mutation compatibility
• ADR-0007 — Absorb sync-engine into the client
• ADR-0008 — Documentation proves the product interface
• ADR-0009 — Internalize the read-path sync (break with pglite-sync)
• ADR-0010 — Convergence barrier: resolve optimistic state by Server version, not key-match
• ADR-0011 — The Convergence model: one owner of local convergence, derived not stored
• ADR-0012 — Canonical entity identity and a composite-PK-correct applier
• ADR-0013 — Read-path identity: refresh the token, never freeze it at boot
• ADR-0014 — Bulk apply on both paths, without the set-based ordering hazard
• ADR-0015 — Stale-write conflict policy: detect by Server version, choose per table
• ADR-0016 — Deferred read-path optimisations and their triggers to revisit
• ADR-0017 — Framework-neutral server: drop the Hono dependency
• ADR-0018 — Apply-function drift detection via an embedded fingerprint
• ADR-0019 — Row filters as type-safe Drizzle fragments → parameterized Electric where
• ADR-0020 — Index-friendly RLS: = ANY(ARRAY(subquery)) for runtime-resolved id-sets
• ADR-0021 — Sync lifecycle: subscription-timing and retention as orthogonal axes
• ADR-0022 — Pessimistic write-units: server-authoritative writes via flush-routing
• ADR-0023 — Subquery move-out: applying Electric’s tagged-subquery eviction in the local store
• ADR-0024 — Subquery move-in: applying Electric’s live snapshot rows in the local store
• ADR-0025 — Per-client mode projection: one authoritative registry, readonly projections per client
• ADR-0026 — One claim-stamping managed-field strategy: authClaim
• ADR-0027 — Read projections: a derived second client shape over an owned table
• ADR-0028 — Own the sync engine outright (upstream compatibility is an anti-goal)
• ADR-0029 — The registry item is the ingest engine’s spec
• ADR-0030 — Self-verifying apply function and the serverless deployment profile
• ADR-0031 — Catch-up commit-floor alignment for CDN-cached shape watermarks
• ADR-0032 — The whole sync engine moves into a SharedWorker
• ADR-0033 — Live-tail sibling nudge: refresh quiet-shape watermarks instead of waiting out their long-polls
• ADR-0034 — Boot observability: a structured, versioned BootReport for every client boot
• ADR-0035 — Local store export: store backup, diagnostic dump, and data export
• ADR-0036 — Store path contract: derived storage backend, no client-visible memory stores
• ADR-0037 — Vite library build for the React package
• ADR-0038 — Manifest-derived externals for the public package bundles
• ADR-0039 — Ordinary writes activate their lazy group; claims-dependent groups warn on anonymous activation
• ADR-0040 — A worker-owned live-query manager: awaited teardown, deduplication, and bounded keep-alive
• ADR-0041 — Staged boot readiness: local-read before write and network
• ADR-0042 — Session-scoped sync metadata for ephemeral groups
• ADR-0043 — Adopted stores whose persistence cannot be introspected need a named acknowledgment
• ADR-0044 — The attach client proxies one-shot reads; isSynced stays a refusal
• ADR-0045 — Per-table applyMode for locally-derived rows
• ADR-0046 — Restore boots online when the recovered journal is clean
• ADR-0047 — Relaxed durability is the default for the local store, declared on the registry
• ADR-0048 — opfs-repacked — a packed, recreate-only OPFS VFS for PGlite
• ADR-0049 — Capability-driven engine placement: opfs-repacked on every platform
• ADR-0050 — Storage declaration transport and path-addressed store teardown
• ADR-0051 — Content-addressed validate caching and per-file unit-test selection
• ADR-0052 — Row classification and registry invariants
• ADR-0053 — Queue-shaped event ingestion as a first-class lane
• ADR-0054 — The apply function is deny-by-default