coulomb/feature-control
2
0
Fork 0
generated from coulomb/repo-seed
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
feature-control/docs/canon-mapping.md
tegwick 571e2f7127 feat(bootstrap): finish FEATURE-WP-0001 State Hub integration workstream 
- T01 (Review Generated Integration Files): Reviewed INTENT.md, SCOPE.md, AGENTS.md, .custodian-brief.md. Refined SCOPE.md (removed generic generated placeholder, added repo-specific In/Out Scope, Current State noting completion of WP-0001 and WP-0002, canon alignment). Refined README.md with links to canon-mapping and workplans. Confirmed INTENT and AGENTS already specific.
- T02 (Verify Local Developer Workflow): Confirmed pure-docs repo (no build/test files). Added 'Local Developer Workflow' section to AGENTS.md documenting verification commands (cat/ls for review, hub curls, make fix-consistency from state-hub, progress POSTs) and extension guidance.
- Updated FEATURE-WP-0001 workplan: T01/T02 marked done with detailed notes; frontmatter status set to finished.
- Includes completion of FEATURE-WP-0002 (canon alignment for PRD/UCC, docs/canon-mapping.md + interface card stub, terminology updates with EvaluationScope and ITC mappings).
- Ran make fix-consistency REPO=feature-control after changes (synced hub, set workstreams to finished).

All per AGENTS.md session protocol, workplan instructions, and custodian brief.

Bootstrap workstream now 3/3 complete; no active workstreams remaining.
2026-06-14 21:24:46 +02:00

139 lines
15 KiB
Markdown
Raw Permalink Blame History

# 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.
Reference in New Issue View Git Blame Copy Permalink