docs(database): add PostgREST builder architecture spec

[grdsdev]

Summary

• Adds specs/database/_builder_architecture.md: a language-agnostic mermaid flowchart of the PostgREST query builder (Client → QueryBuilder → FilterBuilder → TransformBuilder → Execute)
• Every edge is tagged with its database.* capability ID from capabilities/database.yaml, plus a full legend table, so the graph doubles as a traceability map
• Reference: supabase-js postgrest-js @ 21e410f (JS's specific single-instance/type-narrowing approach is noted as an implementation detail, not a requirement)

Test plan

• npm run validate passes (file sits outside the specs/<area>/<ns>/<method>.md scan pattern, so it's not treated as an unmatched feature spec)

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: d12b610d-8d9d-4ba2-a2f6-100543888aa2

📥 Commits

Reviewing files that changed from the base of the PR and between fabb9a7 and 75d22aa.

📒 Files selected for processing (1)

• specs/database/_builder_architecture.md

---

📝 Walkthrough

Summary by CodeRabbit

• Documentation
  • Added architecture documentation for the database query builder.
  • Documented query stages, supported filters, modifiers, execution operations, mutations, RPC behavior, and configuration flow.
  • Included chaining constraints, implementation considerations, and capability mappings.

Walkthrough

Adds an architecture specification for the PostgREST database query builder. The specification defines five stages: Client, QueryBuilder, FilterBuilder, TransformBuilder, and Execute. It documents entry points, filters, modifiers, terminal operations, mutation selection, RPC routing, execution behavior, implementation alternatives, chaining constraints, capability mappings, and the related capability registry.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[QuintinWillison]

Very relevant to what I'm working on right now so I am looking forward to taking a deeper look when this PR opens for review. 🤓