docs(spritz): define workspace release semantics

Author: Onur Solmaz

docs/2026-03-23-shared-app-tenant-routing-architecture.md

@@ -677,8 +677,8 @@ The intended default behavior should be:
   not on first inbound message
 - install handling should be idempotent
 - disconnect should stop routing immediately
-- reconnect should reuse the same concierge instance identity when the
-  deployment still considers that installation valid
+- reconnect should reuse the same concierge instance identity only while the
+  deployment still considers that installation active and valid
 - outbound channel actions should go back through the shared channel gateway,
   not directly from the concierge runtime to the provider
 
@@ -698,21 +698,25 @@ Spritz should then either:
 
 This gives each tenant a stable concierge before the first real conversation.
 
-### Disconnect and reconnect
+### Disconnect and later reinstall
 
 When an installation is disconnected:
 
-- the external registry should mark it disconnected
+- the external registry should stop treating that route as actively claimed
 - `channel.route.resolve` should return `unresolved`
-- the concierge instance may remain in place for later reuse, depending on
-  deployment policy
+- the previous owner should no longer retain an active reservation on that
+  route
+- any retained concierge/runtime may remain only as detached history or a
+  reusable artifact, depending on deployment policy
 
-When an installation reconnects:
+When the workspace is installed again later:
 
-- the external registry should upsert it back to an active state
-- the same concierge instance identity should be reused when possible
-- only if policy requires a clean replacement should a new concierge be
-  created
+- the external registry should create a fresh active claim for that route
+- the new owner may be the same as the previous owner or a different
+  authorized owner
+- the same concierge instance identity may be reused under the hood only if
+  deployment policy explicitly allows it
+- otherwise a new concierge should be created
 
 If the installation is still active but the runtime has disappeared:
 
@@ -783,15 +787,18 @@ Validation for this architecture should include:
    - `principalId + provider + externalScopeType + externalTenantId`
 5. Send inbound events from both tenants through the same app integration.
 6. Verify each event routes to the correct concierge instance.
-7. Verify reinstall or reconnect returns the same concierge instance identity.
+7. Verify active-route reinstall remains idempotent while the route is still
+   claimed.
 8. Verify runtime replacement preserves concierge instance identity.
 9. Verify uninstall or disconnect disables routing for that tenant.
 
 Disconnect and uninstall behavior should be explicit:
 
-- uninstall or disconnect sets `spritz.sh/concierge.state=disconnected`
-- routing must stop immediately for disconnected instances
-- reconnect may reuse the same instance identity if policy allows
+- uninstall or disconnect must remove the route from the active registry used
+  for route resolution
+- routing must stop immediately for released routes
+- a later install may reuse the same runtime identity only if deployment
+  policy allows it, but it must be treated as a fresh active claim
 
 ## Follow-ups
 

docs/2026-03-24-slack-channel-gateway-implementation-plan.md

@@ -92,7 +92,10 @@ The gateway provides:
 The resolver returns:
 
 - `instanceId`
-- route state such as `ready` or `disconnected`
+- route state such as `ready`
+
+Released or disconnected workspace routes should resolve as `unresolved`
+rather than surfacing a reserved `disconnected` active state.
 
 ### 2. Installation registry client
 
@@ -182,8 +185,10 @@ Install must be idempotent:
 2. Gateway calls the external disconnect API for the same routing identity.
 3. Route resolution must immediately stop returning a concierge for that
    workspace.
-4. The concierge instance may remain for later reuse, depending on deployment
-   policy.
+4. The active workspace claim must be released so a later install may bind the
+   same workspace to a different owner.
+5. Any retained concierge/runtime may remain only as detached history or a
+   reusable artifact, depending on deployment policy.
 
 ## Inbound Event Flow
 

docs/2026-04-17-channel-install-ownership-and-management-architecture.md

@@ -234,20 +234,24 @@ Those settings may affect runtime behavior, but they are not the same concept
 as target selection and should evolve through a separate installation-config
 surface.
 
-### Disconnect and uninstall are soft
+### Disconnect and uninstall release the active workspace claim
 
-Provider uninstall or product-side disconnect should soft-disconnect the
-installation, not hard-delete it immediately.
+Provider uninstall or product-side disconnect should release the active
+installation claim for that route.
 
 Pinned rule:
 
 - routing stops immediately
-- provider auth may be cleared according to deployment policy
-- the durable installation record remains
-- the logical concierge binding may remain for later reuse
+- provider auth tied to the released installation should be cleared or revoked
+  according to deployment policy
+- the active installation row should no longer reserve that route
+- any retained concierge/runtime may remain only as detached history or a
+  reusable artifact, not as an active claim
+- a later install for the same route should be treated as a fresh install,
+  even when the same runtime is reused under the hood
 
-This keeps reconnect flows simple and consistent with the existing shared
-channel lifecycle model.
+History and audit may still be retained, but they should not live in the same
+table or record that answers "who currently owns this workspace route."
 
 ## UX Consequences For Spritz
 
@@ -264,9 +268,13 @@ For each manageable installation, Spritz should show at least:
 The minimum action set is:
 
 - change target
-- reconnect
 - disconnect
 
+`reconnect` may still exist as a repair action for an active installation that
+is temporarily broken or missing provider auth, but it is not the path after a
+user-facing disconnect. After disconnect, the route has been released and the
+next claim should come from a fresh install flow.
+
 When an installation is in a broken but still durable state, the UI should
 still render the row and show a repair-needed state through `problemCode`
 rather than dropping the installation from the page.
@@ -286,22 +294,29 @@ shapes vary by deployment:
   installation
 - install-management APIs must authorize against the effective owner, not just
   the original installer
-- reinstall APIs must detect effective-owner mismatch and return conflict
+- reinstall APIs must detect effective-owner mismatch and return conflict only
+  while an active claim still exists for that route
 - management-target-change APIs must update target and owner together
 - mutable installation-config APIs must stay separate from target-selection APIs
+- disconnect APIs must release the active claim instead of keeping a
+  disconnected reservation behind
+- audit/history for released installations must stay separate from the active
+  registry used for ownership conflicts and route resolution
 
 These behaviors matter more than the exact transport details.
 
 ## Validation
 
 At minimum, an implementation should validate:
 
-- reinstall of the same route and same effective owner updates in place
-- reinstall of the same route and different effective owner returns conflict
+- reinstall of the same active route and same effective owner updates in place
+- reinstall of the same active route and different effective owner returns
+  conflict
 - changing to a new valid target updates the installation atomically
 - changing to a target owned by a different principal updates effective owner
 - deleting or invalidating the saved target blocks routing until repair
-- disconnect stops routing but preserves the installation for reconnect
+- disconnect stops routing and releases the route for a later fresh install by
+  the same or a different authorized owner
 - install rows expose the correct `allowedActions` and `problemCode`
 - future provider-specific configuration can change without rewriting saved
   target selection
@@ -315,7 +330,7 @@ needs for:
 
 - listing manageable installations
 - updating the selected target on an installation
-- reconnecting a disconnected installation
+- reconnecting an active but temporarily broken installation
 - surfacing repair-needed state when the saved target is no longer valid
 - defining the generic installation-config surface for provider-specific
   mutable settings