feat(routes): live group-route expansion + full-live invalidation (§11 tail R3)

The runtime half. Group route TEMPLATES now expand into every descendant
app's in-memory match slice, live, with no per-app materialization.

- `compile_effective_routes` consumes the `list_effective` expansion and
  applies NEAREST-OWNER-WINS shadowing: for one app, identical binding
  tuples (method+host+path) owned at multiple chain levels collapse to the
  nearest (an app's own route shadows an ancestor-group template); a nearer
  group beats a farther one. Non-identical bindings coexist and the
  existing matcher precedence resolves each request. `compile_route` now
  takes the effective app_id, so the matcher + dispatch are unchanged.
- `rebuild_route_table` is the single refresh chokepoint (list_effective →
  compile_effective_routes → replace_all). Route CRUD, the apply reconcile,
  and startup all route through it; the apply guards drop the "a group node
  touches no routes" assumption (a group apply may now create templates).
- FULL-LIVE INVALIDATION: app create/delete (apps_api) and group reparent
  (groups_api) rebuild the snapshot, so inherited routes take effect the
  instant the tree changes — matching the live model of triggers/vars.
  Best-effort, mirroring apply: a failed rebuild self-heals on the next
  write or restart, never failing the committed mutation.

The isolation boundary is the chain expansion: a template lands only in the
slices of apps whose ancestor chain contains the owning group. Pinned by a
deterministic live-DB integration test (descendant inherits, sibling
subtree does not, app shadows by identical binding, non-identical coexists).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

crates/manager-core/src/apply_service.rs

@@ -1173,9 +1173,10 @@ impl ApplyService {
 
         // Post-commit: rebuild the orchestrator's route snapshot once. A
         // failure here doesn't undo the committed DB write — the table
-        // self-heals on the next route write or restart. A group node touches
-        // no routes, so there's nothing to refresh.
-        if matches!(owner, ApplyOwner::App(_)) {
+        // self-heals on the next route write or restart. §11 tail: a GROUP node
+        // may now declare route TEMPLATES, so refresh on either owner (the
+        // rebuild expands templates into every descendant app's slice).
+        {
             if let Err(e) = self.refresh_route_table().await {
                 tracing::warn!(error = %e, "apply: route table refresh failed");
                 report
@@ -1254,7 +1255,6 @@ impl ApplyService {
 
         let mut report = ApplyReport::default();
         let mut group_script_index: HashMap<GroupId, HashMap<String, ScriptId>> = HashMap::new();
-        let mut any_app = false;
 
         // Phase A — groups first: reconcile each and record its post-create
         // `name -> id` so descendant app nodes can resolve inherited bindings.
@@ -1285,7 +1285,6 @@ impl ApplyService {
         // ids just created) and pre-existing ancestors, then reconcile.
         for p in &prepared {
             if let ApplyOwner::App(_) = p.owner {
-                any_app = true;
                 report
                     .warnings
                     .extend(disabled_target_warnings(&p.node.bundle));
@@ -1314,14 +1313,15 @@ impl ApplyService {
         tx.commit()
             .await
             .map_err(|e| ApplyError::Backend(e.to_string()))?;
-        // One post-commit route refresh covers every app node touched.
-        if any_app {
-            if let Err(e) = self.refresh_route_table().await {
-                tracing::warn!(error = %e, "apply_tree: route table refresh failed");
-                report
-                    .warnings
-                    .push("route table refresh failed; it will self-heal".into());
-            }
+        // One post-commit route refresh covers the whole tree. §11 tail: a
+        // group node may declare route TEMPLATES affecting descendant apps even
+        // when no app node is in this apply, so refresh unconditionally (a full
+        // rebuild; cheap relative to a tree apply).
+        if let Err(e) = self.refresh_route_table().await {
+            tracing::warn!(error = %e, "apply_tree: route table refresh failed");
+            report
+                .warnings
+                .push("route table refresh failed; it will self-heal".into());
         }
         Ok(report)
     }
@@ -1608,14 +1608,11 @@ impl ApplyService {
     }
 
     async fn refresh_route_table(&self) -> Result<(), ApplyError> {
-        let rows = self
-            .routes
-            .list_all()
+        // §11 tail: rebuild via the live expansion so a group route TEMPLATE
+        // created in this apply lands in every descendant app's slice.
+        crate::route_admin::rebuild_route_table(self.routes.as_ref(), &self.route_table)
             .await
-            .map_err(|e| ApplyError::Backend(e.to_string()))?;
-        let compiled = crate::route_admin::compile_routes(&rows);
-        self.route_table.replace_all(compiled);
-        Ok(())
+            .map_err(|e| ApplyError::Backend(e.to_string()))
     }
 
     /// Resolve a referenced secret to plaintext, then re-seal it for an

crates/manager-core/src/apps_api.rs

@@ -16,7 +16,7 @@ use axum::http::StatusCode;
 use axum::response::{IntoResponse, Json, Response};
 use axum::routing::{delete, get, post};
 use axum::{Extension, Router};
-use picloud_orchestrator_core::routing::{pattern, AppDomainTable, CompiledAppDomain};
+use picloud_orchestrator_core::routing::{pattern, AppDomainTable, CompiledAppDomain, RouteTable};
 use picloud_shared::{App, AppDomain, AppId, AppRole, InstanceRole, Principal};
 use serde::{Deserialize, Serialize};
 use serde_json::json;
@@ -43,6 +43,10 @@ pub struct AppsState {
     /// Cached host → app_id lookup; replaced after every domain CRUD
     /// operation so the orchestrator sees changes immediately.
     pub domain_table: Arc<AppDomainTable>,
+    /// §11 tail: the route match snapshot. Creating/deleting an app changes
+    /// which group route TEMPLATES are inherited, so it is rebuilt here
+    /// (full-live invalidation) — mirroring the domain_table refresh.
+    pub route_table: Arc<RouteTable>,
     /// Capability gate — Phase 3.5.
     pub authz: Arc<dyn AuthzRepo>,
     /// Group tree — resolves an app's parent group at create time
@@ -226,6 +230,9 @@ async fn create_app(
             )
             .await?
     };
+    // The new app may sit under a group that owns route TEMPLATES — make them
+    // servable immediately (full-live invalidation).
+    refresh_route_cache(&s).await;
     Ok((StatusCode::CREATED, Json(created)))
 }
 
@@ -368,6 +375,8 @@ async fn delete_app(
         s.apps.delete(app.id).await?;
     }
     refresh_domain_cache(&s).await?;
+    // Drop the deleted app's slice (and any routes it owned) from the snapshot.
+    refresh_route_cache(&s).await;
     Ok(StatusCode::NO_CONTENT)
 }
 
@@ -545,6 +554,19 @@ fn validate_slug(slug: &str) -> Result<(), AppsApiError> {
 
 /// Rebuild the in-memory host → app_id cache used by the orchestrator.
 /// Called after every domain CRUD operation.
+/// §11 tail: rebuild the route match snapshot after a tree mutation that
+/// changes route inheritance (an app gained/lost its place in the group tree,
+/// so the set of ancestor-group route TEMPLATES it serves changed). Best-effort
+/// to mirror the apply path — a failure leaves a stale-but-self-healing table
+/// rather than failing the committed mutation.
+async fn refresh_route_cache(state: &AppsState) {
+    if let Err(e) =
+        crate::route_admin::rebuild_route_table(state.routes.as_ref(), &state.route_table).await
+    {
+        tracing::warn!(error = %e, "apps: route table refresh failed; it will self-heal");
+    }
+}
+
 pub async fn refresh_domain_cache(state: &AppsState) -> Result<(), AppsApiError> {
     let all = state.domains.list_all().await?;
     let compiled = all

crates/manager-core/src/groups_api.rs

@@ -22,6 +22,8 @@ use serde::{Deserialize, Serialize};
 use serde_json::json;
 use uuid::Uuid;
 
+use picloud_orchestrator_core::routing::RouteTable;
+
 use crate::admin_user_repo::{AdminUserRepository, AdminUserRow};
 use crate::app_repo::AppRepository;
 use crate::authz::{require, AuthzDenied, AuthzError, AuthzRepo, Capability};
@@ -29,6 +31,7 @@ use crate::group_members_repo::{
     GroupMembersRepository, GroupMembersRepositoryError, GroupMembershipDetail, GroupMembershipRow,
 };
 use crate::group_repo::{GroupRepository, GroupRepositoryError};
+use crate::route_repo::RouteRepository;
 
 const SLUG_MAX: usize = 63;
 const RESERVED_SLUGS: &[&str] = &[
@@ -42,6 +45,11 @@ pub struct GroupsState {
     pub apps: Arc<dyn AppRepository>,
     pub users: Arc<dyn AdminUserRepository>,
     pub authz: Arc<dyn AuthzRepo>,
+    /// §11 tail full-live invalidation: reparenting a group moves a whole
+    /// subtree, changing which ancestor-group route TEMPLATES its descendant
+    /// apps inherit — so the route snapshot is rebuilt after a reparent.
+    pub routes: Arc<dyn RouteRepository>,
+    pub route_table: Arc<RouteTable>,
 }
 
 pub fn groups_router(state: GroupsState) -> Router {
@@ -280,6 +288,13 @@ async fn reparent_group(
         }
     };
     let moved = s.groups.reparent(group.id, new_parent).await?;
+    // §11 tail: the moved subtree now inherits a different set of ancestor-group
+    // route TEMPLATES — rebuild the snapshot (best-effort; self-heals on the
+    // next route write or restart if it fails).
+    if let Err(e) = crate::route_admin::rebuild_route_table(s.routes.as_ref(), &s.route_table).await
+    {
+        tracing::warn!(error = %e, "groups: route table refresh after reparent failed; it will self-heal");
+    }
     Ok(Json(moved))
 }
 

crates/manager-core/src/lib.rs

@@ -218,7 +218,7 @@ pub use repo::{
     ExecutionLogRepository, NewScript, PostgresExecutionLogRepository, PostgresScriptRepository,
     RepoResolver, ScriptPatch, ScriptRepository, ScriptRepositoryError,
 };
-pub use route_admin::{compile_routes, route_admin_router, RouteAdminState};
+pub use route_admin::{compile_routes, rebuild_route_table, route_admin_router, RouteAdminState};
 pub use route_repo::{NewRoute, PostgresRouteRepository, RouteRepository};
 pub use sandbox::{CeilingError, SandboxCeiling};
 pub use secrets_api::{secrets_router, SecretsApiError, SecretsState};

crates/manager-core/src/route_admin.rs

@@ -20,7 +20,7 @@ use uuid::Uuid;
 use crate::app_domain_repo::AppDomainRepository;
 use crate::authz::{require, AuthzDenied, AuthzRepo, Capability};
 use crate::repo::{ScriptRepository, ScriptRepositoryError};
-use crate::route_repo::{NewRoute, RouteRepository};
+use crate::route_repo::{EffectiveRoute, NewRoute, RouteRepository};
 
 pub struct RouteAdminState<RR, SR> {
     pub routes: Arc<RR>,
@@ -388,9 +388,26 @@ fn first_conflict(
 async fn refresh_table<RR: RouteRepository, SR: ScriptRepository>(
     state: &RouteAdminState<RR, SR>,
 ) -> Result<(), RouteApiError> {
-    let rows = state.routes.list_all().await?;
-    let compiled = compile_routes(&rows);
-    state.table.replace_all(compiled);
+    rebuild_route_table(state.routes.as_ref(), &state.table).await?;
+    Ok(())
+}
+
+/// Rebuild the entire in-memory [`RouteTable`] from the database, expanding
+/// §11 tail group route TEMPLATES into every descendant app's slice.
+///
+/// This is the single chokepoint for route-table refresh — called from route
+/// CRUD, the declarative apply reconcile, startup, and (full-live invalidation)
+/// every tree mutation that changes inheritance (app create/reparent/delete,
+/// group reparent). It reads the live expansion (`list_effective`) so a group
+/// template lands in the slice of each app whose ancestor chain contains the
+/// owning group, and nowhere else — the chain walk is the isolation boundary.
+pub async fn rebuild_route_table(
+    routes: &dyn RouteRepository,
+    table: &RouteTable,
+) -> Result<(), ScriptRepositoryError> {
+    let effective = routes.list_effective().await?;
+    let compiled = compile_effective_routes(&effective);
+    table.replace_all(compiled);
     Ok(())
 }
 
@@ -423,6 +440,59 @@ pub fn compile_routes(rows: &[Route]) -> Vec<CompiledRoute> {
         .collect()
 }
 
+/// Compile the §11 tail effective expansion into per-app match slices, applying
+/// **nearest-owner-wins shadowing**: for a given app, if the same binding tuple
+/// (method + host + path) is owned at more than one chain level — e.g. the app
+/// declares its own `/x` and an ancestor group also templates `/x` — the
+/// nearest owner (lowest `depth`) wins and the farther one is dropped. Unlike
+/// triggers (which fan out to every match), a route resolves to a single
+/// winner, so identical bindings MUST dedupe; **non-identical** bindings (the
+/// app's `/users/:id` + the group's `/users/admin`) coexist and the matcher's
+/// existing precedence picks per request.
+///
+/// Requires `rows` ordered by `(effective_app_id, depth ASC)` — which
+/// [`RouteRepository::list_effective`] guarantees — so first-seen is nearest.
+#[must_use]
+pub fn compile_effective_routes(rows: &[EffectiveRoute]) -> Vec<CompiledRoute> {
+    let mut seen: std::collections::HashSet<(AppId, String)> = std::collections::HashSet::new();
+    let mut out = Vec::new();
+    for er in rows {
+        if !er.route.enabled {
+            continue;
+        }
+        // A nearer owner already claimed this binding for this app → shadow.
+        if !seen.insert((er.effective_app_id, binding_key(&er.route))) {
+            continue;
+        }
+        if let Some(compiled) = compile_one(&er.route, er.effective_app_id) {
+            out.push(compiled);
+        }
+    }
+    out
+}
+
+/// The shadow-identity of a route within one app's slice: the binding tuple a
+/// request resolves against (method + host + path), matching the per-owner DB
+/// unique index. Two routes with the same key are "the same endpoint" and only
+/// the nearest owner's survives.
+fn binding_key(r: &Route) -> String {
+    let method = r
+        .method
+        .as_deref()
+        .map_or("ANY".to_string(), str::to_uppercase);
+    let host_kind = match r.host_kind {
+        HostKind::Any => "any",
+        HostKind::Strict => "strict",
+        HostKind::Wildcard => "wildcard",
+    };
+    let path_kind = match r.path_kind {
+        PathKind::Exact => "exact",
+        PathKind::Prefix => "prefix",
+        PathKind::Param => "param",
+    };
+    format!("{method} {host_kind} {} {path_kind} {}", r.host, r.path)
+}
+
 /// Parse one stored route into a `CompiledRoute` bound to `app_id` (the
 /// effective app — its own for app routes, the firing descendant for a group
 /// template). Lenient: an un-compilable row is skipped-with-warning, never an