refactor(routes): drop prod-dead compile_routes; document disabled-shadow (§11 tail review)

Two review findings.

1. After R3 every production rebuild path uses `compile_effective_routes`;
   `compile_routes` (the old app-only compile) was called only by its own
   two unit tests, and its "runs in build_app" doc was stale — so the
   lenient-skip + disabled-drop regression guards no longer covered the
   live path. Remove `compile_routes` + its re-export, fold the lenient-skip
   rationale onto `compile_one`, and port both guards to
   `compile_effective_routes` (app-only rows are just depth-0 effective
   rows). Add a third guard pinning nearest-owner shadowing at the pure-
   compile layer. Fix the stale `compile_routes` mention in apply_service.

2. Document the disabled + inherited semantic: the `enabled` filter runs
   before the shadow check, so a disabled own-route does not claim its
   binding and an enabled ancestor template at the same path falls through
   ("disabled = absent", §4.3). Recorded on `compile_effective_routes` and
   in design §4.5 — the corollary (can't 404 an inherited route by
   disabling a same-path own route) points at the deferred per-app opt-out.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
MechaCat02
2026-06-30 22:14:09 +02:00
parent a977ff6a32
commit b048daa700
4 changed files with 97 additions and 41 deletions

View File

@@ -414,8 +414,12 @@ Two distinct constraints:
> reparent (`groups_api`) all route through the single `rebuild_route_table` chokepoint, so a new app
> under a group serves its templates instantly. Host-claim validation is skipped for a group template
> (no single app; descendants serve it on whatever host they claim, so templates use `host_kind = any`).
> Authoring is `[[routes]]` on a `[group]`; read-only `pic routes ls --group`. **Deferred:** per-app
> route opt-out, and multi-node route-snapshot propagation (cluster mode).
> Authoring is `[[routes]]` on a `[group]`; read-only `pic routes ls --group`. **Disabled semantic
> (§4.3):** the shadow check runs *after* the `enabled` filter, so a **disabled** own-route does not
> claim its binding — an enabled ancestor template at the same path then falls through and serves
> ("disabled = absent"). The corollary: a descendant can't 404 an inherited route by disabling a
> same-path own route. **Deferred:** per-app route opt-out (the true way to decline an inherited
> route), and multi-node route-snapshot propagation (cluster mode).
### 4.6 Secrets & `pull`