0049. Organization provisioning and reversible workspace archival

• Status: Proposed for owner review
• Date: 2026-10-31
• Extends: ADR 0017, ADR 0030, ADR 0036

Observable acceptance criteria

The instance administrator creates an organization and its first production or sandbox workspace from the application. The creator becomes the organization’s owner. An organization owner or administrator creates additional workspaces; a workspace manager can change its name; organization owners/admins archive or restore it. Changes persist after reload, use strong preconditions, and append safe audit entries in the same transaction. Invalid or denied changes preserve the prior state.

Organization owners and administrators read organization Activity with the same exact identifier, action, date filters and bounded paging as workspace Activity. Workspace-only administration does not grant organization audit access. The workspace switcher lists all workspaces the member reaches across organizations and remembers recent choices.

Decisions

The module-wave brief is the approved implementation brief in place of a separate issue. Instance administration is an explicit persisted capability, separate from organization ownership. First-run setup grants it to the first operator. An upgrade grants it only to the actor of the earliest instance.setup_completed audit entry, only if that user still exists and remains an owner or administrator of that organization; it never promotes all organization owners. Embeddings without a first-run setup receive no implicit instance administrator. Instance administration authorizes provisioning, not access to another organization’s business data.

The installation operator recovers or rotates this capability through the protected instance-administrator CLI. Its list, grant and revoke commands require owner database credentials and the private setup code on standard input. Grant and revoke are idempotent; serialized last-administrator protection prevents concurrent revocations from removing every administrator. Operators grant a replacement and verify the list before revoking the departing administrator. Each grant, revoke and refusal is an append-only installation-level change record with a truthful actor class, target user identifier, operation, outcome and safe reason code. The CLI actor is the installation operator authenticated by the shared setup code and has no invented human user id. First-run setup records its real user actor; an upgrade records the installation operator provenance while targeting the eligible historical setup actor. Target identifiers remain in the history after identity deletion. Refusals that can be safely tied to the matching installation, including a last-administrator refusal, commit their record before the command returns exit 1; malformed input, instance mismatch and failures before that identification are not attributed.

Organization and workspace provisioning resolve the actor’s live authority inside the transaction that writes the new identities, membership, audit and domain events. Organization owners/admins inherit full workspace administration. Workspace managers cannot create a new workspace and grant themselves permissions beyond their live delegation ceiling. The new workspaces.configure grant permits workspace name settings only with unrestricted property access; archival remains organization administration. Environment is immutable after creation. Sandbox marks a training workspace with separate data and gc_test_ API keys. It connects to Channex staging since ADR 0050; before that it used the same Channex service as production; a sandbox key saved then fails closed until a staging key replaces it.

There are no existing persisted workspace locale or measurement defaults. This change edits the workspace name and lifecycle only. Regional staff formatting remains the reader’s existing explicit request context; property time zone and currency remain property settings. Adding a workspace setting with no downstream consumer would promise behavior the product does not implement. A future default-locale or units workflow must define inheritance and user overrides before adding persistence.

Archival requires organization ownership or administration. It is reversible and never deletes records or memberships. An archived workspace loses operational access for sessions, device tokens, API keys, organization tokens and client sessions, while administrators keep an explicit settings path for restoration and audit. Channex properties must first be unlinked through Channels and their webhook cleanup finished. Archival waits on the existing ownership fence and refuses linked or cleanup-pending mappings; it retains the saved encrypted credential. This uses an operator workflow the product supports and prevents archival from suspending cleanup before its remote work has settled. Restrictive RLS also denies business-table access to queued app/worker work while archived; control-plane memberships, roles, audit and events remain available for recovery. The confirmation states these consequences before the write. Schedulers exclude archived workspaces before dispatch, as well as enforcing the business row policy; migration 0045 gives the nightly drift check and the Channex alerts (ADR 0048) the same exclusion. Restore leaves property night-audit automation paused until an operator reviews the business date and explicitly re-enables it. Pending webhook deliveries strictly older than the normal retry window of 246,960 seconds (68 hours 36 minutes, about 69 hours) at restore time become expired, preserving the delivery log. Deliveries exactly at the boundary remain pending. Restore also removes stale webhook outbox routing markers older than that window, so queued events that have no delivery yet are not dispatched automatically. It preserves domain events for the existing 30-day manual replay window. Operators can manually replay the event within 30 days of the event; restore does not send months of stale notifications. Both the restore confirmation and success notice explain the operator’s review and recovery work. The restore audit and matching domain event record the actually paused property identifiers, the expired delivery total and counts by endpoint, and the withheld outbox-event count. Each affected property also receives a workspace Activity entry with enabled:false and reason:workspace_restored, so the explanation remains after reload. The trigger produces these facts inside the same transaction as the restore. The expiration clock injection may move the cutoff earlier for deterministic tests; PostgreSQL clamps future values to its normal retry boundary so a caller cannot expire recent deliveries.

Workspace selection is independent of the session’s active organization. The requested workspace determines which live membership is resolved; a preference cookie or workspace header never grants access. The directory is member-specific and includes organization labels. Archived entries are shown only to members who may configure or restore them; the landing and post-sign-in onboarding prefer an active workspace and use retained settings for an archived-only fallback. Recent choices are user-scoped local UI preferences on that browser, ignore the old browser-wide cookie, and are filtered against that directory. The landing choice, workspace recents, and per-workspace property recents use an opaque SHA-256 hash of the authenticated actor in their cookie names; raw usr_… identifiers never appear in browser preference names. Device sessions remain bound to the organization that issued them; API keys remain bound to their workspace.

The organization Activity view includes organization-scoped audit entries and relevant workspace lifecycle entries. It follows ADR 0016 with opaque keyset cursors over (occurred_at, id), descending, bound to the organization and exact action, actor, subject and instant filters. limit is 1–100 (API default 20; the screen requests 50); responses are { data, next_cursor, has_more }, and cursor misuse returns cursor.invalid. Workspace Activity retains ADR 0030’s temporary numeric-offset deviation; large exports remain planned.

Consequences

Operators can provision and manage tenancy through the screens and the public contract. Archival provides a recovery workflow without silently deleting operational history. Organization export/import, SSO/SCIM and consolidated reports remain separate capabilities; this ADR makes no claim that those enterprise workflows are implemented.

Amendment 2026-11-01: workspace Activity keyset and exports

Workspace Activity gains the same keyset cursors over (occurred_at, id) descending, bound to the workspace and its exact filters, with a page size of 50, as keyset_cursor and { next_keyset_cursor, has_more }; ADR 0030’s numeric offsets remain beside them, deprecated, for clients of revision 6.6.0. Organization Activity also gains CSV and JSON exports for owners and administrators, bounded and audited as described in ADR 0030’s amendment of the same date; the organization’s audit.exported entry is organization-level, so it appears in organization Activity and not in any workspace’s.