docs: scope project lifecycle and org switching - #20
Open
marcorivm wants to merge 1 commit into
Open
Conversation
This was referenced Aug 7, 2026
An error occurred while trying to automatically change base from
open-edition/reconciled
to
open-edition/08-web-org-policy
August 8, 2026 19:22
Everything below the UI is already multi-project — Agent, Secret, AppConnection, PolicyRuleV2, ApiKey and Budget all FK to Project, and the gateway resolves off agent.project_id. What is missing is create, list and switch. Records what already works (so it is not rebuilt), the invariants that must not break, and the sequencing. Two findings worth the write-up: - Switching on flat editions has no transport today: proxy.ts strips the /p/<id> prefix when !CAPS.orgScopedUI, so a cookie is needed. Upstream is building the same mechanism for orgs (DEFAULT_ORG_COOKIE, new in v1.45.0), so ours should sit alongside it rather than duplicate it. - Org switching is blocked on resolution precedence, not UI: session.ts derives organizationId FROM the resolved project and ignores x-organization-id whenever a project resolves, which on flat editions is always. Making findUserDefaultProject org-aware fixes it without inverting precedence. Living document — the status table tracks each slice.
marcorivm
force-pushed
the
docs/project-lifecycle
branch
from
August 8, 2026 19:34
da3417a to
b844505
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Scoping doc for the project-lifecycle work, plus the org-switching follow-up. Living document — the status table tracks each slice, and decisions that change during implementation get recorded here rather than drifting from the code.
Why
Groups (#12) and project access (#13) both bind permissions to projects, but there's no way to create a project, list the ones you can reach, or switch between them. That's why groups feel inert — the thing they grant access to barely exists as a user-facing concept.
What the investigation found
Multi-project is already live and headless.
Agent,Secret,AppConnection,PolicyRuleV2,ApiKeyandBudgetall FK toProject; the gateway resolves everything offagent.project_id;resolveProjectIdalready honoursx-project-idgated bycanAccessProjectAsUser.ensureMemberDefaultProjectis already creating one project per invited member — which is exactly whyprojectNameSchemais deliberately non-unique per org. Only create, list and switch are missing.Switching on flat editions has no transport.
proxy.tsstrips the/p/<id>prefix when!CAPS.orgScopedUI, so onossandonprem-slima switcher has nothing to ride on. A cookie is the answer — and upstream is already building the same mechanism for orgs (DEFAULT_ORG_COOKIE, new in v1.45.0, absent from our v1.44.0 base). Ours should sit alongside it innavigation.tsrather than duplicate it.Org switching is blocked on resolution precedence, not UI.
session.tsderivesorganizationIdfrom the resolved project and ignoresx-organization-idwhenever a project resolves — which on flat editions is always, becauseresolveProjectIdfalls back tofindUserDefaultProject. Making that fallback org-aware fixes it without inverting precedence or touching the lockout invariant.Slices
GET /v1/projects— listPOST /v1/projects— createSlice 1 is stacked on this branch. Slice 4 should wait for the v1.45.0 adoption so it inherits the org cookie instead of racing it.
The invariant to watch
findUserDefaultProjectandhasResolvableProjectExcludingmust move together — the code comment is emphatic that drift is a lockout: a user whose last project disappears resolves nothing and session auth 401s them everywhere. Slice 4 edits that function directly.