# BASE.2.a — Surface classification schema

Mutually-exclusive criteria for classifying every discovered workbench surface
(a route row in [`inventory/routes.json`](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`](../../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).
