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 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 (InfoTechCanon itc-ident).
• 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.

Federation reference update — 2026-09-06

The identity model owns Scope and Synonymity Assertion; organization/access definitions retain their respective upstream owners. The evidence model owns Evidence and Evidence Source. CommerceCanon owns commercial concepts. This updates owner references under CFED-WP-0001-T09; it does not certify a new consumer adoption or change feature-control behavior.