@variantlab/core 0.1.4 → 0.1.6

package/docs/design/config-format.md

@@ -0,0 +1,442 @@
+# Config format (`experiments.json`)
+
+The canonical specification for the `experiments.json` file. Also published as a JSON Schema at [`experiments.schema.json`](../../experiments.schema.json) for IDE validation.
+
+## Table of contents
+
+- [File structure](#file-structure)
+- [Top-level fields](#top-level-fields)
+- [Experiment fields](#experiment-fields)
+- [Variant fields](#variant-fields)
+- [Targeting fields](#targeting-fields)
+- [Rollback fields](#rollback-fields)
+- [Validation rules](#validation-rules)
+- [Examples](#examples)
+- [Forward compatibility](#forward-compatibility)
+
+---
+
+## File structure
+
+```json
+{
+  "$schema": "https://variantlab.dev/schemas/experiments.schema.json",
+  "version": 1,
+  "signature": "base64url-hmac-optional",
+  "enabled": true,
+  "experiments": [
+    {
+      "id": "example",
+      "name": "Example experiment",
+      "variants": [
+        { "id": "a" },
+        { "id": "b" }
+      ],
+      "default": "a"
+    }
+  ]
+}
+```
+
+---
+
+## Top-level fields
+
+| Field | Type | Required | Description |
+|---|---|:-:|---|
+| `$schema` | string | No | JSON Schema reference for IDE support. Ignored by the engine. |
+| `version` | integer | Yes | Schema version. Must be `1`. The engine rejects unknown versions. |
+| `signature` | string | No | Base64url-encoded HMAC-SHA256 of the canonical form of `experiments`. Verified via Web Crypto API when an `hmacKey` is configured. |
+| `enabled` | boolean | No | Global kill switch. When `false`, all experiments return their default variant. Defaults to `true`. |
+| `experiments` | array | Yes | Array of experiment definitions. Max 1000 entries. |
+
+### Why `version`?
+
+The schema will evolve. We want forward-compatible configs that can upgrade in memory (minor) and be rejected cleanly (major). Currently version 1.
+
+### Why `signature`?
+
+Optional HMAC enables tamper detection on remote configs. See [`docs/features/hmac-signing.md`](../features/hmac-signing.md).
+
+### Why `enabled`?
+
+Kill switch for fast incident response. If a bad config ships, users can flip this flag in a new config and push to disable everything instantly without a code release.
+
+---
+
+## Experiment fields
+
+| Field | Type | Required | Default | Description |
+|---|---|:-:|---|---|
+| `id` | string | Yes | — | Unique identifier. `/^[a-z0-9][a-z0-9-]{0,63}$/` |
+| `name` | string | Yes | — | Human-readable. Max 128 chars. |
+| `description` | string | No | — | Shown in debug overlay. Max 512 chars. |
+| `type` | enum | No | `"render"` | `"render"` for component swaps, `"value"` for returned values. |
+| `variants` | array | Yes | — | At least 2, at most 100. |
+| `default` | string | Yes | — | Must match one of `variants[].id`. |
+| `routes` | array | No | — | Glob patterns. Max 100. |
+| `targeting` | object | No | — | Targeting predicate. |
+| `assignment` | enum | No | `"default"` | Strategy: `default | random | sticky-hash | weighted`. |
+| `split` | object | No | — | Traffic split for `weighted` strategy. |
+| `mutex` | string | No | — | Mutual exclusion group. |
+| `rollback` | object | No | — | Crash-rollback configuration. |
+| `status` | enum | No | `"active"` | `draft | active | archived`. |
+| `startDate` | ISO 8601 | No | — | Inactive before this. |
+| `endDate` | ISO 8601 | No | — | Inactive after this. |
+| `owner` | string | No | — | Free text. Max 128 chars. |
+| `overridable` | boolean | No | `false` | Whether deep link overrides are accepted. |
+
+### `id`
+
+Case-sensitive, lowercase. Allowed characters: `a-z`, `0-9`, `-`. Max 64 characters. Must not start with a hyphen. Examples:
+
+- `cta-copy` ✅
+- `news-card-layout` ✅
+- `checkout-v2` ✅
+- `CTA_copy` ❌ (uppercase + underscore)
+- `-leading-dash` ❌
+
+### `type`
+
+- `"render"`: designed for `<Variant>` component-swap usage. Variants don't need a `value`.
+- `"value"`: designed for `useVariantValue` usage. Each variant has a `value` field.
+
+Mixing is fine; you can use a `render`-type experiment with `useVariant` to read the variant ID as a string.
+
+### `default`
+
+Required. Must reference a valid variant ID. Used when:
+
+- Targeting fails
+- Kill switch is on
+- `startDate` is in the future or `endDate` is in the past
+- Engine is in fail-open mode and an error occurs
+- Deep link override is not allowed
+- Crash rollback has triggered
+
+### `routes`
+
+Glob patterns matching current route/pathname. Used both for targeting and for debug overlay filtering.
+
+Supported patterns:
+
+- Exact: `/`, `/about`
+- Wildcard segment: `/blog/*`
+- Wildcard deep: `/docs/**`
+- Parameter: `/user/:id`
+- Trailing-slash insensitive
+
+Routes are matched against `VariantContext.route` at evaluation time. Adapters auto-populate this from the router:
+
+- `@variantlab/react-native` — from Expo Router `usePathname` or React Navigation
+- `@variantlab/next` — from `useRouter().pathname` or `usePathname`
+- `@variantlab/remix` — from `useLocation().pathname`
+- etc.
+
+### `assignment`
+
+- `"default"` — always return the default variant. Useful for pre-launch experiments.
+- `"random"` — uniform random across variants, assigned once per user and cached.
+- `"sticky-hash"` — deterministic hash of `(userId, experimentId)` mapped to a variant. Stable across devices for the same `userId`.
+- `"weighted"` — traffic split via `split` field. Uses sticky-hash for determinism.
+
+### `split`
+
+Required when `assignment: "weighted"`. Object mapping variant IDs to integer percentages summing to 100.
+
+```json
+"split": {
+  "control": 50,
+  "treatment-a": 25,
+  "treatment-b": 25
+}
+```
+
+### `mutex`
+
+Mutual exclusion group. Experiments with the same `mutex` cannot co-run on the same user. When two mutex'd experiments both target a user, the engine picks one by stable hash and excludes the others.
+
+Use case: two competing card-layout experiments shouldn't both fire on the same session.
+
+### `rollback`
+
+See [rollback fields](#rollback-fields) below and [`docs/features/crash-rollback.md`](../features/crash-rollback.md).
+
+### `status`
+
+- `"draft"` — visible in debug overlay (with a draft badge), returns default in production
+- `"active"` — normal operation
+- `"archived"` — hidden from debug overlay, returns default
+
+### `startDate` / `endDate`
+
+ISO 8601 timestamps. Inclusive start, exclusive end. Useful for time-boxed rollouts.
+
+### `owner`
+
+Free-text field for tracking who owns the experiment. Not used by the engine. Shown in debug overlay.
+
+### `overridable`
+
+Whether deep links can override this experiment. Default `false` for safety. See [`docs/features/qr-sharing.md`](../features/qr-sharing.md).
+
+---
+
+## Variant fields
+
+| Field | Type | Required | Description |
+|---|---|:-:|---|
+| `id` | string | Yes | Unique within the experiment. Same regex as experiment ID. |
+| `label` | string | No | Human-readable. Shown in debug overlay. Max 128 chars. |
+| `description` | string | No | Shown in debug overlay. Max 512 chars. |
+| `value` | any | No | For `type: "value"` experiments, the value returned by `useVariantValue`. |
+
+### `value`
+
+Any JSON-serializable value. Strings, numbers, booleans, arrays, and objects are all supported. Type safety on the JS/TS side comes via codegen or explicit generic arguments.
+
+---
+
+## Targeting fields
+
+All fields optional. **All specified fields must match** for a user to be eligible. An empty `targeting` object matches all users.
+
+| Field | Type | Description |
+|---|---|---|
+| `platform` | `("ios" \| "android" \| "web" \| "node")[]` | Match if `context.platform` is in the list. |
+| `appVersion` | string | Semver range. Match if `context.appVersion` satisfies. |
+| `locale` | string[] | IETF language tags. Exact match or prefix match. |
+| `screenSize` | `("small" \| "medium" \| "large")[]` | Match `context.screenSize`. |
+| `routes` | string[] | Glob patterns. Match if `context.route` matches any. |
+| `userId` | string[] \| hash object | Explicit user list or hash bucket. |
+| `attributes` | object | Exact-match predicate on `context.attributes`. |
+
+### Screen-size buckets
+
+Adapter packages auto-derive the bucket from screen dimensions:
+
+- `small`: max(width, height) < 700 px
+- `medium`: 700 ≤ max(width, height) < 1200 px
+- `large`: max(width, height) ≥ 1200 px
+
+These thresholds are configurable at engine-creation time but have good defaults.
+
+### App version matching
+
+Supports standard semver range syntax:
+
+- `>=1.2.0`
+- `^1.2.0` (>= 1.2.0 < 2.0.0)
+- `~1.2.0` (>= 1.2.0 < 1.3.0)
+- `1.2.0 - 2.0.0` (range)
+- `>=1.0.0 <2.0.0 || >=3.0.0` (compound)
+
+Parsed by our hand-rolled semver matcher. See [`docs/research/bundle-size-analysis.md`](../research/bundle-size-analysis.md).
+
+### User ID matching
+
+Two modes:
+
+1. **Explicit list**: `"userId": ["alice", "bob", "charlie"]`
+2. **Hash bucket**: `"userId": { "hash": "sha256", "mod": 10 }` — match if `sha256(userId) % 100 < mod` (10% of users)
+
+### Attributes matching
+
+Exact-match predicates on arbitrary user attributes:
+
+```json
+"targeting": {
+  "attributes": {
+    "plan": "premium",
+    "region": "us-west",
+    "betaOptIn": true
+  }
+}
+```
+
+All specified attributes must match exactly. For complex predicates, use the `targeting.predicate` escape hatch available only in application code, not in JSON.
+
+---
+
+## Rollback fields
+
+| Field | Type | Required | Default | Description |
+|---|---|:-:|---|---|
+| `threshold` | integer | Yes | `3` | Crashes that trigger rollback. 1-100. |
+| `window` | integer | Yes | `60000` | Time window in ms. 1000-3600000. |
+| `persistent` | boolean | No | `false` | Persist rollback across sessions. |
+
+When enabled, if a variant crashes `threshold` times within `window` milliseconds, the engine:
+
+1. Clears the user's assignment for that experiment
+2. Forces the `default` variant
+3. Emits an `onRollback` event
+4. If `persistent`, stores the rollback in Storage
+
+See [`docs/features/crash-rollback.md`](../features/crash-rollback.md).
+
+---
+
+## Validation rules
+
+The engine validates configs at load time and rejects:
+
+- **Unknown version** (`version !== 1`)
+- **Config larger than 1 MB**
+- **Duplicate experiment IDs**
+- **Duplicate variant IDs within an experiment**
+- **`default` that doesn't match any variant**
+- **`split` sum != 100** when assignment is `weighted`
+- **Invalid route globs** (unsupported patterns)
+- **Invalid semver ranges**
+- **Targeting nesting deeper than 10 levels**
+- **Invalid ISO 8601 timestamps**
+- **Reserved keys** (`__proto__`, `constructor`, `prototype`)
+
+Errors are collected and thrown as a `ConfigValidationError` with an `issues` array.
+
+In fail-open mode (default), the engine logs the error and falls back to returning defaults. In fail-closed mode, it throws.
+
+---
+
+## Examples
+
+### Simple value experiment
+
+```json
+{
+  "version": 1,
+  "experiments": [
+    {
+      "id": "cta-copy",
+      "name": "CTA button copy",
+      "type": "value",
+      "default": "buy-now",
+      "variants": [
+        { "id": "buy-now", "value": "Buy now" },
+        { "id": "get-started", "value": "Get started" },
+        { "id": "try-free", "value": "Try it free" }
+      ]
+    }
+  ]
+}
+```
+
+### Render experiment with route scope
+
+```json
+{
+  "version": 1,
+  "experiments": [
+    {
+      "id": "news-card-layout",
+      "name": "News card layout",
+      "routes": ["/", "/feed"],
+      "targeting": { "screenSize": ["small"] },
+      "default": "responsive",
+      "variants": [
+        { "id": "responsive", "label": "Responsive image" },
+        { "id": "scale-to-fit", "label": "Scale to fit" },
+        { "id": "pip-thumbnail", "label": "PIP thumbnail" }
+      ]
+    }
+  ]
+}
+```
+
+### Weighted rollout with rollback
+
+```json
+{
+  "version": 1,
+  "experiments": [
+    {
+      "id": "new-checkout",
+      "name": "New checkout flow",
+      "assignment": "weighted",
+      "split": { "control": 90, "new": 10 },
+      "default": "control",
+      "variants": [
+        { "id": "control" },
+        { "id": "new" }
+      ],
+      "rollback": {
+        "threshold": 5,
+        "window": 120000,
+        "persistent": true
+      }
+    }
+  ]
+}
+```
+
+### Time-boxed experiment
+
+```json
+{
+  "version": 1,
+  "experiments": [
+    {
+      "id": "black-friday-banner",
+      "name": "Black Friday banner",
+      "type": "render",
+      "startDate": "2026-11-24T00:00:00Z",
+      "endDate": "2026-12-01T00:00:00Z",
+      "default": "hidden",
+      "variants": [
+        { "id": "hidden" },
+        { "id": "shown" }
+      ]
+    }
+  ]
+}
+```
+
+### Targeted beta
+
+```json
+{
+  "version": 1,
+  "experiments": [
+    {
+      "id": "ai-assistant",
+      "name": "AI assistant beta",
+      "targeting": {
+        "platform": ["ios", "android"],
+        "appVersion": ">=2.0.0",
+        "attributes": { "betaOptIn": true }
+      },
+      "default": "disabled",
+      "variants": [
+        { "id": "disabled" },
+        { "id": "enabled" }
+      ]
+    }
+  ]
+}
+```
+
+---
+
+## Forward compatibility
+
+### Minor version updates
+
+If we add new optional fields in a future release, old configs still work. The engine ignores unknown fields that are backward-compatible by design.
+
+### Major version updates
+
+A breaking change increments the `version` field. The engine refuses to load configs of a newer major version and logs a clear error pointing to the migration guide.
+
+### Migration strategy
+
+We ship a `variantlab migrate` CLI command to upgrade configs between major versions. Migration is always one-way (v1 → v2); we don't support downgrades.
+
+---
+
+## See also
+
+- [`experiments.schema.json`](../../experiments.schema.json) — machine-readable JSON Schema
+- [`API.md`](../../API.md) — TypeScript interfaces matching this format
+- [`docs/features/codegen.md`](../features/codegen.md) — how configs become types
+- [`docs/features/targeting.md`](../features/targeting.md) — targeting predicate semantics

package/docs/design/design-principles.md

@@ -0,0 +1,212 @@
+# Design principles
+
+The 8 principles that govern every design decision in variantlab. When we disagree about a change, we refer back to this document.
+
+## Table of contents
+
+1. [Framework-agnostic core, thin adapters](#1-framework-agnostic-core-thin-adapters)
+2. [Zero runtime dependencies](#2-zero-runtime-dependencies)
+3. [ESM-first, tree-shakeable, edge-compatible](#3-esm-first-tree-shakeable-edge-compatible)
+4. [Security by construction](#4-security-by-construction)
+5. [Declarative JSON as the contract](#5-declarative-json-as-the-contract)
+6. [SSR correct everywhere](#6-ssr-correct-everywhere)
+7. [Privacy by default](#7-privacy-by-default)
+8. [Docs-first development](#8-docs-first-development)
+
+---
+
+## 1. Framework-agnostic core, thin adapters
+
+**Principle**: The engine runs in any ECMAScript environment. Every framework binding is a thin wrapper.
+
+**Why**: Frameworks change. React's concurrent mode, Vue's composition API, Svelte's runes, Solid's signals — each framework has its own way of expressing reactivity. If we tie the engine to one of them, we're locked in.
+
+**Consequence**:
+- `@variantlab/core` never imports `react`, `vue`, `svelte`, `solid`, or any framework
+- The engine exposes a synchronous `subscribe(listener)` API and framework adapters bridge to their native reactivity
+- Each adapter is < 200 LOC
+- Adding a new framework costs us days, not months
+
+**Test**: Can we write the core in pure TypeScript with only the TypeScript standard library? Yes. Is there any framework-specific code in `@variantlab/core`? No.
+
+---
+
+## 2. Zero runtime dependencies
+
+**Principle**: `@variantlab/core` has zero runtime dependencies. Adapter packages have exactly one: `@variantlab/core`.
+
+**Why**: Every runtime dependency is a supply-chain attack vector, a potential version conflict, a source of bundle bloat, and a transitive trust decision. The `event-stream` incident (2018), the `ua-parser-js` hijack (2021), the `xz-utils` backdoor (2024) — every major supply chain attack starts with an innocuous dependency.
+
+**Consequence**:
+- We write our own schema validator (400 bytes vs zod's 12 KB)
+- We write our own semver matcher (250 bytes vs `semver`'s 6 KB)
+- We write our own route glob matcher (150 bytes vs `minimatch`'s 4 KB)
+- We write our own hash function (80 bytes vs `murmurhash`'s 500 bytes)
+- We use Web Crypto API for HMAC, not a polyfill
+- We reject every PR that adds a runtime dep without 2 maintainer approvals + discussion
+
+**Test**: Does `npm ls --prod` in `@variantlab/core` show zero entries? Yes. Enforced by CI.
+
+**Tradeoff**: We spend engineering time writing hand-rolled replacements for well-tested libraries. This is intentional. The cost is upfront; the benefit is compounding.
+
+---
+
+## 3. ESM-first, tree-shakeable, edge-compatible
+
+**Principle**: All packages ship ES modules with aggressive tree-shaking. Every package runs in every modern runtime — Node 18+, Deno, Bun, browsers, React Native Hermes, Cloudflare Workers, Vercel Edge, AWS Lambda@Edge.
+
+**Why**: CommonJS is dying. ESM is the future. Edge runtimes are the future. Any library that doesn't support all of these is a library that will need a rewrite in 3 years.
+
+**Consequence**:
+- `"type": "module"` in all package.json files
+- Dual ESM+CJS output only for maximum compatibility (CJS wrapped via tsup)
+- `"sideEffects": false` so bundlers tree-shake aggressively
+- Separate entry points per feature (`@variantlab/core`, `@variantlab/core/debug`, `@variantlab/core/crypto`)
+- No Node built-ins in core (no `fs`, no `path`, no `process`)
+- No browser built-ins in core (no `window`, no `document`, no `localStorage`)
+- Only Web APIs: `crypto.subtle`, `Date`, `Math`, `Map`, `Set`
+
+**Test**: Does `@variantlab/core` import from `node:*`? No. Does it reference `window`? No. Does it run in a Cloudflare Worker sandbox? Yes.
+
+---
+
+## 4. Security by construction
+
+**Principle**: Security is a property of the design, not a feature we add later.
+
+**Why**: Security features retrofitted onto a library are always worse than security features designed in. A library that assumes it will only see trusted input will have a CVE the first time it sees untrusted input.
+
+**Consequence**:
+- No `eval`, no `Function()`, no dynamic `import()` on config data
+- Prototype pollution blocked at the schema validator level via `Object.create(null)` and key allow-lists
+- Constant-time HMAC verification via Web Crypto
+- Hard limits on config size, nesting, and iteration counts
+- Fail-open by default (return defaults on errors) with a fail-closed opt-in
+- No global mutation (`window`, `globalThis`, module-level state)
+- Config frozen after load via `Object.freeze`
+- Zero-telemetry by default
+
+**Test**: Does a crafted config with `{"__proto__": {"admin": true}}` compromise any object? No. Does a 10 MB config crash the engine? No, it's rejected at 1 MB. Does timing-attack HMAC verification reveal bytes? No, we use `crypto.subtle.verify`.
+
+See [`SECURITY.md`](../../SECURITY.md) and [`docs/research/security-threats.md`](../research/security-threats.md).
+
+---
+
+## 5. Declarative JSON as the contract
+
+**Principle**: `experiments.json` is the single source of truth. The engine's behavior is fully determined by the config plus the runtime context.
+
+**Why**: JSON configs are:
+- Version-controllable — diffs are readable in PRs
+- Reviewable — a non-developer can read the config
+- Tool-able — linters, codegen, IDE schema completion all work
+- Portable — the same config works in every framework
+- Safe — no code execution, no hidden behavior
+
+**Consequence**:
+- The config has a published JSON Schema (`experiments.schema.json`) for IDE validation
+- The CLI provides `validate` to check configs in CI
+- The CLI provides `generate` to codegen TypeScript types from configs
+- Targeting predicates are data structures, not functions (except the escape hatch)
+- Custom predicates (`targeting.predicate`) can only be supplied in application code, never in the JSON itself
+- Configs are forward-compatible via a required `version` field; the engine refuses unknown versions
+
+**Test**: Can a product manager edit `experiments.json` without reading any code? Yes. Can a QA engineer verify the config's validity without running the app? Yes (`variantlab validate`).
+
+---
+
+## 6. SSR correct everywhere
+
+**Principle**: The engine is deterministic. Given the same config and context, it produces the same variant every time. This means no hydration mismatches, ever.
+
+**Why**: A/B testing tools that cause hydration mismatches are broken. They force users to either render a placeholder (causing layout shift) or to defer all variant selection to the client (losing the point of SSR).
+
+**Consequence**:
+- No `Math.random()` in hot paths (even for `random` assignment — we use a seeded RNG keyed by userId)
+- No `Date.now()` in hot paths (time-based targeting only at boundaries)
+- Stable iteration order over config (sort by ID at load time)
+- Cookie-based stickiness as the default hydration strategy
+- Server helpers (`getVariantSSR`, `createVariantLabServer`) that run on any runtime
+- Framework adapters handle the `<Provider initialVariants={...}>` hydration pattern
+
+**Test**: Does rendering the same page 100 times produce identical HTML for a given user? Yes. Does the Next.js App Router test suite report zero hydration mismatches? Yes.
+
+See [`docs/research/framework-ssr-quirks.md`](../research/framework-ssr-quirks.md).
+
+---
+
+## 7. Privacy by default
+
+**Principle**: variantlab collects zero data about users, developers, or their apps. Every network call is explicit and opt-in.
+
+**Why**: "Privacy opt-out" is a dark pattern. "Anonymous telemetry" is still data collection. GDPR and CCPA have real teeth. We believe a library should do exactly what the user asks and nothing more.
+
+**Consequence**:
+- No phone-home on import, initialization, or any event
+- No analytics, no error tracking, no usage stats, no "anonymous ID"
+- `Fetcher` is always user-provided — we ship a helper, not a default endpoint
+- `Telemetry` is always user-provided — we ship an interface, not an implementation
+- User IDs passed for sticky hashing are hashed client-side before any network call
+- Debug overlay state is stored locally — QR sharing generates the QR on-device
+- Every dependency is audited for phone-home behavior
+
+**Test**: Run variantlab in a sandbox with no network access. Does it still work? Yes (except for user-provided remote configs). Does it try to open any connections? No.
+
+**Promise to users**: If we ever add telemetry, it will be opt-in only, clearly documented, and the repo will be publicly forkable to a telemetry-free version under the same license.
+
+---
+
+## 8. Docs-first development
+
+**Principle**: Every public API is specified in markdown before any code is written.
+
+**Why**: Libraries that ship APIs first and documentation later almost always end up with inconsistencies, under-documented corners, and unclear intent. Libraries like TanStack Query, Zod, and tRPC all ship comprehensive docs *before* the corresponding code.
+
+**Consequence**:
+- `API.md` is authoritative — any PR that changes public APIs must update this file first
+- `ARCHITECTURE.md` describes the runtime data flow before we implement it
+- `SECURITY.md` describes the threat model before we design mitigations
+- Every feature has a `docs/features/<name>.md` spec before implementation starts
+- Every phase has a `docs/phases/phase-N-*.md` plan with exit criteria
+- We run a design review on each doc with at least 2 reviewers before locking it
+
+**Test**: Can a contributor read the docs and predict exactly what the code does? Yes. Does the test suite match the documented behavior? Yes.
+
+---
+
+## How these principles interact
+
+The principles sometimes conflict. When they do:
+
+- **Security always wins** over convenience
+- **Privacy always wins** over features
+- **Zero-dependency wins** over minor DX improvements
+- **SSR correctness wins** over bundle size
+- **Framework-agnostic core wins** over per-adapter ergonomics
+
+We document every tradeoff in the relevant feature spec.
+
+---
+
+## Anti-principles (what we refuse to be)
+
+1. **Not a SaaS.** We will never host a dashboard. We will ship reference self-host templates.
+2. **Not a data collector.** We will never send data we don't absolutely need.
+3. **Not a kitchen sink.** We will say no to features that don't earn their bundle-size cost.
+4. **Not a plugin platform.** We keep the core small and let users compose.
+5. **Not one-framework-only.** We refuse to optimize for any single framework at the expense of others.
+6. **Not a dashboard.** Configs are files. Tools edit files. Git diffs them. We stay out of the editing UI business.
+7. **Not closed-source.** Everything is MIT, everything is public, forever.
+
+---
+
+## Review cadence
+
+These principles are reviewed:
+
+- **On every major release** (1.0, 2.0, etc.)
+- **When we add a new framework adapter** (does the adapter respect principle 1?)
+- **When we add a runtime dependency** (does this violate principle 2?)
+- **When we add a feature that collects data** (does this violate principle 7?)
+
+Changes to principles require a public discussion and 2 maintainer approvals.