# Configuration Surface Schema

**Status:** draft
**Updated:** 2026-06-26
**Repo:** config-atlas
**Schema:** [`../schemas/surface-entry.schema.json`](../schemas/surface-entry.schema.json)
**Related:** [`canon-mapping.md`](canon-mapping.md), [`../specs/ProductRequirementsDocument.md`](../specs/ProductRequirementsDocument.md) §7/§10,
[`../specs/ArchitectureBlueprint.md`](../specs/ArchitectureBlueprint.md) §3

A **configuration surface** is a bounded, named place where configuration is
defined, read, or overridden. Each surface is one markdown file in
`registry/surfaces/` whose **YAML frontmatter** validates against
`schemas/surface-entry.schema.json`; the markdown body holds prose (meaning,
precedence notes, gotchas).

The atlas stores the **map**: where a surface lives, who owns it, its kind, scope,
and source links. It **never** stores live configuration values and **never** stores
secret values (PRD NFR-2, NFR-4). `additionalProperties: false` throughout the schema
prevents an entry from sneaking a `value` field anywhere.

## Fields

| Field | Required | Meaning |
|-------|----------|---------|
| `id` | yes | Stable id `surface.<domain>.<system>.<name>` (lowercase, dashes). |
| `name` | yes | Human-readable name. |
| `kind` | yes | Closed taxonomy (below). Drives kind-separation. |
| `summary` | yes | One-line description. |
| `owner` | yes | Team/agent identity, resolved against `domain-tree`. Not a person. |
| `status` | yes | `draft` \| `active` \| `deprecated`. |
| `scope` | yes | `allowed_layers` (subset of the layer ordering) + `default_layer`. |
| `mutability` | yes | Delivery stage / blast radius (below). |
| `security_class` | yes | `operational` \| `sensitive` \| `secret-ref` \| `policy`. |
| `schema` | no | The **contract** (type/default/min/max/validator) — metadata, not a live value. |
| `sources` | yes | Canonical sources by reference, each with a layer `role`. Never inlines a value. |
| `relations` | no | `consumed_by`, `overrides`, `depends_on_secret` (refs only), `related_to`. |
| `evidence` | no | `last_seen`, `discovery_method`, `change_log_ref`. |

### `kind` taxonomy
`app-config`, `deploy-config`, `secret-ref`, `feature-flag`, `policy`,
`tenant-config`, `infra-state`, `runtime-override`. Secrets, flags, and infra-state
are never treated as ordinary config. A `feature-flag` surface links to a
`feature-control` key (via a `sources[].role: feature-control-key`) and contains no
evaluation logic. A `secret-ref` surface references a secret by id/path only.

### `mutability` classes
`build-time`, `deploy-time`, `startup-time`, `hot-reloadable`, `per-request`,
`emergency`. Prevents treating structural config like a harmless flag.

## Scope / layer ordering (L0–L9)

`allowed_layers` and `default_layer` draw from the **shared scope vocabulary** — an
ordering, not a new set of names (aligned to ITC-LAND/ITC-ORG and `feature-control`
`EvaluationScope`; see `canon-mapping.md`):

```text
L0 product-default   L5 installation
L1 company           L6 tenant
L2 platform          L7 group
L3 environment       L8 user / agent
L4 region            L9 emergency
```

"More specific wins" by default; higher layers may declare **non-overridable
guardrails**. A surface declares which layers may set it, e.g.
`allowed_layers: [company, environment, tenant]`.

## Merge rules (explicit — no hidden last-writer-wins)

```text
scalar     more specific layer replaces earlier value
object/map deep merge by key
array/list replace by default; keyed merge only if declared
null       not deletion unless tombstone semantics are defined
secret     never merged into normal config
policy     restrictive rule wins unless explicitly delegated
```

Resolution of the *effective value* is out of scope (delegated downstream). The
atlas renders only the **effective-config path** — the ordered override path with
owner and validating-schema references (PRD FR-5).

## Authoring

1. Copy the example below into `registry/surfaces/surface.<domain>.<system>.<name>.md`.
2. Fill frontmatter; link `sources[]` to canonical files (no values, no secrets).
3. Add the row to `registry/indexes/surfaces.yaml` (ATLAS-WP-0002-T03).
4. Validate (ATLAS-WP-0002-T06): frontmatter against the schema, plus
   `reuse-surface validate --root .` and `git diff --check`.

## Example

See [`../registry/surfaces/surface.infotech.state-hub.api-config.md`](../registry/surfaces/surface.infotech.state-hub.api-config.md)
— a real, validating entry for the State Hub API configuration surface.