feature-flag-conventions

name	feature-flag-conventions
description	The shared Cargo feature-flag naming and semantics contract across xberg-io Rust libraries — the same flag names mean the same thing everywhere (otel, mcp/mcp-http, mimalloc/jemalloc, acceleration). Load when adding, renaming, or reviewing a crate's [features], or reconciling a library's flags with the rest of the stack.

Feature-flag conventions

Shared concerns use the same flag name with the same semantics in every library. A consumer that learns otel or mcp once should get identical behavior across xberg, crawlberg, liter-llm, html-to-markdown, tree-sitter-language-pack, and their bindings. Repo-specific flags (e.g. crawlberg stealth, liter-llm etcd-watch) stay local — this contract governs only shared concerns.

Standard flags

Flag	Meaning	Default	Notes
(none) tracing	Structured tracing is always-on, never a feature.	—	tracing is a non-optional dependency. Do not gate span emission. Un-gate any legacy optional tracing feature.
otel	Opt-in OpenTelemetry / OTLP export layer, on top of always-on tracing.	off	Pulls tracing-opentelemetry + the opentelemetry* stack. This is the only observability feature. Reconcile any always-on OTLP deps behind it.
mcp	Embedded Model Context Protocol server (stdio transport).	off
mcp-http	MCP Streamable HTTP transport; implies mcp.	off	mcp-http = ["mcp", ...].
mimalloc	Select the mimalloc global allocator.	off	Mutually exclusive with jemalloc — guard with a compile_error! if both are set.
jemalloc	Select the jemalloc global allocator.	off	Mutually exclusive with mimalloc.
cuda / metal / mkl / accelerate	Device / BLAS acceleration backends where a crate exposes them.	off	Same names wherever acceleration is offered.

Rules

• Names are the contract. Never invent a synonym for a shared concern (opentelemetry, observability, otlp for what is otel; model-context-protocol for mcp). Rename divergent flags to match.
• Semantics travel with the name. otel must mean the OTLP export layer everywhere, not "enable tracing" (tracing is always-on) and not a metrics-only subset.
• Always-on tracing, opt-in export. Do not force the opentelemetry dependency tree on library consumers — keep it behind otel so a plain dependency stays lean.
• Implication edges are fixed: mcp-http ⇒ mcp; otel ⇒ (always-on) tracing.
• Mutually-exclusive allocators always carry the both-enabled compile_error! guard.
• Adding a shared flag to a new library? Copy the name, default, and implication edges from this table rather than redefining them. Coordinate a change to this contract across all libraries before landing it — no repo diverges unilaterally.