config-atlas/docs/canon-mapping.md

# Canon Mapping

**Status:** draft
**Updated:** 2026-06-26
**Repo:** config-atlas
**Related:** [`../INTENT.md`](../INTENT.md), [`../specs/ProductRequirementsDocument.md`](../specs/ProductRequirementsDocument.md) (PRD §5),
[`../specs/ArchitectureBlueprint.md`](../specs/ArchitectureBlueprint.md),
[`ecosystem-boundaries.md`](ecosystem-boundaries.md) §2.3,
[`configuration-surface-schema.md`](configuration-surface-schema.md) (ATLAS-WP-0002-T01)

This document maps `config-atlas` concepts to **InfoTechCanon** (ITC) and sibling
repos. It is explicit about owned facts, consumed facts, references, proposed
extensions, and gaps. It follows the pattern of
`~/feature-control/docs/canon-mapping.md` and resolves the `(planned)` references
in PRD §5 and `ecosystem-boundaries.md` §2.3.

## Mapping Stance

`config-atlas` is the **read-first, cross-kind configuration map and evidence
layer**. Its novel core is the **configuration surface** entry, the **L0–L9
layering order**, and the **effective-config *path*** rendering. Everything else is
referenced, not owned (see [`../.claude/rules/repo-boundary.md`](../.claude/rules/repo-boundary.md)).

`config-atlas` **consumes** ITC for governance (policy/decision/evidence), data
(schema/contract/classification), delivery (mutability), and landscape
(environment/deployment/service/repository). It **references** ITC-ORG ownership via
`domain-tree`, and **aligns** its scope vocabulary with `feature-control`'s
`EvaluationScope`. It **extends** the canon only where a configuration surface needs
precision the canon does not yet provide.

It **must not**:
- Become a runtime **resolver / delivery / control plane** (resolution is delegated).
- Own the **runtime control of feature availability** — that is `feature-control`
  (ITC-GOV `Control` + OpenFeature); config surfaces of kind `feature-flag` link out.
- Store **secret values** (ITC-ACCESS / OpenBao own values) — references only.
- Become a **second source of truth** for configuration values.
- **Redefine** the configuration vocabulary — it maps to ITC.

Terminology rule (per ITC "import concepts instead of redefining them"): the L0–L9
**layer** model is an *ordering over* the shared ITC-LAND / ITC-ORG /
`EvaluationScope` scope vocabulary, **not** a new set of scope names.

## Entity Mapping

| config-atlas concept | Canon concept | Ownership | Notes |
| --- | --- | --- | --- |
| `Configuration surface` (bounded named place where config is defined/read/overridden) | `ProducerCapability` (ITC-GOV purpose-demand ext) + Landscape resource (ITC-LAND); relates to repo-scoping `Scope→Ability→Capability→Feature→Evidence→Fact` | **owned** (extension candidate) | The first-class atlas entry. Maps the surface; does not own the underlying system. |
| `kind` (app-config, deploy-config, secret-ref, feature-flag, policy, tenant-config, infra-state, runtime-override) | classification (ITC-DATA) crossed with ITC-GOV (policy), ITC-LAND (infra/deploy), ITC-ACCESS (secret-ref) | **owned** (taxonomy) on consumed concepts | Drives kind-separation: secrets/flags/infra-state never treated as ordinary config. |
| `scope` / `layer` (L0–L9 over company, environment, region, installation, tenant, group, user, agent, …) | ITC-LAND dimensions (Environment, Deployment, Service, Repository) + ITC-ORG `Membership` (scope_type/scope_id) + `feature-control` `EvaluationScope` | **align + own ordering** | config-atlas owns only the *ordering and precedence*; the scope names are shared, not new. |
| `Effective configuration` | derived state from layered Sources + precedence (resolution **delegated**) | **own the *path***, not the resolved value | The `config explain` path: winning layer, overrides, validator, owner. |
| `Source` (repo/path/endpoint + layer `role`, no values) | ITC-LAND (Repository, Service, Environment, Deployment) + ITC-DEVSECOPS delivery artifacts | **reference** | Source-linked; never inlines a value. |
| `Merge semantics` (scalar/object/array/null/secret/policy rules) | ITC-GOV `Policy` precedence; restrictive-wins | **owned** | Explicit; no hidden last-writer-wins. |
| `mutability` class (build/deploy/startup/hot/per-request/emergency) | ITC-DEVSECOPS delivery stages | **reference** | Prevents treating structural config like a harmless flag. |
| `security_class` (operational/sensitive/secret-ref/policy) | ITC-DATA classification + ITC-SEC | **reference** | `secret-ref` never carries a value. |
| `Evidence` (last_seen, discovery_method, change_log_ref) | ITC-GOV `Evidence` / `Audit` | **reference** | Answers who/what/why/when and "is this still used?". |
| `Relationship` / edge (`consumed_by`, `overrides`, `depends_on_secret`, `related_to`) | ITC-GOV relations + State Hub graph; `consumed_by`→ITC-LAND Service; `depends_on_secret`→ITC-ACCESS (ref) | **own config semantics**, reference topology | config-atlas owns the config meaning of the edge; State Hub stores it. |
| `owner` | ITC-ORG `Ownership`/`Stewardship`/`Actor`, resolved via `domain-tree` bindings | **reference** | Mandatory; references identity, not a person. |
| `feature-flag` surface | `feature-control` key (ITC-GOV `Control` + OpenFeature) | **reference / link** | Never re-derives rules, resolver, or kill switches. |
| `secret-ref` surface | ITC-ACCESS secret + OpenBao | **reference only** | Records dependency/injection point, never the value. |

## Relationship Mapping

| Relationship | Source | Target | Notes |
| --- | --- | --- | --- |
| `consumed_by` | Configuration surface | Service / Repository (ITC-LAND) | Which systems read the surface. |
| `overrides` | Surface (higher specificity) | Surface (broader layer) | config-atlas owns; honors L0–L9 + guardrails. |
| `depends_on_secret` | Surface | Secret (ITC-ACCESS, OpenBao) | Reference only; never the value. |
| `owned_by` | Surface | Actor / Team (ITC-ORG via domain-tree) | Mandatory metadata. |
| `sourced_from` | Surface | Repository/Service/Environment (ITC-LAND) | Source-linked, layer `role` per source. |
| `emits_evidence_for` | Surface change | Evidence (ITC-GOV) | Audit + change-log reference. |
| `links_to_control` | `feature-flag` surface | feature-control key | Delegation boundary; no local resolution. |
| `classified_by` | Surface | Tag (ITC-TAG) | `kind`/category tagging. |

## Read model / projection surface

A canon-aligned atlas read surface should expose (without leaking values or
secrets): the normalized owner (ITC-ORG via domain-tree); the surface `kind` and
allowed `scope`/layers; source links with layer `role`; the effective-config
**path** (winning layer, overrides, validating schema, owner) — *not* the resolved
value; relationship edges (consumed_by, overrides, depends_on_secret); and
evidence (last_seen, change_log_ref). Entries must remain parseable by agents
without live hub or resolver data (PRD NFR-1, NFR-3).

## Current gaps (config-atlas side)

- No first-class `Configuration surface` / `EffectiveConfigPath` / `MergeSemantics`
  in the current ITC seed — these are the primary **extension candidates**.
- The scope/layer ordering (L0–L9) has no canon owner yet; aligned to ITC-LAND/ORG
  and `EvaluationScope` but the *precedence/guardrail* semantics are config-atlas owned.
- `domain-tree` ownership-binding resolution is referenced but not yet wired
  (ATLAS-WP-0002-T03/T06).
- Effective-config *value* resolution is intentionally **out of scope** (delegated);
  only the path is modeled.
- "AI/agent configuration" as a named scope class is an open question (PRD §14 Q5).

## Validation hooks / checks (for the schema + CI, ATLAS-WP-0002-T01/T06)

- Entry requires `owner` (ITC-ORG reference) and `kind` (closed taxonomy).
- Schema **forbids** literal configuration values and secret values (NFR-2, NFR-4).
- Layer names must come from the shared scope vocabulary — no new scope names.
- `feature-flag` surfaces must carry a `sources[]` link to a feature-control key and
  contain no evaluation logic.
- `secret-ref` surfaces reference a secret by id only; never a value.
- References to canon concepts use short owner IDs (e.g. `ITC-GOV.Evidence`,
  `ITC-LAND.Environment`, `ITC-DATA.Classification`).

## Extension candidates (for assimilation back into InfoTechCanon)

Record for feedback to canon owners (via State Hub messages / ITC workplans):

- `ConfigurationSurface` (typed ProducerCapability/Landscape-resource specialization
  with kind, scope, source links, and evidence).
- `EffectiveConfigPath` (an explainable override path; specialized Governance
  Decision/Evidence projection without a resolved value).
- `LayeringOrder` / `MergeSemantics` (precedence + merge-rule vocabulary, with
  non-overridable guardrails).
- `ConfigurationKind` taxonomy (data/governance/landscape/access crossing).

These preserve orthogonality: canon owns general concepts; config-atlas owns the
cross-kind map, layering order, and effective-config path.

## Related canon artifacts

- `infospace/kernel/InfoTechCanonCore.md` (itc-core), `itc-kernel-map`
- `infospace/models/governance/InfoTechCanonGovernanceModel.md` (itc-gov)
- `infospace/models/data/InfoTechCanonDataModel.md` (itc-data)
- `infospace/models/devsecops/InfoTechCanonDevSecOpsModel.md` (itc-devsecops)
- `infospace/models/landscape/InfoTechCanonLandscapeModel.md` (itc-land)
- `infospace/models/organization/InfoTechCanonOrganizationModel.md` (itc-org)
- `infospace/models/access-control/InfoTechCanonAccessControlModel.md` (itc-access)
- `infospace/models/security/InfoTechCanonSecurityModel.md` (itc-sec)
- `infospace/standards/tagging/InfoTechCanonTaggingStandard.md` (itc-tag)
- `~/feature-control/docs/canon-mapping.md` (alignment style + `EvaluationScope`)

## Next steps (tied to ATLAS-WP-0002)

- T01: encode the validation hooks above in `schemas/surface-entry.schema.json` and
  `docs/configuration-surface-schema.md`.
- T03/T06: wire `owner` resolution to `domain-tree`; enforce checks in CI.
- Assimilation: submit the Extension Candidates to ITC owners; update this mapping
  (Status, Updated) and run `make fix-consistency REPO=config-atlas`.
</content>