# Organization upgrade and installation

The current source supports [owner/admin/member authority, membership scope
tags/public data and voluntary departure](org.md), plus caller-specific
[SSO org discovery](https://m7.org/docs/api/sso.user.m7.org/userinfo-orgs.md).
This guide describes installation order; local checks do not establish a live
deployment or an immutable SDK release.

## OAuth ownership storage prerequisite

The ownership/directory split requires `oauth_clients.org` to contain a valid
UUID independently of `tenant`. Before installing readers or writers that use
the split, verify the existing database has that field and correctly populated
rows: legacy personal registrations use nil `org` and nil `tenant`; legacy
tenant registrations use `org = tenant`. Preserve any already assigned non-nil
`org` on consumer registrations whose tenant is nil. Nil is
`00000000-0000-0000-0000-000000000000`, not SQL `NULL`.

The current OAuth repository projects and filters stored `org`; it does not
install this column or backfill old rows. Legacy request compatibility infers
omitted `org` from `tenant` for inserts/searches, and is not a storage migration.
Verify the deployment's reviewed schema/backfill before rollout; no automatic
ownership migration is established by this guide. Ordinary updates cannot move
registrations between these scopes. Multiple independent tenants per org remain
future work. See [normalization and isolation](https://m7.org/docs/api/api.user.m7.org/oauth-clients.md#ownership-and-directory-context).

## Install in dependency order

1. Install compatible shared PHP library/platform source. Keep the existing
   Management group repositories and configured membership metadata support:
   `organization_manage_group_meta`, keyed by the Management membership UUID.
   The org management controller's `ensureStorage()` ensures its group,
   membership, link, metadata and principal repositories.
2. Install API User's `OrganizationManagementTags` adapter. Its constructor
   lazily calls `ensureTables()` for `organization_manage_tag_names` and
   `organization_manage_tag_junction`; `ensureTables()` is also available for
   controlled explicit installation through the application's configured SQL
   service. Use the shared repository installers, database UUID helpers
   `uuid_bin()` / `uuid_str()`, normal SQL quote setup, and appropriate schema
   creation privileges. Verify the tables before SSO reads them. SSO does not
   install them. Preserve existing data; do not replace an existing schema or
   run test fixtures on production.
3. Install SSO's `/userinfo/orgs` endpoint, explicit consented `orgs` scope and
   discovery metadata. Verify both public metadata URLs and the configured mTLS
   gate. The richer projection reads live membership tags and `pub`. Owner-controlled
   discovery also requires compatible platform `DiscoveryPolicy` and
   `OrganizationConfig` service methods before the new SSO code is installed.
4. Install updated Token/PHP source with the Organizations and Emails classes
   and facade wiring. Existing Token/PHP 0.1.3 ZIPs lack those classes; follow
   [current-source SDK installation](https://m7.org/docs/sdk/m7-identity/cli/organization-access.md#installation-and-release-boundary).
5. Install the platform remote organization service and shared bootstrap with
   `M7_LIB_ROOT`, `M7_PLATFORM_ROOT`, and `M7_IDENTITY_TOKEN_ROOT` pointing at
   compatible deployment roots. The platform bootstrap needs the SDK root
   containing `packages/token-php/autoload.php`, not the CLI package-root form.
   Optional local imports use the application-local `remote_organizations`
   repository and its `ensureTables()`; live lookup needs no import table.
6. Install API BigFS and BigFS pickup/client configuration. Register `orgs` for
   the BigFS OAuth client and obtain fresh consent; an existing token does not
   gain it from registration alone. See
   [BigFS organization acquisition](https://m7.org/docs/api/api.bigfs.m7.org/organizations.md).
7. Install API User and User M7 together for the later role enforcement,
   read-only modal and departure slices. Those slices add no tables/columns or
   extra schema migration. The operational `viewer` → `member` migration is
   separate from the shared generic group enum.
8. Install compatible platform, API User, SSO and User M7 source for the
   **Access → Members / Policy** discovery controls. Policy is stored in the
   existing `organization_config`; this slice adds no schema migration or new
   OAuth scopes. Both discovery switches default off for existing and new orgs.
   An owner must enable the appropriate switch or add an allow rule for BigFS
   or another consuming app to see the org. Rule order is authoritative.

## Acceptance boundaries

Use current-source role, owner app/key, tenant-security, org tags/pub/leave,
owner-only discovery policy, SSO projection/discovery, SDK validation, platform
and API BigFS checks. Storage
and locking suites require a disposable authorized scratch database; browser
fixtures use synthetic responses. Release extraction verifies packaging only.
Before claiming live rollout, exercise a consented consumer token, sender
bindings, signed/encrypted policy if configured, fresh membership changes and
departure through the actual deployment.

The platform offline-access accessible-app helper is a remaining role-boundary
inconsistency: issued client-credentials search/view/revoke and device app-grant
inventory use active Management membership in stored `org`, without filtering
the stored owner role. They exclude creator-only access but are broader than
owner-only registration/key management. The current owner-boundary fixtures
cover registration/key routes; they do not establish owner-only issued-grant
access. See [issued-record behavior](https://m7.org/docs/api/api.user.m7.org/oauth-client-credentials.md#search-issued-records).

Admin delegation and admin app/key inventory remain deferred. The standalone
catalogue UI and shared tag pool were cancelled; membership expiry was not
added. BigFS transports/displays facts, while bucket authorization and each
other product's scope semantics remain separate work. Blog adoption is future
work. No schema replacement, production fixture run or release creation is
part of this upgrade guide.