shard-wiki/spec/adr/ADR-0001-engine-activation-via-feature-control.md

ADR-0001 — Engine extension activation via feature-control (OpenFeature)

Status: Accepted · Date: 2026-06-15 · Deciders: tegwick · Source: SHARD-WP-0013 follow-up (feature-control assessment)

First repo-level ADR. (Note: FederationRequirements.md contains document-internal "ADR-01…06" design notes — those are scoped to that spec; this spec/adr/ series is the repository's standalone architecture decision log, starting here.)

Context

WikiEngineCoreArchitecture.md (SHARD-WP-0013 T5) defines the engine as a small kernel plus a typed-extension framework where each shard activates only the extensions it needs (invariants E-4 activation, E-8 reuse-not-reinvent). It needs a mechanism to decide, per shard (and per tenant/context), which extensions/features are active — without baking a bespoke flag system into the engine, and without breaking the standalone, zero-external-dependency L0 posture shard-wiki guarantees.

The helix_forge sibling feature-control (capability.feature-control.evaluate, registered at D5 / A4 / C3 / R3) provides exactly this: an OpenFeature-based feature-availability control plane with a working SDK (feature_control_sdk: FeatureControlClient, Resolver, a static LocalProvider), context-scoped evaluation (tenant_id/scope), explainable decisions, and graceful degradation when OpenFeature is absent. shard-wiki already proposed this as a T3 consumption (reuse, don't rebuild).

Decision

Adopt feature-control (via the OpenFeature standard) as the engine's per-shard extension/ feature activation mechanism — availability only — with these constraints:

1. OpenFeature-shaped, provider-pluggable. The engine evaluates activation through an OpenFeature-style client. A static LocalProvider is the standalone/L0 default (zero external dependency); a feature-control/remote provider is plugged in for governed deployments. This mirrors shard-wiki's existing identity-provider ladder (null/local default → external when present).
2. Availability ≠ authorization. feature-control decides which extensions are active, never who may read/write. Authorization stays in core (X-AUTHZ / authorization.policy- evaluate). The two are composed but never conflated. (feature-control's own INTENT requires this.)
3. Engine layer, not the orchestrator foundation. Integration lives in engine/activation.py; the current src/shard_wiki/ core stays dependency-free. OpenFeature/ feature-control is an optional extra, kept out of the standalone path by the LocalProvider.
4. Thin slice only. Consume feature-control.evaluate (mature, A4). Do not take a dependency on the heavier control-plane governance / rollout / visibility (A2) until a concrete need appears.

Activation keys = extension ids; evaluation context = {tenant_id: root-entity, shard_id, …}; the resulting active-extension set then derives the shard's §A capability profile (E-5).

Consequences

Positive

• No bespoke flag system; reuses a mature (D5/A4) capability — reuse-surface aligned.
• Standalone stays zero-dep (LocalProvider); governed deployments get real runtime control, multi-tenant scoping, and explainable decisions that feed the engine's agent-introspection API (E-7: "why is extension X off for this shard?").
• "Activate only what you need" + compute control become first-class and reversible at runtime.
• Clean layering: availability (feature-control) vs authorization (core) vs identity (provider).

Negative / risks (mitigated by the constraints)

• An optional OpenFeature dependency at the engine layer (mitigated: out of the standalone path).
• Coupling to an external control plane in governed mode (mitigated: provider-pluggable, degrade to LocalProvider).
• Temptation to route authz through it (mitigated: constraint 2, hard boundary).

Alternatives considered

• Bespoke per-shard flag/config in the engine — rejected: reinvents feature-control, no standard, no multi-tenant/explainability, violates reuse-not-reinvent (E-8).
• No activation (all extensions always on) — rejected: defeats "small core + activate only what you need" (E-2/E-4) and the compute-control goal.
• Build on the heavier feature-control control-plane now — deferred: over-scoping a single engine's activation; revisit if rollout/governance needs emerge.

Related

WikiEngineCoreArchitecture.md (E-4/E-8, §4 activation), UseCaseCatalog.md capability-structure layer (X-AUTHZ vs activation), history/260615-reuse-surface-contributions.md (T3 consumption), reuse-surface capability.feature-control.evaluate, INTENT amendment decision 84ffdb48.