Foundations

The test for every item in Synergy's scope is how much it costs to add later, not whether it is frontend or backend. Styling, icons and bulk endpoints are cheap to add later, so they wait. The items below would force a data migration or a rewrite of components every module uses, so they ship in Phase 3. Each one has a planned use in a near-term phase.

Backend foundations

Each of these is cheap to build now and expensive to retrofit.

Data model

1. D167 rule #synergy #database: Every field the vision needs, from day one. This covers the entity index (owner, provider, type, title, status, version, revision, timestamps, tombstone), the version log (change notes), relationships (single and list, label, type, version snapshot, to_anchor with its quote, cited and mentioned), tags (with key, aliases and deprecation), and the relation-type vocabulary (with its inverse name and reference/association kind). Columns a near-term phase needs, like the anchors Taxila uses in Phase 4, exist now. Adding a nullable column later is easy. Backfilling meaning into rows that were written without it is not. derived-from D2
2. D168 rule #synergy #database: Provenance on every write. Each write records who made it: a person, the system, an agent or an API key, and why. AI tag approval, "removed by system" revisions and any future audit all depend on it. derived-from D2
3. D169 rule #synergy #database: Client-generated UUIDs, updated_at and soft delete on every table. This is what lets the PWA in Phase 8 sync offline without redesigning the tables. derived-from D2

Correctness

4. D170 rule #synergy #database: Rules live in the database, not only in code. Foreign keys, unique constraints, a check constraint for the tag format, and one transaction for each rule that spans rows. "Block delete while referenced" and "reject cycles" run under a per-user lock in the same transaction as the write. Bots and agents call the API concurrently. A rule checked in app code alone breaks under a race. derived-from D2
5. D171 rule #synergy #concurrency: Optimistic concurrency. An update carries the content_seq it started from, and a stale write gets 409. content_seq moves on every content write, versions and anchors included, so a version save or an anchor added by another link can't be silently overwritten (Content sequence). Two tabs, or a person and an agent, editing the same entity must not silently overwrite each other. derived-from D2

Security

6. D172 rule #synergy #rls: RLS on every table, comparing the uuid column directly (col = nullif(current_setting(...), '')::uuid, never col::text = ...). The cast form converts every row's uuid to text, so Postgres can't use the uuid index and scans the whole table. The right form converts the setting once and lets the index find the user's rows directly. Every Synergy query filters by owner. Phase 3 also fixes the existing policies in sidekick migrations 0002 and 0007, which use the cast form today . derived-from D2
7. D173 rule #synergy #security: Locked, redacted and deleted states are decided on the server, before any renderer runs. No content leaves a module the reader can't see. derived-from D2

Scale

8. D174 rule #synergy #database: Indexes for every hot path. Backlinks (to_id), outgoing links (from_id), list order (parent_id, position), by tag, by owner and status, and a trigram index on titles. Popular entities will have thousands of backlinks. derived-from D2
9. D175 rule #synergy #staleness: Staleness is computed when it's read, never fanned out on write. It comes from a join of the relationship's snapshot with the index row. Flagging every referencer when a popular entity changes turns one edit into thousands of writes. Post-MVP digests ("you reference stale or deprecated entries") fit this: the digest job is the reader and runs one indexed query per user. Instant alerts fan out asynchronously from the outbox, never inside the save. derived-from D2
10. D176 rule #synergy #rendering: Batched resolution. A document with 50 links makes one resolver call per provider (resolveMany), not 50. The resolver and renderer contracts take lists from the start. derived-from D2
11. D177 rule #synergy #cache: Cache keys that carry the content sequence. Rendered card and preview data is cached under (entity, content_seq, display type), and HTTP responses carry content_seq as an ETag. Any content write means a new key, so invalidation is never a purge problem. Only render data is cached; states are read fresh. The cache sits behind an interface: in-process or Postgres now, a shared cache (Redis) later without changing callers. derived-from D2
12. D178 rule #synergy #api: Cursor pagination on every list. This covers backlinks, search, tags and the version log. Offset pagination collapses at the sizes Synergy is meant for. derived-from D2

Change tracking

13. D179 rule #synergy #outbox: An outbox from day one. Every change writes an event row in the same transaction, with the transaction id so readers can follow commit order: entity, relationship, tag and passage events, listed in the system design. Nothing consumes the outbox in Phase 3. Notifications, Factory automations, cache warming and search reindexing all start from it later, and an event log can't be reconstructed for writes that never recorded one. derived-from D2

API

14. D180 rule #synergy #api: One public contract. Typed request and response schemas, stable error codes (delete_blocked with the referencer count, cycle, locked) and idempotency keys on create, so a retried bot request doesn't link twice. Everything goes through withApiGuard, which also logs. Bulk endpoints can wait: adding them later changes nothing that exists. derived-from D2

Frontend foundations

Styling can wait. These can't, because every module will build on the component's contract.

15. D181 rule #synergy #sneak-peek-link: Lists that page from the start. Any list the component shows (backlinks, list-relationship members, search results) loads incrementally by cursor and can scroll to load more, with virtualization for long lists. A component built for "load everything" gets rewritten at the first popular entity. derived-from D2
16. D182 rule #synergy #sneak-peek-link: Async resolvers with every state. The frame owns loading, error, empty, locked, redacted and deleted. The resolver is async from day one and returns serialisable render data; the renderer is a pure function from that data to React. The component always awaits the resolver. A synchronous contract would force a signature change on every caller the first time one provider needs a fetch. derived-from D2
17. D183 rule #synergy #sneak-peek-link: Batched fetching in the component. Links on one page are collected, grouped by provider (Taxila, War Room, Alter Ego; note and task in Phase 3), and resolved in one request per provider (pairs with item 10). A plan page with 20 datums, 8 tasks and 2 chat sessions makes 3 calls, not 30. Fetching per link can't be fixed without changing how every caller mounts the component. derived-from D2
18. D184 rule #synergy #sneak-peek-link: Display type and states as props and data attributes. The four display types and the states are explicit props, exposed to styling as attributes and tokens. That's what keeps icons, pills and hover cards purely additive later. derived-from D2
19. D185 rule #synergy #sneak-peek-link: Accessible semantics. Real links, focus order, and a text equivalent for the edited and changed dots, which also differ in shape so colour is never the only cue. Retrofitting accessibility means touching every renderer. derived-from D2
20. D186 rule #synergy #sneak-peek-link: A host-agnostic component. The component takes its data and a transport (resolveLinks(requests)) as inputs and assumes no app-wide context, so Notion, Slack or an embed page can show a Sneak Peek Link later. A component that reaches into Sidekick's app shell has to be rewritten the day a third party wants it. derived-from D2
21. D187 rule #synergy #registry: An open type registry. Linkable types, resolvers and renderers are registered by packages, never listed in Synergy. Adding a Twitter thread or a news article as a linkable type is a new package, not a Synergy change. derived-from D2