# Data Model: Canonical Control Catalog Foundation

## Overview

The first slice introduces a product-seeded control catalog and a shared resolution contract. The catalog itself is not operator-managed persistence in v1; it is a bounded canonical registry consumed by existing governance domains.

## Entity: CanonicalControlDefinition

- **Purpose**: Represents one stable governance control objective independent of framework clauses, provider identifiers, or individual workload payloads.
- **Identity**:
  - `control_key` — stable canonical slug, unique across the catalog
- **Core fields**:
  - `name`
  - `domain_key`
  - `subdomain_key`
  - `control_class`
  - `summary`
  - `operator_description`
- **Semantics fields**:
  - `detectability_class`
  - `evaluation_strategy`
  - `evidence_archetypes[]`
  - `artifact_suitability`
  - `historical_status` — `active` or `retired`
- **Validation rules**:
  - `control_key` must be stable, lowercase, and provider-neutral.
  - `domain_key` and `subdomain_key` must point to canonical catalog taxonomy, not framework or provider namespaces.
  - Each control must declare at least one evidence archetype.
  - Each control must declare explicit suitability flags for baseline, drift, finding, exception, evidence, review, and report usage.

## Entity: MicrosoftSubjectBinding

- **Purpose**: Connects provider-owned Microsoft subjects, workloads, or signals to one canonical control without redefining the control.
- **Fields**:
  - `control_key`
  - `provider` — always `microsoft` in the first slice
  - `subject_family_key`
  - `workload`
  - `signal_keys[]`
  - `supported_contexts[]` — for example baseline, finding, evidence, exception, review, report
  - `primary` — whether this binding is the default control for the declared context
  - `notes`
- **Validation rules**:
  - Every binding must reference an existing `control_key`.
  - Provider-specific descriptors must not overwrite control-core terminology.
  - More than one binding may point to the same control.
  - Multiple controls may only claim the same binding context when the ambiguity is intentionally declared and handled.

## Entity: CanonicalControlResolutionResult

- **Purpose**: Shared response contract for downstream consumers.
- **Resolver matching rule**: provider, consumer context, and every supplied subject-family, workload, or signal discriminator combine conjunctively to narrow candidate bindings.
- **States**:
  - `resolved`
  - `unresolved`
  - `ambiguous`
- **Fields when resolved**:
  - `status` — always `resolved`
  - `control` — full `CanonicalControlDefinition` payload containing:
    - `control_key`
    - `name`
    - `domain_key`
    - `subdomain_key`
    - `control_class`
    - `summary`
    - `operator_description`
    - `detectability_class`
    - `evaluation_strategy`
    - `evidence_archetypes[]`
    - `artifact_suitability`
    - `historical_status`
- **Fields when unresolved**:
  - `reason_code` — stable failure vocabulary such as `missing_binding`, `unsupported_provider`, `unsupported_consumer_context`, or `insufficient_context`
  - `binding_context`
- **Fields when ambiguous**:
  - `reason_code` — stable failure vocabulary, including `ambiguous_binding`
  - `candidate_control_keys[]`
  - `binding_context`
- **Validation rules**:
  - `resolved` returns exactly one canonical control.
  - All supplied discriminator inputs must narrow resolution together; the resolver must not ignore a provided field to force a match.
  - `ambiguous` returns no guessed winner.
  - `unresolved` returns no local fallback label.

## Supporting Classifications

### DetectabilityClass

- `direct_technical`
- `indirect_technical`
- `workflow_attested`
- `external_evidence_only`

### EvaluationStrategy

- `state_evaluated`
- `signal_inferred`
- `workflow_confirmed`
- `externally_attested`

### EvidenceArchetype

- `configuration_snapshot`
- `execution_result`
- `policy_or_assignment_summary`
- `operator_attestation`
- `external_artifact_reference`

## Relationships

- One `CanonicalControlDefinition` has many `MicrosoftSubjectBinding` records.
- One `MicrosoftSubjectBinding` references exactly one canonical control.
- One governed subject or signal context may resolve to one control or to an explicit ambiguous set.
- Existing governance consumers remain the owners of their own records and read models; they do not become child entities of the canonical catalog.

## Lifecycle

### CanonicalControlDefinition lifecycle

- `active`: valid for new bindings and downstream use
- `retired`: historical references remain resolvable, but new adoption should stop unless explicitly allowed

### Resolution lifecycle

- `resolved`: downstream consumer may use canonical metadata directly
- `unresolved`: downstream consumer must surface or log explicit absence rather than invent local meaning
- `ambiguous`: downstream consumer must stop and preserve explicit ambiguity until the binding model is clarified

## Rollout Model

- The first slice keeps the catalog seeded in code and consumed through the resolver.
- Broad persistence of `canonical_control_key` on downstream entities is deferred.
- First-slice adoption is read-through and bounded to findings-derived evidence composition and tenant review composition.