Eve library

BASE.2.a — Surface classification schema

Evidence

Revision 1

On this page

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. partial is 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 than none is a release-blocking finding regardless of primary class.
  • providerStates[] — for provider-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: partial until 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.ts freezes STUDIO_ISIS_ALLOWED_ROUTE_SEGMENTS = [], so isAaaOnlyRoute returns 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.ts reports provider_not_configured when credentials are absent; any surface bound to it inherits providerStates: [not_configured, configured].
  • redirected — apps/metis/admin/src/middleware.ts / apps/metis/web/src/middleware.ts issue auth redirects; routes reachable only through such a redirect to a login destination classify as redirected (verify final destination per BASE.2.e).
  • live — apps/veritas/web/src/app/[locale]/reading-list/page.tsx backed 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 not live merely because its module exists — the proxy fail-closes it (ledger §1's explicit trap).
  • A page.tsx that renders <EmptyState/> for a legitimately empty live query is not dead — it is live with dataStates: [empty].
  • A *.spec.ts / *-utils.ts file inside a pages/ directory is not a surface at all — it is excluded from routes.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 not fixture-backed in production — fixture classification requires the fixture path to be reachable in a production configuration.

6. Assignment procedure (per surface, BASE.2.b–g)#

  1. Resolve the effective host, middleware, flags, and authorization for each role (BASE.2.b) → populate roleMatrix.
  2. Trace the data source with fixtures disabled (BASE.2.c, BASE.7.b) → wiringCompleteness, fixtureLeakage.
  3. Exercise provider present/absent (BASE.2.d, BASE.7.e) → providerStates.
  4. Verify redirect destinations (BASE.2.e) before assigning redirected.
  5. Apply the precedence table to pick the single primary class.
  6. Attach evidenceRefs; a surface with no evidence stays provisional.
  7. Any surface that is dead/ambiguous/mixed gets an owner + action (BASE.2.f).
  8. Independent review reconciles the classified set against the route inventory with zero unclassified reachable routes (BASE.2.g).