Codex 0 · Chapter 11 — Surfaces

This chapter specifies the surface taxonomy, the contract every surface must satisfy before it may be marked built, naming and URL doctrine, and the full inventory of every SURF- entry against the routes that exist today.

11.0 Purpose

A surface is where a person meets the institution. This chapter turns Codex 6's experience doctrine and the Codex 6 Rubric into an enforceable specification of what a surface is, what it must declare before it exists, and what it must prove before its Registry entry may say built.

11.1 Scope and non-scope

In scope. The surface taxonomy; the surface contract (primary action, layers, states, metadata, accessibility, authorisation); naming and URL doctrine; the full SURF- inventory with route, audience, primary action, owning division, data consumed, and status; the rubric gate that governs the built status.

Not in scope. The engines and boundaries a surface calls (Chapters 5, 10), the entities it reads and writes (Chapter 07), the permission model it is authorised against (Chapter 08), dashboards (Chapter 12, a distinct surface class with its own doctrine), and visual design tokens and components (Codex 6, the design system itself).

11.2 The surface taxonomy

Every surface belongs to exactly one of six classes, recorded in its Registry entry:

institutional   the public voice of the institution: mission, charter, research, ecosystem
division        a division's front matter and delivery surfaces (Academy, Advisory, ...)
member          authenticated, person-scoped: what a member owns and does
operator        internal, role-scoped: what an employee or steward administers
verification    public, permanent, machine- and human-readable proof (credentials)
machine         no human renderer: API responses and service-to-service contracts

11.2.1 A surface's class determines its default authentication class (§10.10) and its default register: institutional and verification surfaces speak to a stranger; member and operator surfaces speak to someone already inside; machine surfaces do not speak at all.

11.2.2 A surface may serve more than one user type (§04.4) without changing class. /academy is one institutional surface visited by both a public visitor and an enrolled scholar; it does not fork into two surfaces to do this (§9.4.2 restated for the surface layer).

11.2.3 Verification is its own class, distinct from institutional, because its permanence obligation (§10.3.3, §10.12.5) binds the surface as well as the boundary behind it. A verification surface is written to still resolve correctly in twenty years.

11.2.4 Taxonomy diagram

 institutional ─── the public voice: Charter, Philosophy, Research, Ecosystem
 division      ─── a division's front matter and delivery: Academy today
 member        ─── authenticated, person-scoped: /scholar/*
 operator      ─── internal, role-scoped: consoles reserved (§11.6.4)
 verification  ─── permanent, public proof: credential verification (reserved)
 machine       ─── no renderer: API- boundaries consumed directly

Every route in src/routes today falls into institutional, division, or member. No operator, verification, or machine-class surface is built; each is reserved (§11.6.4) or specified only as an API- boundary (Chapter 10).

11.3 The surface contract

No route may be marked built in the Registry until it satisfies every clause of this section. A surface that satisfies some but not all is partial, and the Registry entry names what remains.

11.3.1 One primary action

11.3.1.1 Every surface has exactly one primary action, named as the outcome it produces, not as a verb of the interface ("Enrol," not "Submit").

11.3.1.2 Secondary paths may exist but never carry the same visual weight as the primary action. A surface with two candidate primary actions is defective regardless of any other quality (Rubric dimension 1).

11.3.1.3 A surface with no discernible next step is not a surface; it is unfinished.

11.3.2 Layers

11.3.2.1 Every surface declares a surface layer (shown on arrival), at least one further layer reached by a labelled affordance, and, where the domain has expert precision to offer, a precision layer reached without leaving the surface.

11.3.2.2 What is withheld on arrival is a deliberate choice, stated in the surface's specification, not an accident of what was easiest to build first.

11.3.2.3 Complexity is earned by the person reaching for it. A surface that imposes its precision layer on arrival fails progressive disclosure regardless of how well-organised that layer is.

11.3.3 The five states

11.3.3.1 Every surface that reads or writes data specifies, in writing, before implementation: empty, loading, partial (some data unavailable), error, and unauthorised. A sixth state — offline or poor connection — is specified wherever the surface is reasonably used outside a reliable network.

11.3.3.2 An error state names cause, consequence, and remedy in plain language. A raw error, a dead end with no remedy, or an irreversible action taken without prior warning is a blocking defect (Rubric dimension 7, score 0).

11.3.3.3 An unauthorised state names what is missing and what the person can do about it. It never simply disappears the surface without explanation, because concealment is not permission's substitute (§04.2.2.2, §08.4).

11.3.4 Metadata

11.3.4.1 Every content route carries a unique title under 60 characters, a description under 160 characters, and social tags (og:title, og:description, and og:image/twitter:image where the surface renders a meaningful cover).

11.3.4.2 No two routes may share a title or description. A shared metadata block across distinct routes is a defect found in review, not a matter of taste.

11.3.5 Accessibility

11.3.5.1 Every surface is keyboard-complete with visible focus, correct landmark and heading order, alternative text for meaning-bearing images, verified contrast, and respect for reduced motion, per Codex 6.

11.3.5.2 Accessibility is verified, not asserted. The Registry proposal and rubric self-score state how it was checked (Rubric dimension 8).

11.3.6 Server-side authorisation

11.3.6.1 What a surface shows is decided server-side from the viewer's roles and scope (§04.2.2.2, §08.4, §10.10.2). No surface conceals data in the client that the server would still return to a suitably crafted request.

11.3.6.2 A surface's specification states explicitly, per user type that can reach it, what is never visible there — quoting the relevant "never sees" clause of §04.4. An unstated "never visible here" field is an unanswered field, and the surface is not ready.

11.3.6.3 Every write a surface performs names the entities it emits and the audit record produced, where the workflow it belongs to requires one (§09.2.3.1).

11.4 Naming and URL doctrine

11.4.1 A route's path is a noun or noun phrase describing what is there, in the plural for a collection and the singular for an item (/institutions, /institutions/:slug), never a verb describing an interaction (/do-enrollment).

11.4.2 A route nests to reflect ownership in the data model, not to reflect navigation convenience. /academy/schools/:school/:program/:course/:module/:lesson mirrors the curriculum hierarchy (ENT-09) exactly; a shortcut route that skips a level is never introduced merely to save a click.

11.4.3 Slugs are stable identifiers, never regenerated on a content edit. A slug that must change is redirected permanently from its prior form, because external citations — including credential verification links — must still resolve.

11.4.4 Authenticated member surfaces are namespaced under the person's type (/scholar, /scholar/portfolio), never mixed into the institutional namespace, so that authentication boundary is visible in the URL itself.

11.4.5 A reserved surface is named in the Registry (§11.6.4) before any route exists, so that a future implementer finds the name already claimed rather than inventing a second one.

11.4.6 No route encodes a person's identity, role, or any credential detail in a human-readable query parameter where that value is consequential to authorisation; authorisation is resolved from the session, never from the URL (§10.10.2, restated as a naming rule).

11.4.7 Lifecycle of a surface's status

11.4.7.1 A surface begins reserved: named in the Registry, no route exists.

11.4.7.2 A surface becomes partial the day a route exists and renders real data for at least one of its declared user types, even where states, metadata, or the rubric score are incomplete. partial always names what remains.

11.4.7.3 A surface becomes built only after the rubric gate (§11.5) is passed and every clause of the surface contract (§11.3) is satisfied for every user type the Registry entry names as its audience.

11.4.7.4 Status moves upward only through work (Registry rule 5, restated). A surface is never marked built in anticipation of finishing work, and a regression that reintroduces a missing state or a broken authorisation check moves the entry back to partial until fixed.

11.5 The rubric gate

11.5.1 No SURF- Registry entry may carry status built without a completed rubric self-score (CODEX-6/RUBRIC.md) and a completed review form, attached to the entry.

11.5.2 A surface scoring 0 on any rubric dimension does not ship at any total score. A surface scoring 1 on a dimension ships only with a named remediation owner and date; the Registry entry's status remains partial until that remediation lands.

11.5.3 A surface at or below 16 total is redesigned, not patched, and does not move to built in its patched form.

11.5.4 The final gate — "did this make the person's life better?" — is answered in writing for every surface before built. A surface that only "increased engagement" fails this gate regardless of score and is removed, not shipped, per Codex 6.

11.5.5 Passing the rubric is necessary, not sufficient. A surface may still fail Codex 1's six questions, the Codex 8 seven-axis evaluation (if it carries cost or revenue), or Institutional Critic review (Codex 10) for a major surface.

11.5.6 Note on inheritance

11.5.6.1 A surface that reuses another surface's layout primitive inherits none of that surface's rubric score. Each SURF- entry is scored on its own evidence (Rubric preamble, restated); shared components reduce the work of scoring well, never the requirement to score at all.

11.6 The surface inventory

Every entry below carries: route, audience (user types per §04.4), primary action, owning division, data consumed, and status. Status for built and partial entries is grounded in the routes present in src/routes at the time of writing; status for reserved entries reflects that no route yet exists.

11.6.1 Institutional surfaces

Owner: as stated per entry · Governing Codex: 6, plus the domain Codex named in Chapter 02.

11.6.2 Academy (division) surfaces

Owner: DIV-01 · Governing Codex: 6, 3 · data: ENT-09 curriculum, ENT-10 enrolment, ENT-07 assessment.

11.6.3 Member surfaces (authenticated)

Owner: DIV-01 · Governing Codex: 4, 6 · access decided server-side from ENT-05, never by UI concealment (§11.3.6).

Implementation note: SURF-16 through SURF-20 correspond to src/routes/_authenticated/scholar*.tsx, gated by the _authenticated route layout (src/routes/_authenticated/route.tsx), which is the enforcement point for the authentication class described in §10.10.

11.6.4 Reserved surfaces

Named here so none is invented twice. Each takes a SURF- ID and a completed Registry entry (all eight questions, §11.6, and the surface page template) the day it is proposed — not retroactively once code exists.

11.6.5 Surface-to-workflow mapping

A member surface is never a dead end for a workflow stage; every stage a person performs directly (Chapter 09) names the surface that carries it.

A stage with no surface in this table is either machine-initiated (an agent or engine acting without a human interface, Chapter 13) or exposes a gap to be closed, per §11.6.4, before the workflow can be claimed complete.

11.7 Interfaces

Every SURF- entry (Registry §9) · the surface page template (CODEX-6/TEMPLATE-page.md) and rubric (CODEX-6/RUBRIC.md) · §04.4 for the "never sees" clauses each surface must quote · Chapter 07 entities and Chapter 10 boundaries each surface consumes · Chapter 09 workflows each member surface participates in · Chapter 12 for the distinct dashboard surface class · Chapter 13 for agent-mediated surfaces.

11.8 Invariants

1. 1Every surface has exactly one primary action.
2. 2What a surface shows is always resolved server-side; UI concealment is never the enforcement mechanism.
3. 3Every content route carries unique, complete metadata.
4. 4No SURF- entry reaches built without a passed rubric self-score and review form.
5. 5A route's path and nesting mirror the data model and ownership it exposes, never navigation convenience alone.
6. 6A reserved surface is named in the Registry before it is implemented.

11.9 Prohibitions

1. 1Two candidate primary actions on one surface.
2. 2A surface shown or hidden by client-side role checking without a corresponding server-side check.
3. 3Duplicate metadata across distinct routes.
4. 4A precision layer or advanced control imposed on arrival.
5. 5A slug regenerated on content edit without a permanent redirect from its prior form.
6. 6Marking a Registry entry built on the strength of visual completeness alone, absent the rubric gate.

11.10 Open questions

1. 1Machine-surface documentation. Whether machine-class surfaces (raw API responses with no renderer) require their own Registry subclass or remain documented solely under their API- entry is undecided.
2. 2Reserved-surface expiry. Whether a name reserved in §11.6.4 for an extended period without a proposal should lapse, and by what authority, is unspecified.
3. 3Partner-branded surfaces. Whether a partner institution may ever be served a co-branded surface, and under what naming and metadata rule, is undecided (relates to §04.13.1).
4. 4Verification surface's non-web renderers. Whether the permanent verification surface (§11.6.4) must also specify a non-browser rendering (email, PDF) obligation is open, given the twenty-year resolution promise (§10.12.5).

1. 1Operator console consolidation. Whether the reserved operator consoles (administrator, steward/executive reporting) should be one surface with role-scoped views or several distinct surfaces is undecided; Chapter 14 (internal tooling) may settle this before any is proposed.
2. 2Mobile and native surfaces. Whether a dedicated native application constitutes a new surface class or a rendering of existing routes is unspecified.

11.11 Governing Codices

Codex 1 (Article VI, server-side enforcement), Codex 4 (people, visibility contract), Codex 5 (entities and boundaries a surface exposes), Codex 6 (experience doctrine and the rubric), Codex 8 (seven-axis evaluation for cost- or revenue-bearing surfaces), Codex 9 (amendment procedure), Codex 10 (Institutional Critic review for major surfaces).