Mutually-exclusive criteria for classifying every discovered workbench surface
(a route row in inventory/routes.json) as live,
fixture-backed, documentation-only, dead, redirected, or
provider-gated, plus the sub-state fields that represent mixed and partially
wired surfaces. Satisfies BASE.2.a of
V1_DOMAIN_WORKBENCHES_TODOS_2026-07-23.md.
This is the definition. Applying it — resolving each route through its real host/middleware/flags/auth and probing its data source — is BASE.2.b–g and requires runtime execution, so those children remain unchecked until the walkthrough (BASE.6) and API probe (BASE.7) produce the evidence per row.
1. The classification unit#
One surface = one reachable route as it resolves for one (audience, role,
provider-configuration, data-state) tuple. A single source file can yield
several surfaces: /studio/isis/nvidia-rtx-processing resolves to a rendered
page for an AAA operator but to a fail-closed block on the contemplative
product, so it produces two surface rows with different classifications. The
inventory row is the source; the classification row is per resolved context.
2. Primary classifications (exactly one per surface)#
Assigned by the precedence order below — the first matching rule wins, so every surface gets exactly one primary class. Precedence exists because the categories overlap in the raw signal (a provider-gated surface is also, in a sense, "not live"); precedence resolves the overlap deterministically.
| # | Class | Definition | Decisive signal (must be captured, not inferred) |
|---|---|---|---|
| 1 | dead | The route is unreachable by any authorized audience: no host renders it, or the middleware fail-closes it for everyone. | Effective-host resolution (BASE.2.b) returns 404/blocked for every role, and no redirect target exists. |
| 2 | redirected | The route exists only to send the client elsewhere; it renders no terminal content of its own. | A 3xx / redirect() / permanentRedirect() / middleware rewrite whose final destination is a different route (BASE.2.e). |
| 3 | provider-gated | The route renders, but its core capability is unavailable until an external provider/credential/flag is configured; absence yields explicit not_configured/503, never fabricated data. |
With provider config removed, the API/UI preserve not_configured/503 semantics (BASE.2.d, BASE.7.e). |
| 4 | documentation-only | The route renders static explanatory/reference content with no live data binding and no mutation. | No data-source request is initiated by the surface; content is compiled/static (BASE.2.c returns no backing API). |
| 5 | fixture-backed | The route renders, but its data originates from a fixture/mock/seed/interception path rather than a live source. | A fixture/demo/mock switch is active, or a mock signature is detected in the response, and disabling it changes the result (BASE.7.b, BASE.7.g). |
| 6 | live | The route renders real data from a persisted or provider source for an authorized audience. | Displayed values match persisted/provider source data with all fixture switches off (BASE.7.c). |
If a surface matches none of these after runtime resolution, it is an unclassified exception and must be owned and remediated per BASE.2.f — the schema forbids leaving a reachable surface unclassified.
3. Sub-state fields (represent mixed & partial surfaces)#
Primary class is not enough for real surfaces, which are frequently partly live and partly stubbed. Every classification row additionally carries these orthogonal fields so a mixed surface is represented precisely rather than forced into one bucket:
wiringCompleteness∈ {full,partial,none} — of the data regions the surface presents, how many resolve to their intended live source.partialis mandatory when any region is live and any other is fixture/absent (e.g., a Veritas newsroom page whose article list is live but whose analytics panel is fixture-backed).fixtureLeakage∈ {none,possible,confirmed} — whether fixture/mock data can reach this surface in a production configuration (BASE.7.g). Any value other thannoneis a release-blocking finding regardless of primary class.providerStates[]— forprovider-gated(and any surface with an optional provider), the observed result in each of { configured,not_configured, error, partial } (BASE.2.d).roleMatrix[]— the primary class per authorized role, since the same route is often live for an operator and dead/redirected for a customer (the Studio-boundary case). The row-level primary class is the union; per-role divergence lives here.dataStates[]— observed { loaded, empty, partial, unauthorized, unavailable, error } states (BASE.2.d), so an empty-but-live surface is not misread as dead.evidenceRefs[]— links to the walkthrough screenshot/trace (BASE.6) and API probe (BASE.7) that justify the assignment. A classification without an evidence ref is provisional and cannot flip a BASE.2 child.
4. Precedence rationale (why this order)#
- dead before everything: an unreachable route cannot be live/fixture/gated; reachability is the precondition for any other class.
- redirected before provider-gated/live: a route that only forwards has no terminal content to classify; its destination is classified separately.
- provider-gated before fixture-backed/live: the honest-absence contract
(
not_configured/503) is the defining property and must be verified even when a provider happens to be configured in the test environment; classifying it as live would hide the fail-closed requirement. - documentation-only before fixture/live: a static reference page has no data binding, so fixture-vs-live is not applicable.
- fixture-backed before live: fixture provenance is a defect to surface;
when both live and fixture data are present, the surface is fixture-backed
with
wiringCompleteness: partialuntil the fixture path is removed.
5. Worked examples (grounded in this repo)#
Positive (rule fires):
- provider-gated — every
/studio/isis/*segment.libs/isis/entitlements/src/studio-boundary.tsfreezesSTUDIO_ISIS_ALLOWED_ROUTE_SEGMENTS = [], soisAaaOnlyRoutereturns true for all 31 catalogued segments; on the contemplative product they are fail-closed (manifest.proxyGovernance.studioIsisFailClosed = true).roleMatrix:{ AAA-operator: live-or-gated, customer: dead }. - provider-gated —
libs/isis/ai-providers/src/providers/comfy-cloud/comfy-cloud-provider.tsreportsprovider_not_configuredwhen credentials are absent; any surface bound to it inheritsproviderStates: [not_configured, configured]. - redirected —
apps/metis/admin/src/middleware.ts/apps/metis/web/src/middleware.tsissue auth redirects; routes reachable only through such a redirect to a login destination classify asredirected(verify final destination per BASE.2.e). - live —
apps/veritas/web/src/app/[locale]/reading-list/page.tsxbacked by the Veritas reading-list service with fixtures off (pending BASE.7.c proof).
Negative (rule must NOT fire):
- A source-mounted page under
/studio/isis/*is notlivemerely because its module exists — the proxy fail-closes it (ledger §1's explicit trap). - A
page.tsxthat renders<EmptyState/>for a legitimately empty live query is notdead— it islivewithdataStates: [empty]. - A
*.spec.ts/*-utils.tsfile inside apages/directory is not a surface at all — it is excluded fromroutes.json(BASE.1.d framework-aware detection) and therefore never classified. - A Vite React Router
<Route>that renders a component fed by MSW in a test is notfixture-backedin production — fixture classification requires the fixture path to be reachable in a production configuration.
6. Assignment procedure (per surface, BASE.2.b–g)#
- Resolve the effective host, middleware, flags, and authorization for each
role (BASE.2.b) → populate
roleMatrix. - Trace the data source with fixtures disabled (BASE.2.c, BASE.7.b) →
wiringCompleteness,fixtureLeakage. - Exercise provider present/absent (BASE.2.d, BASE.7.e) →
providerStates. - Verify redirect destinations (BASE.2.e) before assigning
redirected. - Apply the precedence table to pick the single primary class.
- Attach
evidenceRefs; a surface with no evidence stays provisional. - Any surface that is dead/ambiguous/mixed gets an owner + action (BASE.2.f).
- Independent review reconciles the classified set against the route inventory with zero unclassified reachable routes (BASE.2.g).