docs(authz): Wave 0 permission storage DDL spike

[adlerhurst]

Summary

Adds the Wave 0 design spike for portable FGA relational storage (ADR 032–033 / epic #419): locked decisions D1–D14, Postgres/Spanner-oriented DDL strawman, dual-write membership edges, check/list SQL sketches, end-to-end narrative, and a #333 cross-project grant depiction (foreign user/team principal on the protected project_id).

Links the doc from the API design index and points ADR 032/033 follow-ups at it so #422 can implement migrations without re-litigating the schema shape.

Validation

• Doc review against plan acceptance criteria (D1–D14 present, dual-write + [ARCH-ADR] Define Architecture for Cross-Project Identity and Collaboration #333 depiction, deferrals for Leopard / partitioning / app grants)
• Addressed thermo-nuclear review P1–P8: one check SQL shape with $principal_home_project_id, relations+closure only (D14), tighter DDL CHECKs, authz.md / ADR follow-up alignment
• Docs-only change; no runtime or migration code

Release notes / changeset

No changeset required — no shipped behavior changed (docs only).

Notes

• Addressed thermo-nuclear review P1–P8 on this branch
• Out of scope: Goose migrations, internal/authz/*, resolver (Permission Resolver & SQL List Predicate Injection #423), OpenFGA compiler (OpenFGA Parser, IR & Profile Compiler #421), implementing [ARCH-ADR] Define Architecture for Cross-Project Identity and Collaboration #333 product/identity
• Related: Permission Management — ADR 032–034 Implementation #419, Relational Schema & Migrations for Authorization #422, [ARCH-ADR] Define Architecture for Cross-Project Identity and Collaboration #333

  

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
nextgen	Ready	Preview	Aug 6, 2026 12:26pm
nextgen-docs	Ready	Preview	Aug 6, 2026 12:26pm
nextgen-mock-zitadel	Ready	Preview	Aug 6, 2026 12:26pm

[github-actions]

⚠️ No Changeset found

Latest commit: 3330aa6

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[Copilot]

Pull request overview

Adds a new API design doc that captures the Wave 0 “permission storage” DDL spike for the portable relational FGA core, then threads that reference into the API design index and ADR 032/033 follow-ups to anchor future implementation work (notably #422 migrations).

Changes:

• Introduces docs/design/api/permission-storage.md documenting locked DDL/storage decisions (D1–D13), strawman schema, and query sketches.
• Links the new design doc from docs/design/api/README.md to include it in the suggested reading order.
• Updates ADR 032 and ADR 033 follow-ups to point implementers at the Wave 0 storage doc and #422.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.

File	Description
docs/design/api/README.md	Adds the new permission-storage doc to the API design index/reading order.
docs/design/api/permission-storage.md	New Wave 0 storage/DDL spike doc with locked decisions, schema strawman, and illustrative SQL.
docs/adrs/033-internal-permission-management.md	Follow-up section now references the Wave 0 storage doc and links to #422.
docs/adrs/032-permission-catalogs.md	Follow-up section now references the Wave 0 storage doc and links to #422/#333 context.

[livio-a]

Review: Wave 0 permission storage DDL spike — reviewed alongside the rest of the stack (#677, #758).

Well-reasoned spike at the right altitude — freezing tables/PKs/indexes/dual-write rules as locked decisions D1–D13 is exactly the right output for Wave 0, and the implementation in #677 tracks it closely. Two notes, both doc-level:

• This doc is partially superseded by #677 and reads that way in isolation. #677 reverses D5 (it does create authz_expression_edges + authz_relation_references, which D5 here says to defer until #421) and changes relation identity to (catalog_id, object_type, relation). #677 updates permission-storage.md to match, so head stays consistent — but a reader landing on this PR's version sees the pre-revision D5/identity. Worth a one-line "superseded by #677 for D5 / relation identity," or squashing the doc evolution so the frozen decisions and their revisions land together.

• [NIT] Illustrative check SQL contradicts the D13 home-project note. The single-resource check example hardcodes e.project_id = a.project_id for the team-membership EXISTS, while the D13 discussion a few lines down states membership edges for a foreign team principal live in the principal's home project, not a.project_id. It's labeled illustrative, but the two passages read as directly contradictory — a half-sentence caveat on the example would remove the trap for whoever writes the Wave 1 resolver.