TenantAtlas/specs/370-global-surface-information-architecture-contract/artifacts/surface-contract.md

# Global Surface Information Architecture Contract v1

Verification level: derived from existing implementation using Spec 368 browser-verified audit findings plus repo-verified existing surface patterns.

## Principle

Decision first. Diagnostics second. Evidence third. Technical metadata only on demand.

Practical reading: the decision layer may show evidence availability or evidence basis because that is part of the decision. Diagnostic disclosure follows the primary decision, full evidence/proof remains distinct from diagnostics, and raw technical metadata stays on demand.

This contract is a documentation and review artifact. It does not define a runtime framework, component library, presenter layer, static guard, or new persisted truth.

It is subordinate to the project constitution, product standards, operator UX standards, enterprise UI standards, action surface contract, and runtime `ActionSurfaceType` enum. The IA review language in this package must not be used as a replacement for those canonical standards.

## Verification Labels

Future specs that use this contract must label surface facts with one of these verification classes:

- `repo-verified`: confirmed in code, routes, tests, configs, or existing artifacts.
- `browser-verified`: confirmed through browser pass or screenshot.
- `derived from existing implementation`: logically derived from current implementation but not explicit product rule.
- `foundation-real`: technical foundation exists but is not yet customer/operator-safe product surface.
- `plausible`: sensible but not asserted as fact.
- `not verified`: not checked.
- `not available`: missing or unreachable.
- `deferred`: explicitly later scope.

Do not treat a plausible or deferred rule as implementation truth. Do not invent conclusions for unavailable browser evidence.

## First-Viewport Contract

Every decision-relevant surface should answer these questions before metadata:

1. Where am I?
2. What is the current state?
3. Why is this the state?
4. Why does it matter?
5. What should I do next?
6. What objects are affected?
7. What evidence supports the claim?

Default-visible structure:

- Status
- Reason
- Impact
- Primary next action
- Affected objects
- Evidence availability

On demand:

- Diagnostics
- Operation internals
- Raw IDs
- Exact timestamps
- Provider payloads
- Raw logs
- Normalization lineage
- Technical counters

## Header / First Viewport

Allowed:

- Entity title and human-readable entity type
- One primary status
- One reason or impact sentence
- One primary action
- At most two secondary actions when they are genuinely useful
- Critical blocker or warning if current
- Scope chip when needed for safety or disambiguation
- Readiness badge when it changes operator action

Disallowed by default:

- Multiple repeated status badges
- Raw IDs
- Long technical names without a human label
- Debug/provider payload terms
- Multiple equally prominent actions
- Zero metric cards
- Full lifecycle/timing detail
- Notification replay that pushes the page question down

## Main Content

Main content carries the primary answer for the page's job.

Examples:

- Backup Set: included items, restore usability, degraded/current-item exceptions when present.
- Finding: risk, reason, affected object, owner, accepted-risk state, next action.
- OperationRun: outcome, actionability, blocker/failure reason, affected objects, related evidence/diagnostic links.
- Customer Review Workspace: review outcome, findings requiring decision, accepted risks, evidence/report pack availability, limitations.
- Provider Connections: readiness, blocker reason, required action, affected workspaces/environments.

Main content must not become a metadata drawer.

## Sidebar / Aside

Allowed:

- Created/updated timestamps
- Created by
- Operation reference
- Workspace/environment context
- Source type
- Plan/billing context where relevant
- Last sync / last evaluated
- Retention or disclosure level

Rule: sidebar data may help orientation, but must never displace the decision.

## Technical Details

Collapsed by default except on explicit diagnostic or system-support surfaces.

Contains:

- Internal IDs
- Raw provider IDs
- Provider payload snippets
- Normalization lineage
- Operation context JSON
- Exact timestamps
- Debug labels
- Technical counters
- Raw logs
- Stack traces
- Advanced permission data

Customer/auditor default paths must not expose raw internals. If technical detail is available to authorized operators/support users, label it in customer-safe language and gate or collapse it appropriately.

## Evidence Area

Evidence is not diagnostics.

Evidence area shows:

- Evidence type
- Subject
- Captured at
- Customer-safe readiness
- Limitations
- Export/download action
- Related review/report

Evidence must be reachable and explain its limitations, but must not mix with raw logs, debug payloads, or runtime metadata.

## Zero-Metric Suppression

Suppress zero cards or no-attention metrics when the primary decision already says no action is needed.

Keep zero metrics visible only when:

- zero is the proof of the current decision;
- the metric is needed for audit/compliance interpretation;
- the operator must compare it with a non-zero adjacent metric;
- the page is explicitly diagnostic or system-support-oriented.

## Duplicate-Truth Control

One first-viewport block owns the current decision. Later sections add evidence or detail; they should not restate the same status, reason, impact, and next action as peers.

Allowed duplication:

- Short status chips inside rows when rows represent independent objects.
- Evidence labels that prove the decision.
- Audit trail entries that record historical states.

Disallowed duplication:

- Multiple first-viewport cards that repeat the same "ready", "healthy", "no action", or "blocked" message.
- Separate action panels that compete with the primary action without new decision context.