# Configuration Schema Contract

**Status:** Approved target-state baseline  
**First realization:** I0.

## Definition Schema

Every product setting is declared through metadata conceptually like:

```text
ConfigurationDefinition<T> {
  key
  schemaVersion
  title
  description
  valueSchema
  defaultValue?
  allowedScopes[]
  overrideStrategy
  mutable
  effectCategory
  sensitiveReferenceOnly
  securityCeiling?
  deprecation/migration?
}
```

## Value / Override Schema

```text
ConfigurationOverride<T> {
  definitionKey
  scopeType
  scopeId
  valueOrReference
  resourceRevision
  setBy
  setAt
}
```

Effective resolution returns:

```text
value
sourceScope/sourceId
provenanceChain[]
locked/ceiling reason?
material consequence?
```

## Override Strategies

Allowed semantics are explicit by definition: replace, merge-map, append-unique, deny-lower-override or custom resolver. Avoid accidental generic deep-merge behavior.

## Sensitive Values

If `sensitiveReferenceOnly`, schema accepts a `CredentialReference`/secret handle, never raw secret value in persisted config/API response.

## Effect Categories

At minimum:

```text
presentation-only
future-runs-only
replan/readiness-affecting
restart/reload-required
security/approval-sensitive
immutable-after-creation
```

Consumers use this to show consequences/invalidate dependent state.

## Versioning / Migration

Definition schema changes name/version and include migration/default compatibility when persisted overrides exist. Removed/deprecated keys are surfaced rather than silently ignored.

## UI Generation

Metadata can assist Settings forms, but generated form is not a substitute for page UX/spec. Descriptions, groups and locked reasons are human-readable; complex settings may use custom editor over same contract.

## Increment Realization

I0 builds registry/validation/resolution. New definitions are added per increment under same schema.

## Acceptance

Every effective setting is valid, explainable, scoped and traceable; a config-file typo cannot silently create a second behavior path.