config-atlas/docs/canon-mapping.md

Canon Mapping

Status: draft Updated: 2026-06-26 Repo: config-atlas Related: ../INTENT.md, ../specs/ProductRequirementsDocument.md (PRD §5), ../specs/ArchitectureBlueprint.md, ecosystem-boundaries.md §2.3, 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).

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.