docs(designs): Add OSS/EE convergence assessment and schema parity plan#4669
docs(designs): Add OSS/EE convergence assessment and schema parity plan#4669jp-agenta wants to merge 7 commits into
Conversation
dosubot
Bot
added
the
size:XXL
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughAdds a multi-org convergence assessment, deterministic Postgres schema-dump script, EE/OSS schema dumps and diffs, and a six-PR execution plan to migrate membership models, add OSS org-creation/signup parity, enforce AGENTA_ACCESS_* in OSS, and achieve schema parity. ChangesOSS/EE Convergence: Multi-Org & Schema Parity Design
🎯 3 (Moderate) | ⏱️ ~20 minutes 🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
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. Comment |
jp-agenta
changed the title
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 5
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: 66ad328a-1574-45a9-9be8-8cf26723decd
📒 Files selected for processing (9)
docs/designs/oss-ee-convergence/assessment-a-oss-multi-org.mddocs/designs/oss-ee-convergence/diff_core.txtdocs/designs/oss-ee-convergence/diff_tracing.txtdocs/designs/oss-ee-convergence/dump_pg_schema.shdocs/designs/oss-ee-convergence/ee_core.txtdocs/designs/oss-ee-convergence/ee_tracing.txtdocs/designs/oss-ee-convergence/oss_core.txtdocs/designs/oss-ee-convergence/oss_tracing.txtdocs/designs/oss-ee-convergence/pr-plan.md
| Goal-B follow-through on the dumps above: after both steps, the OSS core schema is | ||
| **identical** to the EE core schema minus exactly four EE-only tables (`meters` + | ||
| `meters_type` enum, `subscriptions`, `organization_domains`, | ||
| `organization_providers`); the membership tables become shared (change 1); tracing |
There was a problem hiding this comment.
Fix the parity-count wording here.
This says “exactly four EE-only tables,” but the parenthesized list includes meters_type, which is an enum, not a table. Rephrase as “four EE-only schema objects” or “three tables plus one enum.”
| > TABLE public.organization_members COLUMN created_at timestamp with time zone | ||
| > TABLE public.organization_members COLUMN id uuid NOT NULL | ||
| > TABLE public.organization_members COLUMN organization_id uuid | ||
| > TABLE public.organization_members COLUMN role character varying NOT NULL DEFAULT 'viewer'::character varying | ||
| > TABLE public.organization_members COLUMN updated_at timestamp with time zone | ||
| > TABLE public.organization_members COLUMN updated_by_id uuid | ||
| > TABLE public.organization_members COLUMN user_id uuid |
There was a problem hiding this comment.
Lock membership rows to one user/scope pair.
These tables only have surrogate id PKs; user_id and the scope FK remain nullable, and there is no uniqueness on (user_id, organization_id/workspace_id/project_id). That allows duplicate or orphan memberships, which makes the new access checks and membership queries ambiguous. Add NOT NULL plus a unique constraint (or composite PK) per membership table.
Also applies to: 116-123, 136-142
| TABLE public.projects CONSTRAINT fk_projects_organization_id FOREIGN KEY (organization_id) REFERENCES organizations(id) ON DELETE SET NULL | ||
| TABLE public.projects CONSTRAINT fk_projects_workspace_id FOREIGN KEY (workspace_id) REFERENCES workspaces(id) ON DELETE SET NULL | ||
| TABLE public.projects CONSTRAINT projects_organization_id_fkey FOREIGN KEY (organization_id) REFERENCES organizations(id) ON DELETE CASCADE | ||
| TABLE public.projects CONSTRAINT projects_pkey PRIMARY KEY (id) |
There was a problem hiding this comment.
Remove the conflicting projects.organization_id foreign key.
The snapshot shows both fk_projects_organization_id ... ON DELETE SET NULL and projects_organization_id_fkey ... ON DELETE CASCADE on the same column. Those actions conflict, so the dump no longer describes a single, unambiguous delete rule for projects.
junaway
force-pushed
the
docs/oss-ee-convergence-design
branch
from
3c545d9 to
b58fc10
Compare
There was a problem hiding this comment.
Actionable comments posted: 1
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: da0c7d2c-a16d-4b70-8519-bbfd3d16660d
📒 Files selected for processing (9)
docs/designs/oss-ee-convergence/assessment-a-oss-multi-org.mddocs/designs/oss-ee-convergence/diff_core.txtdocs/designs/oss-ee-convergence/diff_tracing.txtdocs/designs/oss-ee-convergence/dump_pg_schema.shdocs/designs/oss-ee-convergence/ee_core.txtdocs/designs/oss-ee-convergence/ee_tracing.txtdocs/designs/oss-ee-convergence/oss_core.txtdocs/designs/oss-ee-convergence/oss_tracing.txtdocs/designs/oss-ee-convergence/pr-plan.md
✅ Files skipped from review due to trivial changes (5)
- docs/designs/oss-ee-convergence/diff_tracing.txt
- docs/designs/oss-ee-convergence/oss_tracing.txt
- docs/designs/oss-ee-convergence/ee_tracing.txt
- docs/designs/oss-ee-convergence/oss_core.txt
- docs/designs/oss-ee-convergence/pr-plan.md
🚧 Files skipped from review as they are similar to previous changes (2)
- docs/designs/oss-ee-convergence/dump_pg_schema.sh
- docs/designs/oss-ee-convergence/diff_core.txt
junaway
force-pushed
the
docs/oss-ee-convergence-design
branch
from
b58fc10 to
5b43a1c
Compare
There was a problem hiding this comment.
♻️ Duplicate comments (1)
docs/designs/oss-ee-convergence/assessment-a-oss-multi-org.md (1)
72-75:⚠️ Potential issue | 🟠 Major | 🏗️ Heavy liftClarify the backfill mapping before freezing the plan.
Both spots still rely on an underspecified “backfill or delete” / “member of the
oss-defaultorg/workspace/project” rule. That can collapse scope and assign the wrong org/workspace membership when more than one candidate exists. Please pin a deterministic source-of-truth for each row before the migration sequence is finalized.Also applies to: 275-301
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: d5632826-1536-4737-9bc4-99d020b71878
📒 Files selected for processing (9)
docs/designs/oss-ee-convergence/assessment-a-oss-multi-org.mddocs/designs/oss-ee-convergence/diff_core.txtdocs/designs/oss-ee-convergence/diff_tracing.txtdocs/designs/oss-ee-convergence/dump_pg_schema.shdocs/designs/oss-ee-convergence/ee_core.txtdocs/designs/oss-ee-convergence/ee_tracing.txtdocs/designs/oss-ee-convergence/oss_core.txtdocs/designs/oss-ee-convergence/oss_tracing.txtdocs/designs/oss-ee-convergence/pr-plan.md
✅ Files skipped from review due to trivial changes (4)
- docs/designs/oss-ee-convergence/diff_tracing.txt
- docs/designs/oss-ee-convergence/oss_core.txt
- docs/designs/oss-ee-convergence/ee_tracing.txt
- docs/designs/oss-ee-convergence/pr-plan.md
🚧 Files skipped from review as they are similar to previous changes (3)
- docs/designs/oss-ee-convergence/oss_tracing.txt
- docs/designs/oss-ee-convergence/dump_pg_schema.sh
- docs/designs/oss-ee-convergence/diff_core.txt
junaway
force-pushed
the
docs/oss-ee-convergence-design
branch
from
5b43a1c to
6fafd77
Compare
There was a problem hiding this comment.
Actionable comments posted: 4
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: 28ddac35-a9f7-488d-aa9d-4fd7c7e0c956
📒 Files selected for processing (9)
docs/designs/oss-ee-convergence/assessment-a-oss-multi-org.mddocs/designs/oss-ee-convergence/diff_core.txtdocs/designs/oss-ee-convergence/diff_tracing.txtdocs/designs/oss-ee-convergence/dump_pg_schema.shdocs/designs/oss-ee-convergence/ee_core.txtdocs/designs/oss-ee-convergence/ee_tracing.txtdocs/designs/oss-ee-convergence/oss_core.txtdocs/designs/oss-ee-convergence/oss_tracing.txtdocs/designs/oss-ee-convergence/pr-plan.md
✅ Files skipped from review due to trivial changes (4)
- docs/designs/oss-ee-convergence/diff_tracing.txt
- docs/designs/oss-ee-convergence/oss_core.txt
- docs/designs/oss-ee-convergence/oss_tracing.txt
- docs/designs/oss-ee-convergence/pr-plan.md
🚧 Files skipped from review as they are similar to previous changes (2)
- docs/designs/oss-ee-convergence/ee_tracing.txt
- docs/designs/oss-ee-convergence/dump_pg_schema.sh
| - `db_manager.create_organization()`: drop the `not is_ee()` ON CONFLICT branch; | ||
| generate unique slugs (keep `oss-default` as the legacy slug of the bootstrap org, | ||
| no special meaning afterwards). | ||
| - Move the org-creation orchestration (`create_organization_for_user`, | ||
| `can_create_organization` from `api/ee/src/services/commoners.py`) into OSS shared | ||
| code; EE wraps it to add subscription/trial setup. This follows the established | ||
| pattern: EE is additive over OSS. | ||
| - Mount the create endpoint in the OSS organization router (mirror | ||
| `api/ee/src/routers/organization_router.py:380`, minus billing). | ||
| - Lift the admin-API block (`accounts/service.py:1058`) to accept explicit | ||
| org/workspace/project/memberships like EE does. |
There was a problem hiding this comment.
Specify the slug-collision rule for new orgs.
generate unique slugs is too vague for the new create-org path. Please state how the slug is derived, how duplicates are retried, and whether the existing EE helper is reused verbatim; otherwise concurrent org creates can still fail on duplicate slugs.
🧰 Tools
🪛 LanguageTool
[locale-violation] ~89-~89: In American English, ‘afterward’ is the preferred variant. ‘Afterwards’ is more commonly used in British English and other dialects.
Context: ...the bootstrap org, no special meaning afterwards). - Move the org-creation orchestration...
(AFTERWARDS_US)
junaway
force-pushed
the
docs/oss-ee-convergence-design
branch
from
6fafd77 to
4791d6d
Compare
There was a problem hiding this comment.
♻️ Duplicate comments (3)
docs/designs/oss-ee-convergence/assessment-a-oss-multi-org.md (3)
87-89:⚠️ Potential issue | 🟠 Major | ⚡ Quick winDefine a slug-collision retry rule before removing the singleton branch.
On Lines 87-89, “generate unique slugs” is still too vague for concurrent org creation. Please spell out the slug derivation and retry behavior so two creates can’t race into a duplicate-key failure.
297-301:⚠️ Potential issue | 🟠 Major | 🏗️ Heavy liftSpell out the EE backfill tie-breaker, not just “resolve via the project's members.”
On Lines 297-301, this still does not define how to choose a single org/workspace when multiple members qualify (or none do). Lock the exact selection rule before the NOT NULL/CASCADE migration, or the backfill can assign rows to the wrong tenant.
378-382:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winUse the canonical allowlist name in the upgrade warning.
On Lines 378-382,
ALLOWED_OWNER_EMAILSis still ambiguous; operators need the fullAGENTA_ACCESS_ALLOWED_OWNER_EMAILSname (or an explicit legacy-alias list) to avoid misconfiguring the closed-signup path.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: be1f1353-9972-4ab7-8a58-380035216cb9
📒 Files selected for processing (9)
docs/designs/oss-ee-convergence/assessment-a-oss-multi-org.mddocs/designs/oss-ee-convergence/diff_core.txtdocs/designs/oss-ee-convergence/diff_tracing.txtdocs/designs/oss-ee-convergence/dump_pg_schema.shdocs/designs/oss-ee-convergence/ee_core.txtdocs/designs/oss-ee-convergence/ee_tracing.txtdocs/designs/oss-ee-convergence/oss_core.txtdocs/designs/oss-ee-convergence/oss_tracing.txtdocs/designs/oss-ee-convergence/pr-plan.md
✅ Files skipped from review due to trivial changes (5)
- docs/designs/oss-ee-convergence/diff_tracing.txt
- docs/designs/oss-ee-convergence/ee_tracing.txt
- docs/designs/oss-ee-convergence/oss_tracing.txt
- docs/designs/oss-ee-convergence/pr-plan.md
- docs/designs/oss-ee-convergence/oss_core.txt
🚧 Files skipped from review as they are similar to previous changes (2)
- docs/designs/oss-ee-convergence/dump_pg_schema.sh
- docs/designs/oss-ee-convergence/diff_core.txt
junaway
force-pushed
the
docs/oss-ee-convergence-design
branch
2 times, most recently
from
d8bc371 to
6995ded
Compare
junaway
force-pushed
the
docs/oss-ee-convergence-design
branch
from
6995ded to
a55c0d7
Compare
junaway
force-pushed
the
docs/oss-ee-convergence-design
branch
from
a55c0d7 to
7f114fc
Compare
junaway
force-pushed
the
docs/oss-ee-convergence-design
branch
from
7f114fc to
c2ef2aa
Compare
junaway
force-pushed
the
docs/oss-ee-convergence-design
branch
from
c2ef2aa to
5946296
Compare
junaway
force-pushed
the
docs/oss-ee-convergence-design
branch
from
5946296 to
17c262d
Compare
junaway
force-pushed
the
docs/oss-ee-convergence-design
branch
from
17c262d to
e63a8f6
Compare
junaway
force-pushed
the
docs/oss-ee-convergence-design
branch
from
e63a8f6 to
6ccab20
Compare
junaway
force-pushed
the
docs/oss-ee-convergence-design
branch
2 times, most recently
from
426f70c to
814d8cf
Compare
junaway
force-pushed
the
docs/oss-ee-convergence-design
branch
from
814d8cf to
043284c
Compare
… parity Assessment for making OSS multi-organization with AGENTA_ACCESS_* enforcement, plus the two-step schema parity plan (drift fixes on kept tables, legacy table drop). Includes live schema dumps of both editions' core/tracing DBs, their diffs, the dump script, and the PR execution plan.
junaway
force-pushed
the
docs/oss-ee-convergence-design
branch
from
043284c to
9c06843
Compare
…ble chain ids Record the v0.103.5 propagation (b3c4d5e6f7a9 re-point, App-class collision in _admin_detach_user_references, db_manager_ee import/symbol churn) and the 12-char park/oss/ee revision-id rename. Update checkpoint ids and the chain layout diagram. Flag the committed schema dumps as stale (predate the workflow_revisions repair). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Same scheme as core (no t-prefix); tracing has its own database so the version tables (alembic_version_tracing_oss/_ee) and ids do not collide. tracing_ee is root+proof only (no EE-only tracing tables to adopt on a switch). Update the layout note and runner order. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…e core Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
dump_pg_schema.sh used ${vt^^} (bash 4+ uppercase expansion) which fails on
macOS system bash 3.2 with 'bad substitution'; replace with a portable tr.
Delete the committed schema dumps and diffs (oss/ee core+tracing, diff_*) —
they predate the v0.103.5 workflow_revisions repair and are regenerated from
replays, so the stale copies are misleading.
1 participant
Context
OSS today is hard single-org and ignores the four
AGENTA_ACCESS_*env vars it already parses. We want OSS to support multiple organizations with the same access-control semantics as EE (goal A), and the OSS schema to become a strict subset of the EE schema (goal B). Before changing code, this assessment maps the full blast radius.Changes
Design docs only, no code:
assessment-a-oss-multi-org.md: the assessment. Current single-org mechanisms, the five changes needed, a file-level inventory (EE to OSS moves, OSS and EE modifications, web gate relaxations), the two-step schema parity plan (drift fixes on kept tables, then dropping 20 dead legacy tables), documentation impact, and sequencing.oss_core.txt,ee_core.txt,oss_tracing.txt,ee_tracing.txt: live schema dumps of both editions' databases, withdiff_core.txtanddiff_tracing.txt. The tracing delta is zero; the core delta backs the parity plan.dump_pg_schema.sh: the script that produced the dumps.pr-plan.md: execution plan. The work ships as this PR plus five implementation PRs, one per sequencing step.Notes
🤖 Generated with Claude Code