feature-control/docs/canon-mapping.md

Canon Mapping

Status: draft
Updated: 2026-06-14
Repo: feature-control
Related: INTENT.md, specs/ProductRequirementsDocument.md (PRD), specs/UseCaseCatalog.md (UCC), docs/feature-management-model.md (TBD per T02)

This document maps current feature-control concepts (from INTENT, PRD, and UCC) to identity-canon and InfoTechCanon concepts. It is intentionally explicit about owned facts, consumed facts, references, proposed extensions, and gaps. It follows the pattern established in user-engine/docs/canon-mapping.md and aligns with canon review-kit expectations (interface cards, consumer briefs, alignment reviews).

Mapping Stance

feature-control exists to provide a shared, low-impact, cross-repository infrastructure for feature availability control in multi-vendor, multi-tenant, multi-domain software landscapes.

It treats feature flagging as one mechanism inside a broader feature availability control plane. Primary manifestation in consuming repositories is OpenFeature (SDKs + thin organization wrappers + generated constants + local/test providers). Repositories must not bind directly to a concrete backend.

feature-control consumes InfoTechCanon for organizational structure, access semantics, landscape resources, governance decisions/evidence, and tagging. It extends the canon (via proposed concepts) where feature availability, multi-source decision composition, rich availability states, evaluation scoping, lifecycle hygiene for flags, and compute/agent capability control require additional precision.

It must not:

• Replace central authorization (ITC-ACCESS + Governance).
• Own the source-of-truth for commercial entitlements (ITC-ACCESS.Entitlement / Grant).
• Collapse availability, entitlement, authorization, and UI visibility.

"Scope" (unqualified) in current feature docs is a terminology clash with canon's producer-scope / scope-pressure usage (see ITC-GOV purpose-demand extension and Core). We qualify it going forward (see below).

Entity Mapping

feature-control concept	Canon concept	Ownership	Notes
Feature (named capability, behavior, UI element, workflow path, compute path, or config-controlled slice)	ProducerCapability (Governance ext) + Feature (extension candidate)	owned (feature-control) + extension proposed to canon	See repo-scoping "Scope → Ability → Capability → Feature → Evidence → Observed Fact" chain and purpose-demand ProducerCapability. feature-control owns availability control, registry, and OpenFeature surface.
FeatureKey	Stable identifier (no direct single owner; relates to Landscape resource + Tagging)	owned (feature-control)	Immutable once used; namespaced <domain>.<capability>.<feature>[.<mode>].
FeatureAvailability / availability states (enabled, disabled, hidden, visible_disabled, readonly, degraded, variant, configured, unavailable, fallback)	(derived state from Decision + Control)	owned (feature-control overlay)	Richer than boolean. Composed from multiple signals. Maps to OpenFeature value + reason + variant + flagMetadata.
FeatureDecision (value, state, reason, source, scope, fallback, variant, config, evaluated_at, metadata)	Governance Decision + Evidence + OpenFeature FlagEvaluationDetails (reason, variant, flagMetadata)	owned overlay (feature-control) on consumed ITC-GOV + OF	Precedence (kill_switch > ... > default) is feature-control policy. Must be explainable.
EvaluationContext (targetingKey + installation_id, environment, tenant_id, domain_id, organization_id, user_id, agent_id, actor_type, roles, plan, region, service, repository, etc.)	OpenFeature EvaluationContext (targetingKey + custom fields) composed from ITC-LAND (Environment, Deployment, Service, Repository, RuntimeResource) + ITC-ORG (Actor, Agent, Membership, Tenant patterns) + ITC-ACCESS facts	consumed structure (OF) + projection/reference (canon models)	Strict merge precedence per OF spec. targetingKey is principal/subject projection. Minimize sensitive attributes and high cardinality. "domain" (OF) is client/provider binding — distinct from business domain_id.
EvaluationScope / TargetingScope / FeatureRuleScope (proposed) (platform, installation, environment, deployment, vendor, tenant, domain, organization, group, user, agent, service/repository)	Membership (scope_type + scope_id) + Assignment + ITC-LAND / ITC-ORG dimensions (Tenant in profiles, OrganizationalUnit, Environment/Deployment/Service/Repository, Group/Team)	reference + extension candidate (EvaluationScope)	Replaces unqualified "Scope" / "scope_type" / "scope_id" to avoid clash with canon producer scope / ScopePressure. Tenant patterns from small-saas profile (deployment separates tenants + tenant-isolation policy).
Entitlement	Entitlement + Grant (ITC-ACCESS)	consumed / reference	Commercial/contractual/administrative grant. feature-control composes (e.g. disabled_by_entitlement) but does not own or replace source-of-truth.
Authorization / authorization_denied	AuthorizationDecision / Principal / EnforcementPoint (ITC-ACCESS)	consumed / reference	feature-control may emit signals but must never be trusted as final security enforcement (client-side or otherwise).
Visibility (hidden, visible_disabled, visible preview, readonly, admin-only...)	(no strong direct owner yet; presentation / UI concern)	owned (feature-control for feature-derived visibility) / future reference to Landscape or Data	Must remain distinct from availability and from AuthorizationDecision. Backend enforcement independent of UI state.
Agent (non-human actor)	Agent (ITC-ORG)	consumed / reference	First-class evaluation subject. Agent capability features require both feature availability + separate tool authorization (Access).
Kill Switch	Control + AccessExceptionReference (ITC-GOV + ITC-ACCESS)	reference + owned operational pattern (feature-control)	Highest practical precedence after security/compliance hard deny. Auditable, reversible, fast propagation for availability.
Remote Config / Variant / rollout treatment	OpenFeature structure value + variant in resolution details	consumed (OF) + owned governance/validation (feature-control)	Typed values with schemas. Unknown falls back safely.
Segment / Group (beta-testers, etc.)	Group / Team (ITC-ORG) or Tagging selector (with tenant boundaries)	reference	Reusable; membership source documented; respects tenant/environment.
FeatureRule / FeatureOverride	Policy / Rule / Control + binding (ITC-GOV)	reference + owned (feature-control)	Scoped application via EvaluationScope/Membership.
FeatureLifecycleRecord / states (proposed, registered, implemented, internal, preview, beta, general-availability, deprecated, sunset, removed) + categories (release, experiment, operational, entitlement, compute_control, agent_capability...)	Task (ITC-TASK) for reviews/expiry/cleanup + Governance states/approvals + TaggingStandard for categories	reference	Temporary flags require review/expiry date (spawns Task). Long-lived require explicit justified category + owner (ORG Ownership). Removed flags must be purged from code + control plane.
Owner / owning repo/service/domain	Ownership / Stewardship / Actor (ITC-ORG)	reference	Mandatory for registration.
AuditEvent	Evidence / Audit (ITC-GOV)	reference (local + export)	Append-only / tamper-evident for production-impacting changes.
Approval (for sensitive changes)	Approval / Review (ITC-GOV)	reference	Policy-driven; emergency path audited + reconciled.

Relationship Mapping

Relationship	Source	Target	Implementation source / notes
controls_availability_of	Feature / FeatureRule	ProducerCapability / Landscape resource (Service, Endpoint, etc.)	feature-control registry + resolver
evaluated_in	FeatureDecision	EvaluationContext (projected canon facts)	OpenFeature client + feature-control resolver
scoped_via	FeatureRule / Override	EvaluationScope (Membership + Landscape/Org dimension)	tenant_id etc. become scoped Membership or Assignment facts
composes_from	FeatureDecision	Entitlement (ITC-ACCESS), Governance Decision/Control, AuthorizationDecision	Multi-source precedence (kill > entitlement > policy > default)
owned_by	Feature	Actor / Team / OrganizationalUnit (ITC-ORG)	Required metadata
categorized_by	Feature	Tag (ITC-TaggingStandard)	release / compute_control / agent_capability etc.
generates_task_for	Temporary Feature / stale flag	Task (ITC-TASK)	review, expiry, cleanup, removal
emits_evidence_for	Feature change / decision	Evidence (ITC-GOV)	audit + explanation
informs_but_does_not_replace	FeatureAvailability / Decision	AuthorizationDecision (ITC-ACCESS)	explicit boundary
projects_to	Canon facts (Actor/Agent, Tenant, Environment, Service, Entitlement, Grant)	OpenFeature EvaluationContext + targetingKey	identity_context / landscape / access projection pattern (see user-engine)

Read Model / Projection Surface (for resolvers, SDK wrappers, explanations, scanners)

A canon-aligned feature evaluation / explanation surface should expose (without leaking cross-tenant data):

• Normalized Actor / Agent (from ITC-ORG, projected from IAM or agent identity).
• Memberships and scoped Assignments (tenant, organization, group, team).
• Landscape facts in context (Environment, Deployment, Service, Repository, Installation).
• Entitlement / Grant references (ITC-ACCESS).
• Effective FeatureDecision with reason taxonomy, source (rule/override/kill/etc.), variant, config, and provenance links to Governance Decision / Evidence where applicable.
• OpenFeature EvaluationDetails (value + reason + variant + flagMetadata) as the repo-visible contract.
• Gaps explicitly called out (e.g., "no matching entitlement record").

Local/test providers and generated constants must be usable without live canon or control-plane data.

Current Gaps (feature-control side)

• Natural Person not modeled (consistent with user-engine). Agent vs human must remain distinct in context and rules.
• Strong/weak identity linking and synonymity assertions are external (identity-canon).
• Full Organization / Vendor / Legal Entity / Customer modeling is referenced via tenant + external identifiers (small-saas profile uses tenant separation).
• Presentation/Visibility semantics have no deep canon owner yet (future Landscape/Data or profile concern). feature-control owns the feature-derived portion only.
• Scope (bare) term clash in prior feature docs vs canon producer-scope / ScopePressure. Mitigated by introducing EvaluationScope / TargetingScope.
• No native first-class Feature / FeatureAvailability / FeatureDecisionRecord / EvaluationScope in current canon seed (these are the primary extension candidates feature-control will propose).
• Multi-signal composition logic (entitlement + kill switch + policy + experiment + compute cost) and rich availability state machine are feature-control owned (not generalized in canon yet).
• Cross-tenant leakage prevention in explanations, metrics, and context must be explicit (enforced in resolver + API layers).

Validation Hooks / Checks (to be implemented in tests + scanners + CI)

• Feature registration requires owner (ORG Ownership reference) and category (Tagging).
• Temporary features carry review/expiry date that spawns or links to a Task.
• FeatureDecision always distinguishes entitlement_missing from disabled_by_flag / kill_switch etc.
• Agent contexts use distinct actor_type: agent + Agent reference (never conflated with human User).
• No unqualified "Scope" / "scope_type" remains in canon-facing text, schemas, or examples (use EvaluationScope or explicit Membership dimension).
• EvaluationContext projection never includes raw PII or high-cardinality fields by default; explanations respect tenant boundaries.
• OpenFeature evaluation contract honored: always returns default on error path; never throws from hot evaluation; detailed results include reason/variant/flagMetadata.
• Backend provider can be swapped (via OF) without changing repo integration or feature keys.
• Stale / permanently-on flags are reported and linked to Task remediation.
• References to canon concepts include short owner IDs (e.g. "ITC-ACCESS.Entitlement", "ITC-LAND.Environment", "ITC-GOV.Decision").

These checks can live in feature-control tests + repo scanner + future canon interface card conformance.

Extension Candidates (for assimilation back into InfoTechCanon)

Record these for feedback to canon owners (via State Hub messages, ITC workplans such as ITC-WP-0006 purpose-demand, ITC-WP-0011 review kit, or caring standards):

• Feature (as typed ProducerCapability specialization with availability lifecycle).
• FeatureAvailability / availability state machine.
• FeatureDecision / FeatureDecisionRecord (specialized Governance Decision with feature reason taxonomy and source precedence).
• EvaluationScope / TargetingScope (to resolve Scope term clash while supporting Membership + Landscape dimensions).
• CapabilityControl or FeatureControl pattern (cross-cutting concern for compute, agent, and operational governance of capabilities).
• KillSwitchControl (privileged high-precedence Governance Control subtype with propagation and safe-degradation semantics).
• Stronger support in Information Space / profiles for feature registry artifacts, GitOps baselines, and drift detection.

These preserve orthogonality: canon owns general concepts and machinery; feature-control owns the availability control plane, OpenFeature integration, resolver composition, and registry.

Related Canon Artifacts (for ongoing reference)

• kernel/itc-core, itc-kernel-map
• models/organization/InfoTechCanonOrganizationModel.md
• models/access-control/InfoTechCanonAccessControlModel.md
• models/governance/InfoTechCanonGovernanceModel.md + InfoTechCanonPurposeDemandExtension.md
• models/landscape/InfoTechCanonLandscapeModel.md
• standards/tagging/InfoTechCanonTaggingStandard.md
• models/task/InfoTechCanonTaskModel.md (future)
• infospace/evaluations/repo-scoping/comparison-report.md (Capability → Feature chain)
• infospace/reports/small-saas-profile-proof.md (tenant patterns)
• user-engine/docs/canon-mapping.md + tests/test_identity_canon_alignment.py (reference alignment style)
• canon review-kit (agent/briefs, interface-card.schema.yaml, alignment-review.schema.yaml)

Next Steps (tied to FEATURE-WP-0002)

• T01/T04: This mapping is the primary deliverable. Cross-check against railiance-fabric canon-alignment-review.md style if a formal review packet is created later.
• T05/T06: Revise PRD and UCC to reference this document heavily, replace unqualified Scope language, update conceptual models/entities/FRs/UCs with canon IDs and boundaries, add "Canon Alignment" section near the top.
• T08: Use the Extension Candidates section above as the proposal artifact.
• T09: Add references from INTENT/PRD/UCC; create short feature-management-model.md (T02) that shows OF surface → resolver/composition (feature-control) → canon facts.
• After edits: update this mapping (Status, Updated), run make fix-consistency REPO=feature-control from state-hub, and request canon owner feedback.

This mapping + the revised PRD/UCC will ensure feature-control matches well with canon terminology and provides a deeper, interoperable understanding of feature management.