feature-flag-conventions

# 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.